Character
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 of the actor, specified as a string scalar or character vector.
Numeric identifier of the actor, specified as a positive integer.
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.
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).
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.
Initial location of the actor, specified as a Point
object.
Examples
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);
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;
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]);
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
See Also
addActor
| CharacterAsset
| BehaviorAsset
| Vehicle
| MovableObject
Topics
- Actors in RoadRunner Scenario (RoadRunner Scenario)
- Built-In Behavior for Vehicles (RoadRunner Scenario)
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)