@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/codex/skills/funpixel-gdd/references/genre-shooter.md

@@ -0,0 +1,128 @@
+# Shooters
+
+Twin-stick arenas, bullet hells and vertical scrollers, arena shooters, top-down run-and-gun,
+first-person arenas. (Survivor-likes with automatic fire are on the survival card.) What the
+genre's best games give players comes first, then the choices open to you, then the checks. The
+creator's brief wins over anything here.
+
+## What players remember
+
+- **The gun that felt amazing.** The kick, the sound, the enemy thrown back. A shooter is loved for
+  how shooting feels long before anyone reads its upgrade tree.
+- **The dodge through a wall of bullets.** Threading a gap with a pixel to spare, rolling through a
+  shot at the last moment. The best shooters make the player feel untouchable because they earned it.
+- **The screen that erupts.** A boss exploding in stages, a chain of kills that lights the arena, a
+  grid that bends under the blast.
+- **The room they cleared by the skin of their teeth**, and the one weapon they found that changed
+  the run.
+
+## The look and the world
+
+- Enemy shots are the brightest, most readable things on screen and share one threat colour; the
+  player's own shots are quieter so they never hide danger.
+- Each enemy kind has one shape and one colour, readable in a swarm.
+- The floor answers the action: scorch marks, shells and bodies that stay, a grid that ripples.
+- A strong world makes a shooter memorable: a dungeon of gun-shaped jokes, a neon void, a
+  mutant wasteland.
+
+## Characters
+
+A hero with a silhouette readable at 30 px and a personality in how they move (a swagger, a roll, a
+lean). Bosses are characters with phases and tells. Guns can be characters too: named, drawn big,
+with their own sound.
+
+## HUD
+
+Health as hearts or pips (countable at a glance), ammo or a cooldown near the hero or a corner, a
+boss bar across the top when it matters. The play space stays clear; the aim reticle or the second
+stick zone never hides a threat.
+
+## Feel
+
+- Every shot: a muzzle flash, a kick of the gun, a recoil nudge on the hero, a distinct sound.
+- Every hit: a spark, a flash on the enemy, knockback, a short freeze on a kill (a few frames).
+- Screen shake scaled to the weapon and capped; the camera leans a little toward where the player
+  aims.
+- The dodge has a clear safe window and a committed tail: it is a decision, not a spam button.
+
+## Hits to study
+
+- **Enter the Gungeon.** The dodge roll lasts about 0.7 s and only its first half is invulnerable,
+  so a roll is a commitment. Watch how enemy bullets are larger and brighter than the player's, and
+  how a scarce screen-clearing blank works as a panic button.
+- **Geometry Wars.** One shape and one colour per enemy kind, readable at a glance in a swarm; the
+  background grid bends and ripples back under every shot and blast, so the floor answers the
+  player. Its designer plotted the enemy shapes by hand on graph paper.
+- **Touhou and the bullet-hell tradition.** The player's real hitbox is far smaller than the sprite
+  and shows as a dot while moving slowly, which is why walls of bullets are passable. Look at how
+  patterns are designed as readable shapes (spirals, fans, rings) the player learns to read.
+- Nuclear Throne is often cited for its screen shake and weapon feel (kick, knockback, a brief freeze
+  on kills, bodies and shells that stay); its shake setting goes to 200%.
+
+## Conventions players bring
+
+What a player of the hit expects without being told. Keep them as defaults; breaking one is a choice to state in the design doc and to tell the player in the game (a how-to line, a first-screen hint), or it reads as a bug.
+Starting code with these as defaults, and the screen flow: [starters.md](starters.md), "Shooter".
+
+- Enemy bullets are larger and brighter than the player's own (Enter the Gungeon), and the player's hitbox is smaller than the sprite.
+- Holding fire keeps firing; on a phone, aim follows a thumb or assists toward the nearest target.
+- A brief invulnerable window after a hit, shown on the hero, so one mistake is not three.
+- A scarce panic button (Gungeon's blank) for the moment the screen fills.
+
+## Wow catalogue
+
+- A blue ship shooting red squares in a black void is every shooter prototype. Give the world a
+  premise and let it reach the enemies, the guns and the sounds.
+
+Pick one signature and up to three more before building (`npx @funpixel/tools wow` prints what to build and how each is checked; `wow pick <id> --signature` records it in the GDD's `## Wow`):
+
+- `shooter-gun-is-move` (signature): The gun is also how you move, Downwell
+- `shooter-kick-sleep` (juice): Kick, flash and a sleep on kills, Nuclear Throne
+- `shooter-roll-window` (feel): A dodge with a committed tail, Enter the Gungeon
+- `shooter-threat-colour` (presentation): One colour means danger, Enter the Gungeon
+- `shooter-boss-idea` (signature): Each boss one new idea, Hollow Knight
+- `shooter-pick-three` (feel): A choice of three after each room, Hades
+
+## What is each weapon for?
+
+A design question for the GDD: for each gun, upgrade or panic button, the situation where it beats
+the others (range, a crowd, armour, a state it opens or finishes) and what it costs. Two guns that
+answer the same situation are one weapon wearing two looks (our reading). One of our
+hand-iterated games answered it per weapon (a cutter for joints, a rivet driver that pins an enemy
+from range, a scattergun that clears a crowd at the cost of stealth, a knife that finishes a staggered
+enemy). A question, not a mandate; more in skill `funpixel-game-feel`, `references/contact.md`.
+
+## Open choices
+
+A starting contract you may keep or break; write down which in the GDD's genre-card line.
+
+- **Camera.** Top-down follow with a dead zone is the common phone shape; a vertical scroller, a
+  side-on run-and-gun, a fixed arena and a first-person view are all real choices. First person on a
+  phone asks for two thumbs and careful look controls: commit to it or pick another camera.
+- **Body.** One hero or ship.
+- **Core systems.** Move and shoot; aim on a second stick when aiming is the skill, or auto-aim at
+  the nearest threat when movement is. Then choose: a dodge, pickups, weapon swaps, rooms, bosses,
+  upgrades between rooms.
+- **How a run ends.** Death, a boss beaten, a timer or a room count; the picks carry the run.
+- **Orientation.** Landscape for twin-stick; portrait for a vertical scroller.
+
+## Depth and replay
+
+Options with reasons; more in skill `funpixel-game-logic`, its depth reference.
+
+- An arena run of about 5 to 15 minutes (estimated), the first upgrade within 20 to 30 s, then a pick
+  every minute or two; a boss or a timer is the finish line.
+- Endless waves past the boss with the counter still climbing, or a score attack; the best wave or
+  score saved, and one thing unlocked for run two.
+
+## Engineering checks
+
+- **Pool before the first enemy.** Many bullets and enemies want an ECS or plain arrays, pooling, and
+  one draw call per family (Pixi `ParticleContainer`, Three `InstancedMesh`).
+- **Shake on the render offset.** Apply shake to where the camera draws, never to the position it
+  follows, so the follow and the checks read a steady camera (skill `funpixel-game-spine`, its
+  camera reference).
+- **State the checks can read.** Expose `wave` or `time_alive`, `kills`, `level`. One check proves
+  movement through the real stick or key; with automatic fire, one proves `kills` rises with no input.
+
+**Shelf** (libraries that fit, none required): bitecs or miniplex; nipplejs for a second stick; gsap.

package/plugins/codex/skills/funpixel-gdd/references/genre-simulation.md

@@ -0,0 +1,112 @@
+# Simulation, idle and cozy
+
+Farming and life sims, idle clickers, tycoons, cozy sandboxes, little worlds to tend. What the
+genre's best games give players comes first, then the choices open to you, then the checks. The
+creator's brief wins over anything here.
+
+## What players remember
+
+- **The morning after.** Waking up to crops that grew overnight, a shop that earned while they were
+  away, a villager with news. The best sims end a day on a promise and keep it the next session.
+- **The place becoming theirs.** The farm laid out their way, the room decorated, the town grown
+  from one road. Ownership is the reward, so the player's choices must show in the world.
+- **The number that got huge.** In idle games, the jump from thousands to millions to names for
+  numbers nobody has heard of, and the purchase that doubled everything at once.
+- **Small, perfect responses.** The pop of a harvested turnip, the squish of a clicked cookie, a
+  door that chimes. A calm game still answers every touch.
+
+## The look and the world
+
+- Warm light, soft shadows and a time of day that moves: morning, dusk and night each change the
+  palette. Seasons, if the game has them, repaint the world.
+- Things grow and change visibly: a sapling to a tree, an empty plot to a field, a shack to a shop.
+- A cozy world is dense with small detail near the player and quiet at the edges.
+
+## Characters
+
+Neighbours with names, routines and a line of dialogue that changes are what turn a sim into a
+place. Even an idle game gains from a mascot or a manager who reacts to milestones.
+
+## HUD
+
+The clock, the calendar, the money and the energy (or its equivalent) sit in one corner, always
+readable. Numbers format for humans (1.2K, 3.4M) and tick up rather than jump. The screen centre is
+the world, not panels; menus slide in and leave.
+
+## Feel
+
+- Every action answers with a little animation and a sound; tools have weight (a swing, a pause, a
+  result).
+- Time is felt: a day that visibly advances, lamps that light at dusk, a bell at closing time.
+- Calm can move: a sway, a drift, a ticking counter show the world is alive. A still screen chosen
+  on purpose is a valid style too.
+
+## Hits to study
+
+- **Stardew Valley.** Ten game minutes pass in about 7 real seconds, so a day runs about 14 minutes
+  and ends on its own. Look at how the day's end summarises what you earned and how the next
+  morning is the hook, with the calendar showing festivals and birthdays ahead.
+- **Animal Crossing: New Horizons.** Time follows the real clock, so a session is short and daily.
+  Watch how villagers greet you, how the island fills with things the player placed, and how
+  collecting (fish, bugs, fossils) gives a quiet game a shelf to complete.
+- **Cookie Clicker.** One big cookie that squishes on every click, a rate per second always visible,
+  and a golden cookie that appears rarely and briefly for a big bonus. Study how a few rare,
+  well-timed surprises keep an idle loop awake.
+
+## Conventions players bring
+
+What a player of the hit expects without being told. Keep them as defaults; breaking one is a choice to state in the design doc and to tell the player in the game (a how-to line, a first-screen hint), or it reads as a bug.
+Starting code with these as defaults, and the screen flow: [starters.md](starters.md), "Simulation".
+
+- No fail state that throws away an hour: a bad day costs a day's earnings, not the farm (Stardew Valley).
+- The day or cycle ends with a summary of what was made and earned, the natural place to stop or go on.
+- A tool acts on the tile or thing the player faces, highlighted before the press.
+- Time pauses in menus and while reading.
+
+## Wow catalogue
+
+- A grid of identical buildings with coin icons is every idle prototype. Give each tier a look and
+  a joke, and make the next tier something the player wants to see.
+
+Pick one signature and up to three more before building (`npx @funpixel/tools wow` prints what to build and how each is checked; `wow pick <id> --signature` records it in the GDD's `## Wow`):
+
+- `sim-day-ends` (signature): The day ends by itself, Stardew Valley
+- `sim-every-action` (juice): Every action answers, Stardew Valley
+- `sim-calendar` (presentation): What is coming is visible, Stardew Valley
+- `sim-placing-tells` (signature): Placing things tells a life, Unpacking
+- `sim-world-changes` (presentation): The world changes because of you, Animal Crossing
+- `sim-energy` (feel): A day has a budget, Stardew Valley
+
+## Open choices
+
+A starting contract you may keep or break; write down which in the GDD's genre-card line.
+
+- **Camera.** A fixed or gently panning view; a top-down town, an isometric room, a side-on shop
+  counter, or no world at all for a pure idle.
+- **Body.** Often none; an avatar who walks the farm is also classic.
+- **Core systems.** Earn, buy, place, grow. Then choose: a day clock, energy, seasons, residents,
+  collections, prestige (reset for a permanent bonus), offline progress.
+- **How a session ends.** A day turned, a quota met, a season closed, a prestige reset. Many cozy
+  games have no way to lose, and that is fine; what they still need is a session that closes.
+- **Orientation.** Portrait for an idle tapper; landscape or either for a town.
+
+## Depth and replay
+
+Options with reasons; more in skill `funpixel-game-logic`, its depth reference.
+
+- A session is one day, season or contract of about 10 to 15 minutes (estimated), ending on its own
+  with what tomorrow brings on screen.
+- A goal ladder (the next building, the next tier), a best day saved, and a scenario or sandbox mode
+  opened by the first goal.
+- Tune the economy with a headless bot before art: a pacing sweep finds a 65-minute late game before
+  a person does (skill `funpixel-game-logic`).
+
+## Engineering checks
+
+- **Persistence is the game.** Save on change and resume exactly where the player left. Offline
+  progress is computed on load, capped and shown in a welcome-back card: our studio's first idle
+  paid out a whole city for one night away.
+- **State the checks can read.** Expose `currency`, `rate`, and `day` or `level`. One check proves
+  the core tap raises `currency` through a real `pointer`; one proves a purchase raises `rate`.
+
+**Shelf** (libraries that fit, none required): `SaveManager`; yuka for agent routines; gsap.

package/plugins/codex/skills/funpixel-gdd/references/genre-strategy.md

@@ -0,0 +1,116 @@
+# Strategy
+
+Tower defense, small turn-based tactics, network and route builders, tycoon loops, base builders.
+What the genre's best games give players comes first, then the choices open to you, then the
+checks. The creator's brief wins over anything here.
+
+## What players remember
+
+- **The plan that held.** The last wave breaking on a line of towers they built, a turn where every
+  unit moved and nothing was wasted. Strategy's peak is watching a decision pay off.
+- **The save at one life.** A leak stopped by the last tower, a city saved by pushing an enemy into
+  another. Near-disasters are the stories.
+- **The board growing under their hands.** A metro map that sprawled, a maze of towers that became
+  a machine. The final board is a picture of the player's thinking.
+- **Knowing what is coming.** Seeing the next wave or the enemy's intent and outwitting it. Good
+  strategy is fair because it is readable.
+
+## The look and the world
+
+- A board that reads at a glance: terrain types by colour and shape, paths clearly paths, one
+  threat colour reserved for threats.
+- The world has a theme that gives the units their jokes and their silhouettes (knights and orcs,
+  mechs and bugs, trains and stations).
+- Minimal can be beautiful: a clean diagram-like look (Mini Metro) is a style, not a lack of one.
+
+## Units and characters
+
+Each unit type has one silhouette, one colour and one job. Heroes, commanders or a narrator who
+comments on the battle give a board game a voice. Enemies should look like what they do (fast ones
+lean forward, armoured ones are bulky).
+
+## HUD
+
+Resources and lives in one corner, the next wave or turn indicator where the eye returns between
+decisions, and build or command buttons along the thumb edge. Tooltips and range rings appear on
+touch, not all the time.
+
+## Feel
+
+- Placement is loud: a ghost under the finger that turns green or red, a snap to the grid, a thud
+  and a puff of dust when it lands, a refusal sound when it cannot.
+- Upgrades change the look of a tower or unit, not only a number.
+- Time controls (pause, speed up) and a clear "start the wave" button put the player in charge of
+  tempo.
+
+## Hits to study
+
+- **Kingdom Rush.** Each tower has a clear role and branches into specialised upgrades that look
+  different; a hero unit you move gives an active verb in a placement game. Look at the early-call
+  button, which pays extra for starting the next wave sooner and turns confidence into reward.
+- **Into the Breach.** Every enemy shows exactly what it will do next turn, on a small grid, and your
+  tools mostly push and redirect rather than kill. Study how perfect information makes each turn a
+  puzzle with several clever answers, and how a whole battle fits on one phone-sized board.
+- **Mini Metro.** One new piece of pressure at a time (a station, a shape, a crowded line), a small
+  upgrade choice on a weekly cadence, and a soundtrack generated from the network itself, so growth
+  and strain are heard.
+
+## Conventions players bring
+
+What a player of the hit expects without being told. Keep them as defaults; breaking one is a choice to state in the design doc and to tell the player in the game (a how-to line, a first-screen hint), or it reads as a bug.
+Starting code with these as defaults, and the screen flow: [starters.md](starters.md), "Tactics".
+
+- The enemy's next move is shown before the player commits (Into the Breach's attack previews).
+- One take-back: Into the Breach allows one turn reset a battle; a misclick is not a lost campaign.
+- Full information on hover or tap: range, damage and who acts next.
+- A turn ends on the player's say, never on a timer, unless the timer is the design.
+
+## Wow catalogue
+
+- Three towers named Arrow, Cannon and Magic on a grass path is every tower-defense prototype. Tie
+  the units to a world with its own logic.
+
+Pick one signature and up to three more before building (`npx @funpixel/tools wow` prints what to build and how each is checked; `wow pick <id> --signature` records it in the GDD's `## Wow`):
+
+- `strategy-telegraph` (signature): Every attack shown before your turn, Into the Breach
+- `strategy-one-frame` (presentation): The whole battle in one frame, Bad North
+- `strategy-upgrade-shape` (juice): An upgrade changes the silhouette, Kingdom Rush
+- `strategy-reset` (feel): One reset per battle, Into the Breach
+- `strategy-paced-choice` (feel): One upgrade a week, Mini Metro
+- `strategy-map-twist` (signature): Each map one twist, Kingdom Rush
+
+## Open choices
+
+A starting contract you may keep or break; write down which in the GDD's genre-card line.
+
+- **Camera.** A fixed board, or pan and zoom for a large map; isometric and top-down both work.
+- **Body.** No avatar by default: a brief that says "I hold the pass" names the player's role,
+  not a character who walks around. A single hero unit is an option.
+- **Core systems.** Place and upgrade between rounds, or command units turn by turn. Then choose:
+  waves, a route network, resources, research, terrain effects, a boss.
+- **How a match ends.** A final wave, a day target, a quota, or the network or base collapsing;
+  a win screen and a way back in. Between rounds nothing attacks; the player decides when the next
+  starts.
+- **Real time or turns.** A real-time base builder asks for sustained attention; on a phone,
+  short rounds or turns often fit better. Your call.
+
+## Depth and replay
+
+Options with reasons; more in skill `funpixel-game-logic`, its depth reference.
+
+- A match of about 5 to 10 minutes on a phone (estimated), with the first real decision inside 30 s.
+- The ramp is the wave list: each wave adds something new, and the player sees it before it starts.
+- Difficulty tiers or a second map opened by the first win, a best score per map saved, and a daily
+  seeded scenario.
+
+## Engineering checks
+
+- **A silent failed placement** is this genre's most common bug: every refused placement shows why
+  (the red ghost, a sound, a short reason).
+- **Balance with a bot that plays well** before tuning by hand; a bot that places at random proves
+  nothing (skill `funpixel-game-logic`).
+- **State the checks can read.** Expose `wave` or `day`, `gold`, `lives`. One check proves a
+  placement through a real tap (`towers` rises); one proves a wave runs with no input.
+
+**Shelf** (libraries that fit, none required): easystarjs for grid paths; bitecs for many units;
+`SaveManager` for a tycoon.

package/plugins/codex/skills/funpixel-gdd/references/genre-survival.md

@@ -0,0 +1,122 @@
+# Survival
+
+Survivor-likes (a horde, a timer, upgrades), wave defence, and resource survival (gather, craft,
+last the night). What the genre's best games give players comes first, then the choices open to
+you, then the checks. The creator's brief wins over anything here.
+
+## What players remember
+
+- **The screen full of enemies, and the build that melts them.** Minute one is a trickle; minute
+  twenty is a wall of bodies evaporating around a character who has become a storm. The distance
+  between those two pictures is the whole game.
+- **The level-up that changed everything.** An evolution, a synergy, a pick that made two weapons
+  into one monster. Players retell their builds.
+- **The chest.** The rarest reward gets the longest ceremony, and players remember the jackpot.
+- **The first night.** In resource survival: the light going, the sounds changing, the fire you
+  built just in time. Dread is a feeling to design, not a side effect.
+- **One more run.** Falling short of the clock by seconds is the reason to go again.
+
+## The look and the world
+
+- The hero reads against any crowd: a brighter value, an outline, a colour no enemy uses.
+- Enemies come in families, each with one silhouette and colour, so a swarm reads as types.
+- Pickups glow or pulse; the floor stays darker and quieter than everything on it.
+- For resource survival, day and night are two different palettes, and night is a real threat.
+
+## Characters
+
+Pick-able heroes with one starting weapon and one quirk each give a survivor-like its roster.
+Bosses announce themselves (a warning, a sound, a camera nudge). A merchant between waves can have
+a face and a line.
+
+## HUD
+
+A clock or wave counter the player always sees, a health bar that reads at a glance, an XP bar
+across an edge, and the weapons owned as small icons. Level-up and shop screens pause the world and
+own the whole screen while they are up.
+
+## Feel
+
+- Every hit sparks, every kill pops, and the XP gems vacuum toward the hero with a rising chime.
+- The level-up is a punctuation mark: freeze, three cards, one tap, resume with a burst.
+- A low-health cue (a heartbeat, a red edge) tells the player to change what they are doing.
+- Upgrades are visible in play (a bigger aura, more projectiles), never a hidden percentage.
+
+## Hits to study
+
+- **Vampire Survivors.** A known finish line (the 30-minute mark) makes a run that falls short feel
+  like a near miss. Look at how the chest opening escalates past every other pickup, how weapon
+  evolutions reward two choices made together, and how late-game screens look nothing like the
+  first minute.
+- **Brotato.** 20 waves; the first lasts 20 s, each adds 5 s up to 60 s, the last (a boss) runs
+  90 s, and a shop sits between waves. Study how a published schedule paces a run, and how short
+  early waves put the first shop inside 20 seconds.
+- **Don't Starve.** Night falls and without light something unseen attacks, so fire is the first
+  thing a new player learns to fear losing. Look at the hand-drawn, gothic look, the sanity that
+  bends the world's picture, and how seasons change what each day needs.
+
+## Conventions players bring
+
+What a player of the hit expects without being told. Keep them as defaults; breaking one is a choice to state in the design doc and to tell the player in the game (a how-to line, a first-screen hint), or it reads as a bug.
+Starting code with these as defaults, and the screen flow: [starters.md](starters.md), "Survivors-like".
+
+- Auto-fire (Vampire Survivors, Brotato): the player's verb is movement and choice; attacks happen on their own.
+- A level-up pauses play and offers three or four upgrades to pick from; XP drops fly to the player inside a pickup radius.
+- A run has a known length and an ending (Vampire Survivors' 30-minute clock, Brotato's 20 waves), with the boss or reaper as the last beat.
+- The swarm builds up gradually: the first minute is safe while the player learns to move.
+
+## Wow catalogue
+
+- Green zombies on grass around a soldier is every survivor prototype. Pick a world whose enemies
+  have a reason to swarm (bees, ghosts, bureaucrats, weeds).
+
+Pick one signature and up to three more before building (`npx @funpixel/tools wow` prints what to build and how each is checked; `wow pick <id> --signature` records it in the GDD's `## Wow`):
+
+- `survival-chest` (signature): The chest that spins, Vampire Survivors
+- `survival-vacuum` (juice): Every gem flies to you at once, Vampire Survivors
+- `survival-wave-clock` (presentation): A clock with known stops, Brotato
+- `survival-evolution` (signature): Two items become one, Vampire Survivors
+- `survival-first-upgrade` (feel): The first upgrade inside 20 s, Brotato
+- `survival-late-spectacle` (presentation): Minute ten looks nothing like minute one, Vampire Survivors
+
+## What is each weapon or tool for?
+
+A design question for the GDD: for each weapon, tool or upgrade, the situation where it beats the
+others (a crowd, range, the night, a resource it saves) and what it costs. An upgrade that answers
+no new situation is a bigger number rather than a choice (our reading). One of our
+hand-iterated games answered it per weapon (a cutter for joints, a rivet driver that pins an enemy
+from range, a scattergun that clears a crowd at the cost of stealth, a knife that finishes a staggered
+enemy). A question, not a mandate; more in skill `funpixel-game-feel`, `references/contact.md`.
+
+## Open choices
+
+A starting contract you may keep or break; write down which in the GDD's genre-card line.
+
+- **Camera.** Top-down follow is usual; side view and a fixed arena work too.
+- **Body.** One hero; a camp or base to defend is also a body of sorts.
+- **Core systems.** Move and survive, with automatic attacks or aimed ones. Then choose: level-up
+  picks, a shop between waves, evolutions, gathering and crafting, a day-night cycle, meta unlocks.
+- **How a run ends.** Death, or the clock or the last wave survived; a summary (time, kills,
+  nights) and instant retry.
+- **Orientation.** Portrait or landscape; a one-thumb move stick suits either.
+
+## Depth and replay
+
+Options with reasons; more in skill `funpixel-game-logic`, its depth reference.
+
+- A wave run is about 17 minutes on Brotato's schedule; a resource day about 14 minutes (Stardew
+  Valley's clock). A known finish line makes falling short the reason to go again.
+- The clock is always visible, and nights or waves grow longer and harder on a schedule the player
+  can see coming.
+- Waves survived beside the best, an endless mode past the last wave, a meta unlock through
+  `SaveManager`.
+
+## Engineering checks
+
+- **The horde is a frame-budget problem first.** Pool enemies and projectiles, draw each family in
+  one call (Pixi `ParticleContainer`, Three `InstancedMesh`) and spread a spawn wave across frames so
+  it never hitches (the shooter card has more).
+- **State the checks can read.** Expose `night` or `wave`, `hp`, `resources`. One check proves
+  gathering or an attack through real input; one proves `night` or `wave` advances with no input.
+
+**Shelf** (libraries that fit, none required): seeded noise terrain and scatter; bitecs; gsap.

package/plugins/codex/skills/funpixel-gdd/references/in-the-loop.md

@@ -0,0 +1,106 @@
+# Keep the person in the loop
+
+A long build that shows nothing until it ends feels broken, however good the game is. The owner,
+after a 100-minute run: "waiting is too long; the feedback loop is important; asking in between,
+showing progress". The products people trust during long runs share four habits: something real
+on screen early, evidence at each milestone, questions only at real forks, and a ping only when the
+run needs the person or is done. The ones people complain about nag, report progress they cannot
+show, or spend quietly in loops.
+
+## Where the person is
+
+**In this chat.** You are their copilot: plan with them here, show them the game here, ask them
+here. Three things carry the game between you:
+
+- **The GDD** (`design/GDD.md`): the plan and the record. Its `## Where we are` sits on top and is
+  updated every round: the round and what it did, each target frame beside the game's capture at
+  the same moment (picture links), the biggest gap left and the next step, the preview link, the
+  price approved and the credits spent, what the owner asked last and what was done with it. A page
+  made apart from it is linked in `## Linked pages` with what it shows and what it is for.
+- **The preview**: the running game, side by side with the chat, reloading on every save; open it beside the chat where they are: your host's own browser when it has one (Cursor's, Codex's), else `npx @funpixel/tools dev --open` (the system browser, in its own tab). A picture or a clip opens the same way (the host's viewer, else `npx @funpixel/tools open <file>`).
+- **The record** (`progress card`, `progress answer`, `note`): what happened, kept in `.funtools/`
+  so a later session and the hand-back read it. It is for the kit, not a page for the person.
+
+`FUNPIXEL_NOTIFY_URL` (an ntfy.sh topic, a Slack or Discord webhook; free, optional) is pinged only
+on "needs you" and "done", for a person who stepped away.
+
+## The cadence: they watch, they steer
+
+The owner follows the build as it happens, the way a person watches a remote session: a short
+status after every step, with a picture, so they can say "not that" before it is built on.
+
+- **After every step** (an asset landed, a build, a fix, a playtest): two or three lines in the
+  chat (what changed, what it shows, what is next) with a fresh `funtools capture` of the BUILD, or
+  the asset under the game's light. Never a wall of text, never only "done".
+- **First visible result about 10 minutes in**: a built frame on the real camera, with the preview
+  link.
+- **Every round** (`flow round` closes it): the captures beside their targets, the evidence (a
+  score, a blind player's verdict), what is next, credits spent; the same in the GDD's
+  `## Where we are`, recorded with `progress card --shot last`.
+- **Stuck:** the third try on one gate becomes a question: skip it, cut it, or keep going,
+  instead of spending on in a loop.
+
+**Their word steers at any time.** A message mid-build outranks the step you were on: answer it,
+fold it in, say what changed. The lock means "good, let's build, unless I say otherwise": a new
+direction (another place, more levels, a different story) goes into the GDD as a new version,
+shown in the chat, and their yes locks it again (`flow ask`, `flow agree --by owner`).
+
+A target picture or a concept is never a progress frame: say "a picture, not the build".
+
+## Three reveals, made as moments
+
+The game has three moments the owner remembers. Stage them; never report them.
+
+1. **The key art.** Opened big (the host's viewer, else `npx @funpixel/tools open <file>`), with the
+   brief's one line as its caption and one line on what it promises: "Ren on Calder's ridge at
+   dusk: the load sways, the light is the only warmth for miles."
+2. **The first playable.** A 10 to 15 second clip of real play (`npx @funpixel/tools reel --seconds
+   12 --viewport desktop`, opened), the game open beside the chat, and "try this first: <the one
+   thing that feels best>". Then let them play before you say anything else.
+3. **Each new chapter.** Its clip beside its target frame, and one line on what it adds.
+
+## The voice: the game's words, never the kit's
+
+Speak to the owner about the game: places, people, the verb, how it feels. Never stage numbers,
+gates, verdict commands or file counts unless they ask ("stage 2 of 16: never verified" is the
+kit talking; "the canal level runs, but the wind does not push you yet" is the game). The kit's
+words stay in the record and the GDD. End every status on what comes next, in the same words:
+"next: the canal at night, where the wind starts pushing", never "next step: core test".
+
+## Questions only at forks
+
+| Fork | When | Example |
+|---|---|---|
+| taste | a choice the plan left open; a target the build cannot reach | "Keep the noon palette, or try dusk?" |
+| spend | an expensive route the plan never named, or out of credits (a pause: they top up) | "Out of credits with the tug's rig still to make: top up, and I go on" |
+| scope | cutting or adding a mechanic, content or a performance cut | "Cut the second tower, or keep it?" |
+
+Everything else is yours to decide: say it in one line in the chat and the GDD, never as a
+question. Ask in the chat and record the answer in their words (`progress answer <Q> <option>
+"<their words>"`). Under autonomy `go`, decide, say what and why, and go on. Never end the session
+waiting on yourself.
+
+## A round, recorded
+
+```
+npx @funpixel/tools capture --view playing --viewport phone
+npx @funpixel/tools progress card --stage slice --shot last \
+  --line "the slice plays: drag swings the cradle, a wiped window scores" \
+  --evidence verify.json --next "the pots and the loss, about 20 min" --spent 140 \
+  --decision "no jump: the verb is the swing"
+```
+
+Each card picks up the owner's new notes and answers, and writes the dev log's `step` line for you.
+At the end, `progress report` is the hand-back's spine: what plays, what is out, every fallback still
+in the game, what was decided without the person, and the cost.
+
+**The spend is the account's.** With a key, every card reads the account's usage since the run began
+(`--spent account`); never post your own tally as the cost.
+
+**A note closes on evidence that fits it.** The owner's note on the build closes only on evidence of the
+BUILD made after it (a capture, a walk/life/boxes record, a score), never a picture in `design/`. A design
+note (the plan, its open questions) closes on a commit made after it that changes the GDD or `design/`.
+A note that HOLDS the stage ("keep designing, do not start the build", "not signed off yet") is the owner's:
+record it with `note add "<their words>" --hold`. The kit shows it as waiting on the owner, never as a step,
+and no evidence closes it; work on what it names. The owner's own word closes any note: `note close N1 --by
+owner --force "their words"`, run when they say so.