如何在您的大逃杀游戏中集成匹配

-> 本文基于匹配文档。如果您遇到问题或差异，请务必参考原始指南，因为那里的内容更新更频繁。

以下示例将帮助您测试核心匹配玩家流程，即：

• 在共享托管集群上创建匹配器实例，

• 在匹配器配置中定义规则和设置，

• 最后，使用我们的 API 测试玩家流程并管理玩家票据。

将我们的匹配器实现到您的游戏只需五个步骤：

1. 第一步是创建账户并使用我们的大逃杀游戏示例。瞧，（从技术上讲）您已经完成了一半！您只需要将匹配器集成到您的游戏中（见步骤 5）。

2. 现在，您绝不应该盲目遵循在网上找到的 JSON 示例，因此强烈建议根据您的游戏调整上述规则。步骤 2（“探索配置”）是我们的“使用说明”，其中详细介绍了每项匹配规则功能（“探索配置”）。

3. 步骤 3（“查看实例详情”）涵盖您个人的具体匹配器，以确保其已部署并与您的游戏设计协同工作。

4. 步骤 4，顾名思义（“4. 测试票据 API”），主要是测试玩家的匹配请求（称为票据）是否已被匹配器接收。

5. 步骤 5（“在游戏中集成匹配”）重点介绍如何在引擎项目中集成匹配器。

如果您遇到故障排除难题，我们详尽的学习中心提供了额外的排错提示。

1. 设置免费层

注册您的免费 Edgegap 账户，然后导航至 匹配器控制面板页面。

在此处，先点击 创建匹配器，然后输入：

• 匹配器的名称——这仅供您自己参考，例如 quickstart-dev，

• 然后，为您的 BR 游戏上传以下简单示例作为 JSON 配置：

{
  "version": "1.0.0",
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "profiles": {
    "casual-example": {
      "application": {
        "name": "my-game-server=>CHANGE-THIS-NAME-HERE",
        "version": "2024.01.30-16.23.00-UTC=>CHANGE-THIS-HERE "
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 2,
              "team_size": 5
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 25,
              "max_latency": 100
            }
          },
          "league_rank": {
            "type": "number_difference",
            "attributes": {
              "max_difference": 1
            }
          },
          "selected_maps": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "selected_beacons": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "10": {
            "beacons": {
              "difference": 40,
              "max_latency": 150
            }
          },
          "30": {
            "beacons": {
              "difference": 50
            }
          },
          "60": {
            "league_rank": {
              "max_difference": 2
            }
          },
          "180": {
            "beacons": {
              "difference": 100,
              "max_latency": 500
            }
          }
        }
      }
    },
    "competitive-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 2,
              "team_size": 5
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 25,
              "max_latency": 100
            }
          },
          "league_rank": {
            "type": "number_difference",
            "attributes": {
              "max_difference": 0
            }
          },
          "selected_maps": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "selected_beacons": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "30": {
            "beacons": {
              "difference": 40,
              "max_latency": 150
            }
          },
          "60": {
            "beacons": {
              "difference": 50
            }
          },
          "180": {
            "beacons": {
              "max_latency": 250
            }
          }
        }
      }
    },
    "challenger-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 2,
              "team_size": 5
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 25,
              "max_latency": 100
            }
          },
          "league_rank": {
            "type": "number_difference",
            "attributes": {
              "max_difference": 0
            }
          },
          "selected_maps": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "selected_beacons": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "30": {
            "beacons": {
              "difference": 40,
              "max_latency": 150
            }
          },
          "180": {
            "beacons": {
              "difference": 50
            }
          },
          "240": {
            "beacons": {
              "max_latency": 250
            }
          }
        }
      }
    }
  }
}

（温馨提示：请务必修改应用程序 name 和 version 以匹配您的 应用程序和版本！）

如果没有出现验证错误，请点击 创建并启动 并等待过程完成。这将启动一个新的免费集群，并运行您的简单示例匹配器。

您现在可以继续执行下一步。

2. 探索配置​

独特的大逃杀游戏规则

针对大逃杀游戏，您可以为游戏模式特定规则和设置定义多个 匹配配置文件：

• 限制两名玩家之间的段位差距，适用于更休闲的比赛，

• 在排位赛中限制段位差距，仅允许段位相同的对手，

• 让玩家提供他们的地图偏好，并选择一张适合所有人的地图，

• 添加 中心选择 UI 以将对手限制在指定的 Ping 信标，

• 将 匹配延迟 限制在最大阈值以内，以防止匹配相距甚远的玩家，

• 将 匹配延迟 限制在最大差异以内，以最大程度地提高 Ping 的公平性，

• 当允许更多玩家时，使用不同的 应用版本 分配更多 CPU 或内存，

• 作为队伍加入 适用于预组大厅或在不超过队伍人数上限的情况下补充队员。

从理想条件开始，然后 放宽限制 以确保快速匹配：

• 随着时间的推移逐步放宽延迟限制，以找到更多玩家，

• 逐步增加允许的段位差距，以找到更多玩家，

• 对于最高段位（挑战者），由于可用玩家较少，应增加每次扩展之间的间隔时间。

为晋级赛创建具有更高段位的票据，以匹配更强劲的对手。

定义 单独的作弊者配置文件，以确保被标记的作弊者或收到大量管理举报的玩家不会对排位赛中守规矩玩家的体验产生负面影响。

语义化版本控制

每个新版本都使用 语义化版本控制 通过解释 major.minor.patch 格式来清晰传达更改的影响：

• major （主版本号）包含重大破坏性更改，需要进行集成审查，

• minor （次版本号）包含实质性的向后兼容改进，

• patch （修订版本号）包含问题修复和细微改进。

某些 部署可能会导致错误。我们尝试通过自动重试部署最多 max_deployment_retry_count 次（无需客户端确认）来解决此问题。

为确保意外的客户端崩溃或被放弃的票据不会逗留并占用您的匹配器资源，票据将在 ticket_expiration_period 后被取消，导致其状态变为 CANCELLED，然后在 ticket_removal_period 后被永久删除。

我们匹配逻辑的核心在 匹配配置文件 中配置。每个配置文件都是一个完全隔离的匹配队列，指向具有预定义所需 CPU 和内存 (RAM) 资源的 应用版本。

初始规则集中的 匹配规则 必须得到满足，玩家才能被分组在一起，每项规则由三个属性定义：

• 您选择的名称，例如 - match size，

• 规则类型，也称为运算符，例如 - player_count，

• 最后是运算符属性，例如 team_count 或 team_size。

玩家数量规则

这是一项定义需要匹配多少玩家才能启动分配的特殊规则：

• team_count 指队伍数量，1 支队伍可用于合作模式或全员混战模式，

• team_size 指 每支队伍的玩家人数。

我们的简单示例展示了一个 2 名玩家的合作游戏。

请注意，“玩家数量”规则是必需的，且在您的初始配置规则中只能定义一次。

延迟规则

使用此规则可为所有玩家提供尽可能低的 Ping 值。一旦客户端测量并提交了针对所有可用信标的往返时间 (Ping)，Gen2 将仅考虑在特定 Ping 值 difference（差值）范围内的匹配（针对 Ping 信标 测量）。这提供了一种分割玩家群的“软性”解决方案，使其能够与邻近区域进行匹配，尤其可以提高玩家较少区域的匹配速度。使用 max_latency 可防止与远距离玩家匹配。

您现在可以继续执行下一步。

上面示例中的 beacons 规则最初设置为 "difference": 50, "max_latency": 200：

• Alice 和 Bob 将会匹配成功，因为北京已被舍弃 (>200)，其余部分均在 | A-B | < 50 范围内：

  • Alice {Montreal: 12.3, Newark: 45.6, Dallas: 59.9, Beijing: 264.4}；以及

  • Bob {Montreal: 27.3, Newark: 32.4, Dallas: 23.1, Beijing: 252.2}。

• Charlie 和 Dave 将不会匹配成功，因为在达拉斯信标上 | C-D | > 50：

  • Alice {Montreal: 5.7 Newark: 44.2, Dallas: 59.5, Beijing: 263.2}；以及

  • Bob {Montreal: 57.8, Newark: 32.0, Dallas: 24.2, Beijing: 272.3}。

请注意，“延迟规则”在您的初始配置规则中只能定义一次。

3. 查看实例详情​

新匹配器初始化后，在我们的控制面板中查看其详细信息：

状态 指示服务健康状况，可能为 ONLINE（在线）、OFFLINE（离线）或 ERROR（错误）。

• 标识符 可帮助 Edgegap 工作人员在您需要故障排除协助时快速找到您的匹配器。

• 启动时间 可用于追踪最新更新时间。

• 规格 对应我们的某一 定价层。

• API URL 将供游戏客户端和游戏服务器用于与 Gen2 通信。

• Swagger URL 是我们提供的一个方便的 openAPI 规范图形用户界面，用于探索 API 架构。

• 认证令牌 是游戏客户端和游戏服务器用于身份验证的唯一秘密令牌。

要使用 API 测试您的新匹配器，您将需要 Swagger URL、API URL 和认证令牌。

您现在可以继续执行下一步。

4. 测试票据 API

首先，打开您的 Swagger URL，在 Swagger GUI 中检查您的 openAPI 架构

点击“Matchmaker”标题下方的 /...swagger.json URL 以打开原始 JSON 架构：

将此页面作为文件保存到您的驱动器中 (CTRL/CMD+S)。

打开您的 Postman 应用程序 并登录您的免费账户。

从上一步导入您的 swagger.json 文件：

• 保持选中 Postman Collection，

• 选择 View Import Settings（查看导入设置）并将设置 Parameter generation（参数生成）更改为 Example（示例）。

确认导入，这将在左侧的集合列表中显示一个名为 Matchmaker 的新集合。

查看更多操作，打开标签页 Authorization 并选择：

• Auth Type - API Key，

• Key - “Authorization”

• Value - 在此处插入您的 AuthToken 值，

• Add to - Header。

按 (CTRL/CMD+S) 或点击保存图标以保存更改。Postman 标签页中的橙色圆点应该会消失。

在您的 Matchmaker 集合中，选择 tickets 和 Create a matchmaking ticket，这将打开一个新标签页。

选择标签页 Body 以预览您的 玩家票据请求：

注意 player_ip 设置为 null——这将导致使用自动添加到您请求中的 IP 地址（其他替代方案请参见 服务器到服务器集成），

• profile 指您的 匹配配置文件，

• attributes 包含用于您的匹配器规则的值，在此例中用于 latencies 规则，

  • 规则 player_count 是唯一不需要在玩家票据中提供任何属性的规则。

注意：请务必参考示例的 Swagger 导入配置。 

点击 Send 并查看对您的玩家票据请求的响应：

• id 是您唯一的匹配票据 ID，请妥善保存以便稍后查询您的票据，

• profile 确认所选的 匹配配置文件，

• group_id 是发放给每张票据的唯一组 ID，单人玩家表示为大小为 1 的组，

  • 有关与好友或大厅一起匹配的信息，请参阅 作为队伍加入，

• player_ip 是玩家解析后的公网 IP 地址，无论使用何种识别方法，

• assignment 设置为 null 表示该票据尚未匹配或分配到服务器，

• created_at 提供有关玩家票据创建时间的信息，供游戏 UI 使用，

• status 指示票据的当前状态，所有票据均以 SEARCHING 开始（详情请参阅 匹配流程）。

再次点击 Send 创建第二张票据，以便我们的两名玩家完成匹配并启动服务器。

在您的 Matchmaker 集合中，选择 {ticketId} 和 Read a matchmaking ticket。

从上一步的响应中输入票据 ID，然后点击 Send。

查看玩家票据更新后的分配情况：

• 状态首先变为 MATCH_FOUND，同时保持 assignment 设置为 null，表示玩家已完成匹配并且正在分配服务器，

再次点击 Send 以检查您的票据，并查看玩家票据更新后的分配情况：

• 状态变为 HOST_ASSIGNED，并且 assignment 包含所分配服务器的详细信息。

 在我们的控制面板中检查您的新部署：

• 注意每个部署都标有所有票据 ID 和配置文件，以增加可追溯性。

尝试从您的游戏客户端连接到已分配的服务器。

一旦您验证能够毫无问题地连接到您的部署并完成测试后，请 停止您的部署 以释放账户中的容量供下一个构建使用。

您现在可以继续执行下一步。

5. 在您的游戏中集成匹配器​

Edgegap 的匹配集成包括：

• 与 游戏客户端 集成，以管理 玩家票据，

• 与 游戏服务器 集成，以便：

  • 处理通过其票据传递的玩家偏好，

  • 可选地支持 回填 以在启动后添加或替换玩家。

对于游戏客户端内部，我们建议在整个 匹配流程 中使用游戏内 UI 向玩家提供票据状态更新，以获得最佳玩家体验。参见：

• Edgegap - Unity Gen2 匹配 SDK，

  • 导入简单示例 并根据您的需要进行自定义，

• Betide Studio - Unreal Engine Edgegap Integration Kit，

  • 下载示例项目 并根据您的需要进行自定义。

在 游戏客户端 中，确保处理不可重试的错误：

• HTTP 404 Not Found - 票据已被删除，

• HTTP 500 Internal Server Error - 临时服务中断。

在 游戏服务器 中，处理玩家偏好和初始服务器上下文。无需 API 集成：

1. 读取 注入的环境变量 (Gen2) 以检索初始玩家的匹配数据。

2. 读取 注入的环境变量 (App Versions) 以获取特定于版本的参数、设置（玩家容量）和机密信息。

3. 读取 注入的环境变量 (Deployment) 以获取部署信息，例如 IP 地址、位置等。

玩家连接后，游戏服务器和游戏客户端将启动加载场景以执行同步步骤（例如选择和加载地图/场景/关卡）。我们建议使用功能完备的 3D 场景、类似大厅的社交 UI 或带有进度条的加载屏幕，以指示初始化正在进行。

一旦 游戏客户端 完全加载，玩家将加载/切换到主游戏场景。

可选地，游戏服务器 可以创建并管理 回填 和玩家容量（添加或替换离开的玩家）。

请确保在发生以下情况时，使用 注入的 DELETE_URL 妥善停止您的部署：

• 没有玩家加入比赛，

• 所有玩家都已离开比赛，

• 比赛正常结束。

恭喜，您已完成 Edgegap 匹配器的集成！如果您想了解更多信息，请在我们的学习中心阅读全部内容。