# 权威多人游戏

**URL:** https://heroiclabs.com/docs/zh/nakama/concepts/multiplayer/authoritative/
**Summary:** 权威多人游戏适合的游戏依赖于游戏服务器管理的中央状态。Nakama权威多人游戏引擎引入了一种以固定节拍率运行自定义匹配逻辑的方法。消息可以验证，状态更改可以广播到连接的对等方。

---


# 权威多人游戏

除了[中继多人游戏](../relayed/)之外，Nakama还支持服务器权威的多人模式，让您可以自由灵活地决定最适合您游戏的方法。

在服务器权威的多人游戏中，服务器验证并广播所有游戏数据交换。在这个模式中，您可以为游戏规则编写自定义服务器运行时代码（即多少玩家可以加入，是否可以加入进行中的比赛等等），交由 Nakama 强制执行。

没有强有力的决定因素限制采取中继还是权威的方法，这是基于所需游规则的设计决定。权威多人游戏更适合于依赖于游戏服务器管理中央状态的游戏、每场比赛玩家数量更高的游戏，以及您不想信任游戏客户端，而是希望对游戏规则进行更严格的控制，以尽量减少作弊等游戏。

为了支持需要数据消息来改变服务器上维护的状态的多人游戏设计，权威多人引擎使您能够以固定的节拍率运行自定义匹配逻辑。消息可以验证，状态更改可以广播到连接的对等方。这样您就能构建：

1. **异步实时权威多人游戏**：快节奏实时多人游戏。消息被发送到服务器，服务器计算环境和玩家的变化，数据被广播到相关的对等方。这通常需要较高的数据接收和计算率才能让游戏流畅。
2. **主动回合制多人游戏**：例子有Stormbound或Clash Royale，两个或多个玩家连接在一起，进行快速回合比赛。玩家需要立即响应回合。服务器接收输入，对其验证，然后广播给玩家。预期的节拍率非常低，因为发送和接收消息的速率很低。
3. **被动回合制多人游戏**：一个很好的例子是手机上的Words With Friends，其中游戏可以持续数小时至数周。服务器接收并验证输入，将其存储在数据库中，并在关闭服务器循环之前将变化广播到任何连接的对等方，直到下一个游戏序列为止。
4. **会话制多人游戏**：对于您希望物理运行在服务器端的复杂游戏（例如Unity无头实例）。Nakama可以通过编排层管理这些无头实例，并可以用于[匹配](../matchmaker/)、在比赛结束时移动玩家以及报告比赛结果。

注意，在构建服务器权威的多人游戏时，没有现成或通用的场景。您必须通过编写自定义[运行时代码](../../../server-framework/)来定义游戏玩法——每场比赛有多少玩家、是否允许中途加入、比赛如何结束等等。

在决定实施权威多人游戏功能时，您需要熟悉几个概念。

## 比赛处理程序

匹配处理程序表示所有服务器端功能，这些功能组合在一起以处理游戏输入并对其进行操作。将其视为实例化比赛的“蓝图”。比赛处理程序为比赛建立游戏规则，因为一场比赛可能有多种玩法模式（例如夺旗、死亡竞赛、完全免费等），您可能需要多个比赛处理程序 — 每个游戏模式一个。

任何比赛处理程序都需要使用7个函数。只有Nakama调用这些函数，客户端或其他运行时代码**无法**直接调用。

* Match Init
* Match Join Attempt
* Match Join
* Match Leave
* Match Loop
* Match Terminate
* Match Signal

请参阅[Match Handler](../../../server-framework/typescript-runtime/function-reference/match-handler/)和[Match Runtime](../../../server-framework/typescript-runtime/function-reference/match-runtime/)函数参考了解详情。

这些函数定义了给定比赛的状态和生命周期，任何一个Nakama节点都可以根据硬件和玩家数量运行数千场比赛。给定比赛的比赛处理程序和状态存储在特定的Nakama实例上，该实例成为该比赛的_主机_。

单个节点负责实现该功能，以确保访问和更新状态的最高水准的一致性，并避免协调分布式状态的潜在延迟。

{{< note "important" "Nakama Enterprise Only" >}}
对比赛状态进行复制，因此群集中的所有节点都可以立即访问比赛列表和比赛参与者的详细信息。节点之间的平衡自动完成，在最合适的节点上但从不在已进入关闭状态的节点上创建新的比赛。

从Nakama开源迁移到Nakama Enterprise是无缝操作，不需要更改客户端或服务器端的任何代码。状态复制、集群间数据交换和消息路由对比赛处理程序都是透明的，如同在单个实例集群上运行。
{{< /note >}}

每一场运行中的比赛都是独立的，不能与任何其他比赛通信或影响任何其他比赛。比赛通信**仅**通过客户端发送比赛数据而完成。Nakama在内部管理每场比赛的CPU调度和内存分配，确保在集群中的单个实例或所有实例上公平和平衡地分配负载。

{{< note "important" >}}
比赛信号功能可以在一定限度上实现这一点：在比赛中为给定的玩家保留一个位置，或者将玩家/数据切换到另一场比赛。应当仅将此用作**极少数异常**而不是标准做法。
{{< /note >}}

即使没有连接的或活动的状态，比赛处理程序也可以运行。在比赛运行时逻辑中，必须考虑空闲或空的比赛的处理。

{{< code type="server" >}}
```go
type LobbyMatch struct{}

type LobbyMatchState struct {
	presences  map[string]runtime.Presence
	emptyTicks int
}

func (m *LobbyMatch) MatchInit(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, params map[string]interface{}) (interface{}, int, string) {
	state := &LobbyMatchState{
		emptyTicks: 0,
		presences:  map[string]runtime.Presence{},
	}
	tickRate := 1 // 1 tick per second = 1 MatchLoop func invocations per second
	label := ""
	return state, tickRate, label
}

func (m *LobbyMatch) MatchJoin(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, dispatcher runtime.MatchDispatcher, tick int64, state interface{}, presences []runtime.Presence) interface{} {
	lobbyState, ok := state.(*LobbyMatchState)
	if !ok {
		logger.Error("state not a valid lobby state object")
		return nil
	}

	for i := 0; i < len(presences); i++ {
		lobbyState.presences[presences[i].GetSessionId()] = presences[i]
	}

	return lobbyState
}

func (m *LobbyMatch) MatchLeave(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, dispatcher runtime.MatchDispatcher, tick int64, state interface{}, presences []runtime.Presence) interface{} {
	lobbyState, ok := state.(*LobbyMatchState)
	if !ok {
		logger.Error("state not a valid lobby state object")
		return nil
	}

	for i := 0; i < len(presences); i++ {
		delete(lobbyState.presences, presences[i].GetSessionId())
	}

	return lobbyState
}

func (m *LobbyMatch) MatchLoop(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, dispatcher runtime.MatchDispatcher, tick int64, state interface{}, messages []runtime.MatchData) interface{} {
	lobbyState, ok := state.(*LobbyMatchState)
	if !ok {
		logger.Error("state not a valid lobby state object")
		return nil
	}

	// If we have no presences in the match according to the match state, increment the empty ticks count
	if len(lobbyState.presences) == 0 {
		lobbyState.emptyTicks++
	}

	// If the match has been empty for more than 100 ticks, end the match by returning nil
	if lobbyState.emptyTicks > 100 {
		return nil
	}

	return lobbyState
}
```
{{< / code >}}

{{< code type="server" >}}
```typescript
const matchInit = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, params: {[key: string]: string}): {state: nkruntime.MatchState, tickRate: number, label: string} {
  return {
    state: { presences: {}, emptyTicks: 0 },
    tickRate: 1, // 1 tick per second = 1 MatchLoop func invocations per second
    label: ''
  };
};

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 (p) { 
    state.presences[p.sessionId] = p;
  });

  return {
    state
  };
}

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 (p) {
    delete(state.presences[p.sessionId]);
  });

  return {
    state
  };
}

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 {
  // If we have no presences in the match according to the match state, increment the empty ticks count
  if (state.presences.length === 0) {
    state.emptyTicks++;
  }

  // If the match has been empty for more than 100 ticks, end the match by returning null
  if (state.emptyTicks > 100) {
    return null;
  }

  return {
    state
  };
}
```
{{< / code >}}

{{< code type="server" >}}
```lua
local M = {}

function M.match_init(context, initial_state)
	local state = {
		presences = {},
		empty_ticks = 0
	}
	local tick_rate = 1 -- 1 tick per second = 1 MatchLoop func invocations per second
	local label = ""

	return state, tick_rate, label
end

function M.match_join(context, dispatcher, tick, state, presences)
	for _, presence in ipairs(presences) do
		state.presences[presence.session_id] = presence
	end

	return state
end

function M.match_leave(context, dispatcher, tick, state, presences)
	for _, presence in ipairs(presences) do
		state.presences[presence.session_id] = nil
	end

	return state
end

function M.match_loop(context, dispatcher, tick, state, messages)
  -- Get the count of presences in the match
  local totalPresences = 0
  for k, v in pairs(state.presences) do
    totalPresences = totalPresences + 1
  end

	-- If we have no presences in the match according to the match state, increment the empty ticks count
	if totalPresences == 0 then
		state.empty_ticks = state.empty_ticks + 1
	end

	-- If the match has been empty for more than 100 ticks, end the match by returning nil
	if state.empty_ticks > 100 then
		return nil
	end

	return state
end
```
{{< / code >}}

比赛无法从外部停止，只有在生命周期函数之一返回`nil`状态时才会结束。

必须注册比赛处理程序才能使用它。

{{< code type="server">}}
```go
func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
	if err := initializer.RegisterMatch("lobby", func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule) (runtime.Match, error) {
		return &LobbyMatch{}, nil
	}); err != nil {
		logger.Error("unable to register: %v", err)
		return err
	}
}
```
{{< / code >}}

{{< code type="server">}}
```typescript
let InitModule: nkruntime.InitModule = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, initializer: nkruntime.Initializer) {
  initializer.registerMatch('lobby', {
    matchInit,
    matchJoinAttempt,
    matchJoin,
    matchLeave,
    matchLoop,
    matchSignal,
    matchTerminate
  });
}
```
{{< / code >}}

{{< code type="server">}}
```lua
-- the name must be the same as the match handler file (e.g. lobby.lua)
nk.register_matchmaker_matched(function(context, matched_users)
    local match_id, err = nk.match_create("lobby", { invited = matched_users })
    return match_id
end)
```
{{< / code >}}

## 节拍率

虽然大多数比赛处理程序函数是由于用户行为或内部服务器进程而调用的，但即使没有等待处理的输入，服务器也会**定期调用比赛循环函数**。该逻辑能够根据需要推进游戏状态，还可以验证输入并踢出非活动玩家。

您的节拍率表示服务器调用比赛循环函数的期望频率（每秒），即比赛更新的频率。例如`10`的节拍率表示每秒10次表示循环。

服务器总是试图保持均匀的_起点_间距。使用`10`的节拍率例子，每个循环将在最后一个_启动_后启动`100ms`。最佳实践是在循环之间留出尽可能多的时间，允许不规则调用的非循环函数在循环之间的间隙中执行。

注意，您的游戏循环逻辑和配置的节拍率不会导致服务器落后，即每个循环必须能够在下一个循环计划之前完成（在本示例中少于`100ms`）。如果比赛循环确实落后，服务器将首先尝试尽快启动下一个循环来“赶上”。如果太多的循环落后（通常是循环逻辑设计不佳的结果），服务器将结束比赛。

可以对节拍率进行配置，常见的频率范围从回合制游戏的每秒一次到快节奏游戏的每秒几十次。选择节拍率时的一些注意事项：

* 应选择提供可接受的玩家体验（无延迟等）的最低可能节拍率。
* 更高的节拍率意味着比赛循环之间的差距更小，玩家“感觉”到反应更灵敏
* 应始终以低速率开始，并以小增量（1-2）增加，直到获得所需的体验
* 节拍率越低，每个CPU核可以并发运行的比赛数越多
* 每个比赛处理程序可以有不同的节拍率，例如对于不同的游戏模式

## 比赛状态

Nakama公开了一个内存区域，供权威比赛在比赛期间使用，以存储其状态。这可以包括在比赛过程中跟踪比赛数据和客户行为所需的任何信息。

每场比赛维护自己单独的隔离状态。这种状态是基于验证后的用户输入循环应用于初始状态的连续转换的结果。请注意，这些状态**不会**被自动发送到客户端。您必须[广播](#broadcast-message)合适的操作代码和数据，在自己的比赛处理程序逻辑内手动完成此任务。

### 发送数据消息

与[在中继多人游戏中发送消息](../relayed/#send-data-messages)不同，在权威比赛中，接收到的消息不会被自动重播到所有其他连接的客户端。比赛逻辑必须显式调用[`broadcast`函数](../../../server-framework/typescript-runtime/function-reference/match-runtime/#BroadcastMessage)来发送消息。

每条消息包含[操作码](#op-codes)以及有效负载。 

{{< code type="server">}}
```go
const MATCH_START_OPCODE = 7

matchStartData := &map[string]interface{} {
  "started": true,
  "roundTimer": 100,
}

data, err := json.Marshal(matchStartData)
if err != nil {
  logger.Error("error marshaling match start data", err)
  return nil
}

reliable := true
dispatcher.BroadcastMessage(MATCH_START_OPCODE, data, nil, nil, reliable)
```
{{< / code >}}

{{< code type="server">}}
```typescript
const matchStartOpcode = 7

const matchStartData = {
  started: true,
  roundTimer: 100
};

dispatcher.broadcastMessage(matchStartOpcode, json.stringify(matchStartData), null, null, true);
```
{{< / code >}}

{{< code type="server">}}
```lua
local match_start_opcode = 7

match_start_data = {
    started = true,
    round_timer = 100
}

dispatcher.broadcast_message(match_start_opcode, nk.json_encode(match_start_data), nil, nil)
```
{{< / code >}}


每条数据消息的二进制内容（有效负载）应当**尽可能地小**，不超过`1500`字节的最大传输单位 (MTU)。通常使用的是 JSON，最好使用 [Protocol Buffers](https://developers.google.com/protocol-buffers/) 或 [FlatBuffers](https://google.github.io/flatbuffers/) 等紧凑二进制格式。 

在无法进一步减少消息大小和/或频率的情况下，最好优先发送**更少的消息**。例如，1 条每秒 `1000` 字节的消息优于 5 条每秒 `200` 字节消息。

客户端消息由服务器按照接收的顺序进行缓冲，当下一个比赛循环运行时，将作为一批发出。最佳做法是尝试对服务器维护不超过每次 1 条消息、每个状态，并且从服务器到每个状态都相同。

如果您配置的节拍率的消息太多，服务器可能会丢弃一些消息，并记录一个错误。为避免连续丢弃消息，请尝试：

* 降低从客户端到服务器的消息发送速率
* 增加节拍率，更频繁地消耗消息
* 增加[缓冲大小](../../../getting-started/configuration/#match.input_queue_size)

#### 操作码

操作码是发送的消息类型的数值标识符。操作码可以让用户在对消息解码之前了解消息的目的和内容。 

可以将其用于定义游戏中属于某些用户操作的命令，例如：

* 初始状态同步
* 就绪状态
* Ping / Pong
* 游戏状态更新
* 表情

使用按位操作对数据进行编码，还可以在操作码字段中包含其他信息。

有关示例实现，请参阅 [Fish Game 教程](../../../tutorials/unity/fishgame/#operation-codes)。

#### Broadcast与BroadcastDeferred

借助传入[比赛处理程序函数](../../../server-framework/typescript-runtime/function-reference/match-handler/)的`dispatcher`类型，可将来自比赛的数据发送到_此比赛_中的一个或多个状态。

可通过两种方法发送数据：`Broadcast`和`BroadcastDeferred`。

`Broadcast` 对于每个函数可以调用多次，但最佳做法是将传出数据限制为每个循环中每个状态一条消息。仅当您需要向每个状态发送不同的消息时，才建议在每个循环中使用多个调用。

使用`Broadcast`与`BroadcastDeferred`只有一个区别 — 前者在被调用时将数据立即发送出去，后者在循环结束前不发送数据。

请注意，如果发送/广播的数据太多，并且连接到客户端的下行速率低于比赛的数据发送速率，将会填满客户端连接的发送缓冲区队列，并迫使服务器断开连接以防止内存溢出。

### 接收数据消息

服务器按照处理来自客户端的数据消息的顺序交付数据。客户端可以为传入的比赛数据消息添加回调。应当在他们[加入](#join-a-match)和[退出](#leave-a-match)比赛前完成此任务。

{{< code type="client" >}}
```javascript
socket.onmatchdata = (result) => {
  var content = result.data;

  switch (result.op_code) {
    case 101:
      console.log("A custom opcode.");
      break;
    default:
      console.log("User %o sent %o", result.presence.user_id, content);
  }
};
```
{{< / code >}}

{{< code type="client" >}}
```csharp
// Use whatever decoder for your message contents.
var enc = System.Text.Encoding.UTF8;
socket.ReceivedMatchState += newState =>
{
    var content = enc.GetString(newState.State);

    switch (newState.OpCode)
    {
        case 101:
            Console.WriteLine("A custom opcode.");
            break;
        default:
            Console.WriteLine("User '{0}'' sent '{1}'", newState.UserPresence.Username, content);
    }
};
```
{{< / code >}}

{{< code type="client" >}}
```cpp
rtListener->setMatchDataCallback([](const NMatchData& data)
{
    switch (data.opCode)
    {
        case 101:
            std::cout << "A custom opcode." << std::endl;
            break;
        default:
            std::cout << "User " << data.presence.userId << " sent " << data.data << std::endl;
            break;
    }
});
```
{{< / code >}}

{{< code type="client" >}}
```java
SocketListener listener = new AbstractSocketListener() {
    @Override
    public void onMatchData(final MatchData matchData) {
        System.out.format("Received match data %s with opcode %d", matchData.getData(), matchData.getOpCode());
    }
};
```
{{< / code >}}

{{< code type="client" framework="godot3" >}}
```gdscript
func _ready():
    # First, setup the socket as explained in the authentication section.
    socket.connect("received_match_state", self, "_on_match_state")

func _on_match_state(p_state : NakamaRTAPI.MatchData):
    print("Received match state with opcode %s, data %s" % [p_state.op_code, parse_json(p_state.data)])
```
{{< / code >}}

{{< code type="client" framework="defold" >}}
```lua
socket.on_matchdata(function(message)
  local data = json.decode(message.match_data.data)
  local op_code = tonumber(message.match_data.op_code)
end)
```
{{< / code >}}

{{< missing type="client" lang="bash" />}}
{{< missing type="client" lang="shell" />}}

## 比赛标签

使用比赛标签突出显示比赛想要向Nakama和玩家群宣传的内容。这可以包括游戏模式、游戏是开放还是关闭的、玩家人数、比赛状态等细节。  

比赛标签可以是**简单字符串**或**JSON**值。可通过[Match Listing API](../match-listing/)将其用于筛选比赛。  

记住，对于带有**JSON值**的比赛标签，只能使用**[搜索查询](../query-syntax/)**。对于带有**简单字符串值**（例如`"team-deathmatch"`）的比赛标签，只能使用`label`参数，执行**精确匹配**。 

索引查询对于列出比赛中更有效、更实用，因此，建议使用JSON比赛标签。需要注意的其他最佳做法：

* 比赛标签的大小应限制为2kb
* 尽量避免频繁地更新标签（即每节拍不超过一次）
* 标签的更新成批进行，产生时间点视图

## 管理比赛

### 创建比赛

[手动](#manually)或通过[匹配程序](#matchmaker)均可在服务器上创建权威比赛。

#### 手动

您可以使用一个RPC函数，此函数将一些用户ID提交给服务器并创建比赛。

将创建一个比赛ID，该ID可以通过应用内通知或推送消息（或两者）发送给玩家。当您想要手动创建比赛并与特定用户竞争时，这种方法非常实用。

{{< code type="server" >}}
```lua
local nk = require("nakama")

local function create_match(context, payload)
  local modulename = "pingpong"
  local setupstate = { initialstate = payload }
  local matchid = nk.match_create(modulename, setupstate)

  return nk.json_encode({ matchid = matchid })
end

nk.register_rpc(create_match, "create_match_rpc")
```
{{< / code >}}

{{< code type="server" >}}
```go
func CreateMatchRPC(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, payload string) (string, error) {
    params := make(map[string]interface{})

    if err := json.Unmarshal([]byte(payload), &params); err != nil {
        return "", err
    }

    modulename := "pingpong" // Name with which match handler was registered in InitModule, see example above.

    if matchId, err := nk.MatchCreate(ctx, modulename, params); err != nil {
        return "", err
    } else {
        return matchId, nil
    }
}

// Register as RPC function, this call should be in InitModule.
if err := initializer.RegisterRpc("create_match_rpc", CreateMatchRPC); err != nil {
    logger.Error("Unable to register: %v", err)
    return err
}
```
{{< / code >}}

{{< code type="server" >}}
```typescript
function rpcCreateMatch(context: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, payload: string): string {
  var matchId = nk.matchCreate('pingpong', payload);
  return JSON.stringify({ matchId });
}
```
{{< / code >}}

#### 匹配程序

使用[匹配程序](../matchmaker/)查找对手，并使用服务器上匹配程序匹配的回调创建权威比赛，并返回比赛ID。这使用客户端上的帮助匹配程序API。

客户端将正常接收带有比赛ID的匹配程序回调。

{{< code type="server" >}}
```lua
local nk = require("nakama")

local function makematch(context, matched_users)
  -- print matched users
  for _, user in ipairs(matched_users) do
    local presence = user.presence
    nk.logger_info(("Matched user '%s' named '%s'"):format(presence.user_id, presence.username))
    for k, v in pairs(user.properties) do
      nk.logger_info(("Matched on '%s' value '%s'"):format(k, v))
    end
  end

  local modulename = "pingpong"
  local setupstate = { invited = matched_users }
  local matchid = nk.match_create(modulename, setupstate)
  return matchid
end

nk.register_matchmaker_matched(makematch)
```
{{< / code >}}

{{< code type="server" >}}
```go
func MakeMatch(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, entries []runtime.MatchmakerEntry) (string, error) {
    for _, e := range entries {
        logger.Info("Matched user '%s' named '%s'", e.GetPresence().GetUserId(), e.GetPresence().GetUsername())

        for k, v := range e.GetProperties() {
            logger.Info("Matched on '%s' value '%v'", k, v)
        }
    }

    matchId, err := nk.MatchCreate(ctx, "pingpong", map[string]interface{}{"invited": entries})

    if err != nil {
        return "", err
    }

    return matchId, nil
}

// Register as matchmaker matched hook, this call should be in InitModule.
if err := initializer.RegisterMatchmakerMatched(MakeMatch); err != nil {
    logger.Error("Unable to register: %v", err)
    return err
}
```
{{< / code >}}

{{< code type="server" >}}
```typescript
function matchmakerMatched(context: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, matches: nkruntime.MatchmakerResult[]): string {
  matches.forEach(function (match) {
    logger.info("Matched user '%s' named '%s'", match.presence.userId, match.presence.username);

    Object.keys(match.properties).forEach(function (key) {
      logger.info("Matched on '%s' value '%v'", key, match.properties[key])
    });
  });

  try {
    const matchId = nk.matchCreate("pingpong", { invited: matches });
    return matchId;
  } catch (err) {
    logger.error(err);
    throw (err);
  }
}

// ...

initializer.registerMatchmakerMatched(matchmakerMatched);
```
{{< / code >}}

如果比赛应按中继多人游戏继续，匹配程序匹配的挂钩必须返回比赛ID或`nil`。

传递到比赛创建函数的字符串取决于使用的服务器运行时语言：

- 对于_Lua_，这应当是模块名称。在本例中，这是名称为`pingpong.lua`的文件，因此比赛模块是`pingpong`。
- 对于_Go_和_TypeScript_，这必须是比赛处理程序函数的注册名称。在上例中，在`InitModule`函数中的调用`initializer.RegisterMatch`时，我们将其注册为`pingpong`。 

### 加入比赛

即使经过匹配程序的匹配，玩家也不在比赛中，直到他们加入为止。这使得球员可以选择退出他们决定不参加的比赛。

这可以由客户端以与中继多人游戏相同的方式完成。[此处](../relayed/#join-a-match)是一个如何完成此任务的完整示例。

### 退出比赛

用户可随时退出比赛。这可以由客户端以与中继多人游戏相同的方式完成。[此处](../relayed/#leave-a-match)是一个如何完成此任务的完整示例。

在退出比赛时，将调用`LeaveMatch`生命周期比赛处理程序函数，并添加退出的原因：玩家是离开比赛还是断开连接。在断开连接的情况下，您可以决定暂时保留他们的席位。

记住，与中继比赛不同的是，即使所有玩家都退出了，权威比赛**也不**结束。这是正常的，旨在允许您支持这样的用例：允许玩家在游戏世界继续前进时暂时断开连接。

权威比赛处理程序仅在任何回调返回`nil`状态时才停止。你可以选择在比赛期间的任何时间点这样做，无论是否还有玩家连接到比赛。

### 比赛迁移

{{< note "important" "Nakama Enterprise Only" >}}
{{< / note >}}

当比赛因Nakama实例的[正常关闭](../../../getting-started/configuration/#shutdown_grace_sec)而终止时，可用此宽限期将玩家迁移到新的比赛。

首先您需要为他们创建新的比赛，或找到他们可以通过[比赛列表](../match-listing/)加入的现有比赛。然后向受影响的客户端发送带有此新比赛信息的[调度程序广播](#send-data-messages)。最后，您可以等待他们退出目前的比赛，必要时，可以强行将其踢出比赛：

{{< code type="server" >}}
```go
// Define an op code for sending a new match id to remaining presences
const newMatchOpCode = 999

func (m *LobbyMatch) MatchTerminate(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, dispatcher runtime.MatchDispatcher, tick int64, state interface{}, graceSeconds int) interface{} {
	logger.Debug("match will terminate in %d seconds", graceSeconds)

	var matchId string

	// Find an existing match for the remaining connected presences to join
	limit := 1
	authoritative := true
	label := ""
	minSize := 2
	maxSize := 4
	query := "*"
	availableMatches, err := nk.MatchList(ctx, limit, authoritative, label, minSize, maxSize, query)
	if err != nil {
		logger.Error("error listing matches", err)
		return nil
	}

	if len(availableMatches) > 0 {
		matchId = availableMatches[0].MatchId
	} else {
		// No available matches, create a new match instead
		matchId, err = nk.MatchCreate(ctx, "match", nil)
		if err != nil {
			logger.Error("error creating match", err)
			return nil
		}
	}

	// Broadcast the new match id to all remaining connected presences
	data := map[string]string{
		matchId: matchId,
	}

	dataJson, err := json.Marshal(data)
	if err != nil {
		logger.Error("error marshaling new match message")
		return nil
	}
	
	dispatcher.BroadcastMessage(newMatchOpCode, dataJson, nil, nil, true)

	return state
}
```
{{< / code >}}

{{< code type="server" >}}
```typescript
// Define an op code for sending a new match id to remaining presences
const newMatchOpCode = 999;

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(`Match will terminate in ${graceSeconds} seconds.`);

  let matchId = null;
  
  // Find an existing match for the remaining connected presences to join
  const limit = 1;
  const authoritative = true;
  const label = "";
  const minSize = 2;
  const maxSize = 4;
  const query = "*";
  const availableMatches = nk.matchList(limit, authoritative, label, minSize, maxSize, query);
  
  if (availableMatches.length > 0) {
    matchId = availableMatches[0].matchId;
  } else {
    // No available matches, create a new match instead
    matchId = nk.matchCreate("match", { invited: state.presences });
  }

  // Broadcast the new match id to all remaining connected presences
  dispatcher.broadcastMessage(newMatchOpCode, JSON.stringify({ matchId }), null, null, true);

  return {
    state
  };
}
```
{{< / code >}}

{{< code type="server" >}}
```lua
-- Define an op code for sending a new match id to remaining presences
local new_match_op_code = 999

function M.match_terminate(context, dispatcher, tick, state, grace_seconds)
	local message = "Server shutting down in " .. grace_seconds .. " seconds"

	local match_id

	-- Find an existing match for the remaining connected presences to join
	local limit = 1;
	local authoritative = true;
	local label = "";
	local min_size = 2;
	local max_size = 4;
	local query = "*";
	local available_matches = nk.match_list(limit, authoritative, label, min_size, max_size, query);

	if #available_matches > 0 then
		match_id = available_matches[0].match_id;
	else
		-- No available matches, create a new match instead
		match_id = nk.match_create("match", { invited = state.presences });
	end

	-- Broadcast the new match id to all remaining connected presences
	dispatcher.broadcast_message(new_match_op_code, nk.json_encode({ ["matchId"] = match_id }))

	return state
end
```
{{< / code >}}

## 最佳做法

### 存储比赛状态数据

{{< code type="server" >}}
```go
type LobbyMatchState struct {
	presences  map[string]runtime.Presence
	started bool
}

func (m *LobbyMatch) MatchInit(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, params map[string]interface{}) (interface{}, int, string) {
	state := &LobbyMatchState{
		presences:  map[string]runtime.Presence{},
		started: false,
	}
	tickRate := 1
	label := ""
	return state, tickRate, label
}

func (m *LobbyMatch) MatchLoop(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, dispatcher runtime.MatchDispatcher, tick int64, state interface{}, messages []runtime.MatchData) interface{} {
	lobbyState, ok := state.(*LobbyMatchState)
	if !ok {
		logger.Error("state not a valid lobby state object")
	}
	
  if (len(lobbyState.presences) > 2) {
		lobbyState.started = true;
	}

	return lobbyState
}
```
{{< / code >}}

{{< code type="server" >}}
```typescript
const matchInit = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, params: {[key: string]: string}): {state: nkruntime.MatchState, tickRate: number, label: string} {
  return {
    state: { presences: {}, started: false },
    tickRate,
    label: ''
  };
};

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 {
   if (state.presences.length > 2) {
    state.started = true;
  }

  return {
    state
  };
}

```
{{< / code >}}

{{< code type="server" >}}
```lua
local M = {}

function M.match_init(context, initial_state)
	local state = {
		presences = {},
		started = false
	}
	local tick_rate = 1
	local label = ""

	return state, tick_rate, label
end

function M.match_loop(context, dispatcher, tick, state, messages)
  -- Get the count of presences in the match
  local totalPresences = 0
  for k, v in pairs(state.presences) do
    totalPresences = totalPresences + 1
  end

	if totalPresences > 2 then
		state.started = true
	end

	return state
end
```
{{< / code >}}