Run the example bot

Running the game locally is great, but the event is about having a bot play in your place.

Each scaffold comes with a very simple example bot. We will use it in this guide to show you how to run a bot locally and make it play the game. You can then replace the sample code with your own, more complex bot logic.

Prerequisites

• tools setup, in particular the language-specific tools (e.g. Python, Java)
• cloning the repo to have a local copy of the game and the example bot

Running the example bot

1. Choose your preferred bot scaffold. We provide scaffolds in Python and Java.

   Choose the one you are most comfortable with, or the one you want to learn. The instructions and provided code are functionally the same in both scaffolds.

   You may of course try both of them out before choosing one, however keep in mind that for the tournament, you will have to choose a single scaffold to work with.

2. Open your team repository in your preferred IDE (e.g. VS Code).

3. Inside the directory of your chosen scaffold (either python or java), you will find a file named example.env. This file contains configuration for your bot. Copy it and name the copy .env. Make sure to keep it inside the same directory.

   The default configuration should be good for an initial run.

4. Open a new terminal.

5. Navigate to the directory of your chosen scaffold using the ls and cd commands. Do not hesitate to ask the staff for help if you are not familiar with the terminal.

6. The exact command to run the bot will depend on the scaffold you chose. You can find instructions below, or more detailed instructions in the README of the chosen scaffold.

   Note that the commands below should be run inside the scaffold's directory (either python or java).

   Python

   # =================================================
   # Those commands only need to be run the first time
   # =================================================
   
   # Create a Python virtual environment in .venv
   python3 -m venv .venv
   # Activate the Python virtual environment on Linux/macOS
   source .venv/bin/activate
   # Activate the Python virtual environment on Windows
   .venv\Scripts\activate
   
   # Install Python dependencies
   pip install -r requirements.txt
   
   # =================================================
   # This command needs to be run every time you want
   # to start the bot
   # =================================================
   
   # Start the script, it needs to be started from within python/src/
   cd src
   python3 main.py
   
   # If you are running the bot inside WSL or inside a container, you need to tell the bot to
   # listen on all interfaces, not just localhost.
   CONQUERHACK_HOST=0.0.0.0 python3 main.py
   # If you do not want to set the environment variable every time, you can also set the host in
   # the .env file.

   Java

   # Build the bot to a JAR file
   # This creates a JAR file at target/conquerhack-bot-1.0-SNAPSHOT.jar
   mvn clean package
   
   # Run the bot
   java -jar target/conquerhack-bot-1.0-SNAPSHOT.jar
   
   # If you are running the bot inside WSL or inside a container, you need
   # to tell the bot to listen on all interfaces, not just localhost.
   CONQUERHACK_HOST=0.0.0.0 java -jar target/conquerhack-bot-1.0-SNAPSHOT.jar
   # If you do not want to set the environment variable every time, you
   # can also set the host in the .env file.

7. This will start a websocket server at ws://localhost:12345. The modified OpenFront client (the game) will connect to this server to communicate with the bot. But for that, we need to start the OpenFront client.

8. Start a local instance of the game by following the instructions in this guide.

9. On localhost:9000 in a browser, wait for the game and the bot to connect and start communicating. After a few seconds, you should see that a lobby is joined automatically, and the game starts. The bot will then play by itself, and you can see its actions in the game.

10. Just like for the game, once you are done testing the bot, you can stop it by going back to the terminal and pressing CTRL + C (or CMD + C on macOS). This will stop the bot server.

Now that you are able to run the game and bot locally, it is time to start customizing your bot!