-
Notifications
You must be signed in to change notification settings - Fork 20
Simulation Primer
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.
We'll only be covering the setup of Unreal, UnrealGAMS, and GAMS on Ubuntu Linux. Simulating with GAMS involves two basic steps:
- Start the UnrealGAMS instance (essentially, launch the Unreal Engine)
- Launch at least one GAMS agent controller (e.g.,
$GAMS_ROOT/bin/gams_controller)
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.shFrom 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.shEither of the above will acquire the UnrealGAMS simulation environment and start an instance of it
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.
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.
The Follow algorithm instructs an agent or swarm of agents to follow a target at a specific offset.
Youtube Videos
Arguments
./run_follow_agent.sh [leader=agent.0] [id start=1] [type=quad] [num agents=10] [no-transport]
./run_follow_line.sh [type] [num agents] [no-transport]
./run_follow.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).
id start is important for running the follow_agent script at a later agent id (rather than agent.0), which can be combined with other scripts (such as running waypoints for agent.0 or using a Xbox joystick for agent.0 that can then be followed by a swarm). leader specifies the leader agent to follow.
Terminal 1 (Launch Unreal)
cd <Your UnrealGAMS client directory>
./UnrealGAMS.shTerminal 2 (Launch GAMS Controller)
cd $GAMS_ROOT/scripts/simulation/unreal/follow
./run_follow_line.sh quad 30 ntFormation Sync shows an example of team/group formation in swarms with collision avoidance and a synchronous model of computation executed within the collection of agents.
Youtube Videos
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.shTerminal 2 (Launch GAMS Controller)
cd $GAMS_ROOT/scripts/simulation/unreal/formation_sync
./run_rectangle.sh quad 30 ntGreet is a reconnaissance algorithm that creates a scalable team of greeters that watch their own areas for one of a list of targets. If the targets come within their guard/greeting area, the greeters will move to a position above the target. The algorithm is primarily meant for quadcopters but could also be fun to play with for biological agents such as puppies, deer, etc. (the animals would move atop the trigger targets).
Youtube Videos
Arguments
./run_greet.sh [type=quad] [targets=1] [num agents=10] [no-transport]
./run_greet_and_follow.sh [type=quad] [targets=1] [followers=2] [num agents=10] [no-transport]
type is the spawnable type of the agent. targets is the number of agents to spawn within the targets group that may prompt a greeting. 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). followers is the maximum number of followers that will leave their greeting area and move with the target.
Terminal 1 (Launch Unreal)
cd <Your UnrealGAMS client directory>
./UnrealGAMS.shTerminal 2 (Launch GAMS Controller)
cd $GAMS_ROOT/scripts/simulation/unreal/greet
./run_rectangle.sh quad 1 30 ntJoystick creates a GAMS-enabled agent that interacts with an XBox controller (primarily) or some other agent that registers with the Linux joystick interface (/event/js*). Using the axis or buttons will trigger the agent to move or interact in an intuitive way while also updating GAMS variables such as location and orientation for the agent, so other agents can interact with a human-controlled agent.
Youtube Videos
Arguments
./run_joystick.sh [scriptfile=init.mf] [agent id=0] [num agent controllers=1]
scriptfile is the name of the script to use one startup. It is recommended that you use the default init.mf in the script directory. agent id is the identifier of the first agent you spawn (i.e., 1 for agent.1). num agent controllers is the number of agents to spawn.
Terminal 1 (Launch Unreal)
cd <Your UnrealGAMS client directory>
./UnrealGAMS.shTerminal 2 (Launch GAMS Controller)
cd $GAMS_ROOT/scripts/simulation/unreal/joystick
./run_joystick.sh init.mf 0 2 ntThe Move algorithm is a typical Waypoints algorithm. The scripts in the simulation directory do not really use collaborative AI but are instead greedy, self-interested agents (if they even have any concept of self) that move wherever they please.
Youtube Videos
Arguments
./run_20m_square.sh [type] [num agents] [no-transport]
./run_return.sh [type] [num agents] [no-transport]
./run_line.sh [type] [num agents] [no-transport]
./run_stop.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.shTerminal 2 (Launch GAMS Controller)
cd $GAMS_ROOT/scripts/simulation/unreal/move
./run_line.sh quad 20 ntThe spawn scripts will create an arbitrary number of agents within the Unreal environment. This is a useful starter script if you just want to spawn a certain number of agents and then run other scripts.
Youtube Videos
Arguments
./spawn.sh [type=quad] [num agents=1] [starting id=0] [no-transport]type is the spawnable type of the agent. num agents is the number of agents to spawn. id is the starting agent id. 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.shTerminal 2 (Launch GAMS Controller)
cd $GAMS_ROOT/scripts/simulation/unreal/spawn
./run_line.sh quad 250 0 nt
./run_line.sh quad 250 250 nt
./run_line.sh quad 250 500 ntThe Spell algorithm creates a synchronous model of computation between a swarm of agents to spell words that humans can read. This algorithm is interesting in that it can be paired with the MADARA plotting capabilities to show visualizations of agent activities. Spell creates a SMoC between 3 agents per letter, who form their own clique to spell arbitrarily long phrases at 3 agents per letter. Each letter is robust to communication outages across the swarm, making it a fun algorithm that can be deployed in sims or real-world robotics.
Youtube Videos
Arguments
./run_spell.sh [text='hello'] [no-transport]
./plot.sh [num letters=6]text is the phrase you want to spell. letters is the number of letters you need to graph in the plotter (to use plot.sh, you need to compile MADARA with python support--e.g., $GAMS_ROOT/scripts/linux/base_build.sh madara gams python. 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.shTerminal 2 (Launch GAMS Controller)
cd $GAMS_ROOT/scripts/simulation/unreal/spell
./spell.sh gamsuser ntTerminal 3 (Launch MADARA plotter)
cd $GAMS_ROOT/scripts/simulation/unreal/spell
./plot.sh 8