---

name: roadrunner-scenario-simulating description: > Expert guidance for simulating RoadRunner scenarios via the MATLAB programmatic API and Simulink co-simulation. Use when the user wants to run a simulation, step through a simulation, control actors during co-simulation, add observers, attach sensors, retrieve simulation logs, or read/write scenario variables. Covers simulateScenario, createSimulation, ScenarioSimulation set/get, ActorSimulation getAttribute/setAttribute, addObserver, SensorSimulation, Simulink co-sim blocks, and publishActorBehavior. NOT for project setup, scene building, scenario authoring, or trajectory export. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.0"

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:

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.

% 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:

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.

% 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 actor's name or other static properties, use ActorModel — NOT getAttribute(actorSim, "Name") (which does not exist):

actorModel = get(actorSim, "ActorModel");
actorName = getAttribute(actorModel, "Name");
boundingBox = getAttribute(actorModel, "BoundingBox");

Static attributes on ActorModel: "ID", "Name", "PaintColor", "BoundingBox", "WheelSpec", "TrafficSignalSpec", "TrafficSignalControllerSpec"

---

Workflow D: Co-Simulation with MATLAB System Object

Architecture

1. Assign a behavior to the actor (see below)
2. In MATLAB: Write a System object that controls the actor at runtime
3. The System object finds itself using Simulink.ScenarioSimulation.find

Assigning Behaviors

R2024a: Assign behaviors in the RoadRunner Scenario Editor UI only (no MATLAB API).

R2025a+: Assign behaviors programmatically via the roadrunnerAPI authoring interface:

rrApi = roadrunnerAPI(rrApp);
prj = rrApi.Project;
scnro = rrApi.Scenario;

% Get or create a behavior asset
behaviorAsset = getAsset(prj, "Behaviors/MyBehavior.rrbehavior", "BehaviorAsset");

% Assign to an existing actor
car.BehaviorAsset = behaviorAsset;

Key points:

• roadrunnerAPI(rrApp) provides access to Project and Scenario objects
• Use getAsset(prj, path, "BehaviorAsset") to retrieve existing .rrbehavior assets
• Use createAsset(prj, path, "BehaviorAsset") to create new behavior assets
• After creating a behavior asset, set its platform: setPlatform(behaviorAsset, "SimulinkPlatform") — this is correct for BOTH MATLAB System objects and Simulink models. Do NOT use "MATLAB", "External", or "MATLABSystem" (they are not registered)
• Assign via the BehaviorAsset property on Vehicle/Character/MovableObject
• There is NO setBehavior() function — use property assignment instead

System Object Pattern

classdef MyActorController < matlab.System
    properties (Access = private)
        ActorSim  % ActorSimulation handle
    end

    methods (Access = protected)
        function setupImpl(obj)
            obj.ActorSim = Simulink.ScenarioSimulation.find( ...
                "ActorSimulation", SystemObject=obj);
        end

        function stepImpl(obj)
            action = getAction(obj.ActorSim, "PathAction");
            currentPose = getAttribute(obj.ActorSim, "Pose");

            % Modify pose
            currentPose(1,4) = currentPose(1,4) + 0.5;
            setAttribute(obj.ActorSim, Pose=currentPose);

            % Signal action completion (guard: ActionID may not exist)
            if ~isempty(action) && isfield(action, "ActionID")
                sendEvent(obj.ActorSim, "ActionComplete", action.ActionID);
            end
        end
    end
end

Actor Control Methods

setAttribute(actorSim, Pose=poseMatrix);            % 4x4
setAttribute(actorSim, Velocity=[vx vy vz]);        % 1x3
setAttribute(actorSim, AngularVelocity=[wx wy wz]); % 1x3

action = getAction(actorSim, "PathAction");
action = getAction(actorSim, "SpeedAction");
action = getAction(actorSim, "LaneChangeAction");

sendEvent(actorSim, "ActionComplete", actionID);
sendEvent(actorSim, "UserDefinedEvent", eventName, eventStruct);
eventData = receiveEvent(actorSim, "UserDefinedEvent", eventName);

---

Workflow E: Co-Simulation with Simulink

Architecture

1. Create a Simulink model with the RoadRunner Scenario block at root level
2. Use RoadRunner Scenario Reader blocks to receive data from RoadRunner
3. Use RoadRunner Scenario Writer blocks to send data back
4. Publish the behavior: Simulink.publish.publishActorBehavior("myModel", OutputFile="output.slprotodata")
5. Assign the behavior to an actor (via RoadRunner UI, or programmatically in R2025a+ — see Workflow D)
6. Start simulation via set_param("myModel", SimulationCommand="start") — NOT sim()

Key Constraints

• The RoadRunner Scenario block must be at the model root level
• Use set_param(..., SimulationCommand="start") to start — never sim("model")
• Sample time in the RoadRunner Scenario block defines the co-sim step size (default 0.02s)
• One MATLAB instance connects to one RoadRunner co-sim at a time
• Bus types are loaded from rrScenarioSimTypes.mat

Reader Topics

Actor Pose, Specifications, Lane Location, Vehicle Wheel Poses, Traffic Signals, Target Poses, Lane Boundaries, Actions (Path/Speed/Lane Change/etc.), User-Defined Events

Writer Topics

Actor Pose, Vehicle Pose, Action Complete, User-Defined Events, Diagnostics

See references/simulink-cosim-details.md for block configuration and bus types.

---

Workflow F: Observers (Read-Only Monitoring)

Observers monitor simulation state without modifying it. Unlike co-sim behaviors (assigned in UI), observers are added programmatically.

rrSim = createSimulation(rrApp);
addObserver(rrSim, "VelocityMonitor", "MyVelocityObserver");
simulateScenario(rrApp, IsBlocking=false);
% Observer's stepImpl is called each step automatically

Note: The observer .m file must be on the MATLAB path. Use addpath if needed. Call addObserver BEFORE starting the simulation.