@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.9

package/skills/grok-building-games/SKILL.md

@@ -1,213 +0,0 @@
----
-name: building-games
-description: >
-  Build browser games and interactive/canvas/3D experiences in this TanStack
-  Start + React app. Use for any game, simulation, or WebGL/Canvas experience —
-  2D or 3D, single-player. Covers the game loop & timing, 3D orientation/camera
-  conventions, collision, performance, assets, audio, save, game feel, and
-  per-genre playbooks. For WASD / vehicle / flight **input signs and inverted
-  A/D**, open the **`controls`** skill — do not rely on this file or racing-kart
-  alone. Triggers on "game", "minecraft", "fps", "platformer", "racing",
-  "tetris", "snake", "shooter", "3d", "three.js", "canvas", "voxel", "physics".
-metadata:
-  short-description: "Browser games: loop, 3D orientation, camera, perf, assets, genres"
-user-invocable: false
----
-
-# Building Games
-
-Build a **playable, correct** browser game — not a static screenshot. A game is
-just a React route with a `<canvas>` (or `<Canvas>` for R3F) plus DOM overlay UI.
-Style the overlay (start screen, HUD, menus) with the **`design-ui`** skill; this
-skill owns the gameplay loop and world.
-
-**Controls / inverted A/D:** open **`.grok/skills/controls/SKILL.md`** **before**
-writing WASD, steering, or flight input. Vehicle/flight demos often ship with
-A/D flipped if you only read this file or a single genre playbook.
-
-**Scope note — single-player, bots, or small P2P co-op:**
-- Ship **single-player** or **single-player + AI/bots** by default.
-- **2–8 player co-op / casual realtime** (shared cursors, party games, casual
-  action among friends) is supported — use the **`multiplayer-p2p` skill**
-  (WebRTC mesh, signaled at `/api/rtc`). Read its trust model first.
-- P2P is the only supported multiplayer right now. Do not half-build sockets
-  that can’t connect.
-
-**References (load on demand):**
-- **`controls` skill** (`../controls/`) — **required** for movement/steer/flight:
-  player-visible A/D, inverted-steer anti-pattern, flight ailerons, mandatory
-  self-test + `window.__controlsTest`. Not optional for vehicles/planes.
-- `references/threejs-foundational.md` — the deep 3D/loop/perf reference. Read for 3D.
-- `references/3d-libs.md` — three.js + @react-three/fiber + drei + rapier usage.
-- **`threejs` skill** (`../threejs/`) — official full Three.js + TSL API dump
-  (`llms-full.txt`). Load for advanced materials/shaders/WebGPU/loaders; not for
-  simple 2D canvas games.
-- `references/babylon.md` — Babylon.js, the batteries-included 3D engine alternative.
-- `references/phaser.md` — Phaser 3, the default engine for 2D games.
-- `references/ecs-architecture.md` — entity-component-system structure for larger games.
-- `references/genres/*.md` — per-genre playbooks (fps, platformer-2d, racing-kart,
-  puzzle-match3-tetris, voxel-minecraft, endless-runner, topdown-twin-stick,
-  tower-defense, board-card-chess). Genre files **do not** replace **`controls`**.
-- `references/game-feel-juice.md`, `input.md`, `audio.md`, `collision-physics.md`,
-  `save-persistence.md`, `procedural-generation.md`, `ai-pathfinding.md`.
-- **`game-asset-core`** (+ `game-animation-frames` / `game-tilesets` /
-  `game-character-consistency` / `game-ui-icons`) — engine-ready 2D art defaults
-  and verification when generating sprites, sheets, tiles, or UI (see §6).
-
-Pick the specific genre/topic reference for the build; this file is the universal
-core for loop/world. **Input signs → `controls`.** **2D game art → `game-asset-core`.**
-
----
-
-## 1. Game loop & timing (the #1 correctness issue)
-
-- Drive the loop with the engine's RAF loop (`renderer.setAnimationLoop`, R3F
-  `useFrame`, or `requestAnimationFrame` for 2D canvas). **Never** `setInterval`/
-  `setTimeout`/`Date.now()` for game timing.
-- **Scale ALL movement/animation by delta time** (seconds) so speed is frame-rate
-  independent (60Hz vs 144Hz). Compute delta **once per frame** and reuse it.
-  - three.js: use `THREE.Timer` (not `Clock` — `Clock.getDelta()` returns ~0 on a
-    second call in the same frame, a classic freeze bug).
-- **Cap delta** (`min(delta, 0.1)`) so a backgrounded tab doesn't teleport things.
-- **Fixed timestep for physics/gameplay:** accumulate delta and step simulation at
-  a fixed rate (e.g. 1/60) while rendering at display rate — prevents tunneling and
-  non-determinism.
-
-## 2. Controls (delegate to the `controls` skill)
-
-**Open `.grok/skills/controls/SKILL.md` before implementing any WASD / steer /
-flight code.** That skill is the source of truth for:
-
-- Player-visible **A = left / D = right** (chase cam, while moving forward)
-- Why **`KeyA → steer−` + `yaw += steer * +rate` inverts** (most common bug)
-- Vehicle vs FPS (strafe ≠ steer), fixed-wing ailerons, heli/drone notes
-- Mandatory self-test + `window.__controlsTest` probe
-
-Do **not** treat `genres/racing-kart.md` as the only place steer signs live —
-planes, jetskis, and mechs never open it.
-
-**Short reminder (full detail in `controls`):**
-
-```
-// Vehicle yaw body (chase cam): A must increase yaw with this basis
-forward = (-sin(yaw), 0, -cos(yaw))
-// KeyA → steer = +1;  yaw += steer * turnRate * speedFactor * dt
-// WRONG (ships inverted): KeyA → steer = -1; yaw += steer * turnRate * dt
-```
-
-- **Pointer lock:** mouse-look only — implement WASD yourself; click-to-play
-  overlay; dismiss on lock.
-- Track keys with held state + **dt**; unify devices via `references/input.md`.
-- **Finish:** run the `controls` skill checklist. Screenshot-only is insufficient
-  for vehicles/flight.
-
-## 3. 3D orientation & world objects (the "sideways/backwards" bugs)
-
-- three.js is **right-handed, +Y up**: +X right, +Y up, +Z toward viewer. **Meshes
-  face +Z; cameras look −Z** (the classic "camera backwards" gotcha).
-- Primitives like `Cone`/`Cylinder` point **+Y** by default → rotate to align a
-  tip with forward (`geo.rotateX(Math.PI/2)`).
-- **Orienting a mesh to face `forward`** (meshes face **+Z**): simplest correct way
-  is `mesh.lookAt(mesh.position.clone().add(forward))`. To build the basis by hand,
-  set the **+Z column to `forward`** and choose the x-axis that keeps it a *proper*
-  right-handed rotation (`det = +1`):
-  `xAxis = normalize(cross(up, forward))`, then `makeBasis(xAxis, up, forward)`.
-  Note this is `cross(up, forward)` — **not** the movement `right = cross(forward, up)`
-  from §2. Targeting +Z (instead of a camera's −Z) flips the x-axis sign so that
-  `xAxis × up = forward`; the frame stays right-handed (no mirroring). Do **not** use
-  `makeBasis(xAxis, up, -forward)` for a mesh — that targets −forward (the *camera*
-  convention) so the mesh faces **backwards**.
-- **Orienting a camera** to look along `forward` (cameras look **−Z**): set the +Z
-  column to `-forward` — `xAxis = normalize(cross(forward, up))`, then
-  `makeBasis(xAxis, up, -forward)` (or just `camera.lookAt(target)`).
-- Keep a consistent world `up` so objects stay upright; only rotate flat primitives
-  to stand up.
-- Verify glTF import orientation; debug with `AxesHelper`/`ArrowHelper`. Upright
-  self-test: characters stand on the ground plane, not lying/sunk.
-
-## 4. Camera must agree with movement
-
-- Keep a **dedicated `moveForward`/`moveRight`** for movement, computed once and
-  never mutated by camera code (aliasing a shared temp vector makes camera and
-  movement disagree — a real repro bug).
-- Third-person follow: `desired = playerPos + up*height + moveForward*(-followDist)`;
-  lerp the camera toward it (use exp-based smoothing, delta-scaled), `lookAt(player)`.
-- Isolate-the-layer debug order: (1) keys register → (2) movement signs correct →
-  (3) camera agrees. Fix in that order.
-
-## 5. Performance
-
-- **Minimize draw calls** (`renderer.info.render.calls`, target <100): share
-  materials, `InstancedMesh`/`BatchedMesh` for repeated objects, atlases.
-- **Dispose GPU resources yourself** (`geometry/material/texture.dispose()`) on
-  level change — three.js does not GC them. **Pool** bullets/enemies/particles.
-- No per-frame allocations (reuse temp vectors). Compress textures; LOD for distance.
-
-## 6. Assets (avoid the generated-photo trap)
-
-- **Interactive 3D elements** (weapon viewmodels, characters, props, projectiles)
-  → build from **3D geometry / glTF**, not a generated image. A flat photorealistic
-  JPG of a gun-in-hands used as an FPS viewmodel looks wrong, can't animate, and
-  (JPG has **no alpha**) renders as a black box. Parent a real 3D viewmodel to the
-  camera as an overlay render layer.
-- Reserve image generation for **flat 2D** assets only (textures, sky/menu
-  backgrounds, 2D sprites, UI art). **Never** use a generated photo as a 3D mesh,
-  viewmodel, or character substitute — build those in 3D geometry / glTF.
-  Set `crossOrigin="anonymous"` on images drawn to canvas/textures.
-  See the **`imagine`** skill (2D only — image tools cannot produce real 3D).
-- **Engine-ready game art doctrine** → open **`game-asset-core`**
-  (`../game-asset-core/`) for defaults + blind verify + retry discipline, then the
-  matching specialist: **`game-animation-frames`** (loop / motion laws),
-  **`game-tilesets`**, **`game-character-consistency`**, **`game-ui-icons`**.
-  These are **QC/doctrine**, not the export pipeline. Do not ship stick-figure
-  placeholders when real art is expected.
-- **2D game sprites / animation sheets** → run **`generate2dsprite`**
-  (`.grok/skills/generate2dsprite/SKILL.md`): solid **`#FF00FF`** magenta
-  `imagine_text_to_image` sheets + chroma postprocess scripts (magenta is required for the
-  processor). Wire transparent PNGs/GIFs into Canvas/Phaser. Still apply
-  **`game-asset-core`** (+ animation/character specialists when relevant).
-- **2D maps / levels / prop packs** → open **`generate2dmap`**
-  (`.grok/skills/generate2dmap/SKILL.md`). Prefer foundation-only base + separate
-  props/collision for playable maps. Browser default: `raw_canvas` / Phaser.
-  Tileable ground/walls → also **`game-tilesets`** for 2×2 seam checks.
-- **Optional denser locomotion** → run **`video2dsprite`** (Grok
-  `imagine_image_to_video` + sandbox scripts; magenta base). Prefer `generate2dsprite`
-  for crisp production heroes. Use **`game-animation-frames`** for loop/flip-test
-  laws; prefer **`video2dsprite`** over ad-hoc ffmpeg-only harvest in this
-  sandbox.
-
-## 7. Audio, save, feel
-- **Audio**: unlock `AudioContext` on the first user gesture (tap-to-start) or iOS
-  is silent; re-resume on `visibilitychange`. (`references/audio.md`)
-- **Save**: `localStorage`/IndexedDB with a `version` field + migrations.
-- **Juice**: screen shake, hit-stop, eased tweens, particles — cheap, huge
-  perceived-quality lift. Keep presentation separate from simulation.
-
-## 8. Mobile
-- Distinguish canvas buffer size from CSS size; respect `devicePixelRatio`.
-- `touch-action: none`, letterbox-fit to a base resolution, handle orientation.
-- Touch controls (virtual joystick + action buttons), ≥44px targets.
-
----
-
-## Stack / engine choice
-- **3D → three.js**, ideally via **@react-three/fiber + drei** (fits the React
-  app; drei gives pointer-lock/controls/loaders) + **@react-three/rapier** for
-  physics/character controllers. See `references/3d-libs.md`.
-- **2D →** native Canvas 2D is enough for snake/tetris/flappy/platformer; reach for
-  Phaser only when the genre needs it.
-- These game deps are **not preinstalled** — `npm install` them (and make sure they
-  land in `package.json` so the Vercel build has them).
-
-## Finish criteria (before "done")
-- Loads with **no console errors**; visible gameplay (not a blank canvas).
-- **`controls` skill self-test passed** (A = left / D = right from chase cam
-  while moving forward; flip one sign if inverted). Not screenshot-only.
-- 3D upright & camera-agrees self-tests pass (§3, §4).
-- Runs on mobile viewport with touch controls.
-- Production build (`npm run build`) renders the built output, not just dev.
-- **Share / X card:** open the **`og`** skill — custom `public/og.jpg` **and**
-  `"type": "x:game"` in `src/lib/og/site.json`. X uses `og:type="x:game"`
-  to present the unfurl as a game card; do not use `twitter:card` or invent
-  `x:type` for this. `browser-smoke` / `brand-check` warn when canvas apps omit
-  the `site.json` field.

package/skills/grok-building-games/agentsam.skill.json

@@ -1,25 +0,0 @@
-{
-  "schema": "agentsam.skill.v1",
-  "id": "grok-building-games",
-  "name": "Grok \u00b7 building-games",
-  "description": "Browser games: loop, 3D orientation, camera, perf, assets, genres",
-  "icon": "skill",
-  "slash": {
-    "suggested": "/grok-building-games"
-  },
-  "instructions": {
-    "source": "local_file",
-    "ref": "SKILL.md"
-  },
-  "execution": {
-    "mode": "turn",
-    "tools": [],
-    "operations": [],
-    "capabilities": []
-  },
-  "provenance": {
-    "source": "apps/local-studio/.grok/skills",
-    "vendor": "grok",
-    "status": "imported"
-  }
-}

package/skills/grok-building-games/references/3d-libs.md

@@ -1,64 +0,0 @@
-# 3D libraries for this stack (three.js + React Three Fiber + drei + rapier)
-
-The app is React/TanStack. The idiomatic way to do 3D here is **React Three
-Fiber (R3F)** — write three.js as React components inside a `<Canvas>` on a
-route. It deploys like any other page.
-
-> These are **not preinstalled**. Install and confirm they land in `package.json`:
-> `npm i three @react-three/fiber @react-three/drei @react-three/rapier`
-> (+ `npm i -D @types/three`). If the deploy build has no three, the game is blank.
-
-## When to use what
-- **three.js** — the engine. Raw three is fine for a self-contained canvas; prefer
-  R3F when the game has React UI/state around it.
-- **@react-three/fiber** — renders three as React; `useFrame((state, delta) => …)`
-  is your game loop (delta is seconds — scale movement by it, see SKILL §1).
-- **@react-three/drei** — helpers so you don't hand-roll bug-prone code:
-  `<PointerLockControls/>`, `useKeyboardControls`, `<OrbitControls/>`,
-  `useGLTF`, `<Environment/>`, `<Instances/>`, `<Stats/>`.
-- **@react-three/rapier** — physics + **character controller** (capsule +
-  autostep + snap-to-ground). Use for FPS/platformer movement and collisions
-  instead of hand-rolled raycasts. `<Physics>`, `<RigidBody>`, `useRapier`.
-
-## Minimal R3F shape
-```tsx
-import { Canvas, useFrame } from "@react-three/fiber";
-import { PointerLockControls, useKeyboardControls } from "@react-three/drei";
-
-function Player() {
-  useFrame((_, delta) => {
-    const d = Math.min(delta, 0.1);       // cap delta (SKILL §1)
-    // move with a dedicated moveForward/moveRight basis (SKILL §2/§4)
-  });
-  return null;
-}
-
-export default function Game() {
-  return (
-    <Canvas camera={{ position: [0, 1.7, 5], fov: 75 }} shadows dpr={[1, 2]}>
-      {/* scene */}
-      <PointerLockControls />   {/* mouse-look ONLY — implement WASD yourself */}
-      <Player />
-    </Canvas>
-  );
-}
-```
-
-## Gotchas (map to the SKILL universals)
-- **Controls:** drei `PointerLockControls` is mouse-look only — WASD is yours
-  (SKILL §2). Gate `.lock()` behind a "click to play" overlay and dismiss it on lock.
-- **Orientation:** meshes face +Z, camera looks −Z; right-handed +Y up (SKILL §3).
-- **Delta:** `useFrame` delta is seconds; cap it; fixed-step physics via rapier's
-  own stepping. Don't read `THREE.Clock.getDelta()` twice a frame.
-- **Perf:** `<Instances>`/`InstancedMesh` for repeats; dispose on unmount (R3F
-  auto-disposes objects it created, but not manual textures/loaders — dispose those).
-  Set `dpr={[1, 2]}` to cap retina cost.
-- **Mobile:** R3F sets pixel ratio via `dpr`; still add touch controls + `touch-action:none`.
-
-## Alternatives
-- **Babylon.js** (`references/babylon.md`) — batteries-included 3D (Havok physics,
-  inspector, SceneOptimizer). Viable if you want an all-in-one engine, but it's a
-  separate paradigm from React; default to three/R3F for consistency with the app.
-
-Sources: R3F docs (https://r3f.docs.pmnd.rs), drei (https://github.com/pmndrs/drei),
-react-three-rapier (https://github.com/pmndrs/react-three-rapier), three.js docs.

package/skills/grok-building-games/references/ai-pathfinding.md

@@ -1,122 +0,0 @@
-# Game AI & Pathfinding (A* on grids, steering, FSM, behavior trees, navmesh)
-
-Consolidated from Red Blob Games (the canonical A*/grid reference), Craig Reynolds' steering work, and Game AI Pro / behavior-tree canon (see Sources). Focus: what an AI builder needs so enemies/agents **move sensibly and don't jitter, get stuck, or tank the frame rate.**
-
----
-
-## 1. Pathfinding: A* on a grid (the default)
-
-**A\*** finds the shortest path by expanding the node that minimizes `f = g + h`, where `g` = cost so far and `h` = heuristic estimate to goal. It's Dijkstra + a goal-directed heuristic.
-
-Rules:
-- **Heuristic must be admissible** (never overestimate true cost) or A* may return a non-optimal path.
-  - **4-directional grid → Manhattan distance** `|dx|+|dy|`.
-  - **8-directional grid → octile/Chebyshev distance** (diagonal cost ≈ 1.414). Using Manhattan on an 8-dir grid overestimates → wrong paths; using Euclidean on a 4-dir grid underestimates → slow.
-- **Use a binary heap / priority queue** for the open set. A linear scan of the open set is the #1 A* perf bug — turns O(E log V) into O(V²) and stutters on big maps.
-- **Track a closed set / best-g per node** so you don't reprocess nodes; update `g` if a cheaper path to a node is found.
-- **Weighted tiles:** give terrain costs (mud=5, road=1) via `g`; A* naturally routes around expensive terrain.
-- **Diagonal corner-cutting:** forbid diagonal moves that clip through two wall corners, or agents visually cut through walls.
-- **Reconstruct the path** by following `cameFrom` parents from goal back to start, then reverse.
-
-Related tools (Red Blob Games):
-- **Breadth-First Search / Dijkstra maps ("flow fields"):** when *many* agents chase *one* goal (tower defense, RTS), compute one BFS/Dijkstra field from the goal and have every agent follow the gradient — far cheaper than one A* per agent.
-- **Greedy Best-First** is faster but not optimal; A* is the balanced default.
-- **JPS (Jump Point Search)** optimizes A* on uniform-cost grids.
-
-Libraries: **PathFinding.js** (grid A*/JPS/BFS, easy), or roll your own for control.
-
-**Path-following gotchas:** smooth the raw grid path (string-pulling / line-of-sight simplification) so agents don't zig-zag along cell centers; recompute paths sparingly (on target move / periodically, not every frame); handle "no path exists" explicitly.
-
----
-
-## 2. Steering behaviors (smooth local movement)
-
-A* gives *where* to go; **steering** (Craig Reynolds) makes agents *move there naturally* by accumulating steering forces on velocity:
-- **Seek / Arrive** — move toward a target; Arrive decelerates within a slowing radius (prevents overshoot/orbit).
-- **Flee / Evade** — away from a threat.
-- **Pursuit** — seek the target's *predicted future* position.
-- **Wander** — smooth random roaming (jitter a point on a circle ahead), not teleporting random targets.
-- **Obstacle avoidance** — steer around obstacles detected by a look-ahead feeler.
-- **Separation / Alignment / Cohesion** = **Flocking (boids)** for crowds/schools/swarms.
-- **Path following** — follow a computed A* path smoothly rather than snapping cell-to-cell.
-
-Rules: **combine forces** (weighted sum or priority), **clamp to max force and max speed**, apply with **delta time**. Steering handles the smooth "how"; A*/flow fields handle the strategic "where." Use both together — A* alone looks robotic; steering alone gets stuck on walls.
-
----
-
-## 3. Finite State Machines (FSM) — decision-making for simple agents
-
-- Agent is in exactly one **state** (Idle, Patrol, Chase, Attack, Flee); **transitions** fire on conditions (saw player → Chase; lost player → Patrol; low HP → Flee).
-- Each state has `enter()`, `update(dt)`, `exit()`. Keep transition logic centralized/table-driven.
-- Great for enemies with a handful of behaviors. **Downside:** transitions explode combinatorially (n states → up to n² transitions) — becomes spaghetti past ~6–8 states.
-- **Hierarchical FSMs** (states containing sub-states) tame some of that.
-
----
-
-## 4. Behavior Trees (BT) — scalable decision-making
-
-When FSMs get unwieldy, use a **behavior tree**: a tree of nodes evaluated each tick, each returning **Success / Failure / Running**.
-- **Composites:** **Sequence** (run children in order, fail-fast — "AND"), **Selector/Fallback** (try children until one succeeds — "OR"), **Parallel**.
-- **Decorators:** Inverter, Repeat, Cooldown, Succeeder, condition guards.
-- **Leaves:** Actions (MoveTo, Attack, Reload) and Conditions (IsPlayerVisible, HasAmmo).
-- **`Running` is the key concept:** long actions (walking a path) return `Running` and resume next tick — don't block.
-- Far more **modular/reusable/authorable** than FSMs; the industry standard for complex NPCs. Consider a lib (behaviortree.js) or a small hand-rolled implementation.
-- **Utility AI / GOAP** are alternatives for emergent/goal-driven behavior at higher complexity.
-
-**Rule:** simple enemies → FSM; complex/multi-goal NPCs → behavior tree. Don't build a BT framework for a single 3-state slime.
-
----
-
-## 5. Navmesh basics (3D / open spaces)
-
-- Grids are natural for tile games; for **open 3D/continuous** worlds, a **navigation mesh** (convex polygons covering walkable surfaces) is more efficient and gives smoother paths than a dense grid.
-- Run A* over the polygon graph (portal edges), then **string-pull ("funnel algorithm")** through polygon portals for a smooth, natural path.
-- In JS: **recast-navigation-js** (WASM port of industry-standard Recast/Detour) bakes navmeshes from level geometry and provides crowd/agent avoidance; three-pathfinding for a simpler Three.js navmesh follower.
-- Navmeshes handle multi-level geometry (ramps, bridges) that flat grids can't; support off-mesh links (jumps, ladders).
-
----
-
-## 6. Performance & correctness rules
-- **Don't A* every agent every frame.** Cache paths; recompute on target movement or a throttled interval; **time-slice** pathfinding across frames or use a **web worker** for big searches so the main thread doesn't hitch.
-- **Flow field / Dijkstra map** when many agents share one goal — one computation for all.
-- **Binary heap** open set, **typed arrays** for large grids, reuse buffers (no per-search allocation churn).
-- **Run AI on a fixed timestep** (decoupled from render) for determinism/netcode; often at a lower rate than render (e.g. 10–20Hz for decisions) with steering interpolating between.
-- **Stagger** AI updates across agents (LOD-AI): distant/off-screen agents think less often.
-- Handle **dynamic obstacles**: mark blocked cells / re-path when the map changes; use local steering avoidance for moving agents.
-
----
-
-## 7. Bug-prevention checklist
-- **Non-admissible heuristic** (Euclidean on 4-dir, Manhattan on 8-dir) → non-optimal or slow paths; match heuristic to movement.
-- **Linear open-set scan** → severe stutter on big maps; use a binary heap.
-- **A* per agent per frame** → frame drops; cache/throttle/flow-field/worker.
-- **Following raw grid path** → robotic zig-zag; smooth/string-pull and add steering.
-- **No Arrive/slowing radius** → agents overshoot and orbit the target.
-- **Corner-cutting diagonals** → agents clip through wall corners; forbid unsafe diagonals.
-- **FSM sprawl** → unmaintainable transitions; switch to a behavior tree.
-- **Blocking actions in a BT** → tree stalls; return `Running` for long actions.
-- **Ignoring "no path"** → crashes/agents freeze; handle unreachable goals explicitly.
-- **Not re-pathing on map change** → agents walk into new walls; invalidate cached paths.
-- **AI tied to render frame rate** → non-deterministic/uneven; fixed timestep, staggered.
-
----
-
-## Defaults to apply
-- **Default AI stack:** **A\* on a grid** (binary-heap open set, movement-matched heuristic, weighted tiles) for "where," **steering behaviors** (seek/arrive/avoid/separation) for smooth "how," and an **FSM for simple enemies / behavior tree for complex NPCs** for "what to do."
-- **Use flow fields (BFS/Dijkstra map) when many agents chase one target** (tower defense/RTS) — big perf win over per-agent A*.
-- **For 3D/open worlds, generate navmeshes via recast-navigation-js**; smooth paths with the funnel algorithm.
-- **Bake in the perf guardrails**: cache paths, throttle/time-slice/worker pathfinding, run AI on a fixed lower-rate tick with steering interpolation, and stagger distant agents. Always handle "no path found."
-
----
-
-## Sources
-- Red Blob Games — Introduction to A* (canonical, interactive): https://www.redblobgames.com/pathfinding/a-star/introduction.html ; A* Implementation Guide: https://www.redblobgames.com/pathfinding/a-star/implementation.html
-- Red Blob Games — Grids/heuristics & "Pathfinding for Tower Defense" (flow fields): https://www.redblobgames.com/pathfinding/tower-defense/ ; grid pathfinding tricks: https://www.redblobgames.com/pathfinding/grids/algorithms.html
-- Craig Reynolds — "Steering Behaviors For Autonomous Characters": https://www.red3d.com/cwr/steer/ ; Boids: https://www.red3d.com/cwr/boids/
-- Amit Patel / Red Blob — heuristics guide: https://theory.stanford.edu/~amitp/GameProgramming/Heuristics.html
-- PathFinding.js (grid A*/JPS/BFS): https://github.com/qiao/PathFinding.js
-- Jump Point Search (Harabor & Grastien): https://harablog.wordpress.com/2011/09/07/jump-point-search/
-- Behavior Trees — Chris Simpson, "Behavior trees for AI: How they work": https://www.gamedeveloper.com/programming/behavior-trees-for-ai-how-they-work ; behaviortree.js: https://github.com/Calamari/BehaviorTree.js
-- Game Programming Patterns — State (FSM): https://gameprogrammingpatterns.com/state.html
-- Recast/Detour navmesh: https://github.com/recastnavigation/recastnavigation ; recast-navigation-js: https://github.com/isaac-mason/recast-navigation-js ; three-pathfinding: https://github.com/donmccurdy/three-pathfinding
-- GOAP (Jeff Orkin, F.E.A.R.): https://alumni.media.mit.edu/~jorkin/goap.html

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

@@ -1,129 +0,0 @@
-# Game Audio in the Browser (Web Audio API, mobile unlock, Howler.js, gain buses, spatial, latency)
-
-Consolidated from MDN Web Audio docs and Howler.js docs (see Sources). Focus: what an AI builder needs so audio **actually plays on mobile, stays low-latency, and mixes cleanly** — the #1 audio bug in browser games is "no sound on iOS."
-
----
-
-## 1. The autoplay unlock — the single most important rule
-
-Browsers block audio until the user interacts with the page. An `AudioContext` created on page load starts in the **`"suspended"`** state and will silently play nothing until resumed.
-
-**Rule: create/resume the AudioContext (or unlock your audio lib) from inside the FIRST real user gesture** (`click`/`touchend`/`keydown`), and call `resume()` **synchronously** in that handler's call stack (iOS Safari is strict — an `await` before `resume()` can break the gesture chain).
-
-```js
-let audioCtx;
-function unlockAudio() {
-  if (!audioCtx) audioCtx = new (window.AudioContext || window.webkitAudioContext)();
-  if (audioCtx.state === 'suspended') audioCtx.resume(); // call synchronously in the gesture
-}
-// Attach once; remove after first success. `pointerdown`/`touchend`/`keydown` all count.
-window.addEventListener('pointerdown', unlockAudio, { once: true });
-window.addEventListener('keydown', unlockAudio, { once: true });
-```
-
-- Show a "tap to start" / "click to play" screen so the first gesture reliably unlocks audio (and any pointer lock / fullscreen you need). Games should not expect audio before the player clicks in.
-- Also **resume on `visibilitychange`/focus** — contexts can get re-suspended when a tab is backgrounded on mobile.
-- Listen to the `statechange` event if you need to reflect mute/paused UI.
-
----
-
-## 2. Web Audio API vs `<audio>` vs Howler
-
-- **Don't use `<audio>` / `Audio()` elements for game SFX.** They have high latency, limited simultaneous playback, and inconsistent mobile behavior. Fine for background music streaming only.
-- **Web Audio API** is the correct foundation: decode once into an `AudioBuffer`, then fire many low-latency, overlapping `AudioBufferSourceNode`s. Gives you precise scheduling, gain buses, and spatialization.
-- **Howler.js** is the recommended default library — it wraps Web Audio (with `<audio>` fallback), auto-handles the **mobile unlock**, sprite support, fades, spatial audio, and pooling. Use it unless you specifically need raw Web Audio control. (Note: `AudioBufferSourceNode` is one-shot — you create a new source per play; that's normal and cheap. Howler manages this for you.)
-
-**Preload & decode up front:** `fetch → arrayBuffer → audioCtx.decodeAudioData` during a loading screen. Decoding on first play causes an audible hitch.
-
----
-
-## 3. Gain buses (music / SFX / master) — do this from the start
-
-Route everything through a small mixer graph so you can control category volumes and a master mute:
-
-```
-source → (per-sound gain) → sfxBus ─┐
-music  → musicGain ────────────────┼→ masterGain → audioCtx.destination
-```
-
-```js
-const master = audioCtx.createGain();
-const musicBus = audioCtx.createGain();
-const sfxBus   = audioCtx.createGain();
-musicBus.connect(master); sfxBus.connect(master); master.connect(audioCtx.destination);
-```
-
-- Set volumes with **`gain.setTargetAtTime(value, audioCtx.currentTime, 0.02)`** or `setValueAtTime`, **not** a raw `gain.value =` mid-play — abrupt jumps cause clicks/pops. Ramp fades over ~10–50ms.
-- Perceived loudness is logarithmic: map a 0–1 slider to gain with a curve (e.g. `gain = slider²`) so sliders feel linear.
-- Howler equivalent: per-sound `volume`, category via `Howler` groups / separate `Howl` instances, and `Howler.volume()` for master.
-
----
-
-## 4. Latency (keep audio tight)
-
-- Prefer **Web Audio buffer sources** over `<audio>` for anything reactive — element playback latency ruins hit feedback.
-- Optionally construct the context with **`{ latencyHint: 'interactive' }`** (default) for lowest latency; use `'playback'` only for pure music.
-- **Reuse decoded buffers**; never `decodeAudioData` in the gameplay hot path.
-- Schedule to `audioCtx.currentTime` for sample-accurate timing (e.g. rhythm games): `source.start(when)`. Don't rely on `setTimeout` for musical timing — use the Web Audio clock ("A Tale of Two Clocks").
-- Avoid creating hundreds of nodes per frame; cap concurrent voices and stop/disconnect finished sources (set `source.onended` to disconnect) to avoid graph buildup.
-
----
-
-## 5. Variation & layering (feel)
-
-- **Pitch-randomize** repeated SFX so footsteps/gunfire don't sound robotic: set `source.playbackRate.value = 1 + (Math.random()*2-1)*0.1` (Howler: `rate`). Randomize volume slightly too.
-- **Layer** a sound from multiple samples (thump + body + transient) — see `game-feel-juice.md`.
-- **Round-robin / random pick** from a few variants of the same sound.
-- Use **audio sprites** (one file, offset+duration segments) to cut HTTP requests and decode overhead — Howler supports `sprite` natively.
-
----
-
-## 6. Spatial / positional audio (for 3D or top-down games)
-
-- **`PannerNode`** positions a source in 3D relative to `audioCtx.listener`. Connect `source → panner → bus`. Update `panner.positionX/Y/Z` and `listener.positionX/Y/Z` (+ listener `forward`/`up`) each frame to match camera/player.
-- `panningModel`: `'HRTF'` (realistic, headphone-friendly, costlier) or `'equalpower'` (cheap stereo). `distanceModel`: `'inverse'`/`'linear'`/`'exponential'` with `refDistance`, `maxDistance`, `rolloffFactor` for falloff.
-- For simple **2D stereo pan** (left/right by screen x), a `StereoPannerNode` (pan −1..1) is cheaper and sufficient — don't reach for HRTF in a 2D game.
-- Howler exposes `pos()`, `orientation()`, and `pannerAttr()` for this.
-- Update positions in the render loop; set the position AudioParams via `.value` (or `setValueAtTime`) to avoid zipper noise on fast movement.
-
----
-
-## 7. Formats & assets
-- Use **compressed formats**: `.webm`/`.ogg` (Opus/Vorbis) with an `.mp3`/`.m4a` fallback for Safari. Howler takes an array of sources and picks a supported one.
-- Keep SFX short and mono (mono halves size and works with panners); keep music stereo but compressed.
-- Watch total download; long music tracks can stream via `html5: true` in Howler (uses `<audio>`, saves memory, slightly higher latency — fine for music).
-
----
-
-## 8. Bug-prevention checklist
-- **No sound on mobile/iOS** → didn't resume `AudioContext` synchronously inside a user gesture; add a tap-to-start unlock.
-- **Silence after backgrounding tab** → context re-suspended; resume on `visibilitychange`/focus.
-- **Clicks/pops on volume change or start/stop** → setting `gain.value` abruptly; ramp with `setTargetAtTime` and fade in/out a few ms.
-- **Laggy hit sounds** → using `<audio>` elements; use Web Audio buffer sources.
-- **Hitch on first play of a sound** → decoding at play time; preload + `decodeAudioData` during loading.
-- **Robotic repeated sounds** → no pitch/volume variation; randomize `playbackRate`.
-- **Growing memory / stuck voices** → not disconnecting finished sources or capping concurrent voices.
-- **Works in Chrome, silent in Safari** → format not supported (provide ogg/opus **and** mp3/m4a) or async break before `resume()`.
-- **No volume controls** → always expose master/music/sfx sliders + mute (accessibility + player expectation).
-
----
-
-## Defaults to apply
-- **Default to Howler.js** for generated games (handles unlock, sprites, fades, spatial, pooling) — fall back to raw Web Audio only when we need custom DSP/scheduling.
-- **Always wire the mixer graph**: master + music + sfx gain buses with sliders and a mute, from the first commit. Map sliders through a `x²` curve.
-- **Always add a "tap to start" gate** that unlocks audio (and pointer lock/fullscreen) on the first gesture, and re-resume on visibility change — kills the #1 "no audio on mobile" bug.
-- **Preload + decode on the loading screen**, reuse buffers, pitch-randomize repeated SFX, ramp all gain changes. Provide ogg/opus + mp3 fallbacks.
-
----
-
-## Sources
-- MDN — Web Audio API Best Practices (autoplay, gesture, gain, controls): https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Best_practices
-- MDN — `AudioContext.resume()`: https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/resume
-- MDN — `BaseAudioContext.decodeAudioData()`: https://developer.mozilla.org/en-US/docs/Web/API/BaseAudioContext/decodeAudioData
-- MDN — `GainNode` / `AudioParam.setTargetAtTime`: https://developer.mozilla.org/en-US/docs/Web/API/GainNode , https://developer.mozilla.org/en-US/docs/Web/API/AudioParam/setTargetAtTime
-- MDN — `PannerNode` + Web audio spatialization basics: https://developer.mozilla.org/en-US/docs/Web/API/PannerNode , https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics
-- MDN — `StereoPannerNode`: https://developer.mozilla.org/en-US/docs/Web/API/StereoPannerNode
-- MDN — Autoplay guide for media & Web Audio: https://developer.mozilla.org/en-US/docs/Web/Media/Autoplay_guide
-- Chris Wilson — "A Tale of Two Clocks" (Web Audio scheduling): https://web.dev/articles/audio-scheduling
-- Howler.js — docs & repo: https://howlerjs.com/ , https://github.com/goldfire/howler.js
-- Chrome autoplay policy for Web Audio: https://developer.chrome.com/blog/autoplay/#webaudio