Sockets

Socket connections are used in Nakama to enable real-time communication and gameplay between servers 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:

1
2
3
4
5
6
7
8
9

var socket = client.NewSocket();

bool appearOnline = true;
int connectionTimeout = 30;
await socket.ConnectAsync(Session, appearOnline, connectionTimeout);

// If you want socket handlers to execute outside of the main thread,
// pass 'useMainThread' as false when creating the socket
var socket = client.NewSocket(useMainThread: false);

1
2
3

let socket = client.createSocket() as! Socket

socket.connect(session: session, appearOnline: true)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const host = '127.0.0.1';
const ssl = false;

final socket = NakamaWebsocketClient.init(
  host: 'host',
  ssl: ssl,
  token: session.token,
);

// The socket automatically connects after created

1
2
3
4

const socket = client.createSocket();

var appearOnline = true;
await socket.connect(session, appearOnline);

 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.")

 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 = await socket.connect_async(session)
    if connected.is_exception():
        print("An error occurred: %s" % connected)
        return
    print("Socket connected.")

1
2
3
4
5

NRtClientPtr rtClient;
rtClient = client->createRtClient();

bool createStatus = true;
rtClient->connect(session, createStatus);

 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.");

 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)

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:

• Chat
• Parties
• Multiplayer
• Status

Realtime messages have a per-message size limit set by socket.max_message_size_bytes, 4 KB by default. A single socket message larger than this limit, such as a large RPC payload sent over the socket, causes the server to close the connection. For large payloads, send the RPC over HTTP instead, which uses the larger socket.max_request_size_bytes limit (256 KB by default), or split the data into smaller messages.

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:

1

socket.CloseAsync();

1

socket.disconnect()

1

await socket.close();

1

socket.disconnect();

1
2

socket.close()
print("Socket disconnected.")

1
2

socket.close()
print("Socket disconnected.")

1

rtClient->disconnect();

1

socket.disconnect().get()

1

-- Sockets can not be manually closed in Defold

When the server initiates the disconnect, it waits up to socket.close_ack_wait_ms (2 seconds by default) for the client to acknowledge the close before dropping the connection. A client that never acknowledges can make a server-initiated disconnect appear to hang until this timeout elapses.

The server can also close a connection on its own when the client stops answering the heartbeat, which usually means long blocking work on the client stalled its network loop. For the timings, the causes, and how to avoid it, see Socket heartbeat disconnects .

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: