Create a scenario

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.

A scenario is two files:

srunner/scenarios/my_scenario.py    the class: actors + behaviour tree + criteria
srunner/examples/MyScenario.xml     the config: town, ego spawn, parameters

ScenarioRunner finds the class by globbing $SCENARIO_RUNNER_ROOT/srunner/scenarios/*.py and matching the config's type attribute against class names in those modules. There is no registration list — dropping the two files in is the whole install. The corollary is that the type in the XML must match the class name exactly, and a typo produces Scenario 'X' not supported.

Instructions

Progress:
- [ ] Step 1: Check prerequisites (bash scripts/check_env.sh)
- [ ] Step 2: Generate the skeleton (scaffold), or copy the closest existing scenario
- [ ] Step 3: Fill in _initialize_actors, _create_behavior, _create_test_criteria
- [ ] Step 4: Validate offline (validate) — imports, class/type match, tree shape
- [ ] Step 5: Run it (run-scenario), iterate with DEBUG=1

Step 2: Scaffold

source scripts/env.sh

# a standalone scenario with a config, in the checkout
python3 scripts/scaffold_scenario.py --name MyCutIn --town Town04 \
    --template follow_leading_vehicle

# somewhere else, to keep the checkout clean (use --additionalScenario to run it)
python3 scripts/scaffold_scenario.py --name MyCutIn --town Town04 --out ~/my_scenarios

python3 scripts/scaffold_scenario.py --list-templates

The scaffold writes both files with the four methods stubbed, the imports that actually exist in this branch, and a CollisionTest criterion so the run reports something. Then edit.

Step 3: The four methods

class MyCutIn(BasicScenario):
    def __init__(self, world, ego_vehicles, config, randomize=False,
                 debug_mode=False, criteria_enable=True, timeout=60):
        self.timeout = timeout
        self._map = CarlaDataProvider.get_map()
        self._reference_waypoint = self._map.get_waypoint(config.trigger_points[0].location)
        # scenario parameters come from the XML, via config.other_parameters
        self._distance = 50
        if "distance" in config.other_parameters:
            self._distance = float(config.other_parameters["distance"]["value"])
        super().__init__("MyCutIn", ego_vehicles, config, world, debug_mode, criteria_enable=criteria_enable)

    def _initialize_actors(self, config):
        """Spawn everything the scenario needs. Use CarlaDataProvider, never world.spawn_actor."""
        wp = self._reference_waypoint.next(self._distance)[0]
        actor = CarlaDataProvider.request_new_actor("vehicle.tesla.model3", wp.transform)
        self.other_actors.append(actor)

    def _create_behavior(self):
        """Return the py_trees tree. Composites: Sequence, Parallel; leaves: atomics."""
        root = py_trees.composites.Sequence("MyCutIn")
        root.add_child(InTriggerDistanceToVehicle(self.other_actors[0], self.ego_vehicles[0], 30))
        root.add_child(LaneChange(self.other_actors[0], speed=10, distance_other_lane=30))
        root.add_child(ActorDestroy(self.other_actors[0]))
        return root

    def _create_test_criteria(self):
        """Return a list of criteria. These decide pass/fail."""
        return [CollisionTest(self.ego_vehicles[0])]

Rules that are not obvious and cost the most time:

• Spawn through CarlaDataProvider.request_new_actor, not world.spawn_actor. Only the provider registers the actor for velocity/transform caching and for cleanup; direct spawns leak between runs and read as not found in atomics.
• Append to self.other_actors or the actor is never destroyed.
• _create_behavior must return a tree that terminates. A Sequence whose last child never succeeds hangs until the timeout — which is what an apparently stuck scenario usually is.
• config.other_parameters is a dict of {name: {attr: value}} built from the XML child elements, and every value is a string. Cast it.
• self.timeout must be set before super().__init__, because the base class reads it while building the tree.
• Criteria are attached in parallel with the behaviour and run to the end. An optional=True criterion reports but does not fail the scenario.

Step 4: Validate offline

python3 scripts/scaffold_scenario.py validate --name MyCutIn

Checks, without a simulator: the module imports, the class exists and derives from BasicScenario, the XML type matches the class name, the XML parses and names a real map for this branch, the four methods are present, and _create_behavior returns something tree-shaped. Most authoring mistakes surface here rather than after a 30 s world reload.

Step 5: Run

cd ../run-scenario
DEBUG=1 OUTPUT=1 bash scripts/run_scenario.sh MyCutIn_1

# scenario file outside the checkout
python3 "$SCENARIO_RUNNER_ROOT/scenario_runner.py" --scenario MyCutIn_1 \
    --additionalScenario ~/my_scenarios/my_cut_in.py \
    --configFile ~/my_scenarios/MyCutIn.xml --reloadWorld

DEBUG=1 prints the behaviour tree every tick with each node's status — the only practical way to see which child is blocking.

Examples

Example 1: "make a scenario where a car brakes hard in front of me"

scaffold --name HardBrakeAhead --town Town04 --template follow_leading_vehicle, then in _create_behavior: InTriggerDistanceToVehicle → ChangeActorTargetSpeed(0) or HardBreak → Idle → ActorDestroy. Criteria: CollisionTest plus DrivenDistanceTest.

Example 2: "add a parameter so I can sweep the distance"

Add <distance value="50"/> to the XML config and read config.other_parameters["distance"]["value"] in __init__. Duplicate the <scenario> element with different values and names to get MyCutIn_1, MyCutIn_2, … then run group:MyCutIn.

Example 3: "put my scenario in a leaderboard route"

Write the class, then reference it by type in a route's <scenarios> block and run with [[run-route-scenario]]. Route scenarios take their position from trigger_point rather than from the config's ego spawn, so read config.trigger_points[0] and derive everything relative to it — that is what makes a scenario reusable across routes.

Troubleshooting

Problem: Scenario 'MyCutIn_1' not supported Cause: the XML type does not match a class name, the file is not in srunner/scenarios/, or SCENARIO_RUNNER_ROOT is unset so the glob is ./. Solution: validate; use --additionalScenario for files outside the checkout.

Problem: the scenario starts and hangs until the timeout Cause: a behaviour that never returns SUCCESS — a trigger condition that cannot be met, or a Sequence missing a terminating child. Solution: DEBUG=1 and read the tree; add Idle(duration) or a TimeOut in parallel.

Problem: KeyError / not found from CarlaDataProvider.get_velocity Cause: the actor was spawned with world.spawn_actor, so it is not registered. Solution: CarlaDataProvider.request_new_actor(...).

Problem: actors from the last run are still there Cause: on master, _cleanup() has manager.cleanup() and CarlaDataProvider.cleanup() commented out, and actors not in self.other_actors are never destroyed. Solution: append every actor to self.other_actors; reload the world between runs.

Problem: TypeError: unsupported operand on a parameter Cause: config.other_parameters values are strings. Solution: float(...) / int(...).

Problem: AttributeError: 'NoneType' object has no attribute 'transform' Cause: waypoint.next(d) returned an empty list — the distance runs off the end of the road, or past a junction. Solution: guard the result; generate_target_waypoint / get_waypoint_in_distance in srunner/tools/scenario_helper.py handle junctions.

Outputs

srunner/scenarios/<snake_name>.py and srunner/examples/<Name>.xml (or the same pair under --out), immediately runnable by name. validate prints a per-check report and exits non-zero on anything that would stop the scenario loading.

The atomic behaviours, trigger conditions and criteria available — with the signatures that matter — are catalogued in references/atomics.md.