Step by Step Installation Guide

This section will explain the installation process of the Geometry Friends Framework through a step by step process.

First Step

First and foremost there are some simple prerequisites that have to be met depending on your operating system:

  • Windows: (optional) if you want to play the game with sound install the openal library from here
  • Ubuntu/Debian: install the mono framework and, optionally, the openal library for sound. To do this type in a terminal the following command: sudo apt-get install mono-complete libopenal1
  • MacOSX: install the mono framework from here

Second Step

Download the competition pack (see Downloads) and extract its contents. Once extracted go into the GeometryFriendsAgents folder. This is the main folder of the Geometry Friends Framework.


The most important files in this folder are:

  • GeometryFriendsAgents.sln the project solution;
  • The two .cs files (CircleAgent.cs and RectangleAgent.cs);
  • GeometryFriendsGame folder where the GeometryFriends game is located;

Let’s open the solution file first, assuming you have installed Visual Studio (we recommend Visual Studio 2012 or 2013 at least), let’s double click on the GeometryFriendsAgents.sln file.

Third Step

Once Visual Studio has loaded you should have a setup much like the one shown here:


By default the framework comes with the random circle and rectangle agent implementations. Participants are expected to modify both of these files in order to implement their own agent algorithms.

In order to be able to run/debug you agents directly from Visual Studio you now need to add the game as an existing project and set it as the default startup project. To do this, in the Solution Explorer, right-click on the Solution ‘GeometryFriendsAgents’ (1 project) item and select Add > Existing Project. Then navigate to GeometryFriendsAgents > GeometryFriendsGame > Release and select GeometryFriends.exe.

To finalize this step right click on the newly added item GeometryFriends (the one with the icon gf_vs_icon) and select Set as StartUp Project. It should look like this:


Fourth Step

If you want to ensure that your agent code always builds before you start GeometryFriends, i.e. you don’t want to have to issue build commands manually and want it to be triggered automatically when you start (Debug or Release) an extra configuration is required. In Visual Studio go to TOOLS > Options > Projects and Solutions > Build and Run and untick the option Only build startup projects and dependencies on Run. Additionally, in the same options menu check that the On Run, when projects are out of date is set to Always build. Your configuration should look similar to the image below.


Next, in the Solution Explorer right-click on “Solution ‘GeometryFriendsAgents’ (1 project)” and select Configuration Manager. Ensure that the Build column is checked.

Build the solution so that the example agent implementation, GeometryFriendsAgents.dll is created.

Fifth Step

Lets check if everything is set up properly. In Visual Studio press Start or the F5 key to start your project. If it ran successfully this screen should appear:

gf_initial_screenYou can now skip the Wiimote remote controller connection by pressing Esc and proceed to the main menu as shown below


You should now go to the options menu. If for some reason the game crashes at this stage please it is because your files are marked as downloaded from the web please see Troubleshooting point 4 at the end of this page. Once inside the options menu navigate to the Agents Implementation option and press enter until the Geometry Friends Agents are selected as the agent implementation to be used.


You can now try the game with or without AI:

  • Single Player: play the game with one of the characters being played by an AI (mode specific options available in the Options menu)
  • Multiplayer: play the game without any AI where both characters are played by you (keys circle: a s d w; keys rectangle: j k l i)
  • Agents Only: both characters are played by AI. Since several AIs can be provided in the Agents folder of the game you can select the one you wish to play in this mode from the Options menu

After choosing Single Player/Multiplayer/Agents Only the Level Select screen should appear:

gf_level_selectBy selecting a level (any level should do) the game should start, you and/or your AI can start solving the selected puzzle by controlling the Circle and Rectangle respectively.


Agents DLL File Location

Since you can have several AI implementations to control the Circle and Rectangle characters you can now choose which executes from the game Options menu. To enable you to have several implementations and alternate between them without problems it is important to understand where the AI implementations are loaded from. All implementations are loaded from the same folder that is targeted as the output directory of you Visual Studio GeometryFriendsAgents project: GeometryFriendsGame\Release\Agents\ . In this folder you can have as many implementations as you wish (e.g. ReinforcementLearningAgent.dll or RandomAgent.dll) given that they have different assembly names as shown in the image below.

gf_several_agent_implementationsThis means that if you create another agent implementation you should change the assembly name so that you can switch between implementations within the game without the need to copy files or build projects. In Visual Studio choose the GeometryFriendsAgents project and right click it. Then choose the Properties option. Under the Application tab change the Assembly name property to the new implementation name.


If you have not been able to build the agents provided and play the game please verify the following settings which are already pre-configured in the competition pack but might have accidentally been changed:

  1. Project Properties related: in Visual Studio choose the GeometryFriendsAgents project and right click it. Then choose the Properties option.
    • In the Application tab check that the Output Type is set to Class Library
    • In the Build tab set the Configuration: field to All Configurations. Next, check that Output path: is set to GeometryFriendsGame\Release\Agents\ (do not change this path, the Release in this path refers the game build and not your agents’ build)
  2. The GeometryFriends project (the one with the icon gf_vs_icon) should be the default startup project, to do this right-click the project and select Set as StartUp Project
  3. Verify that the GeometryFriends dependency of your GeometryFriendsAgents project is not being copied to the output directory. In the solution explorer of Visual Studio navigate to GeometryFriendsAgents > References > GeometryFriends , right click this item and select Properties. Set the Copy Local property to false.
  4. When downloading/extracting the competition pack from the Geometry Friends website the files may be marked as being copied from the web which will crash the game when you try read/load any agent implementations. Under Windows, to resolve this you should go to the Agents folder and right click each file and then select the option “unblock“. You must do this for all the agent implementations in this folder.