@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.8

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

@@ -1,202 +0,0 @@
-# Babylon.js — Deep Engine Guide (Havok physics, cameras, SceneOptimizer, WebGPU, assets, GUI, freezing)
-
-Babylon.js is the "batteries-included" 3D engine: built-in physics, inspector, GUI, node materials, camera behaviors, SceneOptimizer, and a first-class WebGPU backend. Use it when you want an integrated engine rather than assembling Three.js + libraries.
-
-This file assumes the general loop/orientation/perf rules and the short Babylon perf bullets in `threejs-foundational.md` and goes **much deeper** without repeating them.
-
----
-
-## 1. Engine setup & the render loop
-
-```js
-import { Engine, Scene, Vector3 } from "@babylonjs/core";
-const engine = new Engine(canvas, true, { preserveDrawingBuffer: false, stencil: true, powerPreference: "high-performance" });
-const scene = new Scene(engine);
-engine.runRenderLoop(() => scene.render());
-window.addEventListener("resize", () => engine.resize());
-```
-
-- `engine.runRenderLoop` is Babylon's RAF loop; hook game logic into **`scene.onBeforeRenderObservable`** and read delta with **`engine.getDeltaTime()`** (ms) or `scene.getAnimationRatio()` (frame-rate compensation factor). Scale movement by delta as always.
-- Use **`scene.onBeforeRenderObservable.add(fn)`** for per-frame logic instead of stuffing everything in the render loop closure — it's observable, disposable, and composable.
-- `engine.setHardwareScalingLevel(n)` renders at 1/n resolution (n>1 = lower res, big mobile win; n<1 = supersample).
-
----
-
-## 2. WebGPU (real, production-ready — prefer it with fallback)
-
-Babylon has a mature **`WebGPUEngine`** that dramatically cuts CPU-side draw-call overhead and enables compute shaders.
-
-```js
-import { WebGPUEngine, Engine } from "@babylonjs/core";
-async function createEngine(canvas) {
-  if (await WebGPUEngine.IsSupportedAsync) {
-    const e = new WebGPUEngine(canvas, { antialias: true });
-    await e.initAsync();            // REQUIRED before creating a Scene
-    return e;
-  }
-  return new Engine(canvas, true, { powerPreference: "high-performance" });   // WebGL2 fallback
-}
-```
-
-- `WebGPUEngine.initAsync()` **must be awaited** before you create the scene — a top setup bug.
-- **Snapshot rendering** (`engine.snapshotRendering = true`, WebGPU only) records the command stream for a static scene and replays it, slashing CPU cost for scenes whose draw list doesn't change. Set `snapshotRenderingMode` and refresh when the scene structure changes.
-- WebGPU supports **compute shaders** (particles, culling, GPU picking) — not available on WebGL.
-
----
-
-## 3. Cameras & Camera Behaviors (free polish)
-
-- **ArcRotateCamera** — orbit/inspection. Set limits and inertia so it feels good: `lowerRadiusLimit`/`upperRadiusLimit`, `lowerBetaLimit`/`upperBetaLimit`, `wheelPrecision`, `panningSensibility`, `inertia`. `camera.attachControl(canvas, true)`.
-- **UniversalCamera** — FPS/free camera (WASD + mouse; combines FreeCamera + touch/gamepad). `camera.applyGravity`, `camera.checkCollisions`, `camera.ellipsoid` for simple capsule collision against meshes with `mesh.checkCollisions = true` (built-in, no physics engine needed).
-- **FollowCamera** — third-person chase; set `radius`, `heightOffset`, `rotationOffset`, `cameraAcceleration`, `maxCameraSpeed`.
-- **Keep `camera.maxZ` as small as practical** and `minZ` as large as practical — improves depth precision, culling, and overdraw.
-
-**Behaviors** attach polished motion for free (this is a Babylon differentiator):
-- **FramingBehavior** — auto-frames a target mesh nicely (`camera.useFramingBehavior = true`).
-- **BouncingBehavior** — soft bounce at radius limits.
-- **AutoRotationBehavior** — idle turntable spin (great for product/menu scenes).
-Enable via `camera.useAutoRotationBehavior = true` etc., then tune the behavior object.
-
----
-
-## 4. Physics — Havok (V2 plugin, the current default)
-
-Havok is the recommended physics engine (WASM, fast, deterministic-ish). Use the **Physics V2** API (`PhysicsAggregate` / `PhysicsBody` / `PhysicsShape`).
-
-```js
-import { HavokPlugin, PhysicsAggregate, PhysicsShapeType } from "@babylonjs/core";
-import HavokPhysics from "@babylonjs/havok";
-
-const havok = await HavokPhysics();                 // MUST await — loads the .wasm
-scene.enablePhysics(new Vector3(0, -9.81, 0), new HavokPlugin(true, havok));
-
-// dynamic body:
-new PhysicsAggregate(sphere, PhysicsShapeType.SPHERE, { mass: 1, restitution: 0.6, friction: 0.5 }, scene);
-// static body: mass 0
-new PhysicsAggregate(ground, PhysicsShapeType.BOX, { mass: 0 }, scene);
-```
-
-- **`await HavokPhysics()` is mandatory** and the #1 init error. First `HavokPlugin` arg (`_useDeltaForWorldStep`, usually `true`) makes physics use engine delta for smoother variable framerate.
-- **Bundler gotcha (Vite/webpack):** the `HavokPhysics.wasm` file must be served. Use `await HavokPhysics({ locateFile: f => \`/assets/${f}\` })` or configure the bundler to copy the wasm.
-- **PhysicsAggregate** is the easy path: it builds the matching `PhysicsShape` + `PhysicsBody` automatically. For fine control (compound shapes, sharing shapes across many bodies) build `PhysicsBody` + `PhysicsShape` yourself.
-- Read/write motion: `aggregate.body.setLinearVelocity(v)`, `applyImpulse`, `setMassProperties`, `body.setMotionType(PhysicsMotionType.ANIMATED/DYNAMIC/STATIC)`.
-- Collisions/triggers: `body.setCollisionCallbackEnabled(true)` + `body.getCollisionObservable().add(...)`; use `PhysicsShapeType.CONTAINER`/mesh shapes sparingly (mesh colliders are expensive — prefer primitives or convex hulls).
-- **glTF imports:** apply physics to the actual mesh, not the `__root__` transform node — often re-parent or use the child mesh; otherwise transforms get double-applied.
-- Debug: `new BABYLON.Debug.PhysicsViewer(scene).showBody(aggregate.body)`.
-- Older engines (Cannon, Ammo, Oimo) still exist via the V1 plugin, but **Havok V2 is the recommended choice** for new games. Ammo remains an option if you need its specific features/soft bodies.
-
----
-
-## 5. Asset loading — containers & glTF (do it right for level switching)
-
-- **glTF/GLB is the format.** `import "@babylonjs/loaders";` then `await ImportMeshAsync("model.glb", scene)` (or `SceneLoader.ImportMeshAsync` / `AppendSceneAsync`). Use Draco + KTX2/Basis compression.
-- **AssetContainer is the key tool for reusable/levels:** `LoadAssetContainerAsync(url, scene)` loads meshes/materials/textures **without adding them to the scene**. Then `container.addAllToScene()` / `container.removeAllFromScene()` and, crucially, **`container.dispose()`** to fully free GPU resources when unloading a level. This gives clean load/unload cycles and lets you **instantiate** copies:
-  - `container.instantiateModelsToScene(name => name, cloneMaterials)` clones a loaded model (with skeletons/animations) cheaply for spawning many enemies from one load.
-- **AssetsManager** gives progress-tracked batch loading with tasks (mesh, texture, binary) and `onProgress`/`onFinish` — good for a loading screen.
-- **Babylon does not GC GPU resources** any more than Three.js does — dispose meshes/materials/textures or (better) dispose the AssetContainer when leaving a level.
-
----
-
-## 6. Materials & Node Material Editor
-
-- **PBRMaterial** for realistic; **StandardMaterial** for simpler/cheaper. Reuse material instances across meshes (shared material = fewer state changes).
-- **Node Material** — visual shader graph (Node Material Editor at nme.babylonjs.com). Export as JSON and load with `NodeMaterial.ParseFromSnippetAsync("snippetId", scene)` or from file. Great for custom effects (dissolve, water, force-fields) without writing GLSL/WGSL by hand, and it compiles to both WebGL and WebGPU.
-- **Material plugins** and `material.freeze()` (see freezing below) reduce per-frame shader/uniform recompute.
-
----
-
-## 7. GUI (built-in — no DOM juggling)
-
-`import { AdvancedDynamicTexture, Button, ... } from "@babylonjs/gui";`
-
-- **Fullscreen UI:** `AdvancedDynamicTexture.CreateFullscreenUI("ui")` — a 2D overlay in screen space for HUD/menus (buttons, sliders, text, stack panels, grids). Resolution-independent, handles pointer input, works on mobile.
-- **In-world UI:** apply an ADT to a mesh's material for diegetic screens/labels; use `linkWithMesh` to attach floating labels/health bars that track 3D objects.
-- Prefer Babylon GUI over hand-rolled DOM overlays for game HUDs — it integrates with the scene, scales with the canvas, and doesn't fight CSS.
-
----
-
-## 8. Performance — FREEZING is the Babylon superpower
-
-For anything static, tell Babylon to stop recomputing it. This is the highest-leverage Babylon optimization and under-used in generated code.
-
-- **`mesh.freezeWorldMatrix()`** — mesh never moves ⇒ skip world-matrix recompute each frame. Call `unfreezeWorldMatrix()` if it needs to move again. Also set `mesh.doNotSyncBoundingInfo = true` for static meshes.
-- **`material.freeze()`** — material params fixed ⇒ skip uniform/shader re-evaluation. `unfreeze()` to change it.
-- **`scene.freezeActiveMeshes()`** — locks the active-mesh (culling) list; use when the set of visible meshes doesn't change (e.g., fixed camera or after setup). `unfreezeActiveMeshes()` when it changes. Huge CPU savings on large static scenes.
-- **`scene.blockMaterialDirtyMechanism = true`** while bulk-creating materials to avoid repeated recompiles.
-
-Other big levers (deeper than the three.js file's bullets):
-- **`scene.performancePriority = ScenePerformancePriority.Intermediate` (or `Aggressive`)** — auto-applies a bundle of optimizations (freezes active meshes, skips some checks). `Aggressive` disables per-mesh picking/some features — verify nothing you need breaks.
-- **Thin instances** (`mesh.thinInstanceAdd(matrix)` / `thinInstanceSetBuffer`) for thousands of identical static objects → one draw call, cheaper than regular instances. Regular **instances** (`mesh.createInstance()`) when you need per-instance picking/parenting.
-- **`scene.autoClear = false`** (and `autoClearDepthAndStencil`) when the scene fully covers the viewport — skips the clear.
-- **`scene.skipPointerMovePicking = true`** if you don't need hover/move picking (picking on every pointer move is a silent CPU cost). Set `mesh.isPickable = false` on non-interactive meshes.
-- **`scene.skipFrustumClipping`**, `mesh.alwaysSelectAsActiveMesh` — micro-tune culling for known-visible meshes.
-- **Merge meshes** (`Mesh.MergeMeshes([...], true, true, undefined, false, true)`) for static geometry sharing a material.
-- **LOD:** `mesh.addLODLevel(distance, lowMesh)` and `addLODLevel(farDist, null)` to cull entirely far away.
-- Keep **`camera.maxZ` low**; limit lights (each real-time light multiplies shader cost); use **shadow generators sparingly** with small map sizes and `RefreshRate` for static lights.
-- Avoid per-frame allocations: use **`TmpVectors.Vector3[0]`** scratch vectors and the `...ToRef()` method variants (`addToRef`, `scaleToRef`) instead of returning new objects.
-
----
-
-## 9. SceneOptimizer — adaptive quality to hit a target FPS
-
-Instead of guessing settings per device, let Babylon degrade quality until it reaches a target framerate.
-
-```js
-import { SceneOptimizer, SceneOptimizerOptions } from "@babylonjs/core";
-// preset tiers try progressively harder optimizations to reach the target FPS:
-SceneOptimizer.OptimizeAsync(scene,
-  SceneOptimizerOptions.HighDegradationAllowed(60),   // target 60 fps
-  () => console.log("reached target"),
-  () => console.log("could not reach target"));
-```
-
-- Presets: `LowDegradationAllowed`, `ModerateDegradationAllowed`, `HighDegradationAllowed(targetFps)`. They apply, in escalating order, optimizations like: reduce hardware scaling, merge meshes, disable shadows, reduce texture size, disable post-processes, cut particle counts.
-- You can build a custom `SceneOptimizerOptions` with specific `SceneOptimization` steps and priorities. Great for shipping one build that adapts from low-end mobile to desktop automatically.
-
----
-
-## 10. Inspector & profiling
-
-- **`import "@babylonjs/inspector"; scene.debugLayer.show()`** — the in-browser inspector: scene tree, per-mesh stats, materials, textures, and a **Statistics/Performance** tab (draw calls, active meshes, frame breakdown, GPU/CPU time). This is the fastest way to find what's slow.
-- Watch **draw calls** and **active meshes** counts; use the profiler to see whether you're CPU-bound (draw calls, matrix updates → freeze/instance) or GPU-bound (overdraw, shader cost, texture size → LOD/compression/fewer lights).
-
----
-
-## 11. Common Babylon pitfalls (checklist)
-
-- Forgetting `await WebGPUEngine.initAsync()` / `await HavokPhysics()` → cryptic init failures.
-- Havok `.wasm` not served by the bundler → physics silently absent; use `locateFile` / copy the wasm.
-- Not disposing meshes/materials/textures or the AssetContainer on level switch → GPU memory leak.
-- Applying physics to a glTF `__root__` node → double transforms / wrong positions.
-- Static scene running full cost because nothing is frozen → freeze world matrices, materials, active meshes.
-- Picking on every pointer move (`skipPointerMovePicking` not set; meshes left `isPickable`) → CPU drain.
-- Too many real-time lights / large shadow maps → shader + fill cost explosion.
-- Per-frame `new Vector3()`/`Matrix` allocations → GC churn; use `TmpVectors` + `...ToRef()`.
-- Huge `camera.maxZ` → z-fighting and wasted culling range.
-- Mesh colliders for everything instead of primitive/convex shapes → physics perf collapse.
-
----
-
-## Defaults to apply
-
-- **Reach for Babylon when the game wants an integrated engine** (built-in physics, GUI, inspector, camera behaviors) rather than the assemble-it-yourself Three.js route.
-- **Always await `initAsync()` (WebGPU) and `HavokPhysics()`**, and wire the **WebGPU-with-WebGL2-fallback** pattern by default.
-- **Emit freezing by default for static content**: `freezeWorldMatrix()` on non-moving meshes, `material.freeze()` on static materials, and `scene.freezeActiveMeshes()` / `performancePriority` once the scene is set up. This is the single biggest Babylon win most generated code misses.
-- **Ship `SceneOptimizer.OptimizeAsync(scene, HighDegradationAllowed(60))`** so one build adapts from low-end mobile to desktop instead of hardcoding quality.
-- **Use AssetContainers** for level load/unload (`instantiateModelsToScene` to spawn many from one load; `dispose()` to free on unload) to avoid the memory leaks that plague generated 3D games.
-- **Use Babylon GUI** (fullscreen ADT) for HUDs/menus instead of DOM overlays; use **camera Behaviors** (Framing/AutoRotation) for free menu/product polish.
-- Set **`skipPointerMovePicking`, low `maxZ`, `isPickable=false`** on non-interactive meshes as defaults.
-
----
-
-## Sources
-- Babylon.js docs — Optimizing your scene (freeze APIs, autoClear, performancePriority, active meshes): https://doc.babylonjs.com/features/featuresDeepDive/scene/optimize_your_scene
-- Babylon.js docs — Physics V2 / Havok (`enablePhysics`, `PhysicsAggregate`, `PhysicsBody/Shape`): https://doc.babylonjs.com/features/featuresDeepDive/physics/usingPhysicsEngine and https://github.com/BabylonJS/Documentation/blob/master/content/features/featuresDeepDive/physics/v2/usingPhysicsEngine.md
-- `@babylonjs/havok` npm (init pattern, `await HavokPhysics()`, `locateFile`): https://www.npmjs.com/package/@babylonjs/havok
-- Babylon.js docs — WebGPU (`WebGPUEngine`, `initAsync`, snapshot rendering): https://doc.babylonjs.com/setup/support/webGPU
-- Babylon.js docs — Cameras & Camera Behaviors: https://doc.babylonjs.com/features/featuresDeepDive/cameras/camera_introduction and https://doc.babylonjs.com/features/featuresDeepDive/behaviors/cameraBehaviors
-- Babylon.js docs — Asset Containers & glTF loading: https://doc.babylonjs.com/features/featuresDeepDive/importers/assetContainers and https://doc.babylonjs.com/features/featuresDeepDive/importers/loadingFileTypes
-- Babylon.js docs — SceneOptimizer: https://doc.babylonjs.com/features/featuresDeepDive/scene/sceneOptimizer
-- Babylon.js docs — GUI: https://doc.babylonjs.com/features/featuresDeepDive/gui/gui ; Node Material: https://doc.babylonjs.com/features/featuresDeepDive/materials/node_material/nodeMaterial
-- Babylon.js docs — Inspector: https://doc.babylonjs.com/toolsAndResources/inspector
-- Babylon.js forum — optimization best practices thread: https://forum.babylonjs.com/t/best-practices-for-optimizing-babylon-js-scenes-not-just-on-lower-end-devices/58688

package/skills/grok-building-games/references/collision-physics.md

@@ -1,122 +0,0 @@
-# Collision & Physics for Browser Games (2D AABB/SAT/broadphase, swept collision, 3D Rapier/cannon, fixed timestep)
-
-Consolidated from MDN game collision docs, Gaffer On Games, Rapier/cannon-es docs, and the SAT/swept-AABB canon (see Sources). Focus: what an AI builder needs so collisions are **correct and stable** — the classic bugs are tunneling through walls at speed, jitter, sinking into the ground, and O(n²) slowdowns.
-
----
-
-## 1. Do you even need a physics engine?
-
-- **Simple arcade games** (platformers, top-down, breakout, shooters) → hand-rolled **AABB** collision + resolution is often better: fully deterministic, no dependency, and you control feel. Most 2D games don't need Box2D/Matter.
-- **Rigid-body simulation** (stacking, ragdolls, joints, realistic bouncing, vehicles) → use an engine: **2D → Matter.js / Planck.js (Box2D) / Rapier2D**; **3D → Rapier (rapier.js, WASM, fast, favored) / cannon-es / Ammo.js**.
-- **Rule:** don't pull in a full rigid-body engine for a game that just needs "does the player box overlap the wall box." Physics engines add non-determinism and tuning overhead. Match the tool to the game.
-
----
-
-## 2. 2D collision detection primitives
-
-- **AABB (axis-aligned bounding box)** — the workhorse. Two boxes overlap iff they overlap on **both** axes:
-  ```js
-  const hit = a.x < b.x+b.w && a.x+a.w > b.x && a.y < b.y+b.h && a.y+a.h > b.y;
-  ```
-  Cheap, ideal for tile maps, most 2D gameplay. Only valid for **non-rotated** boxes.
-- **Circle/distance** — for round objects: compare squared distance to summed radii (`dx*dx+dy*dy < (r1+r2)²` — avoid `sqrt`).
-- **SAT (Separating Axis Theorem)** — for **rotated boxes / convex polygons**: two convex shapes don't intersect iff there exists an axis (a face normal of either shape) on which their projections don't overlap. Test all face normals; if any gap exists → no collision. The **minimum overlap axis gives the collision normal + penetration depth** (the MTV, minimum translation vector) for resolution.
-  - SAT only works on **convex** shapes — decompose concave shapes into convex pieces.
-  - For circles vs polygon, also test the axis from circle center to nearest vertex.
-
----
-
-## 3. Broadphase: don't test every pair (O(n²) killer)
-
-Checking all pairs is O(n²) — fine for dozens, catastrophic for hundreds/thousands. Split into **broadphase** (cheap culling of pairs that can't touch) → **narrowphase** (exact AABB/SAT on survivors).
-
-- **Uniform spatial hash grid** — bucket objects into cells by position; only test objects sharing a cell. Best default for many similar-sized, evenly-distributed objects (bullets, particles, .io games). Cell size ≈ average object size (2–3×).
-- **Quadtree** — recursively subdivide space; good for **non-uniform / clustered / varied-size** objects. Rebuild or update each frame.
-- **Sort and sweep (sweep-and-prune)** — sort AABB endpoints on an axis; good when objects move coherently.
-- **Rule:** the moment you have >~100 dynamic colliders, add a broadphase. Physics engines do this internally; hand-rolled collision needs it explicitly.
-
----
-
-## 4. Tunneling & swept collision (the top correctness bug)
-
-**Tunneling:** a fast object moves so far in one frame that it passes *through* a thin wall without ever overlapping it on any frame. Discrete AABB checks miss it entirely.
-
-Fixes (in order of preference):
-- **Swept collision (continuous / CCD):** instead of testing the box at its new position, test the **motion path**. **Swept AABB** computes the fraction of the frame `t (0..1)` at which the moving box first touches the target, then moves the object to exactly that contact point and resolves — no overlap ever occurs. Essential for bullets, fast platformers, thin walls.
-- **Substepping / smaller fixed timestep:** break a big move into several small steps and test each. Simpler than swept, good enough for moderate speeds.
-- **Raycast** fast/small projectiles (bullets) instead of moving a body — cast a ray along the travel and hit the first collider.
-- **Minimum wall thickness** ≥ max per-step travel is a cheap band-aid but fragile.
-- In engines, **enable CCD** on fast bodies (Rapier `setCcdEnabled(true)`, cannon-es CCD options).
-
----
-
-## 5. Collision *resolution* (not just detection)
-
-- **AABB resolution:** compute penetration on each axis; push the object out along the **axis of least penetration** (this makes walls/floors behave). Zero the velocity component on the axis you resolved (hitting the floor kills downward velocity).
-- **Resolve axes separately** for platformers ("move X, resolve X, then move Y, resolve Y") — prevents catching on tile seams and gives clean wall-slide behavior.
-- **Ground detection:** you're grounded if resolving downward this frame; set a small `coyoteTime` (see input skill) for feel.
-- **Avoid sinking/jitter:** apply a tiny "skin"/epsilon and don't over-correct; with engines, tune restitution/friction and let the solver settle. Resting jitter usually means variable timestep or fighting corrections.
-- With **SAT**, resolve along the MTV (normal × penetration depth); reflect/scale velocity along the normal for bounces.
-
----
-
-## 6. Fixed timestep — the stability foundation (tie-in)
-
-**Physics MUST run on a fixed timestep with an accumulator** ("Fix Your Timestep!", Gaffer On Games). Variable `dt` makes collision/physics non-deterministic and unstable (tunneling worsens, springs explode, replays/netcode desync).
-```js
-const STEP = 1/60; let acc = 0;
-function frame(dt){ acc += Math.min(dt, 0.25);        // clamp to avoid spiral-of-death after tab-out
-  while (acc >= STEP){ physicsStep(STEP); acc -= STEP; }
-  const alpha = acc / STEP; render(alpha);            // interpolate between last two states
-}
-```
-- **Clamp accumulated dt** (e.g. ≤0.25s) so a backgrounded tab doesn't trigger a "spiral of death" of catch-up steps.
-- **Interpolate rendering** between the previous and current physics state using `alpha` for smooth visuals at any display rate.
-- All physics engines expect a fixed step — call `world.step()` at a fixed rate, not per rAF with variable dt. Rapier is deterministic given fixed steps + same inputs (good for netcode).
-
----
-
-## 7. 3D character controllers
-
-Falling capsules from raw rigid-body dynamics feel bad for players — use a **kinematic character controller**:
-- **Rapier `KinematicCharacterController`** (favored): create via `world.createCharacterController(offset)`, use a kinematic body + capsule/collider, then each fixed step call `computeColliderMovement(collider, desiredTranslation)` and read `computedMovement()` to get the collision-corrected move. Built-in **autostep** (stairs), **snap-to-ground** (don't float off slopes/ramps), **max slope climb angle**, and slide-along-walls. Set gravity/jump yourself (kinematic = you control motion).
-- **cannon-es**: `PointerLockControlsCannon` example / a sphere or capsule body; more manual.
-- Rules: use a **capsule** (not a box) so the player slides over small steps and around corners; apply movement each **fixed step**; do ground checks via the controller's grounded flag or a short downward ray; keep the visual mesh synced to the body each frame (with interpolation).
-
----
-
-## 8. Bug-prevention checklist
-- **Variable timestep for physics** → non-deterministic, jitter, worse tunneling, netcode desync; fixed step + accumulator.
-- **No dt clamp** → "spiral of death" after tab-out; clamp accumulated dt.
-- **Fast objects passing through walls** → tunneling; use swept AABB / CCD / raycast / substeps.
-- **SAT on concave shapes** → wrong results; decompose into convex pieces.
-- **AABB test on rotated boxes** → false/missed hits; use SAT for rotation.
-- **O(n²) pair testing** → frame drops at scale; add spatial hash/quadtree broadphase.
-- **Resolving both axes at once** → catching on tile seams / clipping corners; resolve X then Y.
-- **Not zeroing velocity on the resolved axis** → gravity accumulates, object shudders into ground.
-- **Player floats off ramps / trips on stairs** → missing snap-to-ground / autostep; use a character controller (Rapier) with those enabled.
-- **Box character controller** → snags on edges; use a capsule.
-- **`sqrt` in hot distance checks** → wasted perf; compare squared distances.
-- **Reading physics state without render interpolation** → visible stutter at high refresh rates; interpolate with `alpha`.
-
----
-
-## Defaults to apply
-- **Right-size the solution:** hand-rolled **AABB + separate-axis resolution + swept collision** for arcade/2D/platformers; **Rapier** (2D or 3D) when we need real rigid bodies, joints, or a character controller. Don't default to a heavy engine.
-- **Always run physics on a fixed timestep with a clamped accumulator + render interpolation** — this one pattern prevents tunneling instability and jitter, and it ties directly into the fixed-timestep game loop (see `threejs-foundational.md`).
-- **Ship anti-tunneling by default** for fast objects (swept AABB or CCD/raycast for projectiles) and a **broadphase (spatial hash or quadtree)** once there are many colliders.
-- **For 3D player movement, generate a Rapier `KinematicCharacterController` with a capsule, autostep, snap-to-ground, and slope limits** — not a raw dynamic body — so movement feels right out of the box.
-
----
-
-## Sources
-- MDN — 2D collision detection (AABB, circle, SAT): https://developer.mozilla.org/en-US/docs/Games/Techniques/2D_collision_detection
-- Gaffer On Games — "Fix Your Timestep!": https://gafferongames.com/post/fix_your_timestep/ ; "Collision Response and Coulomb Friction": https://gafferongames.com/post/collision_response_and_coulomb_friction/
-- Swept AABB collision — jitter physics / "Swept AABB Collision Detection and Response" (gamedev): https://www.gamedev.net/tutorials/programming/general-and-gameplay-programming/swept-aabb-collision-detection-and-response-r3084/
-- SAT reference — Metanet/N tutorial & dyn4j "SAT (Separating Axis Theorem)": https://dyn4j.org/2010/01/sat/ ; https://www.metanetsoftware.com/technique/tutorialA.html
-- Spatial hashing / broadphase — "Spatial Hashing" (gamedev) & quadtree collision (GameDev Academy): https://gameprogrammingpatterns.com/spatial-partition.html
-- Rapier — docs (rigid bodies, CCD, character controller): https://rapier.rs/docs/ ; character controller: https://rapier.rs/docs/user_guides/javascript/character_controller ; JS bindings: https://github.com/dimforge/rapier.js
-- cannon-es — repo/examples (incl. PointerLockControlsCannon): https://github.com/pmndrs/cannon-es ; https://pmndrs.github.io/cannon-es/
-- Matter.js: https://brm.io/matter-js/ ; Planck.js (Box2D): https://github.com/piqnt/planck.js
-- Box2D docs (continuous collision / solver background): https://box2d.org/documentation/
-- Game Programming Patterns — Spatial Partition & Game Loop: https://gameprogrammingpatterns.com/spatial-partition.html , https://gameprogrammingpatterns.com/game-loop.html

package/skills/grok-building-games/references/ecs-architecture.md

@@ -1,111 +0,0 @@
-# ECS & Game State Architecture for JS Games (bitECS, miniplex, ECS vs OOP, state structure)
-
-Consolidated from webgamedev.com, the bitECS and miniplex docs, and data-oriented-design canon (see Sources). Focus: how an AI builder should **structure game state so it stays fast and untangled** as a game grows — and when *not* to reach for ECS.
-
----
-
-## 1. What ECS is (and why it exists)
-
-**Entity-Component-System** separates data from behavior:
-- **Entity** — an ID (or a plain object) with no logic; just a thing that exists.
-- **Component** — pure **data**, no methods (Position, Velocity, Health, Sprite, Collider).
-- **System** — pure **behavior** that iterates all entities having a given set of components and updates them (MovementSystem reads Position+Velocity).
-
-Benefits: **composition over inheritance** (add/remove capabilities by adding/removing components — no deep class hierarchies), cache-friendly iteration, easy serialization (state = plain data), and clean separation that scales to thousands of entities.
-
-The classic problem ECS solves: the "deadly diamond" of OOP inheritance (`FlyingEnemy` vs `SwimmingEnemy` vs `FlyingSwimmingShootingEnemy`...). With ECS you just attach `Flying`, `Swimming`, `Shooting` components in any combination.
-
----
-
-## 2. When ECS vs OOP (don't cargo-cult ECS)
-
-**Use plain OOP / a simple object list when:**
-- Small games, jams, prototypes, or a handful of distinct entity types.
-- Entity count is low (dozens–low hundreds) and perf isn't a concern.
-- The team/model iterates faster with intuitive `player.jump()` classes.
-- The engine already gives you a good model (Phaser GameObjects/prefabs, Three.js `Object3D` scene graph) — you can go a long way with a component-ish mixin approach without a full ECS.
-
-**Reach for ECS when:**
-- **Many similar entities** (bullet-hell, RTS, particles, simulations, .io games) — thousands of entities needing fast batch updates.
-- Highly **combinatorial** entity capabilities (lots of mix-and-match behaviors/status effects).
-- You need **determinism/serialization** (netcode, replays, save states) — pure-data components serialize trivially.
-
-**Rule:** ECS is an optimization/organization tool, not a moral requirement. A giant `update()` switch or a tidy class hierarchy is fine for small games. Adopt ECS when entity count/combinatorial complexity actually bites — premature ECS adds boilerplate for no gain.
-
----
-
-## 3. Library choice: bitECS vs miniplex
-
-**miniplex** — DX-first, entities are **plain JS objects**, components are just properties. Best default for most indie/web games and rapid prototyping; excellent TypeScript + React bindings.
-```js
-import { World } from 'miniplex';
-const world = new World();
-const player = world.add({ position:{x:0,y:0}, velocity:{x:100,y:0}, health:{cur:100,max:100} });
-const moving = world.with('position','velocity');   // live archetype query
-function movementSystem(dt){ for (const e of moving){ e.position.x += e.velocity.x*dt; e.position.y += e.velocity.y*dt; } }
-world.remove(player);
-```
-- Use `world.addComponent(e,'velocity',{...})` / `removeComponent` so queries re-index (mutating a bare property can skip re-indexing).
-- `for...of` over a query is fast and **safe for removal during iteration**. No built-in scheduler — you call systems from your loop.
-- Object property access is slightly slower at extreme entity counts than bitECS's typed arrays.
-
-**bitECS** — performance-first, data-oriented: entities are **integer IDs**, components are **Structure-of-Arrays (typed arrays)**, archetype/bitmask queries. Best for tens of thousands of entities, WebGPU, perf-critical sims. ~5kb, zero deps (used in Hubs/Third Room; eyed by Phaser 4).
-```js
-import { createWorld, addEntity, addComponent, query } from 'bitecs';
-const world = createWorld({ Position:{x:new Float32Array(1e4),y:new Float32Array(1e4)}, Velocity:{x:[],y:[]} });
-const { Position, Velocity } = world.components;
-const eid = addEntity(world); addComponent(world,eid,Position); addComponent(world,eid,Velocity);
-const moving = query(world,[Position,Velocity]);
-for (const e of moving){ Position.x[e] += Velocity.x[e]*dt; Position.y[e] += Velocity.y[e]*dt; }
-```
-- **Note the API moved on:** older tutorials use `defineComponent`/`defineQuery`/`Types`; current bitECS (0.4+) uses `createWorld({...schemas})` + `query(world,[...])`, plus relationships/observers/prefabs. Verify the version you install.
-- SoA layout = cache-friendly; entities-as-IDs = trivial to serialize/network.
-
-**Others:** Becsy (multithreaded), Koota, or the engine's own model. Some projects mix (bitECS core sim + object layer for UI).
-
----
-
-## 4. Structuring game state (even without a formal ECS)
-
-- **Single source of truth:** keep a central, serializable game-state object (or ECS world). Avoid scattering authoritative data across DOM, closures, and random globals — it makes save/load, undo, and netcode nearly impossible.
-- **Separate data from rendering:** gameplay state (positions, health) should be independent of the visual objects (meshes/sprites). Systems update data; a render/sync step pushes data → Three.js/Phaser objects each frame. This keeps the sim testable/deterministic and lets you do fixed-timestep + interpolation.
-- **Systems run in a defined order each tick:** input → AI → movement → collision → damage → cleanup → render-sync. Order matters and should be explicit, not incidental.
-- **Object pooling instead of create/destroy churn:** for bullets/enemies/particles, recycle entities (mark inactive) rather than allocating/GCing every frame (pairs with ECS well; see `threejs-foundational.md`).
-- **Deferred structural changes:** don't add/remove entities in the middle of iterating a query in ways the lib doesn't support — queue spawns/despawns and apply between systems (miniplex `for...of` is removal-safe; still queue mass changes for clarity).
-- **Fixed timestep for the sim** (see game-loop/collision skills) so ECS systems are deterministic — required for netcode/replays.
-- **Events/messaging** between systems via a small event queue rather than direct cross-system calls, to keep systems decoupled.
-
----
-
-## 5. Bug-prevention checklist
-- **Putting logic in components / data in systems** → defeats ECS; keep components pure data, systems pure behavior.
-- **Adopting ECS for a tiny game** → boilerplate with no benefit; use a simple object list/classes until entity count/complexity warrants it.
-- **Deep inheritance for entity variety** → combinatorial class explosion; compose with components instead.
-- **Mutating a miniplex property directly and expecting query updates** → use `addComponent`/`removeComponent` so archetypes re-index.
-- **Using stale bitECS `defineComponent` tutorials against a new version** → API mismatch; check installed version's docs.
-- **Mixing render objects into authoritative state** → non-serializable, non-deterministic; separate sim data from view.
-- **Undefined system order** → order-dependent bugs (moving before collision, etc.); define an explicit pipeline.
-- **create/destroy per frame** → GC stalls; pool entities.
-- **Structural changes mid-iteration** → skipped/duplicated updates; defer to a queue.
-- **Scattered global state** → save/load and netcode become impossible; centralize the world.
-
----
-
-## Defaults to apply
-- **Default to miniplex** for generated games that need ECS (plain objects, great TS/React DX); **switch to bitECS** only when the game genuinely has thousands of entities or needs SoA perf. For small/simple games, a plain object list or engine prefabs is fine — don't force ECS.
-- **Always structure state as a single serializable world with sim/render separation** and an **explicit system pipeline** (input→AI→movement→collision→damage→cleanup→render-sync) run on a fixed timestep. This unlocks save/load, replays, and netcode for free.
-- **Bake in pooling + deferred spawn/despawn** for entity-heavy genres.
-- When generating ECS code, **verify the library version's current API** (bitECS especially changed) rather than emitting old `defineComponent` patterns from memory.
-
----
-
-## Sources
-- Web Game Dev — Code architecture / ECS overview: https://www.webgamedev.com/code-architecture/ecs
-- bitECS — repo & docs: https://github.com/NateTheGreatt/bitECS , https://bitecs.dev/docs/introduction
-- miniplex — repo & docs: https://github.com/hmans/miniplex , miniplex-react: https://github.com/hmans/miniplex/tree/main/packages/miniplex-react
-- Becsy (multithreaded ECS): https://lastolivegames.github.io/becsy/
-- Sander Mertens — "Entity Component System FAQ": https://github.com/SanderMertens/ecs-faq
-- Adam Martin — "Entity Systems are the future of MMOG development": http://t-machine.org/index.php/2007/09/03/entity-systems-are-the-future-of-mmog-development-part-1/
-- Mick West — "Evolve Your Hierarchy" (components over inheritance): https://cowboyprogramming.com/2007/01/05/evolve-your-hierarchy/
-- Richard Fabian — Data-Oriented Design (book): https://www.dataorienteddesign.com/dodbook/
-- Game Programming Patterns — Component pattern: https://gameprogrammingpatterns.com/component.html

package/skills/grok-building-games/references/game-feel-juice.md

@@ -1,110 +0,0 @@
-# Game Feel & Juice (screenshake, hitstop, tweening/easing, particles, squash & stretch, camera, SFX layering)
-
-The canon: Steve Swink's *Game Feel*, Vlambeer/"Juice it or lose it" (Martin Jonasson & Petri Purho), and Jan Willem Nijman's "The art of screenshake" (see Sources). "Juice" = generous, layered, non-gameplay-affecting feedback that makes every input feel physical and satisfying. Focus: what an AI builder should reflexively add so games feel **alive instead of static**, without hurting readability or perf.
-
----
-
-## 1. The core principle
-
-**Every meaningful action should produce disproportionate, multi-sensory feedback.** A single "hit" should simultaneously trigger several of: sound, particles, screenshake, hitstop, flash, knockback, squash/stretch, and a number/pop. The gameplay math can stay simple — the *feel* comes from the feedback layer stacked on top. The classic demo takes the same identical Breakout and makes it feel amazing purely by adding these layers.
-
-**Rule:** Separate "simulation" from "presentation." Feedback (shake, tween, particles, flash) must **never change gameplay outcomes** — it's cosmetic. This keeps physics deterministic (important for netcode/replays) while letting you pile on juice freely.
-
----
-
-## 2. Screenshake (the highest impact-per-effort effect)
-
-- Offset the **camera** (or a camera container), not the world objects. Apply a random offset each frame from a **trauma value** that **decays over time**.
-- **Use trauma², not linear** (Squirrel Eiserloh's "Juicing Your Cameras"): store `trauma` in [0,1], set `shake = trauma * trauma` (or `trauma³`). Add trauma on events (small hit +0.3, explosion +0.8), decay `trauma -= decay * dt` each frame. Squaring makes small hits subtle and big hits explosive.
-- Offset with **noise, not pure random**, for smoother shake: `offsetX = maxOffset * shake * (noise(t) )`; also shake **rotation** slightly (`maxAngle * shake * noise`) — rotational shake reads as more violent.
-- **Directional shake** for directional hits (kick the camera opposite the impact) reads better than omnidirectional for melee/recoil.
-- **Cap it & scale it down for accessibility.** Excessive shake causes motion sickness — expose a "screen shake" slider/toggle. Never shake so hard UI/targets become unreadable.
-- Scale offsets by `dt`-independent amount but decay by `dt` so it's frame-rate independent.
-
-Nijman's rules also include: **more bullets, bigger bullets, muzzle flash, impact effects, permanent decals, camera lerp/lookahead, camera kick, sleep/hitstop, gun delay, knockback, screen shake, and even a little randomness in everything.**
-
----
-
-## 3. Hitstop / hitstun / "sleep" (freeze frames on impact)
-
-- On a big hit, **freeze the game (or just the two involved entities) for a few frames** (~30–120ms), then resume. This sells impact enormously — the brain reads the pause as force.
-- Implement as a global **time scale** or a short "freeze frames" counter: while frozen, skip the gameplay update (or set `timeScale=0`) but **keep rendering** and keep the flash/particles visible. Common: freeze ~2–6 frames for normal hits, longer for finishers.
-- Keep hitstop **short**; too long feels laggy/unresponsive. Often paired with a brief hit **flash** (tint the sprite white for 1–2 frames) and knockback that starts *after* the freeze.
-- Distinguish **hitstop** (brief freeze for feel) from **hitstun** (gameplay state where a hit character can't act) — the latter is real gameplay, the former is pure juice.
-
----
-
-## 4. Tweening & easing (motion that isn't linear)
-
-- **Almost nothing should move linearly.** Real, satisfying motion accelerates/decelerates. Use **easing functions** for UI transitions, pickups flying to the HUD, menus, popups, camera moves, damage numbers.
-- Common curves (see easings.net for exact formulas/graphs):
-  - **easeOutQuad/Cubic** — arrive gently (great for things settling into place).
-  - **easeInQuad/Cubic** — start slow (things launching).
-  - **easeOutBack** — slight overshoot then settle (pop-in for UI/pickups — very juicy).
-  - **easeOutElastic / easeOutBounce** — springy/bouncy (buttons, coin pickups). Use sparingly.
-  - **easeInOutQuad** — smooth both ends (camera, generic).
-- **Use a tween library** rather than hand-rolling: **GSAP** (best-in-class, huge easing set, timelines), **@tweenjs/tween.js** (lightweight, common in Three.js), or the engine's built-in (Phaser `this.tweens.add`). Tweens compose (chains, delays, yoyo, repeat) and auto-handle dt.
-- **Kill/clean up tweens** when the target is destroyed or the scene shuts down (leaked tweens mutating dead objects = crashes/bugs). Phaser: kill on `SHUTDOWN`; GSAP: `.kill()`.
-- A **spring/damped-lerp** (`x += (target - x) * (1 - exp(-k*dt))`) is a great procedural alternative for continuous following (cameras, cursors, UI) — always frame-rate correct if you use the `exp` form rather than `x += (target-x)*0.1` (the naive lerp is frame-rate dependent — see §6).
-
----
-
-## 5. Particles & squash-and-stretch
-
-- **Particles everywhere:** dust on landing/footsteps, sparks on hit, debris on death, trails on projectiles, confetti on win, ambient motes. They cost little and add enormous life. Use the engine's particle system (Phaser `add.particles`, Three.js points/instanced sprites) and **pool** them (no per-emit allocation — see `threejs-foundational.md`).
-- **Squash & stretch** (Disney's foundational animation principle): deform on acceleration to convey weight/speed while preserving apparent volume.
-  - Jump: stretch vertically (taller/thinner) on takeoff, squash (shorter/wider) on landing, then spring back via `easeOutBack`/elastic.
-  - Preserve volume: if you scale `y` by `s`, scale `x` by ~`1/s`, so it doesn't look like it's growing.
-  - Drive it from velocity (stretch along the movement direction) or trigger on discrete events (land, hit, shoot recoil).
-- **Anticipation + follow-through:** wind up before a big action (tiny reverse/squash) and overshoot after — even a couple frames sells it.
-- **Pop numbers & flashes:** floating damage numbers that rise + fade + scale-pop, combo counters, "+10" pickups. Cheap, huge readability + satisfaction win.
-
----
-
-## 6. Camera feel (lerp, lookahead, deadzone, punch)
-
-- **Never hard-snap the camera to the player.** Smoothly follow (`lerp`/spring) toward the target so motion is fluid.
-  - **Frame-rate-correct smoothing:** `pos += (target - pos) * (1 - Math.exp(-k * dt))`. The naive `pos += (target - pos) * 0.1` is **frame-rate dependent** (faster on 144Hz than 60Hz) — a common bug; use the exp form or a fixed-timestep camera update.
-- **Lookahead:** offset the camera slightly in the direction of movement / where the player is aiming, so the player sees more of what's ahead. Ease the offset in/out.
-- **Deadzone / soft zone:** don't move the camera until the player leaves a central box — prevents nauseating micro-jitter from small movements.
-- **Camera punch/kick** on impacts (a quick zoom-in or positional kick that eases back) complements screenshake.
-- Clamp the camera to level bounds; round the final camera position to whole pixels for pixel-art games to avoid shimmer.
-
----
-
-## 7. SFX layering & audio feel
-
-- **Layer sounds** for richness: a single "shoot" = a low thump + a mid body + a high click/transient. Impacts = hit + debris + a tail.
-- **Pitch-randomize** repeated sounds (±5–15%) so rapid fire / footsteps don't sound robotic (`playbackRate` / Howler `rate`). Slightly randomize volume too.
-- Sound is feedback: **every** action should have audio, and it should be tight (low latency) and satisfy on first frame of the action (see the audio skill for Web Audio/Howler, mobile unlock, buses).
-- Duck music briefly under big events; add a subtle low-frequency "boom" on explosions.
-
----
-
-## 8. Don't over-juice (readability & perf guardrails)
-- **Juice must not obscure gameplay.** If shake/flash/particles hide the player, enemies, or projectiles, dial back. Readability > spectacle.
-- **Accessibility:** provide toggles/sliders for screen shake, flashing, and reduced motion (respect `prefers-reduced-motion`). Heavy flashing risks photosensitivity — avoid rapid full-screen strobing.
-- **Perf:** pool particles/tweens, cap concurrent particles, don't allocate in the hit path. Juice is cheap but "thousands of unpooled particles per explosion" is not.
-- Keep hitstop short and prediction-safe in multiplayer (apply juice on the client only; never let it alter the authoritative sim).
-
----
-
-## Defaults to apply
-- **Auto-juice defaults:** whenever the builder generates a hit/pickup/death/land/win event, reflexively attach the stack: **sound + particles + short hitstop + white flash + screenshake(trauma²) + easeOutBack pop / squash-stretch + floating number.** Same simple gameplay, dramatically better feel — this is the single biggest perceived-quality lever.
-- **Ship a tiny reusable "juice" toolkit** in generated games: a `trauma`-based shake (squared, noise-driven, decaying), a `hitstop(frames)` helper (timeScale/freeze-count), a `flash(sprite)` helper, easing/tween helpers (or GSAP/tween.js), and frame-rate-correct camera follow with lerp + lookahead + deadzone.
-- **Always use the `exp`-based lerp** for cameras/followers so smoothing is frame-rate independent — bake this in to avoid the classic 144Hz-vs-60Hz bug.
-- **Separate presentation from simulation** so juice never affects gameplay/netcode. Provide screenshake/flash/reduced-motion toggles by default for accessibility.
-
----
-
-## Sources
-- Martin Jonasson & Petri Purho — "Juice it or lose it" (GDC talk): https://www.youtube.com/watch?v=Fy0aCDmgnxg ; companion "Game feel" write-up on grapefrukt.
-- Jan Willem Nijman (Vlambeer) — "The art of screenshake": https://www.youtube.com/watch?v=AJdEqssNZ-U
-- Steve Swink — *Game Feel: A Game Designer's Guide to Virtual Sensation* (book), gamefeelbook.com.
-- Squirrel Eiserloh — "Juicing Your Cameras With Math" (GDC, trauma² screenshake): https://www.youtube.com/watch?v=tu-Qe66AvtY
-- easings.net — easing function reference with formulas & graphs: https://easings.net/
-- Robert Penner's easing equations (origin of the standard easings): http://robertpenner.com/easing/
-- GSAP docs (tweening/easing/timelines): https://gsap.com/docs/v3/ ; tween.js: https://github.com/tweenjs/tween.js
-- Disney's 12 principles of animation (squash & stretch, anticipation, follow-through): https://en.wikipedia.org/wiki/Twelve_basic_principles_of_animation
-- MDN — `prefers-reduced-motion`: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion
-- "The Juice Factor" / GDC Vault talks on feedback & game feel.