For the complete documentation index, see llms.txt. This page is also available as Markdown.

Three.js 小游戏

带有配对功能的 three.js 多人游戏:五个浏览器小游戏,在每场对局开始时,匹配系统会启动一个权威的 node.js 服务器。

了解如何使用匹配功能创建 three.js 多人游戏。

使用匹配器的 Three.js 多人游戏

此示例包含五个小型浏览器游戏,每个类型一个,使用 three.js 以及纯 node.js WebSocket 服务器构建。玩家点击 查找匹配 页面上的该按钮后,匹配器会将他们分组,并在离他们较近的位置启动专用服务器,以便连接并游戏。比赛结束后,服务器会自行停止。

此示例包含 5 个小游戏:

  • Blaster Arena:俯视角自由混战,先达到 10 次淘汰获胜。2-8 名玩家,机器人补足至共 3 个。

  • Kart Rally:竞速,先跑完 3 圈获胜。1-8 名玩家。

  • Rocket Soccer:体育游戏,1v1 或 2v2 队伍。共 2-4 名玩家。

  • Light Cycles:街机,最后存活者获胜。2-6 名玩家,机器人补足至共 4 个。

  • Sumo Push:派对游戏,占山为王。2-8 名玩家,机器人补足至共 4 个。

此示例展示:

  • 从浏览器进行匹配 使用 Edgegap JavaScript SDK (@edgegap/sdk:查找匹配、取消,以及在速率限制下重试;为每个游戏配置一个匹配器和一个配置文件,其中包括一个双队伍配置。

  • 权威服务器:页面只发送输入并渲染接收到的状态,因此玩家无法在浏览器中更改规则。

  • 每场比赛一个服务器,借助 TLS 升级,已超过 wss:// 。它会使用 SDK 读取自己的比赛详情,并在比赛结束、所有人离开或无人加入时停止自己的部署。

  • 一个镜像支持五个游戏:每个游戏一个应用版本,使用一个 GAME 环境变量来选择服务器。

  • 无需构建步骤:Three.js 和 SDK 的浏览器构建通过导入映射从 CDN 加载,因此这些页面是可以托管在任何地方的静态文件。

查看 示例仓库 了解每个游戏的规则和服务器设计, 架构说明 以及一个关于 添加你自己的游戏.

✔️ 准备工作

开始之前,你需要:

☑️ 先在本地试试这些游戏:

这会在端口上启动这五个游戏服务器 7771 变为 7775 并在以下地址提供页面: http://localhost:8080。选择一个游戏,点击 本地服务器,然后打开第二个标签页与自己对战。 npm test 使用两个无头玩家对每个游戏进行完整对局。

⚡ 部署并连接

1. 构建服务器镜像

☑️ 开始前,你需要 在 Edgegap 创建一个免费账户。无需信用卡。

☑️ 找到你的 容器仓库 项目名称和凭据。

☑️ 使用你的注册表项目名称、用户名和令牌,通过 Docker 登录 Edgegap 的容器注册表:

☑️ 提高你的 tag 值,构建并推送包含游戏服务器的镜像:

✅ 现在你可以继续下一步。

2. 创建应用版本

☑️ 创建一个应用 名称为 threejs-minigames,每个游戏一个版本: blaster-v1, kart-v1, soccer-v1, cycles-v1 以及 sumo-v1.

☑️ 设置每个应用版本:

  • 镜像: registry.edgegap.com/<project>/threejs-minigames,标签 <tag>,

  • 镜像仓库凭据:你的容器镜像仓库用户名和令牌,以便 Edgegap 拉取镜像,

  • 资源:0.25 vCPU 和 512 MB 内存,

  • 端口: 7777,名称 gameport,协议 WS,并启用 TLS 升级 启用,

  • 环境变量: GAME 设置为 blaster, kart, soccer, cycles 或 sumo,

  • 最大时长:30 分钟,作为安全措施:服务器会自行停止。

任何版本均可选的环境变量:

  • WAIT_SECONDS - 在第一位玩家加入后这么久再启动,即使匹配到的玩家还未到齐(默认 15),

  • MATCH_SECONDS - 比赛时限(各游戏默认值),

  • FIRST_JOIN_TIMEOUT_S - 在没人加入时,服务器停止自身前的秒数(默认 120),

  • EMPTY_TIMEOUT_S - 在所有人离开后,服务器自行停止前等待的秒数(默认 30),

  • REQUIRE_TICKET - 1 会拒绝其匹配器票据不属于本场比赛的玩家。

✅ 现在你可以继续下一步。

3. 直接测试一台服务器

☑️ 使用示例的部署脚本在离你较近的位置启动一台服务器。你的 Edgegap API 令牌仍保留在你的本机上:

脚本会输出 wss://<request_id>.pr.edgegap.net:<port>.

☑️ 打开 http://localhost:8080/games/sumo/?server=wss://... 在两个浏览器标签页中打开并游玩。比赛结束后,服务器会停止自己的部署。

🙌 祝贺你在 Edgegap 上完成首次部署!

4. 创建匹配器

☑️ 打开 匹配器 仪表板中的页面,点击 创建,并上传 edgegap/matchmaker-config.json 示例中的文件。

配置中每个游戏都有一个配置文件,每个都指向该游戏的应用版本:

  • blaster, kart 以及 sumo:2 到 8 名玩家, cycles:2 到 6。20 秒后,单独等待的玩家会获得一台服务器,机器人会填补空位。

  • soccer: team_count: 2 每队 1 或 2 名玩家,因此当有四名玩家等待时是 2v2,否则是 1v1。每张票都会获得一个 team_id,服务器会将每位玩家分配到各自的队伍。

☑️ 浏览器游戏会从页面调用匹配器,因此请将所有提供页面服务的源添加到 allowed_cors_origins。该配置允许 http://localhost:8080.

☑️ 点击 创建并启动。当匹配器显示 在线时,复制其 API URL 以及 认证令牌.

对于团队配置文件,请以 min_team_size: 1 开始,而不是依赖扩展。根据我们的测试, team_count: 2 一个带有 min_team_size: 2 以及 20 秒扩展到 1 只会在两名等待玩家的票据即将过期时才将他们匹配。

✅ 现在你可以继续下一步。

5. 查找匹配

☑️ 将匹配器的 API URL 和认证令牌放入 client/config.js (或一个被 git 忽略的 client/config.local.js),或者在页面 URL 中添加 ?mm=<API URL>&token=<Auth Token> 。

☑️ 运行 npm run web 并在两个标签页中打开同一个游戏。点击 查找匹配 ,并在 20 秒内在两个标签页中都点击。

每个标签页都使用 SDK 的 GroupAgent 来:

  1. 为该游戏的配置创建一个由一名玩家组成的匹配组,立即就绪,

  2. 使用 nextAssignment() 等待,直到该组处于 HOST_ASSIGNED,其中包含服务器地址和 gameport,

  3. 连接到 getConnectionUrl(assignment, "gameport"),它会返回 wss://<fqdn>:<port>,并发送其票据 ID,这样服务器就知道玩家属于哪个队伍。

新的部署在之后的几秒内可能会拒绝连接 HOST_ASSIGNED,因此客户端会重试。SDK 会自动重试受速率限制的(429)和失败的请求,并且 取消 会让该组处于 stopMatchmaking().

🙌 现在两名玩家已进入同一场比赛,服务器部署在离他们较近的位置。

☑️ 若要在不使用浏览器的情况下测试整个流程,请运行端到端测试。它会为每个游戏排队多个无头玩家,检查他们是否落在同一部署上并完成一整局,然后等待该部署自行停止:

📦 发布你的游戏

  • 页面可托管在任何地方:它们是不需要构建步骤的静态文件(index.html, client/, games/)。将每个源添加到 allowed_cors_origins.

  • 将 检查 在发布前在匹配器配置中关闭。

  • 将 REQUIRE_TICKET=1 设置在应用版本上,以阻止匹配器未发送来的玩家。

  • 要发布新的服务器构建,请推送一个新的镜像标签,并将每个应用版本指向它。新的匹配会使用它,而正在运行的匹配会继续使用旧构建。

  • 要升级 SDK,请在以下位置更改其版本: package.json 以及每个游戏页面的导入映射中,并更新导入映射的完整性哈希值。

在使用编码代理吗? edgegap-threejs Edgegap 的代理技能中的 Edgegap 的代理技能 会将此示例的服务器和客户端作为模板提供,并引导你的代理为你自己的浏览器游戏完成相同步骤。

最后更新于

这有帮助吗?