Author a scenario

A scenario is a small JSON file: the map, the actors and their routes, what triggers what, the weather and the clip length. It holds no video or sensor data. Never write it by hand: create it on an installed map and change it with authoring operations, which check every change against the map.

Scenario files use UTF-8, with or without a byte-order mark. Windows CRLF line endings are supported; save UTF-16 files as UTF-8 before running them.

Find places on the map#

simforge locations find --map easterbrook-discovery-school --limit 20
simforge scenario actors

locations find returns real lanes and junctions with their lane address (roadAnchor.rsl, as road:section:lane) and distance along the lane (s). scenario actors lists the actors you can place, such as vehicle.sedan.

Create and edit#

simforge scenario new --map easterbrook-discovery-school --out s.json
simforge scenario apply s.json add-actor --id ego --catalog-id vehicle.sedan --lane-rsl <road:section:lane> --s 20 \
  -- set-ego --role-id ego -- set-clip --clip-seconds 20
simforge scenario check s.json --strictness warnings --preview

• Operations are chained with --; the whole chain applies atomically or not at all.
• --expect-version and --expect-digest, given right after the file and before the first operation, refuse a change when the file changed since you last read it.
• scenario check validates the scenario on its map and exits 2 on findings; --preview also drives every actor on the engine.
• simforge scenario ops list lists every operation: actors, ego, speed, lane changes, junction turns, routes, event timing, weather, clock and clip length.

Packages#

A scenario package (.scenario.zip) carries a scenario with what it pins, for moving it between machines.

simforge package inspect scenario.zip
simforge package verify scenario.zip

package verify checks the manifest and every member's digest and exits 2 on a mismatch. Both need the runtime.

For agents#

The simforge-authoring skill in the skills pack covers every operation, its arguments and the refusals, with worked examples.