# Makepad Game Skills

Self-contained Codex and Claude Code skills for building playable, polished **Makepad** games in Rust. Install the skills, then ask your agent to use `makepad-game-director`; the director routes gameplay, graphics, UI, asset sourcing, audio, debugging, and release verification without requiring you to choose every specialist skill manually.

This is a port of [threejs-game-skills](https://github.com/majidmanzarpour/threejs-game-skills) by [Majid Manzarpour](https://x.com/majidmanzarpour) to the Makepad engine. The workflow, the director pattern, the premium bar and the visual scorecard come from that pack. Everything about the runtime is different.

## What changed in the port

| Three.js pack | This pack |
| --- | --- |
| Vite + TypeScript + Three.js scaffold | Rust workspace crates: `apps/arcade` or a new `apps/<game>` |
| `npm`, `package.json` | `cargo`, workspace `Cargo.toml` |
| Playwright browser QA | `makepad-test` — drives the real app, real input, `screenshot()`, `widget_snapshot()` |
| DOM/CSS HUD | `makepad-widgets` + `makepad-game-render::hud`, styled with `script_mod!` |
| GLSL in-material shaders | engine shaders in `libs/game/render`, look overridden in the splash DSL |
| Paid 3D / image / audio generation APIs | the vendored ~5000-entry **CC0 library** plus procedural `makepad-game-gen` |
| `requestAnimationFrame` loop | fixed `TICK_DT` sim step + `GameRenderer` adaptive quality |
| No multiplayer story | host-authoritative `makepad-game-net` / `makepad-game-session` |

**No paid API key is required by any skill in this pack.**

## The nine skills

| Skill | Owns |
| --- | --- |
| `makepad-game-director` | entrypoint; routes everything, sets the bar, owns continuity |
| `makepad-gameplay-systems` | core loop, movers vs rigid bodies, input, camera, AI brains, racing, netplay |
| `makepad-aaa-graphics-builder` | lighting, materials, shaders, shadows, AO, VFX, render budget, **visual scorecard** |
| `makepad-game-ui-designer` | HUD, menus, overlay states, responsive/touch/XR UI |
| `makepad-debug-profiler` | black viewport, silent asset fallback, stutter, desync, profiling |
| `makepad-qa-release` | the verification ladder, driven tests, evidence, packaging |
| `makepad-3d-generator` | CC0 model search, rigged casts, procedural geometry |
| `makepad-image-generator` | procedural textures, palettes, sky, icons |
| `makepad-audio-generator` | sample bank, mixer, material impacts, 3D audio, the mix |

## Install

From this checkout:

```bash
./skills/install.sh --codex     # ~/.codex/skills
./skills/install.sh --claude    # ~/.claude/skills
./skills/install.sh --all
./skills/install.sh --list      # see what's in the pack
./skills/install.sh --codex --force
```

`--agents` installs into `~/.agents/skills` for surfaces that read only that root. Avoid installing duplicate copies into two roots.

## Use

Open your agent in this repo and name the director:

```text
Use makepad-game-director to build a premium arcade racing game in this repo.
Automatically use the relevant gameplay, graphics, UI, asset, audio, debug and
QA skills. Build a playable loop first, then iterate until it passes cargo
tests, driven makepad-test runs, screenshot review, and the frame budget.
```

Both runners share the same `SKILL.md` files. Claude Code reads `~/.claude/skills` and routes from each description; Codex discovers skills and uses `agents/openai.yaml` for the display name and a `$skill-name` kickoff prompt.

## Two build routes

The director decides this first, because it determines everything downstream:

**Script route** — the game is a set of `game.*` verbs (~180 of them: `box`, `mover`, `character`, `car`, `race`, `on_tick`, `sfx`, `particles`, `camera`, …) evaluated by `ScriptHost`. Sandboxed, hot-reloadable, network-replicable, packageable. The default.

**Rust route** — a new crate under `apps/` calling `makepad-game-sim` and `makepad-game-render` directly, modelled on `apps/arcade/src/arcade_view.rs`. For when a verb gap blocks the design.

## Assets

Binaries are not in git. Probe first, fetch once:

```bash
bash skills/makepad-game-director/scripts/probe_assets.sh
./apps/arcade/download_assets.sh                 # core, ~1900 models, ~75 MB
./apps/arcade/download_assets.sh --packs=all     # 4669 models / 47 packs, ~185 MB
```

Everything is CC0, pinned, and sha256-verified. Search by **description**, never filename. Gaps are filled procedurally with `makepad-game-gen`, which is seeded and deterministic, so content replicates as `(preset, seed, position)` rather than vertex data.

Without any download the game still runs on primitives and asset-dependent tests skip — convenient for CI, and the reason every skill insists on asserting `model_is_loaded(id)` rather than trusting a screenshot.

## Validate

```bash
./skills/validate-skills.sh
```

Checks frontmatter, name/directory agreement, agent manifests, that every referenced file exists, that scripts are executable and syntactically valid, and that cross-skill references resolve.

## Credits

Skill structure, director pattern and quality bar: [threejs-game-skills](https://github.com/majidmanzarpour/threejs-game-skills) by Majid Manzarpour.
Game assets: Kenney (<https://kenney.nl/assets>) and KayKit / Kay Lousberg (<https://kaylousberg.itch.io/>), all CC0. Machine-readable attribution lives in `apps/arcade/resources/CREDITS.toml`.