Simulation Primer

---

Introduction

So, you've installed GAMS and now you're ready to get started with some simulations? Great news. GAMS simulations are easy to setup with real, distributed, and decentralized agents that scale to dozens and hundreds within seconds in the Unreal Engine. On this page, we'll walk through your first GAMS simulations.

---

The Basics of Simulation

We'll only be covering the setup of Unreal, UnrealGAMS, and GAMS on Ubuntu Linux. Simulating with GAMS involves two basic steps:

1. Start the UnrealGAMS instance (essentially, launch the Unreal Engine)
2. Launch at least one GAMS agent controller (e.g., $GAMS_ROOT/bin/gams_controller)

---

Starting UnrealGAMS

Depending on how you installed UnrealGAMS, you can start UnrealGAMS in two different ways. First, if you downloaded a release candidate, you can simply launch UnrealGAMS.sh from within the extracted release candidate. Second, if you cloned the UnrealGAMS repo (e.g., with $GAMS_ROOT/scripts/linux/base_build.sh unreal-gams), then you can run cook.sh from within the cloned directory after you've built everything with base_build.sh. Within the cloned directory will be an out/LinuxNoEditor, which has an UnrealGAMS.sh. We tend to recommend modifying this UnrealGAMS.sh to operate in a smaller windows mode instead of the default full screen. To do this, simply download this example script and replace the result of the cook.sh command.

From Release Candidate (Download)

unzip UnrealGAMS.zip
cd UnrealGAMS
./UnrealGAMS.sh

From Git Clone

$GAMS_ROOT/scripts/linux/base_build.sh unreal-gams gams madara
<reload your terminal if it's first install by closing and reopening your terminal>
cd $UNREAL_GAMS_ROOT
./cook.sh
cd out/LinuxNoEditor
UnrealGAMS.sh

Either of the above will acquire the UnrealGAMS simulation environment and start an instance of it

---

Starting GAMS Agent Controllers

GAMS controllers tend to come in one of two forms: 1) the provided GAMS controller and 2) a custom GAMS controller generated by gpc.pl. The first controller has all of the built-in platforms and algorithms that come with the GAMS installation process. The second controller is necessary if you build your own algorithms, platforms, threads, or other components. Both agent controllers share a common help system and set of arguments that you can use to specify algorithms to run, the number of agents to control, etc.

To start a GAMS agent controller, you should be able to simply call gams_controller from anywhere on the command line. Help is available with the -h or --help option. The most common arguments are combinations of -i (the identifier of the agent), -n (the number of agents in the simulation), -mc (the number of controllers to merge into the same process), -b, -m, -u, --zmq (transport options), -nt (use only shared memory transport between merged controllers). See -h for more information.

---

Example Simulations

In this section, we'll get you started with some example simulation scripts that are provided in the GAMS repo. By tweaking parameters and looking into the simple scripts, you can what is possible with the default gams_controller and also what is available to you in custom controllers generated by gpc.pl.

Formation Sync

Arguments

./run_rectangle.sh [type] [num agents] [no-transport]
./run_triangle.sh [type] [num agents] [no-transport]
./run_wing.sh [type] [num agents] [no-transport]

type is the spawnable type of the agent. num agents is the number of agents to spawn. If you specify an argument to the no-transport option, then it will only use a shared memory transport within the GAMS controller (technically within the gams::controllers::Multicontroller which can manage many agents in the same GAMS controller).

Terminal 1 (Launch Unreal)

cd <Your UnrealGAMS client directory>
./UnrealGAMS.sh

Terminal 2 (Launch GAMS Controller)

cd $GAMS_ROOT/scripts/simulation/unreal/formation_sync
./run_rectangle.sh quad 30 nt