Defold
Last updated
Last updated
The Defold SDK integrates our multiplayer platform with Defold. The plugin provides components and messages 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 Defold Quickstart Guide.
The Defold SDK can be installed by navigating to your game.project
file, then in the 'Project' tab (in the Editor window) you will see the 'Dependencies' list.
You need to add the following dependencies:
The Planetary Processing SDK: https://github.com/Planetary-Processing/defold-sdk/archive/master.zip
Defold Websocket, which we depend on: https://github.com/defold/extension-websocket/archive/master.zip
Defold Protobuf, which we depend on: https://github.com/Melsoft-Games/defold-protobuf/archive/master.zip
You need then to fetch dependencies, this is done with the 'Fetch Libraries' button under 'Project' in the topbar.
The Defold Websocket library has additional configuration settings. Check there is a 'Websocket' tab in your game.project file, with the 'Debug' and 'Socket Timeout' settings.
If these settings are missing, edit your game.project
file in a text editor and add the options to it manually.
You can find an example project in the same repo as the library, on our GitHub.
The Defold SDK provides three new components which can be added to GameObjects. These are master, entity and chunk.
For every type of Entity you wish to display in the Defold client, you must create a GameObject file containing the Entity Component. These will act as protypes. These Entity prototypes will be spawned into your world, by factories attached to the Game Object with the Master Component.
Other players in the game are also represented as Entities, using the player
Entity Type. The local player, controlled by the person playing your game, is not a prototype. It should instead be a separate GameObject in your collection, however it also needs an Entity Component.
By default, entities 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 config window. Should you not want this, you can still keep track of the server position using Messages.
Like the entity component, if you wish to represent chunk data in the Defold client, you must create a GameObject file containing the Chunk Component. This will act a protypes. The chunk prototype will be spawned into your world as an invisible object, by a factory attached to the Game Object with the Master Component.
Chunks are static and invisible. A chunk object will spawn at the origin of each loaded chunk. Chunk objects are optional and you can create a game without them if you wish.
The Master Component 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.
Factories to produce Entities and Chunks must be attached to the same GameObject as the Master Component. Entity factories should be named after the Entity Type in the formattypenamefactory
as in the example below for the types cat
, player
and tree
.
Within the Master Component you will need to set the URL of the local player GameObject, the Chunk Size (available in Game Settings), and the Planetary Processing Game ID.
Messages can be sent to and from your game server along a connection,. Messages to the server are sent to the Master Component. Messages from the server are sent to each entity, and the listener (the script which sent the pp_init
message). Each of these message use a message_id, such as pp_init
, pp_join
, pp_update
, or pp_message
.
There is 2KB limit on the size of messages in Defold, which affects the amount of data which can be transferred from the server. If your message buffer is being overloaded, reduce the amount of Data stored in each individual entity.
The first thing you need to do when your game starts is initialise the SDK, to do this you send the Master Component (or its whole GameObject) a message with ID hash("pp_init")
. The sender url of this message will be allocated as the 'listener' and will be sent all updates in future.
If you are using authentication, you should supply username and password in a table like so:
By default, the player will not have joined the world, in order to do this, you should send an empty message with ID hash("pp_join")
to the master component (or its GameObject).
The pp_join
message will fail if it is called too soon after the pp_init
and before the connection is fully established. To avoid this , either trigger the pp_join
once a pp_connected
message has been received, or on input from the person playing.
The PP SDK sends and receives several different messages and accepts several too. Each time an entity or chunk updates its position or data, a message with ID hash("pp_update")
is sent to that entity's GameObject and the listener.
This message is of the following format:
(the same format is also used for pp_spawn
and pp_delete
messages)
uuid
string
UUID of the entity.
x
float
X coordinate in world units.
y
float
Y coordinate in world units.
z
float
Z coordinate in world units.
data
table
Data of the entity.
type
string
Type of the entity.
The example below shows an update message being handled by printing out all the key-value pairs in the message's data table.
If you wish to send a message to the server, it must be sent to the Master Component (or its whole GameObject). It will be received by the player entity (player.lua) on the server. All messages are handled by the player entity's message function on the server side API. Messages from the client can be identified by the Client field. To use, send a message with ID hash("pp_message")
to the Master Component where the message content is the Lua table to be sent as a message.
pp_init
Send this to the master component to connect to the PP servers.
For anonymous games, nothing, otherwise: username
and password
.
pp_join
Send this to the master component to spawn your player into the world.
None.
pp_message
Send this to the master component to send a message to your server-side player script.
Arbitrary table.
pp_disconnect
Send this to the master component to disconnect from PP's servers.
None.
pp_update
Sent to an entity or chunk (and the listener) when it changes its server-side state.
See above table for pp_update
message format.
pp_spawn
Sent to the listener when a new entity or chunk spawns.
Same as pp_update
.
pp_delete
Sent to the listener when an entity or chunk is removed.
Same as pp_update
.
pp_authentication_error
Sent to the listener when PP fails to authenticate.
Short error string (error
), an error code (code
) and a longer message (message
).
pp_connected
Sent to the listener when the client successfully connects and authenticates.
The connected player's uuid
.
pp_disconnected
Sent to the listener when the client disconnects from PP's servers.
A message
field explaining cause of disconnection.
pp_connection_error
Send to the listener when there is an error during initial connection.
The error
string.