了解Edgegap的工作原理

了解Edgegap的工作原理

如何在多人第一人称射击(FPS)游戏中添加匹配机制

已发布

已发布

已发布

关键洞察

关键洞察

关键洞察

Edgegap 的 匹配系统 是一个全面管理、无限可定制的匹配系统,可以优化全球玩家的分组——在开发您第一人称射击多人游戏时,其使用是免费的。

它也是我们所知的 唯一 具有 基于延迟的匹配规则 的匹配系统,可以为您的游戏提供理想的在线多人体验,无论引擎(Unity、Unreal 等)或游戏服务(EOS、UGS、PlayFab、Heroic Labs Nakama、Braincloud 等)。

由于我们的匹配系统基于参数,因此不需要编写代码。因此集成非常简单,如有需要,我们的 入门指南 将陪伴您每一步。

当您的游戏上线时,由于我们的匹配系统完全管理,您无需处理基础设施、错误、故障、可扩展性或数据库管理。我们为您照顾这一切。将您的 DevOps 工作量减少到几乎为零。

如何在多人第一人称射击 (FPS) 游戏中集成匹配功能

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

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

将我们的匹配器实施到您的游戏中有五个步骤:

  1. 第一步是创建账户并使用我们的 FPS 游戏示例。瞧,您(在技术上)已经完成了一半!您只需要将匹配器集成到游戏中即可(参见步骤 5)。

  2. 现在,绝不应该盲目照搬在网上找到的 JSON 示例,因此强烈建议根据您的游戏调整上述规则。步骤 2(“探索配置”)是我们的“阅读指南”,深入介绍了每项匹配规则的功能(“探索配置”)。

  3. 步骤 3(“查看实例详情”)涵盖您个人的特定匹配器,以确保其已部署并与您的游戏设计兼容。

  4. 步骤 4,顾名思义(“4. 测试票证 API”),完全是关于测试匹配器是否收到了玩家发出的匹配请求(称为票证 (tickets))。

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

如果您遇到故障排查难题,我们深入详尽的学习中心提供了额外的故障排查提示。

1. 设置免费层级

注册您的免费 Edgegap 账户,并导航至 匹配器仪表板页面。

在该页面中,先点击 Create Matchmaker(创建匹配器),然后输入:

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

  • 然后,上传以下简单的 JSON 配置示例,用于您的 FPS 游戏:

{
  "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,使其与您的 应用程序和版本保持一致!)

如果没有出现验证错误,请点击 Create and Start(创建并启动) 并等待流程完成。这将启动一个新的免费集群,其中包含您的简易示例匹配器。

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

2. 探索配置​

独特的 FPS 游戏规则

针对 FPS 游戏,您可以定义多个 匹配配置文件,以设置游戏模式特定的规则和配置:

  • 在休闲游戏中,将两名玩家之间的段位限制在一定差值范围内,

  • 在排位赛中,限制段位差以仅允许相同段位的对手匹配,

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

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

  • 将 匹配延迟 限制在最大阈值内,以防止匹配相隔太远的玩家,

  • 将 匹配延迟 限制在最大差值内,以最大限度提高 Ping 的公平性,

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

  • 作为队伍加入 以用于预组队大厅或填充队伍而不超过队伍规模限制。

从理想条件开始,并 放宽限制 以确保快速匹配:

  • 随着时间的推移慢慢放宽延迟限制,以寻找更多玩家,

  • 随着时间的推移慢慢增加允许的段位差,以寻找更多玩家,

  • 由于高段位(王者/挑战者)的玩家较少,因此可以增加各次放宽限制之间的间隔时间。

在晋级赛中创建具有更高段位的票证,以便与更强大的对手进行匹配。

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

语义化版本控制 (Semantic Versioning)

每个新版本都使用 语义化版本控制,通过解释格式 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 支队伍可用于合作模式或混战(free-for-all)模式,

  • team_size 指 每队玩家数量。

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

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

延迟规则

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

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

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

  • Alice 和 Bob 将会匹配,因为 Beijing 被舍弃 (>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 将不会匹配,因为对于 Dallas 信标,| 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. 查看实例详情​

匹配器初始化后,在我们的仪表板中查看新匹配器的详细信息:

Status(状态) 指示服务运行状况,可能为 ONLINE、OFFLINE 或 ERROR。

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

  • Started at(启动时间) 有助于追踪最新的更新时间。

  • Size(规格) 对应于我们的 定价层级之一。

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

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

  • Auth Token(身份验证令牌) 是游戏客户端和游戏服务器用于身份验证的唯一机密令牌。

要使用 API 测试新的匹配器,您将需要 Swagger URL、API URL 和 Auth Token。

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

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 的新集合。

View more actions(查看更多操作),打开选项卡 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 的匹配系统可集成:

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

  • 与 游戏服务器,以:

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

    • 可选地支持 补位 (Backfill) 以便在启动后添加或替换玩家。

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

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

  • HTTP 404 Not Found - 票证已被删除,

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

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

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

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

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

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

游戏客户端完全加载后,玩家将加载/前往主游戏场景。

可选地,游戏服务器可以创建和管理 补位 和玩家容量(添加或替换离开的玩家)。

确保在发生以下情况时,使用 注入的 DELETE_URL 正确停止您的部署:

  • 没有玩家加入比赛,

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

  • 比赛正常结束。

祝贺您,您已完成 Edgegap 匹配器集成!如果您想了解更多信息,请在我们的学习中心中阅读相关所有内容。

如何在多人第一人称射击 (FPS) 游戏中集成匹配功能

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

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

将我们的匹配器实施到您的游戏中有五个步骤:

  1. 第一步是创建账户并使用我们的 FPS 游戏示例。瞧,您(在技术上)已经完成了一半!您只需要将匹配器集成到游戏中即可(参见步骤 5)。

  2. 现在,绝不应该盲目照搬在网上找到的 JSON 示例,因此强烈建议根据您的游戏调整上述规则。步骤 2(“探索配置”)是我们的“阅读指南”,深入介绍了每项匹配规则的功能(“探索配置”)。

  3. 步骤 3(“查看实例详情”)涵盖您个人的特定匹配器,以确保其已部署并与您的游戏设计兼容。

  4. 步骤 4,顾名思义(“4. 测试票证 API”),完全是关于测试匹配器是否收到了玩家发出的匹配请求(称为票证 (tickets))。

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

如果您遇到故障排查难题,我们深入详尽的学习中心提供了额外的故障排查提示。

1. 设置免费层级

注册您的免费 Edgegap 账户,并导航至 匹配器仪表板页面。

在该页面中,先点击 Create Matchmaker(创建匹配器),然后输入:

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

  • 然后,上传以下简单的 JSON 配置示例,用于您的 FPS 游戏:

{
  "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,使其与您的 应用程序和版本保持一致!)

如果没有出现验证错误,请点击 Create and Start(创建并启动) 并等待流程完成。这将启动一个新的免费集群,其中包含您的简易示例匹配器。

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

2. 探索配置​

独特的 FPS 游戏规则

针对 FPS 游戏,您可以定义多个 匹配配置文件,以设置游戏模式特定的规则和配置:

  • 在休闲游戏中,将两名玩家之间的段位限制在一定差值范围内,

  • 在排位赛中,限制段位差以仅允许相同段位的对手匹配,

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

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

  • 将 匹配延迟 限制在最大阈值内,以防止匹配相隔太远的玩家,

  • 将 匹配延迟 限制在最大差值内,以最大限度提高 Ping 的公平性,

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

  • 作为队伍加入 以用于预组队大厅或填充队伍而不超过队伍规模限制。

从理想条件开始,并 放宽限制 以确保快速匹配:

  • 随着时间的推移慢慢放宽延迟限制,以寻找更多玩家,

  • 随着时间的推移慢慢增加允许的段位差,以寻找更多玩家,

  • 由于高段位(王者/挑战者)的玩家较少,因此可以增加各次放宽限制之间的间隔时间。

在晋级赛中创建具有更高段位的票证,以便与更强大的对手进行匹配。

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

语义化版本控制 (Semantic Versioning)

每个新版本都使用 语义化版本控制,通过解释格式 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 支队伍可用于合作模式或混战(free-for-all)模式,

  • team_size 指 每队玩家数量。

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

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

延迟规则

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

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

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

  • Alice 和 Bob 将会匹配,因为 Beijing 被舍弃 (>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 将不会匹配,因为对于 Dallas 信标,| 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. 查看实例详情​

匹配器初始化后,在我们的仪表板中查看新匹配器的详细信息:

Status(状态) 指示服务运行状况,可能为 ONLINE、OFFLINE 或 ERROR。

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

  • Started at(启动时间) 有助于追踪最新的更新时间。

  • Size(规格) 对应于我们的 定价层级之一。

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

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

  • Auth Token(身份验证令牌) 是游戏客户端和游戏服务器用于身份验证的唯一机密令牌。

要使用 API 测试新的匹配器,您将需要 Swagger URL、API URL 和 Auth Token。

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

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 的新集合。

View more actions(查看更多操作),打开选项卡 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 的匹配系统可集成:

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

  • 与 游戏服务器,以:

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

    • 可选地支持 补位 (Backfill) 以便在启动后添加或替换玩家。

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

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

  • HTTP 404 Not Found - 票证已被删除,

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

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

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

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

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

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

游戏客户端完全加载后,玩家将加载/前往主游戏场景。

可选地,游戏服务器可以创建和管理 补位 和玩家容量(添加或替换离开的玩家)。

确保在发生以下情况时,使用 注入的 DELETE_URL 正确停止您的部署:

  • 没有玩家加入比赛,

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

  • 比赛正常结束。

祝贺您,您已完成 Edgegap 匹配器集成!如果您想了解更多信息,请在我们的学习中心中阅读相关所有内容。

如何在多人第一人称射击 (FPS) 游戏中集成匹配功能

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

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

将我们的匹配器实施到您的游戏中有五个步骤:

  1. 第一步是创建账户并使用我们的 FPS 游戏示例。瞧,您(在技术上)已经完成了一半!您只需要将匹配器集成到游戏中即可(参见步骤 5)。

  2. 现在,绝不应该盲目照搬在网上找到的 JSON 示例,因此强烈建议根据您的游戏调整上述规则。步骤 2(“探索配置”)是我们的“阅读指南”,深入介绍了每项匹配规则的功能(“探索配置”)。

  3. 步骤 3(“查看实例详情”)涵盖您个人的特定匹配器,以确保其已部署并与您的游戏设计兼容。

  4. 步骤 4,顾名思义(“4. 测试票证 API”),完全是关于测试匹配器是否收到了玩家发出的匹配请求(称为票证 (tickets))。

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

如果您遇到故障排查难题,我们深入详尽的学习中心提供了额外的故障排查提示。

1. 设置免费层级

注册您的免费 Edgegap 账户,并导航至 匹配器仪表板页面。

在该页面中,先点击 Create Matchmaker(创建匹配器),然后输入:

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

  • 然后,上传以下简单的 JSON 配置示例,用于您的 FPS 游戏:

{
  "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,使其与您的 应用程序和版本保持一致!)

如果没有出现验证错误,请点击 Create and Start(创建并启动) 并等待流程完成。这将启动一个新的免费集群,其中包含您的简易示例匹配器。

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

2. 探索配置​

独特的 FPS 游戏规则

针对 FPS 游戏,您可以定义多个 匹配配置文件,以设置游戏模式特定的规则和配置:

  • 在休闲游戏中,将两名玩家之间的段位限制在一定差值范围内,

  • 在排位赛中,限制段位差以仅允许相同段位的对手匹配,

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

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

  • 将 匹配延迟 限制在最大阈值内,以防止匹配相隔太远的玩家,

  • 将 匹配延迟 限制在最大差值内,以最大限度提高 Ping 的公平性,

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

  • 作为队伍加入 以用于预组队大厅或填充队伍而不超过队伍规模限制。

从理想条件开始,并 放宽限制 以确保快速匹配:

  • 随着时间的推移慢慢放宽延迟限制,以寻找更多玩家,

  • 随着时间的推移慢慢增加允许的段位差,以寻找更多玩家,

  • 由于高段位(王者/挑战者)的玩家较少,因此可以增加各次放宽限制之间的间隔时间。

在晋级赛中创建具有更高段位的票证,以便与更强大的对手进行匹配。

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

语义化版本控制 (Semantic Versioning)

每个新版本都使用 语义化版本控制,通过解释格式 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 支队伍可用于合作模式或混战(free-for-all)模式,

  • team_size 指 每队玩家数量。

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

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

延迟规则

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

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

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

  • Alice 和 Bob 将会匹配,因为 Beijing 被舍弃 (>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 将不会匹配,因为对于 Dallas 信标,| 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. 查看实例详情​

匹配器初始化后,在我们的仪表板中查看新匹配器的详细信息:

Status(状态) 指示服务运行状况,可能为 ONLINE、OFFLINE 或 ERROR。

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

  • Started at(启动时间) 有助于追踪最新的更新时间。

  • Size(规格) 对应于我们的 定价层级之一。

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

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

  • Auth Token(身份验证令牌) 是游戏客户端和游戏服务器用于身份验证的唯一机密令牌。

要使用 API 测试新的匹配器,您将需要 Swagger URL、API URL 和 Auth Token。

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

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 的新集合。

View more actions(查看更多操作),打开选项卡 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 的匹配系统可集成:

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

  • 与 游戏服务器,以:

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

    • 可选地支持 补位 (Backfill) 以便在启动后添加或替换玩家。

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

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

  • HTTP 404 Not Found - 票证已被删除,

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

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

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

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

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

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

游戏客户端完全加载后,玩家将加载/前往主游戏场景。

可选地,游戏服务器可以创建和管理 补位 和玩家容量(添加或替换离开的玩家)。

确保在发生以下情况时,使用 注入的 DELETE_URL 正确停止您的部署:

  • 没有玩家加入比赛,

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

  • 比赛正常结束。

祝贺您,您已完成 Edgegap 匹配器集成!如果您想了解更多信息,请在我们的学习中心中阅读相关所有内容。

如何在多人第一人称射击 (FPS) 游戏中集成匹配功能

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

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

将我们的匹配器实施到您的游戏中有五个步骤:

  1. 第一步是创建账户并使用我们的 FPS 游戏示例。瞧,您(在技术上)已经完成了一半!您只需要将匹配器集成到游戏中即可(参见步骤 5)。

  2. 现在,绝不应该盲目照搬在网上找到的 JSON 示例,因此强烈建议根据您的游戏调整上述规则。步骤 2(“探索配置”)是我们的“阅读指南”,深入介绍了每项匹配规则的功能(“探索配置”)。

  3. 步骤 3(“查看实例详情”)涵盖您个人的特定匹配器,以确保其已部署并与您的游戏设计兼容。

  4. 步骤 4,顾名思义(“4. 测试票证 API”),完全是关于测试匹配器是否收到了玩家发出的匹配请求(称为票证 (tickets))。

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

如果您遇到故障排查难题,我们深入详尽的学习中心提供了额外的故障排查提示。

1. 设置免费层级

注册您的免费 Edgegap 账户,并导航至 匹配器仪表板页面。

在该页面中,先点击 Create Matchmaker(创建匹配器),然后输入:

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

  • 然后,上传以下简单的 JSON 配置示例,用于您的 FPS 游戏:

{
  "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,使其与您的 应用程序和版本保持一致!)

如果没有出现验证错误,请点击 Create and Start(创建并启动) 并等待流程完成。这将启动一个新的免费集群,其中包含您的简易示例匹配器。

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

2. 探索配置​

独特的 FPS 游戏规则

针对 FPS 游戏,您可以定义多个 匹配配置文件,以设置游戏模式特定的规则和配置:

  • 在休闲游戏中,将两名玩家之间的段位限制在一定差值范围内,

  • 在排位赛中,限制段位差以仅允许相同段位的对手匹配,

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

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

  • 将 匹配延迟 限制在最大阈值内,以防止匹配相隔太远的玩家,

  • 将 匹配延迟 限制在最大差值内,以最大限度提高 Ping 的公平性,

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

  • 作为队伍加入 以用于预组队大厅或填充队伍而不超过队伍规模限制。

从理想条件开始,并 放宽限制 以确保快速匹配:

  • 随着时间的推移慢慢放宽延迟限制,以寻找更多玩家,

  • 随着时间的推移慢慢增加允许的段位差,以寻找更多玩家,

  • 由于高段位(王者/挑战者)的玩家较少,因此可以增加各次放宽限制之间的间隔时间。

在晋级赛中创建具有更高段位的票证,以便与更强大的对手进行匹配。

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

语义化版本控制 (Semantic Versioning)

每个新版本都使用 语义化版本控制,通过解释格式 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 支队伍可用于合作模式或混战(free-for-all)模式,

  • team_size 指 每队玩家数量。

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

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

延迟规则

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

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

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

  • Alice 和 Bob 将会匹配,因为 Beijing 被舍弃 (>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 将不会匹配,因为对于 Dallas 信标,| 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. 查看实例详情​

匹配器初始化后,在我们的仪表板中查看新匹配器的详细信息:

Status(状态) 指示服务运行状况,可能为 ONLINE、OFFLINE 或 ERROR。

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

  • Started at(启动时间) 有助于追踪最新的更新时间。

  • Size(规格) 对应于我们的 定价层级之一。

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

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

  • Auth Token(身份验证令牌) 是游戏客户端和游戏服务器用于身份验证的唯一机密令牌。

要使用 API 测试新的匹配器,您将需要 Swagger URL、API URL 和 Auth Token。

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

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 的新集合。

View more actions(查看更多操作),打开选项卡 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 的匹配系统可集成:

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

  • 与 游戏服务器,以:

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

    • 可选地支持 补位 (Backfill) 以便在启动后添加或替换玩家。

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

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

  • HTTP 404 Not Found - 票证已被删除,

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

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

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

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

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

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

游戏客户端完全加载后,玩家将加载/前往主游戏场景。

可选地,游戏服务器可以创建和管理 补位 和玩家容量(添加或替换离开的玩家)。

确保在发生以下情况时,使用 注入的 DELETE_URL 正确停止您的部署:

  • 没有玩家加入比赛,

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

  • 比赛正常结束。

祝贺您,您已完成 Edgegap 匹配器集成!如果您想了解更多信息,请在我们的学习中心中阅读相关所有内容。

Get your Game Online Easily & in Minutes

立即开始集成!

轻松在线游戏
且在几分钟内