@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.8

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

@@ -1,277 +0,0 @@
-# Phaser 3 / 4 — Deep Engine Guide (scenes, physics, scale, tilemaps, pooling, architecture)
-
-Phaser is the default choice for **2D browser games**. This file goes deep on the parts that actually break in generated games. It assumes the general loop/mobile/perf rules in `threejs-foundational.md` and does **not** repeat them.
-
-> **Version note (verified):** Phaser **3** is the mature, ubiquitous line (3.90+). Phaser **4** shipped in 2025 with a rewritten WebGL renderer (internally "Beam") and optional **WebGPU** path, plus the core split into modular packages. Phaser 4 is *intentionally near-API-compatible with Phaser 3* — the Scene lifecycle, Arcade/Matter physics, Scale Manager, Loader and GameObject APIs described here carry over. Prefer Phaser 3 (3.90.x) for maximum stability/plugin compatibility today; use Phaser 4 when you want the faster renderer/WebGPU and can tolerate a younger ecosystem. When unsure, target v3 API surface — it runs on both.
-
----
-
-## 1. Scene model — the thing to get right first
-
-A Phaser game is a **stack of Scenes**, each an almost self-contained world (own display list, cameras, input, tweens, physics, clock). The `Phaser.Game` instance owns only truly global systems: **Renderer, Animation Manager, global Cache, Registry (global DataManager), Input Manager, Scene Manager, Sound Manager, TimeStep**. Everything else (`this.add`, `this.tweens`, `this.physics`, `this.input`, `this.cameras`) is **per-scene**. A tween created in Scene A is unrelated to one in Scene B.
-
-### Lifecycle callbacks (exact order)
-
-```js
-class GameScene extends Phaser.Scene {
-  constructor() { super('game'); }          // unique string key
-  init(data) {}      // (1) reset per-run state HERE, receives data from start/launch
-  preload() {}       // (2) queue asset loads only
-  create(data) {}    // (3) build objects; assets from preload are now ready
-  update(time, delta){} // (4) every tick while RUNNING (delta in ms)
-}
-```
-
-Status flow: `PENDING → INIT (booted) → START → LOADING → CREATING → RUNNING`. `RUNNING` can go to `PAUSED` (renders, no update) or `SLEEPING` (no update, no render), then back. `stop()` → `SHUTDOWN` (can restart). `remove()` → `DESTROYED` (gone).
-
-### The scene stack pattern (best-practice architecture)
-
-Run **multiple scenes at once**, layered bottom→top by config order:
-
-- **Boot** — load the tiny assets needed for the loading screen (bar image, logo); set Scale/registry defaults; `this.scene.start('preload')`.
-- **Preload** — load everything with a visible progress bar (`this.load.on('progress', v => …)`), then `start('menu')`.
-- **Menu / Title** — UI, start button.
-- **Game** — actual gameplay.
-- **UI / HUD** — run **in parallel** over Game via `this.scene.launch('ui')`; keeps HUD stable while Game restarts. Communicate via events/registry, never direct references.
-- **Pause / GameOver** — overlay scenes launched over Game.
-
-### Scene control verbs (get these exactly right — a top bug source)
-
-| Method | Effect on target | Effect on caller |
-|---|---|---|
-| `start('k')` | **stops** then starts k | **stops** caller |
-| `launch('k')` | starts k (parallel) | caller keeps running |
-| `switch('k')` | starts or **wakes** k | **sleeps** caller |
-| `run('k')` | resume if paused / wake if sleeping / restart if running / else start | caller keeps running |
-| `pause`/`resume` | freeze update, keep render | — |
-| `sleep`/`wake` | freeze update + render | — |
-| `stop` | shutdown | — |
-
-Rules of thumb: gameplay you replay from scratch → **start/stop** or **sleep/wake**; a modal (pause menu, shop) over live gameplay → **pause/resume** or **launch** an overlay; menus you revisit → **sleep/wake** is easier to reason about than start/stop.
-
-### The #1 Phaser correctness bug: state not reset on restart
-
-Scenes are **booted once, started many times**. Module-level or constructor-set flags persist across restarts.
-
-```js
-// BROKEN: gameOver stays true after restart → instant game over
-class S extends Phaser.Scene { constructor(){ super('s'); this.gameOver = false; } }
-
-// CORRECT: reset run state in init()
-class S extends Phaser.Scene {
-  constructor(){ super('s'); }
-  init(){ this.gameOver = false; this.score = 0; }   // runs on every start
-}
-```
-
-Related: arrays of destroyed game objects survive restart. **Clean up on SHUTDOWN**:
-```js
-this.events.once('shutdown', () => { this.enemies.length = 0; });
-```
-
-### Cleanup rule
-
-On `shutdown`, Phaser auto-destroys the scene's display list, tweens, timers and input. But **external references, global timers, DOM listeners, EventEmitter subscriptions on cross-scene emitters, and pooled arrays are yours to clear**. A destroyed GameObject still registered on an emitter is a classic crash. Always `this.events.once('shutdown', cleanup)`.
-
----
-
-## 2. Physics: Arcade vs Matter (choose deliberately)
-
-Phaser ships two physics systems. **Pick Arcade unless you specifically need Matter** — mixing/over-choosing is a common performance and complexity mistake.
-
-### Arcade Physics — AABB, fast, for platformers/shooters/arcade
-
-- **Only axis-aligned bounding boxes (rectangles) and circles.** No rotation of bodies, no slopes, no polygons. Extremely fast; handles thousands of bodies.
-- Two body types: **Dynamic** (`this.physics.add.sprite`) responds to velocity/gravity/collisions; **Static** (`this.physics.add.staticGroup`) never moves (platforms, walls) and is cheaper.
-- Core calls: `body.setVelocity(x,y)`, `setGravityY`, `setBounce`, `setCollideWorldBounds(true)`, `setImmovable(true)`, `setAllowGravity(false)`.
-- **Collide vs Overlap:**
-  - `this.physics.add.collider(a, b, cb)` — separates bodies (they block each other), optional callback.
-  - `this.physics.add.overlap(a, b, cb)` — detects overlap without separation (pickups, hitboxes, triggers).
-  - Both accept Groups, arrays, or single objects; add a `processCallback` (4th arg) to conditionally allow/deny a collision.
-- Config: `physics: { default: 'arcade', arcade: { gravity: { y: 300 }, debug: true } }`. Turn on `debug` while building — it draws body outlines and velocity vectors and reveals 90% of "collision doesn't work" issues.
-- Set body size explicitly for non-rectangular sprites: `sprite.body.setSize(w,h).setOffset(x,y)` or `setCircle(r)`.
-- **Fast small objects tunnel through thin walls** (AABB, discrete step). Mitigate: thicker colliders, cap max velocity, or set world bounds; Arcade has limited continuous collision.
-
-### Matter.js — full rigid-body, for physics-toys/ragdolls/complex shapes
-
-- Real rigid-body dynamics: rotation, arbitrary convex/compound polygons, constraints/joints, springs, restitution, friction, sleeping bodies.
-- Use when the *physics itself is the game* (Angry-Birds-like, stacking, contraptions, vehicles) or you need realistic collisions/rotation.
-- Config: `physics: { default: 'matter', matter: { gravity: { y: 1 }, debug: true } }`.
-- `this.matter.add.sprite(x,y,key,null,{ shape:'circle', restitution:0.6 })`. Use collision events: `this.matter.world.on('collisionstart', (e)=>{ for (const p of e.pairs){…} })`, plus **collision filters/categories** for what hits what.
-- Heavier than Arcade; watch body counts on mobile. Enable body sleeping for idle stacks.
-
-**Decision:** platformer, top-down shooter, endless runner, breakout, most casual games → **Arcade**. Physics sandbox, realistic stacking/rotation, joints → **Matter**. Don't reach for Matter just for "better collisions" — 90% of 2D games are Arcade games.
-
----
-
-## 3. Scale Manager — responsive/mobile without stretching
-
-Set once in game config. The two modes that matter:
-
-```js
-scale: {
-  mode: Phaser.Scale.FIT,          // letterbox: keep aspect, fit inside parent
-  autoCenter: Phaser.Scale.CENTER_BOTH,
-  width: 800, height: 600,         // your fixed design resolution
-  parent: 'game',
-  // min/max clamp the FIT scaling:
-  min: { width: 400, height: 300 }, max: { width: 1600, height: 1200 }
-}
-```
-
-- **`FIT`** — canvas scales to fit the parent preserving aspect ratio; letterbox bars appear. Your game logic runs at a **fixed design resolution** (800×600 here) — simplest and most predictable. Best default for most games.
-- **`RESIZE`** — canvas always matches parent size; **no fixed resolution**, game world dimensions change. You must handle the `resize` event and reposition/relayout UI yourself (`this.scale.on('resize', (gameSize)=>{…})`). Use for games that should truly fill the screen (strategy, infinite canvas) where you can reflow layout.
-- `ENVELOP` — cover the parent (may crop). `WIDTH_CONTROLS_HEIGHT` / `HEIGHT_CONTROLS_WIDTH` — lock one axis.
-- `NONE` — fixed, no scaling.
-
-**Orientation:** listen `this.scale.on('orientationchange', o => …)` or check `this.scale.isPortrait`. For a landscape-only game, show a "rotate your device" overlay in portrait rather than fighting the layout. Combine with `viewport` meta + `touch-action: none` (see three.js file §7).
-
-**Retina/DPR:** Phaser respects `resolution`/DPR via the renderer; for pixel-art keep `pixelArt: true` (sets nearest-neighbor + disables antialias) and `roundPixels: true` to avoid sub-pixel shimmer. Rendering at a modest internal resolution and letting FIT upscale is a legit perf win on mobile.
-
----
-
-## 4. Sprites, atlases & animations
-
-- **Always pack sprites into a texture atlas** (TexturePacker → JSON Hash/Array, or free tools). One atlas = one texture bind = fewer draw calls and no seams. `this.load.atlas('sheet','sheet.png','sheet.json')`, then `this.add.sprite(x,y,'sheet','frameName')`.
-- Uniform grid frames → `this.load.spritesheet('run','run.png',{ frameWidth:32, frameHeight:32 })`.
-- Animations are **global** (stored on the Animation Manager), defined once, reused by any sprite in any scene:
-  ```js
-  this.anims.create({ key:'run', frames:this.anims.generateFrameNames('sheet',{prefix:'run_',start:0,end:7,zeroPad:2}), frameRate:12, repeat:-1 });
-  sprite.play('run');
-  ```
-- Batching: sprites sharing the **same texture** batch into few draw calls. Interleaving textures (sprite from atlas A, then B, then A) breaks the batch. Group same-texture sprites and set depth thoughtfully.
-- Bitmap fonts (`load.bitmapFont`) render far cheaper than lots of dynamic `Text` objects (each `Text` is its own canvas texture — expensive to update every frame). For frequently-changing text prefer bitmap fonts or update sparingly.
-
----
-
-## 5. Tilemaps
-
-For levels, use **Tiled** (`.tmx`/exported JSON) rather than hand-placing sprites.
-
-```js
-// preload
-this.load.image('tiles','tileset.png');
-this.load.tilemapTiledJSON('map','level1.json');
-// create
-const map = this.make.tilemap({ key:'map' });
-const tileset = map.addTilesetImage('tilesetNameInTiled','tiles');
-const ground = map.createLayer('Ground', tileset, 0, 0);
-ground.setCollisionByProperty({ collides:true });        // set per-tile in Tiled
-this.physics.add.collider(player, ground);
-// object layer for spawns/enemies:
-const objs = map.getObjectLayer('Objects').objects;
-```
-
-- **Static layers** (`createLayer`) are fast (culled, batched). Dynamic tile edits use the same layer API (`putTileAt`, `removeTileAt`) — layers are dynamic in current Phaser.
-- Set collision by **property** or by tile index/array; visualize with `layer.renderDebug(graphics)`.
-- Cull off-screen tiles automatically via the camera; keep tile layers reasonably sized, split huge worlds into chunks.
-- Use **object layers** for spawn points, triggers, and entity placement instead of hardcoding coordinates.
-
----
-
-## 6. Object pooling with Groups (the mobile perf lever)
-
-Creating/destroying bullets, enemies, particles every frame thrashes GC and stutters. **Pool them.**
-
-```js
-this.bullets = this.physics.add.group({
-  classType: Bullet, maxSize: 64, runChildUpdate: true
-});
-// fire:
-const b = this.bullets.get(x, y);        // reuse dead one or make new (up to maxSize)
-if (!b) return;                          // pool exhausted → skip
-b.enableBody(true, x, y, true, true);    // reactivate + show
-// on expire/off-screen: DON'T destroy — recycle:
-b.disableBody(true, true);               // deactivate + hide, returns to pool
-```
-
-- `get()` returns an **inactive** member (recycled) or creates a new one until `maxSize`; returns `null` when full — always null-check.
-- `killAndHide(child)` / `disableBody(true,true)` recycles; avoid `destroy()` for pooled objects.
-- `runChildUpdate:true` calls each active child's `preUpdate`/`update` — put per-object logic in the class.
-- Only iterate **active** members: `this.bullets.getChildren()` and skip `!child.active`, or use `group.getMatching('active', true)`.
-- Reuse tween/particle emitters too; destroy emitters and tweens on `SHUTDOWN`.
-
----
-
-## 7. Input
-
-- Keyboard: `this.cursors = this.input.keyboard.createCursorKeys()` (arrows + space/shift), or `this.keys = this.input.keyboard.addKeys('W,A,S,D')`. **Read state in `update` via `.isDown`**; use `Phaser.Input.Keyboard.JustDown(key)` for single-press actions. Don't drive movement off `keydown` events.
-- Pointer/touch: `this.input.on('pointerdown', p => …)`; enable object interaction with `sprite.setInteractive()` then `sprite.on('pointerdown', …)`. Set explicit hit areas for irregular sprites.
-- Unify keyboard + touch + **Gamepad API** (`this.input.gamepad`) into one input-state object your `update` reads, so control code doesn't branch per device.
-- Drag: `this.input.setDraggable(sprite)` + `'drag'` event. For virtual joysticks on mobile, integrate nipplejs or the rex virtual joystick plugin and feed normalized -1..1 into your input state.
-
----
-
-## 8. Cameras & tweens
-
-- Each scene has a main camera (`this.cameras.main`). Follow the player: `camera.startFollow(player, true, 0.08, 0.08)` (lerp for smooth follow), set `camera.setBounds(0,0,mapW,mapH)` and `setZoom()`. `setDeadzone()` avoids jitter around the player.
-- Effects for free polish: `camera.shake(200, 0.01)`, `camera.flash()`, `camera.fade()`. Multiple cameras enable split-screen / minimaps (`camera.ignore(objects)` to exclude).
-- Tweens for juice: `this.tweens.add({ targets:sprite, scale:1.2, yoyo:true, duration:120, ease:'Sine.easeInOut' })`. **Always destroy long-lived/looping tweens on SHUTDOWN** or they reference dead objects.
-
----
-
-## 9. Cross-scene communication (avoid spaghetti)
-
-- **Registry** (global DataManager): `this.registry.set('score', 0)` / `get` — shared across all scenes; emits `changedata` events.
-- **Scene events / a shared EventEmitter** ("EventsCenter"): create one `new Phaser.Events.EventEmitter()` in a module, import into scenes, emit/subscribe. Lets the UI scene react to Game scene events with **zero direct coupling**. Always `off()` listeners on shutdown.
-- `this.scene.get('ui').events.emit(...)` works but couples scenes — prefer the shared emitter/registry.
-- Pass one-shot data via `this.scene.start('game', { level: 3 })` → arrives in `init(data)` / `create(data)`.
-
----
-
-## 10. Performance checklist (Phaser-specific)
-
-- **Object pooling** for anything spawned repeatedly (bullets, enemies, particles, floating text).
-- **Texture atlases** everywhere; group same-texture draws to keep batches intact.
-- Turn **off physics debug** in production; only add bodies to objects that need them.
-- Process **only active** objects; set `sprite.active=false`/`visible=false` for off-screen entities instead of updating them.
-- Prefer **static** physics bodies / static tile layers for non-moving geometry.
-- Minimize per-frame `Text` updates and `Graphics` re-draws (redrawing a Graphics every frame is expensive) — cache to a texture (`generateTexture`) or use bitmap fonts.
-- Avoid per-frame allocations in `update`; reuse vectors/objects.
-- Destroy tweens, timers (`this.time` events), and particle emitters on `SHUTDOWN`; clear pooled arrays.
-- Lazy-load per-level assets in that level's preload; unload with `this.textures.remove` / `this.cache` when leaving big levels.
-- Smaller canvas + FIT upscale on low-end mobile; consider `Phaser.CANVAS` fallback only if WebGL is unavailable (WebGL is default and much faster).
-- Profile with the browser FPS meter and `game.loop.actualFps`; Phaser 4's WebGPU path reduces CPU draw-call overhead further.
-
----
-
-## 11. Common Phaser pitfalls (checklist)
-
-- Run-state not reset in `init()` → instant game-over / carried-over score after restart.
-- Not cleaning arrays/emitter listeners on `shutdown` → crashes on destroyed objects after restart.
-- Using `this.scene.start` when you meant `launch` (start stops the caller — kills your HUD).
-- Movement/animation not scaled by `delta` (Phaser `update(time, delta)` gives delta in **milliseconds**).
-- Physics body doesn't match sprite art → set `body.setSize/offset`; wrong/no collider group; forgetting `setCollideWorldBounds`.
-- Fast objects tunneling through thin walls in Arcade → thicker walls / velocity cap.
-- Text objects updated every frame tanking FPS → bitmap fonts / update on change only.
-- Creating instead of pooling bullets/enemies → GC stutter on mobile.
-- `RESIZE` scale mode without repositioning UI → misaligned HUD; use `FIT` unless you handle `resize`.
-- Loading assets in `create` instead of `preload` → assets not ready / race conditions.
-- Mixing Matter + Arcade needlessly, or choosing Matter when Arcade suffices → perf and complexity cost.
-
----
-
-## Defaults to apply
-
-- **Default to Phaser (v3 API) for any 2D game**; scaffold the **Boot → Preload(progress bar) → Menu → Game → parallel UI → Pause/GameOver** scene stack automatically.
-- **Always put per-run state reset in `init()`** and register a `this.events.once('shutdown', cleanup)` in every gameplay scene — this alone eliminates the most common generated-game bug (broken restart).
-- **Choose Arcade physics by default; only emit Matter when the physics is the game.** Encode the decision table above in the builder's engine-selection step.
-- **Emit object pools (Groups with `maxSize` + recycle via `disableBody`) for bullets/enemies/particles** rather than create/destroy, and **texture atlases** for all sprites.
-- Use **`Scale.FIT` + fixed design resolution + `CENTER_BOTH`** as the responsive default; add a rotate-device overlay for orientation-locked games.
-- Load levels from **Tiled JSON tilemaps** with collision-by-property and object layers for spawns, instead of hardcoded coordinates.
-- Decouple scenes via a **shared EventEmitter + Registry**, never direct scene references.
-- Turn **physics `debug` on during generation/testing, off in the shipped build.**
-
----
-
-## Sources
-- Phaser official docs — Scenes (lifecycle, systems, control methods, restart pitfalls): https://docs.phaser.io/phaser/concepts/scenes
-- Phaser docs — Arcade Physics: https://docs.phaser.io/phaser/concepts/physics/arcade ; Matter Physics: https://docs.phaser.io/phaser/concepts/physics/matter
-- Phaser docs — Scale Manager: https://docs.phaser.io/phaser/concepts/scale-manager
-- Phaser docs — Tilemaps: https://docs.phaser.io/phaser/concepts/tilemaps ; Loader: https://docs.phaser.io/phaser/concepts/loader
-- Phaser docs — Groups & object pooling: https://docs.phaser.io/phaser/concepts/gameobjects/group ; Animations: https://docs.phaser.io/phaser/concepts/animations
-- Phaser docs — Input (keyboard/pointer/gamepad): https://docs.phaser.io/phaser/concepts/input
-- Phaser 4 announcement / release: https://phaser.io/news (Phaser 4 + Beam renderer / WebGPU) and https://github.com/phaserjs/phaser/releases
-- API reference: https://newdocs.phaser.io/docs/latest
-- franzeus.medium.com — "How I optimized my Phaser 3 action game" (pooling, atlases, active-only processing)
-- joshmorony.com — Phaser scaling / responsive guides

package/skills/grok-building-games/references/procedural-generation.md

@@ -1,141 +0,0 @@
-# Procedural Generation (seeded RNG, noise, dungeons/mazes/terrain, wave function collapse)
-
-Consolidated from Red Blob Games, the simplex-noise library, and WFC primary sources (see Sources). Focus: what an AI builder needs to generate **varied but reproducible** worlds without the classic bugs — non-deterministic output, disconnected dungeons, blobby/banded terrain.
-
----
-
-## 1. Seeded RNG is the foundation — never use bare `Math.random()`
-
-`Math.random()` is **not seedable**, so you can't reproduce a level, share a seed, debug a bad map, or sync generation across clients in multiplayer. **Always drive procedural generation from a seeded PRNG.**
-
-**mulberry32** — the go-to small, fast, good-quality 32-bit seeded PRNG:
-```js
-function mulberry32(seed) {
-  return function () {
-    let t = (seed += 0x6D2B79F5);
-    t = Math.imul(t ^ (t >>> 15), t | 1);
-    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296; // [0,1)
-  };
-}
-const rng = mulberry32(12345); // same seed → identical sequence forever
-```
-
-Rules:
-- **Hash string seeds to an int first** (e.g. `xmur3`) so `"cave-42"` maps to a stable number.
-- **Use separate RNG streams for independent systems** (terrain vs loot vs enemy placement) so changing one doesn't reshuffle the others (`mulberry32(seed)`, `mulberry32(seed ^ 0x9e3779b9)`, …).
-- Add helpers: `randRange(a,b)=a+rng()*(b-a)`, `randInt`, `pick(arr)`, `shuffle` (Fisher–Yates using `rng`).
-- For **networked/deterministic** generation, both sides must run the *same* PRNG and consume it in the *same order* (deterministic multiplayer is out of scope on this deploy target). Order-of-consumption bugs are the #1 desync source.
-- Alternatives: `alea`, PCG. mulberry32 is plenty for games.
-
----
-
-## 2. Noise: value / Perlin / simplex (for terrain, textures, organic fields)
-
-Random-per-cell is white noise (harsh, uncorrelated). **Coherent noise** produces smooth, natural-looking fields where nearby points are similar.
-
-- **Value noise** — cheap, interpolate random lattice values. OK for simple stuff.
-- **Perlin noise** — classic gradient noise; can show axis-aligned artifacts.
-- **Simplex / OpenSimplex** — fewer directional artifacts, scales better to higher dimensions; preferred default. Use the **`simplex-noise` npm package**.
-  - **v4 API changed:** no more `new SimplexNoise()`. Use factory functions and pass your seeded PRNG:
-  ```js
-  import { createNoise2D } from 'simplex-noise';
-  const noise2D = createNoise2D(mulberry32(12345)); // returns ~[-1, 1]
-  const v = noise2D(x * 0.01, y * 0.01);            // scale coords = "frequency"
-  ```
-  (Also `createNoise3D`/`createNoise4D`; passing a PRNG makes output reproducible — without one it uses `Math.random()` = non-reproducible.)
-
-**Key techniques (from Red Blob Games "Making maps with noise"):**
-- **Frequency:** multiply input coords by a scale; small scale = large smooth features.
-- **Octaves / fBm:** sum several noise layers at increasing frequency and decreasing amplitude (`amplitude *= persistence(≈0.5)`, `frequency *= lacunarity(≈2)`) for natural detail.
-- **Normalize** noise from [−1,1] to [0,1] before thresholding.
-- **Redistribution:** `elev = Math.pow(elev, k)` to bias toward valleys/plains vs peaks.
-- **Island mask:** multiply by a radial falloff so edges are water.
-- **Biomes:** sample **two independent noise fields** (elevation + moisture) and look up a Whittaker-style biome table — don't derive moisture from elevation (they'd correlate and look wrong).
-
----
-
-## 3. Dungeon / room generation
-
-Common approaches, pick per game:
-- **Rooms + corridors (BSP or random placement):** place non-overlapping rooms, then connect. BSP recursively splits space and puts a room in each leaf; connect sibling leaves → guaranteed structure. Random placement: drop rooms, reject overlaps, connect with L-shaped/A* corridors.
-- **Cellular automata caves:** fill grid randomly (~45% wall), run several smoothing passes (`cell = neighbors≥5 ? wall : floor`) → organic caverns. Then **flood-fill and keep only the largest connected region** (or carve tunnels to connect regions).
-- **Drunkard's walk / random walk:** carve floors along a random walk for winding caves.
-
-**Critical rule: guarantee connectivity.** After generation, **flood-fill from the entrance and verify every important tile (exit, key rooms, loot) is reachable.** Discard/regenerate or carve connectors otherwise. "Unreachable exit / locked-in player" is the #1 procgen bug. Also validate: min room count, spawn ≠ exit, no soft-locks.
-
----
-
-## 4. Maze generation
-
-- Grid where each cell has walls; carve passages.
-- **Recursive backtracker (randomized DFS):** deep, winding mazes with long corridors — most common.
-- **Randomized Prim's / Kruskal's:** more uniform, bushier mazes.
-- All produce a "perfect maze" (exactly one path between any two cells). Add **loops** by knocking out extra walls if you want multiple routes.
-- Use your seeded `rng` for neighbor choice so the maze is reproducible.
-
----
-
-## 5. Terrain generation
-
-- **Heightmap from fBm simplex** (see §2): sample noise per cell → elevation → color/mesh. Threshold into water/sand/grass/rock/snow bands.
-- **Domain warping** (offset sample coords by another noise) for more natural, less "blobby" coastlines.
-- For 3D: feed the heightmap into a plane geometry's vertex Y (Three.js `PlaneGeometry` + displace vertices) and `computeVertexNormals()`; consider chunking + LOD for large worlds.
-- Keep generation **deterministic per chunk**: derive each chunk's local seed from `(worldSeed, chunkX, chunkY)` so infinite/streamed worlds are stable and reproducible.
-
----
-
-## 6. Wave Function Collapse (WFC) basics
-
-WFC is a constraint-solver that generates output where every local neighborhood matches examples/adjacency rules — great for tile maps, textures, and levels that must "fit together."
-
-Algorithm (overlapping or simple-tiled):
-1. Every cell starts in **superposition** (all tiles possible).
-2. **Observe:** pick the lowest-entropy cell (fewest remaining options) and **collapse** it to one tile (weighted-random).
-3. **Propagate:** remove now-impossible neighbors' options based on adjacency rules; repeat until stable.
-4. Loop until all cells collapsed, or **backtrack/restart on contradiction** (a cell with zero options).
-
-Rules & gotchas:
-- Adjacency rules come from a sample image (overlapping model) or hand-authored tile edges (simple-tiled model).
-- **Contradictions happen** — implement restart or backtracking; without it, generation hangs/throws.
-- Weight tiles for aesthetics; use noise (from §2) to bias regional weights for large-scale structure, then WFC for coherent local detail.
-- For JS: **mxgmn/WaveFunctionCollapse** (original), Boris the Brave's write-up + **DeBroglie**, or ndarray-based JS ports.
-
-> Note: Red Blob Games does **not** have a WFC tutorial (a common false citation). Cite Maxim Gumin's repo and Boris the Brave instead. Red Blob Games *is* the canonical source for **noise maps** and **A\*/grids**.
-
----
-
-## 7. Bug-prevention checklist
-- **`Math.random()` for generation** → non-reproducible, unshareable, undebuggable, desyncs multiplayer; use a seeded PRNG.
-- **String seed used directly** → NaN/garbage; hash to int (xmur3) first.
-- **Shared single RNG stream across systems** → tweaking one system reshuffles all; use separate streams.
-- **No connectivity check** → unreachable exits / trapped player; flood-fill validate & regenerate.
-- **Forgetting to seed simplex-noise (v4)** → falls back to `Math.random()`, non-reproducible; pass your PRNG to `createNoise2D`.
-- **Single-octave noise** → smooth but featureless; add fBm octaves.
-- **Deriving moisture from elevation** → correlated, unrealistic biomes; use independent noise fields.
-- **WFC with no contradiction handling** → infinite loop / crash; add restart/backtrack.
-- **Per-frame regeneration or huge synchronous gen** → jank; generate in chunks / a web worker / on level load.
-- **Non-deterministic chunk seeds** → seams/flicker in streamed worlds; derive chunk seed from `(worldSeed, cx, cy)`.
-
----
-
-## Defaults to apply
-- **Every generated procgen game gets a visible/optional seed** driven by **mulberry32** (with xmur3 for string seeds), plus `randRange/randInt/pick/shuffle` helpers and **separate RNG streams** per system. Reproducibility is free QA, shareable content, and multiplayer-safe.
-- **Terrain/organic → seeded `simplex-noise` v4 (`createNoise2D(rng)`) with fBm octaves + redistribution + island mask + independent elevation/moisture** per Red Blob Games.
-- **Dungeons → rooms+corridors or cellular-automata caves, ALWAYS followed by a flood-fill connectivity guarantee** (regenerate on failure). Ship this validation step by default — it prevents the worst procgen bug.
-- **Offer WFC** for tile-based levels/textures (with contradiction restart), optionally seeded by noise for macro structure. Do heavy generation in a worker/on load, not per frame.
-
----
-
-## Sources
-- Red Blob Games — Making maps with noise functions: https://www.redblobgames.com/maps/terrain-from-noise/
-- Red Blob Games — Noise (value/Perlin/simplex intro): https://www.redblobgames.com/articles/noise/introduction.html
-- Red Blob Games — Procedural map/dungeon & grids index: https://www.redblobgames.com/
-- simplex-noise (npm, v4 `createNoise2D` API): https://www.npmjs.com/package/simplex-noise , https://github.com/jwagner/simplex-noise.js
-- mulberry32 / xmur3 seeded PRNGs (bryc's gist): https://github.com/bryc/code/blob/master/jshash/PRNGs.md
-- Stefan Gustavson — Simplex noise demystified (PDF): https://weber.itn.liu.se/~stegu/simplexnoise/simplexnoise.pdf
-- Ken Perlin — Improving Noise (SIGGRAPH 2002): https://mrl.cs.nyu.edu/~perlin/paper445.pdf
-- Cellular-automata cave generation (RogueBasin): https://www.roguebasin.com/index.php/Cellular_Automata_Method_for_Generating_Random_Cave-Like_Levels
-- BSP dungeon generation (RogueBasin): https://www.roguebasin.com/index.php/Basic_BSP_Dungeon_generation
-- Maze generation algorithms — Jamis Buck ("Buckblog") & "Mazes for Programmers": https://weblog.jamisbuck.org/2011/2/7/maze-generation-algorithm-recap
-- Wave Function Collapse — Maxim Gumin (original): https://github.com/mxgmn/WaveFunctionCollapse ; Boris the Brave, "WFC explained": https://www.boristhebrave.com/2020/04/13/wave-function-collapse-explained/

package/skills/grok-building-games/references/save-persistence.md

@@ -1,108 +0,0 @@
-# Save & Persistence for Browser Games (localStorage vs IndexedDB, versioned saves, serialization, autosave)
-
-Consolidated from MDN storage docs and the `idb` library (see Sources). Focus: what an AI builder needs so saves **survive updates, don't corrupt, and don't block the frame** — the usual bugs are lost progress on a schema change, quota errors, and jank from synchronous writes.
-
----
-
-## 1. Pick the right storage
-
-**`localStorage`** — simple key/value, **synchronous, string-only, ~5MB** per origin.
-- Good for: small settings, high scores, current-level, a single small save blob, key bindings, volume.
-- **Synchronous = it blocks the main thread.** Fine for occasional small writes; **do NOT write large/frequent blobs to it every frame** (causes hitches). Values must be strings → `JSON.stringify`/`parse`.
-- `sessionStorage` = same API but cleared when the tab closes (use for transient state only).
-
-**IndexedDB** — **asynchronous**, transactional, large (hundreds of MB to GB, quota-based), stores **structured data** (objects, arrays, `Blob`, `ArrayBuffer`, typed arrays via the structured clone algorithm — no manual JSON needed).
-- Good for: big/complex saves, multiple save slots, replays, generated assets/level caches, offline data.
-- The raw API is verbose/callbacky — **use the `idb` wrapper** (Jake Archibald) for a clean promise-based API. Don't hand-roll raw IndexedDB.
-
-**Rule of thumb:** settings/scores/small single save → `localStorage`; anything large, multi-slot, binary, or frequently written → **IndexedDB (via `idb`)**. Cookies are the wrong tool for game saves (tiny, sent on every request).
-
-**Cache API / service worker** is for caching the *game itself* (assets, offline PWA), not for player save data.
-
----
-
-## 2. ALWAYS version your saves (the #1 lost-progress bug)
-
-Your save schema *will* change between game versions. If you `JSON.parse` an old save into new code with no version handling, you get crashes or silent corruption and angry players who lost progress.
-
-**Rule: every save carries a `version` number, and you write migration steps between versions.**
-```js
-const SAVE_VERSION = 3;
-function migrate(save) {
-  let s = { ...save };
-  if (s.version === 1) { s.coins = s.gold ?? 0; delete s.gold; s.version = 2; }
-  if (s.version === 2) { s.settings = { ...defaults.settings, ...s.settings }; s.version = 3; }
-  return s; // now at SAVE_VERSION
-}
-function loadSave(raw) {
-  let save = raw ?? structuredClone(defaultSave);
-  if (save.version !== SAVE_VERSION) save = migrate(save);
-  return save;
-}
-```
-- Migrations run **in sequence** (v1→v2→v3) so any old save upgrades.
-- IndexedDB has its own **schema versioning** via the `open(name, version)` + `onupgradeneeded`/`idb`'s `upgrade` callback — use it to create/alter object stores. That's separate from your *data* version above; you often want both.
-- **New fields:** merge over defaults (`{ ...defaults, ...loaded }`) so older saves gain new keys with sane values instead of `undefined`.
-- Keep a **backup of the previous save** before overwriting, so a failed migration/corruption is recoverable.
-
----
-
-## 3. Serialization: what to save
-
-- **Save state, not behavior.** Serialize plain data (positions, inventory, flags, RNG seed + counters). Never try to serialize class instances/functions/DOM/engine objects directly.
-- **Save the seed + progress**, not the whole generated world, for procgen games — regenerate deterministically on load (see procgen skill). Massively smaller and robust.
-- Use `structuredClone` / IndexedDB for objects with `Map`/`Set`/`Date`/typed arrays; **plain `JSON` drops those** (Map→`{}`, Date→string, `undefined`/functions omitted, `NaN`/`Infinity`→`null`). If using JSON, convert them explicitly.
-- **Wrap every load in try/catch.** Corrupt/partial JSON must fall back to defaults, not white-screen the game.
-- Consider a **checksum** or at least shape-validation of loaded data before trusting it. For competitive/leaderboard games remember client saves are trivially editable — validate server-side, don't trust local high scores.
-
----
-
-## 4. Autosave (do it safely)
-
-- **Autosave on meaningful events** (level complete, checkpoint, item gained) and on a throttled timer — not every frame.
-- **Debounce/throttle writes** (e.g. at most once every few seconds) to avoid thrashing storage and causing jank; coalesce rapid changes.
-- **Save on `visibilitychange` (hidden) and `pagehide`/`beforeunload`** — mobile browsers kill backgrounded tabs without firing `beforeunload` reliably, so `visibilitychange → hidden` is the most reliable "player is leaving" signal. Do a final synchronous-ish flush there (localStorage) or a queued IndexedDB write.
-- **Write atomically:** for IndexedDB use a transaction; for localStorage, build the full string then set it once (a half-written multi-key save = corruption). Keep the previous save until the new one is confirmed.
-- Give visible feedback ("Saved") and expose manual save/load + multiple slots where appropriate.
-
----
-
-## 5. Quota, availability & privacy gotchas
-- **Storage can throw or be disabled:** private/incognito mode, quota exceeded (`QuotaExceededError`), or blocked third-party storage. **Feature-detect and wrap in try/catch**; degrade gracefully (in-memory only) rather than crashing.
-- **Eviction:** browsers can clear storage under pressure ("best-effort" default). For important saves, request **`navigator.storage.persist()`** to reduce eviction risk, and check `navigator.storage.estimate()` for usage/quota.
-- Storage is **per-origin**; a domain change loses saves. iOS Safari has historically been aggressive about clearing storage from rarely-visited sites — don't treat browser storage as permanent; offer export/import (download/upload a save file) for anything precious, and cloud save for accounts.
-- **`localStorage` blocks the main thread** — keep values small; move big/async work to IndexedDB.
-
----
-
-## 6. Bug-prevention checklist
-- **No version field** → old saves crash new builds / silent data loss; version + sequential migrations.
-- **Parsing without try/catch** → corrupt save white-screens the game; fall back to defaults.
-- **Merging loaded save without defaults** → new fields are `undefined`; spread over defaults.
-- **JSON round-trip of Map/Set/Date/typed arrays** → data silently lost; use structuredClone/IndexedDB or convert explicitly.
-- **Frequent/large `localStorage.setItem`** → main-thread hitches; throttle + use IndexedDB for big data.
-- **No save on tab hide** → mobile players lose progress; save on `visibilitychange`/`pagehide`.
-- **Non-atomic multi-key writes** → partial/corrupt saves; write one blob / use a transaction, keep a backup.
-- **Assuming storage always works** → crashes in private mode / over quota; feature-detect + try/catch + graceful degrade.
-- **Trusting local high scores** → trivially cheatable; validate server-side for leaderboards.
-- **Saving the whole procgen world** → bloated saves; save seed + progress and regenerate.
-
----
-
-## Defaults to apply
-- **Ship a tiny save module by default:** `save(state)` / `load()` with a **`version` field + sequential `migrate()`**, **try/catch → defaults**, and **merge-over-defaults**. This single pattern prevents the most damaging bug (progress lost on update).
-- **Storage routing rule baked in:** settings/scores/small save → `localStorage`; large/multi-slot/binary/frequent → **IndexedDB via `idb`**.
-- **Autosave defaults:** save on checkpoints + throttled timer + **`visibilitychange`/`pagehide`**, written atomically with a retained backup.
-- **Persist the seed, not the world** for procgen; offer **export/import** for precious saves and request `storage.persist()`. Never trust local scores for leaderboards.
-
----
-
-## Sources
-- MDN — Web Storage API (`localStorage`/`sessionStorage`): https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API
-- MDN — IndexedDB API + Using IndexedDB (versioning/`onupgradeneeded`): https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API , https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Using_IndexedDB
-- MDN — Structured clone algorithm (what serializes): https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm ; `structuredClone()`: https://developer.mozilla.org/en-US/docs/Web/API/structuredClone
-- MDN — Storage quotas & eviction / `navigator.storage`: https://developer.mozilla.org/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria , https://developer.mozilla.org/en-US/docs/Web/API/StorageManager/persist
-- MDN — `Document.visibilitychange` / Page Visibility API: https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API
-- `idb` (promise-based IndexedDB wrapper, Jake Archibald): https://github.com/jakearchibald/idb
-- web.dev — "Storage for the web" (choosing storage): https://web.dev/articles/storage-for-the-web
-- localForage (localStorage-like API over IndexedDB): https://github.com/localForage/localForage