# Build a Game

This document covers everything you need to know to build and submit a game to the Ape Church platform, including what kinds of games are supported, how to use AI coding tools to build faster, and how to get your game reviewed.

#### **What You're Building**

All games on Ape Church are **Player vs. House**. The player places a bet, an on-chain random number is generated, and your game resolves that result into a payout multiplier. You build the game logic and the visual experience - we handle the blockchain, the liquidity pool, and the platform.

Think of it like this: the chain gives your game a random number, your game turns that into an outcome, and the player wins or loses based on what happens.

#### **Supported Game Types**

&#x20;<mark style="color:green;">**Single-Roll / Instant Resolution**</mark>

The player sets their parameters, one action resolves the outcome immediately.

* **Dice** - Pick an over/under threshold. Payout scales with win probability.
* **Limbo** - Pick a target multiplier. Win if the result hits it.
* **Coin Flip** - Binary. 2x or nothing.
* **Colors** - Bet on a color from a weighted set.
* **Wheel** - Weighted segments with fixed multiplier tiers.

&#x20;<mark style="color:green;">**Progressive / Cash-Out**</mark>

A value builds over time. The player decides when to exit.

* **Crash** - A multiplier climbs until a random bust point. Cash out before it crashes or lose everything.

<mark style="color:green;">**Multi-Step / Decision-Based**</mark>

Sequential decisions that affect the outcome.

* **Twenty-One** - Hit, stand, double against a dealer hand.
* **Baccarat** - Player, banker, or tie with standard rules.
* **Video Poker** - Draw and hold mechanics with paytable payouts.

<mark style="color:green;">**Grid Reveal / Mine-Style**</mark>

The player reveals tiles, accumulating risk as they go.

* **Blocks (Mines)** - Reveal tiles to find multipliers or busts. Cash out anytime.
* **Tower** - Climb rows picking safe tiles. Higher rows, higher multiplier.

<mark style="color:green;">**What We Can't Support Yet**</mark>

* **PvP games** (poker tables, head-to-head) - no peer matching infrastructure
* **Sports or event betting** -  requires external oracle feeds not yet integrated
* **Progressive jackpots** - shared pool doesn't support cross-game jackpot accrual

If you have a game idea that doesn't fit neatly into the above categories, reach out before building; we may be able to support it.

<mark style="color:green;">**Key Constraints**</mark>

Before you start, keep these in mind:

* Your game must accept a **wager amount** and return a **payout multiplier** (including 0x for a loss).
* **Randomness comes from the chain;** your game consumes it and doesn't generate it.
* All games settle against **the house pool;** maximum payout is bounded by pool liquidity.
* House edge is configurable per game but must fall within protocol-defined bounds.

#### **How to Build Your Game**

We recommend using an AI coding agent to build your game. Claude Code, Cursor (Agent mode), and OpenAI Codex all work well. You do not need to be an experienced developer,  but you do need to be hands-on with the tool and test your game as you go.

<mark style="color:green;">**Step 1.  Get the template**</mark>

Go to the game template repository and click **"Use this template"** → **"Create a new repository"**. This creates a clean copy in your own GitHub account.

**Template repo:** [ape-church-game-template](https://github.com/ape-church/ape-church-game-template)

> Do not fork the repo - use the template button. Forking creates a link back to the template that will cause issues when submitting.

<mark style="color:green;">**Step 2.  Open the project in your AI coding tool**</mark>

**Claude Code**

```
cd your-repo-name
claude
```

**Cursor** Open the folder in Cursor and switch to **Agent** mode (not Chat).

**OpenAI Codex** Open the folder in the Codex interface.

<mark style="color:green;">**Step 3.  Send your first prompt**</mark>

This is the most important step. Before asking the agent to build anything, tell it to read the instructions first. Copy and send this prompt exactly:

```
Read SKILL.md and README.md in full before doing anything.

I want to build a [game type] game for the Ape Church platform. 
Here is how it works: [describe your game in a few sentences — 
what the player does, how it resolves, what the win condition is].

Follow all rules in SKILL.md exactly. Build the game inside 
components/my-game/ and public/my-game/. Do not touch any files 
outside those folders or metadata.json.
```

Replace \[game type] and the description with your actual game. Be specific:  the more clearly you describe the game, the better the output.

**Example:**

```
Read SKILL.md and README.md in full before doing anything.

I want to build a Crash game for the Ape Church platform. 
A multiplier starts at 1x and climbs continuously. At a random 
point it crashes. The player must click "Cash Out" before the 
crash to lock in their multiplier. If they don't cash out in 
time, they lose their bet.

Follow all rules in SKILL.md exactly. Build the game inside 
components/my-game/ and public/my-game/. Do not touch any files 
outside those folders or metadata.json.
```

<mark style="color:green;">**Step 4. Test as you go**</mark>

Run the game locally while you build:

```bash
npm install
npm run dev
```

Open <http://localhost:3000> in your browser. You should see the game running. Test it continuously as the agent builds  - don't wait until the end to check if things work.

Things to test as you go:

* Does the game render correctly before any bet is placed?
* Does **playGame()** start the game and show the result?
* Does **handleReset()** return it to exactly the starting state?
* Can you **handleRewatch()** the previous game without placing a new bet?

If something looks wrong, describe it to the agent and ask it to fix it.

<mark style="color:green;">**Step 5.  Ask the agent to run the checklist**</mark>

When you think the game is done, send this prompt:

```
Please run through the completion checklist at the bottom of 
SKILL.md and fix anything that isn't passing. Then run 
npx tsc --noEmit and fix any TypeScript errors.
```

This catches most common issues before submission.

<mark style="color:green;">**Step 6.  Fill out metadata.json**</mark>

The file is already in the root of the repo. You can ask the agent to fill it out:

```
Please fill out metadata.json based on the game you built. 
Use my GitHub username as the team name in kebab-case.
```

Review what it fills in, and make sure **gameName** matches your folder name exactly and all fields are present.

<mark style="color:green;">**Step 7.  Submit**</mark>

When your game is ready, submit it to the submissions repository. Follow the README there for exactly which files to include in your pull request and how the review process works.

**Submissions repo:** [ape-church-game-submissions](https://github.com/ape-church/ape-church-game-submissions)

<mark style="color:green;">**Tips for Working with AI Agents**</mark>

* **Ground the agent first.** Always start with the prompt in Step 3. Agents that skip SKILL.md produce inconsistent code that fails review.
* **Be specific about your game.** Vague prompts produce vague games. Describe exactly how the player interacts, what the win condition is, and what the visual experience should feel like.
* **Test frequently.** Don't let the agent build for 30 minutes without checking the result. Test after each meaningful change.
* **Describe issues clearly.** When something breaks, describe what you expected vs. what happened. Screenshots help. The more context you give, the faster it gets fixed.
* **Don't let the agent go off-script.** If it starts modifying files outside components/my-game/ or public/my-game/, stop it and redirect. Those files are platform-managed and changes there will be rejected.

<mark style="color:green;">**Questions or Issues**</mark>

If you run into problems while building or have a game idea you want to discuss before starting, please contact us here <mark style="color:green;">**<ministry@ape.church>**</mark>**&#x20;or** [<mark style="color:green;">**Discord**</mark>](https://discord.gg/3Jxeeqt59W)<mark style="color:green;">**.**</mark>&#x20;

Include a description of your game idea or the issue you're running into, and we'll get back to you.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ape.church/building/build-a-game.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.