Mission XML Tag Definitions¶
altitude tags must be used
together or the
z tags must be used together. Do not mix
and match between the two paradigms for a single entity.
run: Defines timing parameters for simulation
start: The start time, should usually be set to 0.0.
end: Final time of simulation, in seconds.
dt: Change in simulation time for each time step, in seconds.
time_warp: Specifies how much slower or faster than real-time that the simulation should run. If set to 1, the simulation runs in real-time. If set to 0, the simulation runs as fast as possible. If set to x, it runs x times faster than real-time. For example, if set to 10, the simulation will run 10 times as fast as real-time. If set to 0.5, the simulation will run half as fast as real-time. It should be noted that this parameter only defines a “best effort.” The autonomy logic can and will slow down the simulation, but the simulation is guaranteed to run deterministically with respect to the
seedXML tag, even if it runs slower than real-time.
enable_gui: If set to
true, the SCRIMMAGE gui will run in parallel with the SCRIMMAGE simulation. If
false, the gui will not run during the simulation.
network_gui: If set to
true, the SCRIMMAGE simulation controller will attempt to connect to a network-based (GRPC) SCRIMMAGE viewer. If
network_guiis set to
enable_guishould be set to
false, so that the shared memory version of the SCRIMMAGE viewer isn’t initialized.
true, the simulation will not start until the user types
binto the gui. This allows the user to ensure that the simulation’s initial conditions are correct before running simulation since the gui can launch after the actual simulation begins execution.
motion_multiplierset to an integer greater than or equal to 1.
If not 1, scrimmage will run controller and motion plugins multiple times for each timestep.
network_guiis enabled, GRPC messages of the positions and orientations of SCRIMMAGE entities will be streamed to this port.
network_guiis enabled, GRPC messages of the positions and orientations of SCRIMMAGE entities will be streamed to this network address (e.g., localhost, 192.168.1.49, etc.)
seed: Used to seed SCRIMMAGE’s random number generator. If not specified or commented out, the current computer time will be used to seed the simulation. In some cases a user will want the scenario to begin deterministically and then proceed randomly. This can be achieved by setting a seed but adding an attribute
reseed_timefor the time in the simulation when the seed should be set to something random. Additionally, if you want the reseed to be deterministic you can set it with the
end_condition: Specifies the conditions for ending the simulation. The possible end conditions are
timeis set, the simulation will automatically end when the time reaches the
endattribute defined in the
one_teamis set, the simulation will end when all entities remaining belong to the same team ID. If
all_deadis set, the simulation will end when there are no more remaining entities. If
noneis set, the simulation will only end when the user closes the gui or if the user “kills” the simulation by typing
CTRL + cin the terminal that launched scrimmage. The end conditions can be OR-ed together by separating the end conditions with commas. For example, if the
end_conditionis set to “time, one_team” the simulation will end if the
endtime is reached or if only a single team is remaining.
terrain: Defines the name of the folder that holds the terrain polygon and texture data. This is typically located at:
grid_spacing: Defines the distance in meters between grid lines when not using the
grid_size: Defines the length in meters of the square grid when not using the
background_color: The visualization background color defined in RED, GREEN, BLUE order.
gui_update_period: The gui update period in milliseconds. Providing a small number increases the gui update rate, but can slow the simulation due to system resources.
true, it will launch the
plot-simtool immediately after the simulation is complete.
output_type: Specifies what artifacts are generated by a simulation run. If set to
framesonly the frames.bin file will be created. If set to
summary, a CSV file of the mission metrics will be created. If set to
git_commits, a hash of the current git project will be created. If set to
all, all the possible artifacts will be created. If set to nothing no output will be created.
true, SCRIMMAGE will print the plugins that were discovered on the SCRIMMAGE_PLUGIN_PATH at simulation start-up. The plugins will be grouped into similar plugin types (e.g. autonomy plugins, motion plugins, interaction plugins, sensors, controllers, etc.)
log_dir: The log directory is the folder where scrimmage will save all log information from the simulation. This includes entity trajectory data, event data, and the random seed that was used during the simulation.
true, a symbolically linked directory named
latestwill be created that links to the most recent
log_dir. This tag is
trueby default. When executing parallel runs, the user should set this to
false, so that multiple instances of SCRIMMAGE do not try to create the same
latitude_origin: This is the latitude (decimal degrees) at which the simulation’s cartesian coordinate system’s origin is centered. (e.g., 35.721025)
longitude_origin: This is the longitude (decimal degrees) at which the simulation’s cartesian coordinate system’s origin is centered. (e.g., -120.767925)
altitude_origin: This is the altitude in meters above sea level at which the simulation’s cartesian coordinate system’s origin is centered.
show_origin: If set to
true, a three axis coordinate system will be drawn at the origin of the simulation. This is help for debugging the latitude, longitude, and altitude origin values.
display_progress: whether to show a progress bar on the command line
origin_length: Specifies the length of the origin axes in meters when
metrics: This tag loads metrics plugins and executes them during the mission. Metrics plugins are executed in the order in which they appear in the mission file. A metrics plugin counts “events” in the simulation and outputs the counts to the summary CSV file.
entity_interaction: This tag loads a plugin that computes interactions between entities during the simulation. For example, the
SimpleCollisionentity interaction plugin computes the distance between all entities and if the distance between any two entities is below a given threshold, the entities are removed from the simulation. The
GroundCollisionentity interaction plugin removes entities from the simulation that are within a given distance from the ground. Entity interaction plugins are executed in the order in which they appear in the mission file.
network: This tag loads a plugin that simulates network communications. This can be used to simulate dropped packets. By default, every SCRIMMAGE simulation initializes a “GlobalNetwork,” which is used to transfer simulation data, such as “EntityGenerated” messages. The “LocalNetwork” only allows transmission of messages between plugins that are attached to the same entity. The “SphereNetwork” is a probabilistic transmission model that is parameterized by communication range. (perfect comms within range or probabilistic comms within a range). Multiple network tags can be specified in a single mission file.
entity: The entity tag is used to initialize a single entity or a swarm of homogeneous entities. The following XML tags should be used within the
name: A human-readable name for this entity block. This name can be used to reference this block later. When running SCRIMMAGE within another system, such as ROS or MOOS, this name is used to reference this entity block.
team_id: The team identification number for this entity group. If multiple entity tags are used to initialize a team of heterogeneous entities, as long as the
team_idis the same, the entities will be on the same team.
color: This is a team color that affects vehicle trail colors and home base colors.
count: The number of entities to create.
generate_rate: The rate (in Hz) at which new entities will be generated. For example “1 / 2” will generate new entities every two seconds.
generate_count: The number of entities that are generated at each time interval. If set to
2, two entities will be generated every generation interval.
generate_start_time: The simulation time at which new entities should start to be generated.
generate_time_variance: This tag is used to add “noise” to the generation interval. The time between launches is modeled to be distributed according to the Gaussian Distribution. All four generate tags have to be defined, otherwise, the generate feature will not work properly. See the sasc.xml mission for an example configuration.
autonomy: This tag assigns an autonomy plugin for each entity in the entity group. Scrimmage searches the SCRIMMAGE_PLUGIN_PATH for an XML file with the autonomy tag’s name. Multiple autonomy plugins can run in serial on a single entity. Autonomy plugins are executed in the order in which they appear in the mission file.
loop_rate: This tag sets the autonomy plugin’s loop_rate in Hz. Scrimmage will attempt to step the plugin at this rate, but cannot step a plugin faster than the simulation itself. If the loop_rate is set faster than the sim, or is set to 0 or a negative number, it will step every time the simulator steps.
health: The initial health points for this entity. The entity interaction plugin can affect the health points of each entity depending on entity messages and the world state. When the health points decrement to zero, the entity is usually removed by the entity interaction plugin.
variance_x: The first entity in an entity group is, by default, initialized at the position determined by the the
altitudetags. Since it can be tedious to specifically initialize large numbers of entities, scrimmage has the ability to randomly initialize an entity group’s starting positions. The
variance_ztags bound the possible starting locations to a cube around the
variance_y: The y-distance around the entity’s initial position for generating entities.
variance_z: The z-distance around the entity’s initial position for generating entities.
use_variance_all_ents: Defaults to
false. This tag, if set to
true, causes the first entity in an entity group to be placed randomly according to the same variances and about the same
altitudepoint as the rest of the entity group.
x: The entity’s initial x-position. The first entity in the entity group is initialized at this x-position, but other entities in the same group are randomly placed around this starting position.
y: The entity’s initial y-position.
z: The entity’s initial z-position.
latitude: The entity’s initial latitude.
longitude: The entity’s initial longitude.
altitude: The entity’s initial altitude.
heading: The entity’s initial heading. Zero-degrees is in the x-axis direction. The heading angle increases in a counter-clockwise direction. This is different from GPS heading, which increases in a clockwise heading. Scrimmage has utilities for easily translating between GPS and cartesian coordinate systems.
motion_model: The motion model or “physics” model that describes the entity’s movement. Scrimmage ships with the following motion models:
SimpleAircraft: An efficient aircraft model that does not allow inverted flight.
SimpleQuadrotor: An efficient quadrotor model that does not allow inverted flight.
JSBSimModel: A high-fidelity aircraft model that allows inverted flight. This plugin ships with an autopilot defined in JSBSim that attempts to prevent inverted flight.
JSBSimControl: A high-fidelity aircraft model that allows direct control of the actuators on the aircraft. This is the model that allows for experimenting with the control of inverted aircraft with realistic physics.
SimpleCar: A simple car model
SingleIntegrator: A single integrator model for experimenting with motion planning.
visual_model: Loads an XML file that specifies the appearance of the entity. Examples: zephyr-blue, zephyr-red, iris, sea-angler, volkswagen.
controller: Loads a low-level controller plugin. Each entity can only have a single controller.
loop_rate: This tag sets the controller plugin’s loop_rate in Hz. See autonomy tag for details.
sensor: Loads a sensor plugin. Multiple sensor plugins can run in serial on a single entity.
loop_rate: This tag sets the sensor plugin’s loop_rate in Hz. See autonomy tag for details.
base: Used to define a “home base” for the entity. Only one home base per team should be specified. Entity groups that share a team ID will share a home base defined in only one entity group. The
basetag has the following tags:
x: The base’s x-position
y: The base’s y-position
z: The base’s z-position
latitude: The base’s latitude
longitude: The base’s longitude
altitude: The base’s altitude
radius: The base’s radius
entity_common: this is a way to share parameters across entity blocks. An
entity_commonblock must have a
nameattribute and can have any entries that an
entityblock can have. For an
entityblock to use what is in the
entity_commonblock, the entity must have an attribute
namematches what is in the attribute for the
param_common: plugins have their own xml files but it can be useful to override their attributes in the main mission file. For instance, one can override the parameter
fooin the main mission file with
<autonomy foo="bar">MyAutonomyPlugin</autonomy>. Regardless of what is in
foowill have a value of
barwhen the plugin is initialized. To abstract this further, plugins can share overriden values with a
param_commonblock needs to have a
nameattribute (similar to
entity_commonblocks). The common block can be referenced as
vehicleis the value given to the attribute
camera: defines camera parameters
follow_id: the entity id for the camera to follow
pos: 3 entry comma separated list of where to put the camera (applicable to
focal_point: 3 entry comma separated list of where to point the camera (applicable to
show_fps: whether to show frames per second on the gui
enable_screenshots: if the tag is set to true, scrimmage will save screenshots at regular intervals. This will slow down performance as the simulation loop will wait for the gui to save the screenshot before proceeding. Note that
enable_guimust be true for this setting to be effective. The
endattributes are specified in seconds.
min_period: how often to save screenshots
start: when to start taking screenshots
end: when to stop taking screenshots.
multi_threaded: allows scrimmage to run in multiple threads if the tag is set to true (default=``false``). The default is for scrimmage to run in a single thread. The attributes are:
num_threads: how many threads to use (
default = 1)
autonomy: whether to enable or disable running autonomy plugins in threads (
default = true)
controller: whether to enable or disable running controller plugins in threads (
default = true)
motion: whether to enable or disable running motion plugins in threads (
default = true)
sensor: whether to enable or disable running sensor plugins in threads (
default = true)