roadrunner-scenario-authoring

# 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).

```matlab
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:
```matlab
addpath('<path-to-skill>/scripts');
```

### 2. Initialize Scenario

```matlab
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:

```matlab
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):
```matlab
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:**
```matlab
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:**
```matlab
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):**
```matlab
actor = addActor(rrs, asset, approximatePosition);
autoAnchor(actor.InitialPoint);  % Must be within 5m of road
```

**Option C — Relative to another actor:**
```matlab
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.

```matlab
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.

```matlab
% 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