---
type: explanation
title: Run your own game
summary: What custom game development is, the two ways to deliver your own game (manual slot or self-hosted iframe), and what the dashboard adds (schema, presets, and the replay artifact that lets a custom game gate).
---

A custom game is a game **you** build and host, used in the Caputchin widget instead of a [marketplace](/marketplace) game. Nobody else can install it, there is no GitHub topic and no publish step, and you keep the code. This section is the detailed, build-it-yourself guide to that path. (If you want to ship a game for *anyone* to embed, that is [marketplace game development](/docs/marketplace-game-development/overview), a separate path.)

There are two ways to deliver a custom game, and they are genuinely different surfaces with different limits. Pick by what you need:

```mermaid
flowchart TD
  Q{What do you need}
  Q -->|Just my own DOM in the widget,<br/>no verification gate| M[Manual mode]
  Q -->|A real game that can GATE verification<br/>server-replayed| S[Self-hosted iframe game]
  M --> MX["&lt;caputchin-game trigger=manual&gt;<br/>you slot your own markup<br/>drive pass() / fail() yourself"]
  S --> SX["a JS bundle using @caputchin/game-sdk<br/>hosted by you, loaded via game-src<br/>+ a replay artifact uploaded to the dashboard"]
```

## Manual mode: your own DOM, no gate

[Manual mode](/docs/custom-game-development/manual-mode) is the lightweight option. You set `trigger="manual"` on `<caputchin-game>`, put your own markup inside it, and call the element's `pass()` / `fail()` methods from your own code when the visitor succeeds or fails. There is no iframe and no game SDK; the widget just gives you its layout shell and the verification plumbing around your markup.

The tradeoff: a manual-mode round **cannot be server-replayed**, so a manual-mode game **cannot satisfy a [game gate](/docs/site-keys/games)**. It runs only on an ungated key (proof-of-work verification, with your interaction as UX), or game-only with no verification at all. Use it for a branded interaction, not for a security gate you need replayed.

## Self-hosted iframe game: can gate

A [self-hosted game](/docs/custom-game-development/self-hosted-game) is a real, sandboxed game: a JavaScript bundle built against the `@caputchin/game-sdk` package that runs in the widget's iframe, talks to the host over the SDK bridge, and reports a **trace** the server can re-run. You host the bundle yourself and point the widget at it with the `game-src` attribute.

Because the round produces a replayable trace, a self-hosted game **can gate** a site key, but only once you give Caputchin a [replay artifact](/docs/custom-game-development/replay-and-gating): a small headless build of your game logic that the server runs to re-derive the verdict. Until that artifact is uploaded and passes its self-check, the custom game shows **Not replayable** and cannot gate.

## What the dashboard adds

A marketplace game ships a `caputchin.json` manifest that declares its customization fields. A custom game has no manifest, so **you declare those fields on the dashboard** instead: you [register the custom game](/docs/game-customization/custom-games) by an id you choose, define its field [schema](/docs/custom-game-development/dashboard-schema) per axis (language, skin, configuration), and author presets against it. From there it resolves and applies exactly like a marketplace game, on the same plan tiers.

So the full custom-game surface is:

| Piece | Where | Needed for |
|---|---|---|
| The game itself | Your code, your host | Always |
| Delivery | `trigger="manual"` slot, or `game-src` iframe | Always |
| Field schema + presets | Dashboard (you define the schema) | Customizing language / skin / config |
| Replay artifact | Dashboard upload | Gating verification (self-hosted only) |

## See also

- [Manual mode](/docs/custom-game-development/manual-mode): slot your own DOM and drive pass/fail.
- [Self-hosted game](/docs/custom-game-development/self-hosted-game): build a replayable iframe game with the SDK.
- [Replay and gating](/docs/custom-game-development/replay-and-gating): upload the artifact that lets a custom game gate.
- [Dashboard schema reference](/docs/custom-game-development/dashboard-schema): the field schema you define for a custom game.
- [Custom games](/docs/game-customization/custom-games): registering and hosting, from the customer side.