Get Started Communicating with the Unreal Engine Visualization Environment

You can set up communication with Unreal Engine^® by using the Simulation 3D Message Get and Simulation 3D Message Set blocks:

• Simulation 3D Message Get receives data from the Unreal Engine environment.

• Simulation 3D Message Set sends data to the Unreal Engine environment.

To use the blocks and communicate with Unreal Engine, make sure you install the Vehicle Dynamics Blockset™ Interface for Unreal Engine 4 Projects support package. For more information, see Install Support Package and Configure Environment.

Next, follow these workflow steps to set up the Simulink^® model and the Unreal Engine environment and run a simulation.

Workflow		Description
Set Up Simulink Model to Send and Receive Data		Configure the Simulation 3D Message Get and Simulation 3D Message Set blocks in Simulink to send and receive the cone location from Unreal® Editor. The steps provides the general workflow for communicating with the editor. The Simulation 3D Message Get and Simulation 3D Message Set blocks can send and receive these data types: double, single, int8, uint8, int16, uint16, int32, uint32, and Boolean. The Simulation 3D Actor Transform Set and Simulation 3D Actor Transform Get blocks can send and receive only the single data type.
Set Up Unreal Engine to Send and Receive Data	C++ Workflow: Set Up Unreal Engine to Send and Receive Data	Specific Unreal C++ workflow to send and receive Simulink cone location data. Simulation 3D Message Get receives data from an Unreal Engine environment C++ actor class. In this example workflow, you use the block to receive the cone location from Unreal Editor. Simulation 3D Message Set sends data to an Unreal Engine C++ actor class. In this example, you use the block to set the initial cone location in the Unreal Editor. To follow this workflow, you should be comfortable coding with C++ in Unreal Engine 4.23. Make sure that you have Visual Studio® 2019 installed on your computer.
	Blueprint Workflow: Set Up Unreal Engine to Send and Receive Data	Generalized Unreal Editor blueprint workflow to send and receive Simulink data.
Run Simulation		After you set up the Simulink model and Unreal Editor environment, run a simulation.

Set Up Simulink Model to Send and Receive Data

Step 1: Install Support Package

If you have already downloaded and installed Unreal Engine Version 4.23 and the Vehicle Dynamics Blockset Interface for Unreal Engine 4 Projects support package, go to the next step.

To install and configure the support package, see Install Support Package and Configure Environment.

Step 2: Set Up Simulink Model

Open a new Simulink model. Connect the blocks as shown.

Step 3: Configure Blocks

Use these block settings to configure blocks to send and receive cone data from the Unreal Editor.

Block	Parameter Settings
Constant	Constant value — [100,10,50] Sets the initial cone location in the Unreal Editor coordinate system (in cm, left-handed, in Z-up coordinate system) Interpret vector parameters as 1-D — off Output data type — single
Data Type Conversion	Output data type — single
Simulation 3D Scene Configuration	Scene Source — Unreal Editor Project — Your_Project_Path\TestSim3dGetSet.uproject Open Unreal Editor — Select to open the editor
Simulation 3D Message Get	Signal name, SigName — ConeLocGet Data type, DataType — single Message size, MsgSize — [1 3] Sample time — -1
Simulation 3D Message Set	Signal name, SigName — ConeLocSet Sample time — -1

C++ Workflow: Set Up Unreal Engine to Send and Receive Data

Step 4: Open Unreal Editor in Editor Mode

1. In the Unreal Editor, on the Edit tab, select Plugins. Make sure that the MathWorks Interface plugin is enabled. If prompted, restart the Unreal Editor.

2. Create an Unreal Engine C++ project. Name it TestSim3dGetSet. For steps on how to create C++ project, see the Unreal Engine 4 Documentation.

3. In the Unreal Editor, click the Edit tab in the top left corner. Select Plugins and make sure that the MathWorks Interface plugin is enabled. If the MathWorks Interface plugin is disabled, enable it and restart Unreal Editor, if prompted.

4. Close the Unreal.

5. If Visual Studio is not open, open it.

6. Add the MathWorksSimulation dependency to the TestSim3dGetSet project build file.

   • The project build file, TestSim3dGetSet.Build.cs, is located in this folder: ...\TestSim3dGetSet\Source\TestSim3dGetSet.

   • In the build file, TestSim3dGetSet.Build.cs, edit the line 11 to add the “MathWorksSimulation” dependency:

      PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", 
     "Engine", "InputCore", "MathWorksSimulation"}); 

7. Save the change. In Visual Studio, rebuild the TestSim3dGetSet project. Close Visual Studio.

   Tip

   Before rebuilding the project in Visual Studio, make sure that Unreal is not open.

8. Start MATLAB^®. Change the current folder to the location of the Unreal Engine TestSim3dGetSet project.

9. In MATLAB, open the project:

   editor = sim3d.Editor('TestSim3dGetSet.uproject'); 
   editor.open();

Step 5: Create Actor Class

1. In the Unreal Editor, from the MathWorksSimulation C++ classes directory, select Sim3dActor.

   

   Right-click and select Create C++ class derived from Sim3dActor.

   

2. Name the new Sim3dActor SetGetActorLocation. Select Public. Click Create Class.

3. Close the Unreal Editor.

Step 6: Open SetGetActorLocation.h

Visual Studio opens with new C++ files in the project folder:

• SetGetActorLocation.h

• SetGetActorLocation.cpp

Make sure you close the Unreal Editor.

In Visual Studio, build the solution TestSim3dGetSet:

1. In the Solution Explorer, right-click Solution 'TestSim3dGetSet' (2 projects).

2. Select Build Solution.

3. After the solution builds, open SetGetActorLocation.h. Edit the file as shown.

    Replacement Code: SetGetActorLocation.h

   This is the replacement code for SetGetActorLocation.h.

   // Copyright 2019 The MathWorks, Inc.
   
   #pragma once
   
   #include "Sim3dActor.h"
   #include "SetGetActorLocation.generated.h"
   
   UCLASS()
   class TESTSIM3DGETSET_API ASetGetActorLocation : public ASim3dActor
   {
   	GENERATED_BODY()
   	
   	void *SignalReader;
   	void *SignalWriter;
   
   public:	
   	// Sets default values for this actor's properties
   	ASetGetActorLocation();
   
   	virtual void Sim3dSetup() override;
   	virtual void Sim3dRelease() override;
   	virtual void Sim3dStep(float DeltaSeconds) override;
   };
   

Step 7: Open SetGetActorLocation.cpp

Open SetGetActorLocation.cpp and replace the block of code.

 Replacement Code: Set Pointer to Parameter

This code allows you to set a pointer to the parameter Signal Name parameter for the Simulink blocks Simulation 3D Message Set and Simulation 3D Message Get, respectively.

// Sets default values
ASetGetActorLocation::ASetGetActorLocation():SignalReader(nullptr), SignalWriter(nullptr)
{
}

 Replacement Code: Access Actor Tag Name

The following code allows you to access the tag name of this actor after it is instantiated in the scene with an assigned tag name. The code also initializes the pointers SignalReader and SignalWriter, to initiate a link between Unreal Editor and Simulink. The variables represent these block Signal Name parameter values:

• SignalReaderTag — Simulation 3D Message Set

• SignalWriterTag — Simulation 3D Message Get

void ASetGetActorLocation::Sim3dSetup()
{
Super::Sim3dSetup();
       if (Tags.Num() != 0) {
              unsigned int numElements = 3;
              FString tagName = Tags.Top().ToString();

              FString SignalReaderTag = tagName;
              SignalReaderTag.Append(TEXT("Set"));
              SignalReader = StartSimulation3DMessageReader(TCHAR_TO_ANSI(*SignalReaderTag), sizeof(float)*numElements);

              FString SignalWriterTag = tagName;
              SignalWriterTag.Append(TEXT("Get"));
              SignalWriter = StartSimulation3DMessageWriter(TCHAR_TO_ANSI(*SignalWriterTag), sizeof(float)*numElements);
              }
}

 Additional Code: Read and Write Data During Run Time

Add this code to allow Unreal Engine to read the data value set by Simulation 3D Message Set and then write back to Simulation 3D Message Get during run time. Unreal Engine uses this data to set the location value of the actor.

void ASetGetActorLocation::Sim3dStep(float DeltaSeconds)
{
       unsigned int numElements = 3;
       float array[3];
       int statusR = ReadSimulation3DMessage(SignalReader, sizeof(float)*numElements, array);
       FVector NewLocation;
       NewLocation.X = array[0];
       NewLocation.Y = array[1];
       NewLocation.Z = array[2];
       SetActorLocation(NewLocation);
       float fvector[3] = { NewLocation.X, NewLocation.Y, NewLocation.Z };
       int statusW = WriteSimulation3DMessage(SignalWriter, sizeof(float)*numElements ,fvector);
}

 Additional Code: Stop Simulation

Add this code so that Unreal Engine stops when you press the Simulink stop button. The code destroys the pointer SignalReader and SignalWriter.

void ASetGetActorLocation::Sim3dRelease()
{
       Super::Sim3dRelease();
       if (SignalReader) {
              StopSimulation3DMessageReader(SignalReader);
       }
       SignalReader = nullptr;     

       if (SignalWriter) {
              StopSimulation3DMessageWriter(SignalWriter);
       }
       SignalWriter = nullptr;
}

 Entire Replacement Code: SetGetActorLocation.cpp

This is the entire replacement code for SetGetActorLocation.cpp.

// Copyright 2019 The MathWorks, Inc.
#include "SetGetActorLocation.h"

// Sets default values
ASetGetActorLocation::ASetGetActorLocation():SignalReader(nullptr), SignalWriter(nullptr)
{
}

void ASetGetActorLocation::Sim3dSetup()
{
Super::Sim3dSetup();
       if (Tags.Num() != 0) {
              unsigned int numElements = 3;
              FString tagName = Tags.Top().ToString();

              FString SignalReaderTag = tagName;
              SignalReaderTag.Append(TEXT("Set"));
              SignalReader = StartSimulation3DMessageReader(TCHAR_TO_ANSI(*SignalReaderTag), sizeof(float)*numElements);

              FString SignalWriterTag = tagName;
              SignalWriterTag.Append(TEXT("Get"));
              SignalWriter = StartSimulation3DMessageWriter(TCHAR_TO_ANSI(*SignalWriterTag), sizeof(float)*numElements);
              }
}

void ASetGetActorLocation::Sim3dStep(float DeltaSeconds)
{
       unsigned int numElements = 3;
       float array[3];
       int statusR = ReadSimulation3DMessage(SignalReader, sizeof(float)*numElements, array);
       FVector NewLocation;
       NewLocation.X = array[0];
       NewLocation.Y = array[1];
       NewLocation.Z = array[2];
       SetActorLocation(NewLocation);
       float fvector[3] = { NewLocation.X, NewLocation.Y, NewLocation.Z };
       int statusW = WriteSimulation3DMessage(SignalWriter, sizeof(float)*numElements ,fvector);
}

void ASetGetActorLocation::Sim3dRelease()
{
       Super::Sim3dRelease();
       if (SignalReader) {
              StopSimulation3DMessageReader(SignalReader);
       }
       SignalReader = nullptr;     

       if (SignalWriter) {
              StopSimulation3DMessageWriter(SignalWriter);
       }
       SignalWriter = nullptr;
}

Step 8: Build the Visual Studio Project and Open Unreal Editor

Press F5 on the keyboard to run the Visual Studio solution TestSim3dGetSet. The Unreal Editor opens.

Note

In the Unreal Editor, save the current level by clicking Save Current (located in the top left) and name it TestMap. Add this level as default to Project Settings by clicking on Edit > Project Settings > Maps&Modes. Then select TestMap as the default value for the Editor Startup Map and Game Default Map. Close Project Settings to save the default values.

Step 9: Check Actor

On the World Outliner tab, check that the new instantiated actor, SetGetActorLocation1, is listed.

Step 10: Add Mesh

Click on the actor that you created in Step 9: Check Actor.

1. In the Details panel, click on Add Component to add a mesh to the actor SetConeLocation1. Choose Cone as the default mesh.

2. Find the property tags for actor SetConeLocation1. Add a tag by clicking on the plus sign next to 0 Array elements. Name it ConeLoc.

Step 11: Set Cone Location

On the Details tab, click Cone. Set the cone to X = 0.0, Y = 0.0, and Z = 0.0. Also set the actor Mobility property to Movable.

Step 12: Set Parent Class and Save Scene

Set the parent class.

1. Under Blueprints, click Open Level Blueprint, and select Class Settings.

   

2. In the Class Options, set Parent Class to Sim3dLevelScriptActor.

   

Save the Unreal Editor scene.

Step 13: Run Simulation

Run the simulation. Go to Run Simulation.

Reference: C++ Functions for Sending and Receiving Simulink Data

Call these C++ functions from Sim3dSetup, Sim3dStep, and Sim3dRelease to send and receive Simulink data.

To	C++ Functions
Receive data	StartSimulation3DMessageReader
	ReadSimulation3DMessage
	StopSimulation3DMessageReader
Send data	StartSimulation3DMessageWriter
	WriteSimulation3DMessage
	StopSimulation3DMessageWriter

Blueprint Workflow: Set Up Unreal Engine to Send and Receive Data

Step 4: Configure Scenes to Receive Data

To use the Simulation 3D Message Set block, you must configure scenes in the Unreal Engine environment to receive data from the Simulink model:

1. In the Unreal Editor, instantiate the Sim3DGet actor that corresponds to the data type you want to receive from the Simulink model. This example shows the Unreal Editor Sim3DGet data types.

   

2. Specify an actor tag name that matches the Simulation 3D Message Set block Signal name parameter.

3. Navigate to the Level Blueprint.

4. Find the blueprint method for the Sim3DGet actor class based on the data type and size that you want to receive from the Simulink model.

   For example, in Unreal Editor, this diagram shows that Read Scalar Integer is the method for Sim3DGetInteger actor class to receive int32 data type of size scalar.

   

5. Compile and save the scene.

Step 5: Configure Scenes to Send Data

To configure scenes in the Unreal Engine environment to send data to the Simulink model:

1. In the Unreal Editor, instantiate the Sim3DSet actor that corresponds to the data type you want to send to the Simulink model. This example shows the Unreal Editor Sim3DSet data types.

   

2. Specify an actor tag name that matches the Simulation 3D Message Get block Signal name parameter.

3. Navigate to the Level Blueprint.

4. Find the blueprint method for the Sim3DSet actor class based on the data type and size specified by the Simulation 3D Message Get block Data type and Message size parameters.

   For this example, the array size is 3. The Unreal Editor diagram shows that Write Array Float is the method for the Sim3DSetFloat3 actor class that sends float data type of array size 3.

   

5. Compile and save the scene.

Note

Optionally, for better performance, set Read Array Float Max Num Elements to Num El in the Actor Blueprint.

Step 6: Create Blueprint

In the Unreal Editor, create a level blueprint connecting the Get and Set actors.

1. Set the actor tag values.

   • Sim3dGetFloat1 — Simulation 3D Message Set block Signal name, SigName parameter value, for example ConeLocSet

   • Sim3dSetFloat1 — Simulation 3D Message Get block Signal name, SigName parameter value, for example ConeLocGet

2. Set the parent class.

   1. Under Blueprints, click Open Level Blueprint, and select Class Settings.

      

   2. In the Class Options, set Parent Class to Sim3dLevelScriptActor.

      

3. In the level blueprint, make the connections, for example:

   

Step 7: Run Simulation

Run the simulation. Go to Run Simulation.

Run Simulation

After you configure the Simulink model and Unreal Editor environment, you can run the simulation.

Note

At the BeginPlay event, Simulink does not receive data from the Unreal Editor. Simulink receives data at Tick events.

Run the simulation.

1. In the Simulink model, click Run.

   Because the source of the scenes is the project opened in the Unreal Editor, the simulation does not start.

2. Verify that the Diagnostic Viewer window in Simulink displays this message:

   In the Simulation 3D Scene Configuration block, you set the scene source to 'Unreal Editor'. In Unreal Editor, select 'Play' to view the scene.

   This message confirms that Simulink has instantiated the vehicles and other assets in the Unreal Engine 3D environment.

3. In the Unreal Editor, click Play. The simulation runs in the scene currently open in the Unreal Editor.

You can send and receive these data types: double, single, int8, uint8, int16, uint16, int32, uint32, boolean. The code in Step 7: Open SetGetActorLocation.cpp reads single data type values (or float values) from Simulink.