From 037f8425a6d73ca67b85ff1541698dc8004d23d3 Mon Sep 17 00:00:00 2001 From: Onizuka Date: Thu, 14 Nov 2024 12:27:24 +0100 Subject: [PATCH 1/4] Improve docs --- README.md | 86 +++++++++++++++++++++++++++------------------------ game.cfg | 12 +++++++ start-game.sh | 14 +++++---- 3 files changed, 65 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index f6e911e..501ea55 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,17 @@ +

+ +

+ # Lighthouses AI Contest "Reloaded" -Lighthouses AI Contest is a turn based game built by [Hector Martin aka "marcan"](https://github.com/marcan/lighthouses_aicontest), as the challenge for the AI contest within one of the largest and oldest demoparty and LAN party, the [Euskal Encounter](https://ee32.euskalencounter.org/) in Bilbao, Spain. +Lighthouses AI Contest is a turn based game built by [Hector Martin aka "marcan"](https://github.com/marcan/lighthouses_aicontest), +as the challenge for the AI contest within one of the largest and oldest demoparty and LAN party, +the [Euskal Encounter](https://ee32.euskalencounter.org/) in Bilbao, Spain. + +We are proud to present the "Reloaded" version of the contest, which features a new engine from scratch written in Go +and a proper GRPC API for the engine to communicate with the bots. + +You can find the Game mechanics and rules at our [Game Documentation](https://coda.io/@gabri-igz/lighthouses). To start building a bot, you will need to take the following steps: @@ -52,33 +63,48 @@ There's no need to include the `:latest` tag. ### Run the game -Go to the engine repository and run the `./start-game.sh -h` command to see the available options. -Among those, you will be instructuted on how to create a `.cfg` file with the bots and map you want to use. - -For a quick start, you can create a `game.cfg` file with the following content (make sure to replace `{username}` and `{repository}` with the correct values): -``` -bots=('ghcr.io/{username}/{repository}') -map=square.txt -turns=1000 -``` - -You can now run the game engine by executing `./start-game.sh -f game.cfg`. +Go to the engine repository and folder and run `./start-game.sh -f game.cfg`. After the game ends, some resources will be generated: - `/logs`: logs of the game and each bot that participated. - `/output`: JSON files to be used for visualization. -### Visualizing the game +You can also run `./start-game.sh -h` to see the available options. -To visualize and analyze the game, you can upload a JSON file to the [Lighthouses Visualizer](https://intelygenz.github.io/codeconz-lighthouses-engine/). +### Visualizing and diagnosing a game + +To visualize and analyze the game, you can upload a JSON file from the `/output` folder to the [Lighthouses Game Visualizer](https://intelygenz.github.io/codeconz-lighthouses-engine/). +This tool will help you check what your bot did during the game and how it performed. ### Customizing the game +If you are running the game with no changes at the `game.cfg` file, the game will run with the competition configuration, +a single random python bot playing against itself and a simple map. + +You will probably want to: +- Add your own bot to the game: `bots=('ghcr.io/{username}/{repository}' 'ghcr.io/intelygenz/codeconz-lighthouses-py-bot:latest')` +- change the configuration to test your bot under different scenarios. + +#### Configuration + +To change the game configuration, you can edit the `game.cfg` file at the root of the engine repository: + +- `bots`: an array of bot images that will play the game. E.g.: + `bots=('ghcr.io/john/bot-foo' 'docker.io/jane/bot-bar' ... 'quay.io/dave/bot-baz')` +- `map`: the map file that will be used in the game. E.g.: + `map=square.txt` +- `turns`: the number of turns the game will last. E.g.: + `turns=500` +- `turn_request_timeout`: the time the engine will wait for a bot to respond to a turn request. E.g.: + `turn_request_timeout=100ms` +- `time_between_rounds`: the time the engine will wait between rounds. E.g.: + `time_between_rounds=0s` + #### Add more maps You can find some included maps in the engine repository at the `/maps` folder, but those are not very challenging and will only serve you as a starting point. -You are expected to create your own maps and test your bot in different scenarios. +You are expected to create your own maps to test your bot under different scenarios. To do so: @@ -87,11 +113,7 @@ To do so: - update the `game.cfg` file to use the new map: `map={map_name}.txt` E.g., after downloading a map named `island.txt`, you would update the `game.cfg` file as follows: - -``` -bots=('ghcr.io/{username}/{repository}') -map=island.txt -``` +`map=island.txt` *Remember that the competition will take place on a 43x23 grid!* *Also remember that the competition will take place on maps that will not be revealed until the contest starts! @@ -102,7 +124,7 @@ Be prepared for anything!* You will probably want to test your bot against other bots. You can add more bots to the game by adding more elements to the `bots` array in the `game.cfg` file. -The base python bot is a random bot that you can add to your game. +The base python bot is a random bot that you can use for testing purposes. To be able to add as many instances of this bot as you want, you need to follow these steps: - Make sure you pulled the bot image: `docker pull ghcr.io/intelygenz/codeconz-lighthouses-py-bot:latest` - Generate as many tags from the base image as you want: `docker tag ghcr.io/intelygenz/codeconz-lighthouses-py-bot:latest {}/{}/{}`. @@ -114,26 +136,8 @@ E.g., by issuing the following commands: - `docker tag ghcr.io/intelygenz/codeconz-lighthouses-py-bot:latest local/local/bot-2` - `docker tag ghcr.io/intelygenz/codeconz-lighthouses-py-bot:latest anything/anything/bot-3` -And updating your `game.cfg` file to include the new bots: - -``` -bots=('ghcr.io/{username}/{repository}' 'local/local/bot-1' 'local/local/bot-2' 'anything/anything/bot-3') -map=island.txt -``` +And updating your `game.cfg` file to include the new bots: +`bots=('ghcr.io/{username}/{repository}' 'local/local/bot-1' 'local/local/bot-2' 'anything/anything/bot-3')` These tags will only be available locally and `./start-game.sh` will fail when trying to pull them. To overcome this, you can use the `-x` option: `./start-game.sh -xf game.cfg`. - -#### Configure the game - -There are several options you can use to configure the engine: -- `turn_request_timeout`: the time the engine will wait for a bot to respond to a turn request. -- `turns`: the number of turns the game will last. -- `time_between_rounds`: the time the engine will wait between rounds. - -You can check what values will be used in the competition in the `cfg.yml` file at the root of the engine repository. - -There are several ways to change these values: -- Providing it as an environment variable when running the engine: `TURNS=5 ./start-game.sh -f game.cfg`. -- Exporting them as environment variables and then running the engine. -- Updating the `cfg.yml` file and building the engine image again by passing the `-r` option: `./start-game.sh -rf game.cfg`. diff --git a/game.cfg b/game.cfg index f5b345d..3d1ecc7 100644 --- a/game.cfg +++ b/game.cfg @@ -1,5 +1,17 @@ +# An array of bot images that will play the game. +# Each element in the array needs to be a docker pull URI for a PUBLIC image. +# A ':latest' tag will always be used when pulling images. bots=('ghcr.io/intelygenz/codeconz-lighthouses-py-bot') + +# The map file that will be used in the game. +# The map file MUST exist in the ./maps/ folder. map=square.txt + +# The number of turns the game will last. turns=500 + +# The time the engine will wait for a bot to respond to a turn request. turn_request_timeout=100ms + +# The time the engine will wait between rounds. time_between_rounds=0s diff --git a/start-game.sh b/start-game.sh index 16639dd..fb6771e 100755 --- a/start-game.sh +++ b/start-game.sh @@ -52,20 +52,22 @@ Options: The game-config file format must be: - # bots array with all round participants, these are docker pull URIs, - # these images MUST be public. 'latest' tag will always be used for pulling, e.g.: + # An array of bot images that will play the game. + # Each element in the array needs to be a docker pull URI for a PUBLIC image. + # A ':latest' tag will always be used when pulling images. bots=(${YELLOW}'ghcr.io/john/bot-foo' 'docker.io/jane/bot-bar' ... 'quay.io/dave/bot-baz'${CLEAR}) - # map file. must exist into ./maps/ folder, e.g.: + # The map file that will be used in the game. + # The map file MUST exist in the ./maps/ folder. map=${YELLOW}square.txt${CLEAR} - # game turns, e.g. + # The number of turns the game will last. turns=${YELLOW}500${CLEAR} - # the time the game engine will wait for a bot to answer, e.g: + # The time the engine will wait for a bot to respond to a turn request. turn_request_timeout=${YELLOW}100ms${CLEAR} - # the time the game engine will wait between rounds, e.g: + # The time the engine will wait between rounds. time_between_rounds=${YELLOW}0s${CLEAR} " exit ${1:-0} From 2ee313571c29c23144b0448fd65fded1bd8af826 Mon Sep 17 00:00:00 2001 From: Onizuka Date: Thu, 14 Nov 2024 12:31:03 +0100 Subject: [PATCH 2/4] Small README fix --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 501ea55..baf8913 100644 --- a/README.md +++ b/README.md @@ -89,15 +89,15 @@ You will probably want to: To change the game configuration, you can edit the `game.cfg` file at the root of the engine repository: -- `bots`: an array of bot images that will play the game. E.g.: +- `bots`: an array of bot images that will play the game: `bots=('ghcr.io/john/bot-foo' 'docker.io/jane/bot-bar' ... 'quay.io/dave/bot-baz')` -- `map`: the map file that will be used in the game. E.g.: +- `map`: the map file that will be used in the game: `map=square.txt` -- `turns`: the number of turns the game will last. E.g.: +- `turns`: the number of turns the game will last: `turns=500` -- `turn_request_timeout`: the time the engine will wait for a bot to respond to a turn request. E.g.: +- `turn_request_timeout`: the time the engine will wait for a bot to respond to a turn request: `turn_request_timeout=100ms` -- `time_between_rounds`: the time the engine will wait between rounds. E.g.: +- `time_between_rounds`: the time the engine will wait between rounds: `time_between_rounds=0s` #### Add more maps From f0f56a83b046d0f06e000f4f214d9af4275d008b Mon Sep 17 00:00:00 2001 From: dovixman Date: Thu, 14 Nov 2024 12:50:42 +0100 Subject: [PATCH 3/4] remove unnecessary docs and update game engine configuration variables --- docs/game_engine.md | 14 ++++++------ docs/game_flow.md | 54 --------------------------------------------- docs/go_bot_flow.md | 26 ---------------------- docs/py_bot_flow.md | 26 ---------------------- 4 files changed, 7 insertions(+), 113 deletions(-) delete mode 100644 docs/game_flow.md delete mode 100644 docs/go_bot_flow.md delete mode 100644 docs/py_bot_flow.md diff --git a/docs/game_engine.md b/docs/game_engine.md index d79a556..6b6de70 100644 --- a/docs/game_engine.md +++ b/docs/game_engine.md @@ -15,13 +15,13 @@ It will run three main services to manage the game: ## Loading game configuration The game engine will load the configuration from the environment variables or the configuration file. -- `game.listen_address` (defaults to `50051`) -- `game.join_timeout` (defaults to `5 seconds`) -- `game.turn_request_timeout` (defaults to `100 milliseconds`) -- `game.turns` (defaults to `15`) -- `game.board_path` (defaults to `./maps/island_simple.txt`) -- `game.verbosity` (defaults to `true`) -- `game.time_between_rounds` (defaults to `1 second`) +- `listen_address` (defaults to `50051`) +- `join_timeout` (defaults to `5 seconds`) +- `turn_request_timeout` (defaults to `100 milliseconds`) +- `turns` (defaults to `15`) +- `board_path` (defaults to `./maps/island_simple.txt`) +- `verbosity` (defaults to `true`) +- `time_between_rounds` (defaults to `1 second`) > You can check the default values at the [Configuration file](../cfg.yaml) diff --git a/docs/game_flow.md b/docs/game_flow.md deleted file mode 100644 index 7638115..0000000 --- a/docs/game_flow.md +++ /dev/null @@ -1,54 +0,0 @@ -# Game Flow -- Initialize configuration: - - `game.listen_address` (defaults to `50051`) - - `game.join_timeout` (defaults to `5 seconds`) - - `game.turn_request_timeout` (defaults to `100 milliseconds`) - - `game.turns` (defaults to `15`) - - `game.board_path` (defaults to `./maps/island_simple.txt`) - - `game.verbosity` (defaults to `true`) - - `game.time_between_rounds` (defaults to `1 second`) -- Initializes a new Game board with the defined map on `game.board_path`, and with the defined turns in `game.turns` -- Starts a gRPC server to let the players join the game on `game.listen_address` for the time defined in `game.join_timeout` - - When the players join, they are given their `Player ID` back. -- Sends the initial state to all registered players containing - - `PlayerID` - - `PlayerCount`: Number of Players on the current game - - `Position`: The initial position of the player - - `Map`: The map representation as integers where - - `0` is a Water cell, not playable - - `1` is an Island cell, playable - - `Lighthouses`: The lighthouses position -- Start the game - - Set the initial game state with the Energy, the Player information and the Lighthouses information - - For each turn in the turns defined in `game.turns` ... - - Calculate each Island cell energy based on the distance from the Lighthouses using the next formula (`energy += floor(5 - distance_to_lighthouse)`) with a maximum value of `100` - - Calculate each Lighthouse energy (each turn each Lighthouse looses `10` energy points) - - Calculate each Player energy by extracting current positions cell energy - - If there is only one player on the cell, all the energy will be absorbed by the player - - If there are more than one player on the cell, the energy will be equally distributed between the players - - Store new round information on the game state - - Start a new round, for each player... - - Request the new turn action to each player by sending information about the player - - `Position` - - `Score` - - `Energy` - - `View`: A map with the energy of the surroundings cells of the player up to 7 cells of distance - - `-1` is a Water cell, not playable - - `>0` is an Island or Lighthouse cells Energy - - `Lighthouses` information, including - - `Position` - - `Energy` - - `Owner`: `PlayerID` owning the Lighthouse or `-1` if it has no owner - - `Connections`: The Lighthouse connections to other Lighthouses - - `HaveKey`: If the player has the key to the Lighthouse - - Execute each player action, the actions can be - - `Move` to given position - - `Attack` a Lighthouse - - `Connect` two Lighthouses - - `Pass`, do nothing on this turn - - Store the players turn in the game state - - When all the runs are executed, the `player scores` are calc - - - - - - clearulated based on the number of connections and triangles they have. - - Write game status to a file diff --git a/docs/go_bot_flow.md b/docs/go_bot_flow.md deleted file mode 100644 index 5713a3c..0000000 --- a/docs/go_bot_flow.md +++ /dev/null @@ -1,26 +0,0 @@ -# Go Bot Flow -- Initialize Bot configuration: - - `--bn`: Bot name - - `--la`: Bot listen address - - `--gs`: Game server address -- Connect to the Game server and Join the current game - - Sends the `BotName` and the `BotAddress` to the Game server - - Receives the `PlayerID` from the Game server -- Start the two main services to play the game - - `InitialState`: Receives the initial state from the Game server with the following information - - `PlayerID` - - `PlayerCount` - - `Position` - - `Map` - - `Lighthouses` - - `Turn`: Sends the turn action to the Game server - - Receives from the Game server the following information - - `Position` - - `Score` - - `Energy` - - `View` - - `Lighthouses` - - Returns the action to be executed on the current turn to the Game server - - `Action` - - `Destination` - - `Energy` diff --git a/docs/py_bot_flow.md b/docs/py_bot_flow.md deleted file mode 100644 index 5a36a97..0000000 --- a/docs/py_bot_flow.md +++ /dev/null @@ -1,26 +0,0 @@ -# Py Bot Flow -- Initialize Bot configuration: - - `--bn`: Bot name (defaults to `random-bot`) - - `--la`: Bot listen address - - `--gs`: Game server address -- Connect to the Game server and Join the current game - - Sends the `BotName` and the `BotAddress` to the Game server - - Receives the `PlayerID` from the Game server -- Start the two main services to play the game - - `InitialState`: Receives the initial state from the Game server with the following information - - `PlayerID` - - `PlayerCount` - - `Position` - - `Map` - - `Lighthouses` - - `Turn`: Sends the turn action to the Game server - - Receives from the Game server the following information - - `Position` - - `Score` - - `Energy` - - `View` - - `Lighthouses` - - Returns the action to be executed on the current turn to the Game server - - `Action` - - `Destination` - - `Energy` From 0fa13dbd72dc1157a876b72f522c387904892bde Mon Sep 17 00:00:00 2001 From: dovixman Date: Thu, 14 Nov 2024 12:51:00 +0100 Subject: [PATCH 4/4] remove unnecessary docs and update game engine configuration variables --- docs/game_engine.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/game_engine.md b/docs/game_engine.md index 6b6de70..db9c70c 100644 --- a/docs/game_engine.md +++ b/docs/game_engine.md @@ -23,8 +23,6 @@ The game engine will load the configuration from the environment variables or th - `verbosity` (defaults to `true`) - `time_between_rounds` (defaults to `1 second`) -> You can check the default values at the [Configuration file](../cfg.yaml) - ## Joining the game The players bot will call the Join service on the game server.