@inneranimalmedia/agentsam-sdk 2.6.5 → 2.6.7

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

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

package/skills/grok-building-games/references/genres/racing-kart.md

@@ -0,0 +1,106 @@
+# Genre Playbook — Arcade Racing / Kart
+
+Arcade racing (Mario Kart, not a sim) is about **forgiving, exciting handling**, satisfying **drift**, and correct **lap/checkpoint** logic. Default engine: **Three.js/Babylon.js** (3D) with a simple arcade car model — do **not** reach for a full rigid-body vehicle sim for a demo. Read `../threejs-foundational.md` first (delta time, follow camera, forward-axis convention, disposal).
+
+---
+
+## 1. Core mechanics (minimal-but-good scope for a demo)
+
+1. **Arcade car handling** — accelerate, brake/reverse, steer; grippy but slidey (see §2).
+2. **Drift** with a boost payoff (the fun core of kart racers).
+3. **A looping track** with walls/boundaries and ground collision.
+4. **Checkpoints + lap counting** that can't be cheated by cutting the course.
+5. **A follow (chase) camera** and a HUD (speed, lap X/N, lap time).
+
+One car, one track, 3 laps, a lap timer, and drift-boost is a complete game. Add opponents (even simple waypoint-followers), items, and multiple tracks later. **Handling feel + drift are the whole genre — tune them first.**
+
+---
+
+## 2. Arcade handling (pseudo-physics, not a sim)
+
+Model the car as a point/box with a **heading (yaw)**, a **forward speed**, and a small amount of lateral slide. Avoid full tire-slip simulation.
+
+- **Acceleration:** `speed += throttle * accel * delta`, clamp to `maxSpeed`. Reverse/brake applies negative accel with a lower cap.
+- **Drag + rolling resistance:** each frame `speed *= (1 - drag*delta)` (and stronger when off throttle) so the car coasts to a stop. Add higher drag off-track (grass/sand) to punish going wide.
+- **Steering scales with speed, not constant:** turn rate should be low at very low speed (can't turn a parked kart much) and taper at very high speed so it isn't twitchy. A common trick: `turn = steerInput * baseTurn * clamp(speed / someSpeed, 0, 1)`. Reverse the steering sign when moving backward.
+- **Steer sign (must not invert):** full rules live in the **`controls` skill**
+  (`.grok/skills/controls/SKILL.md`) — open it for **any** vehicle, not only
+  karts. Summary: while `speed > 0` and the chase camera is behind the car,
+  **A / ← turns left**, **D / → turns right**. With
+  `forward = (-sin(yaw), 0, -cos(yaw))`, **KeyA must yield +yaw**
+  (`steer = +1` on A, then `yaw += steer * turnRate * …`). The classic bug is
+  `KeyA → steer = -1` with `yaw += steer * +rate` (A turns right). Run the
+  `controls` self-test before shipping; do **not** use FPS strafe as a steer test.
+- **Apply yaw, then move along heading:** rotate the car by `turn * delta`, then translate along its forward vector by `speed * delta`. Keep a little **lateral velocity** that decays (grip) so the car feels weighty rather than on rails.
+- **Grip model (simple):** split velocity into forward and sideways components; kill most of the sideways component each frame (high grip) — reducing how much you kill it is exactly what creates drift.
+- **Keep the car on the ground:** raycast down to the track to set height/normal (handles hills/banking) rather than full suspension. Align the car's up to the surface normal for looks.
+
+---
+
+## 3. Drift (the payoff mechanic)
+
+- **Drift = temporarily reduce lateral grip** (let more sideways velocity survive) while the player holds a drift/handbrake button and steers, so the car slides through the corner with the nose pointing inward.
+- **Hop-then-drift (kart style):** a small hop initiates the drift; holding it while turning builds a **drift charge** over time.
+- **Mini-turbo / boost payoff:** the longer/tighter the drift, the bigger the speed boost on release (stage it: blue → orange sparks). This risk/reward loop *is* kart racing.
+- **Visual/audio feedback:** tire-skid marks (decals), drift particles/sparks that change color with charge, tire-screech sound, and a slight camera FOV kick on boost. Feedback sells the drift.
+- **Countersteer feel:** while drifting, let the player modulate the slide angle with steering; snap back to grip smoothly on release (don't instantly zero the lateral velocity — lerp it).
+
+---
+
+## 4. Checkpoints & laps (get this right or laps break)
+
+- **Place ordered checkpoints around the track** (invisible trigger volumes/gates), including a start/finish line. Store the count `N`.
+- **Require sequential passing:** track `nextCheckpoint`. A checkpoint only counts if it's the expected next one; passing them out of order (or driving backward) does nothing. This **prevents lap-skipping / reverse-cheesing** — the classic bug where crossing the finish line repeatedly racks up laps.
+- **Count a lap** only when the player crosses the finish line *after* hitting all checkpoints for that lap; then reset `nextCheckpoint` to 0.
+- **Detect crossing with trigger overlap** (AABB/sphere against the car), and for fast cars use a **swept/segment test** (did the car's path this frame cross the gate plane?) so you don't tunnel through a thin checkpoint at high speed.
+- **Respawn / rescue:** if the car flips, leaves the track, or stalls, respawn it at the **last passed checkpoint** facing forward. Also use checkpoints for "wrong way" detection.
+- **HUD:** current lap / total, current + best lap time, position. Freeze the timer at finish.
+
+---
+
+## 5. Camera
+
+- **Chase camera behind & slightly above the car**, following with **lerp/spring** (position and look-at both smoothed) so it lags a touch and swings on turns — this conveys speed. `camera.position.lerp(targetBehindCar, k)`; `camera.lookAt(carPosition + lookAhead)`.
+- **Speed FOV:** widen FOV slightly at high speed / on boost and narrow when slow — a strong, cheap sense of speed.
+- **Don't rigidly parent the camera to the car** or it feels stiff and induces motion sickness; smoothing is essential. Add a tiny bit of positional damping, not rotational snapping.
+- Offer a couple of views (chase / hood) if easy. Add motion lines / ground blur / roadside object density for speed sensation.
+- Mind the forward-axis convention (camera looks down −Z; car "front" should be +Z or handled via `lookAt`).
+
+---
+
+## 6. Common bugs to avoid (checklist)
+
+- **Lap counter increments on any finish-line crossing** → require all checkpoints in order before counting a lap.
+- **Player skips/cuts the track to cheat laps** → sequential-checkpoint gating + wrong-way detection.
+- **Car tunnels through walls/checkpoints at speed** → swept/segment collision, not just per-frame overlap; consider fixed timestep.
+- **Steering identical at all speeds** → twitchy when fast, unturnable when slow; scale turn rate by speed and flip sign in reverse.
+- **A/D reversed while driving forward** → `steerInput` sign disagrees with the
+  `forward`/`yaw` basis; re-check the vehicle self-test (A turns left at speed > 0),
+  not the FPS D→+X strafe test.
+- **Car feels on rails or uncontrollably slidey** → tune the grip (how much lateral velocity you kill per frame); drift = temporarily reduce that.
+- **Camera stiff / nausea-inducing** → smooth (lerp/spring) both position and look-at; don't hard-parent.
+- **Movement/steer not delta-scaled** → frame-rate dependent handling.
+- **Car floats above/sinks into hills** → raycast to ground for height + surface normal each frame.
+- **No off-track penalty** → add drag/slowdown on grass so cutting corners costs speed.
+
+---
+
+## Defaults to apply
+
+1. **Use arcade pseudo-physics, not a rigid-body sim:** heading + forward speed + decaying lateral velocity; drag for coasting; steering that scales with speed. Grippy-but-slidey.
+2. **Ship drift with a boost payoff** (reduce lateral grip while held + charge → mini-turbo on release, with sparks/skid feedback). This is the genre's hook.
+3. **Lap logic MUST use ordered checkpoints:** a lap counts only after all checkpoints are passed in sequence, then the finish line. Prevents skip/reverse cheating. Respawn at last checkpoint.
+4. **Use swept collision for walls and checkpoint gates** so fast cars don't tunnel.
+5. **Chase camera with smoothing + speed-based FOV** for the sense of speed; never hard-parent.
+6. **Minimal scope:** one car, one looping track with checkpoints/laps/timer, drift-boost, HUD. Opponents/items come later.
+7. **Steer self-test before done:** `speed > 0`, hold A → turns left; hold D → turns right (chase cam). Fail = not done.
+
+---
+
+## Sources
+- "How to make an arcade car / kart handling model" (community write-ups, e.g. Kenney/CodinGame arcade car): https://github.com/spacejack/carphysics2d and demo https://spacejack.github.io/carphysics2d/
+- Marco Monster — "Car Physics for Games" (classic arcade/sim reference): https://asawicki.info/Mirror/Car%20Physics%20for%20Games/Car%20Physics%20for%20Games.html
+- Three.js — chase/follow camera & `Object3D.lookAt`: https://threejs.org/docs/#api/en/core/Object3D.lookAt
+- Three.js — `Raycaster` (ground/height sampling): https://threejs.org/docs/#api/en/core/Raycaster
+- Gaffer On Games — Fix Your Timestep (stable vehicle integration / no tunneling): https://gafferongames.com/post/fix_your_timestep/
+- Red Blob Games — line-segment intersection (checkpoint crossing tests): https://www.redblobgames.com/

package/skills/grok-building-games/references/genres/topdown-twin-stick.md

@@ -0,0 +1,97 @@
+# Genre Playbook — Top-Down / Twin-Stick Shooter
+
+Top-down action where you **move with one input and aim with another** (mouse+WASD on desktop, two virtual sticks on mobile, or left/right stick on gamepad). Think Enter the Gungeon, Nuclear Throne, Vampire Survivors, .io shooters. Default engine: **Phaser** (2D) or Three.js with an orthographic/top camera. Read `../threejs-foundational.md` first (delta time, pooling, mobile joysticks).
+
+---
+
+## 1. Core mechanics (minimal-but-good scope for a demo)
+
+1. **Decoupled move + aim** (the defining feature — see §2).
+2. **A shooting weapon** with pooled bullets and a fire-rate cooldown.
+3. **Enemies that spawn and chase** the player (simple seek/steering), with hit + death.
+4. **Collision:** player↔walls, bullets↔enemies, enemies↔player (damage), plus screen/arena bounds.
+5. **HUD:** health + score/wave; a game-over + restart.
+
+A single weapon + one enemy type spawning in waves + juicy hit feedback is already a fun loop (Vampire Survivors shipped on essentially this). Add pickups/upgrades only after the core loop is fun.
+
+---
+
+## 2. Controls & aiming (the twin-stick core)
+
+- **Movement is independent of facing.** Move on a normalized vector; aim on a separate vector. This is *the* genre feature — never couple them (that's a tank/first-person control scheme, not twin-stick).
+- **Desktop:** WASD/arrows → move vector; mouse position → aim. Aim angle = `Math.atan2(mouse.y - player.y, mouse.x - player.x)` **in world space** (convert screen→world with the camera scroll/zoom, not raw clientX/Y). Left click = fire.
+- **Gamepad:** left stick = move, right stick = aim/fire (fire when the right stick is deflected past a deadzone). Apply a **radial deadzone** (`if (len < 0.2) zero it`) and optionally re-scale so the edge maps to full speed.
+- **Mobile:** two virtual joysticks (e.g. nipplejs) — left = move, right = aim/fire. Auto-fire while the aim stick is held is friendlier than a separate button.
+- **Normalize the movement vector** before applying speed so diagonal movement isn't ~1.41× faster (the classic "faster on diagonals" bug). `vec.normalize().scale(speed * delta)`.
+- **Rotate the sprite/mesh to the aim angle**, not the move angle. In Phaser remember sprites face "right" (0 rad) by default; offset art accordingly. In Three.js top-down, rotate around the up axis and mind the +Z/−Z forward convention.
+- **Optional auto-aim / aim-assist** (snap to nearest enemy) is great on mobile and for accessibility.
+
+---
+
+## 3. Camera
+
+- **Follow the player centered**, ideally with a small deadzone and **look-ahead toward the aim/mouse** (offset the camera partway toward the cursor) so you see more of where you're shooting.
+- **Clamp to level bounds**; for arena games, a fixed camera showing the whole arena is also fine.
+- Keep it smooth (lerp) but not laggy; snap on teleport/respawn.
+- Phaser: `cameras.main.startFollow(player, true, 0.1, 0.1)` + `setBounds` + `setDeadzone`.
+
+---
+
+## 4. Bullets, enemies & performance
+
+- **Pool everything.** Twin-stick games spawn hundreds of bullets and enemies. Use object pools (Phaser Groups with `maxSize`, or a preallocated array) — never create/destroy per shot. Recycle by toggling `active/visible`.
+- **Bullets:** move by velocity·delta; despawn on wall hit, enemy hit, or when off-screen/out of range/TTL. Prefer circle-vs-circle overlap for bullet↔enemy (cheap and forgiving).
+- **Enemy steering:** simplest good-enough is **seek** — velocity toward `(player - enemy).normalize() * speed`. Add **separation** (push apart from nearby enemies) so they don't stack into one blob. For walls, either use physics colliders or simple flow-field/grid pathfinding for larger maps.
+- **Broad-phase collision** when counts are high: spatial hash / uniform grid so you only test nearby pairs, not O(n²). Phaser Arcade has a grid/tree internally; hand-rolled Canvas needs its own.
+- **Spawn waves** with a timer + difficulty curve (rate and enemy count rising over time). Spawn off-screen at the arena edge, not on top of the player.
+- **Cap concurrent entities** to protect frame rate; degrade gracefully (fewer particles) on mobile.
+
+---
+
+## 5. Genre-specific "feel" (the juice)
+
+- **Screen shake** on shooting and explosions (small, decaying).
+- **Hit flash** (tint enemy white for 1–2 frames) + **knockback** + **hit-stop** (freeze the game for a few ms on a big hit) — hit-stop is a huge, cheap feel win.
+- **Muzzle flash, bullet tracers, and impact particles.**
+- **Enemy death**: pop into particles/gibs + a sound + score popup + occasional slow-mo on a big kill.
+- **Weapon feel:** spread/recoil for shotguns, fast tiny bullets for SMGs; controller rumble if available.
+- **Readable bullets:** player bullets and enemy bullets must be visually distinct (color/size) so the player can dodge — critical in bullet-hell density.
+- **Sound** for fire, hit, death, pickup; unlock audio on first gesture.
+
+---
+
+## 6. Common bugs to avoid (checklist)
+
+- **Faster movement on diagonals** → normalize the move vector before scaling by speed.
+- **Coupling aim to movement** → they must be independent (that's the whole genre).
+- **Aiming off by camera offset/zoom** → convert screen coords to world coords using the camera; don't use raw clientX/Y.
+- **Sprite faces wrong direction** → account for the engine's default facing (Phaser sprites face +X/0 rad) and 3D forward-axis convention.
+- **No radial deadzone on gamepad** → stick drift makes the player spin/creep.
+- **Creating/destroying bullets & enemies each frame** → GC stutter; pool them.
+- **O(n²) collision with many entities** → use a spatial grid/hash for broad-phase.
+- **Enemies stacking into one sprite** → add separation steering.
+- **Enemies spawning on top of the player** → spawn at arena edges/off-screen.
+- **Bullets living forever** → give them a TTL/range and despawn off-screen.
+- **Movement not delta-scaled** → frame-rate dependent speed.
+
+---
+
+## Defaults to apply
+
+1. **Decouple move and aim by default** — WASD/left-stick move + mouse/right-stick aim; auto-fire on mobile. This one choice defines the genre.
+2. **Always normalize the movement vector** so diagonals aren't faster; apply a **radial deadzone** for sticks; convert mouse→world coords for aim angle.
+3. **Pool bullets and enemies; use a spatial grid for collision** when counts get high; cap entities on mobile.
+4. **Enemy AI = seek + separation** (+ simple wave spawner at edges). Good enough to be fun without pathfinding.
+5. **Feel = hit flash + hit-stop + screen shake + score popups + distinct player/enemy bullet colors.** Cheap, huge payoff.
+6. **Minimal scope:** one weapon, one enemy type, wave spawner, health/score HUD, game-over/restart. That's a complete loop.
+
+---
+
+## Sources
+- MDN — 2D collision detection (circle/AABB): https://developer.mozilla.org/en-US/docs/Games/Techniques/2D_collision_detection
+- Red Blob Games — 2D visibility, grids, pathfinding, and vector math: https://www.redblobgames.com/
+- Steering Behaviors (Reynolds — seek/flee/separation), classic reference: https://www.red3d.com/cwr/steer/
+- Phaser — cameras (follow, deadzone, bounds): https://docs.phaser.io/phaser/concepts/cameras
+- Phaser — Groups & object pooling: https://docs.phaser.io/phaser/concepts/gameobjects/group
+- nipplejs (mobile virtual joysticks): https://github.com/yoannmoinet/nipplejs
+- MDN — Gamepad API (deadzones, axes): https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API

package/skills/grok-building-games/references/genres/tower-defense.md

@@ -0,0 +1,84 @@
+# Genre Playbook — Tower Defense
+
+Place towers on a grid to stop waves of enemies walking a path to your base. The genre is fundamentally about **a grid, pathfinding, targeting, and economy**. 2D (Phaser/Canvas) or 3D top-down (Three.js). Read `../threejs-foundational.md` first (delta time, pooling, top-down camera).
+
+---
+
+## 1. Core mechanics (minimal-but-good scope for a demo)
+
+1. **A grid map** with a defined enemy **path** from spawn to the base.
+2. **Enemies that walk the path** in timed **waves**, with HP and speed.
+3. **Tower placement** on buildable cells, costing money.
+4. **Towers that target + shoot** enemies in range (projectile or hitscan), dealing damage.
+5. **Economy + lives:** kills give gold; leaks cost lives; game over at 0 lives. Wave counter + "start next wave" button.
+
+One tower type, one enemy type, a fixed path, 5–10 escalating waves, gold, and lives is a complete game. Add tower types/upgrades, enemy variety (fast/armored/flying), and maze-building later. **Fixed-path TD is much simpler and less bug-prone than maze/free-build TD — default to it for demos.**
+
+---
+
+## 2. Map, path & pathfinding
+
+- **Two flavors — pick deliberately:**
+  - **Fixed path (recommended default):** the path is authored (a polyline / ordered list of waypoints). Enemies just follow waypoints. No runtime pathfinding, no way to trap enemies — far fewer bugs.
+  - **Maze / free-build:** players place towers anywhere and enemies pathfind around them (Bloons-style is fixed; Desktop TD is maze). Requires **A\*** re-pathing and a critical rule: **never allow a placement that fully blocks the path** — validate with a pathfinding check before committing, and reject if no route remains.
+- **Grid model:** a 2D array of cells with types (path / buildable / blocked / spawn / base). Convert world↔grid with `floor(pos / cellSize)`. Snap tower placement to cell centers.
+- **A\* (maze TD):** grid neighbors (4- or 8-connected), Manhattan/octile heuristic. Recompute affected enemies' paths when a tower is placed/sold. Cache the path; only recompute on change. See Red Blob Games' A* guide (canonical).
+- **Waypoint following (fixed path):** each enemy stores its target waypoint index; move toward it by `speed*delta`; when within a small epsilon, advance to the next; reaching the end = a "leak" (lose a life, despawn).
+
+---
+
+## 3. Towers: targeting, range & firing
+
+- **Range check:** distance (squared, to avoid sqrt) from tower to enemy ≤ range². Use a **spatial grid/quadtree** for broad-phase if there are many enemies — don't test every tower against every enemy each frame (O(towers×enemies)).
+- **Targeting policy (make it explicit & selectable):** common options — **First** (furthest along the path, the usual default), **Last**, **Closest**, **Strongest (most HP)**, **Weakest**. "First" is the standard because it stops leaks best. Ambiguous/implicit targeting is a common complaint — pick and document one.
+- **Fire rate:** cooldown timer per tower (`if (now - lastFire >= 1/fireRate) fire()`), delta-based, not per-frame.
+- **Projectiles vs hitscan:** projectiles (pooled) that travel and can **home** on the target or aim at a **lead/predicted position** feel better and enable "miss if enemy dies mid-flight." Hitscan (instant damage + a drawn beam) is simpler and fine for lasers. Pool projectiles.
+- **Damage types & AoE:** splash damage hits enemies within a radius of impact; slow/poison apply timed status effects. Even one splash tower adds a lot of depth.
+- **Rotate the tower/turret to face its target** (mind facing conventions). Show range as a ring on hover/selection.
+- **Upgrades/selling:** click a tower → upgrade (more damage/range/rate) or sell for partial refund.
+
+---
+
+## 4. Waves & economy (the balance core)
+
+- **Wave data as configuration**, not hardcoded logic: a list of waves, each a list of `{enemyType, count, spawnInterval, delay}`. Easy to tune and extend.
+- **Escalation:** later waves have more/tougher/faster enemies; introduce armored (reduce non-piercing damage), fast, and flying (only certain towers hit) types over time.
+- **Economy loop:** enemies give gold on death; towers/upgrades cost gold; a leak costs a life. Tune so the player is always a little short — that tension is the game. Give inter-wave prep time and optionally a bonus for starting the next wave early.
+- **Lives + win/lose:** lose a life per leak, game over at 0; win by surviving all waves (or endless mode with scaling).
+- **Boss waves** for pacing spikes.
+
+---
+
+## 5. Common bugs to avoid (checklist)
+
+- **(Maze TD) Placement that fully blocks the path** → always run a pathfinding validity check before allowing placement; reject if no route to base remains.
+- **Enemies overshoot/orbit waypoints** → advance when within an epsilon distance and clamp the final step so they don't jitter around the point.
+- **O(towers×enemies) targeting each frame** → use squared-distance checks + a spatial grid/quadtree for broad-phase.
+- **Ambiguous targeting** → choose an explicit policy (default "First"), make it consistent and ideally player-selectable.
+- **Projectiles chasing dead enemies / never expiring** → give projectiles a target ref + TTL; on target death, either retarget, continue to last position, or despawn.
+- **Fire rate frame-rate dependent** → cooldown by delta time, not per frame.
+- **Building on path/occupied cells** → validate cell type + occupancy before placing; snap to grid.
+- **Economy exploits** → full-refund sell + rebuild loops; use partial refunds; validate gold on every transaction.
+- **Not pooling enemies/projectiles** → GC stutter in big waves.
+- **Enemies overlapping into one blob** → optional separation, or just accept single-file on a fixed path.
+
+---
+
+## Defaults to apply
+
+1. **Default to fixed-path (waypoint) TD** for demos — no runtime pathfinding, dramatically fewer bugs. Offer maze/A* only when explicitly wanted.
+2. **If maze/free-build: NEVER allow a tower placement that fully blocks the path** — validate with an A* reachability check before committing.
+3. **Grid-based map + snap placement; validate cell buildability + gold before placing.**
+4. **Explicit, selectable targeting policy (default "First"); squared-distance range checks + spatial grid** for performance. Pool projectiles/enemies.
+5. **Wave and enemy stats as data/config, not code** — makes balancing and expansion trivial.
+6. **Tune the economy tight** (gold from kills, cost of towers, lives from leaks) — the shortage-driven tension is the fun. Minimal scope: 1 tower, 1 enemy, fixed path, escalating waves, gold + lives.
+
+---
+
+## Sources
+- Red Blob Games — Introduction to A* / pathfinding (the canonical grid pathfinding reference): https://www.redblobgames.com/pathfinding/a-star/introduction.html
+- Red Blob Games — Grids, hexagons, and tile math: https://www.redblobgames.com/grids/
+- MDN — 2D collision / distance checks: https://developer.mozilla.org/en-US/docs/Games/Techniques/2D_collision_detection
+- Phaser — Groups & pooling (projectiles/enemies): https://docs.phaser.io/phaser/concepts/gameobjects/group
+- "Tower Defense targeting priorities" (Bloons/Desktop TD community references): https://bloons.fandom.com/wiki/Targeting_Priority
+- Amit Patel / Red Blob — implementation notes on flow fields for many-agent pathing: https://www.redblobgames.com/pathfinding/tower-defense/

package/skills/grok-building-games/references/genres/voxel-minecraft.md

@@ -0,0 +1,89 @@
+# Genre Playbook — Voxel / Minecraft-like
+
+Block worlds you can walk, build, and mine. In the browser this is a **Three.js/WebGL performance problem first, game second** — the naive approach (one cube mesh per block) melts instantly. The whole genre is about **chunking, face culling, greedy meshing, and voxel raycasting**. Read `../threejs-foundational.md` first (draw calls, disposal, instancing, first-person controls).
+
+---
+
+## 1. Core mechanics (minimal-but-good scope for a demo)
+
+1. **A voxel world** stored as data (block IDs in a 3D grid), rendered as merged chunk meshes.
+2. **First-person movement + collision** against blocks (AABB vs voxels).
+3. **Break and place blocks** via a voxel raycast (crosshair targets a block/face).
+4. **A few block types** with distinct textures (atlas).
+5. **Some world generation** (flat, or simple noise terrain) and chunk streaming around the player.
+
+Flat world + walk + place/break + 3–4 block types is already recognizably "Minecraft." Skip inventory depth, lighting/AO, water, and mobs until the core render + edit loop is solid. **If you render each block as its own mesh, nothing else matters — you'll be at single-digit FPS.**
+
+---
+
+## 2. Chunking (the foundational structure)
+
+- **Divide the world into chunks** (commonly 16×16×256, or 16×16×16 sub-chunks). Store each chunk's blocks in a **flat typed array** (`Uint8Array` indexed `x + y*SX + z*SX*SY`), not nested objects — cache-friendly and memory-light.
+- **One merged mesh per chunk** (a single `BufferGeometry` built from all visible faces), not one mesh per block. This is the single most important rule — it turns thousands of draw calls into one per chunk.
+- **Rebuild a chunk's mesh only when its blocks change** (place/break), not every frame. Cache the geometry; dispose the old one on rebuild.
+- **Stream chunks** around the player: load/generate + build meshes for chunks within a radius; unload (and **dispose geometry/material/textures**) chunks that fall out of range. Do meshing off the main thread (**Web Workers**) to avoid frame hitches; transfer the typed arrays.
+- **Neighbor awareness:** meshing a chunk needs to know the blocks in adjacent chunks (to cull faces at chunk borders correctly) — pass neighbor data or a padded copy.
+
+---
+
+## 3. Face culling & greedy meshing (the performance core)
+
+- **Face culling first (mandatory):** only emit a block face if the neighboring block in that direction is **empty/transparent**. Interior faces between two solid blocks are never seen — skipping them removes the vast majority of geometry. This alone makes voxel worlds viable.
+- **Greedy meshing (big win):** after culling, **merge adjacent coplanar faces of the same block type into larger quads.** Instead of one quad per block face, a flat 16×16 grass top becomes (ideally) one quad. Algorithm (per 0fps.net "Meshing in a Minecraft Game"): for each of the 6 face directions, sweep the volume slice-by-slice, build a 2D mask of visible faces of each type, then greedily expand rectangles over the mask (grow width, then height while cells match), emitting one quad per merged rectangle. Cuts vertex count and draw work dramatically.
+- **Trade-off:** greedy meshing complicates per-face texturing/UVs and lighting/AO (merged quads span multiple blocks). For a demo, culled per-face meshing is acceptable; add greedy meshing when you need scale. Use a **texture atlas** (or a texture array) so all block textures share one material → one draw call per chunk. Set atlas textures to `NearestFilter` and mind bleeding at atlas tile edges (add padding or use a texture array).
+- **Don't use `InstancedMesh` of cubes for terrain** — it still submits all 6 faces per block and per-face culling/greedy meshing wins massively. Instancing is fine for sparse identical props.
+
+---
+
+## 4. Voxel raycasting: place & break blocks
+
+- **Use a grid-DDA voxel traversal (Amanatides & Woo), not `Raycaster.intersectObjects` against block meshes.** Step the ray cell-by-cell through the voxel grid: track `tMax`/`tDelta` per axis, advance to whichever axis boundary is nearest, and check the block at each visited cell until you hit a solid block or reach max distance. This is exact, cheap, and independent of how the mesh is built.
+- **Break:** set the hit cell to empty; rebuild that chunk's mesh (and any neighbor chunk if the block was on a border).
+- **Place:** place the new block in the cell **adjacent to the hit face** — you must track *which face* you crossed to enter the solid cell (the last step axis + direction gives the face normal). Place at `hitCell + faceNormal`. Reject placement if that cell is non-empty or overlaps the player's AABB (don't let the player entomb themselves).
+- **Highlight** the targeted block/face (wireframe or overlay) so the player sees what they'll hit.
+
+---
+
+## 5. Collision, feel & world gen
+
+- **Collision = AABB vs voxels:** resolve the player capsule/box against the blocks it overlaps, axis-separated (X, then Y, then Z), like a 3D version of tile collision. Sub-step fast movement to avoid tunneling through thin walls at high speed/low FPS.
+- **First-person feel:** pointer lock, gravity + jump, step-up over 1-block ledges optional; block-break should have a short "mining" delay + crack overlay + particle burst for satisfaction; place/break sounds.
+- **World gen:** simplex/Perlin noise for heightmaps (e.g. `simplex-noise`), layered (base terrain + caves via 3D noise) — keep it cheap and run in the worker with meshing.
+- **Ambient occlusion** (darkening block corners) adds huge visual quality but complicates greedy meshing; add later.
+
+---
+
+## 6. Common bugs to avoid (checklist)
+
+- **One mesh per block** → thousands of draw calls, instant death. Merge into one mesh per chunk.
+- **No face culling** → 6× the geometry, most of it hidden. Cull faces against neighbors (including across chunk borders).
+- **Rebuilding chunk meshes every frame** → rebuild only on edit; cache geometry.
+- **Not disposing unloaded chunk geometry/materials/textures** → memory leak/crash while exploring (Three.js doesn't GC GPU resources).
+- **Meshing on the main thread** → frame hitches when chunks stream; use Web Workers + transferable typed arrays.
+- **Chunk-border faces wrong** (missing or double faces at seams) → meshing must see neighbor chunk blocks.
+- **Using `intersectObjects` for block picking** → slow/fragile; use grid-DDA voxel traversal and track the entry face for placement.
+- **Placing blocks on the wrong side / inside the player** → place at hitCell + face normal; reject if occupied or overlapping the player AABB.
+- **Texture atlas bleeding** between tiles → padding or texture arrays, `NearestFilter`.
+- **Collision tunneling at speed** → axis-separated AABB resolution + sub-stepping.
+
+---
+
+## Defaults to apply
+
+1. **One merged mesh per chunk, never one mesh per block.** Store blocks in flat typed arrays; chunk the world (e.g. 16³). This is non-negotiable for browser performance.
+2. **Always do face culling** (skip faces adjacent to solid blocks, across chunk borders too). Add **greedy meshing** (0fps.net algorithm) for scale; culled-per-face is OK for a small demo.
+3. **Use a texture atlas / texture array so each chunk is one draw call.**
+4. **Rebuild chunk meshes only on edit; stream and dispose chunks by distance; mesh + generate in Web Workers.**
+5. **Break/place via grid-DDA voxel raycast (Amanatides & Woo), tracking the entered face** so placement goes on the correct adjacent cell; reject placements inside the player or occupied cells.
+6. **Minimal scope:** flat/simple-noise world, FP movement + AABB voxel collision, place/break, a few atlas-textured block types. Get render + edit solid before AO, water, lighting, or mobs.
+
+---
+
+## Sources
+- 0fps.net — "Meshing in a Minecraft Game" (greedy meshing, part 1): https://0fps.net/2012/06/30/meshing-in-a-minecraft-game/
+- 0fps.net — "Meshing in a Minecraft Game" (part 2, texturing/AO trade-offs): https://0fps.net/2012/07/07/meshing-minecraft-part-2/
+- Amanatides & Woo — "A Fast Voxel Traversal Algorithm for Ray Tracing" (grid-DDA block picking): http://www.cse.yorku.ca/~amana/research/grid.pdf
+- Three.js — voxel/Minecraft-style tutorial (chunk geometry, raycast place/break): https://threejs.org/manual/#en/voxel-geometry
+- Three.js — disposing objects (chunk unload): https://threejs.org/manual/#en/cleanup
+- MDN — Web Workers (off-thread meshing/gen): https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API
+- "Let's make a voxel engine" community wiki (chunking patterns): https://sites.google.com/site/letsmakeavoxelengine/home