gamestack

🎮 gamestack

An agentic framework for building games on any platform — for Claude. Like gstack is for software, but for games.

Questions, feedback, or just want to follow along: Discord · @metatransformr on X

What this actually is (read this first if you came from a link)

This is a skill pack for an AI coding agent — cited game-design knowledge plus reusable engineering patterns, written as Markdown that Claude Code loads on demand. It is not a game, not a game engine, and not a single codebase you clone and godot --editor into — there's no .tscn file in this repo. If you're looking for the actual input/verb/seam architecture and headless test-bench pattern referenced elsewhere (e.g. a Reddit post about building a Godot RPG from the terminal), the concrete, runnable-code version of that lives in docs/headless-architecture.md — a worked Godot example, with the input→verb→seam pattern, the bench pattern, deterministic headless time (--fixed-fps), a playtest API, and a GitHub Actions example. Everything else in this README is the design-knowledge half: what an agent should know before and while it builds.

gamestack is two things working together:

• A design brain — first-party, engine-agnostic skills that give Claude the knowledge of game design (cited, discipline by discipline) and the process to apply it: concept → world → content → self-review → iterate.
• Engine hands — curated, best-in-class community skill packs for each engine (Godot, Unreal, Unity), referenced directly from one marketplace so Claude can turn a design into real engine code.

You design once, then hand off to whichever engine you're shipping in. The design layer doesn't overlap the engine packs — it's the layer they're missing.

                        gamestack  (one marketplace)
                              │
        ┌─────────────────────┼──────────────────┬──────────────────┐
   gamestack                godot               unreal           unity-jahro
 (first-party brain)       (jame581)          (quodsoler)       (jahro-console)
 design · procgen ── implements ──▶  GDSCRIPT · C++ · per-engine code
 combat · process

We don't reinvent engine work others do well — we slot it in and add the design/discipline layer on top, plus the router that binds them.

---

How it fits together

Layer	What it is	Who builds it
🧠 Design brain (first-party)	Cited design disciplines + the headless generate-and-review pipeline. Engine-agnostic.	This repo
🎮 Engine hands (curated)	Per-engine implementation skills (code patterns, systems, optimization), referenced from the marketplace by their authors.	Community, MIT-licensed
🔀 The router	engine-router — detects the target engine and routes: design → brain, implementation → the right engine pack.	This repo

---

The two first-party skill kinds

Layer	What it is	Example
🧠 Knowledge	A cited design discipline as a guide + do/don't checklist. The "what good looks like."	open-world-design, procedural-generation
⚙️ Process	A workflow verb the agent runs — generate, review, route, plan. Draws on the knowledge skills.	procgen-review, game-design-process, engine-router

---

The pipeline

  CONCEPT ──▶ WORLD & SYSTEMS ──▶ CONTENT ──▶ REVIEW & GATE ──▶ HANDOFF ──▶ ENGINE CODE
  pillars,    structure, nav,      procgen +   oatmeal/fanfic/    engine-     godot / unreal /
  core loop,  progression,         handcrafted  sameness/anti-     router      unity pack
  signature   economy, combat,     anchors,     pattern gates      picks the   implements
  mechanics   systemic rules       lore                            engine      the spec
  └──────────────── design brain (first-party) ───────────────┘ └──── engine hands ────┘

game-design-process orchestrates the design half and pulls the right skill at each phase. engine-router runs the handoff to engine code. Start at either, or invoke any skill directly.

---

Headless, testable architecture (input → verb → seam)

The other half of how this actually gets built — not just designed — once content exists: every system needs to be checkable without a human walking to it in a running game, and every input needs to drive the game through one auditable path.

• Input never performs logic. A keyboard read, a gamepad read, and an automated test all translate to the same verb call on a seam (a single object that owns the action). Keyboard and gamepad can't drift apart; a headless test exercises the real code path.
• Every system that's worth iterating on gets a preview harness ("bench") — boots that one slice headless, takes parameters from the CLI, captures deterministically, quits. godot --headless --path . res://tools/benches/DungeonBench.tscn -- --shots --seed=1234 and you get the same PNGs every time — golden-image testing for procgen, no editor required.
• Headless time isn't wall-clock time by default — Godot's --fixed-fps N flag forces every frame's delta to exactly 1/N regardless of real elapsed time, making physics/animation/movement fully deterministic and machine-speed-independent.
• A playtest API is just verbs composed into a session (boot(), goto(), fight_nearest(), loot_nearby(), rest()) — an integration test, or an AI agent, can play the real game headless and read the result back from logs and screenshots.

This is the concrete form of iteration-loop's preview-harness pattern and AI-playtester concept (the skill describes it engine-agnostically; the pattern itself is good testing hygiene regardless of whether an AI ever touches it). Full worked example with real GDScript, the determinism flag, and a GitHub Actions setup: docs/headless-architecture.md.

---

First-party skills (the design brain)

Process

Skill	What it does	Status
game-design-process	The orchestrator. Walks concept → world → content → review → iterate and names which skill to use at each phase. The entry point for "I'm designing a game."	🟢 v0.1
engine-router	The platform router. Takes a ready design and routes implementation to the right engine pack (Godot/Unreal/Unity), keeping design logic and engine code cleanly separated.	🟢 v0.1
procgen-review	The self-review pass for generated content. Runs the oatmeal test, the fanfic/retell test, a cross-instance sameness scan, and the intentionality + anti-pattern gates. Built to run in a headless generation loop.	🟢 v0.1
iteration-loop	The generic Reference → Diff → Prioritize → Generate/Implement → Verify loop that brings any system — visual, systemic, or narrative — up to fidelity with its intended target, in any engine. Covers the preview-harness pattern, animation contact-sheet capture, the human + AI playtester channels (the latter via a "playtester API"), and the external-asset-request escalation. Gates fidelity; procgen-review gates variety — independent axes.	🟢 v0.1

Knowledge

Knowledge skills are organized into three tiers (see docs/architecture.md): universal craft (every game needs them → headed for gamestack-core), genre lenses (pulled for that kind of game), and technique modules (pulled when using that technique). Today they all live in the one gamestack plugin and are tagged with their tier in SKILL.md; the split into separate marketplace packs is a later, mechanical move.

🌐 Universal craft — applies to every genre

Skill	What it covers	Status
game-design-fundamentals	The spine the rest of the pack builds on: interesting decisions (Meier), flow & difficulty curves, motivation (Self-Determination Theory), feedback & agency, and choice architecture — with machine-checkable tests for a generation loop.	🟢 v0.1
game-feel-and-juice	The moment-to-moment feel of any action: Swink's three building blocks (fix feel before you juice it), input latency & forgiveness (coyote time, buffering), the juice toolkit + the inverted-U ceiling (Kao), the 12 animation principles, camera & UI feel — as a per-action feedback budget a generator can't exceed. (Extracted as the universal foundation under combat-design.)	🟢 v0.1
level-design	The craft of shaping space & encounters: guiding the player (leading lines, landmarks, light, affordances), structure & gating (lock-and-key, interconnection), teaching through space, arena design, in-level pacing, the greybox/metrics process — and a level-design grammar for generators.	🟢 v0.1
onboarding-and-teaching	Tutorialization & the first-time experience: teach one mechanic at a time (introduce→test→combine→twist), show-don't-tell over pop-ups, progressive disclosure, the FTUE/retention funnel — and a dependency-ordered teaching ramp for a generated verb set.	🟢 v0.1
ui-ux-and-feedback	Game UI/UX at the design level: the diegetic/non-diegetic/spatial/meta framework, information hierarchy & cognitive load, game-state feedback, menu & navigation flow — and generating a HUD/UX spec from a mechanic set.	🟢 v0.1
difficulty-and-balancing	The most machine-checkable discipline: eliminating dominant strategies (payoff-matrix dominance checks), cost-curve/power-budget balance, difficulty curves & DDA/hidden directors, per-axis accessibility assists, and metrics/simulation-driven tuning.	🟢 v0.1
pacing-and-the-player-journey	Macro pacing as a complement to game feel: the fractal interest curve (encounter→level→session→playthrough), challenge/rest rhythm, novelty cadence, the nested engagement loops + retention-ethics line, and a spec-level pacing director for generated content.	🟢 v0.1
art-direction-and-readability	Design-level visual communication: readability as an engineerable objective, silhouette-first validation, value/contrast eye-direction, reserved signal colors, fidelity-fights-readability, the named style bible, and per-asset read contracts for generators.	🟢 v0.1

🛠️ Technical craft — applies to every real-time 3D (or 2D-with-lighting) game, regardless of genre. Engine-agnostic design-spec level (principles, citations, "Test for:" criteria — no engine code); topic breadth inspired by GodotPrompter's implementation-skill library, but researched and written independently. See docs/architecture.md for why this is a separate tier from universal craft and technique modules.

Skill	What it covers	Status