Scene Configuration Settings¶

The scene config JSONC file specifies the settings for the scene’s actors, clock, and other scene-level settings.

The scene is loaded from the JSONC file that is specified when the World object is initialized in the client script. The client can also reload a specified scene config file through an API call while the simulation is running.

Main scene configuration¶

scene_basic_drone.jsonc

{
  "id": "SceneBasicDrone",
  "actors": [...],
  "environment-actors": [...],
  "environment-objects": [...],
  "clock": {...},
  "home-geo-point": {...},
  "segmentation": {...},
  "scene-type": "UnrealNative"
}

Parameter	Value	Description
`id`	string	Name identifier for the scene (simulation world).
`actors`	array of Actor settings	Actor settings for each actor to spawn in the scene.
`environment actors`	array of Environment actor settings	Environment actor settings for each actor to spawn in the scene.
`environment objects`	array of Environment object settings	Environment object settings for each object to spawn in the scene.
`clock`	Clock settings	Simulation clock settings.
`home-geo-point`	Home GeoPoint settings	GeoPoint coordinates (latitude, longitude, altitude) corresponding to the scene origin.
`segmentation`	Segmentation ID settings	Segmentation ID settings for automatically assigning segmentation IDs to objects in the scene.
`scene-type`	string	(Optional) Use ‘CustomGIS’ if you are running a geospecific GIS scenario. Defaults to ‘UnrealNative’ for non-GIS scenes.
`tiles-dir`	string	(Optional) Local path containing the GIS tiles used when `scene-type` is set as `CustomGIS`.
`tiles-altitude-offset`	float	(Optional) Our tiles have altitude values of WGS84 ellipsoidal height. Sometimes other altitude models are preferred, so you can use this setting to offset the tiles by the provided value in meters. Most GIS software use a geoid relative altitude, so you can query the geoid height at some coord and enter it here: https://geographiclib.sourceforge.io/cgi-bin/GeoidEval
`tiles-lod-max`	integer	(Optional) Maximum level of detail for tiles. Default is 19. Maximum allowed is 23.
`tiles-lod-min`	integer	(Optional) Minimum level of detail for tiles. Default is 13. Minimum allowed is 13.

Actor settings¶

"actors": [
  {
    "type": "robot",
    "name": "Drone1",
    "origin": {
      "xyz": "109.05 -7.5 -19.42", // or "geo-point": "33.047329 -97.292618 4.5"
      "rpy-deg": "0 0 0"
    },
    "robot-config": "robot_quadrotor_fastphysics.jsonc",
    "start-landed": true
  },
  ...
]

Parameter	Value	Description
`type`	`robot`	Type of actor, currently only `robot` is supported.
`name`	string	Name identifier for the actor.
`origin`: `xyz`	string of 3 floats	Spawning origin position “X Y Z” coordinates with units of SI meters in the NED frame (up = negative z). Note: “0 0 0” is at the global UE origin, not relative to `PlayerStart`.
`origin`: `geo-point`	string of 3 floats	Alternative to `xyz`. Spawning origin position at “lat lon alt” coordinates.
`origin`: `rpy`	string of 3 floats	Spawning origin orientation “Roll Pitch Yaw” angles with units of SI radians with right-hand rotation around the NED frame X Y Z axes.
`robot-config`	string	Filename for JSONC config file for this actor’s Robot Configuration Settings.
`start-landed`	bool	(Optional) Start from a manually-set landed state at the spawned origin (without needing to drop onto a mesh with collision). For FastPhysics, a landed state means that the position is locked until a net vertical force up exceeds the weight of the body (to counter gravity forces) such as from rotors during takeoff, or there is already an upward velocity. Defaults to false if omitted.

Environment actor settings¶

"environment-actors": [
  {
    "type": "env_car",
    "name": "car1",
    "origin": {
      "xyz": "3.0 0.0 -5.0",
      "rpy-deg": "0 0 0"
    },
    "env-actor-config": "env_actor_car.jsonc"
  },
  ...
]

Parameter	Value	Description
`type`	`env_actor`, `env_car`, `env_human`	Types of environment actors: `env_actor` is for generic environment actors, `env_car` for cars, `env_human` for humans.
`name`	string	Name identifier for the actor.
`origin`: `xyz`	string of 3 floats	Spawning origin position “X Y Z” coordinates with units of SI meters in the NED frame (up = negative z). Note: “0 0 0” is at the global UE origin, not relative to `PlayerStart`.
`origin`: `geo-point`	string of 3 floats	Alternative to `xyz`. Spawning origin position at “lat lon alt” coordinates.
`origin`: `rpy`	string of 3 floats	Spawning origin orientation “Roll Pitch Yaw” angles with units of SI radians with right-hand rotation around the NED frame X Y Z axes.
`env-actor-config`	string	Filename for JSONC config file for this actor’s Environment Actor Configuration Settings.

Environment object settings¶

"environment-objects": [
  {
    "type": "env_particle_effect",
    "name": "fire1",
    "origin": {
      "xyz": "3.0 0.0 -5.0",
      "rpy-deg": "0 0 0"
    },
    "env-object-config": "env_particle_effect_nfire_02.jsonc"
  },
  ...
]

Parameter	Value	Description
`type`	`env_particle_effect`	Types of environment objects: `env_particle_effect` like fire and smoke assets.
`name`	string	Name identifier for the environment object.
`origin`: `xyz`	string of 3 floats	Spawning origin position “X Y Z” coordinates with units of SI meters in the NED frame (up = negative z). Note: “0 0 0” is at the global UE origin, not relative to `PlayerStart`.
`origin`: `geo-point`	string of 3 floats	Alternative to `xyz`. Spawning origin position at “lat lon alt” coordinates.
`origin`: `rpy`	string of 3 floats	Spawning origin orientation “Roll Pitch Yaw” angles with units of SI radians with right-hand rotation around the NED frame X Y Z axes.
`env-object-config`	string	Filename for JSONC config file for this object’s Environment Object Configuration Settings.

Clock settings¶

"clock": {
  "type": "steppable",
  "step-ns": 3000000,
  "real-time-update-rate": 3000000,
  "pause-on-start": false
}

Parameter	Value	Description
`type`	`steppable`, `real-time`	Type of simulation clock. Defaults to `steppable` if omitted.
`step-ns`	integer	Step size in nanosec for `steppable` clock. Defaults to 20000000 (20 ms) if omitted.
`real-time-update-rate`	integer	Real-time execution period in nanosec between each simulation loop and clock update for all clock types. Defaults to 3000000 (3 ms) if omitted.
`pause-on-start`	bool	Flag to start with simulation paused for `steppable` clock. Defaults to false if omitted.

There are 2 supported simulation clock types:

Steppable clock
Real-time clock

See below for example of how to configure each type of simulation clock.

Steppable clock¶

"clock": {
  "type": "steppable",
  "step-ns": 3000000,
  "real-time-update-rate": 3000000,
  "pause-on-start": false
}

Steppable clock is a fixed-step clock with sim time step = step-ns nanosecs that is stepped every execution period set by real-time-update-rate real-time nanosecs.

For example, with step-ns = 3 ms and real-time-update-rate = 3 ms, the sim clock will advance by exactly 3 ms every execution period, which is also every ~3 ms so the simulation will appear to move at ~1x real-time but with deterministic fixed time steps.

With step-ns = 6 ms and real-time-update-rate = 3 ms, the sim clock will advance by exactly 6 ms every execution period, which is still 3 ms so the simulation will appear to move at ~2x faster than real-time.

The pause-on-start option allows the simulation to start paused to allow full-manual control of the time step advancement through the clock APIs.

Real-time clock¶

"clock": {
  "type": "real-time",
  "real-time-update-rate": 3000000
}

Real-time clock is a variable-step clock with sim time step = real-time step between each execution period set by real-time-update-rate real-time nanosecs. Since the real-time step between each execution period varies slightly by the system clock, the sim time step will also have variations.

Note: Since real-time clock follows real-time advancement, it can not be paused and is not deterministic or repeatable. In order to do the simulation at a scaled multiple of real-time, use a steppable clock with the desired ratio set between step-ns and real-time-update-rate as described in the Steppable clock section.

Home GeoPoint settings¶

"home-geo-point": {
  "latitude": 47.641468,
  "longitude": -122.140165,
  "altitude": 122.0
}

Parameter	Value	Description
`latitude`	float	Latitude coordinate of the scene origin.
`longitude`	float	Longitude coordinate of the scene origin.
`altitude`	float	Altitude value of the scene origin in SI meters (positive values are higher, not NED).

The home GeoPoint is used to correlate the simulation scene origin to a position on Earth to use as a reference point for GPS sensor values and for physics calculations such as air temperature, pressure, etc.

The default value is set for the Microsoft Building 99 parking garage in Redmond, WA, but a new desired location’s latitude/longitude values can be easily looked up by right-clicking anywhere on Bing maps.

Segmentation settings¶

"segmentation": {
  "initialize-ids": true,
  "ignore-existing": false,
  "use-owner-name": true
}

Parameter	Value	Description
`initialize-ids`	bool	Flag to initialize the segmentation ID for the scene objects at simulation start. Defaults to `false` if omitted to reduce sim startup time.
`ignore-existing`	bool	Flag to ignore any existing segmentation IDs already set and initialize them for everything. Defaults to `false` if omitted.
`use-owner-name`	bool	Flag to use each mesh component’s owner’s name (usually the actor name) instead of the mesh component’s name for hashing the segmentation ID. Defaults to `true` if omitted.

The segmentation IDs can be set on scene objects of class UStaticMeshComponent, USkinnedMeshComponent, and ALandscapeProxy, including any derived classes (instanced static meshes, etc). The IDs are set using Unreal’s CustomDepth Stencil parameter so that the object can be rendered with all pixels set to the RGB color that is mapped to the segmentation pallet based on its segmentation ID.

The segmentation ID (CustomDepth Stencil value) can be set manually on objects using the Unreal Editor, or using the client’s world API SetSegmentationIDByName. To get the existing segmentation ID of an object, you can use the client’s world API GetSegmentationIDByName.

To have the segmentation IDs automatically assigned at the start of simulation, set initialize-ids to true. If ignore-existing is set false, then any object that has already been manually assigned an ID (the CustomDepth Stencil rendering is already enabled on the object) will keep its original value. Otherwise, all objects will get reassigned segmentation IDs that are calculated by a hash method based on the sum of the chars in the name (lowercased and ignoring number/symbol chars) and then modulo 256 to get an ID in the allowed range of 0~255. If use-owner-name is true, the name used for this hash will be the mesh object’s owner’s name (ex. the StaticMeshActor’s name that contains the StaticMeshComponent that will be assigned the ID). Using the owner’s name may provide better grouping of the IDs and uses the names that are readable in the Editor’s object tree.

To find out what object names were assigned what segmentation ID, check the simulation server log’s output for InitSegmentationID lines, such as:

[2020.08.13-15.20.45:719] [InitSegmentationID] seg_id:  95, seg_name: 'cylinder8'
[2020.08.13-15.20.45:720] [InitSegmentationID] seg_id:  95, seg_name: 'cylinder_2'
[2020.08.13-15.20.45:720] [InitSegmentationID] seg_id: 148, seg_name: 'ground'
[2020.08.13-15.20.45:720] [InitSegmentationID] seg_id:   0, seg_name: 'templatecube_48'
[2020.08.13-15.20.45:720] [InitSegmentationID] seg_id: 241, seg_name: 'templatecube_rounded_1'
...