Simulation 3D Actor

Define actors in Unreal Engine viewer

Since R2022b

• 

×

Libraries:
Simulink 3D Animation / Simulation 3D

Description

The Simulation 3D Actor block implements a generic actor in the Unreal Engine^® viewer. You can use this block to specify actor name and source file, initialize the actor, and define how the actor is created and behaves during simulation.

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

Remove an actor during simulation using Simulink^® and MATLAB^®.

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 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. Unlike the Create at setup option, you cannot control the actors created using with this option selected in the block mask. You can only create actors in the scene.

• 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 will return 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

  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

  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.

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 from MAT or STL files.

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

Initialization script — Text area to set properties of actor

MATLAB script

Text area to set properties of the actor created by the block, specified as a MATLAB script. The order of actor creation is:

1. Root actor with specified name is created.

2. The Source file is loaded into the root actor.

3. The Initialization script runs.

Use the name Actor when modifying the root actor of the block. Actor is a reserved handle in the initialization script. Otherwise, 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. The 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.

Transform

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

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.

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.

Scale — Relative scaling

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

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

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. 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. 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. 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. 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.

• 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 specified in the block dialog. 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.

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. 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. 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 sim3d.Actor.

Type	Properties
Input and output properties	Translation Rotation Scale Color Transparency Shininess Metallic Mass CenterOfMass Collisions Force Torque AngularVelocity LinearVelocity Friction Restitution
Events 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

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) + 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

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.