Simulation 3D Actor

Create actors in 3D environment

Since R2022b

• 

Libraries:
Simulink 3D Animation / Simulation 3D / Actors

Description

The Simulation 3D Actor block implements an actor in the Unreal Engine^® environment. You can use this block to:

• Create a movable sim3d.Actor object as the root actor and specify actor name.

• Set how the actor is created and behaves during simulation.

• Control actors created using other Simulation 3D Actor block in the 3D environment.

• Specify source file to import 3D files for building an appearance for the actor.

• Initialize the actor including defining the actor appearance using 3D graphic primitive shapes or mesh data.

• Report object interaction events for the actor. By default, the actor enables hit event.

• Create and add other sim3d actor objects to the 3D environment as children of this actor.

Examples

Create Light Using Simulink

This example shows how to create custom lighting with a point light, a spot light, and a rectangular light using the Simulation 3D Actor block. First, create a room in the 3D environment. Next, create three actors using sim3d.Actor objects, add them as child actors of the room, and position them inside the room. Then, create a point light, a spot light, and a rectangular light, add them as child actors of the room, and position them above the actors inside the room. Finally, in the Simulation 3D Viewer, view the room and its actors illuminated by the different types of light.

Open the model.

open_system("CreateLightUsingSimulink.slx");

The model includes a Simulation 3D Scene Configuration block and a Simulation 3D Actor block. The Simulation 3D Scene Configuration block implements a 3D simulation environment and sets a view in the scene with the Scene view parameter. The Simulation 3D Actor block, named Room, creates an actor in the 3D environment. The block first creates an empty actor named Room, as specified by the Actor name parameter. The block then runs the Initialization script. In the Initialization script, use Actor as the handle to the actor object created by the Simulation 3D Actor block and World as the handle to the world object created by the Simulation 3D Scene Configuration block. The script builds a box shape for Actor using the createShape function to create a room in the 3D environment and set the properties of the room to visualize the custom lighting. The Initialization script then creates three actors using sim3d.Actor objects with box, sphere, and cone shapes. Set the translation of the actors to position them inside the room. Add the actors to World as child actors of Actor. The Initialization script finally creates a point light, spot light, and rectangular light using the sim3d.Light objects, positions the lights above the actors inside the room, and adds them to World as child actors of Actor. Transform properties of an actor are relative to its parent actor. Set the properties of the child actors for enhanced lighting effects.

Simulate the model and view the custom lighting in the Simulation 3D Viewer. You can visualize the reflections of each light type on the wall behind the actors.

sim("CreateLightUsingSimulink.slx");

close_system("CreateLightUsingSimulink.slx");

Create Annotations Using Simulink

Create arrows and text labels in the 3D environment and attach them to an actor using Simulation 3D Actor block.

Open the model.

open_system("CreateAnnotationsUsingSimulink.slx");

The model includes Simulation 3D Scene Configuration and Simulation 3D Actor blocks. The Simulation 3D Scene Configuration block implements a 3D simulation environment and sets a view in the scene that you specify with the Scene view parameter. The Simulation 3D Actor block named Box creates a box actor in the 3D environment. The block creates an empty actor with the name you specify in the Actor name parameter. Then, the block runs the Initialization script. In the Initialization script, use Actor as the handle to the actor object created by the Simulation 3D Actor block and World as the handle to the world object created by the Simulation 3D Scene Configuration block. The Initialization script builds a box shape for the Actor object using the createShape function. The Initialization script then creates arrows and text labels as child actors of the Actor object using the sim3d.graphics.Arrow and sim3d.graphics.Text objects, respectively. Set the properties of the box, arrows, and text labels. Transform properties of the child actors are relative to the parent actor.

Simulate the model and view the annotated box actor in the Simulation 3D Viewer.

sim("CreateAnnotationsUsingSimulink.slx");

close_system("CreateAnnotationsUsingSimulink.slx");

Create and Control Actors

This example shows how to create actors and dynamically control them using the operation modes of Simulation 3D Actor block. You can create actors during simulation and control existing actors by name or instance number.

Use the Operation parameter of the Simulation 3D Actor block to set the block behavior to one of these options:

• Create at setup – Create actors before the simulation starts.

• Create at step – Create actors dynamically during simulation.

• Reference by name – Control an actor using its name.

• Reference by instance number – Control an actor using its instance number.

For more details, see Operating Modes.

In this example, you create a 3D environment with a plane and pyramid. Then, you create ball actors dynamically during simulation. You also control the properties of the pyramid and ball actors using their names and instance numbers.

Open Model

Open the Simulink model.

open_system("OperationModesOfActorBlock");

Explore Model

The model includes Simulation 3D Scene Configuration block and Simulation 3D Actor blocks. You must include the configuration block when building Simulink models with Simulation 3D Actor blocks.

Each Simulation 3D Actor block connects its Valid output port to a display, which shows whether the specified actor exists in the 3D environment. The display shows 1 if the actor is present and 0 if it is not.

The model includes these areas:

• Create 3D Environment — This area includes a Simulation 3D Scene Configuration block to create the 3D environment. You can configure the view of the 3D environment or define a custom viewpoint using the Simulation 3D Scene Configuration block.

• Create at setup — This area includes two Simulation 3D Actor blocks with the Operation parameter set to Create at setup. During setup, the Simulation 3D Actor block named Plane creates a plane actor and the block named Pyramid creates a pyramid actor in the 3D environment.

• Reference by name — This area includes a Simulation 3D Actor block named Control pyramid, with the Operation parameter set to Reference by name. The block uses the actor name specified in the Actor name parameter to identify the pyramid actor in the 3D environment and control its color.

• Create at step — This area includes a Simulation 3D Actor block named Ball, with the Operation parameter set to Create at step. This setting creates a input port Instance. The block generates actors during simulation based on the value at the Instance port. Use a Ramp block and a Round block to generate the integer instance value. When the Instance value is positive, the block creates an actor named 'Actor name + Instance value'.

• Reference by instance number — This area includes a Simulation 3D Actor block named Control Ball, with the Operation parameter set to Reference by instance number. This setting creates the input port Instance. Based on the value at the Instance port, the block looks for the actor with the name 'Actor name + Instance value' in the environment and controls its Transparency property.

Simulate Model

Simulate the model and, in the Simulation 3D Viewer, view the pyramid actor created at the start of the simulation along with the plane actor and the ball actors created during the simulation.

sim("OperationModesOfActorBlock");

You can see the pyramid changes color and the ball actors changes its transparency.

Close Model

Close the Simulink model.

close_system("OperationModesOfActorBlock");

Report Events Using Simulink

This example shows how to report actor events in the Unreal Engine® simulation environment using Simulink®. Use the HitEventEnabled, OverlapEventEnabled, and Collisions properties of the actor object to report hit and overlap events. Click event is enabled by default.

First, create a 3D environment. Then, build box actors and set the properties of actor objects to simulate the actors and report events. Then, enable event ports to display the events. Finally, create annotation actors to indicate the start of click event and view the animation in the Simulation 3D Viewer window.

You can detect these actor events:

• Hit event

• Begin overlap event

• End overlap event

• Click event

Unreal Engine® uses the physics engine to control actor motion and perform real-time physics calculations when the physics property of an actor is enabled.

Open Model

Open the model.

open_system("ReportEvents.slx");

Explore Model Components

The model includes a Simulation 3D Scene Configuration block and Simulation 3D Actor blocks to create a 3D environment with actors. The Simulation 3D Scene Configuration block implements the 3D environment. Double-click the Simulation 3D Scene Configuration block to open the Block Parameters dialog box and set a custom viewpoint.

The Simulation 3D Actor block named Actors creates five box actors to report the hit event, overlap event, and click event. For this example, use Clock and Switch blocks to enable gravity for box actors to simulate and report the hit event and overlap event one after the other. Use the Inputs tab of the Simulation 3D Actor block to enable the input ports Box1.Gravity and Box3.Gravity to set the gravity of box actors during simulation. Use the Events tab of the Simulation 3D Actor block to enable the output ports Box1.HitEventOUT, Box3.BeginOverlapEventOUT, Box3.EndOverlapEventOUT, and Box5.ClickEventOUT, and display the events using a Scope block. You can also enable event ports to access the actor properties listed in the Event Attributes. You can use a To Workspace block to store the name or identifier of the actor that participates in an event.

The Simulation 3D Actor block named Annotation creates annotation actors using the sim3d.graphics.Text and sim3d.graphics.Arrow objects to visualize the click event. The text label displays Click the box, and an arrow points to the box actor to visualize the click event.

Simulate Model

Simulate the model. The Simulation 3D Viewer Window displays five box actors. During simulation, the actors named Box1 and Box2 display the hit event. After the hit event, Box3 starts to overlap Box4. The Simulation 3D Viewer displays Click the box and an arrow points at Box5. To report the click event, click Box5. You can also view the reported events in the Scope block.

sim("ReportEvents.slx");

Close Model

Close the Simulink model.

close_system("ReportEvents.slx");

Extended Examples

Simulate a Quadcopter

Use Simulation 3D Actor block to simulate a quadcopter.

• Open Live Script

Create Multiple Instances of Actors

Use For Each Subsystem block to create multiple instances of an actor.

• Open Model

Delete Actor During Simulation Using Simulink

Remove an actor during simulation from the Unreal Engine visualization environment using Simulink^®.

• Open Live Script

Annotate Vehicle Simulation

Use Simulation 3D Actor block to create and add annotations to the 3D environment.

• Open Live Script

Ports

Input

Instance — Instance number of actor

real integer

Instance number of actor, specified as a real integer.

• For positive values, a new actor is created if it has not been created already. The reference block refers to this actor if the actor is present in the world.

• For negative values, actor instances are deleted, if they exist. For example, instance 1 is deleted if the value of this port is -1 at a given time step.

Dependencies

This input is visible when the operating mode of the block is set to either Create at step or Reference by instance number.

Output

Valid — Validity of specified actor

false (default) | true

Validity of the specified actor, returned as false if the specified actor cannot be found in the world or true if the actor is found.

Parameters

Main

Actor Name — Name of actor

Sim3dActor1 (default) | string

Name of the root actor for the current Simulation 3D Actor block.

Parent Name — Parent of actor

Scene Origin (default) | string

Name of the parent actor of the actor, specified as a string.

Operation — Operating mode of block

Create at setup (default) | Create at step | Reference by name | Reference by instance number

Operating mode that determines block behavior, specified as one of these options.

• Create at setup – Use this option to create actors in the scene. The actors are created during game setup, before the simulation runs. You can also control the simulation of these actors using the Input, Output, and Event ports.

• Create at step – Use this option to dynamically create and delete actors when the simulation is running. An Instance input port of the type int is created in this mode, and the actors are dynamically generated based on the values input to the block. If the value of Instance is greater than zero, an actor with the name 'Actor name + Instance value' is created. The name of the actor is derived from 'Actor Name' in the block mask. The instance value is the current value of the port. When the value of Instance is negative and an actor with the same instance number exists, then the actor is deleted. Unlike the Create at setup option, you cannot control the actors created with this option selected in the block mask.

• Reference by name – Use this option to refer to an actor in the scene using Actor Name, and control this actor's simulation using the inputs of the block. Get data of the actor using the outputs or events. This also provides a Valid output port.

  If an actor with the specified name is not present, the Valid port returns false or 0. In this case, default values will be passed as output for rest of the out ports (if any). Use the Valid port to verify whether the other outputs generated are currently valid or not.

  Note

  Path to source file and Initialization script parameters are unavailable in the Reference by name operating mode.

• Reference by instance number – Use this option to refer to an instance created via a different actor block. Similar to the Create at step operating mode, this option creates an Instance input in the block, and the effective actor name 'Actor name + Instance value' is used to reference the actor.

  If an actor with the generated name is not present, the Valid port returns false or 0. In this case, default values are passed as output for rest of the output ports, if any. Use the Valid port to verify whether the other outputs generated are currently valid or not.

  Note

  Path to source file and Initialization script parameters are unavailable in the Reference by instance number operating mode.

Dependencies

The Transform tab is available if you set Operation as either Create at setup or Create at step.

Path to source file — File from which actors are sourced

string

File from which actors are sourced, specified as a string.

This option loads a 3D file or imports a sim3d.Actor object, including child actor objects.

The supported sources are:

File Formats

• MAT (MAT file from MATLAB^®)

• STL (Stereolithography)

• FBX (Autodesk^® Filmbox format)

• URDF (Unified Robot Description File)

• X3D (Extensible 3D)

• WRL (Virtual Reality Modeling Language)

• DAE (Collada digital asset exchange)

• USD, USDA, USDC (Universal Scene Description)

You can also instantiate actors using .m files.

Alternatively, the Select button can also be used to select a file from the Windows^® file browser.

Note

USD file import is not supported on Linux^®. USD files do not support collision detection.

Initialization script — Code to initialize actor

MATLAB script

Code to initialize the actor created by the block, specified as a MATLAB script.

For example, this sample script creates a box actor and initializes its values. The sample script is also included in the block when you open a new block.

% Reserved keywords:
% - Actor : handle to this actor object
% - World : handle to the world object

% Create a primitive geometry (optional)
createShape(Actor, 'box', [1 1 1]);

% Initialize values (optional)
Actor.Physics = true;
Actor.Color = [1 0 0];

This MATLAB script runs when the 3D environment initializes the actors created by the block. The order of actor creation is:

1. Root actor with specified name is created.

2. The Path to source file is loaded into the root actor.

3. The Initialization script runs.

You can instantiate additional actor objects in the 3D environment as children of the root actor. You can set their properties and add them to the 3D environment. Use the name Actor when modifying the root actor of the block. Actor is a reserved handle in the initialization script. To add an actor as child of the root actor, set Actor as the parent in the add function. Alternatively, use the findBy function to get the actor handle of a different name, for example, one of the child actors. Then, use the retrieved actor handle to initialize that specific actor.

Use the name World for actors in the 3D environment. World is a reserved handle in the initialization script for the 3D environment created by the Simulation 3D Scene Configuration block.

You can create and add these sim3d actor objects.

• sim3d.Light

• sim3d.graphics.Arrow

• sim3d.graphics.Text

• sim3d.graphics.PathMarker

Initialization script does not use the base workspace variables.

Sample time — Sample time

-1 (default) | scalar

Sample time, T_s. The graphics frame rate is the inverse of the sample time.

If you set the sample time to -1, the block uses the sample time specified in the Simulation 3D Scene Configuration block.

For optimal performance, check that this value is not less than the value of Sample time specified in the Simulation 3D Scene Configuration block.

Transform

The Transform tab is available to set the initial transform properties when you set Operation as either Create at setup or Create at step. Otherwise, the transform properties set in the Initialization script are used in the Transform tab and overwrite any values set there.

Translation — Relative translation

[0,0,0] (default) | real 1-by-3 vector

Translation (x,y,z) of the actor object relative to its parent actor, specified as a real 1-by-3 vector, in meters.

Dependencies

The Translation property set in the Initialization script overwrites this parameter value.

Rotation — Relative rotation

[0,0,0] (default) | real 1-by-3 vector

Rotation (Roll, Pitch, Yaw) of the actor object relative to its parent actor, specified as a real 1-by-3 vector, in radians. The rotation order is Roll, then Pitch, then Yaw. When you update any of the three rotation values and leave others unchanged, the software reapplies all three rotations in the same order.

Dependencies

The Rotation property set in the Initialization script overwrites this parameter value.

Scale — Relative scale

[1,1,1] (default) | real 1-by-3 vector

Relative scale in x, y and z coordinates, specified as a real 1-by-3 vector.

Dependencies

The Scale property set in the Initialization script overwrites this parameter value.

Note

Setting the initial transform properties in the Initialization script overwrites the Transform tab values.

Inputs

Input ports — List of user-selected input ports

text area

This text area lists the user-selected input ports of the block and provides a button that opens the port selector app, which you can use to modify the input ports. You can also select multiple ports by pressing the Shift or Ctrl key and clicking the port simultaneously. Each line in the text area represents one block port.

You can manually modify the ports using the text area, but using the port selector app is recommended for choosing the ports.

Outputs

Output ports — List of user-selected output ports

text area

This text area lists the user-selected output ports of the block and provides a button that opens the port selector app, which you can use to modify the output ports. You can also select multiple ports by pressing the Shift or Ctrl key and clicking the port simultaneously. Each line in the text area represents one block port.

You can manually modify the ports using the text area, but using the port selector app is recommended for choosing the ports.

Events

Event ports — List of user-selected event ports

text area

This text area lists the user-selected event ports of the block and provides a button that opens the port selector app, which you can use to modify the event ports. You can also select multiple ports by pressing the Shift or Ctrl key and clicking the port simultaneously. Each line in the text area represents one block port.

You can manually modify the ports using the text area, but using the port selector app is recommended for choosing the ports.

More About

Operating Modes

• Create at setup – Use this operating mode to create actors before simulation begins and control the actors when the simulation is running. You can control actors in a simulation by adding input ports to the block using the Inputs tab in the block dialog box. Similarly, you can read specific actor properties using the Outputs tab to create custom output ports for the block.

  The Simulation 3D Actor block implements these steps during actor creation:

  1. An empty root actor is created with an Actor Name equal to the name specified in the block dialog box.

  2. The source file is used to load actors, meshes, or 3D objects into the root actor.

  3. The initialization script is run to initialize the actors that have been created.

  Note

  The initialization script and the source file are optional. However, if both are empty, the block will only create an empty actor in the scene.

  You can use the load function in the initialization script as an alternative to the source file. This command has the same effect as specifying a source file path.

  load(actor, "source_file_path")

• Create at step – Use this operating mode to create actors dynamically during simulation runtime. When the Instance port is a nonzero number, an instance of the specified actors is created. If the instance input is unique, it will only create a new instance for the first step in which it is equal to the input number.

  When this operating mode is selected, the block creates actor instances by creating an empty root actor is created with name equal to specified values of Actor Name + Instance.

  So, if the actor name specified in the dialog box is ActorInst, and value of Instance is specified as 1, then the ActorName for the new instance will be equal to ActorInst1. This process is followed for every new instance that is created.

  Note

  The Valid output port for this mode returns 0 (false) by default and returns 1 (true) when an instance is created.

• Reference by name – Use this operating mode to control an actor that is already present in the scene. The block looks for an actor with the actor name specified in the block dialog box. If found, the block controls that specific actor using the specified input ports. You can control the actor in a simulation by adding input ports to the block using the Inputs tab in the block dialog box.

• Reference by instance number – Use this operating mode to control an actor that is already present in the scene. The block looks for an actor with the actor name 'Actor name + Instance value' specified in the block dialog box and the current value of the Instance port. If found, the block controls that specific actor using the specified input ports. You can control the actor in a simulation by adding input ports to the block using the Inputs tab in the block dialog box.

The difference between the Reference by name and Reference by instance number operating modes is that, based on the value of the Instance input port, the Simulation 3D Actor block can control multiple actors during simulation. However, during individual time steps, the block still controls a single actor. In the Reference by name operating mode, the block can control only a single actor during the entire simulation.

Input, Output, and Event Port Modification

Use the Simulation 3D Actor block to control simulation during runtime by modifying the block ports. To control actors during simulation, you can use the Inputs tab of the block mask to add input ports to the block which can then be used to control specific actors.

Similarly, you can use the output and event ports of the block mask to get data about the actors from Unreal Engine. The output ports can be modified from the Outputs and Event tabs in the dialog box. Selecting event ports on the Event tab creates corresponding output ports on the block.

The Browse buttons in Inputs, Outputs, and Events text area opens up the port selection app, which you can use to add or delete input and output ports. Select the actor from the Actor hierarchy to display its corresponding ports. Although ports can be modified manually, the suggested method is to use the port selection app.

This table provides the possible input, output, and event Properties of the sim3d.Actor.

Type	Properties
Input and output properties	Translation Rotation Scale Color Transparency Shininess Metallic Mass CenterOfMass Collisions Force Torque AngularVelocity LinearVelocity Friction Restitution
Event properties	Hit Event HitEvent HitSelfID HitLocation HitOtherID HitOtherActorName Begin Overlap Event BeginOverlapEvent BeginOverlapSelfID BeginOverlapOtherID BeginOverlapOtherActorName End Overlap Event EndOverlapEvent EndOverlapSelfID EndOverlapOtherID EndOverlapOtherActorName Click Event ClickEvent ClickActorID ClickLocation ClickActorName

Additionally, these are the possible input and output ports of the Simulation 3D Actor block if you add sim3d actor objects.

• Properties of sim3d.Light

• Properties of sim3d.graphics.Arrow

• Properties of sim3d.graphics.Text

• Properties of sim3d.graphics.PathMarker

Actors can be controlled for all operating modes, except Create at step. For all other operating modes, these are some special considerations.

• Create at setup – The port selection app in this mode lists the entire tree hierarchy of actors created in the actor block, and you can use the block ports to control the simulation of the parent as well as child actors. These actors are present throughout the entire simulation, and the outputs of the blocks are always valid.

• Reference by name – In this operating mode, the block can only control a single actor during the simulation, specified using the actor name. If the actor is not present in the world, the block inputs are ignored, the Valid output is false, and the remaining outputs are default values (invalid).

• Reference by instance number – In this operating mode, the Simulation 3D Actor block only controls one actor per time step. In different time steps the block can control different actor based on the value of the Instance input. The port selection app for this operating mode uses * as a placeholder for the actor name. The actor being controlled has the name as a concatenated string: actor name (in block dialog box) + current instance input value. The * wildcard only applies to the Reference by instance number operating mode. Similar to Reference by name operating mode, the Valid output is false whenever the actor currently being referenced is not present in the world.

Version History

Introduced in R2022b

R2026a: Improved communication interface to Unreal Engine

The improved communication interface to Unreal Engine applies incremental updates to transformations such as translation, rotation, and scale. Previously, only the last transformation increment was applied.

R2024b: Create Light and Annotation Actors

Use the Simulation 3D Actor block Initialization script to initialize and add these actors in the 3D environment with tunable block parameters.

• Light using the sim3d.Light object

• Arrow using the sim3d.graphics.Arrow object

• Text using the sim3d.graphics.Text object

R2023b: Tunable Translation, Rotation, and Scale Parameters

These Simulation 3D Actor block parameters are tunable, allowing you to use the For Each Subsystem (Simulink) block to create multiple instances of the same actor type in the virtual world.

• Translation

• Rotation

• Scale

For an example, see Create Multiple Instances of Actors.

R2023a: Communicate Unreal Engine Events

Use the Simulation 3D Actor block event ports to communicate events in the Unreal Engine simulation 3D environment, including when:

• You click on an actor.

• An actor collides or overlaps with another actor.