> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```sh theme={null}
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

```sh theme={null}
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.

```sh theme={null}
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]
>
> **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](/skills) covers every operation, its arguments and the refusals, with worked examples.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.