@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.9

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

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

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

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

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

package/skills/grok-building-games/references/input.md

@@ -1,139 +0,0 @@
-# Unified Input for Browser Games (keyboard + mouse + touch + Gamepad, action mapping, deadzones, buffering)
-
-Consolidated from MDN (Gamepad API, Pointer Events, KeyboardEvent) and fighting/platformer input-design canon (see Sources). Focus: what an AI builder needs so games are **playable on every device with one code path**, controls are rebindable, and input feels responsive (buffering) rather than dropped.
-
----
-
-## 1. Architecture: one action layer over all devices
-
-**Never scatter `if (keys.KeyW)` gameplay checks through your code.** Build two layers:
-1. **Raw device state** — updated from events (keyboard/pointer) and polling (gamepad).
-2. **Abstract actions** — a fixed set like `moveX`, `moveY`, `aimX`, `jump`, `attack`, `pause`. Gameplay reads only actions. Any device can drive any action → keyboard, touch, and gamepad all "just work," and rebinding is trivial.
-
-```js
-const actions = { moveX:0, moveY:0, jump:false, attack:false /* ... */ };
-```
-
-Compute actions once per frame in an `updateInput()` called at the top of the loop, then gameplay consumes `actions` (and derived `justPressed` edges).
-
----
-
-## 2. Keyboard: use `event.code`, track state, don't act on the event
-
-- **Track pressed keys in a `Set`** on `keydown`/`keyup`; read the set in the loop. **Do NOT run movement/gameplay directly in the event handler** (event repeat rate ≠ frame rate → frame-dependent, laggy movement).
-- **Use `event.code`** (physical key, e.g. `'KeyW'`, `'Space'`, `'ArrowLeft'`) not `event.key` (layout/locale-dependent) and not the **deprecated `keyCode`**. `event.code` keeps WASD in the same physical spot on AZERTY/QWERTZ.
-- **`preventDefault()` for game keys** (Space, arrows) so the page doesn't scroll; but don't blanket-block everything (leave F5, devtools, tab-out).
-- **Clear the key set on `blur`/`visibilitychange`** — otherwise a key held while tabbing out gets "stuck down" forever (very common bug).
-- For text-entry vs gameplay, gate input by focus/mode.
-
-```js
-const keys = new Set();
-addEventListener('keydown', e => { keys.add(e.code); if (GAME_KEYS.has(e.code)) e.preventDefault(); });
-addEventListener('keyup',   e => keys.delete(e.code));
-addEventListener('blur',    () => keys.clear());
-```
-
----
-
-## 3. Pointer Events: unify mouse + touch + pen
-
-- **Use Pointer Events (`pointerdown/move/up/cancel`) instead of separate mouse + touch listeners.** One API covers mouse, touch, and stylus, with `pointerId` for multitouch and `pressure`/`pointerType`.
-- Handle **`pointercancel`** (OS steals the touch) as a release — forgetting it strands buttons/joysticks "held."
-- Set CSS **`touch-action: none`** on the canvas and `preventDefault()` to stop scroll/zoom/pull-to-refresh eating input.
-- Convert client coords to canvas/world coords using `getBoundingClientRect()` and `devicePixelRatio`; don't assume clientX == canvas pixel.
-- Mouse-look for FPS uses the **Pointer Lock API** (`requestPointerLock` on a gesture; read `movementX/Y`) — see the Three.js controls skill.
-
----
-
-## 4. Touch controls (mobile)
-
-- **Virtual joystick** for movement (e.g. **nipplejs**, static or dynamic) mapped to `moveX/moveY` normalized −1..1; **on-screen buttons** or a right-side aim/tap zone for actions. Split-screen: left = move, right = act/aim.
-- **Minimum 44px hit targets** (Apple HIG). Give visual feedback on press.
-- Support multitouch: track pointers by `pointerId` so moving the joystick doesn't cancel a jump button.
-- Normalize touch → the same **actions** as keyboard/gamepad; apply with delta time.
-
----
-
-## 5. Gamepad API: poll every frame, use standard mapping + deadzones
-
-- **Poll `navigator.getGamepads()` every frame** in the loop. The `gamepadconnected`/`gamepaddisconnected` events only tell you a pad exists — **do not cache the `Gamepad` object**; it's a snapshot. Get fresh state each frame.
-- A pad often only appears **after the user presses a button** ("waking"). Handle connect/disconnect gracefully mid-game.
-- Prefer **`gamepad.mapping === 'standard'`** — browsers remap Xbox/PS/etc. to a consistent layout:
-  - Buttons: 0=A/Cross, 1=B/Circle, 2=X/Square, 3=Y/Triangle, 4/5=bumpers, 6/7=triggers (**use `.value` 0–1**, analog), 8=Back/Select, 9=Start, 10/11=stick presses, 12–15=D-pad U/D/L/R.
-  - Axes (−1..1): 0=LX, 1=LY (**−1 is up**), 2=RX, 3=RY.
-- Read digital with `buttons[i].pressed`, analog triggers with `buttons[i].value > threshold`.
-- Non-standard pads (`mapping !== 'standard'`) have unpredictable indices — offer a rebinding screen as fallback.
-- Haptics via `gamepad.vibrationActuator?.playEffect('dual-rumble', {...})` where supported (progressive enhancement).
-
-### Deadzones (required for analog sticks)
-Sticks never rest at exactly 0. Apply a deadzone or you get drift ("character walks by itself").
-- **Radial deadzone** (correct for sticks — treat X/Y together, not per-axis) with re-normalization so full tilt still reaches magnitude 1:
-
-```js
-function radialDeadzone(x, y, dz = 0.15) {
-  const m = Math.hypot(x, y);
-  if (m < dz) return { x: 0, y: 0 };
-  const scale = ((m - dz) / (1 - dz)) / m; // re-normalize
-  return { x: x * scale, y: y * scale };
-}
-```
-- Typical deadzone 0.1–0.25. Also deadzone trigger `.value`. Per-axis deadzones make diagonals feel wrong — prefer radial.
-
----
-
-## 6. Action mapping & rebinding
-
-- Store bindings as **data** (action → list of physical inputs): `{ jump: ['Space','KeyW', {pad:0}], attack: ['Mouse0', {pad:2}] }`. `updateInput()` resolves bindings into `actions`.
-- **Rebinding UI:** capture the next input event, write it into the binding table, persist to localStorage (see `save-persistence.md`). Detect and warn on conflicts.
-- Support **multiple simultaneous devices** and per-action multiple bindings (WASD *and* arrows *and* stick all drive `moveX`).
-- Keep a **`justPressed` / `justReleased` edge set**: compare this frame's action booleans to last frame's for one-shot actions (jump, shoot, menu confirm). Reading level-triggered state for these causes repeat-fire bugs.
-
----
-
-## 7. Input buffering (responsiveness / fairness)
-
-- **Buffer discrete actions for a short window** (~100–150ms / ~6–8 frames) so an input pressed slightly before it's actionable still fires. Essential for platformers and fighting games — makes controls feel "tight" instead of "eating" inputs.
-  - E.g. jump pressed 4 frames before landing → still jump on landing.
-- **Coyote time:** allow jump for a few frames *after* walking off a ledge — pairs with jump buffering; both dramatically improve platformer feel.
-- Store buffered inputs with a timestamp/frame stamp; consume when the action becomes valid, and expire after the window.
-- **Poll gamepad and sample input at a fixed rate tied to your fixed-timestep** update for deterministic gameplay/netcode; buffering + fixed step is what makes combos/prediction reproducible.
-
----
-
-## 8. Bug-prevention checklist
-- **Movement in the keydown handler** → frame-rate-dependent, jerky; set flags, move in the loop with `dt`.
-- **Using `event.key`/`keyCode`** → breaks on non-US layouts / deprecated; use `event.code`.
-- **Stuck keys after tab-out** → clear key set on `blur`/`visibilitychange`.
-- **Caching the `Gamepad` object** → stale input; call `getGamepads()` every frame.
-- **No stick deadzone** → character drifts; apply radial deadzone with re-normalization.
-- **Per-axis deadzone** → mushy/wrong diagonals; use radial.
-- **Ignoring `pointercancel`** → stuck touch buttons/joysticks on mobile.
-- **Page scrolls/zooms during play** → missing `touch-action:none` / `preventDefault`.
-- **Repeat-firing one-shot actions** → reading level state instead of `justPressed` edges.
-- **"Ate my jump" feel** → no input buffering / coyote time.
-- **Gamepad never detected** → user hasn't pressed a button to wake it; handle connect event + prompt.
-
----
-
-## Defaults to apply
-- **Always generate the two-layer input system**: raw devices → normalized `actions`, with `justPressed`/`justReleased` edges. Gameplay reads only actions, so keyboard+mouse, touch (nipplejs + buttons), and gamepad all work from one code path.
-- **Bake in the safety defaults**: `event.code`, clear keys on blur, poll gamepad each frame, radial deadzone (~0.15) with re-normalization, `touch-action:none`, handle `pointercancel`.
-- **Include jump/input buffering (~120ms) + coyote time** in platformers/action templates by default — biggest feel win for cheap.
-- **Make bindings data-driven and persisted** so a rebinding screen is a small add, and auto-detect the active device to show correct button prompts.
-- **Semantic signs for move/steer/flight** are **not** defined here — open the
-  **`controls` skill** (`.grok/skills/controls/SKILL.md`) so `steer`/`roll`
-  mean player-left correctly. This file is plumbing; that skill is the sign
-  convention + mandatory A/D self-test.
-
----
-
-## Sources
-- MDN — Gamepad API: https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API ; Using the Gamepad API: https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API ; Implementing controls: https://developer.mozilla.org/en-US/docs/Games/Techniques/Controls_Gamepad_API
-- MDN — `Navigator.getGamepads()`: https://developer.mozilla.org/en-US/docs/Web/API/Navigator/getGamepads ; `Gamepad` / `GamepadButton`: https://developer.mozilla.org/en-US/docs/Web/API/Gamepad
-- MDN — Pointer Events: https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events ; `touch-action`: https://developer.mozilla.org/en-US/docs/Web/CSS/touch-action
-- MDN — `KeyboardEvent.code` + code values: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code ; https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values
-- MDN — Pointer Lock API: https://developer.mozilla.org/en-US/docs/Web/API/Pointer_Lock_API
-- W3C — Gamepad spec (standard mapping): https://w3c.github.io/gamepad/#remapping
-- Josh Sunshine / gamepad mapping deep dive: https://adamjones.me/blog/gamepad-mapping/
-- nipplejs (virtual joystick): https://github.com/yoannmoinet/nipplejs
-- Input buffering & coyote time (game feel): GDC/《Celeste》 & fighting-game input design write-ups, e.g. https://www.gamedeveloper.com/design/how-to-add-input-buffering-to-your-game and Celeste physics notes.