roadrunner-scenario-simulating

# RoadRunner Scenario Simulation

Simulate RoadRunner scenarios, step through simulations, control actors in co-simulation, add observers, attach sensors, and retrieve results — from MATLAB and Simulink.

## When to Use

- User wants to run a RoadRunner scenario simulation
- User wants to step through a simulation frame-by-frame
- User wants to control an actor externally (co-simulation)
- User wants to observe simulation state (read-only monitoring)
- User wants to add sensors and read target poses or lane boundaries
- User wants to retrieve simulation logs programmatically
- User wants to read or write scenario variables
- User asks about co-simulation with Simulink
- User asks about publishing actor behaviors

## When NOT to Use

- Launching or connecting to RoadRunner
- Authoring scenarios (adding actors, paths, behaviors in the editor)
- Building or editing scenes (roads, terrain, assets)
- Exporting actor trajectories to CSV — use `exportActorTrajectoryToCSV` directly
- Working with `drivingScenario` (that is a DIFFERENT toolbox — Automated Driving Toolbox)

## Critical: Do NOT Confuse With drivingScenario

`drivingScenario` (from Automated Driving Toolbox) is a MATLAB-native scenario tool.
RoadRunner Scenario simulation uses completely different APIs on the `roadrunner` object.
**Never mix these two — they are unrelated.**

---

## Decision Tree

```
User wants to simulate →
  ├── Just run to completion? → Workflow A (simulateScenario)
  ├── Need step control OR programmatic log? → Workflow B (createSimulation)
  ├── Need to read actor state during sim? → Workflow C (getAttribute)
  ├── Need external actor control? →
  │     ├── From MATLAB? → Workflow D (System object co-sim)
  │     └── From Simulink? → Workflow E (Simulink blocks)
  ├── Need read-only monitoring? → Workflow F (Observers)
  └── Need sensor data during sim? → Workflow G (SensorSimulation)
```

---

## Workflow A: Simple Simulation (run to completion)

Use when the user just wants to simulate an already-open scenario:

```matlab
openScenario(rrApp, "MyScenario");
simulateScenario(rrApp, EnableLogging=true);
```

Options: `Pacing`, `IsBlocking`, `IsSteppingStart`, `EnableLogging`.

**Important:** `simulateScenario` does NOT return a log object. Use it when you only need to run to completion. If you need **programmatic access** to the simulation log in MATLAB, use `createSimulation` (Workflow B) instead.

---

## Workflow B: Step-by-Step Simulation

Use when the user needs frame-by-frame control or programmatic log access.

**CRITICAL call order:** `createSimulation` must be called BEFORE `simulateScenario`. The Scenario Server rejects new connections while a simulation is running or paused. Also, do NOT use `set(rrSim, SimulationCommand="Start")` then `"Step"` — `"Start"` runs the sim freely to completion.

```matlab
% 1. Get the simulation handle FIRST (before anything is running)
rrSim = createSimulation(rrApp);
stepSize = 0.01;
set(rrSim, StepSize=stepSize);
set(rrSim, MaxSimulationTime=30);

% 2. THEN start simulation in stepping mode
simulateScenario(rrApp, IsSteppingStart=true, IsBlocking=false, EnableLogging=true);
pause(0.5);  % Allow sim to initialize before stepping

% 3. Step through the simulation
for i = 1:numSteps
    set(rrSim, SimulationCommand="Step");
    pause(stepSize);  % REQUIRED — Step is async, must wait for frame to complete
end
set(rrSim, SimulationCommand="Stop");

simLog = get(rrSim, "SimulationLog");
```

**CRITICAL:** `"Step"` is **asynchronous** — you MUST add `pause(stepSize)` after each Step. Without it, commands pile up and are silently dropped. Do NOT use dot-method syntax (`rrSim.step()`) — always use `set(rrSim, SimulationCommand=...)`. Do NOT set `Logging="On"` during stepping — use `EnableLogging=true` in the `simulateScenario` call.

### SimulationCommand values

`"Start"`, `"Step"`, `"Pause"`, `"Continue"`, `"Stop"`, `"Replay"`

Replay uses positional syntax: `set(rrSim, "SimulationCommand", "Replay", fileName)`

### Polling SimulationStatus

`get(rrSim, "SimulationStatus")` returns: `"Inactive"`, `"Running"`, `"Paused"`, `"Done"`

Use in wait loops when running non-blocking simulations. Check BOTH `"Done"` and `"Inactive"` — short scenarios may transition past `"Done"` before the poll catches it:
```matlab
status = get(rrSim, "SimulationStatus");
while ~ismember(status, ["Done", "Inactive"])
    pause(0.1);
    status = get(rrSim, "SimulationStatus");
end
```

---

## Workflow C: Reading Actor State

To get actor information during a step-by-step simulation:

**Note:** `get(rrSim, "ActorSimulation")` always includes the **world actor** (ID 0) at index 1. This is a non-movable root actor, not a vehicle. Skip it or filter by ID when iterating.

**Note:** Actors are only queryable while the simulation is active (Running or Paused). After `"Stop"`, `get(rrSim, "ActorSimulation")` returns empty.

```matlab
% Get all actors — returns a CELL ARRAY, use {idx} not (idx)
actors = get(rrSim, "ActorSimulation");
actorSim = actors{2};  % cell indexing required; index 1 is world actor (ID 0)

% Or find a specific actor by ID (returns a single object)
% NOTE: ActorID must be uint64 — double will fail silently or error
actorSim = Simulink.ScenarioSimulation.find("ActorSimulation", ActorID=uint64(1));

% Read runtime attributes — use getAttribute, NOT property access
pose = getAttribute(actorSim, "Pose");              % 4x4 matrix
velocity = getAttribute(actorSim, "Velocity");      % 1x3 vector
angVel = getAttribute(actorSim, "AngularVelocity"); % 1x3 vector
```

**CRITICAL:** Do NOT use `actorSim.Pose` or `actorSim.Velocity` — these are NOT public properties. Always use `getAttribute(actorSim, "AttrName")`.

Runtime attributes: `"ID"`, `"Pose"`, `"Velocity"`, `"AngularVelocity"`, `"WheelPoses"`, `"LaneLocation"`, `"Children"`, `"Parent"`, `"PhaseStatus"`, `"ActorType"`, `"TrafficSignalRuntime"`, `"TrafficSignalControllerRuntime"`

### Static Attributes (Name, BoundingBox, etc.)

To get an