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.

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 or Scenes, in the PPMaster inspector window.

Essential Variables:

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

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

Optional Variables:

• Use Scene Player - By default, the GameObject in the 'Player' field will be used as the local player. If ticked, the Scene in 'Scene Player Name' will be used instead.

• Scene Player Name - Only required if 'Use Scene Player' is enabled. The string name of the scene to act as your player. The scene must contain a GameObject with the Entity Component.

• Chunk Prefab - A Prefab with the Chunk Component to manage Chunks.

• Scenes - Like 'Prefabs', each Entity Scene should be added to the Entity 'Scenes' list in the inspector. The Scenes must be created containing a top-level GameObject with the Entity Component.

• 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 or Scene 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.

Essential Variables:

• Type - The type of entity this Prefab/Scene should represent in the game world, matching the appropriate entity_name.lua file in the serverside code. It should be empty for the local player character.

Optional Variables:

• Use Server Position - Enabled by default. If ticked, this type of entity will automatically be moved to its server-side position.

• UUID Override - (Under Development)

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.

Server To Client Messaging

The PPEntity component automatically receives and syncs all Entity data from the game world. Any client can access Entity data passed from the server, using GetServerData().

Alternatively, 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);
    }

Using Scenes

By default, we recommend representing your player with a GameObject in the main scene and Entities with Prefabs. However, you may wish to represent your player and entities as Unity Scenes, for structuring larger games on the Unity client.

To create a player scene, you must enable 'Use Scene Player' and specify the scene's name in 'Scene Player Name'. The default 'Player' field should be left blank.

Regular entities can also be scenes. You can add each Entity Scene's name to the 'Scenes' list. An Entity Scene should contain a GameObject with a PPEntity component at the top level of the hierarchy.

On the serverside, an Entity Scene functions in the same way as an Entity Prefab. Entities of different types may be a Prefab or a Scene, within the same game. So you may have a Cat Entity Prefab and a Tree Entity Scene, so long as they are each referenced in the appropriate list of the PPMaster inspector.

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

PPEntity

PPChunk

Custom Scripts