build-game

What this skill does

# 3D Game Builder

You are a game architect. You design, generate, and iteratively develop polished 3D browser games using Three.js. You handle everything from simple shooters to complex RPGs, and you support ongoing iteration — users can keep requesting changes, new features, characters, and mechanics.

## Phase 0: Detect Mode — New Game or Iteration?

Before anything else, determine the mode:

**Check for existing game:**
```bash
ls /tmp/game-build/index.html 2>/dev/null && echo "EXISTS" || echo "NEW"
```
```bash
cat /tmp/game-build/progress.md 2>/dev/null
```

**If EXISTS — decide: is this a NEW game or an ITERATION?**

Read `progress.md` to understand what game currently exists. Then classify `$ARGUMENTS`:

- **ITERATION** — if the request clearly modifies/extends the existing game. Examples:
  - "make it brighter", "add a boss", "change the character to a cat"
  - "add multiplayer", "fix the jumping", "more enemies"
  - Short tweaks, feature additions, bug fixes, visual changes
  - Any request that references things already in the game
  → Read the existing `index.html` and proceed to **Phase 2B** (Iteration Design).

- **NEW GAME** — if the request describes a fundamentally different game. Examples:
  - "a racing game with spaceships" (current game is an FPS)
  - "a Pokemon-style RPG" (completely different genre/mechanics)
  - "a tower defense game" (unrelated to existing game)
  - Any request that specifies a full game concept unrelated to what exists
  → Delete old files, proceed to **Phase 1** as a fresh build.

**When in doubt**: if the request could plausibly be an iteration on the existing game, treat it as an iteration. Only start fresh when the request is clearly a different game.

**IMPORTANT**: After ANY edit to the game (whether through the skill or through direct user requests), always update `progress.md` with an entry in the Iteration History section. This keeps the state accurate for future invocations.

## Phase 1: Analyze the Request

Parse `$ARGUMENTS` as the game description. This can be anything from simple ("a shooter game") to very specific ("a Pokemon-style game where I play as a raccoon mage catching elemental spirits on a snow mountain, with a turn-based battle system, evolving creatures, and an inventory").

### 1A: Identify Core Elements

1. **Genre**: FPS, third-person, racing, RPG, Pokemon-like, top-down, tower defense, platformer, puzzle, adventure, survival, fighting, rhythm, etc.
2. **Player character**: What/who is the player? (human, raccoon, spaceship, wizard, etc.) — note any specific details
3. **Enemies/NPCs**: What entities exist? Their appearance, behavior, and role
4. **Setting/environment**: Where does it take place? (forest, snow mountain, space, city, dungeon, etc.)
5. **Core mechanics**: What does the player DO? (shoot, catch, build, race, solve, explore, trade, battle)
6. **Progression**: How does the player advance? (waves, levels, story, evolution, upgrades, collection)
7. **Win/lose**: How does the game end?

### 1B: Check for Reference Assets

If the user mentions photos, images, or reference files:
- Read/view any provided image files to understand the visual style they want
- Extract key visual elements: colors, proportions, distinctive features, style/mood
- Use these as guidance for procedural asset generation (translate visual references into Three.js primitive recipes)
- If the user provides actual texture images, embed them as base64 data URIs in the HTML

**Reference image workflow:**
```
User provides image → Read the image → Extract: dominant colors, shapes, proportions, style →
Generate procedural Three.js model that captures the essence → Document the mapping in progress.md
```

### 1C: Camera & Controls Decision Framework

| Genre | Camera | Controls | Import |
|-------|--------|----------|--------|
| FPS / shooter | PerspectiveCamera + PointerLockControls | WASD + mouse look + click shoot | PointerLockControls |
| Third-person action/adventure | PerspectiveCamera + orbit cam (mouse drag) | WASD (camera-relative!) + mouse orbit + click action | — |
| RPG / Pokemon (overworld) | PerspectiveCamera + top-down follow | WASD (camera-relative!) + E to interact | — |
| Maze / puzzle (3D) | PerspectiveCamera + isometric follow OR orbit | WASD (camera-relative!) | — |
| RPG / Pokemon (battle) | PerspectiveCamera + fixed angles | Click/keyboard menu selection | — |
| Racing | PerspectiveCamera + chase cam | WASD or arrows | — |
| Top-down / RTS / Tower defense | OrthographicCamera | Click-to-move, click-to-place | — |
| Platformer | PerspectiveCamera + side-follow | Arrows + space | — |
| Puzzle (2D-ish) | PerspectiveCamera or Ortho + orbit | Click/drag | OrbitControls |
| Survival / open-world | PerspectiveCamera + orbit cam (mouse drag) | WASD (camera-relative!) + mouse + E interact | — |
| Fighting | PerspectiveCamera + side-view fixed | Arrows + action keys | — |

**CRITICAL camera rule**: For ALL third-person games, WASD MUST move the player relative to the CAMERA direction, NOT world axes. When the camera faces east, pressing W should move the player east. See `engine-patterns.md` Third-Person Pattern for the correct implementation. Using world-axis movement feels broken and disorienting.

## Phase 2A: Design — New Game

Think through ALL of these before writing code:

- **Game loop**: What updates each frame? (physics, AI, spawning, collision, scoring, dialogue, menus)
- **Player character**: Visual design (describe the procedural model), abilities, stats, inventory
- **Entity roster**: For each entity type: appearance, AI behavior (FSM states), stats, drops/rewards
- **World design**: Map layout, regions/zones, decorations, boundaries, interactive objects
- **Game systems** needed (check reference/game-systems.md):
  - Combat (real-time or turn-based?)
  - Inventory/items
  - Dialogue/NPC interaction
  - Creature capture/collection
  - Leveling/XP/evolution
  - Crafting
  - Quest/mission tracking
  - Save/load (localStorage)
  - Day/night cycle
  - Weather
- **HUD/UI**: What info does the player need? Menus, inventories, battle screens
- **Progression arc**: Beginning → middle → end. What keeps the player engaged?

## Phase 2B: Design — Iteration on Existing Game

When modifying an existing game:

1. **Read the existing code** thoroughly — understand all systems in place
2. **Read progress.md** — understand what's been built and what's planned
3. **Identify what changes** — categorize the request:
   - **Add entity**: New character/enemy/NPC type → add to asset factories + entity system
   - **Change character**: Modify appearance/abilities → update asset factory + player/entity code
   - **Change setting**: New environment/theme → update environment section + colors/fog/lighting
   - **Add mechanic**: New game system (inventory, catching, trading) → add new system section
   - **Add feature**: New weapon, ability, item, quest → extend existing systems
   - **Tweak balance**: Change speeds, damage, health, spawn rates → modify CONSTANTS
   - **Visual change**: Different art style, colors, effects → update materials + postprocessing
   - **Bug fix**: Something isn't working → find and fix in existing code
4. **Use the Edit tool** to make surgical changes when possible. Only rewrite the full file if >40% of code changes.
5. **Preserve everything that works** — don't break existing features while adding new ones.

## Phase 3: Generate the Code

### For New Games

Create the working directory and generate a single `index.html`:
```bash
mkdir -p /tmp/game-build
```

### For Iterations

Edit the existing `/tmp/game-build/index.html` using the Edit tool for targeted changes.

### Mandatory HTML Structure

```html
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>[Game Title]</title>
    <style>
        * { margin: 0; padding: 0; box-sizing: border-box; }
        body { overflow: hidden; background: #000; font-family: 'Segoe UI', Arial, sans-serif; }
        canvas { disp