Unreal

Introduction

Planetary Processing provides a plugin for Unreal Engine 5. The plugin consists of a number of C++ classes for use in connecting players to your game simulation, as well as communicating simulation state to your game client and messages from the client to your simulation.

Pre-requisites

• Unreal Engine 5.4+

• macOS or Windows, the PP Unreal plugin does not currently support Linux.

Installation

To install the Planetary Processing plugin, you must first download the plugin files from our website, you will need to be logged into your Planetary Processing account to do so, the link is: https://files.planetaryprocessing.io/builds/downloads/artefactid/107/version/latest/dist/dist.tar

Or use a legacy version: 5.4, 5.5.

You'll need then to extract this and move the contents of the lib directory into a directory called PlanetaryProcessing in the Plugins directory at the root level of your project. You'll need to create the Plugins directory if it does not already exist.

You can now enable the Planetary Processing plugin for your Unreal Engine 5 project. You will be required to restart the engine once you enable the plugin.

Classes

PlanetaryProcessing Class

This class is the core of the Planetary Processing plugin. It handles initialization, connection to the server, authentication, message sending, and state updates from the server. This class is intended to be used as a singleton, and instantiated via the Init static function.

Entity Class

This class represents an Entity in the Planetary Processing system. It contains all the data of the corresponding entity on your game server. The Entity Types can be matched up with the EntityActor class using the Entity Map variable.

EntityActor Class

This class extends the Unreal Engine Actor class, spawning an Actor in your game client based on an Entity from your game simulation. You are intended to subclass Entity Actor to create Actors for each of your Entity Types. As an example, a 'Tree' class could be an Entity Actor for a 'tree' Entity Type. Meanwhile a 'Cat' class could be a completely different Entity Actor with a separate mesh component and behaviours.

The EntityActor class is intended to have an Entity associated with it once created, via SetEntity. With this set, the EntityActor class will automatically broadcast OnUpdated and OnRemoved events accordingly, as its associated Entity is either updated or removed.

ChunkActor Class

Use of this class is optional. Similar to the Entity Actor, this class spawns an Actor in your game client. If used, an Actor is spawned at the bottom-left corner of every Chunk in your game simulation.

The main purpose of the Chunk Actor is to store information, such as data about nearby terrain. In most cases the Chunk Actor will not need a mesh, since it cannot move or act.

Chunks only have one type, 'chunk'. A subclass of Chunk Actor must be defined in the Chunk Map using the key 'chunk'. You must also define the Chunk Size integer variable, using the chunk size set in your online game.

The ChunkActor class is intended to have an Chunk associated with it once created, via SetChunk. With this set, the ChunkActor class will automatically broadcast OnUpdated and OnRemoved events accordingly, as its associated Chunk is either updated or goes out of range of a Chunkloader.

MessageData Class

The MessageData class is designed to serve as a flexible container for arbitrary data, akin to JavaScript objects. Its primary purpose is twofold:

• Deserialization from JSON: It allows update messages received from the server in JSON format to be efficiently parsed and stored in a way that can be accessed within Unreal Engine. This ensures that the data stored on each Entity (strings, numbers, booleans, arrays and nested objects) can be translated into native Unreal Engine data structures.

• Serialization to JSON: Conversely, the class enables the construction of arbitrary data structures which can be serialized and sent to the server as the body of the message in a SendMessage call.

Hence it can be used in Blueprints to both access data on Entity instances and construct messages for SendMessage.

If you want to handle serialization and deserialization yourself, without MessageData, the original JSON of an Entity is available in the DataJSON property of that class. Raw JSON messages can also be sent using the SendJSONMessage function of the PlanetaryProcessing class.

Event Class

The Event Class handles manual server-to-client messaging. Every tick, if a message has been sent from the server using api.client.Message(), the Unreal custom event OnEventReceived_Event is triggered.

Use this to handle data sent to a specific player client, as opposed to entity data which is sent to all player clients.

Blueprints

The Planetary Processing plugin is packaged with a number of example Blueprints. These serve to show how to carry out some basic functions using the Planetary Processing plugin. These blueprints are PP_ExamplePlayerController, PP_ExampleEntityActor, and the PP_ExampleLoginWidget.

PP_ExamplePlayerController

This blueprint demonstrates how to initialize your Planetary Processing instance and then how to carry out the fundamental processes required to make use of it. These include establishing the connection, initializing entities, maintaining the connection, and processing messages to and from the server.

Authentication

There are two stages to authentication: initializing the connection the game server and joining the validated connection's processing.

Initializing the connection:

1. Event BeginPlay/Show Login -> Init -> Set

   • Initialize the PlanetaryProcessing singleton with a Game ID (Game ID available in the Planetary Processing Panel).

2. Create PP Example Login Widget Widget -> Set -> Add to Viewport

   • Create an instance of PP_ExampleLoginWidget and adds it to the viewport.

3. Planetary Processing Instance -> Bind Event to On Authenticated -> OnAuthenticated_Event

   • Bind the connection joining processes to the OnAuthenticated event triggered from the PlanetaryProcessing singleton.

Joining a valid connection:

1. OnAuthenticated_Event -> Delay

   • A short delay ensures subsequent bindings are handled by the game thread.

2. Login Widget Instance -> Remove from Parent -> Set

   • Remove the login widget from the viewport.

3. Unbind All Events from On Authenticated -> Planetary Processing Instance

   • Unbind all events from the OnAuthenticated event.

4. Planetary Processing Instance - > Bind Event to On Entity Added -> Bind Event to On Connection Error

   • Set up bindings to generate the game server world using the OnEntityAdded and OnConnectionError events from the PlanetaryProcessing singleton.

5. Start Game -> Start Game (Custom Event)

   • Continue with game logic, in this case a custom event named StartGame.

Entity Actor Spawning

1. OnEntityAdded_Event -> GetType / Entity Map -> Find

   • Look up the EntityActor class reference in the EntityMap variable using the Entity Type from the OnEntityAdded_Event.

2. GetLocationVector -> Make Transform

   • Use the GetLocationVector function of the added Entity to create a Vector for the initial location of the EntityActor.

3. Find / Branch / Make Transform -> Spawn Actor

   • If the Type is valid, spawn an instance of the EntityActor.

4. OnEntityAdded_Event / Spawn Actor -> Set Entity

   • Call SetEntity on the EntityActor to associate it with the Entity that we are representing.

If you wish, you can extend the script to remove spawning for the client player entity. This can be done by adding an extra branch to filter entities with the same ID as the Planetary Processing instance's UUID. This only removes the player's own entity from the client, not other players.

Chunk Actor Spawning

1. OnChunkAdded_Event -> Entity Map -> Find

   • Look up the ChunkActor class reference in the ChunkMap variable using the key 'chunk'.

2. GetLocationVector / Chunk Size -> Multiply -> Make Transform

   • Use the GetLocationVector function of the added Chunk to get its X and Y values. Multiply these by the Chunk Size to create a Vector for the location of the ChunkActor.

3. Find / Branch / Make Transform -> Spawn Actor

   • If the 'chunk' key is in use, spawn an instance of the ChunkActor.

4. OnChunkAdded_Event / Spawn Actor -> Set Chunk

   • Call SetChunk on the ChunkActor to associate it with the Chunk that we are representing.

Connection Error Handling

If the connection fails, cease processing the world and return to the authentication login.

1. OnConnectionError_Event / Planetary Processing Instance -> Unbind All Events from On Entity Added / Planetary Processing Instance -> Unbind All Events from On Connection Error

   • Unbinds all events from OnEntityAdded and OnConnectionError.

2. Show Login -> Show Login Custom Event

   • Calls a custom event called ShowLogin, which feeds back into the authentication flow above.

Update Entities

1. Planetary Processing Instance -> IsAuthenticated / Event Tick -> Branch

   • On each tick, check if the connection is authenticated by calling IsAuthenticated on the PlanetaryProcessing instance.

2. Branch -> Sequence / Planetary Processing Instance -> Update -> OnUpdated_Event

   • If it is authenticated, call the Update function of the PlanetaryProcessing instance to process state changes received.

3. Sequence -> Send Player Coords -> SendPlayerCoords (Custom Event)

   • We then also call the SendPlayerCoords custom event.

Send Player Coordinates Message

1. Send Player Coords (Custom Event) -> ...

   • Process the message on each update tick using the Send Player Coords broadcast.

2. Get Player Pawn -> Get Actor Location

   • Get the location of the Player Pawn Actor.

3. Convert Vector To Server Coords Message Data -> Set

   • Call the ConvertVectorToServerCoordsMessageData static function from the PlanetaryProcessing class. This gives us a map of strings to MessageData values, with the x, y and z values set based on the player position. ConvertVectorToServerCoordsMessageData alters these xyz values to match the Planetary Processing coordinate system orientation.

4. Set / To MessageData (bool) -> Add

   • Uses the implicit conversion of a boolean to MessageData as the value for a new key of threedee in our map.

5. Add / Planetary Processing Instance / Set -> Send Message

   • Calls SendMessage on our PlanetaryProcessing instance with our message map as an argument.

Server to Client Event Messaging (example)

1. OnEventReceived_Event (Custom Event) -> Get Map

   • Get a message map sent to this player client.

2. Find -> Get String -> Print String

   • Use a key to find a specific value in the map, and define what data type that value is expected to be. Then print the value.

PP_ExampleEntityActor

This blueprint shows how to bind to the OnUpdated and OnRemoved events for an EntityActor.

Event Binding

1. Event BeginPlay -> Bind Event to On Updated -> OnUpdated_Event -> Set Actor Location to Entity Coords

   • Bind to the OnUpdated event for the EntityActor. Calls SetActorLocationToEntityCoords to update the Actor's location to match the Entity.

2. Bind Event to On Removed -> OnRemoved_Event -> Destroy Actor

   • Bind to the OnRemoved event for the EntityActor. Destroys the Actor when this event is broadcast.

For the actor to follow the server-side location, without issue, it must have physics disabled on the clientside.

If you wish to retrieve the location vector of an entity before it is set automatically, you can use the following example. Replace the Print String function with functions of your choice.

PP_ExampleChunkActor

This blueprint shows how to bind to the OnUpdated and OnRemoved events for a ChunkActor.

Event Binding

1. Event BeginPlay -> Bind Event to On Updated -> OnUpdated_Event -> Set Actor Location to Chunk Coords

   • Bind to the OnUpdated event for the ChunkActor. Calls SetActorLocationToChunkCoords to update the Actor's location to match the Entity.

2. Bind Event to On Removed -> OnRemoved_Event -> Destroy Actor

   • Bind to the OnRemoved event for the ChunkActor. Destroys the Actor when this event is broadcast.

PP_ExampleLoginWidget

This is a simple login widget which calls the Connect function and displays an error if the connection fails.

Login Click

1. OnClicked (Login_Button) / Error Message Text -> Set Visibility

   • Hide the error message (effectively resetting the error state of the login form) when clicked.

2. Username / Password -> GetText -> Get Planetary Processing Instance / To String (Text) -> Connect

   • Call the Connect function on the PlanetaryProcessing instance with the username and password from the login form.

Error Handling

1. Event On Initialized -> Get Planetary Processing Instance -> Bind Event to On Connection Error -> OnConnectionError_Event

   • Bind to the OnConnectionError event when the widget is initialized.

2. OnConnectionError_Event / Error Message Text -> Set

   • Set the error message to be visible when OnConnectionError is broadcast.

API

PlanetaryProcessing Class

Properties

Functions

Delegates

Entity Class

Properties

Functions

EntityActor Class

Properties

Functions

ChunkActor Class

Properties

Functions

MessageData Class

Functions

Event Class

PP_ExamplePlayerController

Variables

PP_ExampleLoginWidget

Variables