BOT ARENA

Contents

• Few words about project
• How to use?
• How does the program work?
• Projects structure
• Creating maps
• Creating bots
• What is log? (baby don't hurt me)

Few words about project

"Bot arena" is a group project implemented under the "Innovative Projects by Nokia", which main goal was to create an environment where users can watch and test performance and efficiency of bots written by them.

How to use?

Installation

1. Download python interpreter.
2. Download external pygame module with "pip install pygame".
3. Download the repository or clone it with "git clone https://github.com/BartoszKruszewski/bot-arena.git".

Activation

1. Go to the root folder of the project in terminal.
2. Start the app with "py main.py" instuction.

Usage

The program consists of 2 scenes where user can set up a simulation and a scene, where he can watch and analyze the bots' performance. Each scene consists of windows with different functionalities.

• Simulation creation scene

Allows user to configure and generate a simulation in which multiple games could be carried out. This scene is made up with 5 windows:

1. Bots - List of bots from which user can choose 2 bots that will play against one another in simulation that is being genereated.

2. Maps - List of maps the simulation can be generated on.

3. Add random map - Tool for creating new maps. After clicking "generate map" button a random map with given name will appear in the list of maps.

4. Control - Panel where user can see the names of bots and map that will be used in simulation and adjust:

   • Number of games - Amount of games that will be played in simulation.
   • Timeout fields for which simulations generation will be terminated if any of the specified timeout values are exceeded.
     • Max ready timeout - Time for bot to preprocess the game.
     • Max move timeout - Time for bot to make a move.
     • Max game timeout - Time for bots to play out entire game.
   • Simulation's name

   After specifing those fields user can push "start simulation" button that will start generating game's for that simulation.

5. Progress - Contains information about current progress of generation of the simulation and number of games each bot has won.

• Simulation launch scene

Gives user functionality of inspecting one log from previously generated simulations and running it. This scene consists of 4 windows:

1. Simulations - List of simulations previously generated by user.
2. Logs - List of logs that make up the selected simulation.
3. Simulation info - Gives user information about active simulation:
   • Simulation's name.
   • Which map the simulation was generated on.
   • Names of the bot's that played in this simulation.
   • Number of games each bot has won.
4. Log info - Gives user information about active log:
   • Log's name.
   • Name of the bot that has won the game.
   • Amount of turns the bots took to end the game.

• Simulation analyzing scene

Allows user to analyze the performance of each bot based on the log that has been chosen previously in simulation launch scene. This scene consists of 4 windows:

1. Log - List of turns from chosen log where the highlighted turn is the decision the bots made in current turn.
2. Game - Graphical representation of the state of game played in real time.
3. Stats - Resources of both bots.
4. Controls - Panel to control the general game flow:
   • Game speed - field where you can adjust how fast the simulation is being played out or even pause it.
   • Zoom - field where you can adjust how much the game's graphical representation is magnified.
   • Helpers:
     • eye icon - Option to see where tiles that are occupied by obstacles
     • pointer icon - Displays a little red dot indicating each objects real position.
     • grid icon - Shows a grid that marks where the tiles are.

How does the program work?

Projects structure

• assets Assets for game's graphical representation.
• bots Bot scripts.
• logs Maps the game is played on.
• packages Program's logic.
  • game logic Module responisble for game's logic.
  • gui Module responsible for the program's graphical representation.
    • game renderer Game's graphical represention.
    • gui_objects User interface's graphical representation.
    • scenes Views of the program.
  • simulator Module responsible for bot's logic.

Creating maps

The maps that bots can play thier games on are represented as json files with 4 attributes:

• MAP_SIZE_X - value specifing the width of the map.
• MAP_SIZE_Y - value specifing the height of the map.
• path - list of ordered pairs (2-tuple) that specifies the path that the units will be walking on in the game.
• obstacles - list of ordered pairs (2-tuple) that specifies placement of the objects that take up tiles to prevent placing buildings there

The path has to:

• start in point (0, 0)
• end in point (X_SIZE - 1, Y_SIZE - 1)
• have the next tile placed with it's side connected to the previous tile's in the path side.

Creating bots

Bot standard

Bot Package Python

To simplify the implementation of bots in Python for Bot Arena, a dedicated package is available. This package provides a class template, Bot, that offers tools for easier implementation of your own agents. Explore the Bot Package on GitHub for seamless bot implementation in Python for Bot Arena.

What is log?

Log is our handy way of keeping track what choice did each bot in every turn. So to answer the question log is a text file that in each line has information about a turn in played game. There is a convention to the name and content of a log file.

Naming convention

index_bot1_bot2_win.log where:

• index - index of log in the whole generated simulation
• bot1, bot2 - names of the bots that played in this game
• win - information about which bot won (0 - first bot won, 1 - second bot won)

For example: "4_random_bot.py_spawn_bot.py_1.log"

Content convention

In the first 3 lines the log keeps map, player1, player2 values which are names of the players and map that that where used in this log's game.

The rest of the lines has a form as follows: Action_of_first_player | Action_of_second_player

Player can make an action of 3 types:

• Place a building
  • F x y - builds farm at (x, y) coordinates.
  • T x y - builds tower at (x, y) coordinates.
• Spawn a soldier
  • S swordsman - spawns a swordsman that is a melee unit.
  • S archer - spawns an archer that is a ranged unit.
• Skip turn
  • W - don't do anything in this turn.