Simulate RoadRunner Scenarios with MATLAB and Simulink

Develop MATLAB^® and Simulink^® behaviors, publish actor behavior, simulate behaviors in RoadRunner Scenario simulation, control simulation, and access simulation parameters

Automated Driving Toolbox™ provides a flexible framework for simulating scenarios RoadRunner scenarios with actors modeled in MATLAB and Simulink. In this framework, you can configure actors, define their behaviors, or create observers for scenario-level analysis:

Actors represent dynamic entities in a RoadRunner scenario, such as vehicles or pedestrians.
Behaviors define the logic that controls how an actor moves or reacts during simulation. You can author behaviors using MATLAB System objects or Simulink models.
Observers are special scenario-level analysis components which can read scenario states without modifying them during simulation. Unlike behaviors, observers exist only within MATLAB or Simulink and are not recognized by RoadRunner. The purpose of observers is to allow for custom computations, for example, visualization and runtime analysis of simulation data, such as detecting when vehicles exceed a speed threshold or get too close to each other.

This table outlines the roles of behaviors and observers, its purpose, workflow steps and implementation options:

Simulation Role	Purpose and Workflow Steps	Getting Started Examples
Observer	Use observers to only read scenario simulation states without modifying them and then perform runtime analysis of simulation data in MATLAB and Simulink Author MATLAB System objects or Simulink models to define observers. Add observers to the scenario.	Simulate RoadRunner Scenarios with Observers Modeled in MATLAB or Simulink
Behavior	Use actor behaviors to control actors during the simulation and also read the simulation states. Author MATLAB System objects or Simulink models to define actor behavior. Associate actor behavior in RoadRunner. Optionally, publish the actor behavior. Tune parameters defined in MATLAB or Simulink for RoadRunner simulations.	Simulate RoadRunner Scenarios with Actors Modeled in MATLAB Simulate RoadRunner Scenarios with Actors Modeled in Simulink

After setting up either an observer or an actor behavior, you can simulate the scenario using the RoadRunner user interface, or control simulations programmatically from MATLAB.

If you are using actor behaviors to cosimulate a scenario, you can log simulation data, inspect simulation results from the log, and replay the scenario simulation using the saved simulation log.

You can also store the scenario simulation data in ASAM Open Simulation Interface (OSI)^® file format.

For an overview of cosimulating RoadRunner scenarios using MATLAB and Simulink, see Overview of Simulating RoadRunner Scenarios with MATLAB and Simulink.

Functions

expand all

Set Up MATLAB Interface for Scenario Simulation

`ScenarioSimulation`	Create, access, and control RoadRunner Scenario simulations from MATLAB (Since R2022a)
`addAction`	Add user-defined action in MATLAB actor interface (Since R2023a)
`addEvent`	Add user-defined event in MATLAB actor interface (Since R2023a)
`get`	Get value of scenario simulation parameter (Since R2022a)
`load`	Load saved simulation log (Since R2023a)
`reportDiagnostic`	Report information, warning, or error message during scenario simulation (Since R2022a)
`save`	Save simulation log to file for later use (Since R2023a)
`set`	Set value of scenario simulation parameter (Since R2022a)
`Simulink.ScenarioSimulation.find`	Return scenario simulations or actors in current MATLAB session (Since R2022a)

Observers for Scenario Simulation

`addObserver`	Add observer to scenario simulation (Since R2022a)
`removeObserver`	Remove observer from scenario simulation (Since R2022a)

Actor Behaviors for Scenario Simulation

`ActorSimulation`	Access and modify runtime specifications of RoadRunner Scenario actor in MATLAB (Since R2022a)
`ActorModel`	View static specifications of RoadRunner Scenario actor in MATLAB (Since R2022a)
`sendEvent`	Send event to scenario (Since R2022b)
`receiveEvent`	Receive event from scenario (Since R2023a)
`convertToStruct`	Convert actor to MATLAB structure (Since R2022a)
`get`	Get scenario or static attribute of actor (Since R2022a)
`getAction`	Get actions associated with actor (Since R2022a)
`getAttribute`	Get run-time attribute of actor (Since R2022a)
`setAttribute`	Set run-time attribute of actor (Since R2022a)
`getAttribute`	Return static attribute of actor (Since R2022a)
`reportDiagnostic`	Report information, warning, or error message during scenario simulation (Since R2022a)
`Simulink.ActorSimulation.createMATLABStruct`	Create MATLAB structure for bus object for RoadRunner (Since R2024a)
`Simulink.ActorSimulation.load`	Load built-in RoadRunner bus definitions into MATLAB workspace (Since R2024a)

Add Sensors to Scenario Simulation

`SensorSimulation`	Add sensors and access sensor data from RoadRunner Scenario simulation (Since R2023a)
`addSensors`	Add sensors to vehicle actors in RoadRunner scenario (Since R2023a)
`targetPoses`	Get positions and orientations of targets in sensor range from RoadRunner Scenario (Since R2023a)
`laneBoundaries`	Get lane boundaries relative to host vehicle from RoadRunner Scenario (Since R2023a)

Publish Actor Behavior, Custom Action and Events

`publishActor`	Generate package for actor simulation (Since R2022a)
`publishActorBehavior`	Generate proto file for actor simulation (Since R2022a)
`publishCustomAction`	Generate asset file for user-defined action (Since R2022b)
`publishCustomEvent`	Generate asset file for user-defined event (Since R2023a)

Log Scenario Simulation Data

`ScenarioLog`	View RoadRunner Scenario simulation outcomes in MATLAB at any time step (Since R2022a)
`get`	Get logged scenario simulation data (Since R2022a)
`view`	View logged scenario simulation data (Since R2024a)

Export Scenario Data to ASAM Open Simulation Interface (OSI) Format

`openSimulationInterface`	Store RoadRunner Scenario simulation data in ASAM Open Simulation Interface (OSI) format (Since R2024b)
`groundTruthArea`	Ground truth area centered at ego vehicle origin (Since R2025a)
`startRoadRunnerSimulation`	Start RoadRunner Scenario simulation (Since R2024b)
`write`	Write OSI data to binary file (Since R2024b)
`getProtoMessage`	Get OSI protocol buffer (protobuf) message at each simulation step (Since R2024b)

Visualize Scenario in Unreal Engine 3D Viewer

`sim3d.scenario.ActorBehavior`	Define RoadRunner actors that use Unreal Engine viewer visualization (Since R2023b)
`onSimulationStart`	Specify code to run at start of simulation (Since R2023b)
`onSimulationStop`	Specify code to run at end of simulation (Since R2023b)
`onSimulationStep`	Specify code to run at each time step (Since R2023b)
`matrix2transform`	Convert 4-by-4 pose matrix to translation, rotation, and scale vectors (Since R2023b)
`transform2matrix`	Convert translation, rotation, and scale vectors to 4-by-4 pose matrix (Since R2023b)

Use Scenario Services

`ScenarioServices`	Perform calculations on scene elements of RoadRunner Scenario in MATLAB (Since R2024b)
`get`	Get calculations on scene elements of RoadRunner Scenario in MATLAB (Since R2024b)

Blocks

RoadRunner Scenario	Define interface for Simulink actor model (Since R2022a)
RoadRunner Scenario Reader	Reads selected topic from `RoadRunner` scenario (Since R2022a)
RoadRunner Scenario Writer	Write selected topic to `RoadRunner` scenario (Since R2022a)

Apps

Bird's-Eye Scope

Visualize sensor coverages, detections, and tracks

Topics

Set Up MATLAB Interface for Scenario Simulation

Overview of Simulating RoadRunner Scenarios with MATLAB and Simulink
This topic describes workflows to create actor behaviors in MATLAB or Simulink, associate the behaviors with graphical actors in RoadRunner Scenario, start the scenario simulation in RoadRunner, and log simulation results for further analysis.
Connect MATLAB and RoadRunner to Control and Analyze Simulations
Use MATLAB with RoadRunner to control simulations programmatically and model actors in MATLAB or Simulink.

Add Observers to Scenario Simulation

Simulate RoadRunner Scenarios with Observers Modeled in MATLAB or Simulink
Author observers as MATLAB System object™ files or Simulink models and add to a RoadRunner scenario.

Model Actor Behaviors for Scenario Simulation

Simulate RoadRunner Scenarios with Actors Modeled in Simulink
Author RoadRunner actor behaviors in Simulink and associate actor behavior in RoadRunner.
Simulate RoadRunner Scenarios with Actors Modeled in MATLAB
Author RoadRunner actors as MATLAB System object files and associate behaviors in RoadRunner.
Simulate RoadRunner Scenarios with Traffic Signals in MATLAB
Simulate RoadRunner Scenarios containing traffic signal actors in MATLAB.
What Is a RoadRunner Pose Matrix?
Understand the position and orientation of a RoadRunner actor using its four-by-four pose matrix.

Add Sensors to Scenario Simulation

Add Sensors to RoadRunner Scenario Using MATLAB
Simulate a RoadRunner Scenario with sensor models defined in MATLAB and visualize object and lane detections.
Add Sensors to RoadRunner Scenario Using Simulink
Simulate a RoadRunner Scenario with sensor models defined in Simulink and visualize object and lane detections.
Publish Ground Truth and Sensor Data from RoadRunner Scenario to ROS 2 Network (ROS Toolbox)
Publish ground-truth and sensor data from a RoadRunner scenario to ROS 2 network and visualize it using ROS Data Analyzer app. (Since R2025a)

Publish Actor Behavior, Custom Action and Events

Publish Actor Behavior as Proto File, Package, Action Asset or Event Asset
Publish your Simulink or MATLAB System object actor behaviors as proto files, packages, action asset files or event asset files.
Publish Ready-to-Run Actor Behaviors for Reuse and Simulation Performance
Publish your Simulink or MATLAB System object actor behaviors with Matlab System blocks as ready-to-run packages to improve simulation performance.

Visualize Scenario in Unreal Engine 3D Viewer

Simulate RoadRunner Scenarios with Actors Modeled in MATLAB and View in Unreal Engine 3D Viewer
Define custom actor behavior and visualize RoadRunner simulations in 3D using sim3d.scenario.ActorBehavior object.

Featured Examples

Speed Action Follower with RoadRunner Scenario

Design a speed action following actor behavior using MATLAB and cosimulate with RoadRunner Scenario.

Open Live Script

Highway Lane Following with RoadRunner Scenario

Simulate highway lane following application, designed in Simulink, with RoadRunner Scenario.

Open Example

Lane-Level Path Planning with RoadRunner Scenario

Design a lane-level path planner in MATLAB and cosimulate with RoadRunner Scenario.

Open Live Script

Lateral Offset Follower with High-Fidelity Vehicle Dynamics

Simulate a lateral offset action follower, designed in Simulink, with RoadRunner Scenario.

Open Script