Merge branch 'merge-doc-with-source' into 'master'

[SDK][FIX] adding the tech.io doc in the sdk repo

See merge request codingame/game-engine!153

Author: Julien Poulton

playground/README.md

@@ -0,0 +1,5 @@
+# CodinGame SDK
+
+The CodinGame SDK is a Java project that allows you to write programming games for [CodinGame](https://www.codingame.com).
+
+This project is a [Tech.io](https://tech.io) playground for the CodinGame SDK documentation.

playground/core-concepts/core-1-introduction.md

@@ -0,0 +1,15 @@
+# Core concepts
+
+This section will introduce the core concepts involved in creating games with the CodinGame Game Engine.
+
+## The Game Runner
+
+See how to **run your game locally** with the [Game Runner](core-2-game-runner.md).
+
+## The Game Manager
+
+See how to **manage players and the game flow** with the [Game Manager](core-3-game-manager.md).
+
+## Configure your game
+
+See how to setup your game [Configuration](core-4-configuration.md).

playground/core-concepts/core-2-game-runner.md

@@ -0,0 +1,119 @@
+# The Game Runner
+
+The Game Runner lets you run your game locally during developement. It comes with a handy HTML package to watch each game's replay. The parameters you set to the Game Runner will not affect the final contribution.
+
+You can create your own AI for your game and use the Game Runner to connect it to your game's implementation.
+
+You can also fiddle with your game's initialization input, such as the seed for random values (for **Multiplayer** games) or a [test case file](core-4-configuration.md#test-case-file) (for **Solo** games).
+
+# Usage
+
+Include the dependency below in the pom.xml of your project.
+```xml
+<dependency>
+  <groupId>com.codingame.gameengine</groupId>
+  <artifactId>runner</artifactId>
+  <version>2.13</version>
+</dependency>
+```
+Or a more recent version. See the [Release Notes](playground/misc/misc-3-release-notes.md).
+
+As the Game Runner is meant for testing, you must create a Class with a `main` method in `src/test/java`.
+
+Instantiate a `MultiplayerGameRunner` or a `SoloGameRunner` to launch a game with the `start()` method. This will create a temporary directory and start a server to serve the files of that directory. You don't need to stop the previous server to launch a new game.
+
+In addition, you will need to set **Agents** to the Game Runner. They are programs you must code to test your game, just as if they were players' code submissions.
+
+By default, you can access the game viewer for testing at [http://localhost:8888/test.html](http://localhost:8888/test.html). You may change the configuration of the game viewer by editing the `config.js` file. See the [Viewer configuration](core-4-configuration.md#viewer-configuration) for more details.
+
+Warning ⚠ To use the game viewer locally, your browser must support ES6 JavaScript **modules**. For Chrome, that's version 61 or above. For Firefox, from version 54 this feature is behind the `dom.moduleScripts.enabled` preference. To change preferences in Firefox, visit `about:config`.
+
+
+# Examples
+
+In order to run a game, you must have prepared a `Referee` and a `Player`. The game will surely fail to finish if they are not properly implemented. See [Game Manager](core-3-game-manager.md) for details.
+
+## Running a **Multiplayer** game
+
+### Using the same java class for each agent:
+```java
+MultiplayerGameRunner gameRunner = new MultiplayerGameRunner();
+gameRunner.addAgent(Agent.class);
+gameRunner.addAgent(Agent.class);
+gameRunner.start();
+    
+```
+⚠ _This method will prevent the agent from printing to stdout from any other class than Player._
+
+### Using external python programs as agents:
+```java
+MultiplayerGameRunner gameRunner = new MultiplayerGameRunner();
+
+gameRunner.addAgent("python3 /home/user/agent1.py");
+gameRunner.addAgent("python3 /home/user/agent2.py");
+gameRunner.addAgent("python3 /home/user/agent3.py");
+
+gameRunner.start();
+```
+
+### Using a custom seed:
+```java
+// I want to debug the strange case of this particuliar seed: 53295539
+MultiplayerGameRunner gameRunner = new MultiplayerGameRunner();
+gameRunner.setSeed(53295539L);
+gameRunner.addAgent(Agent1.class);
+gameRunner.addAgent(Agent2.class);
+gameRunner.start();
+```
+
+## Running a **Solo** game
+
+### Using a java class and a test case with its filename:
+```java
+SoloGameRunner gameRunner = new SoloGameRunner();
+gameRunner.setTestCase("test1.json"); // You must set a test case to run your game.
+gameRunner.setAgent(Solution.class);
+gameRunner.start();
+```
+
+# Viewing a replay
+
+Once a game is run, files are copied into a temporary folder. A server is started to serve those files on `localhost:8888`.
+
+The test page `/test.html` let's you watch the replay as it would appear on CodinGame.
+
+Many of the viewer's game-specific parameters may be changed by the default `config.js` file located in `src/main/resources/view` of your game's project. These parameters include: 
+* The list of modules needed by the game.
+* The colours for the different players (affects the IDE).
+
+See the [Viewer configuration](core-4-configuration.md#viewer-configuration) for more details.
+
+# Testing
+
+You can run your game without launching a server. This is useful to batch test your game in various conditions.
+
+Call the GameRunner's `simulate()` function to launch such a game, it will return a `GameResult` object containing information about the game's execution.
+
+```java
+// I want to make sure my randomly generated maps don't cause the game to crash
+for (int i = 0; i < 100; ++i) {
+  MultiplayerGameRunner gameRunner = new MultiplayerGameRunner();
+  gameRunner.setSeed((long) (i * 100));
+  gameRunner.addAgent(Agent1.class);
+  gameRunner.addAgent(Agent2.class);
+  GameResult result = gameRunner.simulate();
+}
+```
+
+An instance of `GameResult` exposes:
+  * `outputs` & `errors` the standard and error outputs of all agents and the referee.
+  * `summaries` the game summary as outputted by the GameManager.
+  * `scores` the scores assigned to each agent.
+  * `uinput` the game's input parameters (including the game's seed).
+  * `metadata` extra info generated by your referee. Useful for debugging and mandatory for Optimization games.
+  * `tooltips` the list of tooltips to be displayed on the replay's progress bar.
+  * `agents` a list of objects representing the agents. Contains their index, avatar and nickname.
+  * `views` the replay data, useful when creating a Module.
+
+
+

playground/core-concepts/core-3-game-manager.md

@@ -0,0 +1,205 @@
+# The Game Manager
+
+This document introduces the core code of the CodinGame's toolkit which includes the Game Manager and the viewer's replay engine.
+
+# Usage
+
+Include the dependency below in the pom.xml of your project.
+```xml
+<dependency>
+  <groupId>com.codingame.gameengine</groupId>
+  <artifactId>core</artifactId>
+  <version>2.4</version>
+</dependency>
+```
+Or a more recent version. See the [Release Notes](misc/misc-3-release-notes.md).
+
+
+## Basic Implementation
+
+Your project should include the class `Player` and the class `Referee`.
+Your `Referee` class may then inject (using Guice) a singleton of `SoloGameManager` or `MultiplayerGameManager` (corresponding to the type of game you want to create) parameterized by your `Player` class.
+Your `Player` class should extend `AbstractSoloPlayer` or `AbstractMultiplayerPlayer`.
+
+Example for a **Multiplayer** game:
+```java
+class Player extends AbstractMultiplayerPlayer {
+    @Override
+    public int getExpectedOutputLines() {
+        return 1;
+    }
+}
+
+public class Referee extends AbstractReferee {
+    @Inject private MultiplayerGameManager<Player> gameManager;
+    @Override
+    public void init() {
+    }
+
+    @Override
+    public void gameTurn(int turn) {
+    }
+
+    @Override
+    public void onEnd() {
+    }
+}
+```
+
+Example for a **Solo** game:
+```java
+class Player extends AbstractSoloPlayer {
+    @Override
+    public int getExpectedOutputLines() {
+        return 1;
+    }
+}
+
+public class Referee extends AbstractReferee {
+    @Inject private SoloGameManager<Player> gameManager;
+    @Override
+    public void init() {
+    }
+
+    @Override
+    public void gameTurn(int turn) {
+    }
+
+    @Override
+    public void onEnd() {
+    }
+}
+```
+
+The Game Manager's API will thus work with your `Player` class, which you may modify at leisure.
+
+# Features
+
+## General Features
+This section introduces the different features of the Game Manager for any type of game.
+
+For type-specific features, see:
+- [Multiplayer Game Features](#multiplayer-game-features)
+- [Solo Game Features](#solo-game-features)
+- [Optimization Game Features](#optimization-game-features)
+>Note that an Optimization game *is* a Solo game with more settings
+
+### Players
+
+You can get your `Player` instances from the Game Manager with `getPlayer` methods. They allow you to interact with the players' AIs.
+
+You can use the `getNicknameToken()` and `getAvatarToken()` methods to get tokens that will be converted into the real corresponding information by the viewer.
+
+To allow the AIs to play:
+- You must send input data to your players with `sendInputLine()`. 
+- Execute one turn of their code with `execute()`
+- Finally, get their output with `getOutputs()` and use them in your game.
+
+**Timeout**
+If a player times out (send an invalid value, takes too long to execute ...) you will be sent a `TimeoutException`. You can use this to end the game or deactivate the player, for example.
+
+### Maximum number of turns
+
+You can set the maximum number of turns before the game ends (even if there are still active players). If you don't set this paramter, the game will end within **400** turns.
+
+```java
+gameManager.setMaxTurns(200);
+```
+
+>This parameter is an important performance setting. See the [Guidelines](playground/misc/misc-1-guidelines.md) for more details.
+
+### Turn maximum time
+
+You can set the maximum time allowed to a Player to execute their code for a turn. If you don't set this paramter, the players will have **50**ms to execute.
+
+```java
+gameManager.setTurnMaxTime(45);
+```
+
+>This parameter is an important performance setting. See the [Guidelines](playground/misc/misc-1-guidelines.md) for more details.
+
+### Tooltips
+
+Tooltips will appear on the replay of the current game. They are usually short and describe when a player loses or timeout.
+
+```java
+gameManager.addTooltip(player, player.getNicknameToken() + " timeout!");
+```
+
+### Game Summary
+
+You can add texts that will be displayed to all players in the game summary, under the viewer.
+
+```java
+gameManager.addToGameSummary(String.format("%s pushed %s!", player1.getNicknameToken(), player2.getNicknameToken()));
+```
+
+### Frame duration
+
+You can modify the duration of a frame displayed in the viewer.
+
+```java
+gameManager.setFrameDuration(2000);
+```
+
+The duration is in milliseconds and the default one is 1000ms.
+
+You can also get this value with `gameManager.getFrameDuration();`.
+
+## Multiplayer Game Features <a name="multiplayer-game-features"></a>
+
+In a Multiplayer game, you will need to use the `MultiplayerGameManager` implementation parameterized with your `Player`.
+
+### Game parameters
+
+The Multiplayer Game Manager gives you access to **Game parameters**. These are used to vary your game and allow configuration in the CodinGame IDE Options. The game parameters is a `Properties` object you can get with `getGameParameters()`.
+
+By default, the game parameters contain a randomized `seed`.
+
+### Active Players
+
+All the players are active at the beginning of a battle. If they lose or timeout, you can choose to `deactivate()` them. They will no longer be in the list of players obtained with `getActivePlayers()`.
+
+### End Game
+
+You may want to end the game before the maximum number of turns is reached. You can use `endGame()` whenever one of the players meets the victory condition.
+
+## Solo Game Features <a name="solo-game-features"></a>
+
+In a Solo game, you will need to use the `SoloGameManager` implementation parameterized with your `Player`.
+
+### Test cases
+
+Your game will need at least one test case. See [Test case files](core-4-configuration.md#test-case-file) for more details on their creation.
+
+The Solo Game Manager provides you the test case input with `getTestCase()`.
+
+### End Game
+
+In Solo games, you do not compete against other players. Therefore, you will need to decide when a player *wins* or *loses*. To do that, you have two methods:
+```java
+gameManager.winGame();
+```
+and
+```java
+gameManager.loseGame();
+```
+
+## Optimization Game Features <a name="optimization-game-features"></a>
+
+An Optimization game is a Solo game with a score. The only differences comes in the [configuration](core-4-configuration.md#optimization-game-configuration) and the metadata you need to send.
+
+Once your game is correctly configured, you need to send your player's score. We advise you set it at the end of the game as below:
+```java
+@Override
+public void onEnd() {
+    // I set my criteria "Fuel" to what's left of the player's fuel
+    gameManager.putMetadata("Fuel", remainingFuel);
+}
+```
+
+### Score calculation
+
+Once the game is online, players will be able to submit their code and a score will be calculated to determine their rank in the leaderboard.
+
+This score corresponds to **the sum of all the scores obtained when running validators**. Validators are specific kinds of test cases. Make sure you [configure them correctly](core-4-configuration.md#test-case-file).