---

name: scenario-studio description: "Define, generate, inspect, and troubleshoot SMARTS scenarios from supported maps, traffic, missions, social agents, bubbles, surface patches, traffic histories, and metadata. Use this route when the task is scenario DSL or generated scenario layout; route live SUMO/TraCI, Envision replay, or environment lifecycle elsewhere." disable-model-invocation: true metadata: disco-role: operating license: MIT

Scenario Studio

Use this route when you need a self-contained SMARTS scenario definition or need to explain why generated scenario artifacts are missing or incompatible. The runtime DSL is smarts.sstudio.types (smarts.sstudio.sstypes is the implementation module) and the high-level entry point is smarts.sstudio.genscenario.gen_scenario(scenario, output_dir, seed=42).

Decide the boundary first

• Use Scenario from smarts.sstudio.types for the authoring DSL. It combines map_spec, named traffic, ego_missions, social_agent_missions, bubbles, friction_maps, traffic_histories, and scenario_metadata.
• Use the runtime smarts.core.scenario.Scenario only after generation, when SMARTS discovers a map and build/ assets. It is not the authoring dataclass.
• Use scripts/validate_scenario_layout.py for a read-only layout check and scripts/generate_minimal_scenario.py for a bounded local fixture. Both take explicit paths and never start SUMO, TraCI, Envision, or a network download.
• Route scl scenario build, scl scenario clean, SUMO/TraCI, Waymo/Argoverse conversion, and other system integrations to cli-integrations.
• Route Gym/RLlib environment reset/step/close to simulation-environments. Route Envision replay and rendered sensors to sensors-visualization.

Read the linked references before authoring a nontrivial scenario:

• API reference for live constructor signatures and the stable meaning of each DSL object.
• Workflows for minimal generation, custom maps, social agents, histories, deterministic rebuilds, and discovery.
• Data formats for source-vs-build layout and artifact ownership.
• Maps and traffic for map engines, routes, flows, missions, bubbles, friction, and dataset boundaries.
• Troubleshooting for actionable recovery.

Minimal authoring contract

1. Create an application-owned scenario directory and put a scenario.py in it. Keep input maps and data paths explicit; do not depend on the current working directory.
2. Select a map source: map.net.xml/another .net.xml for SUMO, map.xodr for OpenDRIVE, a Waymo .tfrecord source, an Argoverse map archive, or a MapSpec(source=..., builder_fn=...) for a custom RoadMap implementation.
3. Define named traffic, missions, and optional social/bubble/history metadata. Use edge/lane/offset tuples only when the referenced roads and lanes exist.
4. Call gen_scenario(..., output_dir=scenario_dir, seed=<integer>). Set the same seed for comparable generated output; seed random choices before the call as well when authoring code uses Python or NumPy randomness.
5. Validate the source and then the generated build/ tree. Build assets are generated state, not source code; regenerate after changing the DSL or map.
6. Before simulation, ensure the selected engine is compatible with the map and manually check that ego mission starts do not overlap traffic starts. Studio does not detect that collision-prone overlap for you.

Fast recipe

from pathlib import Path
from smarts.sstudio import gen_scenario, types as t

root = Path("my_scenario").resolve()
car = t.TrafficActor(name="car")
scenario = t.Scenario(
    map_spec=t.MapSpec(source=str(root / "map.net.xml")),
    traffic={"background": t.Traffic(
        engine="SUMO",
        flows=[t.Flow(
            route=t.Route(begin=("edge_in", 0, "random"),
                          end=("edge_out", 0, "max")),
            rate=60, begin=0, end=60, actors={car: 1.0},
        )]
    )},
    ego_missions=[t.Mission(t.Route(
        begin=("edge_in", 1, 10), end=("edge_out", 1, "max")
    ))],
)
gen_scenario(scenario, root, seed=42)

SUMO traffic requires a SUMO road network and the SUMO Python/runtime integration; use engine="SMARTS" for supported non-SUMO road maps. The recipe is a shape example: replace edge ids with ids from the selected map and install optional dependencies before claiming a successful build.

Generated-artifact explanation

A successful generation normally creates build/build.db, a map artifact under build/map/, route files under build/traffic/, and optional files for missions, social agents, bubbles, friction, histories, and metadata. The exact set is determined by non-empty Scenario fields; see the data-format reference. smarts.core.scenario.Scenario.is_valid_scenario() checks that a map can be built, not that every optional artifact or traffic combination is semantically safe. Missing build/map/map.glb, stale build.db, or absent route files means regenerate/build rather than edit generated pickle/XML files manually.

Checks and handoff

Run the validator from any cwd:

python /path/to/skills/disco/smarts/sub-skills/scenario-studio/scripts/validate_scenario_layout.py \
  --scenario /absolute/path/to/my_scenario --require-build

For a safe local fixture (OpenDRIVE is used only when the installed optional parser can load the supplied map), write to an explicit empty output directory:

python /path/to/skills/disco/smarts/sub-skills/scenario-studio/scripts/generate_minimal_scenario.py \
  --map /absolute/path/to/map.net.xml --output /absolute/path/to/out --seed 42

The helper refuses to overwrite non-empty output unless --force is supplied, uses no external service, and exits nonzero with the failing path or import reason. Treat missing SUMO, Waymo, Argoverse, or dataset packages as explicit integration gaps, not as evidence that core Scenario Studio is broken.