Match Runtime Reference #

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

Match runtime #

broadcast_message #

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
op_code number REQUIREDNumeric message op code.
data string REQUIREDData to be sent to the provided presences, or nil.
presences table REQUIREDList of presences (a subset of match participants) to use as message targets, or 'nil' to send to the whole match.
sender nkruntime.Presence REQUIREDA presence to tag on the message as the sender, or 'nil'.
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

local nk = require("nakama")

function match_loop(context, dispatcher, tick, state, messages)
  local opcode = 1234
  local message = { ["hello"] = "world" }
  local encoded = nk.json_encode(message)
  local presences = nil -- send to all.
  local sender = nil -- used if a message should come from a specific user.
  dispatcher.broadcast_message(opcode, encoded, presences, sender)

  return state
end

match_kick #

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 table 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

local nk = require("nakama")

function match_loop(context, dispatcher, tick, state, messages)
  -- Assume we store presences in state
  dispatcher.match_kick(state.presences)
  return state
end

match_label_update #

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

local nk = require("nakama")

function match_loop(context, dispatcher, tick, state, messages)
  dispatcher.match_label_update("updatedlabel")
  return state
end