Update README

README.md

@@ -2,41 +2,114 @@
 
 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.
 
-I have updated from his original Python 2.7 code, to a Go 1.22 languaje and also I have added a few more changes:
-
-- Original version
-  - Python 2.7
-  - PyGame for visualization
-  - Based on comunications via stdin / stdout
-  - Maps esigned for a few players at the same game
-  - Built to run in a stand alone computer
-- My "Reloaded" version
-  - Go 1.22
-  - No Visualization layer
-  - Based on gRPC/Protobuf communication
-  - Focused on allowing many players in the same game
-  - Container first approach, game server is a container, each bot is a container (no matter which language)
-
-The following command will build and start the game server + 3 bots and will show you the game progress until one of the bot wins, then all created resources (_docker containers, images, networks_) will be erased.
-
-```bash
-make docker-test
+To start building a bot, you will need to take the following steps:
+
+## First steps
+
+- Install [Docker](https://docs.docker.com/engine/install/#release-channels)
+- Make sure you have a [GitHub account](https://www.github.com)
+- Clone this repository in your local machine
+
+## Create a new bot repository
+
+- Create a new repository using one of the following templates (you can also start from scratch!):
+    - [Go bot template](https://github.com/new?owner=intelygenz&template_name=codeconz-lighthouses-go-bot&template_owner=intelygenz)
+    - [Python random bot template](https://github.com/new?owner=intelygenz&template_name=codeconz-lighthouses-py-bot&template_owner=intelygenz)
+- Clone it in your local machine
+
+Considerations:
+
+- Make sure the bot repository is owned by one of your team members.
+- The project can be public or private.
+- Only one repository is needed per bot.
+
+## Test your bot!
+
+### Push your changes
+
+Bot repository templates contain a `build-push-github.yml` workflow file that will build and push the bot image to the GitHub Container Registry.
+This action is triggered when you push or merge to the main branch of the repository.
+If you decided to start from scratch, you will need to create a similar workflow file.
+
+Make sure the action is successful and the image is pushed to the GitHub Container Registry.
+
+### Make the image public
+
+For the engine to be able to pull the bot image, you need to make it public.
+
+- Click on the package that was created by the GitHub Action in the "Packages" section of your bot repository, at the bottom of the right column menu.
+- In the package page, click on "Package Settings" at the bottom of the right column menu.
+- At the bottom of the Package Settings page there's a "Danger Zone" section. Click on "Change visibility" and make the package public.
+
+You can also take this opportunity to copy the label of the image, which should be something like `ghcr.io/{username}/{repository}`. 
+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
 ```
 
-If you want to test more bots, change the `GAME_BOTS` variable in `Makefile` and retry.
+You can now run the game engine by executing `./start-game.sh -f game.cfg`.
 
-> In case the test crashes, you can clean docker leftovers by running:
->
-> ```bash
-> make docker-destroy
-> ```
+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.
 
-## Test with local Go/python
+### Visualizing the game
 
-If you want to test the game server and bots locally, you can run the following commands:
+To visualize and analyze the game, you can upload a JSON file to the [Lighthouses Visualizer](https://intelygenz.github.io/codeconz-lighthouses-engine/).
 
-- `make rungs`: Run the game server
-- `make runbotgo`: Run the Go bot (you need to have Go installed)
-- `make runbotpy`: Run the Python bot (you need to have python installed and
-  libraries from requirements.txt installed. You can create a virtualenv or use
-  poetry).
+### Customizing the game
+
+#### 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.
+
+To do so:
+
+- use the [Lighthouses Map Generator](https://dovixman.github.io/lighthouses_map_generator/) to generate a new map
+- copy the generated map to the `/maps` folder in the engine repository
+- 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
+```
+
+*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!
+Be prepared for anything!*
+
+#### Add some competition
+
+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.
+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 {}/{}/{}`.  
+  You only need to replace the three `{}` with any string you want.
+
+E.g., by issuing the following commands:
+
+- `docker tag ghcr.io/intelygenz/codeconz-lighthouses-py-bot:latest local/local/bot-1`
+- `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
+```