@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/skills/grok-building-games/references/ecs-architecture.md

@@ -0,0 +1,111 @@
+# ECS & Game State Architecture for JS Games (bitECS, miniplex, ECS vs OOP, state structure)
+
+Consolidated from webgamedev.com, the bitECS and miniplex docs, and data-oriented-design canon (see Sources). Focus: how an AI builder should **structure game state so it stays fast and untangled** as a game grows — and when *not* to reach for ECS.
+
+---
+
+## 1. What ECS is (and why it exists)
+
+**Entity-Component-System** separates data from behavior:
+- **Entity** — an ID (or a plain object) with no logic; just a thing that exists.
+- **Component** — pure **data**, no methods (Position, Velocity, Health, Sprite, Collider).
+- **System** — pure **behavior** that iterates all entities having a given set of components and updates them (MovementSystem reads Position+Velocity).
+
+Benefits: **composition over inheritance** (add/remove capabilities by adding/removing components — no deep class hierarchies), cache-friendly iteration, easy serialization (state = plain data), and clean separation that scales to thousands of entities.
+
+The classic problem ECS solves: the "deadly diamond" of OOP inheritance (`FlyingEnemy` vs `SwimmingEnemy` vs `FlyingSwimmingShootingEnemy`...). With ECS you just attach `Flying`, `Swimming`, `Shooting` components in any combination.
+
+---
+
+## 2. When ECS vs OOP (don't cargo-cult ECS)
+
+**Use plain OOP / a simple object list when:**
+- Small games, jams, prototypes, or a handful of distinct entity types.
+- Entity count is low (dozens–low hundreds) and perf isn't a concern.
+- The team/model iterates faster with intuitive `player.jump()` classes.
+- The engine already gives you a good model (Phaser GameObjects/prefabs, Three.js `Object3D` scene graph) — you can go a long way with a component-ish mixin approach without a full ECS.
+
+**Reach for ECS when:**
+- **Many similar entities** (bullet-hell, RTS, particles, simulations, .io games) — thousands of entities needing fast batch updates.
+- Highly **combinatorial** entity capabilities (lots of mix-and-match behaviors/status effects).
+- You need **determinism/serialization** (netcode, replays, save states) — pure-data components serialize trivially.
+
+**Rule:** ECS is an optimization/organization tool, not a moral requirement. A giant `update()` switch or a tidy class hierarchy is fine for small games. Adopt ECS when entity count/combinatorial complexity actually bites — premature ECS adds boilerplate for no gain.
+
+---
+
+## 3. Library choice: bitECS vs miniplex
+
+**miniplex** — DX-first, entities are **plain JS objects**, components are just properties. Best default for most indie/web games and rapid prototyping; excellent TypeScript + React bindings.
+```js
+import { World } from 'miniplex';
+const world = new World();
+const player = world.add({ position:{x:0,y:0}, velocity:{x:100,y:0}, health:{cur:100,max:100} });
+const moving = world.with('position','velocity');   // live archetype query
+function movementSystem(dt){ for (const e of moving){ e.position.x += e.velocity.x*dt; e.position.y += e.velocity.y*dt; } }
+world.remove(player);
+```
+- Use `world.addComponent(e,'velocity',{...})` / `removeComponent` so queries re-index (mutating a bare property can skip re-indexing).
+- `for...of` over a query is fast and **safe for removal during iteration**. No built-in scheduler — you call systems from your loop.
+- Object property access is slightly slower at extreme entity counts than bitECS's typed arrays.
+
+**bitECS** — performance-first, data-oriented: entities are **integer IDs**, components are **Structure-of-Arrays (typed arrays)**, archetype/bitmask queries. Best for tens of thousands of entities, WebGPU, perf-critical sims. ~5kb, zero deps (used in Hubs/Third Room; eyed by Phaser 4).
+```js
+import { createWorld, addEntity, addComponent, query } from 'bitecs';
+const world = createWorld({ Position:{x:new Float32Array(1e4),y:new Float32Array(1e4)}, Velocity:{x:[],y:[]} });
+const { Position, Velocity } = world.components;
+const eid = addEntity(world); addComponent(world,eid,Position); addComponent(world,eid,Velocity);
+const moving = query(world,[Position,Velocity]);
+for (const e of moving){ Position.x[e] += Velocity.x[e]*dt; Position.y[e] += Velocity.y[e]*dt; }
+```
+- **Note the API moved on:** older tutorials use `defineComponent`/`defineQuery`/`Types`; current bitECS (0.4+) uses `createWorld({...schemas})` + `query(world,[...])`, plus relationships/observers/prefabs. Verify the version you install.
+- SoA layout = cache-friendly; entities-as-IDs = trivial to serialize/network.
+
+**Others:** Becsy (multithreaded), Koota, or the engine's own model. Some projects mix (bitECS core sim + object layer for UI).
+
+---
+
+## 4. Structuring game state (even without a formal ECS)
+
+- **Single source of truth:** keep a central, serializable game-state object (or ECS world). Avoid scattering authoritative data across DOM, closures, and random globals — it makes save/load, undo, and netcode nearly impossible.
+- **Separate data from rendering:** gameplay state (positions, health) should be independent of the visual objects (meshes/sprites). Systems update data; a render/sync step pushes data → Three.js/Phaser objects each frame. This keeps the sim testable/deterministic and lets you do fixed-timestep + interpolation.
+- **Systems run in a defined order each tick:** input → AI → movement → collision → damage → cleanup → render-sync. Order matters and should be explicit, not incidental.
+- **Object pooling instead of create/destroy churn:** for bullets/enemies/particles, recycle entities (mark inactive) rather than allocating/GCing every frame (pairs with ECS well; see `threejs-foundational.md`).
+- **Deferred structural changes:** don't add/remove entities in the middle of iterating a query in ways the lib doesn't support — queue spawns/despawns and apply between systems (miniplex `for...of` is removal-safe; still queue mass changes for clarity).
+- **Fixed timestep for the sim** (see game-loop/collision skills) so ECS systems are deterministic — required for netcode/replays.
+- **Events/messaging** between systems via a small event queue rather than direct cross-system calls, to keep systems decoupled.
+
+---
+
+## 5. Bug-prevention checklist
+- **Putting logic in components / data in systems** → defeats ECS; keep components pure data, systems pure behavior.
+- **Adopting ECS for a tiny game** → boilerplate with no benefit; use a simple object list/classes until entity count/complexity warrants it.
+- **Deep inheritance for entity variety** → combinatorial class explosion; compose with components instead.
+- **Mutating a miniplex property directly and expecting query updates** → use `addComponent`/`removeComponent` so archetypes re-index.
+- **Using stale bitECS `defineComponent` tutorials against a new version** → API mismatch; check installed version's docs.
+- **Mixing render objects into authoritative state** → non-serializable, non-deterministic; separate sim data from view.
+- **Undefined system order** → order-dependent bugs (moving before collision, etc.); define an explicit pipeline.
+- **create/destroy per frame** → GC stalls; pool entities.
+- **Structural changes mid-iteration** → skipped/duplicated updates; defer to a queue.
+- **Scattered global state** → save/load and netcode become impossible; centralize the world.
+
+---
+
+## Defaults to apply
+- **Default to miniplex** for generated games that need ECS (plain objects, great TS/React DX); **switch to bitECS** only when the game genuinely has thousands of entities or needs SoA perf. For small/simple games, a plain object list or engine prefabs is fine — don't force ECS.
+- **Always structure state as a single serializable world with sim/render separation** and an **explicit system pipeline** (input→AI→movement→collision→damage→cleanup→render-sync) run on a fixed timestep. This unlocks save/load, replays, and netcode for free.
+- **Bake in pooling + deferred spawn/despawn** for entity-heavy genres.
+- When generating ECS code, **verify the library version's current API** (bitECS especially changed) rather than emitting old `defineComponent` patterns from memory.
+
+---
+
+## Sources
+- Web Game Dev — Code architecture / ECS overview: https://www.webgamedev.com/code-architecture/ecs
+- bitECS — repo & docs: https://github.com/NateTheGreatt/bitECS , https://bitecs.dev/docs/introduction
+- miniplex — repo & docs: https://github.com/hmans/miniplex , miniplex-react: https://github.com/hmans/miniplex/tree/main/packages/miniplex-react
+- Becsy (multithreaded ECS): https://lastolivegames.github.io/becsy/
+- Sander Mertens — "Entity Component System FAQ": https://github.com/SanderMertens/ecs-faq
+- Adam Martin — "Entity Systems are the future of MMOG development": http://t-machine.org/index.php/2007/09/03/entity-systems-are-the-future-of-mmog-development-part-1/
+- Mick West — "Evolve Your Hierarchy" (components over inheritance): https://cowboyprogramming.com/2007/01/05/evolve-your-hierarchy/
+- Richard Fabian — Data-Oriented Design (book): https://www.dataorienteddesign.com/dodbook/
+- Game Programming Patterns — Component pattern: https://gameprogrammingpatterns.com/component.html

package/skills/grok-building-games/references/game-feel-juice.md

@@ -0,0 +1,110 @@
+# Game Feel & Juice (screenshake, hitstop, tweening/easing, particles, squash & stretch, camera, SFX layering)
+
+The canon: Steve Swink's *Game Feel*, Vlambeer/"Juice it or lose it" (Martin Jonasson & Petri Purho), and Jan Willem Nijman's "The art of screenshake" (see Sources). "Juice" = generous, layered, non-gameplay-affecting feedback that makes every input feel physical and satisfying. Focus: what an AI builder should reflexively add so games feel **alive instead of static**, without hurting readability or perf.
+
+---
+
+## 1. The core principle
+
+**Every meaningful action should produce disproportionate, multi-sensory feedback.** A single "hit" should simultaneously trigger several of: sound, particles, screenshake, hitstop, flash, knockback, squash/stretch, and a number/pop. The gameplay math can stay simple — the *feel* comes from the feedback layer stacked on top. The classic demo takes the same identical Breakout and makes it feel amazing purely by adding these layers.
+
+**Rule:** Separate "simulation" from "presentation." Feedback (shake, tween, particles, flash) must **never change gameplay outcomes** — it's cosmetic. This keeps physics deterministic (important for netcode/replays) while letting you pile on juice freely.
+
+---
+
+## 2. Screenshake (the highest impact-per-effort effect)
+
+- Offset the **camera** (or a camera container), not the world objects. Apply a random offset each frame from a **trauma value** that **decays over time**.
+- **Use trauma², not linear** (Squirrel Eiserloh's "Juicing Your Cameras"): store `trauma` in [0,1], set `shake = trauma * trauma` (or `trauma³`). Add trauma on events (small hit +0.3, explosion +0.8), decay `trauma -= decay * dt` each frame. Squaring makes small hits subtle and big hits explosive.
+- Offset with **noise, not pure random**, for smoother shake: `offsetX = maxOffset * shake * (noise(t) )`; also shake **rotation** slightly (`maxAngle * shake * noise`) — rotational shake reads as more violent.
+- **Directional shake** for directional hits (kick the camera opposite the impact) reads better than omnidirectional for melee/recoil.
+- **Cap it & scale it down for accessibility.** Excessive shake causes motion sickness — expose a "screen shake" slider/toggle. Never shake so hard UI/targets become unreadable.
+- Scale offsets by `dt`-independent amount but decay by `dt` so it's frame-rate independent.
+
+Nijman's rules also include: **more bullets, bigger bullets, muzzle flash, impact effects, permanent decals, camera lerp/lookahead, camera kick, sleep/hitstop, gun delay, knockback, screen shake, and even a little randomness in everything.**
+
+---
+
+## 3. Hitstop / hitstun / "sleep" (freeze frames on impact)
+
+- On a big hit, **freeze the game (or just the two involved entities) for a few frames** (~30–120ms), then resume. This sells impact enormously — the brain reads the pause as force.
+- Implement as a global **time scale** or a short "freeze frames" counter: while frozen, skip the gameplay update (or set `timeScale=0`) but **keep rendering** and keep the flash/particles visible. Common: freeze ~2–6 frames for normal hits, longer for finishers.
+- Keep hitstop **short**; too long feels laggy/unresponsive. Often paired with a brief hit **flash** (tint the sprite white for 1–2 frames) and knockback that starts *after* the freeze.
+- Distinguish **hitstop** (brief freeze for feel) from **hitstun** (gameplay state where a hit character can't act) — the latter is real gameplay, the former is pure juice.
+
+---
+
+## 4. Tweening & easing (motion that isn't linear)
+
+- **Almost nothing should move linearly.** Real, satisfying motion accelerates/decelerates. Use **easing functions** for UI transitions, pickups flying to the HUD, menus, popups, camera moves, damage numbers.
+- Common curves (see easings.net for exact formulas/graphs):
+  - **easeOutQuad/Cubic** — arrive gently (great for things settling into place).
+  - **easeInQuad/Cubic** — start slow (things launching).
+  - **easeOutBack** — slight overshoot then settle (pop-in for UI/pickups — very juicy).
+  - **easeOutElastic / easeOutBounce** — springy/bouncy (buttons, coin pickups). Use sparingly.
+  - **easeInOutQuad** — smooth both ends (camera, generic).
+- **Use a tween library** rather than hand-rolling: **GSAP** (best-in-class, huge easing set, timelines), **@tweenjs/tween.js** (lightweight, common in Three.js), or the engine's built-in (Phaser `this.tweens.add`). Tweens compose (chains, delays, yoyo, repeat) and auto-handle dt.
+- **Kill/clean up tweens** when the target is destroyed or the scene shuts down (leaked tweens mutating dead objects = crashes/bugs). Phaser: kill on `SHUTDOWN`; GSAP: `.kill()`.
+- A **spring/damped-lerp** (`x += (target - x) * (1 - exp(-k*dt))`) is a great procedural alternative for continuous following (cameras, cursors, UI) — always frame-rate correct if you use the `exp` form rather than `x += (target-x)*0.1` (the naive lerp is frame-rate dependent — see §6).
+
+---
+
+## 5. Particles & squash-and-stretch
+
+- **Particles everywhere:** dust on landing/footsteps, sparks on hit, debris on death, trails on projectiles, confetti on win, ambient motes. They cost little and add enormous life. Use the engine's particle system (Phaser `add.particles`, Three.js points/instanced sprites) and **pool** them (no per-emit allocation — see `threejs-foundational.md`).
+- **Squash & stretch** (Disney's foundational animation principle): deform on acceleration to convey weight/speed while preserving apparent volume.
+  - Jump: stretch vertically (taller/thinner) on takeoff, squash (shorter/wider) on landing, then spring back via `easeOutBack`/elastic.
+  - Preserve volume: if you scale `y` by `s`, scale `x` by ~`1/s`, so it doesn't look like it's growing.
+  - Drive it from velocity (stretch along the movement direction) or trigger on discrete events (land, hit, shoot recoil).
+- **Anticipation + follow-through:** wind up before a big action (tiny reverse/squash) and overshoot after — even a couple frames sells it.
+- **Pop numbers & flashes:** floating damage numbers that rise + fade + scale-pop, combo counters, "+10" pickups. Cheap, huge readability + satisfaction win.
+
+---
+
+## 6. Camera feel (lerp, lookahead, deadzone, punch)
+
+- **Never hard-snap the camera to the player.** Smoothly follow (`lerp`/spring) toward the target so motion is fluid.
+  - **Frame-rate-correct smoothing:** `pos += (target - pos) * (1 - Math.exp(-k * dt))`. The naive `pos += (target - pos) * 0.1` is **frame-rate dependent** (faster on 144Hz than 60Hz) — a common bug; use the exp form or a fixed-timestep camera update.
+- **Lookahead:** offset the camera slightly in the direction of movement / where the player is aiming, so the player sees more of what's ahead. Ease the offset in/out.
+- **Deadzone / soft zone:** don't move the camera until the player leaves a central box — prevents nauseating micro-jitter from small movements.
+- **Camera punch/kick** on impacts (a quick zoom-in or positional kick that eases back) complements screenshake.
+- Clamp the camera to level bounds; round the final camera position to whole pixels for pixel-art games to avoid shimmer.
+
+---
+
+## 7. SFX layering & audio feel
+
+- **Layer sounds** for richness: a single "shoot" = a low thump + a mid body + a high click/transient. Impacts = hit + debris + a tail.
+- **Pitch-randomize** repeated sounds (±5–15%) so rapid fire / footsteps don't sound robotic (`playbackRate` / Howler `rate`). Slightly randomize volume too.
+- Sound is feedback: **every** action should have audio, and it should be tight (low latency) and satisfy on first frame of the action (see the audio skill for Web Audio/Howler, mobile unlock, buses).
+- Duck music briefly under big events; add a subtle low-frequency "boom" on explosions.
+
+---
+
+## 8. Don't over-juice (readability & perf guardrails)
+- **Juice must not obscure gameplay.** If shake/flash/particles hide the player, enemies, or projectiles, dial back. Readability > spectacle.
+- **Accessibility:** provide toggles/sliders for screen shake, flashing, and reduced motion (respect `prefers-reduced-motion`). Heavy flashing risks photosensitivity — avoid rapid full-screen strobing.
+- **Perf:** pool particles/tweens, cap concurrent particles, don't allocate in the hit path. Juice is cheap but "thousands of unpooled particles per explosion" is not.
+- Keep hitstop short and prediction-safe in multiplayer (apply juice on the client only; never let it alter the authoritative sim).
+
+---
+
+## Defaults to apply
+- **Auto-juice defaults:** whenever the builder generates a hit/pickup/death/land/win event, reflexively attach the stack: **sound + particles + short hitstop + white flash + screenshake(trauma²) + easeOutBack pop / squash-stretch + floating number.** Same simple gameplay, dramatically better feel — this is the single biggest perceived-quality lever.
+- **Ship a tiny reusable "juice" toolkit** in generated games: a `trauma`-based shake (squared, noise-driven, decaying), a `hitstop(frames)` helper (timeScale/freeze-count), a `flash(sprite)` helper, easing/tween helpers (or GSAP/tween.js), and frame-rate-correct camera follow with lerp + lookahead + deadzone.
+- **Always use the `exp`-based lerp** for cameras/followers so smoothing is frame-rate independent — bake this in to avoid the classic 144Hz-vs-60Hz bug.
+- **Separate presentation from simulation** so juice never affects gameplay/netcode. Provide screenshake/flash/reduced-motion toggles by default for accessibility.
+
+---
+
+## Sources
+- Martin Jonasson & Petri Purho — "Juice it or lose it" (GDC talk): https://www.youtube.com/watch?v=Fy0aCDmgnxg ; companion "Game feel" write-up on grapefrukt.
+- Jan Willem Nijman (Vlambeer) — "The art of screenshake": https://www.youtube.com/watch?v=AJdEqssNZ-U
+- Steve Swink — *Game Feel: A Game Designer's Guide to Virtual Sensation* (book), gamefeelbook.com.
+- Squirrel Eiserloh — "Juicing Your Cameras With Math" (GDC, trauma² screenshake): https://www.youtube.com/watch?v=tu-Qe66AvtY
+- easings.net — easing function reference with formulas & graphs: https://easings.net/
+- Robert Penner's easing equations (origin of the standard easings): http://robertpenner.com/easing/
+- GSAP docs (tweening/easing/timelines): https://gsap.com/docs/v3/ ; tween.js: https://github.com/tweenjs/tween.js
+- Disney's 12 principles of animation (squash & stretch, anticipation, follow-through): https://en.wikipedia.org/wiki/Twelve_basic_principles_of_animation
+- MDN — `prefers-reduced-motion`: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion
+- "The Juice Factor" / GDC Vault talks on feedback & game feel.

package/skills/grok-building-games/references/genres/board-card-chess.md

@@ -0,0 +1,89 @@
+# Genre Playbook — Board & Card Games (Chess, Checkers, Tic-Tac-Toe, Card games)
+
+Turn-based logic games where correctness *is* the game: an illegal move or a flaky turn transition breaks trust instantly. The genre is about a clean **turn state machine**, **rigorous legal-move validation**, and (for solo play) a **minimax / alpha-beta AI**. Almost always 2D (Canvas/DOM/Phaser); rendering is trivial, logic is everything. Read `../threejs-foundational.md` for general structure; this file is about game-logic correctness.
+
+---
+
+## 1. Core mechanics (minimal-but-good scope for a demo)
+
+1. **A board/state data model** separate from the view (array of pieces / card lists).
+2. **A turn state machine** that governs whose turn it is and what's allowed.
+3. **Legal-move generation + validation** (only legal moves accepted and highlighted).
+4. **Win/draw/loss detection** (checkmate/stalemate, three-in-a-row, deck empty, etc.).
+5. **A simple AI opponent** (minimax/alpha-beta for perfect-info games; heuristics for card games).
+
+For chess specifically: **do not hand-roll the rules for a demo unless asked — use `chess.js`** for move generation/validation/checkmate and `chessground`/a board lib for the UI. Hand-rolling chess rules (en passant, castling through check, pins, promotion, threefold repetition) is a huge bug surface. Build custom rules only for simpler games (tic-tac-toe, checkers, connect-4) or when explicitly required.
+
+---
+
+## 2. Turn state machine
+
+Model the game as an explicit finite state machine — never as ad-hoc booleans scattered across handlers.
+
+- **States (typical):** `PlayerTurn (idle → pieceSelected → moveConfirmed)` → `Resolving/Animating` → `CheckWinCondition` → `OpponentTurn` → … → `GameOver`.
+- **One source of truth for `currentPlayer`.** Only accept input during that player's `idle`/`selecting` state; **ignore all input while animating or during the AI's turn** (a top bug: clicking during resolution corrupts state or lets a player move twice).
+- **Strict transitions:** select piece → show legal moves → choose destination → validate → apply move → switch player → check terminal conditions. Each step gated; no shortcuts.
+- **Undo/history:** keep a move stack (and/or full state snapshots) — enables undo, threefold-repetition detection, and replay. Store enough to reverse a move (captured piece, castling/en-passant flags).
+- **Determinism:** the model must be pure and reproducible; the view only reflects it. This makes AI, undo, and (later) networking possible.
+
+---
+
+## 3. Legal-move validation (get this exactly right)
+
+- **Generate, then filter.** Produce candidate moves per piece, then remove illegal ones. **Only offer/accept legal moves** — highlight them; reject clicks on illegal squares.
+- **Chess "leaves your king in check" rule (the classic omission):** a move is illegal if, *after* making it, your own king is attacked. Implement by making the move on a copy, checking if your king is attacked, and rejecting if so. This automatically handles pins — don't try to special-case pins.
+- **Special chess rules to not forget:** castling (king & rook unmoved, squares empty, king not in/through/into check), en passant (only immediately after the enemy pawn's two-square move), pawn promotion, and the 50-move / threefold-repetition / stalemate draws. These are exactly why `chess.js` exists.
+- **Terminal detection:** checkmate = in check AND no legal moves; stalemate = not in check AND no legal moves (a draw, not a loss — a very common bug is scoring stalemate as a win). For tic-tac-toe/connect-4, check all lines after each move and also detect a full-board draw.
+- **Card games:** validate legality against the rules (can you play this card now?), keep hidden information hidden (trivial in single-player; true hidden-info enforcement needs a server, which is out of scope on this deploy target), and shuffle with an unbiased algorithm (**Fisher–Yates**, not `sort(() => Math.random()-0.5)` which is biased).
+
+---
+
+## 4. AI: minimax & alpha-beta pruning
+
+For **perfect-information, deterministic** games (chess, checkers, tic-tac-toe, connect-4, Othello):
+
+- **Minimax:** recursively explore the game tree; the mover **maximizes** their evaluation, the opponent **minimizes** it. At the depth limit (or terminal node), return a heuristic evaluation. Choose the move leading to the best guaranteed outcome.
+- **Alpha-beta pruning:** carry `alpha` (best already guaranteed to the maximizer) and `beta` (best guaranteed to the minimizer); **prune** a branch when `alpha >= beta` (the opponent would never allow it). Same result as minimax, far fewer nodes → much deeper search. Move ordering (try likely-good moves first, e.g. captures) dramatically improves pruning.
+- **Depth = difficulty.** Tic-tac-toe: search to the end (perfect play). Connect-4/checkers: a few plies. Chess: alpha-beta + a material+position evaluation gets a decent club-level bot; go deeper/iterative-deepening for stronger.
+- **Evaluation function (heuristic):** for chess, material values (P=1, N/B=3, R=5, Q=9) + piece-square tables (positional bonuses) + mobility/king safety. Terminal nodes return ±∞ for win/loss, 0 for draw. A good eval matters more than raw depth for feel.
+- **Avoid freezing the UI:** run deeper searches so they don't block the main thread — use a **Web Worker**, iterative deepening with a time budget, or `requestAnimationFrame`-chunked search. A 2-second UI hang while the AI "thinks" feels broken.
+- **Imperfect-info / non-deterministic games** (most card games) need different AI: rules-based heuristics, Monte Carlo (MCTS) with determinization, or expectiminimax. Don't shoehorn plain minimax into a hidden-hand card game.
+
+---
+
+## 5. Common bugs to avoid (checklist)
+
+- **Accepting input during animation or the AI's turn** → double moves / corrupted state. Gate all input on the turn state.
+- **Offering illegal moves** → validate + highlight only legal moves; reject the rest.
+- **(Chess) Allowing a move that leaves your own king in check** → test post-move king safety; this also handles pins.
+- **(Chess) Missing en passant / castling-through-check / promotion / draw rules** → use `chess.js` instead of hand-rolling.
+- **Scoring stalemate as a win** → stalemate is a draw; checkmate = in check + no legal moves.
+- **Biased shuffle** (`sort(Math.random)`) → use Fisher–Yates.
+- **State in the DOM/sprites, not a model** → makes AI, undo, and win-checks unreliable; keep a pure model.
+- **AI blocks the main thread** → search in a Web Worker or time-boxed/iterative; keep the UI responsive.
+- **Minimax min/max sign errors** → a classic; test against known positions (mate-in-1, forced draws).
+- **No move history** → can't undo or detect repetition; keep a reversible move stack.
+
+---
+
+## Defaults to apply
+
+1. **For chess, default to `chess.js` (rules/validation/mate) + a board UI lib** rather than hand-rolling. Hand-roll only simple games (tic-tac-toe, connect-4, checkers) or when asked.
+2. **Model the game as an explicit turn state machine with one `currentPlayer` source of truth; ignore input during animation/AI turns.** Keep a pure model separate from the view + a reversible move history.
+3. **Only ever present and accept LEGAL moves** (generate → filter → highlight). For chess, reject any move that leaves your own king in check.
+4. **Detect terminal states correctly** — checkmate vs stalemate (draw!), draws, and full-board ties.
+5. **AI = minimax + alpha-beta pruning with a heuristic eval; depth = difficulty; run in a Web Worker / time-boxed so the UI never freezes.** Use MCTS/heuristics (not plain minimax) for hidden-info card games; shuffle with Fisher–Yates.
+6. **Minimal scope:** correct rules + turn FSM + legal-move UI + win/draw detection + one AI opponent. Correctness beats features here.
+
+---
+
+## Sources
+- chess.js — move generation, validation, check/checkmate/draw detection: https://github.com/jhlywa/chess.js
+- chessground — Lichess's board UI: https://github.com/lichess-org/chessground
+- Chess Programming Wiki — Minimax: https://www.chessprogramming.org/Minimax
+- Chess Programming Wiki — Alpha-Beta: https://www.chessprogramming.org/Alpha-Beta
+- Chess Programming Wiki — Evaluation & Piece-Square Tables: https://www.chessprogramming.org/Evaluation and https://www.chessprogramming.org/Piece-Square_Tables
+- Red Blob Games — game trees / minimax intuition and grid tools: https://www.redblobgames.com/
+- Wikipedia — Fisher–Yates shuffle (unbiased): https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle
+- Wikipedia — Monte Carlo tree search (imperfect-info/large trees): https://en.wikipedia.org/wiki/Monte_Carlo_tree_search
+- MDN — Web Workers (off-thread AI search): https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API

package/skills/grok-building-games/references/genres/endless-runner.md

@@ -0,0 +1,83 @@
+# Genre Playbook — Endless Runner
+
+Auto-forward games where the player dodges obstacles and collects pickups at ever-increasing speed (Temple Run, Subway Surfers, Canabalt, Flappy-adjacent, Chrome Dino). Works in 2D (Phaser) or 3D (Three.js). The whole genre rests on **procedural spawning + object pooling + a difficulty ramp**. Read `../threejs-foundational.md` first (delta time, pooling, mobile input).
+
+---
+
+## 1. Core mechanics (minimal-but-good scope for a demo)
+
+1. **Auto-run:** the player moves forward automatically (or the world scrolls toward a fixed player) at a speed that **increases over time**.
+2. **Simple avoidance input:** jump / slide, or lane-switch left/right (or both).
+3. **Endless procedural spawning** of obstacles + collectibles as pooled objects.
+4. **Collision → death** (one hit or a few lives), with **distance/coins as score**.
+5. **Instant restart** and a persisted high score.
+
+One lane setup + jump/slide + one obstacle type + coins + a speed ramp + hi-score is a complete, replayable game. Add power-ups, multiple biomes, and characters later. **The tuning of the speed/difficulty curve is the game.**
+
+---
+
+## 2. The "endless" trick: scroll the world, recycle the pieces
+
+- **Keep the player near a fixed position; move the world toward them** (or move the player and follow with the camera — mathematically equivalent). Fixed-player + moving-world is usually simpler for spawning and scoring by distance.
+- **Chunk/segment spawning:** build the track from prefab segments (ground tiles, obstacle patterns). Spawn a new segment ahead when the last one enters view; **despawn/recycle** segments once they pass behind the player/camera.
+- **Object pooling is mandatory.** Runners spawn thousands of obstacles/coins over a run — preallocate pools and recycle (`active/visible=false` in Phaser, or a free-list). Never create/destroy per spawn (GC stutter kills the feel).
+- **Parallax background** (2D): multiple layers scrolling at different speeds for depth; use `tileSprite`/texture offset scrolling rather than spawning background sprites.
+- **Seamless ground:** loop a tiling ground texture by scrolling UV/tilePosition, or ping-pong two ground pieces, so there's no visible seam.
+
+---
+
+## 3. Controls & feel
+
+- **Jump:** use platformer forgiveness where relevant — **jump buffering** (register a press slightly before landing) and a short **coyote window** make it feel fair. Variable jump height optional. Clamp fall speed.
+- **Slide/duck:** a timed crouch that shrinks the hitbox; must end even if the key is held-then-released oddly (timer-driven, not just key-held).
+- **Lane switch (3D runners):** discrete lanes; **tween** the player smoothly between lane X positions rather than teleporting, and lock input during the transition or allow queueing. Support swipe (mobile) + arrows/A-D (desktop).
+- **One-button variants (Flappy/Canabalt):** tap = flap/jump; keep the single input crisp and buffered.
+- **Coyote/buffer + snappy, immediate response** — runners punish input lag hard because timing is everything.
+- **Fairness rule:** never spawn an **impossible/unavoidable** obstacle combination for the current speed. Constrain the spawner so the player always has a reachable gap/lane (see §5).
+
+---
+
+## 4. Difficulty & scoring
+
+- **Speed ramps up with distance/time** (linear or gently curved), which naturally raises difficulty. Tie obstacle density and pattern complexity to the same progression.
+- **Cap the max speed** or the game becomes unplayable / physics/collision get unstable — and above some speed the player literally can't react.
+- **Reaction-time budget:** obstacles must appear far enough ahead that the player has time to react at the current speed (spawn distance should scale with speed). This is the core fairness constraint.
+- **Score = distance** (+ coins). Persist the high score in `localStorage`. Show near-misses / combos for extra juice.
+- **Pickups:** coins in patterns (arcs, lines) that sometimes lure the player into risk; occasional power-ups (magnet, shield, jetpack) on a timer.
+
+---
+
+## 5. Common bugs to avoid (checklist)
+
+- **Creating/destroying objects per spawn** → GC hitches; use pools and recycle off-screen objects.
+- **Impossible obstacle combos** → spawner must always leave a reachable gap/lane for the current speed; validate patterns.
+- **Obstacles appear too late to dodge** → spawn distance / reaction budget must scale with speed.
+- **Unbounded speed** → cap max speed; otherwise collision tunneling and unfair, unplayable pace.
+- **Collision tunneling at high speed** → swept/segment collision or sub-stepping, not per-frame overlap only.
+- **Visible seams in ground/background** → scroll UV/tilePosition or ping-pong two pieces; don't spawn gap-prone tiles.
+- **Objects never despawn** → recycle everything behind the camera; otherwise memory/entity count grows until it crashes.
+- **Movement/scroll not delta-scaled** → speed differs per frame rate.
+- **Slide/jump state gets stuck** → drive crouch/jump with timers and reset on death/restart.
+- **No fair restart** → reset speed, pools, score, and player state fully on restart (leftover pooled objects reappearing is a classic bug).
+
+---
+
+## Defaults to apply
+
+1. **Fixed player + scrolling/recycled world built from pooled prefab segments** is the canonical, bug-resistant structure. Pool obstacles, coins, and segments; recycle behind the camera.
+2. **Difficulty = increasing speed tied to distance, with a hard speed cap.** Scale obstacle spawn distance to the current speed so there's always time to react.
+3. **Never spawn unavoidable obstacles** — the spawner must guarantee a reachable gap/lane for the current speed.
+4. **Snappy input with jump buffering + coyote time**; tween lane switches smoothly; support swipe + keyboard.
+5. **Score by distance + coins, persisted in localStorage; instant full-reset restart.**
+6. **Use swept collision + a speed cap** to avoid high-speed tunneling. Add parallax + seamless scrolling ground for polish.
+
+---
+
+## Sources
+- MDN — 2D collision detection & game techniques: https://developer.mozilla.org/en-US/docs/Games/Techniques
+- Phaser — Groups / object pooling (recycle sprites): https://docs.phaser.io/phaser/concepts/gameobjects/group
+- Phaser — TileSprite (scrolling ground/parallax): https://docs.phaser.io/api-documentation/class/gameobjects-tilesprite
+- GMTK / general platformer feel (jump buffering, coyote time apply to runners too): https://gmtk.itch.io/platformer-toolkit
+- "How Canabalt / procedural runner level generation works" (chunk-based spawning): https://www.gamedeveloper.com/design/the-power-of-procedural-generation-in-canabalt
+- Chrome Dino (T-Rex Runner) open-source reference: https://github.com/wayou/t-rex-runner
+- Gaffer On Games — Fix Your Timestep (high-speed collision stability): https://gafferongames.com/post/fix_your_timestep/

package/skills/grok-building-games/references/genres/fps.md

@@ -0,0 +1,105 @@
+# Genre Playbook — First-Person Shooter (FPS)
+
+How to build a browser FPS that *feels* right (fast, snappy, weighty) and avoids the classic bugs. Assumes Three.js/Babylon.js. Read `../threejs-foundational.md` first — this file only adds FPS-specific rules (it already covers pointer lock + WASD basics, delta time, disposal, draw calls).
+
+---
+
+## 1. Core mechanics (minimal-but-good scope for a demo)
+
+A convincing FPS demo needs, in priority order:
+1. **Mouse-look + WASD movement** with pointer lock (yaw/pitch, clamped pitch).
+2. **One weapon that shoots** with a crosshair, muzzle flash, and hit feedback.
+3. **Something to shoot** — 3–8 targets or simple enemies with a hit reaction + death.
+4. **A hit indicator + score/ammo HUD.** Feedback is the game.
+5. **A bounded arena** with walls/cover and collision so you can't walk through geometry.
+
+Do NOT try to ship AI pathfinding, multiple weapons with full inventory UI, reload animations, or netcode in a first demo. A single hitscan weapon + stationary/patrolling targets + juice (screen shake, flash, sound) reads as a real game.
+
+---
+
+## 2. Controls & camera
+
+- **Pointer Lock** is mandatory (see MDN below). Request it from a **user gesture** (`canvas.addEventListener('click', () => canvas.requestPointerLock())`), show a "Click to play" blocker, and re-show it on `pointerlockchange` when `document.pointerLockElement === null`. Prefer `requestPointerLock({ unadjustedMovement: true })` to disable OS mouse acceleration for consistent aim; **fall back gracefully** if the returned Promise rejects with `NotSupportedError`.
+- **Read `movementX`/`movementY` on `mousemove`, not `clientX/Y`.** While locked, `clientX/Y` are frozen; only the deltas update. `yaw -= movementX * sensitivity; pitch -= movementY * sensitivity`.
+- **Clamp pitch to just under ±90°** (`±89°`, i.e. `Math.PI/2 - 0.01`) so the camera never flips/gimbal-locks looking straight up/down.
+- **Yaw the body (a container), pitch the camera.** Standard rig: a yaw `Object3D` holding the camera; apply yaw to the container, pitch to the camera. Movement (`moveForward/moveRight`) uses body yaw only — never pitch — so looking up doesn't make you fly.
+- **Sensitivity + optional ADS zoom:** store a base sensitivity; when aiming-down-sights, lower FOV *and* scale sensitivity down proportionally so aim feels consistent.
+- **Add ESC-to-unlock** and pause. Only re-attach the `mousemove` handler while locked; detach on unlock so a paused game doesn't rotate.
+- **Movement feel:** acceleration + friction (not instant velocity), add sprint (Shift), crouch, and subtle **head-bob** driven by a sin wave of distance traveled (disable when idle). Optional: coyote-style step-up for small ledges. Air control should be reduced vs ground.
+- **FOV:** 75–90° vertical feels good for FPS; too low feels claustrophobic, too high distorts. Let the player adjust.
+
+---
+
+## 3. Weapon handling & the viewmodel
+
+### ⚠️ Do NOT use a generated PHOTO as the weapon viewmodel.
+The single most common failure mode: the builder generates an **opaque JPG/PNG photo of a gun** and slaps it as a flat sprite/plane in the bottom-right of a 3D scene. It looks *wrong* — no parallax, wrong perspective, a hard rectangular edge, lighting that doesn't match the world, and it z-fights or clips into walls. **The world is 3D; the gun must be 3D too.**
+
+**Instead:**
+- **Build the viewmodel from 3D geometry/code** — a few boxes/cylinders (`BoxGeometry`, `CylinderGeometry`) assembled into a low-poly gun, or a proper **glTF/GLB model** (right-handed, Y-up; verify +Z-forward orientation). Even a crude boxy gun made of primitives reads far better than a photo because it has real perspective and lighting.
+- **Parent the viewmodel to the camera** (add it as a child of the camera, offset to e.g. `(0.3, -0.3, -0.6)`) so it tracks the view. Because the camera's local forward is **−Z**, the gun sits at negative Z in front of the camera.
+- **Render it so it never clips into walls.** Two robust options: (a) a **separate overlay scene + second camera** rendered after the main scene with `renderer.autoClear=false` and `renderer.clearDepth()` between passes, or (b) put the viewmodel on its own **layer** with a dedicated camera. This guarantees the gun draws on top and never intersects level geometry.
+- If you must use a texture, it must be a **transparent PNG on correctly-perspectived geometry**, never a raw opaque photo on a screen-aligned quad.
+
+### Shooting model
+- **Hitscan (raycast) for fast bullets** (pistols/rifles): on fire, `raycaster.setFromCamera({x:0,y:0}, camera)` (center of screen = crosshair) and `intersectObjects(targets)`. Take the nearest hit; apply damage. Instant, cheap, and what most shooters use.
+- **Projectiles for slow/arcing shots** (rockets, grenades): spawn a pooled mesh, move by velocity·delta, integrate gravity, and sweep-test for collisions (avoid tunneling — see bugs).
+- **Fire rate:** gate with a cooldown timer (`if (now - lastShot < fireInterval) return`), not per-frame or per-mousedown-event alone. Support hold-to-fire for automatics via a boolean set on mousedown/up.
+- **Recoil & spread:** kick the camera pitch/yaw up slightly per shot and recover over time (lerp back); add a small random cone to the ray direction that grows while firing continuously and shrinks when idle. This is 80% of "feel."
+- **Ammo + reload:** track `magazine`/`reserve`; block firing at 0; a timed reload that refills. Even a fake reload with a timer + HUD reads well.
+
+---
+
+## 4. Genre-specific "feel" (the juice)
+
+FPS feel is almost entirely feedback and responsiveness:
+- **Muzzle flash** (a brief additive sprite/light at the barrel, 1–2 frames), **shell/particle**, and a **tracer** for projectiles.
+- **Screen shake** on fire and on taking damage (small, decaying camera offset).
+- **Hitmarker** (crosshair flashes / an X appears) + **hit sound** the instant a shot lands — the game must confirm every hit.
+- **Enemy hit reaction**: flash the material, knockback, a death animation/ragdoll or a satisfying pop.
+- **Weapon sway & bob**: viewmodel lags slightly behind fast mouse movement (lerp toward target offset) and bobs while walking.
+- **Sound is half the feel**: distinct fire, impact, reload, footstep, and empty-click sounds; unlock the audio context on first gesture.
+- **Snappy input**: never add input lag; process shooting on the event but resolve in the fixed/render step. Aim assist is optional on mobile/gamepad.
+
+---
+
+## 5. Common bugs to avoid (checklist)
+
+- **Photo-as-viewmodel** (see §3) → use 3D geometry/model, render as an overlay layer.
+- **Reading `clientX/Y` instead of `movementX/Y`** while locked → camera doesn't rotate.
+- **Pitch not clamped** → camera flips upside down at the poles.
+- **Applying pitch to movement** → you "fly" when looking up. Movement uses yaw only.
+- **Firing tied to frame rate / no cooldown** → 144Hz machine empties the mag instantly.
+- **Projectile tunneling** through thin walls at high speed → use raycast sweep between last and current position, or a fixed timestep + continuous collision, not just point-in-frame checks.
+- **Raycasting from the mouse position instead of screen center** → shots miss the crosshair. Use `{x:0, y:0}` NDC (center).
+- **Viewmodel clips into walls / z-fights** → separate overlay render pass or dedicated layer + `clearDepth()`.
+- **Pointer lock never re-engages after ESC** → you didn't re-show the blocker / re-bind click on `pointerlockchange`.
+- **Not disposing enemies/bullets** → memory leak; pool projectiles and enemies.
+- **No collision** → walking through walls/floor. Add a capsule/AABB character collider (Rapier `KinematicCharacterController`).
+- **Mobile:** pointer lock is unsupported on iOS/most mobile — provide touch look/joystick + fire button fallback and don't hard-require lock.
+
+---
+
+## Defaults to apply
+
+Concrete rules to apply:
+
+1. **NEVER render a weapon as a flat generated photo/JPG in a 3D FPS.** Build the viewmodel from Three.js primitives or load a glTF model, parent it to the camera, and render it as a separate overlay pass/layer so it never clips. A boxy code-built gun > a photorealistic sprite.
+2. **Pointer lock is mandatory and gesture-gated:** click-to-play blocker, `requestPointerLock({ unadjustedMovement:true })` with fallback, read `movementX/Y`, clamp pitch to ±89°, re-show blocker on unlock.
+3. **Separate yaw (body) from pitch (camera); movement uses yaw only.**
+4. **Default to hitscan** with a raycast from screen center; gate fire with a cooldown timer; add recoil + spread + recovery. Projectiles only for slow/arcing weapons, with sweep tests to prevent tunneling.
+5. **Ship juice, not features:** muzzle flash, hitmarker, hit sound, screen shake, enemy flash-on-hit. This makes a 1-weapon demo feel like a game.
+6. **Minimal scope:** one weapon, a handful of targets/enemies, an arena with collision, and a HUD (ammo + score). Pool bullets/enemies; dispose on cleanup.
+7. **Provide a mobile fallback** (touch look + fire button) since pointer lock is desktop-only.
+
+---
+
+## Sources
+- MDN — Pointer Lock API: https://developer.mozilla.org/en-US/docs/Web/API/Pointer_Lock_API
+- MDN — `Element.requestPointerLock()` (options, `unadjustedMovement`, Promise): https://developer.mozilla.org/en-US/docs/Web/API/Element/requestPointerLock
+- MDN — pointer lock live demo: https://mdn.github.io/dom-examples/pointer-lock/
+- Three.js — `PointerLockControls` example: https://threejs.org/examples/misc_controls_pointerlock.html
+- Three.js — `Raycaster` (`setFromCamera`, `intersectObjects`): https://threejs.org/docs/#api/en/core/Raycaster
+- Three.js — layered/overlay rendering (`autoClear`, `clearDepth`, `Layers`): https://threejs.org/docs/#api/en/core/Layers
+- Rapier — Kinematic character controller: https://rapier.rs/docs/user_guides/javascript/character_controller
+- Gaffer On Games — Fix Your Timestep (projectile/physics stability): https://gafferongames.com/post/fix_your_timestep/

package/skills/grok-building-games/references/genres/platformer-2d.md

@@ -0,0 +1,97 @@
+# Genre Playbook — 2D Platformer
+
+How to build a browser 2D platformer whose jump *feels* good and whose collisions don't glitch. Default engine: **Phaser** (Arcade Physics) or a hand-rolled AABB loop on Canvas. Read `../threejs-foundational.md` first (delta time, Phaser scene/pooling rules). This file focuses on the two things that make or break a platformer: **jump feel** and **tile collision**.
+
+---
+
+## 1. Core mechanics (minimal-but-good scope for a demo)
+
+A great-feeling platformer demo needs:
+1. **A responsive jump** with the "forgiveness" features below (coyote time, jump buffer, variable height).
+2. **Solid tilemap/AABB collision** — no sticking to walls, no falling through floors, no tunneling at speed.
+3. **One-way (drop-through) platforms.**
+4. **A few hazards + a goal** (spikes/pit → respawn at last checkpoint; flag/door to win).
+5. **A camera that follows with a deadzone** and doesn't jitter.
+
+That's a complete micro-game. Skip enemies with AI, wall-jump/dash, and moving-platform edge cases until the core jump + collision feel perfect. **Jump feel is the whole genre — spend your polish budget there.**
+
+---
+
+## 2. Jump feel — the forgiveness features (do ALL of these)
+
+These are the difference between "floaty/frustrating" and "tight." Popularized by Celeste and GMTK's "Platformer Toolkit."
+
+- **Coyote time (~80–120 ms):** allow a jump for a few frames *after* the player walks off a ledge. Store `coyoteTimer`; reset to `COYOTE_TIME` while grounded, decrement each frame, and allow a jump if `coyoteTimer > 0`. Prevents "I pressed jump but it didn't register at the edge."
+- **Jump buffering (~100–150 ms):** if the player presses jump slightly *before* landing, remember it and jump the instant they touch ground. Store `jumpBufferTimer` on keypress; on landing, if `jumpBufferTimer > 0`, jump immediately.
+- **Variable jump height:** short tap = short hop, hold = full jump. On jump, set upward velocity to max. On **key release while still rising** (`velocityY < 0`), cut the velocity (e.g. `velocityY *= 0.5`). Do NOT set velocity to 0 or it looks abrupt.
+- **Asymmetric gravity:** apply **higher gravity while falling** than while rising (e.g. fall gravity ×1.5–2.5), and often a lower gravity near the jump apex ("apex hang") plus a small horizontal speed boost at apex. This is the single biggest "feel" upgrade — a pure parabola feels floaty.
+- **Clamp fall speed** (terminal velocity) so long falls stay controllable and collision stays stable.
+- **Instant-ish horizontal control:** high ground acceleration + high friction so direction changes feel snappy; reduced acceleration + a little air drag in the air. Avoid slippery ice-feel unless intended.
+
+Combine coyote + buffer + variable height + asymmetric gravity and even a placeholder box "feels like Mario."
+
+---
+
+## 3. Collision — tilemap / AABB (the #1 bug source)
+
+- **Separate the axes: resolve X, then Y (or Y then X) independently.** Move on X, resolve X collisions; then move on Y, resolve Y collisions. Resolving both at once with a single overlap vector causes corner snags and wall-sticking.
+- **Use AABB (axis-aligned bounding box) vs the tile grid.** For each move, compute which tiles the player's box overlaps (world→tile via `floor(pos / tileSize)`), and push the player out of solid tiles along the axis being resolved. This is O(overlapped tiles), not O(all tiles).
+- **Grounded detection:** you are grounded when a downward Y-resolution stopped you this frame (or a 1px probe below finds a solid tile). Set `velocityY = 0` on landing and on hitting a ceiling.
+- **Prevent tunneling at high speed:** if the player can move more than ~half a tile per frame, do **swept collision** or sub-step the movement (loop in small increments) so you never skip over a thin floor. Fixed timestep helps.
+- **Don't get stuck in seams between tiles:** when scanning multiple solid tiles, resolve using the collision on the axis of motion and skip internal edges (a tile that is adjacent to another solid tile shouldn't push you sideways). Merging colliders for runs of tiles, or ignoring faces between two solids, fixes the classic "snag on a flat floor" bug.
+- **Phaser:** use `map.setCollisionByProperty({ collides: true })` / `setCollisionBetween`, then `this.physics.add.collider(player, layer)`. Set `tile.setCollision(...)` per-side for one-ways. Arcade physics handles separation for you — trust it before hand-rolling.
+
+---
+
+## 4. One-way (drop-through) platforms
+
+- **Collide only when moving downward and coming from above.** The player passes up through the platform but lands on top.
+- **Implementation:** only resolve the collision if `velocityY >= 0` (falling) AND the player's *previous* bottom was above the platform's top last frame. Otherwise ignore it.
+- **Drop-through:** press Down (+ jump) to temporarily disable the current one-way platform for a few frames so the player falls through.
+- **Phaser Arcade:** set `tile.setCollision(false,false,true,false)` (top-only) or use `body.checkCollision.down`; or use `collider`'s `processCallback` to return false when the player is below the platform.
+
+---
+
+## 5. Camera
+
+- **Follow with a deadzone / soft zone**, not rigid lock — the camera only moves when the player leaves a central box, which kills micro-jitter. Phaser: `this.cameras.main.startFollow(player, true, lerpX, lerpY)` + `setDeadzone(w, h)`.
+- **Add look-ahead** in the direction of movement so the player sees where they're going.
+- **Clamp the camera to level bounds** (`setBounds`) so you never see past the edges.
+- **Round the camera position to whole pixels** for pixel-art games to avoid shimmer; pair with `pixelArt: true` / `roundPixels: true`.
+- Smooth vertical follow separately (or snap on landing) so jumps don't make the camera bounce.
+
+---
+
+## 6. Common bugs to avoid (checklist)
+
+- **Floaty jump** → add asymmetric gravity (heavier falling), apex hang, variable height, terminal velocity.
+- **"Jump didn't register" at edges / just before landing** → missing coyote time / jump buffering.
+- **Sticking to walls / snagging on flat floors** → resolving both axes at once, or not ignoring seams between adjacent solid tiles. Resolve axes separately.
+- **Falling through floor at high speed** → tunneling; sub-step or swept collision + fixed timestep + clamp fall speed.
+- **Can't drop through / falls through one-ways when jumping up** → one-way check must gate on downward velocity + coming-from-above.
+- **Double/infinite jump** → grounded flag not reset correctly; only allow jump when grounded OR coyote timer > 0, and consume the buffer.
+- **Camera jitter** → no deadzone / not pixel-rounded / following unsmoothed physics position.
+- **Movement frame-rate dependent** → scale by delta (Phaser gives you `delta`; Arcade integrates for you, but custom code must use it).
+- **Getting stuck when spawning inside a tile** → validate spawn/respawn points are in empty space.
+
+---
+
+## Defaults to apply
+
+1. **Always implement the "forgiveness trio": coyote time (~0.1s), jump buffering (~0.12s), and variable jump height (cut velocity on early release).** These are cheap and are the difference between a good and bad platformer. Bake them into any generated platformer by default.
+2. **Use asymmetric gravity (heavier when falling) + terminal velocity + apex hang.** Never ship a symmetric-parabola jump.
+3. **Resolve collision one axis at a time (X then Y) against an AABB/tile grid; sub-step fast movement to prevent tunneling.** Prefer Phaser Arcade's collider over hand-rolled math when possible.
+4. **One-way platforms: collide only when falling and coming from above; Down = drop through.**
+5. **Camera: follow with a deadzone + look-ahead, clamp to bounds, round to pixels for pixel art.**
+6. **Minimal scope:** tight jump + solid collision + one-ways + hazards/checkpoint + goal. Polish the jump before adding enemies.
+
+---
+
+## Sources
+- GMTK — "Why Does Celeste Feel So Good to Play" / Platformer Toolkit (coyote time, buffering, variable jump): https://www.youtube.com/watch?v=yorTG9at90g
+- GMTK Platformer Toolkit (interactive): https://gmtk.itch.io/platformer-toolkit
+- "Coyote Time and Jump Buffering" (Nathan Hoad / common write-ups): https://nathanhoad.net/coyote-time-and-jump-buffering
+- MDN — 2D breakout/AABB collision detection basics: https://developer.mozilla.org/en-US/docs/Games/Techniques/2D_collision_detection
+- Phaser — Tilemaps & Arcade Physics collision: https://docs.phaser.io/phaser/concepts/tilemaps and https://docs.phaser.io/phaser/concepts/physics/arcade
+- "Rendering Tile-Based Worlds" / one-way platforms (MaddyThorson / Celeste dev notes): https://maddythorson.medium.com/
+- Red Blob Games — grid/tile math reference: https://www.redblobgames.com/