Heroic Labs Documentation

Sockets #

Socket connections are used in Nakama to enable real-time communication and gameplay between the game server and clients. Clients can establish a socket connection to the server, allowing the server to send data to and receive data from the client, enabling use of the real-time features in Nakama.

There are many different ways that socket connections can be used in Nakama, depending on the specific requirements of the game. Socket connections can be used in Nakama to enable:

  • Tracking online status: Socket connections can be used to track which clients are online and available for gameplay. This allows you to keep track of which clients are active and which are inactive, and can help you manage resources effectively.
  • Sending and receiving data: Socket connections are used to send and receive data between the game server and clients. This can include gameplay data, such as player movements and actions, as well as other types of data, such as chat messages and system messages.

Socket connections are a key tool for enabling real-time communication and gameplay in Nakama, and they are used for a variety of features, including chat, parties, multiplayer, and more.

Socket connection lifecycle #

Socket connections are established between the game server and clients, and they are used to send and receive data between the two. The lifecycle of a socket connection is as follows:

  1. The client establishes a socket connection
  2. The client sends and receives data to and from the server
  3. The client disconnects from the server

Establishing a socket connection #

A socket is created from the client object:

Client
1
2
3
4
5
var socket = client.NewSocket();

bool appearOnline = true;
int connectionTimeout = 30;
await socket.ConnectAsync(Session, appearOnline, connectionTimeout);
Client
1
2
3
4
const socket = client.createSocket();

var appearOnline = true;
await socket.connect(session, appearOnline);
Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Make this a node variable or it will disconnect when the function that creates it returns

onready var socket := Nakama.create_socket_from(client)

func _ready():
    var connected : NakamaAsyncResult = yield(socket.connect_async(session), "completed")
    if connected.is_exception():
        print("An error occurred: %s" % connected)
        return
    print("Socket connected.")
Client
1
2
3
4
5
NRtClientPtr rtClient;
rtClient = client->createRtClient();

bool createStatus = true;
rtClient->connect(session, createStatus);
Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
SocketClient socket = client.createWebSocket();

SocketListener listener = new AbstractSocketListener() {
    @Override
    public void onDisconnect(final Throwable t) {
        logger.info("Socket disconnected.");
    }
};

socket.connect(session, listener).get();
logger.info("Socket connected.");
Client
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
local socket = nakama.create_socket(client)

nakama.sync(function()
    -- connect
    local ok, err = nakama.socket_connect(socket)

    if ok then
      -- do socket stuff
    end

    if err then
      print(err.message)
    end
end)

Code snippet for this language cURL has not been found. Please choose another language to show equivalent examples.
Code snippet for this language REST has not been found. Please choose another language to show equivalent examples.

Sending and receiving data #

Once a socket connection has been established, the client can send and receive data to and from the server. This connection is used for all real-time features of Nakama. See specific examples on the pages for these features:

Disconnecting from the server #

Socket connections are closed when the client disconnects from the server. This can also be done manually by calling the given method on the socket:

Client
1
socket.CloseAsync();
Client
1
socket.disconnect();
Client
1
2
socket.close()
print("Socket disconnected.")
Client
1
rtClient->disconnect();
Client
1
socket.disconnect().get()
Client
1
-- Sockets can not be manually closed in Defold

Code snippet for this language cURL has not been found. Please choose another language to show equivalent examples.
Code snippet for this language REST has not been found. Please choose another language to show equivalent examples.

Socket events #

There are a number of events that can be used to monitor the state of a socket connection or events that occur on the socket, which can be used to trigger actions in your game.

The following events are available for socket connections:

EventDescription
closedReceived when a socket connection is closed.
connectedReceived when a socket connection is connected.
ReceivedChannelMessageMessage received on a chat channel.
ReceivedChannelPresenceA user has joined or left a chat channel.
ReceivedErrorAn error has occurred on the socket.
ReceivedMatchmakerMatchedReceived a message indicating the matchmaker has found a match.
ReceivedMatchStateGame state from a multiplayer match.
ReceivedMatchPresenceA user has joined or left a multiplayer match.
ReceivedNotificationThe current user has received a notification.
ReceivedPartyReceived a party event. This occurs when the current user’s invitation request is accepted by the party leader of a closed party.
ReceivedPartyCloseThe current party has been closed.
ReceivedPartyDataReceived custom party data, such as party chat messages.
ReceivedPartyJoinRequestRequest from a user to join a party.
ReceivedPartyLeaderIndicates the party leader has been changed.
ReceivedPartyMatchmakerTicketReceived a new matchmaker ticket for the party.
ReceivedPartyPresenceA user has joined or left the party.
ReceivedStatusPresenceReceived a change to a user’s updated online status.
ReceivedStreamPresenceA user has joined or left a realtime stream.
ReceivedStreamStateReceived a message from a realtime stream.