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.

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.

 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.

 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.

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.

 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.

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.

1
2
3

local function match_terminate(context, dispatcher, tick, state, grace_seconds)
	return state
  end