addActor

Add actor to RoadRunner scenario

Since R2025a

Syntax

rrActor = addActor(scnro,asset,position)

Description

rrActor = addActor(scnro,asset,position) creates an actor using the specified asset and scene location and adds it to the specified scenario. For example, rrActor = addActor(scnro,mySedan,[0 0 0]); adds an actor, rrActor, that uses the asset mySedan to the scenario scnro at the world origin.

Examples

Add Actor to Scenario

Use the addActor function to add an actor to your scenario.

Create a roadrunner object, specifying the path to an existing project. For example, this code shows the path to a project, on a Windows^® machine, located at "C:\RR\MyProject". This code assumes that RoadRunner is installed in the default location, and returns an object, rrApp, that provides functions for performing basic tasks such as opening, closing, and saving scenes and projects.

rrApp = roadrunner(ProjectFolder="C:\RR\MyProject");

Note

If you are opening RoadRunner from MATLAB^® for the first time, or if you have changed the RoadRunner installation location since you last opened it from MATLAB, you can use the roadrunnerSetup function to specify new default project and installation folders to use when opening RoadRunner. You can save these folders between MATLAB sessions by selecting the Across MATLAB sessions option from the corresponding drop down.

Open an existing scene in RoadRunner by using the openScene function, specifying the roadrunner object rrApp and the filename of the specific scene that you want to open. Then, use the newScenario function to create a new scenario.

openScene(rrApp,"ScenarioBasic.rrscene")
newScenario(rrApp)

Create an object for the RoadRunner authoring API, rrApi, that references the object for the current RoadRunner instance rrApp. The rrApi object enables you to programmatically author scenes and scenarios, such as by adding and modifying roads, actors, and logic components, using MATLAB.

rrApi = roadrunnerAPI(rrApp);

Extract the scene and scenario objects from the Scene and Scenario properties of the authoring API object rrApi, respectively. The extracted Scene object enables you to specify the scene in which to add scene components such as roads and lanes. The extracted Scenario (RoadRunner Scenario) object enables you to specify the scenario in which to add scenario components such as actors and logic.

scn = rrApi.Scene;
scnro = rrApi.Scenario;

Extract the object for your RoadRunner project from the Project property of the authoring API object rrApi. The extracted Project object enables you to specify the project folder for the current RoadRunner session from which to retrieve asset objects. You can use the asset objects to assign assets to roads in your scene, or to actors in your scenario.

prj = rrApi.Project;

Add a Vehicle actor to the scenario. Use the getAsset function to extract a VehicleAsset object, mySedan, that represents the Sedan.fbx asset in the project prj. Then, use addActor to specify the scenario object scnro, the asset object, and the location at which to place the actor. Place the vehicle actor car at the world origin, specified as [0 0 0].

mySedan = getAsset(prj,"Vehicles/Sedan.fbx","VehicleAsset");
car = addActor(scnro,mySedan,[0 0 0]);

If you do not know the exact coordinates at which you want to place the actor, you can relocate the actor based on an existing point or anchor. For example, you can use findSceneAnchor to reference an existing anchor in the scene, then use anchorToPoint to relocate the actor from the current location to the location specified by the referenced anchor. For more information, see findSceneAnchor and anchorToPoint.

anchorPoint = findSceneAnchor(scnro,"ScenarioStart");
carPoint = car.InitialPoint;
anchorToPoint(carPoint,anchorPoint,PosePreservation="reset-pose")

Run the simulation by using the simulateScenario function. If you do not specify a BehaviorAsset object or logic phases to alter actor behavior, the actor performs the default lane-following behavior.

simulateScenario(rrApp)

Input Arguments

scnro — Scenario to which to add actor

Scenario object

Scenario to which to add the actor, specified as a Scenario object.

Example: rrActor = addActor(scnro,mySedan,[0 0 0]); adds an actor, rrActor, that uses the mySedan vehicle asset to the scenario scnro at the world origin.

asset — Asset to represent new actor

VehicleAsset object | CharacterAsset object | MovableObjectAsset object

Asset to represent the new actor, specified as one of these objects:

• VehicleAsset — Represents an asset with the Vehicle asset type.

• CharacterAsset — Represents an asset with the Character asset type.

• MovableObjectAsset — Represents an asset with the Movable Object asset type.

To represent an actor, the specified asset must be an .rrvehicle, .rrchar, or .fbx file.

position — World position at which to place new actor

three-element vector

World position at which to place the new actor, specified as a three-element vector.

Output Arguments

rrActor — Scenario actor

Vehicle object | Character object | MovableObject object

Scenario actor, returned as one of these objects:

• Vehicle — Represents a vehicle actor in the RoadRunner scenario. RoadRunner adds a vehicle actor when you specify asset as a VehicleAsset object.

• Character — Represents a character actor in the RoadRunner scenario. RoadRunner adds a character actor when you specify asset as a CharacterAsset object.

• MovableObject — Represents a movable object actor in the RoadRunner scenario. RoadRunner adds a movable object actor when you specify asset as a MovableObjectAsset object.

For more information about actors in RoadRunner Scenario, see Actors in RoadRunner Scenario (RoadRunner Scenario).

Version History

Introduced in R2025a