ChangeSpeedAction

Specify Change Speed action

Since R2025a

expand all in page

    Description

    The ChangeSpeedAction object represents a Change Speed action in the RoadRunner scenario logic. The Change Speed action specifies for the actor to change speed using the specified properties. Specifying ChangeSpeedAction as the action type when adding an action to your scenario adds a Change Speed action to the specified phase in the scenario logic. You can use the ChangeSpeedAction object to programmatically modify the attributes of the corresponding Change Speed action by changing the property values of the object.

    Creation

    By default, RoadRunner Scenario automatically adds a Change Speed action to the initial phase of an actor when you place the actor in your scenario. You can use the initialPhaseForActor function to extract the object for the initial phase of the actor. Then, extract the ChangeSpeedAction object from the first element of the Actions property of the initial phase.

    You can also use the addAction function to add an action of the specified type as a child to the specified phase. Specify the actionType argument as "ChangeSpeedAction" to create a ChangeSpeedAction object associated with the specified phase.

    Properties

    expand all

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

    Note

    You can specify the Name property of ChangeSpeedAction in MATLAB®, but RoadRunner Scenario does not display the Name property of actions in the user interface.

    Phase containing the action, specified as an ActorActionPhase object.

    Method used to set the speed of the actor, specified as one of these options:

    • "absolute" — The actor travels at Speed m/s.

    • "actor" — The actor travels at Speed m/s relative to the reference actor, given the speed direction specified by Direction.

    • "route-time-data" — The actor travels at Speed m/s specified by the speed values assigned to route points using the Route Timing Tool (RoadRunner Scenario).

    The option you specify changes what the Speed property represents.

    Actor speed, specified as a numeric scalar in meters per second. Depending on the SpeedReference value you specify, Speed is either the absolute speed of the actor, the speed of the actor relative to another actor, or determined by waypoint time data.

    If you specify SpeedReference as "actor" and Direction as "same", then the Speed property does not apply.

    Reference actor against which to compare the speed of the actor, 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.

    To use this property, you must set the value of the SpeedReference property to "actor".

    Speed of the target actor relative to the reference actor speed, specified as one of these options:

    • "faster" — The actor completes the action at Speed m/s faster than the reference actor.

    • "slower" — The actor completes the action at Speed m/s slower than the reference actor.

    • "same" — The actor completes the action at the same speed as the reference actor.

    To use this property, you must set the value of the SpeedReference property to "actor".

    Sampling method used to achieve a speed for the actor relative to ReferenceActor, specified as one of these options:

    • "action-start" — The actor sets its relative speed based on the speed of the reference actor at the start of the action.

    • "continuous" — The actor sets its relative speed based on the speed of the reference actor over the course of the action.

    To use this property, you must set the value of the SpeedReference property to "actor".

    Dynamics dimension for the action transition, specified as "rate", "time", or "distance". The actor uses DynamicsDimension to determine how to achieve the action.

    • "rate" — Actor achieves the action with a specified acceleration rate.

    • "time" — Actor achieves the action over a specified length of time.

    • "distance" — Actor achieves the action over a specified distance.

    The option you specify determines what the value of the DynamicsValue property represents.

    Shape of the dynamics profile that the actor uses to achieve the action, specified as one of these options:

    • "cubic" — The actor action change follows a cubic polynomial over time or distance.

    • "linear" — The actor action changes linearly over time or distance.

    • "step" — The actor action changes step-wise over time or distance.

    • "sinusoidal" — The actor action change follows a sine wave over time or distance.

    To use this property, you must set the value of the DynamicsDimension property to "time" or "distance".

    Value for the dynamics dimension, specified as a positive scalar. This property sets the value for the dynamics dimension specified by the DynamicsDimension property.

    Data Types: double

    Examples

    collapse all

    Use a ChangeSpeedAction object to specify for an actor to change its speed to 30 m/s during simulation.

    This example assumes that you have prior knowledge of working with RoadRunner in MATLAB. Before proceeding, follow the steps outlined in Set Up MATLAB Environment for RoadRunner Authoring Functions to set up your scenario using MATLAB functions for scenario authoring.

    Add ChangeSpeedAction to Scenario Logic

    Use addPhaseInSerial to add a new actor action phase, the srPhase object, in serial after the initial phase. Then, use addAction to specify "ChangeSpeedAction" as the action of the new phase. srPhase represents the newly created actor action phase in the scenario logic, and chSpd represents the Change Speed action assigned to srPhase.

    srPhase = addPhaseInSerial(rrLogic,initPhase,"ActorActionPhase",Insertion="after");
chSpd = addAction(srPhase,"ChangeSpeedAction");

    Assign car to the Actor property of the action phase srPhase. For the Change Speed action chSpd, set the Speed property to 30, the DynamicsDimension property to "time", and the DynamicsValue property to 1. This instructs the assigned actor car to change its speed to 30 m/s over 1 second during simulation.

    srPhase.Actor = car;
chSpd.Speed = 30;
chSpd.DynamicsDimension = "time";
chSpd.DynamicsValue = 1;

    Run the simulation by using the simulateScenario function.

    simulateScenario(rrApp)

    Version History

    Introduced in R2025a

    See Also

    | | | |

    Topics