Character

Specify character actor

Since R2025a

Description

The Character object represents a character actor in the RoadRunner scenario. An actor is an object within a scenario that interacts with scenario logic during simulation. You can use the Character object to programmatically modify the attributes of the corresponding character actor in your scenario by changing the property values of the object.

Creation

You can create a Character object by using the addActor function. The addActor function creates an actor in the scenario using the specified asset and scene location.

Properties

Name — Name of actor

string scalar | character vector

Name of the actor, specified as a string scalar or character vector.

ActorID — Numeric identifier of actor

positive integer

Numeric identifier of the actor, specified as a positive integer.

Color — Color of actor

four-element vector | string scalar | character vector

Color of the actor, specified as a four-element vector of the form [R,G,B,A], a string scalar, or a character vector. If specified as a vector, R, G, B, and A represent the red, green, blue, and alpha values for the actor color, respectively. If specified as a string scalar or character vector, you must use a color name, such as "blue", or a hexadecimal value, such as "#0072BD".

This table lists the named color options, the equivalent RGBA values, and hexadecimal color codes.

Color Name	Short Name	RGBA Value	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0 1]	"#FF0000"
"green"	"g"	[0 1 0 1]	"#00FF00"
"blue"	"b"	[0 0 1 1]	"#0000FF"
"cyan"	"c"	[0 1 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1 1]	"#FF00FF"
"yellow"	"y"	[1 1 0 1]	"#FFFF00"
"black"	"k"	[0 0 0 1]	"#000000"
"white"	"w"	[1 1 1 1]	"#FFFFFF"

Note

You can specify the Color property of Character actors in MATLAB^®, but actors that use externally referenced models, such as an .fbx file, do not visually reflect changes made to the Color property.

ActorAsset — Asset to use for actor

CharacterAsset object

Asset to use for the actor, specified as a CharacterAsset object. For more information on actor asset types, see Actors in RoadRunner Scenario (RoadRunner Scenario).

BehaviorAsset — Actor behavior

[] (default) | BehaviorAsset object

Actor behavior, specified as a BehaviorAsset object. By default, actors do not have an assigned BehaviorAsset asset. Character actors without BehaviorAsset assets or logic phases to alter their behavior move forward along their specified route until they reach the end.

InitialPoint — Initial location of actor

Point object

Initial location of the actor, specified as a Point object.

Examples

Add Character Actor to Scenario

Use the getAsset and addActor functions to add a character actor that uses the Citizen_Male.fbx asset to your RoadRunner 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 Character actor to the scenario. Use the getAsset function to extract a CharacterAsset object, myChar, that represents the Citizen_Male.rrchar asset in the project prj. Then, use the addActor function, specifying the scenario object scnro, the asset object, and the location at which to place the actor. Place the character actor citizenM at the world origin, specified as [0 0 0].

myChar = getAsset(prj,"Characters/Citizen_Male.rrchar","CharacterAsset");
citizenM = addActor(scnro,myChar,[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 its current location to the location specified by the referenced anchor. For more information, see findSceneAnchor and anchorToPoint.

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

Character actors do not follow the default lane-following behavior in RoadRunner Scenario. Before you can run the simulation, you must first specify a route for them to follow.

Design a route for the actor citizemM by extracting the Route property of charPoint to the variable charRoute. Then, use addPoint to add a new point to the route at the specified location.

If you do not know the exact coordinates at which you want to place the new point, you can quickly align it to the same lane as the actor by using anchorToPoint and specifying the same anchor point newPoint as the actor citizenM. Then, set the ForwardOffset property of the new point roadPoint to 50 to move it 50 meters in front of citizenM.

charRoute = charPoint.Route;
roadPoint = addPoint(charRoute,[0 0 0]);
anchorToPoint(roadPoint,anchorPoint,PosePreservation="reset-pose")
roadPoint.ForwardOffset = 50;

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 moves forward along the route until it reaches the end.

simulateScenario(rrApp)

Version History

Introduced in R2025a