How to Run the Agents

The quick start feature allows users to start the Geometry Friends game on a specific level with an AI agent.

How to use

In order to streamline agent execution and trigger advanced execution parameters participants must use a specific command line argument order when running the main executable of the Geometry Friends game. The overall command line argument syntax is the following:

GeometryFriends.exe
        [ --no-rendering ]
        [ --disable-fixed-time-step ]
        [ --log-to-file ]
        [ --speed speed_value ]
        [ --simulations simulation_count ]
        [ --batch-simulator ]
        [ -m | -s | -st | -stn | -l world_number level_number ]
        [ -a agent_dll_path ]

Note: brackets represent options, for example [-optional_argument_1 non_optional_parameter [optional_parameter]]

Options

A first set of triggers control how the game runs and the overall logging behavior:

  • --no-rendering : disables rendering launching a basic form with the option to cancel the game simulation that is undergoing.
  • --disable-fixed-time-step : makes the game update as fast as possible without any target timestep between game updates.
  • --log-to-file : if specified the general logging used in the game is written to the file Logs/Log.txt. This logging can be used to log agent information through the GeometryFriends.Log class.
  • --speed speed_value : enables you to make the game run faster/slower. The speed_value must be greater than 0.
  • --simulations simulation_value : enables you to run the same game command several times automatically to simulate the same level multiple times. The simulations_count must be greater than 0.
  • --batch-simulator : launches a batch simulation form that enables you to configure and run multiple simulations using selected agent implementations and levels.

The following triggers configure what game mode is ran and what files are written. The parameters (world_number and level_number) for any of these triggers are always the same and mandatory for any of the options below:

  • -m : this option runs a specific level without AI and where the game is played by a human user.
  • -s : this option runs a specific level with the current implemented AI (Circle, Rectangle or both).
  • -st : the same as -s but the level time limit is applied, i.e. the level ends when the level’s time limit is reached. When the level is finished or the time limit is reached the results file /Results/Results.csv is (created or) updated with thre results of the level.
  • -stn : the same as -st but the results are written to a new file that has in its name the timestamp of when the game ended.
  • -l : this option runs a specific level with the current implement AI, just like -s option, but with the added Agent Logger Tool, running in the background.

The final trigger enables you to specify which agent implementation should be run directly by command line:

  • -a agent_dll_path : selects the agent implementation passed in the agent_dll_path to be used if agents are being used in the game.

World/Level Arguments

These arguments will point towards the specific level the participant wants to run and works in the following fashion.

World Number

The world number is attributed to each XML file found in the Levels folder of the Geometry Friends’ game in alphabetical order. The count starts at 0 (unlike the Level Number), so by using the default number of worlds that comes with the Geometry Friends framework, the Circle World corresponds to the number 0, while the Cooperative world corresponds to the number 1 and the Rectangle world to the number 2.

Note by adding more worlds to the game these numbers will change, so keep track of the files within the folder as they are ordered alphabetically. Meaning that a world named Adventure for example will be the new 0, while the Circle world will shift to number 1.

Level Number

The level number points towards the specific level within a world, so for example if a participant wanted the first level of the circle world the arguments would be 0 1.

Note Unlike the world number argument levels start at 1 and not 0.

Examples

Some typical running options examples:
  • GeometryFriends.exe -m 1 2 : runs the game in multiplayer mode for world 1 level
  • GeometryFriends.exe --no-rendering --disable-fixed-time-step -st 1 1 : runs the game (world 1 level 1) without any rendering and with the maximum updates as possible with the default agent implementation (the last used in the game).
  • GeometryFriends.exe -st 1 1 : runs the game (world 1 level 1) with the default agent implementation (the last used in the game), where the agent execution is observed in the game window and the Results.csv file found in the Results (same directory as the GeometryFriends.exe) will be created/updated.
  • GeometryFriends.exe -stn 1 1 -a “c:\MyAgentImplementation.dll” : runs the game (world 1 level 1) with using the agent implementation of MyAgentImplementation.dll, where the agent execution is observed in the game window and a timestamped results file will be writen to the Results directory.

How to Setup

In the Step by Step Installation Guide we showed the normal start from Visual Studio where participants would always have to go through the game menus to try a specific level. In this section and using the command line arguments described above we show how to quick start GeometryFriends from within Visual Studio.

By right clicking and selecting the Properties option of the GeometryFriends project (in the solution explorer), participants will just need to alter the Arguments space with the defined order described above.

gf_vs_quick_start