simforge scenario

Reference for simforge scenario: usage, arguments and flags, generated from the CLI.

Generated from the CLI’s own help (CLI 0.2.0-rc.5). Global flags and exit codes are on the command reference.

scenario actors

The built-in actors operations place: class, dimensions, ego and static eligibility

simforge scenario actors [OPTIONS]

scenario apply add-actor

Place a new actor: a road vehicle on a semantic lane or before a junction movement, or a pedestrian/free static actor at a scene point.

simforge scenario apply <FILE> add-actor [OPTIONS] --catalog-id <CATALOG_ID> --id <ID> <--lane-rsl <LANE_RSL>|--x <N>|--movement-rsl <MOVEMENT_RSL>> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--before-m N		With movementRsl: distance before the junction (default 40). [1..500 m]
--body-color BODY_COLOR		Presentation body colour #rrggbb.
--catalog-id CATALOG_ID	required	Built-in actor (simforge scenario actors): vehicle.sedan, pedestrian.adult, …
--heading-rad N		Heading in the scene frame; default: the lane heading or the actor class default. [rad]
--id ID	required	New actor id (never allocated implicitly).
--label LABEL		Display label.
--lateral-m N		Lateral offset in the lane, positive to the left of travel. [m]
--opposing		Snap to the nearest genuinely opposing lane.
--overlap-override		Accept overlap with another actor (free/static actors only; refused for moving road vehicles).
--speed-kph N		Initial speed; default: posted limit for road vehicles. [0..160 km/h]
--static		Place as a static actor (no motion, zero speed).
--y N		Explicit height; otherwise the map ground at (x,z) is used and refused without ground. [m]
--lane-rsl LANE_RSL		Semantic lane road:section:lane (with s).
--s N		Metres along laneRsl in its direction of travel, from where traffic enters it: the same s a location’s anchor.road.s and a crossing approach’s stopS report. [>= 0 m]
--x N		Scene-frame x (east). [m]
--z N		Scene-frame z (minus north). [m]
--movement-rsl MOVEMENT_RSL		A junction movement’s connecting lane (a junction_movement location’s anchor.road.rsl): place the actor beforeM up its approach and turn it through that movement.

scenario apply add-encounter

Add an actor that meets the target (the ego by default) the way —kind says, placed and timed from the road graph: lead-brake, slow-lead, stopped, cut-in, crossing, oncoming, cross-traffic, reversing, pull-out, u-turn.

simforge scenario apply <FILE> add-encounter [OPTIONS] --id <ID> --kind <KIND> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--at-s N		Clip time of the moment: lead-brake brake start (default 3), cut-in lane-change start (3), crossing time on the target’s lane (4), reversing start (1), pull-out start (2). [>= 0 s]
--catalog-id CATALOG_ID		Built-in actor; default vehicle.sedan (box truck for reversing, pedestrian.adult for crossing).
--decel-mps2 N		lead-brake deceleration (default 5.5, a hard stop that stays within comfort checks). [0.5..12 m/s²]
--gap-m N		Centre-to-centre distance ahead of the target: at the start (lead-brake 20, slow-lead 30, stopped 25, reversing 25, pull-out 30, u-turn 25) or when the cut-in starts (7). [0..500 m]
--id ID	required	New actor id.
--kind KIND	required; one of lead-brake, slow-lead, stopped, cut-in, crossing, oncoming, cross-traffic, reversing, pull-out, u-turn	lead-brake: ahead in the target’s lane, brakes to a stop at atS. slow-lead: ahead, slower. stopped: standing ahead in the lane. cut-in: from the lane on the target’s side, into its lane from atS, starting gapM in front. crossing: a pedestrian on the target’s path at atS (or at x,z), ttcS before the target. oncoming / cross-traffic: a car on the opposite / a crossing approach of a junction ahead crosses its path ttcS before it (the first junction whose movement enters within 30° of straight against / square to the target’s heading, else the nearest to it). reversing: standing ahead, reverses toward the target from atS. pull-out: parked at the side edge of the target’s lane gapM ahead, pulls into the lane at atS. u-turn: ahead in the target’s lane gapM ahead, makes a U-turn at the first place it can (a mapped U-turn movement, else a path through a junction or across a road wide enough).
--side SIDE	one of left, right	cut-in: the target’s side the car comes from (required). crossing: the side the pedestrian starts on (default right). pull-out: the lane edge the car is parked at (default right).
--speed-kph N		The new actor’s speed: lead-brake the target’s, slow-lead half of it, cut-in 10 faster, crossing walk 4.5, oncoming/cross-traffic the posted limit, reversing 6, pull-out 20, u-turn the target’s within 15-30. [0..160 km/h]
--target TARGET		The actor the encounter is with: a moving road vehicle on a lane. (default “ego”)
--ttc-s N		crossing, oncoming, cross-traffic: the target’s time to the conflict point when the new actor is on it (crossing default 2, junctions 1.5; negative: after the target). [-10..30 s]
--turn TURN	one of left, right, straight	oncoming / cross-traffic: the new car’s movement through the junction (default straight).
--x N		crossing: a scene point on the target’s path where the pedestrian crosses (a crosswalk), with z; replaces atS. [m]
--z N		crossing: the point’s scene z (minus north). [m]

scenario apply add-lane-change

Add a timed lane change for a mobile lane-bound road actor.

simforge scenario apply <FILE> add-lane-change [OPTIONS] --actor-id <ACTOR_ID> --direction <DIRECTION> --id <ID> --start-s <N> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--actor-id ACTOR_ID	required	Actor.
--direction DIRECTION	required; one of left, right	Target lane side.
--duration-s N		Lane-change duration. [> 0 s] (default 3)
--end-s N		Clip time the event ends. [>= 0 s]
--id ID	required	New event id.
--start-s N	required	Clip time the change starts. [>= 0 s]

scenario apply add-next-junction-turn

Choose the turn an actor takes at its next junction.

simforge scenario apply <FILE> add-next-junction-turn [OPTIONS] --actor-id <ACTOR_ID> --direction <DIRECTION> --id <ID> --start-s <N> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--actor-id ACTOR_ID	required	Actor.
--direction DIRECTION	required; one of left, right, straight	Movement at the next junction.
--end-s N		Clip time the event ends. [>= 0 s]
--id ID	required	New event id.
--start-s N	required	Clip time the choice applies from. [>= 0 s]

scenario apply add-speed-change

Change an actor’s speed from a clip time: brake to a stop, slow down, speed up or start moving.

simforge scenario apply <FILE> add-speed-change [OPTIONS] --actor-id <ACTOR_ID> --id <ID> --start-s <N> --target-kph <N> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--actor-id ACTOR_ID	required	Actor.
--end-s N		Clip time the event ends. [>= 0 s]
--id ID	required	New event id.
--rate-mps2 N		Acceleration or deceleration (default 4, at most the class limit: a car brakes at up to 8, speeds up at up to 3). [0.1..20 m/s²]
--start-s N	required	Clip time the change starts. [>= 0 s]
--target-kph N	required	Speed to reach; 0 brakes to a stop. [0..160 km/h]

scenario apply add-u-turn

Make an actor (the ego too) turn back the way it came at the first place ahead on its route where it can: a junction’s mapped U-turn movement, else a path drawn through a junction or across a road wide enough for its turning circle.

simforge scenario apply <FILE> add-u-turn [OPTIONS] --actor-id <ACTOR_ID> --id <ID> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--actor-id ACTOR_ID	required	A moving road vehicle on a lane.
--id ID	required	New event id.
--movement-rsl MOVEMENT_RSL		A U-turn movement’s connecting lane on the actor’s route (authoring discover —kind movements, turnRelation UTurnLeft/UTurnRight); default: the first place it can turn.

scenario apply duplicate-actor

Copy an actor with its presentation and own events under a new id at a new position.

simforge scenario apply <FILE> duplicate-actor [OPTIONS] --id <ID> --new-id <NEW_ID> <--lane-rsl <LANE_RSL>|--x <N>> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--heading-rad N		Heading in the scene frame; default: the lane heading or the actor class default. [rad]
--id ID	required	Source actor.
--lateral-m N		Lateral offset in the lane, positive to the left of travel. [m]
--new-id NEW_ID	required	New actor id.
--overlap-override		Accept overlap with another actor (free/static actors only; refused for moving road vehicles).
--y N		Explicit height; otherwise the map ground at (x,z) is used and refused without ground. [m]
--lane-rsl LANE_RSL		Semantic lane road:section:lane (with s).
--s N		Metres along laneRsl in its direction of travel, from where traffic enters it: the same s a location’s anchor.road.s and a crossing approach’s stopS report. [>= 0 m]
--x N		Scene-frame x (east). [m]
--z N		Scene-frame z (minus north). [m]

scenario apply move-actor

Move an actor to a lane station or scene point, keeping identity, class, static state and speed.

simforge scenario apply <FILE> move-actor [OPTIONS] --id <ID> <--lane-rsl <LANE_RSL>|--x <N>> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--heading-rad N		Heading in the scene frame; default: the lane heading or the actor class default. [rad]
--id ID	required	Actor to move.
--lateral-m N		Lateral offset in the lane, positive to the left of travel. [m]
--overlap-override		Accept overlap with another actor (free/static actors only; refused for moving road vehicles).
--y N		Explicit height; otherwise the map ground at (x,z) is used and refused without ground. [m]
--lane-rsl LANE_RSL		Semantic lane road:section:lane (with s).
--s N		Metres along laneRsl in its direction of travel, from where traffic enters it: the same s a location’s anchor.road.s and a crossing approach’s stopS report. [>= 0 m]
--x N		Scene-frame x (east). [m]
--z N		Scene-frame z (minus north). [m]

scenario apply remove-role

Delete an actor with dependent events, reasoning and ego handoff.

simforge scenario apply <FILE> remove-role [OPTIONS] --id <ID> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--id ID	required	Actor to delete.

scenario apply set-actor-speed

Set an actor’s initial speed.

simforge scenario apply <FILE> set-actor-speed [OPTIONS] --id <ID> --speed-kph <N> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--id ID	required	Actor.
--speed-kph N	required	Initial speed. [0..160 km/h]

scenario apply set-actor-static

Make an actor static (clears its route and motion events) or mobile again.

simforge scenario apply <FILE> set-actor-static [OPTIONS] --id <ID> --static <BOOL> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--id ID	required	Actor.
--static BOOL	required; one of true, false	true: static; false: mobile.

scenario apply set-clip

Set the clip length and/or warm-up; out-of-clip events are refused, never truncated.

simforge scenario apply <FILE> set-clip [OPTIONS] <--clip-seconds <N>|--warmup-seconds <N>> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--clip-seconds N		Clip length. [3..120 s]
--warmup-seconds N		Warm-up before the clip. [0..30 s]

scenario apply set-clock

Set the precise scene clock; the time of day becomes the label of the sun at the map’s site on the scenario’s day.

simforge scenario apply <FILE> set-clock [OPTIONS] --minutes <N> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--minutes N	required	Minutes after local midnight. [0..1439 min]

scenario apply set-ego

Make an actor the ego vehicle.

simforge scenario apply <FILE> set-ego [OPTIONS] --role-id <ROLE_ID> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--role-id ROLE_ID	required	Actor to make ego.

scenario apply set-event-timing

Retime an event’s start and optional end.

simforge scenario apply <FILE> set-event-timing [OPTIONS] --id <ID> --start-s <N> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--end-s N		End clip time. [>= 0 s]
--id ID	required	Event.
--start-s N	required	Start clip time. [>= 0 s]

scenario apply set-waypoint-route

Give an actor a smooth stop-to-stop timed route through scene points (two points: a crossing).

simforge scenario apply <FILE> set-waypoint-route [OPTIONS] --actor-id <ACTOR_ID> --duration-s <N> --id <ID> --point <X,Z> --start-s <N> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--actor-id ACTOR_ID	required	Actor.
--duration-s N	required	Route duration. [> 0 s]
--end-s N		Clip time the event ends. [>= 0 s]
--id ID	required	New event id.
--point X,Z	required; repeatable	Scene points X,Z in metres (x east, z minus north; the height follows the map ground), the actor’s current position first. One --point X,Z per item (comma-separated numbers), at least 2.
--start-s N	required	Clip time the route starts. [>= 0 s]

scenario apply set-weather

Set the scenario weather.

simforge scenario apply <FILE> set-weather [OPTIONS] --weather <WEATHER> [-- [OPERATION]...]

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically)
<operation>	repeatable	Further operations of the same transaction, each after --.
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXT		The transaction’s undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--weather WEATHER	required; one of clear, cloudy, overcast, light_rain, heavy_rain, wet_road, fog_light, fog_dense, snow, sleet	Canonical scenario weather.

scenario check

Full validation on the document’s map (exit 2 per —strictness); —preview also runs every actor on the engine and flags an actor the ego never sees or meets. The installed map’s own findings (mapDiagnostics) never fail it

simforge scenario check [OPTIONS] --strictness <STRICTNESS> <FILE>

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
<file>	required	The scenario document
--strictness STRICTNESS	required; one of errors, warnings	What fails the check (exit 2)
--preview		Also materialize and run every actor on the engine (collisions, quality, input identity)

scenario drive

Run the editor preview’s engine pass over a scenario and report how each road vehicle drove

simforge scenario drive [OPTIONS] <FILE>

Runs on: local runtime.

Argument / flag	Notes	What
<file>	required	The scenario document
--map MAP		Run on this installed map instead of the document’s own
--ambient AMBIENT	one of document, off; default document	Generated traffic
--strict		Exit 2 when any road vehicle has a driving finding

scenario motion

Change how one actor moves: Replay to Follow path (engine-owned speed), Follow path to Behave (lanes)

simforge scenario motion [OPTIONS] --actor <ID> --to <TO> <FILE>

Runs on: local runtime.

Argument / flag	Notes	What
<file>	required	The scenario document (edited in place, atomically, as the next revision)
--actor ID	required	The actor (role id) to convert
--to TO	required; one of follow-path, behave, reset-to-recording	The motion to convert it to
--recording FILE	repeatable	A recording the document pins (plain or gzipped; log-scene/v1 reads as one). Repeatable
--map MAP		Use this installed map instead of the document’s own
--expect-version N		Refuse unless the document is at this revision (stale_version)
--expect-digest SHA256		Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge

scenario new

Create an empty scenario on an installed map (revision 0)

simforge scenario new [OPTIONS] --map <MAP> --out <FILE>

Runs on: local runtime, or hosted with —cloud.

Argument / flag	Notes	What
--map MAP	required	The installed map (simforge maps pull <map>@<version>)
--out FILE	required	Where to write the scenario document
--name NAME	default Untitled scenario	Scenario name
--clip-seconds S	default 20	Clip length, seconds (3 to 120)
--created-at TIME		Creation timestamp YYYY-MM-DDTHH:MM:SS.mmmZ (default: now), for reproducible documents
--force		Overwrite an existing file
--dataset DATASET_ID		The writable dataset the hosted draft goes in; absent, the credential’s default dataset (named in the receipt)

scenario ops list

Every authoring operation: id, command, summary, required map context

simforge scenario ops list [OPTIONS]

scenario ops show

One operation: input and result schemas, flags, applicability and refusal codes

simforge scenario ops show [OPTIONS] <OPERATION>

Argument / flag	Notes	What
<operation>	required	Operation id (addActor) or command (add-actor)

scenario pull

Download a hosted scenario document as a local scenario JSON file

simforge scenario pull [OPTIONS] <ID>

Argument / flag	Notes	What
id	required	The hosted scenario document id
--out OUT		Output file. Default: <ID>.scenario.json
--host HOST		SimForge host. Default: SIMFORGE_HOST, then the host of the last login, then simforge.ai
--force		Overwrite an existing output file
--help		Print help