Match Handler Reference #

This page lists all functions for Nakama’s Server Authoritative multiplayer match handler. To register a match handler, see the match handler documentation.

Match handler #

match_init #

Invoked when a match is created as a result of the match create function and sets up the initial state of a match. This will be called once at match start.

Parameters
NameDefaultDescription
ctx table REQUIREDThe context object represents information about the match and server for information purposes.
params table REQUIREDOptional arbitrary second argument passed to match_create(), or nil if none was used. This can be matched users or any other data you'd like to pass into this function.
Returns
NameDescription
state tableThe initial in-memory state of the match. May be any non-nil Lua term, or nil to end the match.
tick_rate numberTick rate representing the desired number of match_loop() calls per second. Must be between 1 and 60, inclusive.
label stringA string label that can be used to filter matches in listing operations. Must be between 0 and 2048 bytes long. This is used in match listing to filter matches.
1
2
3
4
5
6
7
function match_init(context, params)
	local state = {}
	local tick_rate = 1
	local label = "skill=100-150"
  
	return state, tick_rate, label
  end

match_join #

Executed when one or more users have successfully completed the match join process after their match_join_attempt() returns true. When their presences are sent to this function the users are ready to receive match data messages and can be targets for the dispatcher's broadcast_message() function.

Parameters
NameDefaultDescription
ctx table REQUIREDThe context object represents information about the match and server for information purposes.
dispatcher table REQUIREDExposes useful functions to the match, and may be used by the server to send messages to the participants of the match.
tick number REQUIREDTick is the current match tick number, starts at 0 and increments after every match_loop call. Does not increment with calls to match_join_attempt, match_join, or match_leave, match_terminate, or match_signal.
state table REQUIREDThe current in-memory match state, may be any Lua term except nil.
presences table REQUIREDA list of users that have successfully completed the match join process.
Returns
NameDescription
state tableAn (optionally) updated state. May be any non-nil Lua term, or nil to end the match.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
local function match_join(context, dispatcher, tick, state, presences)
	-- Presences format:
	-- {
	--   {
	--     user_id = "user unique ID",
	--     session_id = "session ID of the user's current connection",
	--     username = "user's unique username",
	--     node = "name of the Nakama node the user is connected to"
	--   },
	--  ...
	-- }
	return state
  end

match_join_attempt #

Executed when a user attempts to join the match using the client's match join operation. Match join attempt can be used to prevent more players from joining after a match has started or disallow the user for any other game specific reason.

Parameters
NameDefaultDescription
ctx table REQUIREDThe context object represents information about the match and server for information purposes.
dispatcher table REQUIREDExposes useful functions to the match, and may be used by the server to send messages to the participants of the match.
tick number REQUIREDTick is the current match tick number, starts at 0 and increments after every match_loop call. Does not increment with calls to match_join_attempt, match_join, or match_leave, match_terminate, or match_signal.
state table REQUIREDThe current in-memory match state, may be any Lua term except nil.
presence table REQUIREDThe user attempting to join the match.
metadata table REQUIREDArbitrary key-value pairs (both as 'strings') received from the client as part of the join request.
Returns
NameDescription
state tableAn (optionally) updated state. May be any non-nil Lua term, or nil to end the match.
accepted boolTrue if the join attempt should be allowed, False otherwise.
reject_message stringIf the join attempt should be rejected, an optional string rejection reason can be returned to the client.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
local function match_join_attempt(context, dispatcher, tick, state, presence, metadata)
	-- Presence format:
	-- {
	--   user_id = "user unique ID",
	--   session_id = "session ID of the user's current connection",
	--   username = "user's unique username",
	--   node = "name of the Nakama node the user is connected to"
	-- }
	return state, true
  end

match_leave #

Executed when one or more users have left the match for any reason including connection loss.

Parameters
NameDefaultDescription
ctx table REQUIREDThe context object represents information about the match and server for information purposes.
dispatcher table REQUIREDExposes useful functions to the match, and may be used by the server to send messages to the participants of the match.
tick number REQUIREDTick is the current match tick number, starts at 0 and increments after every match_loop call. Does not increment with calls to match_join_attempt, match_join, or match_leave, match_terminate, or match_signal.
state table REQUIREDThe current in-memory match state, may be any Lua term except nil.
presences table REQUIREDA list of users that have left the match.
Returns
NameDescription
state tableAn (optionally) updated state. May be any non-nil Lua term, or nil to end the match.
1
2
3
local function match_leave(context, dispatcher, tick, state, presences)
	return state
  end

match_loop #

Executed on an interval based on the tick rate returned by match_init. Each tick the match loop is run which can process messages received from clients and apply changes to the match state before the next tick. It can also dispatch messages to one or more connected opponents. To send messages back to the opponents in the match you can keep track of them in the game state and use the dispatcher object to send messages to subsets of the users or all of them.

Parameters
NameDefaultDescription
ctx table REQUIREDThe context object represents information about the match and server for information purposes.
dispatcher table REQUIREDExposes useful functions to the match, and may be used by the server to send messages to the participants of the match.
tick number REQUIREDTick is the current match tick number, starts at 0 and increments after every match_loop call. Does not increment with calls to match_join_attempt, match_join, or match_leave, match_terminate, or match_signal.
state table REQUIREDThe current in-memory match state, may be any Lua term except nil.
messages table REQUIREDA list of data messages received from users between the previous and current tick.
Returns
NameDescription
state tableAn (optionally) updated state. May be any non-nil Lua term, or nil to end the match.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
local function match_loop(context, dispatcher, tick, state, messages)
	-- Messages format:
	-- {
	--   {
	--     sender = {
	--       user_id = "user unique ID",
	--       session_id = "session ID of the user's current connection",
	--       username = "user's unique username",
	--       node = "name of the Nakama node the user is connected to"
	--     },
	--     op_code = 1, -- numeric op code set by the sender.
	--     data = "any string data set by the sender" -- may be nil.
	--   },
	--   ...
	-- }
	return state
  end

match_signal #

Called when the match handler receives a runtime signal. Match signals allow the match handler to be sent a reservation signal to mark a user ID or session ID into the match state ahead of their join attempt and eventual join flow. This is useful to apply reservations to a matchmaking system with Nakama's matchmaker or match listings APIs.

Parameters
NameDefaultDescription
ctx table REQUIREDThe context object represents information about the match and server for information purposes.
dispatcher table REQUIREDExposes useful functions to the match, and may be used by the server to send messages to the participants of the match.
tick number REQUIREDTick is the current match tick number, starts at 0 and increments after every match_loop call. Does not increment with calls to match_join_attempt, match_join, or match_leave, match_terminate, or match_signal.
state table REQUIREDThe current in-memory match state, may be any Lua term except nil.
data string REQUIREDAn arbitrary input supplied by the runtime caller of the signal.
Returns
NameDescription
state tableAn (optionally) updated state. May be any non-nil Lua term, or nil to end the match.
data stringArbitrary data to return to the runtime caller of the signal. May be a string or null.
1
2
3
local function match_signal(context, dispatcher, tick, state, data)
	return state, "signal received: " .. data
  end

match_terminate #

Called when the server begins a graceful shutdown process. Will not be called if graceful shutdown is disabled. The match should attempt to complete any processing before the given number of seconds elapses, and optionally send a message to clients to inform them the server is shutting down. When the grace period expires the match will be forcefully closed if it is still running, clients will be disconnected, and the server will shut down.

Parameters
NameDefaultDescription
ctx table REQUIREDThe context object represents information about the match and server for information purposes.
dispatcher table REQUIREDExposes useful functions to the match, and may be used by the server to send messages to the participants of the match.
tick number REQUIREDTick is the current match tick number, starts at 0 and increments after every match_loop call. Does not increment with calls to match_join_attempt, match_join, or match_leave, match_terminate, or match_signal.
state table REQUIREDThe current in-memory match state, may be any Lua term except nil.
grace_seconds number REQUIREDThe number of seconds provided to complete a graceful termination before a match is forcefully closed.
Returns
NameDescription
state tableAn (optionally) updated state. May be any non-nil Lua term, or nil to end the match.
1
2
3
local function match_terminate(context, dispatcher, tick, state, grace_seconds)
	return state
  end