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 context.Context REQUIREDThe context object represents information about the match and server for information purposes.
logger runtime.Logger REQUIREDThe logger allows access to log messages at variable severity.
db *sql.DB REQUIREDDatabase object that may be used to access the underlying game database.
nk runtime.NakamaModule REQUIREDExposes runtime functions to interact with various server systems and features.
params map[string]interface{} 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 interface{}The 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 intTick 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

func (m *Match) MatchInit(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, params map[string]interface{}) (interface{}, int, string) {
	state := &MatchState{Debug: true} // Define custom MatchState in the code as per your game's requirements
	tickRate := 1                     // Call MatchLoop() every 1s.
	label := "skill=100-150"          // Custom label that will be used to filter match listings.

	return state, tickRate, 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 context.Context REQUIREDThe context object represents information about the match and server for information purposes.
logger runtime.Logger REQUIREDThe logger allows access to log messages at variable severity.
db *sql.DB REQUIREDDatabase object that may be used to access the underlying game database.
nk runtime.NakamaModule REQUIREDExposes runtime functions to interact with various server systems and features.
dispatcher runtime.MatchDispatcher REQUIREDExposes useful functions to the match, and may be used by the server to send messages to the participants of the match.
tick int64 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 interface{} 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 []runtime.Presence REQUIREDA list of presences that have successfully completed the match join process.
Returns
NameDescription
state interface{}An (optionally) updated state. May be any non-nil value, or nil to end the match.
1
2
3
4

func (m *Match) MatchJoin(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, dispatcher runtime.MatchDispatcher, tick int64, state interface{}, presences []runtime.Presence) interface{} {
	// Custom code to process match join and send updated state to a joining or re-joining user.
	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 context.Context REQUIREDThe context object represents information about the match and server for information purposes.
logger runtime.Logger REQUIREDThe logger allows access to log messages at variable severity.
db *sql.DB REQUIREDDatabase object that may be used to access the underlying game database.
nk runtime.NakamaModule REQUIREDExposes runtime functions to interact with various server systems and features.
dispatcher runtime.MatchDispatcher REQUIREDExposes useful functions to the match, and may be used by the server to send messages to the participants of the match.
tick int64 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 interface{} 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 runtime.Presence REQUIREDA presence structure containing identifying information for the user attempting to join the match.
metadata map[string]string REQUIREDArbitrary key-value pairs received from the client as part of the join request.
Returns
NameDescription
state interface{}An (optionally) updated state. May be any non-nil value, or nil to end the match.
result boolTrue if the join attempt should be allowed, False otherwise.
reason stringIf the join attempt should be rejected, an optional string rejection reason can be returned to the client.
1
2
3
4
5
6

func (m *Match) MatchJoinAttempt(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, dispatcher runtime.MatchDispatcher, tick int64, state interface{}, presence runtime.Presence, metadata map[string]string) (interface{}, bool, string) {
	result := true

	// Custom code to process match join attempt.
	return state, result, ""
}

MatchLeave #

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

Parameters
NameDefaultDescription
ctx context.Context REQUIREDThe context object represents information about the match and server for information purposes.
logger runtime.Logger REQUIREDThe logger allows access to log messages at variable severity.
db *sql.DB REQUIREDDatabase object that may be used to access the underlying game database.
nk runtime.NakamaModule REQUIREDExposes runtime functions to interact with various server systems and features.
dispatcher runtime.MatchDispatcher REQUIREDExposes useful functions to the match, and may be used by the server to send messages to the participants of the match.
tick int64 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 interface{} 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 []runtime.Presence REQUIREDA list of presences that have left the match.
Returns
NameDescription
state interface{}An (optionally) updated state. May be any non-nil value, or nil to end the match.
1
2
3
4

func (m *Match) MatchLeave(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, dispatcher runtime.MatchDispatcher, tick int64, state interface{}, presences []runtime.Presence) interface{} {
	// Custom code to handle a disconnected/leaving user.
	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 context.Context REQUIREDThe context object represents information about the match and server for information purposes.
logger runtime.Logger REQUIREDThe logger allows access to log messages at variable severity.
db *sql.DB REQUIREDDatabase object that may be used to access the underlying game database.
nk runtime.NakamaModule REQUIREDExposes runtime functions to interact with various server systems and features.
dispatcher runtime.MatchDispatcher REQUIREDExposes useful functions to the match, and may be used by the server to send messages to the participants of the match.
tick int64 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 interface{} 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 []runtime.MatchData REQUIREDA list of data messages received from users between the previous and current tick.
Returns
NameDescription
state interface{}An (optionally) updated state. May be any non-nil value, or nil to end the match.
1
2
3
4
5
6
7

func (m *Match) MatchLoop(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, dispatcher runtime.MatchDispatcher, tick int64, state interface{}, messages []runtime.MatchData) interface{} {
	// Custom code to:
	// - Process the messages received.
	// - Update the match state based on the messages and time elapsed.
	// - Broadcast new data messages to match participants.
	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 context.Context REQUIREDThe context object represents information about the match and server for information purposes.
logger runtime.Logger REQUIREDThe logger allows access to log messages at variable severity.
db *sql.DB REQUIREDDatabase object that may be used to access the underlying game database.
nk runtime.NakamaModule REQUIREDExposes runtime functions to interact with various server systems and features.
dispatcher runtime.MatchDispatcher REQUIREDExposes useful functions to the match, and may be used by the server to send messages to the participants of the match.
tick int64 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 interface{} 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 interface{}An (optionally) updated state. May be any non-nil value, or nil to end the match.
data stringArbitrary data to return to the runtime caller of the signal. May be a string or nil.
1
2
3

func (m *Match) MatchSignal(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, dispatcher runtime.MatchDispatcher, tick int64, state interface{}, data string) (interface{}, string) {
	return state, "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 context.Context REQUIREDThe context object represents information about the match and server for information purposes.
logger runtime.Logger REQUIREDThe logger allows access to log messages at variable severity.
db *sql.DB REQUIREDDatabase object that may be used to access the underlying game database.
nk runtime.NakamaModule REQUIREDExposes runtime functions to interact with various server systems and features.
dispatcher runtime.MatchDispatcher REQUIREDExposes useful functions to the match, and may be used by the server to send messages to the participants of the match.
tick int64 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 interface{} 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 int REQUIREDThe number of seconds provided to complete a graceful termination before a match is forcefully closed.
Returns
NameDescription
state interface{}An (optionally) updated state. May be any non-nil value, or nil to end the match.
1
2
3
4

func (m *Match) MatchTerminate(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, dispatcher runtime.MatchDispatcher, tick int64, state interface{}, graceSeconds int) interface{} {
	// Custom code to process the termination of match.
	return state
}