SCRIMMAGE is a multi-agent simulator for robotics research. It has been used to conduct studies in multi-agent task assignment, differential game theory, novel controllers, and reinforcement learning.
If you use SCRIMMAGE in your research, please cite our research paper:
@inproceedings{demarco2018,
title={Simulating Collaborative Robots in a Massive Multi-Agent Game Environment ({SCRIMMAGE})},
author={DeMarco, Kevin and Squires, Eric and Day, Michael and Pippin, Charles},
booktitle={Int. Symp. on Distributed Autonomous Robotic Systems},
year={2018},
}
SCRIMMAGE developers and users may use multiple scrimmage-related projects and repositories. Thus, it is recommended to group your scrimmage-related projects under a single directory, but it is not necessary. To create a directory to hold your scrimmage projects and clone this scrimmage repo, run the following commands:
mkdir -p ~/scrimmage && cd ~/scrimmage
git clone https://github.com/gtri/scrimmage.git
A list of the Ubuntu packages required is provided in ./setup/install-binaries.sh in the "DEPS_DPKG" array. Run our automated installer to install the required packages:
cd scrimmage
sudo ./setup/install-binaries.sh [--external] [--python <version>]
If the first option --external is passed, the script only installs what is necessary for an external build (see EXTERNAL flag to project CMakeLists.txt). The second argument --python <version> selects the version of python for which to install dependencies. Supported values for <version> are "2", "3", and "a", with "a" installing dependencies for both python 2 and 3. This option defaults to "a" if no valid version is specified.
sudo apt install libgrpc++-dev
(optional) sudo ln -s usr/bin/python3 usr/bin/python
Some of SCRIMMAGE's dependencies have to be custom built from source. We provide debian package binaries for both Ubuntu 16.04 (xenial) and 18.04 (bionic) via the SCRIMMAGE PPA on Launchpad for these custom built packages. For Ubuntu 16.04 (xenial) and 18.04 (bionic), and 20.04 (focal) add the following PPA to your apt-get sources:
sudo add-apt-repository ppa:kevin-demarco/scrimmage
For both distributions, update your sources list:
sudo apt-get update
Now, install the SCRIMMAGE custom built binary dependencies:
sudo apt-get install scrimmage-dependencies scrimmage-jsbsim
Run the SCRIMMAGE setup script, which adds the ~/.scrimmage directory to your local system and sets up some environment variables:
source /opt/scrimmage/*/setup.sh
Note: If you need to build the dependencies from source or generate binary packages, see Build Dependencies from Source
mkdir build && cd build
cmake ..
make
source ~/.scrimmage/setup.bash
Whenever you want to use scrimmage, you need to source the ~/.scrimmage/setup.bash file or you can place a line in your ~/.bashrc file to source it automatically:
echo "source ~/.scrimmage/setup.bash" >> ~/.bashrc
Open a new terminal, change to the scrimmage directory, and execute a mission.
cd </path/to/>scrimmage
scrimmage ./missions/straight.xml
You should see the visualization GUI open up and display the simulation.
The GUI responds to the following input keys:
'q' : Quit the simulation
'b' : (Break) Pauses and unpauses the simulation.
'space bar' : When paused, take a single simulation step.
'a' : Rotate through the camera views
'right/left arrows' : Change the aircraft to follow
'[' : Decrease simulation warp speed
']' : Increase simulation warp speed
'+' : Increase visual scale of all entities
'-' : Decrease visual scale of all entities
'r' : Reset visual scale and reset camera position
'z' : Zoom out from entity
'Z' : Zoom in to entity (z+shift)
'w' : Display wireframe
's' : Display solids (vs. wireframe)
'CTRL + Left Click' : Rotate world
'SHIFT + Left Click' : Translate camera through world
The GUI's camera can operate in three modes (cycle with 'a' key):
- Follow the entity and point towards the entity's heading
- Free floating camera
- Follow the entity from a fixed viewpoint
Note: If all of the terrain data does not appear, click on the GUI window with your mouse.
Support for macOS has been deprecated. Refer here for legacy homebrew instructions, but this is not guaranteed to build without intervention from the user. Any user wishing to develop on macOS is free to do so and make pull requests for patches, but the platform is no longer supported by SCRIMMAGE core developers.
It is recommended to build scrimmage's Python bindings in a python virtual environment:
cd /path/to/scrimmage
sudo apt-get install python3 libpython3-dev python3-venv
python3 -m venv env
source ./env/bin/activate
Install the python dependencies with specific version numbers:
(env)$ pip install -r ./python/requirements.txt
Re-build the scrimmage project within the virtual environment:
(env)$ cmake .. -DPYTHON_MIN_VERSION=3.6
(env)$ make
Scrimmage's cmake build procedures will choose the environment
default Python in its configuration process when running
plain cmake ... To specify a specific minimum version of Python
to be used, use the cmake .. -DPYTHON_MIN_VERSION=2.7 flag during
the cmake process.
To install scrimmage's python bindings:
(env)$ cd /path/to/scrimmage/python
(env)$ python setup.py develop
cd build
cmake .. -DBUILD_DOCS=ON
make docs
firefox ./docs/doxygen/html/index.html
firefox ./docs/sphinx/html/index.html
cmake .. -DBUILD_TESTS=ON
make
make test
The scrimmage source code can be cleaned with the standard clean command:
make clean
However, if you want to clean everything, you can remove your build directory:
cd /path/to/scrimmage && rm -rf build
To build SCRIMMAGE's ROS plugins, you must have
ROS installed, the ROS environment
sourced, and the BUILD_ROS_PLUGINS cmake variable must be set:
sudo apt-get install ros-${ROS_VERSION}-desktop-full ros-${ROS_VERSION}-mavros-msgs
source /opt/ros/${ROS_VERSION}/setup.sh
cmake .. -DBUILD_ROS_PLUGINS=ON
The ${ROS_VERSION} should be substituted with an appropriate ROS version
(e.g., "kinetic", "melodic", etc.).
An example of using SCRIMMAGE to simulate robots running the ROS 2D Navigation stack can be found in the scrimmage_ros package.
If you want to use MOOS with SCRIMMAGE, you will first need to download and build MOOS/MOOS-IVP according to the instructions at: https://oceanai.mit.edu/moos-ivp/pmwiki/pmwiki.php?n=Site.Download
The MOOSAutonomy plugin interacts with the MOOSDB to synchronize time, exchange contact information, and receive desired state from the IvP Helm. To build MOOSAutonomy, you have to provide cmake with the path to the moos-ivp source tree:
cmake .. -DMOOSIVP_SOURCE_TREE_BASE=/path/to/moos-ivp
If you want to use FGMS with SCRIMMAGE, you will first need to download and build FGMS according to the instructions at: https://github.com/FlightGear/fgms
Clone the flight gear multiplayer server repository and build it:
git clone https://github.com/FlightGear/fgms.git
cd fgms
git checkout 6669ac222b9f6ca34b0d56ba1bc6cac9cc0324b2
mkdir build && cd build
cmake .. -DBUILD_SHARED_LIB=ON
make
The FGMS plugin interacts with SCRIMMAGE to receive the state variables of each entity. To build FGMS, you have to provide SCRIMMAGE's CMake project the path to the FGMS root source:
cmake .. -DFGMS_SOURCE_TREE_BASE=/path/to/fgms
The SCRIMMAGE docker image is pushed to a public repository after a successful build on Travis. If docker is installed on your machine, you can obtain the SCRIMMAGE docker image by running the following command:
docker pull syllogismrxs/scrimmage:latest
You can pass mission files from your host machine to the scrimmage executable
inside of the docker container with the following command:
cd /path/to/scrimmage/missions
docker run --name my-scrimmage \
-v ${PWD}/straight_jsbsim.xml:/straight_jsbsim.xml \
syllogismrxs/scrimmage:latest /straight_jsbsim.xml
The previous command mounts the straight_jsbsim.xml mission file on your host
machine into the scrimmage container and then the /straight_jsbsim.xml
portion at the end of the command overwrites the default docker CMD, which is
defined in the Dockerfile. Finally, the scrimmage executable is passed the
/straight_jsbsim.xml mission file.
Since we provided a name for our container, we can easily extract the SCRIMMAGE log files from the docker container:
docker cp my-scrimmage:/root/.scrimmage/logs .
If you need to drop into a shell inside of the scrimmage container, you will need to overwrite the docker image's ENTRYPOINT.
docker run -it --entrypoint="/bin/bash" syllogismrxs/scrimmage:latest
Once inside of the container, you will need to source the setup.bash file
manually before running a mission.
source ~/.scrimmage/setup.bash
scrimmage ./missions/straight-no-gui.xml
This repository contains a Dockerfile that builds a compiler with C++14
support, SCRIMMAGE's dependencies, and SCRIMMAGE for CentOS6 or RedHat6. RPMs
are built inside of the docker image and they can be extracted and install on a
CentOS or RedHat system. The user can change the package install prefix for all
RPMs by specifying the PKG_PREFIX docker build argument. Building the docker
image can take several hours:
cd /path/to/scrimmage/ci/dockerfiles
docker build --build-arg PKG_PREFIX=/opt/scrimmage \
--tag scrimmage/centos6:latest \
--file centos6 .
Extract the RPMs that were built to the host's rpms folder:
docker create --name mycontainer scrimmage/centos6:latest
docker cp mycontainer:/root/rpms ./rpms # extract the rpms
docker rm mycontainer # clean up container
Copy the rpms folder to your CentOS or RedHat system and install the run-time
dependencies:
cd /path/to/rpms
rpm -ivh scrimmage_gcc*.rpm \
scrimmage_python*.rpm \
scrimmage_boost*.rpm \
scrimmage_geographiclib*.rpm \
scrimmage_jsbsim*.rpm \
scrimmage_grpc*.rpm \
scrimmage_protobuf*.rpm \
scrimmage_0.2.0*.rpm
To test that SCRIMMAGE was installed correctly, run the following command:
export JSBSIM_ROOT=/opt/scrimmage/etc/JSBSim \
&& source /opt/scrimmage/etc/scrimmage/env/scrimmage-setenv \
&& scrimmage /opt/scrimmage/share/scrimmage/missions/straight-no-gui.xml
Instructions modified from: https://scidom.wordpress.com/2012/01/18/sge-on-single-pc/ https://www.bu.edu/tech/support/research/system-usage/running-jobs/tracking-jobs/
Install Grid Engine:
sudo apt-get install gridengine-master gridengine-exec \
gridengine-common gridengine-qmon gridengine-client
Note that you can configure how qsub is called with a .sge_request in your
home directory. Further, you can set the number of available slots (cores
available) when running grid engine under the Queue Control tab.
Install PostgreSQL and configure the database scrimmage, create user scrimmage with password scrimmage, and add that user to the scrimmage database:
sudo apt-get install postgresql postgresql-contrib
sudo update-rc.d postgresql enable &&\
sudo service postgresql restart &&\
sudo -u postgres createdb scrimmage &&\
sudo -u postgres psql -c "CREATE USER scrimmage with password 'scrimmage';" &&\
sudo -u postgres psql -c "alter user scrimmage with encrypted password 'scrimmage'" &&\
sudo -u postgres psql -c "grant all privileges on database scrimmage to scrimmage;"
Go into /etc/postgresql/9.5/main/pg_hba.conf (or similar path to your postgres install) and change the line:
local all all peer
to
local all all md5
Then run:
sudo service postgresql restart
This will allow us to authenticate the scrimmage user on postgres with the password scrimmage that we created.
To use the python scripts for pulling .csv files to postgres, install psycopg2, the python interface for postgres:
pip install psycopg2
The scripts are located in the scripts directory.
There are some OpenGL issues with VTK6 in Virtualbox. To run SCRIMMAGE in VirtualBox with VTK5, run the following commands:
sudo apt-get install libvtk5-dev
cd ~/scrimmage/scrimmage/build # Note: Path may vary
cmake ..
At this point, cmake should output a message about finding VTK Version 5. Now, you have to rebuild SCRIMMAGE:
make
Make sure that when you run the cmake command it is using the version of python that you want to use with the following:
cmake -DPYTHON_EXECUTABLE:FILEPATH=/usr/bin/python \ # adjust path to your needs
-DPYTHON_INCLUDE_DIR:PATH=/usr/include/python2.7 \ # adjust path to your needs
-DPYTHON_LIBRARY:FILEPATH=/usr/lib/libpython2.7.so # adjust path to your needs
When running cmake, the user gets the cmake warning:
-- The imported target "vtkRenderingPythonTkWidgets" references the file
"/usr/lib/x86_64-linux-gnu/libvtkRenderingPythonTkWidgets.so"
but this file does not exist. Possible reasons include:
* The file was deleted, renamed, or moved to another location.
* An install or uninstall procedure did not complete successfully.
* The installation package was faulty and contained
"/usr/lib/cmake/vtk-6.2/VTKTargets.cmake"
but not all the files it references.
This is a VTK6 Ubuntu package bug. It can be ignored.
SCRIMMAGE uses vtkGeoJSONReader to load polygon extrusion data from a GeoJSON file. This VTK feature was added in VTK7. Since this feature is not available in older versions, SCRIMMAGE does not load building data if the installed VTK version is less than 7. Therefore, the remedy is to upgrade VTK. To install VTK7 on Ubuntu, run the following command:
sudo apt-get install libvtk7-dev
Docker can have DNS issues. If you can ping a public ip address within a docker image (such as 8.8.8.8), but you can't ping archive.ubuntu.com, create the file /etc/docker/daemon.json with the following contents:
{
"dns": ["<DNS-IP>", "8.8.8.8"]
}
Where <DNS-IP> is the first DNS IP address and is a network
interface with internet access from the commands:
nmcli dev list | grep 'IP4.DNS' # Ubuntu <= 14
nmcli device show <interfacename> | grep IP4.DNS # Ubuntu >= 15
Restart docker:
sudo service docker restart