ActorActionPhase

Specify logic phase that executes actor action

Since R2025a

expand all in page

    Description

    An ActorActionPhase object represents an actor action phase in the RoadRunner scenario logic. Actor action phases are the components of scenario logic that specify the actions that actors perform during simulation.

    Creation

    You can create an ActorActionPhase object in these ways:

    • The addPhaseInSerial function creates a logic phase with the specified phase type and adds it before or after the specified existing phase in the RoadRunner scenario logic. Specify the phaseType argument as "ActorActionPhase" to create an ActorActionPhase object.

    • The addPhaseInParallel function creates a phase with the specified type and adds it in parallel to the specified existing phase or serial sequence of phases in the RoadRunner scenario logic. Specify the phaseType argument as "ActorActionPhase" to create an ActorActionPhase object.

    • The addPhase function creates a new phase of the specified type and adds it as the last child of the specified serial or parallel phase in the RoadRunner scenario logic. Specify the phaseType argument as "ActorActionPhase" to create an ActorActionPhase object.

    • The initialPhaseForActor function returns the initial phase for the specified actor. If no initial phase exists, this function returns an empty string. By default, initialPhaseForActor returns the initial phase of an actor as an ActorActionPhase object.

    Properties

    expand all

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

    Actor associated with the phase, specified as one of these objects:

    • Vehicle — Represents a vehicle actor in the RoadRunner scenario.

    • Character — Represents a character actor in the RoadRunner scenario.

    • MovableObject — Represents a movable object actor in the RoadRunner scenario.

    Note

    You must specify a nonempty value for this property before you can run the simulation.

    Actions contained in the phase, specified as an array of one of these types of objects:

    • ChangeSpeedAction — Specifies for the actor to change speed using the specified properties.

    • ChangeLaneAction — Specifies for the actor to change lanes using the specified properties.

    • ChangeLateralOffsetAction — Specifies for the actor to change lateral offset using the specified properties.

    • ChangeLongitudinalDistanceAction — Specifies or the actor to change its forward distance relative to another actor using the specified properties.

    • RemoveActorAction — Specifies for RoadRunner Scenario to remove the associated actor from the scenario during simulation run time.

    • SynchronizeAction — Specifies for an actor to arrive at its specified target point at the same time as a reference actor arrives at another specified target point.

    Note

    You must specify a nonempty value for this property before you can run the simulation.

    This property is read-only.

    Parent phase, represented as a ParallelPhase object or SerialPhase object. RoadRunner Scenario returns an empty object if this phase has no parent phase.

    Condition to trigger phase completion, specified as one of these objects:

    • ActorSpeedCondition — Represents an Actor Speed condition in the RoadRunner scenario logic. Specifies for the associated phase to end when an actor reaches the specified speed.

    • DurationCondition — Represents a Duration condition in the RoadRunner scenario logic. Specifies for the associated phase to end after the specified amount of time elapses.

    • CollisionCondition — Represents a Collision condition in the RoadRunner scenario logic. Specifies for the associated phase to end when the actor specified by FirstActor collides with the actor specified by SecondActor.

    • PhaseStateCondition — Represents a Phase State condition in the RoadRunner scenario logic. Specifies for the associated phase to end when the referenced phase reaches the specified state.

    • DistanceToActorCondition — Represents a Distance To Actor condition in the RoadRunner scenario logic. Specifies for the associated phase to end when the actor is a certain distance away from the reference actor.

    • DistanceToPointCondition — Represents a Distance To Point condition in the RoadRunner scenario logic. Specifies for the associated phase to end when an actor is a certain distance away from a specified point.

    • LongitudinalDistanceToActorCondition — Represents a Longitudinal Distance To Actor condition in the RoadRunner scenario logic. Specifies for the associated phase to end when an actor reaches a certain longitudinal distance from another actor.

    • SimulationTimeCondition — Represents a Simulation Time condition in the RoadRunner scenario logic. Specifies for the associated phase to end after the specified amount of time has elapsed since the start of the simulation.

    If any actions are still executing when the condition triggers, RoadRunner Scenario ends those actions early.

    Condition to fail scenario if triggered during phase execution, specified as one of these objects:

    • ActorSpeedCondition — Represents an Actor Speed condition in the RoadRunner scenario logic. Specifies for the associated phase to end when an actor reaches the specified speed.

    • DurationCondition — Represents a Duration condition in the RoadRunner scenario logic. Specifies for the associated phase to end after the specified amount of time elapses.

    • CollisionCondition — Represents a Collision condition in the RoadRunner scenario logic. Specifies for the associated phase to end when the actor specified by FirstActor collides with the actor specified by SecondActor.

    • PhaseStateCondition — Represents a Phase State condition in the RoadRunner scenario logic. Specifies for the associated phase to end when the referenced phase reaches the specified state.

    • DistanceToActorCondition — Represents a Distance To Actor condition in the RoadRunner scenario logic. Specifies for the associated phase to end when the actor is a certain distance away from the reference actor.

    • DistanceToPointCondition — Represents a Distance To Point condition in the RoadRunner scenario logic. Specifies for the associated phase to end when an actor is a certain distance away from a specified point.

    • LongitudinalDistanceToActorCondition — Represents a Longitudinal Distance To Actor condition in the RoadRunner scenario logic. Specifies for the associated phase to end when an actor reaches a certain longitudinal distance from another actor.

    • SimulationTimeCondition — Represents a Simulation Time condition in the RoadRunner scenario logic. Specifies for the associated phase to end after the specified amount of time has elapsed since the start of the simulation.

    Examples

    collapse all

    Use initialPhaseForActor to extract an ActorActionPhase object for the initial phase of an actor.

    Set Up 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;

    Extract ActorAcionPhase Object from Actor Initial Phase

    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 the addActor function, specifying 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 its 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")
    Extract the phase logic in your RoadRunner scenario from the PhaseLogic property of your scenario object scnro. By default, RoadRunner Scenario creates an initial phase in the scenario logic for each actor added to a scenario. Use the initialPhaseForActor function to extract the object for the initial phase of the actor car. You can use the initial phase object initPhase to modify the properties of the initial phase or specify subsequent logic phases.
    rrLogic = scnro.PhaseLogic;
initPhase = initialPhaseForActor(rrLogic,car);

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

    simulateScenario(rrApp)

    Version History

    Introduced in R2025a

    See Also

    | | | |