---
type: explanation
title: 跑你自己的游戏
summary: 自定义游戏开发是什么、交付你自己游戏的两种方式（手动槽位或自托管 iframe），以及仪表盘增加什么（模式、预设，以及那个让一个自定义游戏能设关卡的回放工件）。
---

一个自定义游戏是 **你** 构建并托管的游戏，在 Caputchin 组件里用，而不是用一个 [应用市场](/marketplace) 游戏。别人都装不了它，没有 GitHub topic、没有发布步骤，而你保留代码。这一节是那条路径的详细、自己动手的指南。（如果你想交付一个供 *任何人* 嵌入的游戏，那是 [应用市场游戏开发](/docs/marketplace-game-development/overview)，一条独立的路径。）

交付一个自定义游戏有两种方式，而且它们是带着不同局限的、确实不同的面。按你的需要来选：

```mermaid
flowchart TD
  Q{你需要什么}
  Q -->|只是组件里我自己的 DOM，<br/>无验证关卡| M[手动模式]
  Q -->|一个能给验证设关卡的真游戏，<br/>由服务器重放| S[自托管 iframe 游戏]
  M --> MX["&lt;caputchin-game trigger=manual&gt;<br/>你嵌入你自己的标记<br/>自己驱动 pass() / fail()"]
  S --> SX["一个用 @caputchin/game-sdk 的 JS 包<br/>由你托管，经 game-src 加载<br/>+ 一个上传到仪表盘的回放工件"]
```

## 手动模式：你自己的 DOM，无关卡

[手动模式](/docs/custom-game-development/manual-mode) 是那个轻量的选项。你在 `<caputchin-game>` 上设 `trigger="manual"`、把你自己的标记放进它里面，并在访客成功或失败时从你自己的代码调用这个元素的 `pass()` / `fail()` 方法。没有 iframe、没有游戏 SDK；组件只是给你它的布局外壳和环绕你标记的那套验证管道。

代价：一个手动模式的回合 **无法被服务器重放**，所以一个手动模式的游戏 **无法满足一个 [游戏关卡](/docs/site-keys/games)**。它只在一个未设关卡的密钥上跑（proof-of-work 验证，把你的交互当作 UX），或者纯游戏、完全不验证。把它用于一个带品牌的交互，而不是用于一个你需要被重放的安全关卡。

## 自托管 iframe 游戏：能设关卡

一个 [自托管游戏](/docs/custom-game-development/self-hosted-game) 是一个真正的、沙箱化的游戏：一个对着 `@caputchin/game-sdk` 包构建的 JavaScript 包，它跑在组件的 iframe 里、通过 SDK 桥和宿主对话、并报告一条服务器能重跑的 **轨迹**。你自己托管这个包，并用 `game-src` 属性把组件指向它。

因为这个回合产出一条可回放的轨迹，一个自托管游戏 **能给** 一个站点密钥 **设关卡**，但只有当你给 Caputchin 一个 [回放工件](/docs/custom-game-development/replay-and-gating) 之后：一个你游戏逻辑的小巧的 headless 构建，服务器跑它来重新推导那个裁定。在那个工件被上传并通过它的自检之前，这个自定义游戏显示 **不可回放**，且无法设关卡。

## 仪表盘增加什么

一个应用市场游戏交付一个 `caputchin.json` 清单，它声明它的自定义字段。一个自定义游戏没有清单，所以 **你在仪表盘上声明那些字段**：你用一个你选的 id [注册这个自定义游戏](/docs/game-customization/custom-games)、按维度（语言、皮肤、配置）定义它的字段 [模式](/docs/custom-game-development/dashboard-schema)、并对着它撰写预设。从那里起，它的解析和应用恰好和一个应用市场游戏一样，在同样的套餐档位上。

所以完整的自定义游戏面是：

| 部件 | 在哪里 | 为什么需要 |
|---|---|---|
| 游戏本身 | 你的代码、你的主机 | 总是 |
| 交付 | `trigger="manual"` 槽位，或 `game-src` iframe | 总是 |
| 字段模式 + 预设 | 仪表盘（你定义模式） | 自定义语言 / 皮肤 / 配置 |
| 回放工件 | 仪表盘上传 | 给验证设关卡（仅自托管） |

## 另见

- [手动模式](/docs/custom-game-development/manual-mode)：嵌入你自己的 DOM 并驱动通过/失败。
- [自托管游戏](/docs/custom-game-development/self-hosted-game)：用 SDK 构建一个可回放的 iframe 游戏。
- [回放与设关卡](/docs/custom-game-development/replay-and-gating)：上传那个让一个自定义游戏能设关卡的工件。
- [仪表盘模式参考](/docs/custom-game-development/dashboard-schema)：你为一个自定义游戏定义的那个字段模式。
- [自定义游戏](/docs/game-customization/custom-games)：从客户侧看的注册与托管。