Unity

The Unity SDK integrates our multiplayer platform with Unity. The plugin provides components and methods to use within your game client code - these communicate changes in state from your server side simulation to the game client itself.

If you are new here, we recommend starting with the Unity Quickstart Guide.

Installation

The Unity SDK can be installed by opening the Unity Package Manager (Window->Package Manager) and clicking the + on the top left and selecting 'Add package from git URL...'

You then enter the GitHub URL of the PP Unity SDK repository, which is: https://github.com/Planetary-Processing/unity-sdk.git

And click 'Add' to add the package.

Components

The Unity SDK provides three new components which can be added to GameObjects. These are the Master, Entity, and Chunk components. These can be accessed in the 'Add Component' menu of any GameObject under the 'PP' heading.

Unity component

Master Component

PPMaster represents the main connection point to PP's servers and performs the heavy lifting and orchestration of the SDK. You must have a GameObject in your game which has the Master Component.

To configure the Master Component you will need to set some references to GameObjects and Prefabs, in the PPMaster inspector window.

• Player - Your local player will be represented by a GameObject.

• Chunk Prefab - A Prefab with the Chunk Component to manage Chunks.
• Prefabs - Each Prefab created with the the Entity Component must be added to the Entity 'Prefabs' list in the inspector.
• Game ID - The ID of your game from the web panel, for Unity to connect to.
• Chunk Size - The size of chunks in your game, defined in the web panel game settings.
• Two Dimensions - Automatically adjusts entity positions to use Unity's 2D orientation.

• Server To Client Object - A GameObject which receives manual messages from the game server to the client.

Entity Component

PPEntity represents a server-side entity in the game world. You are required to, for every type of entity you wish to display in the Unity client, create a Prefab containing the PPEntity component.

By default, entities' GameObjects will be moved to their server-side position, you can disable this per entity type by un-ticking 'Use Server Position' in the entity component's inspector window. Here you also need to set the entity's type, which must match the server-side type that this Prefab represents.

Please note that the player type is needed only for other players, not the one connecting with this client. For the local player, you need to create a separate GameObject (not in a prefab). The local player also requires a PPEntity component, but not a specific type definition in the inspector.

Unity Entity Component

Chunk Component

PPChunk represents each chunk in the game world. Each chunk has a data table, which is synced down to the client with the PPChunk component. To use this, you must create a Prefab with the PPChunk component on it, which will be instantiated at the corner of each chunk and will hold its data.

Unity Chunk Component

Server To Client Messaging

The PPEntity component automatically receives and syncs all Entity data from the game world.

Messages can be manually sent to a specific client using api.client.Message(). These message can be received by a designated Server To Client Object. This GameObject needs a custom script component, with a function named ServerToClient, which receives the server message as a parameter.

void ServerToClient(Dictionary<string, object> message)
    {
        message.TryGetValue("key", out object value);
    }

API

Below are reference tables of the API available within Unity's C# environment.

The PPMaster, PPEntity, and PPChunk components expose various public methods which can be accessed within MonoBehaviour scripts by getting a reference to the component like so:

PPMaster master = GetComponent<PPMaster>();
PPEntity entity = GetComponent<PPEntity>();
PPChunk chunk = GetComponent<PPChunk>();

To connect to the server and join with the player, for example:

PPMaster master = GetComponent<PPMaster>();
master.Init("", "");
master.Join();

PPMaster

Method	Parameters	Return Type	Description
Init(username, password)	username: string password: string	None	Connect to and authenticate with the Planetary Processing servers.
Join()	None	None	Spawn the player into the world.
Message(msg)	msg: Dictionary<string, object>	None	Send a message to the player entity on the server, to be handled by the message function on the server side API.
GetEntity(uuid)	uuid: string	Entity	Get Entity details by UUID.
GetEntities()	None	List<Entity>	Get a list of all Entities that this client can see.

PPEntity

Method	Parameters	Return Type	Description
GetServerPosition()	None	Vector3	Get the server-side position of this entity. Particularly useful if you are not using the 'Use Server Position' feature. NOTE: Planetary Processing uses 'y' for depth in 3 dimensional games, and 'z' for height, the Unity SDK automatically swaps these.
GetServerData()	None	Dictionary<string, object>	Get the server-side data of this entity.
GetUUID()	None	string	Get this entity's UUID.

PPChunk

Method	Parameters	Return Type	Description
GetServerData()	None	Dictionary<string, object>	Get the server-side data of this chunk.

Custom Scripts

Method	Parameters	Return Type	Description
ServerToClient()	message: Dictionary<string, object>	None	Receives manual messages from the server. Must be assigned to a GameObject in the PPMaster inspector.