Report Events Using Actor Callbacks

Open Live Script

This example shows how to report actor events in the Unreal Engine® simulation environment and access actor Properties during simulation using MATLAB®. You use the HitEventEnabled, OverlapEventEnabled and Collisions properties of the actor object to report hit and overlap events. Click event is enabled by default. Use the actor callbacks to access actor properties, including Event Attributes.

First, you create a 3D environment and build box actors and a plane actor with sim3d.World and sim3d.Actor objects and functions. Then, you set function handles for actor objects to execute event callback functions when an actor participates in an event. Then, you set the properties of actor objects to simulate the actors and report events. Then, you add the actors to the world, set a view in the scene, and set up event callback functions. The event callback function passes the actor handle as the input argument to access the actor properties when an event occurs during simulation and creates annotation actors with sim3d.graphics.Text and sim3d.graphics.Arrow to indicate the start of click event. Finally, view the animation in the Simulation 3D Viewer window and the actor properties corresponding to the actor event as the output.

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.

Create World

Create a 3D environment and set up communication with the Unreal Engine simulation environment using the update function UpdateImpl. The sim3d.World object can send and receive data about a sim3d.Actor object to and from the Unreal Engine at each simulation step using output and update functions, respectively. The Unreal Engine executes at each time step and sends data to MATLAB in the update function. For this example, the update function is used to increment the simulation step value after each simulation step and set actor properties so that the events occur one after the other.

world = sim3d.World('Update',@UpdateImpl);

Enable Hit Event

Instantiate an actor named box1. Set the position of the actor using the Translation property. To simulate and report a hit event, set the Mobility, Physics, and HitEventEnabled properties of the actor. The Collisions property is true by default. The OnHit function handle represents the hit event callback function OnHitImpl. Use the OnHitImp function to access the properties of box1. Use the createShape function to build a box shape for the actor, set the size of the box, and set the color of the box. Add the actor to the world.

% Create actors for Hit event in scene
box1 = sim3d.Actor( ...
    ActorName='Box1', ...
    Translation=[8 -5 6], ...
    Mobility=sim3d.utils.MobilityTypes.Movable, ...
    OnHit=@OnHitImpl);
createShape(box1,'box',[2 2 2]);
box1.Color = [1 0 0];
box1.Physics = true;
box1.HitEventEnabled = true;
add(world,box1);

Instantiate an actor named box2. Set the Translation, Mobility, Physics, and Color properties of the actor. Use the createShape function to build a box shape for the actor and set the size of the box. Add the actor to the world.

box2 = sim3d.Actor( ...
    ActorName='Box2', ...
    Translation=[8 -5 2], ...
    Mobility=sim3d.utils.MobilityTypes.Movable);
createShape(box2,'box',[2 2 2]);
box2.Color = [0 0 1]; 
box2.Physics = true;
add(world,box2);

For this example, the OnHitImpl function executes when box1 hits box2 in the scene.

Enable Overlap Event

Instantiate an actor named box3. Set the position of the actor using the Translation property. To simulate and report an overlap event, set the Mobility, Physics, OverlapEventEnabled and Collisions properties of the actor. The OnBeginOverlap and OnEndOverlap function handles represent the overlap event callback functions OnBeginOverlapImpl and OnEndOverlapImpl, respectively. Use these functions to access the properties of box3 when the overlap event begins and ends. Use the createShape function to build box shape for the actor, set the size of the box, and set the color of the box. Add the actor to the world.

% Create actors for Overlap event in scene
box3 = sim3d.Actor( ...
    ActorName='Box3', ...
    Translation=[8 0 6], ...
    Mobility=sim3d.utils.MobilityTypes.Movable, ...
    OnBeginOverlap=@OnBeginOverlapImpl, ...
    OnEndOverlap=@OnEndOverlapImpl);
createShape(box3,'box',[2 2 2]);
box3.Color = [1 0 0];
box3.Physics = true;
box3.Collisions = false;
box3.OverlapEventEnabled = true;
add(world,box3);

Instantiate an actor named box4. Set the Translation, Collisions, and Color properties of the actor. Use the createShape function to build a box shape for the actor and set the size of the box. Add the actor to the world.

box4 = sim3d.Actor(ActorName='Box4',Translation=[8 0 2]);
createShape(box4,'box',[2 2 2]);
box4.Color = [0 0 1]; 
box4.Collisions = false;
box4.OverlapEventEnabled = true;
add(world,box4);

For this example, the OnBeginOverlapImpl function executes when box3 begins to overlap box4. The OnEndOverlapImpl function executes when box3 stops overlapping box4.

Enable Click Event

Instantiate an actor named box5. Set the position of the actor using the Translation property. To report a click event, click on the actor. The OnClick function handle represents the click event callback function OnClickImpl. Use this function to access the properties of box5 when you click the actor during simulation. Use the createShape function to build a box shape for the actor, set the size of the box, and set the color of the box. Add the actor to the world.

% Create actors for Click event in scene
box5 = sim3d.Actor( ...
    ActorName='Box5', ...
    Translation=[8, 5, 6], ...
    OnClick=@OnClickImpl);
createShape(box5,'box',[2 2 2]);
box5.Color = [1 0 0];
add(world,box5);

For this example, the OnClickImpl function executes when you click box5.

Build Plane Actor

Instantiate an actor named plane1. Set the position of the actor using the Translation property. Set the Mobility and PreciseContacts properties of the actor. The PreciseContacts property precisely renders the collision of any actor with the plane actor. Use the createShape function to build a plane shape for the actor and set the size of the plane. Add the actor to the world.

plane1 = sim3d.Actor(... 
    ActorName='Plane1', ...
    Mobility=sim3d.utils.MobilityTypes.Stationary);
createShape(plane1,'plane',[100 100 0.01]);
plane1.PreciseContacts = true;
plane1.Translation = [0 0 -3];
add(world,plane1);

Using the UserData property in the sim3d.World object, create a user data structure with a field named Step to store the simulation step during simulation. Initialize the user data structure to 1. You will use this structure in the update function to increment the UserData.Step value after each simulation step and to display the events one after the other.

world.UserData.Step = 1;

Set Viewer Window Point of View

If you do not create a viewport, then the default view is set and you can use the keyboard shortcuts and mouse controls to navigate in the Simulation 3D Viewer window.

For this example, use the createViewport function to create a viewport.

viewport = createViewport(world);
viewport.Translation = [-15 0 0];

Run Simulation

Run a simulation set for 20 seconds with a sample time of 0.02 seconds. The Simulation 3D Viewer window displays five box actors and a plane actor. During simulation, box1 and box2 display the hit event. The color of the box1 changes when it hits box2, and displays the hit event attributes of box1 as output. After the hit event, box3 starts to overlap box4. During the overlap, box3 changes color, and displays the overlap event attributes as output. After the overlap event, the Simulation 3D Viewer displays, Click the box and an arrow points at the box. Click on box5 to report the click event. Upon each click, the color of box5 changes and displays the click event attributes as output.

sampletime = 0.02;
stoptime = 30;
run(world,sampletime,stoptime)

HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,3] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [7,-4,1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [7,-4,1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,0] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-6,0] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-6,0] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,0] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-6,0] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,0] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-6,0] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,0] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-6,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-6,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-6,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-6,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [7,-6,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [7,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [7,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-6,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-6,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [7,-6,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [7,-6,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-6,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [7,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-4,-1] 
 
 
HIT DETECTED
Actor ID : 2 
Other Actor ID : 3 
Other Actor Name : Box2 
Hit Location : [9,-6,-1] 
 
 
OVERLAP BEGINS
Actor starts overlap with Box4 
Self Actor ID : 4 
Other Actor ID : 5 
 
OVERLAP ENDS
Actor ends overlap with Box4 
Self Actor ID : 4 
Other Actor ID : 5 
 
CLICK DETECTED
Click Event occurred for Box1 
Clicked Actor ID : 6 
Clicked Actor Name : Box5 
 
CLICK DETECTED
Click Event occurred for Box1 
Clicked Actor ID : 6 
Clicked Actor Name : Box5 
 
CLICK DETECTED
Click Event occurred for Box1 
Clicked Actor ID : 6 
Clicked Actor Name : Box5 
 
CLICK DETECTED
Click Event occurred for Box1 
Clicked Actor ID : 6 
Clicked Actor Name : Box5

Five box actors and one plane actor in the 3D environment. Two box actors vertically aligned on the left most side, two box actors vertically aligned in the center of the screen, one box actor on the right most side of the screen and a plane actor below all the box actors.

Left most vertically aligned two box actors collides, one changes color and the other box rests on the plane actor. Two box actors vertically aligned in the center of the screen and one box actor on the right most side of the screen

Left most vertically aligned two box actors collides, one changes color and the other actor is on the plane actor. Two box actors vertically aligned in the center of the screen starts to overlap and one box actor on the right most side of the screen

Left most vertically aligned two box actors collides, one changes color and the other actor is on the plane actor. One of the two box actors vertically aligned in the center of the screen is on the plane and changes color. The message click the box displays on the right side with an arrow pointing at the box actor on the right most side of the screen changes.

Delete World

Delete the world object.

delete(world);

Set Up Event Callback Function

Use an event callback function to access actor properties when an actor participates in a particular event. For this example, the event callback functions displays the actor properties described in the Event Attributes of the sim3d.Actor object.

Set Up Hit Event Callback Function

The OnHitImpl function passes the actor handle of box1 as the input argument. When box1 collides with box2, a hit event is reported, and the OnHitImpl function executes. This function changes the color of box1, and displays the properties of box1 during simulation.

function OnHitImpl(Actor)
% Sets the actor's OnHit callback
    disp('HIT DETECTED');
    fprintf('Actor ID : %d \n',Actor.HitSelfID);
    fprintf('Other Actor ID : %d \n',Actor.HitOtherID);
    fprintf('Other Actor Name : %s \n',Actor.HitOtherActorName);
    fprintf('Hit Location : [%s] \n \n \n', ...
        join(string(Actor.HitLocation),','));
    Actor.Color = [randi([0 1],1,1),randi([0 1],1,1),randi([0 1],1,1)];
end

Set Up Overlap Event Callback Function

The OnBeginOverlapImpl and OnEndOverlapImpl functions pass the actor handle of box3 as the input argument. When box3 starts to overlap box4, the begin overlap event is reported, and the OnBeginOverlapImpl function executes. When box3 stops overlapping box4, the end overlap event is reported, and the OnEndOverlapImpl function executes.

When box3 starts to overlap box4, the OnBeginOverlapImpl function changes the color of box3, and displays the properties as output. To avoid an overlap event of box3 with plane1, the Collisions property of box3 is set to true in the update function after box3 stops overlapping box4.

% Sets the actor's OnBeginOverlap callback
function OnBeginOverlapImpl(Actor)
    disp('OVERLAP BEGINS');
    fprintf('Actor starts overlap with %s \n', ...
        Actor.BeginOverlapOtherActorName);
    fprintf('Self Actor ID : %d \n',Actor.BeginOverlapSelfID);
    fprintf('Other Actor ID : %d \n \n',Actor.BeginOverlapOtherID);
    Actor.Color = [0 1 0];
end

The OnEndOverlapImpl function changes the color of box3 and displays the properties of box3 as output when box3 stops overlapping box4.

% Sets the actor's OnEndOverlap callback
function OnEndOverlapImpl(Actor)
    disp('OVERLAP ENDS');
    fprintf('Actor ends overlap with %s \n', ...
        Actor.EndOverlapOtherActorName);
    fprintf('Self Actor ID : %d \n',Actor.EndOverlapSelfID);
    fprintf('Other Actor ID : %d \n \n',Actor.EndOverlapOtherID);    
    Actor.Color = [0 0 1];
end

Set Up Click Event Callback Function

The OnClickImpl function passes the actor handle of box5 as the input argument. This function changes the color of box5, and displays the properties of box5 as output. Each time you click on box5, a click event is reported, and the OnClickImpl function executes.

% Sets the actor's OnClick callback
function OnClickImpl(Actor)
    disp('CLICK DETECTED');
    fprintf('Click Event occurred for Box1 \n');
    fprintf('Clicked Actor ID : %d \n',Actor.ClickActorID);
    fprintf('Clicked Actor Name : %s \n \n',Actor.ClickActorName);
    Actor.Color = [randi([0 1]),randi([0 1]),randi([0 1])];
end

Set Up Update Function

Use an update function to read data after each simulation step. For this example, the UpdateImpl function increments the simulation step in the UserData structure after each simulation step. This function uses the simulation step value in UserData structure to set the properties of box1 and box3 so that the box actors simulate and the events occur one after the other. To visualize click event, the function creates annotation actors, text and arrow using the objects sim3d.graphics.Text and sim3d.graphics.Arrow, respectively. The text displays the message Click the box and the arrow points at Box5.

function UpdateImpl(world)
    if world.UserData.Step == 100
        world.Actors.Box1.Gravity = true;
    end    

    if world.UserData.Step == 500
        world.Actors.Box3.Gravity = true;
    end

    if world.UserData.Step == 560
        world.Actors.Box3.Collisions = true;
    end

    if world.UserData.Step == 820
        text = sim3d.graphics.Text( ...
            ActorName="Text", ...
            Translation=[0 1 5], ...
            String="Click the box", ...
            FontSize=4,Color=[1 1 0]);
        add(world,text,world.Actors.Box5);
        arrow = sim3d.graphics.Arrow( ...
            ActorName="Arrow", ...
            Translation=[0 1.5 4.5],...
            Rotation=[0 -pi/3 -pi/2], ...
            Scale=[1 1 1]*5, ...
            Length=0.5, ...
            Color=[0 0 1]);
        add(world,arrow,world.Actors.Box5);
    end

    world.UserData.Step = world.UserData.Step + 1;
end