> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/zh/docs/sample-projects/wang-ye-you-xi/threejs-minigames.md).

# Three.js 小游戏

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

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

![使用匹配器的 Three.js 多人游戏](https://raw.githubusercontent.com/edgegap/netcode-sample-threejs-minigames/main/docs/images/banner.jpg)

此示例包含五个小型浏览器游戏，每个类型一个，使用 [three.js](https://threejs.org/) 以及纯 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](https://www.npmjs.com/package/@edgegap/sdk) (`@edgegap/sdk`：查找匹配、取消，以及在速率限制下重试；为每个游戏配置一个匹配器和一个配置文件，其中包括一个双队伍配置。
* **权威服务器**：页面只发送输入并渲染接收到的状态，因此玩家无法在浏览器中更改规则。
* **每场比赛一个服务器**，借助 TLS 升级，已超过 `wss://` 。它会使用 SDK 读取自己的比赛详情，并在比赛结束、所有人离开或无人加入时停止自己的部署。
* **一个镜像支持五个游戏**：每个游戏一个应用版本，使用一个 `GAME` 环境变量来选择服务器。
* **无需构建步骤**：Three.js 和 SDK 的浏览器构建通过导入映射从 CDN 加载，因此这些页面是可以托管在任何地方的静态文件。

{% hint style="info" %}
查看 [示例仓库](https://github.com/edgegap/netcode-sample-threejs-minigames) 了解每个游戏的规则和服务器设计， [架构说明](https://github.com/edgegap/netcode-sample-threejs-minigames/blob/main/docs/architecture.md) 以及一个关于 [添加你自己的游戏](https://github.com/edgegap/netcode-sample-threejs-minigames/blob/main/docs/adding-a-game.md).
{% endhint %}

## ✔️ 准备工作

开始之前，你需要：

* [Three.js 小游戏示例](https://github.com/edgegap/netcode-sample-threejs-minigames).
* [Node.js](https://nodejs.org/) 22 或更高版本，用于在本地运行服务器和页面。
* [Docker](https://docs.docker.com/get-started/get-docker/)，用于构建服务器镜像。

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

{% code collapsedlinecount="10" %}

```bash
npm install
npm run dev:all
```

{% endcode %}

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

## ⚡ 部署并连接

### 1. 构建服务器镜像

☑️ 开始前，你需要 [在 Edgegap 创建一个免费账户](https://app.edgegap.com/auth/register)。无需信用卡。

☑️ 找到你的 [容器仓库](https://docs.edgegap.com/zh/learn/advanced-features/edgegap-container-registry.md) 项目名称和凭据。

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

{% tabs %}
{% tab title="Bash（Linux）" %}

```bash
project='<REGISTRY_PROJECT>';
username='robot$<REGISTRY_ORGANIZATION_ID>+client-push';
token='<REGISTRY_TOKEN>';

echo "$token" | docker login registry.edgegap.com -u "$username" --password-stdin 2>&1
```

{% endtab %}

{% tab title="PowerShell（Windows）" %}

```powershell
$project = '<REGISTRY_PROJECT>'
$username = 'robot$<REGISTRY_ORGANIZATION_ID>+client-push'
$token = '<REGISTRY_TOKEN>'

echo "$token" | docker login registry.edgegap.com -u "$username" --password-stdin 2>&1
```

{% endtab %}
{% endtabs %}

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

{% code collapsedlinecount="10" %}

```bash
docker build --platform linux/amd64 -t registry.edgegap.com/<project>/threejs-minigames:<tag> .
docker push registry.edgegap.com/<project>/threejs-minigames:<tag>
```

{% endcode %}

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

### 2. 创建应用版本

☑️ [创建一个应用](https://app.edgegap.com/application-management/applications/list) 名称为 `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 分钟，作为安全措施：服务器会自行停止。

{% hint style="warning" %}
**TLS 升级** 允许位于 `https` 的页面连接到 `wss://<id>.pr.edgegap.net:<port>`。Edgegap 终止 TLS，并将普通 WebSocket 流量转发到端口 `7777`。请使用 FQDN 连接，而不是 IP，这样证书才会匹配。
{% endhint %}

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

* `WAIT_SECONDS`  - 在第一位玩家加入后这么久再启动，即使匹配到的玩家还未到齐（默认 `15`),
* `MATCH_SECONDS`  - 比赛时限（各游戏默认值），
* `FIRST_JOIN_TIMEOUT_S`  - 在没人加入时，服务器停止自身前的秒数（默认 `120`),
* `EMPTY_TIMEOUT_S`  - 在所有人离开后，服务器自行停止前等待的秒数（默认 `30`),
* `REQUIRE_TICKET` - `1` 会拒绝其匹配器票据不属于本场比赛的玩家。

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

### 3. 直接测试一台服务器

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

{% code collapsedlinecount="10" %}

```bash
EDGEGAP_API_TOKEN=<token> node edgegap/deploy.mjs threejs-minigames sumo-v1
```

{% endcode %}

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

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

{% hint style="danger" %}
**切勿将你的 Edgegap API 令牌放在网页中或服务器镜像中。** 玩家通过匹配器获取服务器，匹配器使用其自身的、对客户端安全的令牌。
{% endhint %}

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

### 4. 创建匹配器

☑️ 打开 [匹配器](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list) 仪表板中的页面，点击 **创建**，并上传 `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** 以及 **认证令牌**.

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

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

### 5. 查找匹配

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

{% hint style="success" %}
该 **匹配器认证令牌可以安全地随游戏客户端一起发布**：它只能用于查找匹配。它不是你的 Edgegap API 令牌。
{% endhint %}

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

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

1. 为该游戏的配置创建一个由一名玩家组成的匹配组，立即就绪，
2. 使用 `nextAssignment()` 等待，直到该组处于 `HOST_ASSIGNED`，其中包含服务器地址和 `gameport`,
3. 连接到 `getConnectionUrl(assignment, "gameport")`，它会返回 `wss://<fqdn>:<port>`，并发送其票据 ID，这样服务器就知道玩家属于哪个队伍。

{% code collapsedlinecount="10" %}

```javascript
import { getConnectionUrl, matchmaking } from "@edgegap/sdk";

const agent = new matchmaking.GroupAgent({ baseUrl: "<API URL>", authToken: "<Auth Token>" });
agent.initialize();

agent.createGroup({ profile: "sumo", attributes: {}, is_ready: true }, true);
const assignment = await agent.nextAssignment();
const url = getConnectionUrl(assignment, "gameport");
const ticketId = agent.group.current.ticket_id;
```

{% endcode %}

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

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

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

{% code collapsedlinecount="10" %}

```bash
MM_URL=<API URL> MM_TOKEN=<Auth Token> npm run e2e
```

{% endcode %}

## 📦 发布你的游戏

* 页面可托管在任何地方：它们是不需要构建步骤的静态文件（`index.html`, `client/`, `games/`）。将每个源添加到 `allowed_cors_origins`.
* 将 `检查` 在发布前在匹配器配置中关闭。
* 将 `REQUIRE_TICKET=1` 设置在应用版本上，以阻止匹配器未发送来的玩家。
* 要发布新的服务器构建，请推送一个新的镜像标签，并将每个应用版本指向它。新的匹配会使用它，而正在运行的匹配会继续使用旧构建。
* 要升级 SDK，请在以下位置更改其版本： `package.json` 以及每个游戏页面的导入映射中，并更新导入映射的完整性哈希值。

{% hint style="info" %}
在使用编码代理吗？ `edgegap-threejs` Edgegap 的代理技能中的 [Edgegap 的代理技能](https://github.com/edgegap/llm-agent-skills) 会将此示例的服务器和客户端作为模板提供，并引导你的代理为你自己的浏览器游戏完成相同步骤。
{% endhint %}
