# Author a scenario

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

Source: https://simforge.ai/docs/scenarios

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
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

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