Run an OpenSCENARIO file

Paths. scripts/… and references/… below are relative to the directory holding this SKILL.md. Your working directory is the user's project, not that directory, so prefix them with its absolute path or the command is not found.

ScenarioRunner speaks two unrelated standards that happen to share a name:

	OpenSCENARIO 1.x	OpenSCENARIO 2.0
Extension	.xosc	.osc
Format	XML (<Storyboard>, <Act>, <Maneuver>)	a domain-specific language
Flag	--openscenario	--openscenario2
Implementation	srunner/tools/openscenario_parser.py	srunner/osc2/ (ANTLR grammar)
Maturity	broad, partial	experimental

They are not versions of each other and no file works with both flags.

Unlike Python scenarios, an OSC file carries its own map, entities and ego — so there is no --scenario name, no town lookup, and --reloadWorld is implied by whatever <RoadNetwork> says.

Instructions

Progress:
- [ ] Step 1: Check prerequisites (bash scripts/check_env.sh)
- [ ] Step 2: Find or validate the file (list / validate)
- [ ] Step 3: Run it with the right flag
- [ ] Step 4: Drive or observe the ego if the file expects an external controller

Step 2: Find and validate

source scripts/env.sh

bash scripts/run_openscenario.sh list                  # bundled .xosc and .osc, per branch
bash scripts/run_openscenario.sh validate path/to.xosc # schema + map + entity check, no server

validate is worth running first: it resolves the <RoadNetwork><LogicFile> map against the server's map list, checks catalog references, and reports the ParameterDeclarations you can override — all of which otherwise fail several seconds into a run, after the world has already been reloaded.

Step 3: Run

source scripts/env.sh

# OpenSCENARIO 1.x
bash scripts/run_openscenario.sh run "$SCENARIO_RUNNER_ROOT/srunner/examples/FollowLeadingVehicle.xosc"

# with global parameter overrides — note the 'key: value' comma-separated form
PARAMS='leadingSpeed: 8.0, egoSpeed: 12.0' \
    bash scripts/run_openscenario.sh run .../FollowLeadingVehicle.xosc

# OpenSCENARIO 2.0
bash scripts/run_openscenario.sh run2 "$SCENARIO_RUNNER_ROOT/srunner/examples/cut_in_and_slow_right.osc"

Direct equivalents:

python3 "$SCENARIO_RUNNER_ROOT/scenario_runner.py" --openscenario  file.xosc --openscenarioparams 'k: v'
python3 "$SCENARIO_RUNNER_ROOT/scenario_runner.py" --openscenario2 file.osc

--openscenarioparams overrides only entries in the global ParameterDeclarations; per-story parameters are not reachable. The format is 'name: value, name2: value2' — it is split on , then on : and both sides are stripped, so a value containing either character breaks the parse.

The OSC timeout is hard-coded to 100000 seconds for both flags. A stuck OSC run does not time out on its own; interrupt it.

Step 4: Who drives the ego

An .xosc that assigns a controller (<ObjectController> with the CARLA NpcVehicleDriving / simple_vehicle_control controllers) drives itself. One that declares the ego with an external controller does not — same silent "nothing happens" as with Python scenarios:

python3 "$SCENARIO_RUNNER_ROOT/manual_control.py" -a --rolename=hero

OscControllerExample.xosc is the file to read for how controllers are wired.

Examples

Example 1: "run this xosc I got from another tool"

validate first. The two usual rejections are a map name the server does not have (<LogicFile filepath="Town04"> needs Town04 loaded/available) and OSC features ScenarioRunner does not implement — validate names both. Then run.

Example 2: "sweep a parameter"

for v in 4 8 12; do
  PARAMS="leadingSpeed: $v" bash scripts/run_openscenario.sh run .../FollowLeadingVehicle.xosc
done

Example 3: "try OpenSCENARIO 2.0"

list shows the .osc corpus (cut_in_and_slow_right.osc, overtake1.osc, follow_trajectory.osc, …). On ue5-master they live in srunner/osc_examples/, not srunner/examples/. Expect gaps: the osc2 pipeline parses a subset of the language and raises from srunner/osc2/ on the rest.

Troubleshooting

Problem: File does not exist Cause: ScenarioRunner checks the path before anything else, and relative paths resolve against your CWD, not $SCENARIO_RUNNER_ROOT. Solution: use an absolute path.

Problem: xmlschema.validators.exceptions.XMLSchemaValidationError Cause: the file targets a newer OpenSCENARIO revision than the bundled schema (srunner/openscenario/0.9.x/*.xsd + xmlschema==1.0.18). Solution: validate reports the offending element. Remove or downgrade it; there is no schema switch.

Problem: the scenario loads but an action never happens Cause: an unimplemented OSC feature. openscenario_parser.py silently skips some actions/conditions rather than failing. Solution: check the support matrix in references/openscenario.md.

Problem: --openscenarioparams ignored, with WARN: Ignoring --openscenarioparams Cause: it was passed without --openscenario (e.g. with --openscenario2, which has no parameter override). Solution: put the values in the file for OSC 2.0.

Problem: ModuleNotFoundError: No module named 'antlr4' Cause: OSC 2.0 needs the ANTLR runtime. Solution: pip install antlr4-python3-runtime==4.10. The version matters — the generated parser in srunner/osc2/osc2_parser/ is pinned to 4.10.

Problem: catalog references fail to resolve Cause: <CatalogLocation> paths are relative to the .xosc file. Solution: keep the file next to its catalogs/ directory, as the bundled examples do.

Outputs

The scenario executed on the server, with the same criteria report as any other ScenarioRunner run (OUTPUT=1, JSON=1, OUTPUT_DIR all work the same way). validate prints a schema verdict, the map required, the entities and the overridable parameters, and exits non-zero if the file cannot run.

Feature support and the OSC 2.0 pipeline are covered in references/openscenario.md.