> 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/fal-ai-relic-rumble.md).

# fal.ai 遗迹争夺战

使用 edgegap 让 fal.ai 游戏支持多人联机：这是一款由编码代理编写的 three.js 游戏，包含由 fal 生成的 3D 角色、道具和音效，并配有匹配机制，以及每场对局一个权威 node.js 服务器。

了解如何让使用 [fal.ai](https://fal.ai/) 构建的游戏资源上线，并通过 Edgegap 实现多人联机。

![Relic Rumble：一场比赛中的四个由 fal 生成的角色](https://raw.githubusercontent.com/edgegap/netcode-sample-fal-relic-rumble/main/docs/images/gameplay.jpg)

Relic Rumble 是一款 [three.js](https://threejs.org/) 四人派对游戏：抢到遗物，把它带到你的角落，并推开任何试图做同样事情的人。代码由编程智能体编写，fal.ai 则生成了你看到和听到的一切：四个带骨骼绑定并配有行走和奔跑动画的角色、道具、地面和音效。

* **fal.ai**：在构建游戏时使用，用于生成游戏资源。
* **Edgegap**：玩家开始游戏后使用，用于匹配玩家，并为每场比赛在玩家附近启动一台专用服务器。

本示例展示了：

* **规则集中在一个文件中**: `client/rules.js` 不包含浏览器代码，因此网页会运行该文件以支持单人游戏，游戏服务器也会运行同一个文件以支持在线游戏。
* **资源保留在网页端**：服务器将角色视为圆形，将柱子视为方形。模型、纹理或音效都不会复制到服务器镜像中；添加新美术资源也无需发布服务器更新。
* **所有资源均为可选**：如果 `client/assets.js` 为空，游戏就会绘制简单图形。在生成任何资源之前，本示例就已通过这种方式构建并在线测试。
* **fal 工作流**：每个角色先生成一张概念图，再通过图像转 3D 并添加骨骼绑定。所有提示词、模型和价格都列在示例的 `PROMPTS.md`.
* **从网页查找比赛** 使用 [Edgegap JavaScript SDK](https://www.npmjs.com/package/@edgegap/sdk)：每场比赛 2 至 4 名玩家，空位由机器人补上。

{% hint style="info" %}
请参阅 [示例仓库](https://github.com/edgegap/netcode-sample-fal-relic-rumble) 了解游戏、fal 脚本和提示词、游戏服务器，以及对完整流程进行端到端测试的内容。
{% endhint %}

## ✔️ 准备工作

开始之前，你需要：

* [fal.ai Relic Rumble 示例](https://github.com/edgegap/netcode-sample-fal-relic-rumble)，并将其推送到你自己的 GitHub 仓库。
* [Node.js](https://nodejs.org/) 22 或更高版本，用于在本地运行服务器和网页。
* 若要生成自己的资源：需要一个 [fal.ai 账号](https://fal.ai/dashboard) ，并预存几美元额度；还需要 fal 的 `genmedia` CLI，或将 [fal MCP 服务器](https://fal.ai/mcp) 连接到你的编程智能体。示例已包含所需资源，因此这一步是可选的。

☑️ 先在本地试运行游戏：

{% code collapsedlinecount="10" %}

```bash
npm install
npm run test:local
npm run client
```

{% endcode %}

`npm run test:local` 会在本地服务器上用两名无头玩家进行一场完整比赛。打开 `http://localhost:8080` 并点击 **与机器人对战** 即可单人游戏。

☑️ 若要在自己的机器上在线游玩，请在另一个终端中运行 `npm run server` 然后在两个浏览器标签页中点击 **本地服务器 :7777** 。

## 🎨 使用 fal.ai 生成素材

### 1. 角色、道具和音效

☑️ 为每个角色生成一张概念图。请生成 A 字站姿的全身图，双臂远离身体，双手空着，以便自动为角色绑定骨骼：

{% code collapsedlinecount="10" %}

```bash
bash art/gen-concepts.sh
```

{% endcode %}

☑️ 将每张图片转换为绑定骨骼的 3D 模型。结果包含模型以及单独的行走和奔跑动画：

{% code collapsedlinecount="10" %}

```bash
genmedia run meshy/v7.1/image-to-3d --image_url "<concept url>" --enable_rigging true --pose_mode "a-pose" --target_polycount 12000 --async --json
genmedia status meshy/v7.1/image-to-3d <request_id> --result --json
```

{% endcode %}

☑️ 下载每个模型、缩小其纹理以适用于网页，并将其列入 `client/assets.js`:

{% code collapsedlinecount="10" %}

```bash
python art/fetch.py raider-blue
bash art/build.sh raider-blue
```

{% endcode %}

道具、地板纹理和音效也采用相同的步骤，使用 `art/gen-props.sh` 和 `art/gen-sfx.sh`.

{% hint style="success" %}
**你的素材不会传到游戏服务器。** 碰撞、攻击距离和速度都是 `client/rules.js`中的数值。渲染器会将每个模型缩放到对应的世界单位尺寸，因此你可以替换任何模型，而无需更改规则。
{% endhint %}

{% hint style="warning" %}
**绑定骨骼的模型尺寸显示不正确** 对于 three.js 默认的边界框来说，这是因为模型的骨架带有自身的缩放比例。应像 `fit()` 在 `client/render.js`中所做的那样，测量蒙皮顶点，否则角色渲染出来会小得多。
{% endhint %}

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

## ⚡ 部署并连接

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

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

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

☑️ 在 GitHub 仓库中，打开 **设置**，然后依次打开 **机密和变量**，然后依次打开 **操作**，并添加：

* 变量 `EDGEGAP_REGISTRY_PROJECT` - 您的注册表项目名称，
* 密钥 `EDGEGAP_REGISTRY_USERNAME` - 您的注册表用户名，
* 密钥 `EDGEGAP_REGISTRY_TOKEN` - 您的注册表令牌。

☑️ 运行 **服务器镜像** 工作流，入口位于 **操作** 选项卡。该工作流会运行本地对局测试，然后构建并推送 `registry.edgegap.com/<project>/relic-rumble:<tag>`，并使用构建时间作为标签。标签会显示在运行摘要中。

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

### 3. 创建应用版本

☑️ [创建一个名为](https://app.edgegap.com/application-management/applications/list) 的应用 `relic-rumble`，并创建一个以您的标签命名的版本：

* **镜像**：注册表 `registry.edgegap.com`，存储库 `<project>/relic-rumble`，标签 `<tag>`,
* **资源**：0.25 vCPU 和 512 MB 内存，
* **端口**: `7777`，名称 `gameport`，协议 **WS**，并 **启用 TLS 升级** ，
* **重启策略**：从不，
* **环境变量**:
  * `EMPTY_TIMEOUT_S` - `15`，用于停止所有玩家都已离开的服务器，
  * `FIRST_JOIN_TIMEOUT_S` - `60`，用于停止没有玩家加入的服务器，
  * `RESULTS_SECONDS` - `8`,
  * `IDLE_TIMEOUT_S` - `75`，用于移除页面已关闭的玩家，
* **最长运行时间**：30 分钟，作为安全保障：服务器会自动停止。

{% hint style="warning" %}
**TLS 升级** 让浏览器可以从 `https` 页面连接到 `wss://<id>.pr.edgegap.net:<port>`。Edgegap 负责终止 TLS，并将未加密的 WebSocket 流量转发到端口 `7777`.
{% endhint %}

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

### 4. 创建 Matchmaker

☑️ 将 `application.version` 设置为示例中的 `matchmaker/rumble.json` 对应的版本，并将页面地址添加到 `allowed_cors_origins`.

☑️ 在控制面板中打开 [Matchmaker](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list) 页面，点击 **创建**，上传配置，然后点击 **创建并启动**.

rumble `配置` 最多支持 4 名玩家参与匹配，最少 2 名。等待 20 秒后，独自等待的玩家也会获得服务器，空位则由机器人补齐。

☑️ 当匹配器显示 **在线**时，复制其 **API URL** 和 **身份验证令牌** 到 `client/config.local.js`中；该文件是 `client/config.js`.

{% hint style="success" %}
的副本。 **Matchmaker 的身份验证令牌可以安全地放在网页中**：它只能用于请求匹配。切勿将 Edgegap API 令牌放在网页或服务器镜像中。
{% endhint %}

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

### 5. 查找对局

☑️ 在两个浏览器标签页中打开页面，并在 20 秒内分别点击 **查找对局** 。

每个页面都会：

1. 加入匹配器并等待 `HOST_ASSIGNED`,
2. 连接到 `wss://<fqdn>:<port>` 并发送其票据 ID，
3. 开始游戏：发送操作输入，并使用与单人游戏相同的渲染器和资源绘制服务器返回的状态。

游戏服务器会：

1. 等待匹配到的玩家，然后用机器人填补空位，
2. 运行 `client/rules.js` 每秒 60 次，并以每秒 20 次的频率发送位置，
3. 并在结果画面显示后停止自身部署。

🙌 两名玩家现在已进入同一场对局，所在服务器也部署在他们附近。

☑️ 无需浏览器即可测试完整流程：运行端到端测试。它会将两名无头玩家加入队列、进行一场对局，并等待部署自行停止：

{% code collapsedlinecount="10" %}

```bash
MM_URL=<API URL> MM_TOKEN=<Auth Token> node tests/e2e.mjs rumble 2
```

{% endcode %}

## 📦 发布你的游戏

* 将页面托管在任意位置： `client/` 目录中的文件都是静态文件，无需构建步骤。示例中包含一个 GitHub Pages 工作流。
* 发布前请检查 `client/assets/` 的大小。示例中的四个角色、三个道具、地板和音效合计 7 MB。
* 保留你的 fal 提示词，以便日后用相同风格再生成一项素材。
* 在启动前，将匹配器配置中的 `inspect` 设为关闭。
* 要发布新规则，请推送新的镜像标签，并将应用版本指向该标签。新对局会使用新版本，正在进行的对局则继续使用旧版本。发布新素材只需重新发布页面。

{% hint style="info" %}
正在使用编码代理？ `edgegap-fal` 技能位于 [Edgegap 的代理技能](https://github.com/edgegap/llm-agent-skills) 中，其中包含游戏简介、fal 素材生成流程、服务器模板和测试，并会引导你的代理按照相同步骤为你自己的游戏完成操作。
{% endhint %}
