Docs menu

// Command reference

simforge scenario

Generated from the CLI's own help (CLI 0.2.0-rc.9). Global flags and exit codes are on the reference index.

All commands

simforge scenario actors

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

simforge scenario actors [OPTIONS]

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--before-m NWith movementRsl: distance before the junction (default 40). [1..500 m]
--body-color BODY_COLORPresentation body colour #rrggbb.
--catalog-id CATALOG_IDrequiredBuilt-in actor (simforge scenario actors): vehicle.sedan, pedestrian.adult, ...
--heading-rad NHeading in the scene frame; default: the lane heading or the actor class default. [rad]
--id IDrequiredNew actor id (never allocated implicitly).
--label LABELDisplay label.
--lateral-m NLateral offset in the lane, positive to the left of travel. [m]
--opposingSnap to the nearest genuinely opposing lane.
--overlap-overrideAccept overlap with another actor (free/static actors only; refused for moving road vehicles).
--speed-kph NInitial speed; default: posted limit for road vehicles. [0..160 km/h]
--staticPlace as a static actor (no motion, zero speed).
--y NExplicit height; otherwise the map ground at (x,z) is used and refused without ground. [m]
--lane-rsl LANE_RSLSemantic lane road:section:lane (with s).
--s NMetres 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 NScene-frame x (east). [m]
--z NScene-frame z (minus north). [m]
--movement-rsl MOVEMENT_RSLA 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.

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--at-s NClip 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_IDBuilt-in actor; default vehicle.sedan (box truck for reversing, pedestrian.adult for crossing).
--decel-mps2 Nlead-brake deceleration (default 5.5, a hard stop that stays within comfort checks). [0.5..12 m/s²]
--gap-m NCentre-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 IDrequiredNew actor id.
--kind KINDrequired; one of lead-brake, slow-lead, stopped, cut-in, crossing, oncoming, cross-traffic, reversing, pull-out, u-turnlead-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 SIDEone of left, rightcut-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 NThe 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 TARGETThe actor the encounter is with: a moving road vehicle on a lane. (default "ego")
--ttc-s Ncrossing, 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 TURNone of left, right, straightoncoming / cross-traffic: the new car's movement through the junction (default straight).
--x Ncrossing: a scene point on the target's path where the pedestrian crosses (a crosswalk), with z; replaces atS. [m]
--z Ncrossing: the point's scene z (minus north). [m]

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--actor-id ACTOR_IDrequiredActor.
--direction DIRECTIONrequired; one of left, rightTarget lane side.
--duration-s NLane-change duration. [> 0 s] (default 3)
--end-s NClip time the event ends. [>= 0 s]
--id IDrequiredNew event id.
--start-s NrequiredClip time the change starts. [>= 0 s]

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--actor-id ACTOR_IDrequiredActor.
--direction DIRECTIONrequired; one of left, right, straightMovement at the next junction.
--end-s NClip time the event ends. [>= 0 s]
--id IDrequiredNew event id.
--start-s NrequiredClip time the choice applies from. [>= 0 s]

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--actor-id ACTOR_IDrequiredActor.
--end-s NClip time the event ends. [>= 0 s]
--id IDrequiredNew event id.
--rate-mps2 NAcceleration 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 NrequiredClip time the change starts. [>= 0 s]
--target-kph NrequiredSpeed to reach; 0 brakes to a stop. [0..160 km/h]

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--actor-id ACTOR_IDrequiredA moving road vehicle on a lane.
--id IDrequiredNew event id.
--movement-rsl MOVEMENT_RSLA 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.

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--heading-rad NHeading in the scene frame; default: the lane heading or the actor class default. [rad]
--id IDrequiredSource actor.
--lateral-m NLateral offset in the lane, positive to the left of travel. [m]
--new-id NEW_IDrequiredNew actor id.
--overlap-overrideAccept overlap with another actor (free/static actors only; refused for moving road vehicles).
--y NExplicit height; otherwise the map ground at (x,z) is used and refused without ground. [m]
--lane-rsl LANE_RSLSemantic lane road:section:lane (with s).
--s NMetres 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 NScene-frame x (east). [m]
--z NScene-frame z (minus north). [m]

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--heading-rad NHeading in the scene frame; default: the lane heading or the actor class default. [rad]
--id IDrequiredActor to move.
--lateral-m NLateral offset in the lane, positive to the left of travel. [m]
--overlap-overrideAccept overlap with another actor (free/static actors only; refused for moving road vehicles).
--y NExplicit height; otherwise the map ground at (x,z) is used and refused without ground. [m]
--lane-rsl LANE_RSLSemantic lane road:section:lane (with s).
--s NMetres 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 NScene-frame x (east). [m]
--z NScene-frame z (minus north). [m]

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--id IDrequiredActor to delete.

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--id IDrequiredActor.
--speed-kph NrequiredInitial speed. [0..160 km/h]

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--id IDrequiredActor.
--static BOOLrequired; one of true, falsetrue: static; false: mobile.

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--clip-seconds NClip length. [3..120 s]
--warmup-seconds NWarm-up before the clip. [0..30 s]

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--minutes NrequiredMinutes after local midnight. [0..1439 min]

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--role-id ROLE_IDrequiredActor to make ego.

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--end-s NEnd clip time. [>= 0 s]
--id IDrequiredEvent.
--start-s NrequiredStart clip time. [>= 0 s]

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--actor-id ACTOR_IDrequiredActor.
--duration-s NrequiredRoute duration. [> 0 s]
--end-s NClip time the event ends. [>= 0 s]
--id IDrequiredNew event id.
--point X,Zrequired; repeatableScene 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 NrequiredClip time the route starts. [>= 0 s]

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically)
<operation>repeatableFurther operations of the same transaction, each after --.
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge
--transaction-label TEXTThe transaction's undo label, at most 256 characters (default: the operation ids, e.g. addActor×2, setEgo)
--weather WEATHERrequired; one of clear, cloudy, overcast, light_rain, heavy_rain, wet_road, fog_light, fog_dense, snow, sleetCanonical scenario weather.

simforge 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 / flagNotesWhat
<file>requiredThe scenario document
--strictness STRICTNESSrequired; one of errors, warningsWhat fails the check (exit 2)
--previewAlso materialize and run every actor on the engine (collisions, quality, input identity)

simforge 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 / flagNotesWhat
<file>requiredThe scenario document
--map MAPRun on this installed map instead of the document's own
--ambient AMBIENTone of document, off; default documentGenerated traffic
--strictExit 2 when any road vehicle has a driving finding

simforge 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 / flagNotesWhat
<file>requiredThe scenario document (edited in place, atomically, as the next revision)
--actor IDrequiredThe actor (role id) to convert
--to TOrequired; one of follow-path, behave, reset-to-recordingThe motion to convert it to
--recording FILErepeatableA recording the document pins (plain or gzipped; log-scene/v1 reads as one). Repeatable
--map MAPUse this installed map instead of the document's own
--expect-version NRefuse unless the document is at this revision (stale_version)
--expect-digest SHA256Refuse unless the document content has this digest (stale_digest); also accepts an edit made outside simforge

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 / flagNotesWhat
--map MAPrequiredThe installed map (simforge maps pull <map>@<version>)
--out FILErequiredWhere to write the scenario document
--name NAMEdefault Untitled scenarioScenario name
--clip-seconds Sdefault 20Clip length, seconds (3 to 120)
--created-at TIMECreation timestamp YYYY-MM-DDTHH:MM:SS.mmmZ (default: now), for reproducible documents
--forceOverwrite an existing file
--dataset DATASET_IDThe writable dataset the hosted draft goes in; absent, the credential's default dataset (named in the receipt)

simforge scenario ops list

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

simforge scenario ops list [OPTIONS]

simforge scenario ops show

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

simforge scenario ops show [OPTIONS] <OPERATION>
Argument / flagNotesWhat
<operation>requiredOperation id (addActor) or command (add-actor)

simforge scenario pull

Download a hosted scenario document as a local scenario JSON file

simforge scenario pull [OPTIONS] <ID>
Argument / flagNotesWhat
idrequiredThe hosted scenario document id
--out OUTOutput file. Default: <ID>.scenario.json
--host HOSTSimForge host. Default: SIMFORGE_HOST, then the host of the last login, then simforge.ai
--forceOverwrite an existing output file
--helpPrint help