Defold Client Guide #
The client is built in Lua 5.1 on top of the Defold game engine. It is available at GitHub. It can also be used by other engines running lua, see how.
Full API documentation #
For the full API documentation please visit the API docs.
Setup #
Add the client to your project. #
Add the URL of a client release .zip as a library dependency to game.project
. The client will now show up as a nakama
folder in your project.
Add Defold plugins. #
Defold projects additionally require the following modules:
- https://github.com/britzl/defold-websocket/archive/1.6.0.zip
- https://github.com/britzl/defold-luasocket/archive/0.11.1.zip
- https://github.com/britzl/defold-luasec/archive/1.1.0.zip
Authenticate #
There are many options when it comes to authentication. In this example we’ll do it with email and password but it’s just as easy to use a social profile from Google Play Games, Facebook, Game Center, etc.
|
|
Sessions #
When client authenticates, the server responds with an auth token (JWT) which should be used when making API requests. The token contains useful properties and gets deserialized into a session
table.
|
|
It is recommended to store the auth token from the session and check at startup if it has expired. If the token has expired you must reauthenticate. The expiry time of the token can be changed as a setting in the server.
|
|
Send requests #
The client includes many APIs for Nakama game server features. These can be accessed with the methods which either use a callback function to return a result or block until a response is available. You absolutely cannot use the blocking variety unless running in a coroutine.
|
|
The Nakama client provides a convenience function for creating and starting a coroutine to run multiple requests synchronously:
|
|
Socket messages #
The client can create one or more sockets with the server. Each socket can have it’s own event listeners registered for responses received from the server.
|
|
You can connect to the server over a realtime socket connection to send and receive chat messages, get notifications, and matchmake into a multiplayer match. You can also execute remote code on the server via RPC.
Handle events #
A socket object has event handlers which are called on various messages received from the server.
Event handlers only need to be implemented for the features you want to use.
Callbacks | Description |
---|---|
on_disconnect | Received when the client is disconnected from the server. |
on_error | Receives events about server errors. |
on_notification | Receives live in-app notifications sent from the server. |
on_channelmessage | Receives realtime chat messages sent by other users. |
on_channelpresence | Receives join and leave events within chat. |
on_matchdata | Receives realtime multiplayer match data. |
on_matchpresence | Receives join and leave events within realtime multiplayer. |
on_matchmakermatched | Received when the matchmaker has found a suitable match. |
on_statuspresence | Receives status updates when subscribed to a user status feed. |
on_streampresence | Receives stream join and leave event. |
on_streamdata | Receives stream data sent by the server. |
Logs and errors #
The server and the client can generate logs which are helpful for debugging.
To enable verbose logging when you work on a client:
|
|
For production use
|
|
Full example #
A small example on how to manage a session object with Defold engine and the Lua client.
|
|
Adapting to other engines #
Adapting the Nakama Defold client to other Lua-based engines should be as easy as providing a different engine module when configuring the Nakama client:
|
|
The engine module must provide the following functions:
http(config, url_path, query_params, method, post_data, callback)
- Make HTTP request.config
- Config table passed tonakama.create()
url_path
- Path to append to the base uriquery_params
- Key-value pairs to use as URL query parametersmethod
- “GET”, “POST”post_data
- Data to postcallback
- Function to call with result (response)
socket_create(config, on_message)
- Create socket. Must return socket instance (table with engine specific socket state).config
- Config table passed tonakama.create()
on_message
- Function to call when a message is sent from the server
socket_connect(socket, callback)
- Connect socket.socket
- Socket instance returned fromsocket_create()
callback
- Function to call with result (ok, err)
socket_send(socket, message, callback)
- Send message on socket.socket
- Socket instance returned fromsocket_create()
message
- Message to sendcallback
- Function to call with message returned as a response (message)