Author a scenario

Create a scenario on an installed map and change it with typed, atomic authoring operations instead of editing JSON by hand.

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 as {records, total, nextCursor}, each record with its lane address (anchor.road.rsl, as road:section:lane) and distance along the lane in its direction of travel (anchor.road.s, which scenario apply add-actor --lane-rsl --s takes as it is); --cursor <nextCursor> reads the next page. Hosted authoring discover --kind locations prints the same records. 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.

Note. simforge package import resolves a package’s map from SimForge’s internal registry; it does not read the maps you pulled.

For agents

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