Match Runtime Reference #

This page lists all functions exposed in the match handler Dispatcher type.

Match runtime #

BroadcastMessage #

Send a message to one or more presences. This may be called at any point in the match loop to give match participants information about match state changes. May also be useful inside the match join callback to send initial state to the user on successful join. Note that when broadcasting to multiple presences, if any presence is invalid then the broadcast will not occur.

Parameters
NameDefaultDescription
opCode number REQUIREDNumeric message op code.
data string REQUIREDData to be sent to the provided presences.
presences nkruntime.Presence[] REQUIREDList of presences (a subset of match participants) to use as message targets, or 'null' to send to the whole match.
sender nkruntime.Presence REQUIREDA presence to tag on the message as the sender, or 'null'.
Returns
NameDescription
error errorAn optional error that may indicate a problem broadcasting data to match participants.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

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');
  
	const opCode = 1234;
	const message = JSON.stringify({ hello: 'world' });
	const presences = null; // Send to all.
	const sender = null; // Used if a message should come from a specific user.
	dispatcher.broadcastMessage(opCode, message, presences, sender, true);
  
	return {
	  state
	};
  }

MatchKick #

Removes participants from the match. Call at any point during the match loop to remove participants based on misbehavior or other game-specific rules.

Parameters
NameDefaultDescription
presences nkruntime.Presence[] REQUIREDA list of match participant presences to remove from the match.
Returns
NameDescription
error errorAn optional error that may indicate a problem kicking the selected match participants.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

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');
  
	// For example we'll kick everyone that sends a message on or after tick 10.
	if (tick >= 10) {
	  dispatcher.matchKick(messages.map(function (message) {
			return message.sender;
		}));
	}
  
	return {
	  state

MatchLabelUpdate #

Sets a new label for the match.

Parameters
NameDefaultDescription
label string REQUIREDNew label to set for the match.
Returns
NameDescription
error errorAn optional error that may indicate a problem applying the new match label.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// Match Label Update
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');
  
	// As an example update the match label in the 10th match tick.
	if (tick === 10) {
	  dispatcher.matchLabelUpdate("Crossed 10 ticks!");
	}
  
	return {
	  state