@inneranimalmedia/agentsam-sdk 2.6.5 → 2.6.7

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

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

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

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

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