@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.9

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

@@ -1,89 +0,0 @@
-# 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

@@ -1,83 +0,0 @@
-# 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

@@ -1,105 +0,0 @@
-# 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

@@ -1,97 +0,0 @@
-# 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/

package/skills/grok-building-games/references/genres/puzzle-match3-tetris.md

@@ -1,131 +0,0 @@
-# Genre Playbook — Grid Puzzle (Match-3 & Tetris)
-
-Grid-based puzzlers (Bejeweled/Candy Crush match-3, Tetris) live or die on **a clean grid data model** and **exactly-correct board logic**. Both are 2D — Canvas/Phaser/DOM all work; the board is data, the rendering is a thin view. Read `../threejs-foundational.md` first (delta time, pooling). This file gives the precise algorithms, including the full **SRS wall-kick tables** (verbatim from the Tetris wiki).
-
----
-
-## 0. The golden rule: separate model from view
-
-**The board is a 2D array of ints/enums; rendering reads from it.** Never store game state in sprite positions or the DOM. All logic (matches, gravity, rotation, collision) runs on the array; then you sync visuals (tween pieces to their cell). This prevents the entire class of "the animation and the logic disagree" bugs.
-
----
-
-# Part A — Match-3 (Bejeweled / Candy Crush)
-
-## A1. Core mechanics & minimal scope
-1. A **grid** (e.g. 8×8) of colored gems (`grid[row][col] = colorId`).
-2. **Swap two adjacent gems** (click-click or drag); the swap is only legal if it creates a match.
-3. **Match detection** (3+ in a row/column) → clear.
-4. **Gravity** (gems above fall into gaps) + **refill** (new gems drop from the top).
-5. **Cascades** (chain reactions) scored with a multiplier, and a score/moves HUD.
-
-That's a complete match-3. Add special gems, objectives, and levels later.
-
-## A2. Match detection
-- **Scan rows and columns for runs of ≥3 identical colors.** The simplest robust method: for each cell, count consecutive same-color horizontally and vertically; mark any run of length ≥3. Collect all marked cells into a set (so an L/T shape counts once).
-- **Flood fill** is the right tool when matches aren't strictly lines (e.g. same-color blobs, or Puyo Puyo–style groups): from each unvisited cell, BFS/DFS to all 4-connected same-color neighbors; if the connected group size ≥ threshold, it's a match. Use flood fill for group-clear variants and for detecting connected clusters after cascades.
-- **Swap validation:** perform the swap in the array, run match detection; if no match results, **swap back** (and animate the reversal). Only commit swaps that match.
-- **Initial board must have no pre-existing matches** and should have at least one valid move — generate, then re-roll any accidental matches; optionally verify a move exists (shuffle if deadlocked).
-
-## A3. Gravity, refill & cascades
-- **Clear** matched cells (set to empty), award score.
-- **Gravity:** for each column, compact non-empty cells downward (iterate from the bottom, pull the next non-empty cell down). Do this on the array first.
-- **Refill:** fill the now-empty top cells with new random gems.
-- **Cascade loop:** after gravity+refill, **run match detection again**; if new matches formed, clear/score them (with an increasing chain multiplier) and repeat until stable. This loop is the satisfying core — don't stop after one pass.
-- **Animate after resolving:** compute the whole settled state, then tween gems to their new cells (falling animation). Lock input while the board is resolving.
-
----
-
-# Part B — Tetris
-
-## B1. Core mechanics & minimal scope
-1. A **playfield** (standard 10 wide × 20 visible, plus hidden rows above for spawning).
-2. **7 tetrominoes** (I, O, T, S, Z, J, L) each with 4 rotation states.
-3. **Gravity** (piece falls on a timer), **soft/hard drop**, **move left/right**, **rotate CW/CCW**.
-4. **Line clears** (full rows removed, rows above shift down) + scoring.
-5. **Spawn next piece; game over** when a new piece can't spawn.
-
-Guideline-quality Tetris additionally needs: **7-bag randomizer**, **SRS rotation + wall kicks**, **lock delay**, ghost piece, hold, and a next-queue. Do these — they're what players expect.
-
-## B2. Data model & collision
-- Represent each piece as a set of 4 cell offsets for its current rotation state, plus a board position `(x, y)`. The board is `grid[row][col]`.
-- **Collision test:** a move/rotation is valid iff every one of the piece's 4 cells is in-bounds and lands on an empty board cell. Check *before* committing any move.
-- **Move/rotate = test the target; if valid, apply; else reject** (rotation additionally tries wall kicks, below).
-- **Line clear:** find full rows, remove them, shift everything above down, and clear the freed top rows. Award by lines cleared at once (1=Single … 4=Tetris) — Tetris (4) scores far more, incentivizing well-building.
-
-## B3. Randomizer, gravity, lock delay
-- **7-bag randomizer (mandatory for modern feel):** shuffle a bag of all 7 pieces, deal them out, refill/reshuffle when empty. Guarantees no long droughts and no floods of one piece. Pure random feels bad.
-- **Gravity:** drop one row every `fallInterval` (decreasing with level). **Soft drop** = faster fall; **hard drop** = instantly place at the lowest valid position (+ small score per cell).
-- **Lock delay (~0.5s):** when a piece lands (can't fall further), don't lock it immediately — give a short window during which moving/rotating keeps it alive. Standard is a **move/rotation reset limited to ~15 resets** (so you can't stall forever). Without lock delay the game feels harsh; with an unlimited reset you can stall infinitely — cap the resets.
-- **DAS/ARR:** delayed auto-shift (a pause before a held direction auto-repeats) + auto-repeat rate. Tune these — they define movement feel for skilled play.
-
-## B4. SRS rotation & wall kicks (verbatim tables)
-
-**Rotation states:** `0` = spawn, `R` = one CW from spawn, `L` = one CCW from spawn, `2` = 180°.
-When a rotation is attempted, test **5 offsets in order**; use the first that fits; if none fit, the rotation fails entirely.
-
-**⚠️ Coordinate convention:** these tables use **x = right positive, y = UP positive**. If your grid's row index increases *downward* (the usual case), **negate the y value** when applying kicks (a `+2` up becomes `row − 2`). Getting this sign wrong is the #1 SRS bug.
-
-**J, L, S, T, Z kick data** (all share one table):
-```
-0->R:  (0,0) (-1,0) (-1,+1) (0,-2) (-1,-2)
-R->0:  (0,0) (+1,0) (+1,-1) (0,+2) (+1,+2)
-R->2:  (0,0) (+1,0) (+1,-1) (0,+2) (+1,+2)
-2->R:  (0,0) (-1,0) (-1,+1) (0,-2) (-1,-2)
-2->L:  (0,0) (+1,0) (+1,+1) (0,-2) (+1,-2)
-L->2:  (0,0) (-1,0) (-1,-1) (0,+2) (-1,+2)
-L->0:  (0,0) (-1,0) (-1,-1) (0,+2) (-1,+2)
-0->L:  (0,0) (+1,0) (+1,+1) (0,-2) (+1,-2)
-```
-
-**I piece kick data** (its own table):
-```
-0->R:  (0,0) (-2,0) (+1,0) (-2,-1) (+1,+2)
-R->0:  (0,0) (+2,0) (-1,0) (+2,+1) (-1,-2)
-R->2:  (0,0) (-1,0) (+2,0) (-1,+2) (+2,-1)
-2->R:  (0,0) (+1,0) (-2,0) (+1,-2) (-2,+1)
-2->L:  (0,0) (+2,0) (-1,0) (+2,+1) (-1,-2)
-L->2:  (0,0) (-2,0) (+1,0) (-2,-1) (+1,+2)
-L->0:  (0,0) (+1,0) (-2,0) (+1,-2) (-2,+1)
-0->L:  (0,0) (-1,0) (+2,0) (-1,+2) (+2,-1)
-```
-
-**O piece does not kick** (it never needs to — its rotation is trivial; only its rotation center appears to move).
-
-**Algorithm:** to rotate, compute the piece cells in the target state (pure rotation about the piece center), then for each of the 5 `(dx, dy)` offsets for that specific `from->to` transition, test the piece translated by `(dx, -dy)` (if y is down); apply the first that fits. If all 5 fail, cancel. This is what enables T-spins and squeezing the I-piece into tight wells.
-
-## B5. Match-3 & Tetris common bugs (checklist)
-- **State stored in sprites/DOM instead of an array** → logic/animation desync. Model is the array.
-- **(Match-3) Not swapping back on a non-matching swap** → illegal moves stick.
-- **(Match-3) Cascade loop stops after one pass** → miss chain reactions; loop until stable.
-- **(Match-3) Initial board has matches or no valid moves** → re-roll on generate; detect deadlock and shuffle.
-- **(Tetris) Pure random piece order** → droughts feel awful; use a 7-bag.
-- **(Tetris) SRS y-sign flipped** → wall kicks push pieces the wrong way; negate y for a downward-row grid.
-- **(Tetris) Wrong/omitted kick table** → no T-spins, I-piece won't fit tight spots; use the exact 5-offset tables per transition (I has its own; O doesn't kick).
-- **(Tetris) No lock delay, or unlimited reset** → either too harsh, or you can stall forever; cap resets (~15).
-- **(Tetris) Line clear shifts rows incorrectly** → clear from the model, shift above down, clear freed top rows; test multi-line clears.
-- **(Tetris) Collision checked after committing** → test the target position first, commit only if valid.
-- **Timing tied to frame rate** → gravity/fall interval must use delta/real time.
-
----
-
-## Defaults to apply
-
-1. **Model = 2D array; view is a thin renderer that tweens to cells.** Run all logic on the array, then animate. Lock input while resolving.
-2. **Match-3: swap → detect → (if no match) swap back; clear → gravity → refill → re-detect in a cascade loop until stable.** Use line-scan for line matches and **flood fill** for connected-group/blob matches. Generate boards with no initial matches and at least one move.
-3. **Tetris: implement the full guideline — 7-bag randomizer, SRS with the exact wall-kick tables above, lock delay with capped resets, hard/soft drop, ghost piece, hold, next queue.** Players expect all of it.
-4. **SRS: mind the y-sign** (tables are y-up; negate for row-down grids). I-piece uses its own kick table; O doesn't kick.
-5. **Always test a move/rotation against the model before committing; reject if any cell is out of bounds or occupied.**
-6. **Both genres are timer-driven** — use delta/real time for fall speed and animations, never per-frame.
-
----
-
-## Sources
-- Hard Drop Tetris Wiki — SRS (spawn, rotation, and the verbatim wall-kick tables above): https://harddrop.com/wiki/SRS
-- Hard Drop Tetris Wiki — Wall kick: https://harddrop.com/wiki/Wall_kick
-- Hard Drop Tetris Wiki — Lock delay: https://harddrop.com/wiki/Lock_delay
-- Hard Drop Tetris Wiki — Random Generator (7-bag): https://harddrop.com/wiki/Random_Generator
-- Tetris Guideline (official standard): https://tetris.wiki/Tetris_Guideline
-- "Tetris" implementation guide (javidx9 / general): https://tetris.wiki/Tetris_(NES,_Nintendo)
-- Wikipedia — Flood fill (BFS/DFS): https://en.wikipedia.org/wiki/Flood_fill
-- Bejeweled/Candy Crush match-3 algorithm write-ups (match detection + cascade): https://www.emanueleferonato.com/2018/07/13/build-a-html5-match-3-game-using-phaser/