This page describes each of the items involved in running a Gazebo simulation.
The world description file contains all the elements in a simulation, including robots, lights, sensors, and static objects. This file is formatted using SDF (Simulation Description Format), and typically has a
The Gazebo server (
gzserver) reads this file to generate and populate a world.
A number of example worlds are shipped with Gazebo. These worlds are installed in
you can also see them in the source code.
A model file uses the same SDF format as world files, but should only contain a single
<model> ... </model>. The purpose of these files is to facilitate model reuse, and simplify world files. Once a model file is created, it can be included in a world file using the following SDF syntax:
<include> <uri>model://model_file_name</uri> </include>
A number of models are provided in the online model database (in previous versions, some example models were shipped with Gazebo). Assuming that you have an Internet connection when running Gazebo, you can insert any model from the database and the necessary content will be downloaded at runtime.
Read more about model files here.
Gazebo uses a number of environment variables to locate files, and set up communications between the server and clients. Default values that work for most cases are compiled in. This means you don't need to set any variables.
Here are the variables:
GAZEBO_MODEL_PATH: colon-separated set of directories where Gazebo will search for models
GAZEBO_RESOURCE_PATH: colon-separated set of directories where Gazebo will search for other resources such as world and media files.
GAZEBO_MASTER_URI: URI of the Gazebo master. This specifies the IP and port where the server will be started and tells the clients where to connect to.
GAZEBO_PLUGIN_PATH: colon-separated set of directories where Gazebo will search for the plugin shared libraries at runtime.
GAZEBO_MODEL_DATABASE_URI: URI of the online model database where Gazebo will download models from.
These defaults are also included in a shell script:
If you want to modify Gazebo's behavior, e.g., by extending the path it searches for models, you should first source the shell script listed above, then modify the variables that it sets.
Gazebo is transitioning to use the Ignition Transport library for inter-process communication instead of the built-in Gazebo Transport library, which will eventually be deprecated. Some functionality already uses Ignition Transport and may be affected by the following environment variables:
IGN_PARTITION: Partition name for all Ignition Transport nodes.
IGN_IP: Similar to
GAZEBO_MASTER_URI, but for Ignition Transport.
IGN_VERBOSE: Show debug information from Ignition Transport.
Read more about Ignition Transport environment variables here.
The server is the workhorse of Gazebo. It parses a world description file given on the command line, and then simulates the world using a physics and sensor engine.
The server can be started using the following command. Note that the server does not include any graphical interface; it's meant to run headless.
<world_filename> can be:
relative to the current directory,
an absolute path, or
relative to a path component in
<world_name> is a world that is installed with Gazebo
For example, to use the
empty_sky.world which is shipped with Gazebo, use the following command
The graphical client connects to a running
gzserver and visualizes the elements. This is also a tool which allows you to modify the running simulation.
The graphical client is run using:
gazebo command combines server and client in one executable. Instead of running
gzserver worlds/empty.world and then
gzclient, you can do this:
Plugins provide a simple and convenient mechanism to interface with Gazebo. Plugins can either be loaded on the command line, or specified in an SDF file (see the SDF format).
Plugins specified on the command line are loaded first, then plugins specified in the SDF files are loaded. Some plugins are loaded by the server, such as plugins which affect physics properties, while other plugins are loaded by the graphical client to facilitate custom GUI generation.
Example of loading a system plugin via the command line:
gzserver -s <plugin_filename>
-s flag indicates it is a system plugin, and
<plugin_filename> is the
name of a shared library found in
For example, to load the
RestWebPlugin that ships with Gazebo:
gzserver --verbose -s libRestWebPlugin.so
The same mechanism is used by the graphical client, the supported command line flags are the following:
-gto load a GUI plugin
--gui-client-pluginto load a GUI plugin
For example, to load the
gzclient --gui-client-plugin libTimerGUIPlugin.so
For more information refer to the plugins overview page.