---

name: roadrunner-scenario-authoring description: > Programmatically author RoadRunner scenarios from MATLAB using roadrunnerAPI. Use when adding actors, creating routes, building scenario logic (phases, conditions, actions), placing vehicles/pedestrians, defining cut-in/crossing/ follow scenarios, or any programmatic scenario creation in RoadRunner. Triggers on: roadrunnerAPI, scenario authoring, add actor, create route, phase logic, cut-in scenario, pedestrian crossing, scenario from MATLAB. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.0"

RoadRunner Scenario Authoring

Programmatically create RoadRunner scenarios from MATLAB: actors, routes, phase logic, and validation — all via roadrunnerAPI.

When to Use

• Adding actors (vehicles, pedestrians, objects) to a RoadRunner scenario
• Creating routes and waypoints for actors
• Building scenario logic: phases, conditions, actions
• Authoring common patterns: cut-in, pedestrian crossing, lead-follow, emergency brake
• Placing actors on roads using anchor-based or HD Map positioning
• Validating scenario structure before simulation

When NOT to Use

• Connecting to or launching RoadRunner → use roadrunner-core
• Building scenarios from recorded sensor data → use matlab-use-scenario-builder
• Authoring road geometry (lanes, junctions) → use roadrunner-rrhd-authoring
• Importing maps or scenes → use roadrunner-import-scene
• Simulating or exporting scenarios → use roadrunner-scenario-simulating

Workflow

1. Ensure Session

Verify rrApp exists. If not, ensure RoadRunner is connected first (e.g., via roadrunner-core or manually).

if ~exist('rrApp', 'var') || ~isvalid(rrApp)
    error("No active RoadRunner session. Use the roadrunner-core skill.");
end

Path setup: Before calling helper functions, ensure the scripts directory is on the MATLAB path:

addpath('<path-to-skill>/scripts');

2. Initialize Scenario

openScene(rrApp, sceneName);
newScenario(rrApp);
rrApi = roadrunnerAPI(rrApp);
rrs = rrApi.Scenario;
phaseLogic = rrs.PhaseLogic;
rrprj = rrApi.Project;

3. Scene Awareness

Before placing actors, survey the scene to find valid lane positions. Use the helperSceneAwareness script for automated analysis, or query manually via HD Map export:

sceneInfo = helperSceneAwareness(rrApp, NumActors=2, ScenarioType="cut-in");

See references/scene-awareness.md for manual HD Map query patterns when the helper is unavailable.

4. Add Actors

Option A — Batch placement (recommended for 2+ actors):

actorSpecs(1) = struct(Name="Ego", AssetPath="Vehicles/Sedan.fbx", ...
    AssetType="VehicleAsset", LaneIndex=1, Fraction=0.1, Speed=15);
[actors, report] = helperPlaceActors(rrs, rrprj, phaseLogic, sceneInfo.HDMap, actorSpecs);
ego = actors{1};  % cell array — use curly braces

Option B — Manual placement:

vehicleAsset = getAsset(rrprj, "Vehicles/Sedan.fbx", "VehicleAsset");
actor = addActor(rrs, vehicleAsset, position);
actor.Name = "Ego";
autoAnchor(actor.InitialPoint);  % Snaps to nearest road

Post-placement check: Verify actor.InitialPoint.WorldPosition is NOT [0 0 0].

See references/asset-catalog.md for available vehicle/character paths.

5. Position Actors (Anchoring)

Option A — Scene anchors available:

anchors = getAnchors(rrApp);
% Use remapAnchor for cross-scene portability (not findSceneAnchor)
anchorPt = findSceneAnchor(rrs, anchors(1).Name);
anchorToPoint(actor.InitialPoint, anchorPt);
actor.InitialPoint.ForwardOffset = 20;
actor.InitialPoint.LaneOffset = 1;

Option B — No scene anchors (use autoAnchor):

actor = addActor(rrs, asset, approximatePosition);
autoAnchor(actor.InitialPoint);  % Must be within 5m of road

Option C — Relative to another actor:

anchorToPoint(target.InitialPoint, ego.InitialPoint);
target.InitialPoint.ForwardOffset = 30;
target.InitialPoint.LaneOffset = 1;

6. Create Routes (When Needed)

Routes put actors in path-following mode. Actors without routes drive in lane-following mode along their anchored lane.

route = actor.InitialPoint.Route;
fwdPt = addPoint(route, actor.InitialPoint.WorldPosition + [20 0 0]);
autoAnchor(fwdPt);
% For vehicles: disable freeform so route follows road surface
% (Do NOT do this for pedestrians — they need freeform to cross roads)
for i = 1:numel(route.Segments)
    route.Segments(i).Freeform = false;
end

When to add routes:

• Character/pedestrian actors — ALWAYS required (validation fails without them)
• Vehicles that follow a specific path (e.g., ego driving straight)
• Vehicles that do NOT need ChangeLaneAction

When NOT to add routes:

• Vehicles that need ChangeLaneAction — they MUST be in lane-following mode (no routes)
• Vehicles that need ChangeLateralOffsetAction — same requirement

Route point rules:

• Always use autoAnchor for route points — position must be within 5m of road
• Do NOT use anchorToPoint + ForwardOffset on route points — causes validation failure
• Keep route offset small (20m) to stay on the road
• For junction turns: use multiple waypoints (pre-junction, post-junction, exit) for smooth path
• After adding route points, set seg.Freeform = false on each segment to follow road geometry (freeform routes ignore road surface and may float above/below the road)

7. Build Phase Logic

See references/actions-and-conditions.md for the complete catalog.

% Get actor's initial phase (auto-created with addActor)
initPhase = initialPhaseForActor(phaseLogic, actor);

% Modify default speed (initial phase already has ChangeSpeedAction)
initPhase.Actions(1).Speed = 20;

% Add sequential phase
nextPhase = addPhaseInSerial(phaseLogic, initPhase, "ActorActionPhase");
nextPhase.Actor = actor;  % REQUIRED — never omit

% Set trigger condition on initial phase
cond = setEndCondition(initPhase, "LongitudinalDistanceToActorCondition");
cond.Actor = actor;           % REQUIRED
cond.ReferenceActor = otherActor;
cond.Distance = 10;

% Add action to next phase
action = addAction(nextPhase, "ChangeLaneAction");
action.Direction = "left";

Multi-actor phase logic: Each actor's phase chain is independent. Any phase that has a subsequent phase MUST have an end condition — without one, the phase runs indefinitely and subsequent phases never execute. For multi-actor scenarios, ensure EVERY phase with a successor has an appropriate end condition set via setEndCondition.

8. Validate and Report

validate(rrs);

After validation passes, present a summary of what was created — never simulate unless explicitly asked.

Scenario Decomposition

MANDATORY: Before writing ANY code, complete Steps 0–1 below and present your plan to the user for confirmation. Do not skip this — scenarios built without pre-analysis frequently fail due to wrong timing, missed collisions, or impossible trigger conditions.

Step 0 — Clarify intent: If the user's prompt is ambiguous about ANY of the following, ASK before proceeding:

• Number and types of actors
• Desired outcome (collision, near-miss, safe completion?)
• Speeds, distances, or timing not specified
• Which actor is "ego" vs "target"
• Scene to use (if not stated)

Step 1 — Physics-first design (REQUIRED for timed interactions): For collisions, near-misses, cut-ins, pedestrian crossings, and any scenario where actors must arrive at the same point at a specific time — you MUST derive kinematic parameters before writing code. Follow the full 5-step process in references/physics-first-design.md:

1. Parse intent into timeline
2. Measure spatial parameters (query HD Map)
3. Build parameter derivation table (show your math)
4. Verify conditions will trigger
5. Write code with derived values

Present your decomposition to the user — show actors, placement, speeds, trigger timing, and expected outcome. Get confirmation before executing code.

1. Actors — How many, what types (vehicle/pedestrian/object), what roles (ego, target, background, stationary)
2. Placement geometry — Determines which helperSceneAwareness type to use:
   • Same lane (ScenarioType="following") — leader/follower, overtake start, emergency brake
   • Adjacent lanes (ScenarioType="cut-in") — lane changes, merges, parallel driving
   • Crossing paths — pedestrian crossing, intersection conflicts
3. Interaction intent — Determines speed/separation/trigger defaults:
   • Conflict/near-miss: Close proximity, speed differential, tests reaction (small gap, distance triggers)
   • Cooperative: Safe completion expected, no collision (large gap ≥ 30m, time or duration triggers)
   • Independent: Actors don't interact directly (background traffic, stationary objects)
4. Maneuver sequence — Identify each distinct behavior change as a phase: drive → lane change → brake → resume. Each transition needs a trigger condition.
5. Trigger selection:
   • Distance-based (LongitudinalDistanceToActorCondition) — requires speed differential between actors
   • Time-based (DurationCondition) — works regardless of speeds, simpler
   • Simulation time (SimulationTimeCondition) — absolute time, good for choreographed sequences
6. Safety validation — Before executing, verify lane-change scenarios won't collide: required_gap = lane_change_distance + closing_rate × (lane_change_distance / actor_speed) + 5m

Scenario Defaults (auto-created by RoadRunner)

When newScenario() is called, RoadRunner automatically creates:

• A CollisionCondition as the root phase's fail condition (any actor-to-actor collision fails the scenario)
• A SimulationTimeCondition (60s) as the root phase's end condition

Do NOT duplicate these. To modify the default collision condition:

rootPhase = phaseLogic.RootPhase;
% The fail condition already exists — access it directly
% To change the end time:
rootEndCond = setEndCondition(rootPhase, "SimulationTimeCondition");
rootEndCond.Time = 30;  % Override default 60s

Hard Constraints

1. Always set .Actor on ActorActionPhase and condition objects — never omit
2. Never add duplicate action types to a single phase — modify phase.Actions(1) instead
3. Character actors require routes — without them validation fails
4. autoAnchor requires proximity — point must be within 5m of road surface
5. Distance condition rules — ONLY "le" and "ge" are valid (not "lt", "gt")
6. Speed condition rules — full set: "eq", "gt", "lt", "ge", "le", "ne"
7. SerialPhase cannot nest in SerialPhase — use ParallelPhase as intermediate
8. Distance triggers need speed difference — if actors travel at same speed, gap never changes
9. Never simulate unless user explicitly asks — authoring and simulation are separate workflows. Never claim scenario outcomes (collision, near-miss) based on math alone — only simulation produces ground truth
10. Never assume — always clarify ambiguous prompts — if user doesn't specify speeds, distances, timing, actor count, desired outcome (collision vs near-miss vs safe), or scene, ASK before writing code. Present your scenario decomposition and physics analysis to the user for confirmation before executing. Guessing leads to scenarios that validate but produce wrong outcomes.
11. setEndCondition not addEndCondition — only one end condition per phase
12. ChangeLaneAction requires lane-following mode — do NOT add routes to actors that need lane changes
13. Do NOT use anchorToPoint + ForwardOffset on route points — causes validation failure; use autoAnchor only
14. LaneOffset can land on junction connectors — for lane-change scenarios, place actors on verified parallel lanes using HD Map positions +