# Roadrunner Scenario Authoring

Programmatically author RoadRunner scenarios from MATLAB using roadrunnerAPI.

- Repository: https://github.com/matlab/matlab-agentic-toolkit (1237 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-10-27
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add matlab/matlab-agentic-toolkit --skill roadrunner-scenario-authoring -g -a claude-code -y`
Codex: `npx skills add matlab/matlab-agentic-toolkit --skill roadrunner-scenario-authoring -g -a codex -y`
Cursor: `npx skills add matlab/matlab-agentic-toolkit --skill roadrunner-scenario-authoring -g -a cursor -y`
Gemini CLI: `npx skills add matlab/matlab-agentic-toolkit --skill roadrunner-scenario-authoring -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add matlab/matlab-agentic-toolkit`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

The rest: https://github.com/matlab/matlab-agentic-toolkit/blob/HEAD/skills-catalog/automotive/roadrunner-scenario-authoring/SKILL.md