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

Name	Default	Description
opCode number REQUIRED		Numeric message op code.
data string REQUIRED		Data to be sent to the provided presences.
presences lgruntime.Presence[] REQUIRED		List of presences (a subset of match participants) to use as message targets, or 'null' to send to the whole match.
sender lgruntime.Presence REQUIRED		A presence to tag on the message as the sender, or 'null'.

Returns

Name	Description
error error	An optional error that may indicate a problem broadcasting data to match participants.

const matchLoop = function (ctx: lgruntime.Context, logger: lgruntime.Logger, lg: lgruntime.LayerG, dispatcher: lgruntime.MatchDispatcher, tick: number, state: lgruntime.MatchState, messages: lgruntime.MatchMessage[]) : { state: lgruntime.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

Name	Default	Description
presences lgruntime.Presence[] REQUIRED		A list of match participant presences to remove from the match.

Returns

Name	Description
error error	An optional error that may indicate a problem kicking the selected match participants.

const matchLoop = function (ctx: lgruntime.Context, logger: lgruntime.Logger, lg: lgruntime.LayerG, dispatcher: lgruntime.MatchDispatcher, tick: number, state: lgruntime.MatchState, messages: lgruntime.MatchMessage[]) : { state: lgruntime.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

Name	Default	Description
label string REQUIRED		New label to set for the match.

Returns

Name	Description
error error	An optional error that may indicate a problem applying the new match label.

// Match Label Update
const matchLoop = function (ctx: lgruntime.Context, logger: lgruntime.Logger, lg: lgruntime.LayerG, dispatcher: lgruntime.MatchDispatcher, tick: number, state: lgruntime.MatchState, messages: lgruntime.MatchMessage[]) : { state: lgruntime.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
	  }
	};