makepad/skills/makepad-game-director/SKILL.md

name

description

makepad-game-director

Entrypoint for building, upgrading, and finishing Makepad/Rust games in this repo. Routes work across the sibling makepad-* skills for gameplay, rendering, UI, 3D/image/audio asset sourcing, debugging, and release. Use for build-a-game, upgrade, polish, premium, AAA, high-fidelity, showcase, from-scratch, arcade, racing, action, XR, and release-ready requests targeting makepad-arcade and the libs/game crates.

Makepad Game Director

Own the end-to-end game outcome: a playable loop first, then the visual and interface depth the request actually asked for, then on-device evidence that it works.

This pack is the Makepad counterpart to the Three.js game-skills pack. The workflow is the same; the runtime is not. There is no npm, no Vite, no DOM, no Playwright. The runtime is Rust + Makepad, the renderer is makepad-game-render, the simulation is makepad-game-sim, and verification runs through cargo test, makepad-test (real widget-level driving + screenshots), and probe examples.

Scope

The user's own words set the bar. "Make a small arcade game" is not a request for the full premium pipeline — build the good version of what was asked and stop. "Premium", "AAA", "polished", "high-fidelity", "showcase", "release-ready", or "less basic" is that request, and at that bar a first playable slice is not done. "Less basic" specifically means the current visual level was rejected; treat it as the premium bar.

The user's scope, art style, constraints, and prior decisions override skill defaults. A narrow edit to a premium game remains a narrow edit. Make routine implementation calls yourself and complete authorized work before seeking a decision that only affects a later step. Ask only when a missing choice materially changes the requested result; continue independent work meanwhile.

Working style

Say in one sentence what you're about to do before your first tool call. While working, give a brief update only when you find something important or change direction. Lead the final response with the outcome.

The lead owns shared interfaces, integration, and the final verification pass. Use available delegation tools for independent work that saves time or improves quality: asset indexing alongside gameplay, or isolated UI work after the intent/state interface is defined. Normally use a lead plus up to two workers. Give each worker a task, separate file ownership, input/output contract, and acceptance criteria. Keep the immediate blocking integration work with the lead.

Rust adds one constraint the Three.js pack does not have: the crate must compile for every worker's commit. Split work by crate or module, never by lines inside one file, and have each worker run cargo check -p <crate> before handing back.

Report what you ran and what you saw. If you couldn't run something, say that instead.

Sibling skills

Use the actual loaded skill directory as <director-skill-dir>. Resolve siblings through ../<skill>/SKILL.md there. If absent, use the runner's discovered skill path, then this repo's skills/ directory, then the active runner's install location (~/.agents/skills for Codex, ~/.claude/skills for Claude Code, legacy ~/.codex/skills last). Resolve references relative to the selected skill; avoid mixing installed versions.

Phase	Skill
Design brief, core loop, levels, entities, input, camera, physics, feel	makepad-gameplay-systems
Meshes, materials, shaders, VFX, lighting, render budget, scorecard	makepad-aaa-graphics-builder
HUD, menus, overlays, responsive and touch UI, splash DSL styling	makepad-game-ui-designer
Black viewport, render/runtime bugs, mobile & XR input, profiling	makepad-debug-profiler
Cargo QA, screenshots, widget snapshots, bot playtest, release build	makepad-qa-release
Characters, vehicles, weapons, buildings, rigs, animation	makepad-3d-generator
Textures, skies, palettes, icons, GUI art, procedural image sources	makepad-image-generator
SFX, ambience, UI sounds, music jingles	makepad-audio-generator

For complete games and broad upgrades, read all five production skills before implementing, plus generators whose trigger surfaces exist. Read each phase's required references at phase entry. For narrow edits, load the affected specialists and references, preserving unrelated systems. Record actual loaded resources when reporting skill use; a phase label is not a skill invocation.

Two ways to build a game here

Decide this first, because it determines which specialists matter.

A. Script route (game.* verbs). The game is a script driven by makepad-game-script's ~180 verbs (box, mover, character, car, race, on_tick, sfx, particles, camera, …), evaluated by ScriptHost inside makepad-arcade. Fastest path to playable, sandboxed (Trust / strip_capabilities), hot-reloadable, and network-replicable for free. Choose it for game-jam scope, AI-authored games, and anything that should ship as a makepad-game-pkg package.

B. Rust route (native app crate). A new crate under apps/, owning its own widget and calling makepad-game-sim + makepad-game-render directly, the way apps/arcade/src/arcade_view.rs does. Choose it when the game needs systems no verb exposes, custom shaders beyond the splash overrides, or its own binary.

Default to A unless the request needs engine-level control; escalate to B when a verb gap blocks the design, and say so when you switch. See references/architecture.md.

Continuity and early quality

Start broad builds with the gameplay design brief, core-loop contract, and level plan. Define art direction, camera scale, and hero/readability targets early. Start asset library work (download_assets.sh, find_model / find_cast queries) while implementing the loop, then assess a representative playable scene with real assets before multiplying levels, waves, or enemy variants.

For substantial tasks maintain artifacts/game-progress.md: current intent and constraints, decisions, completed work, pending jobs, remaining defects, and next actions. Re-read it after an interruption. A correction updates affected work; a status question does not replace the build objective. Preserve completed assets and mark obsolete pending outputs.

The bar for premium work

Every visible surface that exists in the design is authored, not just the hero: player, obstacles and enemies, interactables, ground and world kit, HUD and menu states, lighting and materials, feel, and target-device performance. Untextured Shape::Box primitives, empty flat terrain, box skylines, generic stat-card HUDs, and glow-or-fog-only detail are prototype placeholders unless the user explicitly chose that style. Interpret the scorecard through the genre rather than adding unrelated content.

Score the result with the 10-category scorecard in makepad-aaa-graphics-builder/references/visual-scorecard.md. Premium means no category below 2 and an average of at least 2.3.

Asset sourcing

This repo ships a ~5000-entry CC0 library instead of paid generation APIs. Probe it before planning any asset work:

bash <director-skill-dir>/scripts/probe_assets.sh

If the library is absent, fetch it once:

./apps/arcade/download_assets.sh                 # core packs, ~75 MB
./apps/arcade/download_assets.sh --packs=all     # full catalogue, ~185 MB
./apps/arcade/download_assets.sh --list          # inspect, download nothing

Search by description, never filename, through makepad-game-assets. Ids look like kenney/racing/vehicle-truck-yellow and are stable across re-downloads. Rigged characters come from casts (find_cast): pick members of ONE cast per scene so animation is shared, and use different members so a crowd is not clones. When nothing in the library fits, generate geometry procedurally with makepad-game-gen — see makepad-3d-generator. Everything degrades gracefully: with no assets downloaded the game still runs on primitives, and asset-dependent tests skip with a hint.

Verification ladder

Scale it to the change. Every rung is in makepad-qa-release.

1. cargo check -p <crate> — never hand back code that does not compile.
2. cargo test -p <crate> — sim, gen, audio, net, coedit are all Cx-free and unit-testable.
3. cargo test -p makepad-arcade with makepad-test — drives the real app, screenshot(), widget_snapshot(), wait_for_log_contains().
4. Probe examples (cargo run -p makepad-arcade --example bigworld_probe) for headless render/perf evidence.
5. --release build plus a frame-time reading against apps/arcade/BUDGETS.md.

Required reading at entry

• references/architecture.md — crate map, both build routes, where each system lives.
• references/workflow-evaluations.md — phase order, delegation, review gate.
• references/evidence-manifest.md — what counts as proof, per change size.
• references/asset-library.md — searching, casts, packs, procedural fallback.