如何在您的多人第一人称射击（FPS）游戏中集成配对系统

-> 本文基于 配对文档。如果您遇到问题或差异，请确保查阅 原始指南，因为这些指南更新的频率更高。

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

• 在共享的 主机集群上创建配对实例，

• 在您的配对 配置中定义规则和设置，

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

将我们的配对系统实现到您的游戏中有五个步骤：

1. 第一步是 创建一个账号 并使用我们的 FPS 游戏示例。完美，您（在技术上）已经完成了一半！您只需将配对系统集成到您的游戏中（见步骤 5）。

2. 现在，您永远不应该盲目地遵循互联网上找到的 JSON 示例，因此强烈建议您根据您的游戏来调整以上规则。第二步（“探索配置”）是我们的“如何阅读”，详细讲解了每个 配对规则功能（“探索配置”）。

3. 第三步（“审核实例细节”）涵盖了您的个人、特定的 配对器 ，以确保它已部署并与您游戏的设计相兼容。

4. 第四步，顾名思义（“4. 测试票证 API”），专注于测试配对请求是否来自玩家，并被配对器接收，这些请求称为票证。

5. 第五步（“在您的游戏中集成配对系统”）强调了如何在您的引擎项目中集成配对器。

如果您遇到故障排除的挑战，我们的详细 学习中心 提供额外的故障排除提示。

1. 设置免费套餐

注册您的免费 Edgegap 账户并导航到 配对仪表板页面。

从那里，首先单击 创建配对器 ，然后输入：

• 为您的配对器指定一个名称 - 仅供您自行参考，例如 quickstart-dev，

• 然后，为您的 FPS 游戏上传以下简单示例作为 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. 探索配置​

独特的 FPS 游戏规则

特别针对FPS 游戏，您可以定义多个 配对配置文件 用于游戏模式特定规则和设置：

• 在更休闲的游戏中限制两名玩家之间的排名差异，

• 在排名比赛中限制排名差异仅允许同等级对手，

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

• 添加 中心选择 UI 来限制对手在指定的 延迟信标范围内，

• 限制 配对延迟 到一个最大阈值，以防止匹配远离的玩家，

• 限制 配对延迟 到最大差异以最大化延迟公平性，

• 在允许更多玩家的情况下，分配更多 CPU 或内存使用不同的 应用版本 ，

• 组队加入 以便填补团队或填写预先制定的团队，而不超出团队大小。

从理想条件开始，并且 扩展限制 以确保快速匹配：

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

• 逐步增加允许的排名差异，以便找到更多玩家，

• 提高高排名（挑战者）之间的扩展时间，因为可用的玩家较少。

为晋级赛创建更高排名的票证，以匹配更强的对手。

定义 单独的作弊者配置文件 以确保被标记的作弊者或报告大量违规的玩家不会对合法玩家的排名比赛体验产生负面影响。

语义版本控制

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

• major 版本包括重大变更，并需要集成审查，

• minor 版本包括实质性的向后兼容性改进，

• patch 版本包括错误修复和小改进。

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

为了确保意外的客户端崩溃或被放弃的票证不会滞留并占用您的配对器资源，票证将在 ticket_expiration_period 过期后被取消，状态更改为 CANCELLED 并在 ticket_removal_period 后永久删除。

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

配对规则 在初始规则集中必须满足，以使玩家能够组合在一起，每个规则由三个属性定义：

• 您选择的名称，例如 - 匹配规模，

• 规则类型，也称为操作符，例如 - player_count，

• 最后是操作符属性，例如 team_count 或 team_size。

玩家计数规则

这是一个特殊的规则，定义需要多少玩家匹配以启动分配：

• team_count 指的是团队的数量，1个团队可用于合作或自由对战模式，

• team_size 指的是每个团队的 玩家数量。

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

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

延迟规则

使用此规则为所有玩家提供尽可能低的延迟。一旦客户端测量并提交其往返时间（延迟）与所有可用信标的比较，Gen2 将仅考虑匹配在特定 difference 内的延迟值，以 延迟信标为基准。这提供了一种“软性”解决方案以分割您的玩家基础，使其能够与邻近地区匹配，特别是改善人口较少地区的匹配速度。使用 max_latency来防止与远方玩家对战。

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

我们的示例 信标 规则中使用的 "difference": 50, "max_latency": 200 初步：

• Alice 和 Bob 将匹配，因为北京被丢弃（>200），而其余部分在 | A-B | < 50 之内：

  • Alice {蒙特利尔: 12.3, 纽瓦克: 45.6, 达拉斯: 59.9, 北京: 264.4}; 以及

  • Bob {蒙特利尔: 27.3, 纽瓦克: 32.4, 达拉斯: 23.1, 北京: 252.2}。

• Charlie 和 Dave 将不匹配，因为 | C-D | > 50 针对达拉斯信标：

  • Alice {蒙特利尔: 5.7 纽瓦克: 44.2, 达拉斯: 59.5, 北京: 263.2}; 以及

  • Bob {蒙特利尔: 57.8, 纽瓦克: 32.0, 达拉斯: 24.2, 北京: 272.3}。

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

3. 审核实例细节​

在我们的仪表板中查看您的新配对器的详细信息，一旦它被初始化：

状态 指示服务健康，可以是在线、离线或错误。

• 标识符 可以帮助 Edgegap 员工快速找到您的配对器，以便在您需要帮助进行故障排除时使用。

• 开始于 可以用于追踪最新的更新时间。

• 大小 对应于我们的 定价套餐。

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

• Swagger URL 是我们提供的便捷 openAPI 规范 GUI，用于探索 API 架构。

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

要使用 API 测试您的新配对器， 您将需要 Swagger URL、API URL 和身份验证令牌。

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

4. 测试票证 API

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

单击“配对器”标题下的/...swagger.json URL，以打开原始 JSON 架构：

将此页面保存为文件在您的驱动器上（CTRL/CMD+S）。

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

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

• 保持 Postman 集合 被选中，

• 选择 查看导入设置 并将设置 参数生成 改为 示例。

确认导入，这将使新的集合出现在左侧的集合列表中，名为配对器。

查看更多操作，打开选项卡 授权 并选择：

• 身份验证类型 - API 密钥，

• 密钥 - “授权”

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

• 添加到 - 头部。

按（CTRL/CMD+S）或保存图标以 保存更改。您在 Postman 选项卡中的橙点应消失。

在您的配对器集合中，选择 票证 并 创建一个配对票证，打开一个新选项卡。

选择选项卡 主体 以预览您的 玩家票证请求：

注意 player_ip 被设置为 null- 这将导致使用自动添加到请求中的 IP 地址（请参阅 服务器对服务器集成 以获取替代方案），

• profile 指的是您的 配对配置文件,

• attributes 包括您配对规则的值，在这种情况下是 latencies 规则，

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

注意：确保参阅示例的Swagger 的导入配置。 

点击 发送 并查看对您的玩家票证请求的响应：

• id 是您唯一的配对票证 ID，保存此 ID 以便稍后检查您的票证，

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

• group_id 是分配给每张票证的唯一组 ID，一个单独的玩家被表示为一个组，

  • 请参阅 组队加入 以便与您的朋友或大厅进行配对，

• player_ip 是玩家的解决公共 IP 地址，无论使用的识别方法如何，

• assignment 被设置为 null 以表示票证尚未匹配或分配给服务器，

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

• status 指示票证的当前状态，所有票证开始为 SEARCHING （有关详细信息，请参见 配对过程）。

通过再次点击 发送 来创建第二张票证，以便我们的两名玩家匹配并启动服务器。

在您的配对器集合中，选择 {ticketId} 并 读取配对票证。

输入上一步响应中的票证 ID，并单击 发送。

查看您玩家票证的更新分配：

• 状态变化为 MATCH_FOUND ，同时保持 assignment 设置为 null ，以表明玩家已经匹配并且服务器正在被分配，

再次单击 发送 以检查您的票证，并查看您玩家票证的更新分配：

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

 在我们的仪表板中检查您的新部署：

• 请注意，所有部署都带有所有票证 ID 和配置文件的标签，以提供更好的可追溯性。

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

一旦您确认能够无问题地连接到您的部署并完成测试，请 停止您的部署 以释放您帐户中的容量以便下一个构建。

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

5. 在您的游戏中集成配对系统​

Edgegap 的配对系统集成：

• 与 游戏客户端，管理 玩家票证，

• 与 游戏服务器，以：

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

  • 可选以支持 后填充 以添加或替换开始后的玩家。

在 游戏客户端中，我们建议通过使用游戏内 UI 向玩家提供票证状态更新，以获得最佳玩家体验，参见：

• Edgegap - Unity Gen2 配对 SDK，

  • 导入简单示例 并根据您的需求进行调整，

• Betide Studio - 虚幻引擎 Edgegap 集成工具包，

  • 下载示例项目 并根据您的需求进行调整。

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

• HTTP 404 未找到 - 票证已被删除，

• HTTP 500 内部服务器错误 - 临时服务中断。

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

1. 读取 注入的环境变量（Gen2） 以检索初始化玩家的配对数据。

2. 读取 注入的环境变量（应用版本） 以获取特定于版本的参数、设置（玩家容量）和秘密。

3. 读取 注入的环境变量（部署） 以获取部署信息，例如 IP 地址、位置或更多。

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

一旦 游戏客户端 完全加载，玩家将加载/前往主要游戏场景。

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

确保您的 部署将被正确停止 使用 注入的 DELETE_URL，如果：

• 没有玩家加入比赛，

• 所有玩家都离开比赛，

• 比赛正确结束。

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