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 #

MatchInit #

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 nkruntime.Context REQUIREDThe context object represents information about the match and server for information purposes.
logger nkruntime.Logger REQUIREDThe logger allows access to log messages at variable severity.
nk nkruntime.Nakama REQUIREDExposes runtime functions to interact with various server systems and features.
params {[key: string]: any} REQUIREDMap of various parameters that may be sent from MatchCreate() function while creating the match. It could be list of matched users, their properties or any other relevant information that you would like to pass to the match.
Returns
NameDescription
state nkruntime.MatchStateThe initial in-memory state of the match. May be any interface{} value that will store the match state as it progresses. It will be available to, and can be updated by, all match handler functions.
tickrate numberTick rate representing the desired number of MatchLoop() calls per second. Must be between 1 and 60, inclusive. For example a tickrate of 2 will call the match loop twice every second, which is every 500ms.
label stringA string label that can be used to filter matches in listing operations. Must be between 0 and 2048 characters long. This is used in match listing to filter matches.
1
2
3
4
5
6
7
8
9

const matchInit = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, params: {[key: string]: string}): {state: nkruntime.MatchState, tickRate: number, label: string} {
	logger.debug('Lobby match created');
  
	return {
	  state: { Debug: true },
	  tickRate: 10,
	  label: ""
	};
  };

MatchJoin #

Executed when one or more users have successfully completed the match join process after their MatchJoinAttempt() 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 BroadcastMessage() function.

Parameters
NameDefaultDescription
ctx nkruntime.Context REQUIREDThe context object represents information about the match and server for information purposes.
logger nkruntime.Logger REQUIREDThe logger allows access to log messages at variable severity.
nk nkruntime.Nakama REQUIREDExposes runtime functions to interact with various server systems and features.
dispatcher nkruntime.MatchDispatcher 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 MatchLoop call. Does not increment with calls to MatchJoinAttempt, MatchJoin, or MatchLeave.
state nkruntime.MatchState REQUIREDCustom match state interface, use this to manage the state of your game. You may choose any structure for this interface depending on your game's needs.
presences nkruntime.Presence[] REQUIREDA list of presences that have successfully completed the match join process.
Returns
NameDescription
state nkruntime.MatchStateAn (optionally) updated state. May be any non-null value, or null to end the match.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const matchJoin = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, dispatcher: nkruntime.MatchDispatcher, tick: number, state: nkruntime.MatchState, presences: nkruntime.Presence[]) : { state: nkruntime.MatchState } | null {
	presences.forEach(function (presence) {
	  state.presences[presence.userId] = presence;
	  logger.debug('%q joined Lobby match', presence.userId);
	});
  
	return {
	  state
	};
  }

MatchJoinAttempt #

Executed when a user attempts to join the match using the client's match join operation. This includes any re-join request from a client after a lost connection is resumed, where client will need to explicitly re-join upon reconnection. 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 nkruntime.Context REQUIREDThe context object represents information about the match and server for information purposes.
logger nkruntime.Logger REQUIREDThe logger allows access to log messages at variable severity.
nk nkruntime.Nakama REQUIREDExposes runtime functions to interact with various server systems and features.
dispatcher nkruntime.MatchDispatcher 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 MatchLoop call. Does not increment with calls to MatchJoinAttempt, MatchJoin, or MatchLeave.
state nkruntime.MatchState REQUIREDCustom match state interface, use this to manage the state of your game. You may choose any structure for this interface depending on your game's needs.
presence nkruntime.Presence REQUIREDA presence structure containing identifying information for the user attempting to join the match.
metadata {[key: string]: any } REQUIREDArbitrary key-value pairs received from the client as part of the join request.
Returns
NameDescription
state nkruntime.MatchStateAn (optionally) updated state. May be any non-null value, or null to end the match.
accept boolTrue if the join attempt should be allowed, False otherwise.
rejectMessage 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

const matchJoinAttempt = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, dispatcher: nkruntime.MatchDispatcher, tick: number, state: nkruntime.MatchState, presence: nkruntime.Presence, metadata: {[key: string]: any }) : {state: nkruntime.MatchState, accept: boolean, rejectMessage?: string | undefined } | null {
	logger.debug('%q attempted to join Lobby match', ctx.userId);
  
	return {
	  state,
	  accept: true
	};
  }

MatchLeave #

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

Parameters
NameDefaultDescription
ctx nkruntime.Context REQUIREDThe context object represents information about the match and server for information purposes.
logger nkruntime.Logger REQUIREDThe logger allows access to log messages at variable severity.
nk nkruntime.Nakama REQUIREDExposes runtime functions to interact with various server systems and features.
dispatcher nkruntime.MatchDispatcher 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 MatchLoop call. Does not increment with calls to MatchJoinAttempt, MatchJoin, or MatchLeave.
state nkruntime.MatchState REQUIREDCustom match state interface, use this to manage the state of your game. You may choose any structure for this interface depending on your game's needs.
presences nkruntime.Presence[] REQUIREDA list of presences that have left the match.
Returns
NameDescription
state nkruntime.MatchStateAn (optionally) updated state. May be any non-null value, or null to end the match.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const matchLeave = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, dispatcher: nkruntime.MatchDispatcher, tick: number, state: nkruntime.MatchState, presences: nkruntime.Presence[]) : { state: nkruntime.MatchState } | null {
	presences.forEach(function (presence) {
	  state.presences[presence.userId] = presence;
	  logger.debug('%q left Lobby match', presence.userId);
	});
  
	return {
	  state
	};
  }

MatchLoop #

Executed on an interval based on the tick rate returned by MatchInit(). 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 match participants. To send messages back to the participants 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 nkruntime.Context REQUIREDThe context object represents information about the match and server for information purposes.
logger nkruntime.Logger REQUIREDThe logger allows access to log messages at variable severity.
nk nkruntime.Nakama REQUIREDExposes runtime functions to interact with various server systems and features.
dispatcher nkruntime.MatchDispatcher 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 MatchLoop call. Does not increment with calls to MatchJoinAttempt, MatchJoin, or MatchLeave.
state nkruntime.MatchState REQUIREDCustom match state interface, use this to manage the state of your game. You may choose any structure for this interface depending on your game's needs.
messages nkruntime.MatchMessage[] REQUIREDA list of data messages received from users between the previous and current tick.
Returns
NameDescription
state nkruntime.MatchStateAn (optionally) updated state. May be any non-null value, or null to end the match.
1
2
3
4
5
6
7

const matchLoop = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, dispatcher: nkruntime.MatchDispatcher, tick: number, state: nkruntime.MatchState, messages: nkruntime.MatchMessage[]) : { state: nkruntime.MatchState} | null {
	logger.debug('Lobby match loop executed');
  
	return {
	  state
	};
  }

MatchSignal #

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 nkruntime.Context REQUIREDThe context object represents information about the match and server for information purposes.
logger nkruntime.Logger REQUIREDThe logger allows access to log messages at variable severity.
nk nkruntime.Nakama REQUIREDExposes runtime functions to interact with various server systems and features.
dispatcher nkruntime.MatchDispatcher 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 MatchLoop call. Does not increment with calls to MatchJoinAttempt, MatchJoin, or MatchLeave.
state nkruntime.MatchState REQUIREDCustom match state interface, use this to manage the state of your game. You may choose any structure for this interface depending on your game's needs.
data string REQUIREDAn arbitrary input supplied by the runtime caller of the signal.
Returns
NameDescription
state nkruntime.MatchStateAn (optionally) updated state. May be any non-null value, or null 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
4
5
6
7
8

const matchSignal = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, dispatcher: nkruntime.MatchDispatcher, tick: number, state: nkruntime.MatchState, data: string) : { state: nkruntime.MatchState, data?: string } | null {
	logger.debug('Lobby match signal received: ' + data);
  
	return {
	  state,
	  data: "Lobby match signal received: " + data
	};
  }

MatchTerminate #

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 nkruntime.Context REQUIREDThe context object represents information about the match and server for information purposes.
logger nkruntime.Logger REQUIREDThe logger allows access to log messages at variable severity.
nk nkruntime.Nakama REQUIREDExposes runtime functions to interact with various server systems and features.
dispatcher nkruntime.MatchDispatcher 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 MatchLoop call. Does not increment with calls to MatchJoinAttempt, MatchJoin, or MatchLeave.
state nkruntime.MatchState REQUIREDCustom match state interface, use this to manage the state of your game. You may choose any structure for this interface depending on your game's needs.
graceSeconds number REQUIREDThe number of seconds provided to complete a graceful termination before a match is forcefully closed.
Returns
NameDescription
state nkruntime.MatchStateAn (optionally) updated state. May be any non-null value, or null to end the match.
1
2
3
4
5
6
7

const matchTerminate = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, dispatcher: nkruntime.MatchDispatcher, tick: number, state: nkruntime.MatchState, graceSeconds: number) : { state: nkruntime.MatchState} | null {
	logger.debug('Lobby match terminated');
  
	return {
	  state
	};
  }