@funpixel/tools 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,159 @@
+# Platformers, runners and maze chases
+
+Precision platformers, metroidvanias, one-tap runners, and arcade maze chases (Pac-Man's family).
+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 jump that felt right.** A platformer is loved or dropped on how its main verb feels in the
+  first ten seconds: the lift, the hang at the top, the landing. Everything else is built on it.
+- **The screen they finally beat.** Death after death, then a run where every input landed. The
+  best games make that loop quick and kind, so frustration turns into pride.
+- **The hero's silhouette.** Madeline's hair, the Knight's horned mask and cloak, Ori glowing white
+  against a painted forest. Players draw these from memory.
+- **A world that opens.** A locked door remembered for an hour and finally opened, a shortcut back to
+  the start, a new area that looks like nothing before it.
+- **In a chase: the turn that saved them,** the train of ghosts eaten in one sweep, the near miss in
+  slow motion.
+
+## The look and the world
+
+- The hero is the clearest thing on screen: a value or colour nothing else uses, readable at phone
+  size mid-jump.
+- Hazards look dangerous (spikes, glow, colour reserved for harm); safe ground looks solid.
+- Layers of parallax with a strong foreground and a quiet play layer give depth without clutter.
+- Each area has its own palette, music and one mechanic, so the world is a set of places, not tiles.
+
+## Characters
+
+A hero with a body language (a squash on landing, a stretch on the jump, hair or a scarf that trails),
+and enemies whose shapes say how they move. A metroidvania's cast (a map seller, a rival, a lonely
+boss) gives the exploring a reason.
+
+## HUD
+
+Small and at the edges: hearts or masks, a collectible count, a timer for speed runs. Precision
+platformers often hide the HUD entirely during play; show it on a pause or a checkpoint.
+
+## Feel
+
+- The jump is read on `pointerdown` or keydown and applied the same frame. A held jump rises higher;
+  a tap hops.
+- Forgiveness is part of the verb, not polish: coyote time (a jump just after leaving the edge still
+  counts), a jump buffer (pressed just before landing still fires), a small nudge around a corner
+  the head clips.
+- Landing squashes, jumping stretches; dust at the feet; a short freeze and a directional shake on a
+  dash.
+- Death reads (a held frame showing what hit you) and respawn is fast.
+
+## Hits to study
+
+Numbers in body heights and seconds, so they carry to any art scale.
+
+- **Celeste** (from its published player code). Top run speed is about 8 body heights a second,
+  reached in under 0.1 s; air control about two thirds of ground control. A held jump rises about
+  2.5 body heights in about 0.35 s, with half gravity near the apex while held. Coyote time 0.1 s,
+  buffered presses about 80 ms, a corner nudge of about a third of a body. The dash covers about 3
+  bodies in 0.15 s, opens with a 50 ms freeze and shakes along its direction. The sprite stretches
+  on the jump and springs back. Respawn takes about a second. Its designer's word for the windows:
+  kind, even though the game is hard.
+- **Hollow Knight.** Watch a hit taken: the frame freezes and darkens, the Knight recoils and blinks
+  while invulnerable. A strike flashes the enemy and pushes both apart; striking downward bounces
+  the hero, which turns enemies into platforms. Four core developers made more than 150 enemy
+  designs.
+- **Downwell** (the phone shape). Three inputs (left, right, jump); the gunboots fire downward in the
+  air, their recoil slows the fall and their ammo refills on landing, so one verb moves and attacks.
+  Platforms were cut for floating enemies to keep the player falling.
+
+## Maze chase and arcade score attack
+
+A top-down chase on a tile grid or a small arena: a route under pressure, the safe line weighed
+against the greedy one every second.
+
+- **Pac-Man Championship Edition DX** (the reference hit). Sleeping ghosts wake as you pass and fall
+  in behind as a train; a power pellet turns the whole train into one long eat, the signature payoff.
+  Slow motion on a near miss gives a last chance to turn. A bomb sends every ghost home but lowers
+  speed and the multiplier, so the panic button costs score. Score Attack runs are 5 or 10 minutes.
+- **Readable at phone size.** Hero and chasers at least 28 px (about 1.2 tiles) on a 390 px phone;
+  pickups stand off the floor by value; each chaser keeps one colour and one behaviour, and the
+  frightened state is one colour that also stands off the floor.
+- **Escalation inside a run,** not only between levels: speed climbs as the player eats, new chasers
+  join mid-run, the field changes on a schedule the player can see. Critics called a chase whose only
+  ramp was "the next level is faster" a reskin.
+- **A payoff ladder whose top rung looks like nothing else** (skill `funpixel-game-feel`, its
+  payoffs reference): chasers eaten in one power-up double in value; the rare top rung has its own
+  sound, a longer freeze and a bigger number placed beside the hero, never over it.
+- **Near misses are drama:** a chaser within about a tile that does not catch drops time to about a
+  third for 0.3 to 0.5 s (skipped under reduced motion), with a sound. A catch holds about 0.3 s on
+  both faces, and play resumes in under 2 s.
+- **Actors move by state:** a two- to four-pose walk stepped by speed, a squash on each turn, eyes
+  toward travel; chasers show hunting, frightened, returning and asleep as different poses, not only
+  a tint (skill `funpixel-art`, its animation reference). Music layers or tempo rise with speed.
+
+## 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), "Platformer and Maze chase".
+
+- A late jump still counts and an early press is kept (coyote time and a jump buffer, about 0.1 s each in Celeste's player code); a held jump goes higher than a tap.
+- Death costs seconds, not minutes: back at the last checkpoint in about a second, the checkpoint just before the hard part.
+- Maze chase: a turn pressed before the opening is queued and taken at the next corner (Pac-Man); a swipe never has to land on the exact frame.
+- Downwell: landing on an enemy is safe and refills the gun, so the risky move pays.
+
+## Wow catalogue
+
+- A square hero on green tiles under a blue sky is every platformer prototype. Give the world a
+  premise and let it shape the hazards.
+
+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`):
+
+- `platformer-dash-reads` (signature): A dash the hero wears, Celeste
+- `platformer-forgiving-jump` (feel): The jump that forgives, Celeste
+- `platformer-pogo` (signature): Bounce off what hurts you, Hollow Knight
+- `platformer-stretch` (juice): Stretch up, squash down, Celeste
+- `platformer-death-beat` (juice): A death that costs a second, Celeste
+- `platformer-silhouette` (presentation): The hero is the clearest shape, Ori and the Blind Forest
+
+## Open choices
+
+A starting contract you may keep or break; write down which in the GDD's genre-card line.
+
+- **Camera.** A side view that follows with a dead zone and look-ahead; fixed single-screen rooms
+  (Celeste) suit precision; a top-down fixed field suits a maze chase.
+- **Body.** An embodied hero.
+- **Core systems.** Jump (or flip, dash, fall), then choose: combat, collectibles, abilities that open
+  new routes, checkpoints, a timer.
+- **How a run ends.** Death or the end of a level or room; best distance or time is run two's reason.
+- **On phones.** One-tap timing, a lane runner, or a maze steered by a swipe anywhere that queues
+  the next turn hold up well (a d-pad under a maze repeats the swipe and halves the maze); short
+  rooms with two verbs may earn a pad; precision platforming on a virtual stick is harder to make feel good, so tune it
+  with care if you choose it. Portrait for one-tap runners and mazes, landscape for levels.
+
+## Depth and replay
+
+Options with reasons; more in skill `funpixel-game-logic`, its depth reference.
+
+- A precision platformer runs a room per attempt (20 to 60 s, estimated) with respawn in about 1 s;
+  8 to 12 rooms make a first sitting. Collectibles off the main line give the skilled player a
+  second route through the same rooms.
+- A maze chase is a timed score attack (5 or 10 minutes): the maze refills or changes on a visible
+  schedule, speed and the multiplier climb with eating, and the best score per mode is saved. Critics
+  preferred a ten-minute score attack to a single 1:38 maze.
+
+## Engineering checks
+
+- **Fixed-step physics** (an accumulator) keeps a jump arc the same on a 120 Hz phone and a
+  throttled tab.
+- **Reach is proven:** every gap is within the jump and every spawn stands on ground, checked in
+  `__FPX_SELFTEST__` (skill `funpixel-game-logic`). Falling out of the world respawns the hero.
+- **Maze turns:** a turn pressed before an opening is held and taken when it arrives (about 0.2 s
+  early is normal); a reverse is instant.
+- **State the checks can read.** Expose `distance` or `score`, `alive`, and the hero's `y`. A jump
+  check presses the real key or taps (`subject: player`, `axis: "y"`, `expect: decreases`,
+  since screen y grows downward). A chase: `score`, `lives` or `time_left`, the payoff rung, `x`/`y`,
+  `speed`, with checks that real keys steer, eating scores, the power-up turns the chasers and a
+  catch costs a life.
+
+**Shelf** (libraries that fit, none required): hand-rolled physics; gsap for death and restart;
+matter-js only for a physics-toy variant.

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

@@ -0,0 +1,145 @@
+# Puzzle games
+
+Board puzzles (merge, drop, sort, match, place, slide), daily boards, logic grids, and spatial
+puzzles you walk through. 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 aha.** The moment a known tool is used a way they had not tried, and the solution was in
+  plain sight the whole time. A great puzzle makes the player feel clever, not lucky.
+- **The chain.** A merge that set off three more, a clear that cascaded. In score puzzles, the
+  biggest chain is the story of the run, and the rare top piece is the trophy.
+- **Pieces with personality.** Tiles with faces that grow in character as they grow in value; a
+  fruit that finally becomes the watermelon.
+- **The last-second save.** One slot left, the next piece shown, and it fits.
+- **An impossible place.** A staircase that loops, a room seen through a portal, a world that turns
+  when you turn it.
+
+## The look and the world
+
+- The board is the stage: it fills most of the screen, and everything off it is quiet. A small board
+  was the main layout defect our studio measured in its puzzle games.
+- Pieces read by shape as well as colour, so the game works for colour-blind players and at a glance.
+- A world around the board (a kitchen, a garden, a jar, a tide pool) turns abstract rules into a
+  place. Monument Valley shows how far a puzzle's look can go: every frame is composed like an
+  illustration.
+
+## Characters
+
+Faces on the pieces, a creature who reacts to your moves, a silent guide who walks the path you
+built. Warmth on abstract pieces costs little and is remembered.
+
+## HUD
+
+Score, moves left or the goal, and the next piece: small, in one band, away from the board. The
+clear or merge gets its number near where it happened, never over the next move.
+
+## Feel
+
+- Placement: a ghost under the finger, a snap on release, a short settle (about 80 to 120 ms).
+- The clear is the loudest moment in the game: the biggest effect, and a sound whose pitch rises
+  with each link of a chain.
+- Undo and instant restart make experiments cheap, and experimenting is how puzzles are enjoyed.
+
+## Hits to study
+
+- **Suika Game.** 11 fruit tiers from cherry to watermelon; only the five smallest are ever dropped,
+  and you see the next one. Physics makes every drop a slightly new board, and the watermelon is
+  rare enough to be the story of a run.
+- **Threes.** Built over 14 months for one rule (1 and 2 make 3, then equal tiles double). Mechanics
+  were tried and cut along the way (hunger, arrows, holes, walls). Look at how the tiles gain faces
+  and personality up the ladder, and how much of the design is subtraction.
+- **Baba Is You.** Each area puts one new rule-word in the spotlight, with known words as supporting
+  cast. Undo is unlimited and restart instant, so trying something is free.
+- **Monument Valley 2** (the highest score our calibrated panel has given any hit: 8.60 overall, 9.30
+  look, from its store media) and **Portal** (for spatial chambers, below): one new idea per chapter or
+  chamber, no text tutorial, the solution visible before it is understood.
+
+## 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), "Merge or drop".
+
+- Drop and merge (Suika): the piece hangs over a drop line that shows where it will fall, and the next piece is shown.
+- Aim and bounce (Peggle): the aim guide shows the first path, and the free-ball bucket moves along the bottom every shot; it never runs out. A capped helper read as a bug twice in one of our games.
+- A wrong move is cheap: undo or an instant restart of the level, and a solved state that is unmistakable.
+- No clock on thinking in a pure puzzle (Monument Valley has no fail state); pressure comes from a board that fills, not a timer.
+
+## Wow catalogue
+
+- Coloured squares on a grey grid is every puzzle prototype. Give the pieces a material, a world
+  and faces.
+
+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`):
+
+- `puzzle-top-rung` (signature): The rare top of the ladder, Suika Game
+- `puzzle-chain-pitch` (juice): Each link a note higher, Puyo Puyo
+- `puzzle-faces` (presentation): Pieces with faces, Threes!
+- `puzzle-undo` (feel): Undo without shame, Baba Is You
+- `puzzle-one-word` (signature): One new rule per level, Baba Is You
+- `puzzle-score-sings` (presentation): Play makes the music, Mini Metro
+
+## Spatial puzzle chambers (an avatar in a room)
+
+Portal, Monument Valley and The Witness are puzzles you walk through. What differs from a board:
+
+- **The chamber is the unit.** Each debuts one element, then asks for it in a new combination; a
+  chapter spends itself on one trick. A chamber that tells you every step is a tutorial: one game's
+  first version cleared in 1:11 with a hint per step, and critics called it "a tutorial, not a
+  puzzle". The aha is a known tool used a new way: the exit seen through the portal, the cube
+  carried through it, the switch reachable only from the far side.
+- **Teach, then step back.** Show the first use; after it, let the room speak (a colour-matched
+  plate and gate, light on what matters, the goal in view) and hint only when the player stalls.
+- **Readable space.** The player always knows which side of a portal they are on (a different light
+  or colour per room), where a carried object will land (a ring on the floor before the drop) and
+  when something is in reach (it answers before the tap). These were our blind players' three
+  medium findings on that game.
+- **Controls.** First person, or a fixed three-quarter view with tap-to-move (Monument Valley). Held
+  sideways: move on the left thumb, look on the right, one action button of at least 44 px, and the
+  two thumbs never share a zone.
+
+## Open choices
+
+A starting contract you may keep or break; write down which in the GDD's genre-card line.
+
+- **Camera.** A fixed board view for board puzzles; a moving or rotating camera for spatial ones.
+- **Body.** No avatar for boards; an avatar or a guided figure for spatial puzzles.
+- **Input on a phone.** A slide or step on a grid (Threes, ice and block sliders) is a swipe
+  anywhere on the board with the move previewed under the finger, arrow keys on a keyboard. An
+  on-screen pad fits as an accessibility setting: it repeats the swipe and takes the screen the
+  board needs (skill `funpixel-mobile-ui`, step 6).
+- **Core systems.** Place, swap, merge, sort, push, rotate. Then choose: authored levels, a
+  generator, physics, a daily board, a move budget, a timer.
+- **How a run ends.** No legal move, a goal met, a move budget spent, an exit reached; never a
+  frozen board.
+- **Orientation.** Portrait for boards; landscape for walk-through chambers.
+
+## Depth and replay
+
+Options with reasons; more in skill `funpixel-game-logic`, its depth reference.
+
+- A drop or merge run lasts until the container overflows, 3 to 10 minutes (estimated); a level set
+  places its hard levels on a rhythm the player can feel; a daily seeded board gives a reason to
+  return.
+- Pressure from the first drops: a small container or a partly filled seeded start, so the first
+  minute already asks where things go. Critics called one game's early basket "too sparse, no
+  packing pressure" beside Suika Game.
+- The best score per mode saved, the next piece shown, restart in one tap.
+
+## Engineering checks
+
+- **The generator is the game.** Generated logic boards use a seeded random source and are proven
+  solvable (for example, generated backwards and checked for solver depth; skill
+  `funpixel-game-logic`). Authored levels need a real solution; endless and physics puzzles need
+  reachable goals.
+- **Measure difficulty with a bot that plays like a sharp player**; a random bot wins everything
+  and proves nothing.
+- **Spatial resets.** A reset returns the avatar and every movable object safely; an object that
+  falls out of the world or through a portal edge comes back (no softlock).
+- **State the checks can read.** Boards: `board_fill` (0 to 1) and `cleared`, with one check proving
+  a clear through a real drag (`pointer` on a piece). Chambers: the avatar's room, what it holds, each
+  switch and gate and a `solved` count, with checks that walk the real route with the stick.
+
+**Shelf** (none required): gsap for transitions; a seeded RNG for reproducible boards; a physics
+engine only when physical interaction is part of the game.

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

@@ -0,0 +1,137 @@
+# Racing and flight
+
+Kart racers, arcade drivers, drift games, time trials, endless roads, top-down racers, flyers. What
+follows is what the genre's best games give players, then the choices open to you, then the checks
+that catch this genre's quiet bugs. The creator's brief wins over anything here.
+
+## What players remember
+
+- **The corner they nailed.** A drift held through a bend that pays out a boost, the line that
+  shaved a tenth, the jump taken flat out. Racing is remembered one corner at a time, so a track
+  is a set of corners worth naming, not a loop of road.
+- **Speed you can feel in your stomach.** The world streaming past close to the car, the camera
+  pulling back as the engine climbs, the road dipping so the next section appears all at once.
+- **The overtake and the near miss.** Passing a rival on the last straight, clipping past traffic,
+  a shell or a rival that almost got you. Drama comes from other bodies on the road.
+- **A place with a mood.** A coast road at sunset, a neon city at night, a toy kitchen seen from
+  a mouse-sized car. The track is a trip somewhere, and the good ones change scenery along the way.
+- **Beating your own ghost.** The best time you finally broke, the medal that went from silver to
+  gold after the tenth try.
+
+## The look and the world
+
+- A strong horizon and a sky with a time of day do more for mood than detailed trackside props.
+- Scenery close to the road sells speed (posts, trees, arches, crowds); open fields read slow.
+- Each track or section has its own palette and one landmark you see coming from far away.
+- The road reads first: kerbs, a racing line or lane paint, a clear edge where the grip ends.
+
+## Vehicles and drivers
+
+- The vehicle is the hero: a strong silhouette from behind (the camera sees its rear most of the
+  time), a colour that owns it, and a body that leans, squats and bounces with the physics.
+- A driver visible in the seat, or a face on the kart, buys character for very little.
+- Rivals each keep one colour and one personality in how they drive (the bully, the careful one).
+- **Keep the pack in view** (one racer, Oct 2026). Draw rivals at true scale out to about 60 m
+  and compress the distance beyond it, so the pack stays on screen while contact up close reads
+  exactly. A bunching rule tuned for the chase keeps it there: a racer more than 10 m from the
+  pack's mean distance is pulled toward it, 0.05 m/s per metre beyond, at most 0.8 m/s, ahead or
+  behind alike; one switch, turned down if testers call it rubber-banding. Frames worth judging
+  start from 3rd–6th place with 2–4 rivals at 15–80 m, at least 10 m or a lane apart so
+  silhouettes never merge, and at most three name tags, faded by distance.
+
+## HUD
+
+Racing HUDs are small and live at the edges: position as a big number, lap or distance, a
+speedometer or boost gauge, and a mini-map or progress strip. The screen centre belongs to the road.
+The lap and the finish get a moment of their own (a banner, a sound, a slowdown).
+
+## Feel
+
+- Steering answers the same frame and grows with how long it is held; a car that turns late feels
+  heavy and a car that snaps feels twitchy, and both are tuning numbers, not art.
+- Drift charges something you can see (sparks that change colour at thresholds, a gauge filling),
+  and releasing it at the right moment is the skill.
+- Speed feel: the field of view widens with velocity, streaks or dust at top speed, a slight
+  shake, and an engine pitch that climbs with throttle.
+- Every gate or checkpoint answers locally (a flash on the gate, a chime, a burst), never the
+  whole screen at gate rate, which is a photosensitivity risk.
+
+## Hits to study
+
+- **Mario Kart 8 Deluxe.** Watch the drift: sparks change colour as the charge grows, and letting go
+  fires a boost sized to the charge. Watch the start: a boost for pressing at the right beat of the
+  countdown. Items keep a trailing player in the race; look at how a hit is shown (a spin, a pause,
+  never a long stop).
+- **Trackmania.** Instant restart from the last checkpoint or the start, a ghost of your best run,
+  and bronze, silver, gold and author medals on every track. The whole game is run two, run three,
+  run twenty; notice how little stands between a crash and driving again.
+- **OutRun** (and the phone-era homage Horizon Chase Turbo). The player picks the music before the
+  race, the route forks at checkpoints so each run is a small journey, and the colour of each
+  stretch of road changes with the scenery. Horizon Chase shows a bright low-poly look that runs on
+  a phone and still feels fast.
+
+## 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), "Racing".
+
+- A fall or a wall is a short respawn on the track, never a restart of the race.
+- Position and lap are always on screen; the rivals' pace is beatable with a thumb, not only with frame-perfect input (one racer's last cup was won only at 60 decisions a second).
+- Help for the back of the pack: Mario Kart weights its items toward the players behind, so a race stays open.
+- A ghost or a best time to beat on the next attempt.
+
+## Wow catalogue
+
+- A grey road through green hills with a red car is every racing prototype: give the world a place,
+  a season and a time of day.
+
+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`):
+
+- `racing-drift-tiers` (signature): A drift that charges in colours, Mario Kart 8
+- `racing-speed-lens` (juice): The lens opens with speed, Burnout
+- `racing-takedown` (juice): The crash you cause, replayed, Burnout 3
+- `racing-restart` (feel): Back on the line at once, Trackmania
+- `racing-ghost` (signature): Race your best run, Trackmania
+- `racing-low-camera` (presentation): Low behind, the road fills the frame, Mario Kart 8
+
+## Open choices
+
+A starting contract you may keep or break; write down which in the GDD's genre-card line.
+
+- **Camera.** A chase camera behind the vehicle is the default; top-down, side-on, first-person
+  cockpit and a fixed isometric track are all real shapes of this genre.
+- **Body.** One vehicle the player drives; flight trades the road for rings or a corridor.
+- **Core systems.** Steering and throttle (auto-throttle suits one-thumb phone play), then pick:
+  drift-boost, items, traffic, a fuel or heat gauge, upgrades between races.
+- **How a run ends.** Laps (about three of 30 to 60 s, estimated), a finish line, a checkpoint
+  clock that extends on each gate, or distance until a crash for an endless road. Results with
+  instant retry, and a best time or ghost as the reason for run two.
+- **Orientation.** Landscape for a chase camera; portrait works for top-down and lane-based roads.
+  Tilt can be offered, beside touch controls rather than instead of them.
+
+## Depth and replay
+
+Options with reasons; more in skill `funpixel-game-logic`, its depth reference.
+
+- The first corner or overtake inside about 5 s of the start.
+- A ghost of the best lap, medal times per track, the best time saved on the device; a time trial
+  is this genre's score attack.
+- A second track or a mirrored one opened by the first medal gives a first win somewhere to go.
+
+## Engineering checks
+
+These catch bugs that build green and ship broken.
+
+- **The steering sign.** Steering is judged in screen space: pressing left must move the vehicle
+  left on screen. A chase camera whose offset sits on the wrong side mirrors X, and this is how this
+  genre ships with inverted controls. After any camera change, press the real key once and read the
+  vehicle's projected position (skill `funpixel-game-spine`, its camera reference). Fix the camera
+  or the input mapping, never a state field.
+- **State the checks can read.** Expose `lateralX` (screen space), `speed`, and `lap` or `gates`.
+  One `funpixel.json` check with a real `key` and a `subject` proves the steering sign; one proves
+  `gates` rises while driving.
+- **Frame rate on phones.** Pixel ratio around 1.5, few real-time lights, fog for distance and
+  instanced scenery are a place to start; measure with `npx @funpixel/tools profile` and keep the
+  look you chose (cut how a frame is made, not the art).
+
+**Shelf** (libraries that fit, none required): Three.js; chunked ground; an instanced scatter.

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

@@ -0,0 +1,125 @@
+# RPGs and roguelikes
+
+Action RPGs and roguelites, dungeon crawlers, turn-based adventures, runs with meta progress. 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
+
+- **Who they became.** A build that came together, a character who grew from a stick to a legend.
+  The RPG promise is change in the player's power, and it has to be visible and felt.
+- **The characters they met.** A shopkeeper with a secret, a rival who comes back, a family waiting
+  at home. RPGs are remembered for people as much as for fights.
+- **The loot moment.** A drop in a colour they had never seen, a chest that glowed before it
+  opened, a weapon with a name.
+- **The boss that took five tries,** and the one where everything they had learned clicked.
+- **Death that moved the story.** Coming back changed, to a place that changed.
+
+## The look and the world
+
+- A world with a strong single idea (the underworld as a family business, a castle that rearranges
+  itself, a forest that remembers) gives every room, enemy and item a reason.
+- Rooms or areas each have a palette and a landmark, so the player knows where they are from a
+  screenshot.
+- Loot and rarity have a colour language the whole game respects.
+
+## Characters
+
+The hero reads at phone size with one clear silhouette and a colour that is theirs. Companions,
+merchants and bosses each get a portrait or a pose and a voice (a line, a sound, a way of moving).
+Enemies look like what they do: the fast one leans, the heavy one is wide, the caster glows before
+it casts.
+
+## HUD
+
+Health (and a resource such as mana or a dash charge) in a corner, abilities along the thumb edge
+with cooldowns drawn on the buttons, and the current room or floor named briefly on entry. A choice
+screen (boons, loot, a level-up) takes over the screen and gets the juice.
+
+## Feel
+
+- Every attack has a wind-up, a strike and a recovery the player can read, and every enemy attack
+  has a tell before it lands. Losing should feel like a mistimed dodge, never a surprise.
+- Contact answers with a flash, knockback, a sound and a brief freeze sized to the hit (or what the
+  style calls for).
+- The dodge or dash is the verb that makes combat a dance: quick, safe for a window, then committed.
+
+## Hits to study
+
+- **Hades.** After each room, a choice of boons from a god with a face and a voice. The music plays
+  in stems: all of them during combat, the drums dropping out when it ends, every layer for a boss. Death
+  returns you to a house where the story moves on, so losing is content. Characters were sculpted in
+  3D and then hand-painted with black linework to match the 2D portraits; study how every character
+  reads as a painting.
+- **Dead Cells.** Characters about 50 px tall, animated pose to pose at 30 fps, with extra frames
+  added only before or after a key pose, never between. Visual effects carry the impact. Look at how
+  short the path is from dying to the next run.
+- **Diablo** (the lineage, any entry). Loot drops in rarity colours, each with its own sound, so a
+  good drop is heard before it is read. Watch how a loot beam or a rare sound makes the player stop
+  everything to look.
+
+## 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), "Action RPG".
+
+- A dodge or roll that goes through attacks, with a telegraph long enough to read before each strike.
+- Loot compared at a glance: better or worse shown on the item, not worked out from numbers.
+- Death keeps something (Dead Cells' unlocks, Hades' currency between runs), so a lost run still moves the player on.
+- Enemies announce what they will do next (Slay the Spire's intents) when the fight is about planning.
+
+## Wow catalogue
+
+- A knight with a sword in a grey dungeon fighting slimes is every RPG prototype. Start from a world
+  with a premise and let it name the enemies, the items and the rooms.
+
+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`):
+
+- `rpg-death-is-story` (signature): Death moves the story on, Hades
+- `rpg-dash-strike` (feel): A dash with a safe window, Hades
+- `rpg-hitstop` (juice): Hits freeze by weight, Hollow Knight
+- `rpg-remember` (presentation): People remember what you did, Undertale
+- `rpg-boss-card` (presentation): A boss arrives on a shot, Hollow Knight
+- `rpg-mercy` (signature): A fight you can end without winning it, Undertale
+
+## What is each weapon or skill for?
+
+A design question for the GDD: for each weapon, ability or spell, the situation where it beats the
+others (reach, a crowd, a shield, a state it opens or finishes) and what it costs. A choice of three
+reads as a choice when the three answer different situations (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, isometric or side view that follows; a fixed room view for a dungeon run.
+- **Body.** One hero or a small party.
+- **Core systems.** Fight and choose: every level-up, room or draw offers a few options. Then pick:
+  real-time or turn-based combat, a dash, loot, a shop, a hub, companions, meta progress.
+- **How a run ends.** Death, or a floor or boss cleared; run two carries something (gold, a
+  shortcut, a story beat).
+- **Orientation.** Landscape for action; portrait suits turn-based and card-driven runs.
+
+## Depth and replay
+
+Options with reasons; more in skill `funpixel-game-logic`, its depth reference.
+
+- A floor or quest of about 5 to 10 minutes (estimated); death carries something forward, so
+  losing is progress.
+- The seed as a share code, a best depth or fastest clear saved, one class or item unlocked by the
+  first clear.
+
+## Engineering checks
+
+- **Persistence.** Keep meta progress in `SaveManager` (skill `funpixel-game-spine`): a new run wipes the
+  run, never the meta.
+- **Seeded dungeons** keep only the largest connected region and put the exit farthest from the
+  start; danger rises with distance, not room index (skill `funpixel-game-logic`).
+- **State the checks can read.** Expose `floor` or `turn`, `hp`, `gold`. One check proves an attack
+  lands through real input (`enemy_hp` falls); one proves the choice screen changes state.
+
+**Shelf** (libraries that fit, none required): rot-js (field of view, dungeon generation); a seeded
+RNG (the seed is the share code); yuka for enemy state machines; gsap.