yume

Compositional / recipe-system designer for Yume games. Translates GDD intent for crafting / alchemy / breeding / key-combos / chemistry / spell-combinations into a concrete combining-design.md — recipe table, discovery model, yield rules, failure modes, Yume primitive mapping. Universal pattern (NOT magic-specific) — the underlying shape is "input set + combination rule → output", which appears in dozens of genres.

Run the Yume text-to-game pipeline. Orchestrates 7 specialist skills (yume-game-designer → game-planner → systems-designer → content-designer → asset-designer → qa-tester, plus tech-director on demand) with optional user-approval gates. Skills load into orchestrator context (no subagent spawn — Tier 2.6 architecture). Flags - `--autonomous` skips approval gates and runs end-to-end. `--plan-only` stops after the planning phases (GDD + world-plan) so the user can review before any JSON is committed. `--with-assets` invokes AI-gen pipeline. `--style=pixel-art|low-poly-3d|ascii` art-style hint. `--name=<slug>` game folder name.

Spatial layout designer for Yume games. Reads GDD + world plan, produces level-design.md with concrete coordinates for every placement plus a design rationale per element. Genre-aware patterns (TD paths with chokepoints, shooter arenas with cover, sim zones with density falloff). Output is the single source of truth for content-designer's placement work.

Genre-specific designer for arcade racing games — kart racers (mascot-style kart racer), high-speed (futuristic anti-grav racer), top-down (top-down arcade / top-down combat racer), time-attack (precision time-attack racer), checkpoint runners (arcade crash-racer). Owns the tuning discipline that makes a car FEEL like a car: vehicle profile, steering rate vs speed, drift mechanic, lateral-grip scrubbing, surface variety, AI rubber-banding, power-up taxonomy, race structure, camera. Archetype-driven — every design decision benchmarks against a named racing archetype. Does NOT cover sim racing (dedicated racing simulators) — that needs continuous physics out of Yume's scope.

One-command text-to-3D-world pipeline. From a prose scene pitch, produces a runnable Yume scene end-to-end — hero reference → hero-conditioned orthographic → semantic + heightmap → extract → map (compose_world) → presentation shell (compose_shell) → optional Tripo assets. The catalog is the single LLM-authored input; tools.visual_layout.compose_scene drives the rest deterministically. Invoke when the user wants a whole new 3D scene/level from a description (NOT for HUD/screen authoring, single assets, or GDScript-game generation).

Stage 2 of the text-to-world pipeline (2026-05-25). Reads a scene brief + reference photoreal aerial and produces a fully-dynamic per-scene class catalog plus the stage-3/4/5 prompts. Class count is dynamic 6-32; classes named freely per genre (medieval town vs sci-fi colony vs dungeon vs alien world all get entirely different catalogs). data/lib/semantic_palette.json provides palette conventions; data/lib/extraction_strategies.json provides per-class extraction strategies (extraction_method + rotation_rule + y_anchor + primitive + canonical size) that the catalog injects into each object_placement entry so stage-5 lib_extract can dispatch by name lookup. Outputs class_catalog.json, semantic_map_prompt.txt, heightmap_prompt.txt, and scene_biome_mapping.json (for ADR 0055 engine wiring).

Visual + audio + UI-style designer for Yume games. Picks ONE consistent strategy per project (library lookup / AI-gen prompt / code-draw shape) for visuals; writes audio cue mappings and localized strings. Per ADR 0009 — owns audio/cues.json (semantic event → sound name) and ui/strings.json (localizable HUD text), in addition to entity visual/audio fields and scene/hud config. Doesn't generate raw asset files (.png/.glb/.ogg) — that's the offline `yume assets generate` tool.

Second-pair-of-eyes for Yume engine + content changes. Socratic, principle-aligned, smell-based. Reviews diffs / files / sessions and produces a tight verdict (accept / accept-with-conditions / revise / reject). NOT the invariant gate — that's yume-tech-director. NOT a designer — those are the domain skills. This is the "code reviewer" who asks the questions the user would.

Entities + initial state designer for Yume games. Translates GDD + world plan into entity definitions (entities/*.json), initial placements (per-level entities.json), and world initial state (world/state.json). Picks tag names, state field names, default values, positions. Per ADR 0009 — narrowed scope: rules are NOT this skill's job. World physics rules go to yume-systems-designer; game rules go to yume-game-rules-designer. This skill owns the entity vocabulary and where things are at level start.

Numeric balance + resource flow designer for Yume games. Reads GDD + world plan (+ optional combining-design.md) and produces economy-design.md with explicit sources/sinks per resource, conversion ratios, currency design, pricing curves, pacing math, and adversarial balance checks. Owns the question "do the numbers work?" — catches degenerate strategies, money pumps, and progression cliffs at design time instead of QA time. Applies to TD economies, RPG XP/gold/loot, merchant games, factory chains, civilization-style city economies.

First-line designer for Yume games. Takes a prose description of a game and produces a structured GDD using MDA decomposition (Mechanics → Dynamics → Aesthetics). Output feeds yume-systems-designer.

Translates the abstract GDD (from yume-game-designer) into a concrete world bible — named NPCs with schedules, named items with purposes, named plants with growth properties, named events with triggers, town layout. Bridges design philosophy and content authoring.

Adversarial reviewer for Yume GDDs. Reads docs/games/<name>/GDD.md and applies critical-but-fair scrutiny across 15 depth axes (mechanical/strategic/pacing/feedback/aesthetic/scope/adversarial + total content scope, signature moments, theme/identity, replay value, real-UX, spatial-design/level-layout). Outputs review.md with verdict (accept/revise/reject) and concrete revision requests. Catches shallow designs at the text/idea level — cheap to iterate vs. discovering depth gaps after JSON + scenes are built. Round 2+ MUST run ripple-analysis: when a revision adds structural primitives (multi-level, persistent state, new modes), prior-round axis acceptance does NOT carry over to axes those primitives ripple into — re-interpret under the new design frame.

Goal-condition + flow-progression designer for Yume games. Per ADR 0009 revision (2026-05-16), scope NARROWED — rule authoring (scoring + transitions + objectives + tutorial overlays) folded into yume-systems-designer (writes world/rules/*.json). This skill now owns (a) declarative win:/lose: blocks in hud.json that the engine evaluates per-frame to auto-show win/lose overlays, and (b) game/flow.json for multi-level progression. When in doubt: rule authoring → systems-designer. Declarative HUD condition → this skill.

Genre-specific GDD writer for merchant / shopkeeping / item-shop games. Extends yume-game-designer's generic MDA framework with merchant-required sections — adventurer-class table (≥3 classes × ≥3 gear types each), daily cycle phase table (morning/adventure/shop/sleep durations + transitions), haggle mechanic spec (exchange shape, accept/reject rules), debt-pacing curve, reputation effects matrix, inventory UX. Pairs with yume-merchant-reviewer (8-axis strict review). Use when the prose pitch claims "merchant", "shopkeeper", "item shop", "merchant-shaped", "trader", or similar.

Genre-specific reviewer for merchant / shopkeeping / item-shop GDDs. Strictest layer — runs AFTER yume-game-reviewer's generic 15-axis accept, applies 8 merchant-specific axes that catch genre concerns the generic reviewer can't see (customer-archetype variety, class-gear coverage, daily-cycle pacing balance, haggle UX clarity, debt-tension curve shape, reputation depth, inventory readability, anti-pattern poke). Pairs with yume-merchant-designer. Built proactively as part of

Loads generated Yume JSON into the engine headless, runs N ticks, reports cascade outcomes vs GDD intent. Identifies bugs, dead entities, missing rules, runaway feedback loops. Final gate before declaring a game complete.

Genre-specific GDD writer for shooter / FPS / arena-shooter games. Extends yume-game-designer's generic MDA framework with FPS-specific required sections — movement profile (numbers, drag, diagonal), weapon arsenal table (≥2 weapons with full ballistic specs), enemy roster with weapon-matchup, ammo economy (math-checked), Y-axis policy, projectile-obstacle interaction, hit/kill feedback, restart UX. Pairs with yume-shooter-reviewer (10-axis FPS-strict review). Use when the prose pitch claims "shooter", "fps", "doom-style", "arena shooter", or similar.

Genre-specific reviewer for shooter / FPS / arena-shooter GDDs. Strictest layer — runs AFTER yume-game-reviewer's generic 15-axis accept, applies 10 FPS-specific axes that catch genre concerns the generic reviewer can't see (movement feel, ballistic distinctness, ammo economy, projectile-obstacle policy, weapon-enemy matchup, Y-axis pitch handling, hit/kill feedback, sightline/cover interaction, threat differentiation, restart UX). Empirically built after doomarena3d v2.5 needed reactive fixes (walk speed tune, diagonal motion, blocks_motion bug, weapons added) that an FPS-aware reviewer would have caught at GDD review.

Narrative arc + event scheduling + character progression designer for Yume games. Translates the GDD's narrative intent into a story-design.md with named beats, trigger conditions, character arc curves, branching/non-branching structure, and Yume primitive mapping (signals + world_state flags + level transitions). Distinct from yume-level-designer (which is spatial). Use for any game with a story arc, scripted events, named NPCs that change over time, or campaigns. Works for tightly-scripted (a classic JRPG, the raised-AI life-sim anime arc) AND emergent-narrative (an emergent-narrative sim, a grand-strategy sim) games.

Rules designer for Yume games. Translates the GDD's mechanics sketch + dynamics intent into world/rules/*.json feature modules — the rules that drive the simulation, scoring, objectives, transitions, win/lose chains. Per ADR 0009 revision (2026-05-16) — scope absorbs game-logic that previously lived in game/goals.json. Declarative win/lose conditions still live in hud.json. Also writes rule-sketch document for review before authoring; identifies if a new engine primitive is needed and proposes an ADR.

Guards Yume's primitive invariants. Reviews proposed engine changes (must come with ADR), verifies path-scoped rule compliance, gates merges. Cross-cutting reviewer that other Yume agents defer to before structural changes.

Auto-generates a visual_test_plan.json for a given game + level. Reads the GDD's aesthetic targets, the level's entities.json, the session's git diff, the assertion library, and the priors library — emits a concrete list of 10-15 visual tests that the ADR 0056 runner can execute. Distinct from yume-visual-designer (which is a subjective rubric reviewer) — this skill produces objective binary pass/fail assertions specific to the game's actual contents. Phase B of ADR 0056 / 0057.

Stage 5 of the text-to-world pipeline (2026-05-25). Reads a semantic map (PNG) + class catalog (JSON from stage 2) + optional heightmap (PNG from stage 4), and writes a per-scene Python extraction script that emits extracted.json — the sparse tile-map output containing per-class biome masks (terrain_shader), per-instance positions+rotations+sizes (object_placement), and a heightmap reference (terrain_displacement). LLM-as-script-author pattern: the script is custom per catalog (because every scene has different colors and class roles), but uses tools/visual_layout/lib_extract.py as the generic-helpers library so the per-scene part stays thin (~40-60 lines). Output extracted.json drives stage 6 (asset prompts) and stage 7 (engine wiring).

Fit-fit LEVEL/MAP authoring from a semantic top-down map image. Third sibling of yume-hud-author / yume-screen-author. Reads the per-game context from tools/visual_layout/wireframe_to_map.py preprocess (entity catalog with tags + asset_resolution anchor/zone hints + scatter_presets + world bounds + pixel→world coord transform) AND the map PNG via vision. Authors a level entities.json fragment where every initial_instance.def + pattern.def exists in the game's entity catalog (manifest-only, no invented def_ids), every position is computed deterministically from pixel bbox via the coord transform AND validated in-bounds, every pattern picks a scatter_preset and respects density+cap. Replaces the CV-based compile_map pipeline. Tier 2.7v (2026-05-20).

Generate a structured text-to-image prompt for orthographic top-down map renders (town / city / region / dungeon / level overview). Used right before calling openai_images / imagen / nanobanana with a "show me the whole map from above" intent. Produces a multi-section prompt (scene → perimeter → style refs → camera requirements → visual style → lighting → keywords) that reliably yields TRUE 90° orthographic views — not the angled cinematic shots image models default to. Empirical case: 2026-05-25 medieval-town render via gpt-image-2-2026-04-21 (194s, 2.7MB) succeeded end-to-end with this exact template.

Fit-fit HUD authoring from a wireframe image. Reads the per-game context from tools/visual_layout/wireframe_to_hud.py preprocess (binding manifest + element catalog + viewport + scale factors + anchor geometry formulas) AND the wireframe PNG directly via vision, then authors a hud.json where every panel's geometry is DERIVED from its wireframe bbox (not chosen freely) and every element type comes from the engine catalog. Replaces the CV-based yume-hud-layout pipeline — the LLM IS the parser. Tier 2.7v (2026-05-19).

Fit-fit SCREEN authoring from a wireframe image — for modal/full-cover UIs declared in screens.json (inventory, pause, settings, title menu, ending screens, ...). Sibling of yume-hud-author. Reads the per-game context from tools/visual_layout/wireframe_to_screen.py preprocess (broader 13-element catalog including interactive button/slider/checkbox + transition_screen target allow-list + effect allow-list) AND the wireframe PNG directly via vision, then authors a screen dict where every element's geometry is DERIVED from its wireframe bbox, every element type comes from the engine catalog, every `binds` is manifest-approved, every `transition_screen` target resolves, and every effect chain obeys destructive-last ordering. Tier 2.7v (2026-05-20).

Visual / art-direction critic for built Yume games. Runs the game (or reads existing captures), examines frames for aesthetic quality across 7 axes (readability, contrast, color harmony, layout balance, visual hierarchy, HUD integration, theme coherence), and produces a visual-review.md with prioritized JSON edits to improve how the game looks. Distinct from yume-qa-tester (which checks correctness) and visual-qa (frame-diff automation) — this skill is the LLM art director that makes the game pretty after it works. Output is actionable specific edits (color hex changes, size tweaks, position adjustments), not vague aesthetic opinions.

Designer for music + soundtrack architecture across a Yume game — distinct from yume-asset-designer (which writes audio/cues.json mapping signals to one-shot SFX). This skill owns: BGM selection per screen/level/state, dynamic intensity layers (calm/explore/combat/boss), bus design (composes ADR 0013's set_audio_bus_volume), looping + crossfade transitions, ambient layers, and stinger/jingle moments. Outputs audio-design.md + extends data/<game>/audio/cues.json with music-bed entries.

Designer for "game feel" — the polish layer of particles, screen shake, hit-pause, flash, camera kicks, and timing curves that make actions feel impactful. Distinct from yume-asset-designer (which picks visuals) and yume-visual-designer (which judges aesthetics) — this skill owns the kinetic micro-feedback per signal/event. Outputs juice-design.md + extends rules with juice effects (camera_shake, particle_emit, time_scale, flash_overlay) tied to game signals.

Designer for save_policy.json — declares what persists across sessions, autosave triggers, slot count, schema versioning. Per ADR 0010, the engine has one save/load implementation; per-game variation lives in this JSON. The skill answers: which world_state keys persist, which entity tags survive (persistent NPCs vs transient mobs), what causes an autosave, how many manual save slots, what version is the save schema. Distinct from save-state-designer (which is this skill renamed) — this is the policy author.

Designer for tutorial.json — the rule-chain that walks players through onboarding. Per ADR 0012, tutorial steps are JUST RULES with show_overlay/dismiss_overlay effects + signal sequencing. Skill owns: step sequence, advance conditions (action / signal / timer), highlight design (which entity to glow), pacing (don't overwhelm), skippable + replay flow. Outputs tutorial.json (rules in the same shape as world/rules/*.json feature modules — game/goals.json was removed per ADR 0009 revision 2026-05-16) + tutorial-design.md.

Designer for screens.json — the JSON-declared Godot Control hierarchy that defines a game's title menu, pause overlay, settings menu, save-slot picker, game-over screen, and any other shell-tier UI. Per ADR 0011 (refactored under ADR 0021), screens are JSON descriptions of Godot Control nodes (Button, Label, VBoxContainer, etc.) with on_click/on_change effect chains. The skill owns: which screens exist, their layout, navigation between them, button-click effects, modal vs replace semantics, freeze_world toggling. Distinct from yume-asset-designer (which writes hud.json and visual styling) — this skill owns the SHELL screens that wrap the gameplay.