@inneranimalmedia/agentsam-sdk 2.6.5 → 2.6.7

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

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

package/skills/grok-building-games/references/threejs-foundational.md

@@ -0,0 +1,148 @@
+# Browser Game Best Practices — Three.js / Babylon.js / Phaser (controls, camera, orientation, loop, assets, perf)
+
+Consolidated from official docs, well-regarded tutorials, and engine forums (see Sources at bottom). Focus: what an AI builder needs to get **browser games that feel right and don't have the usual bugs.**
+
+---
+
+## 1. Game loop & timing (the #1 correctness issue)
+
+**Rules:**
+- Drive the loop with **`renderer.setAnimationLoop(fn)`** in Three.js (internally uses `requestAnimationFrame`, plays nicely with WebXR) or the engine's built-in loop (Phaser `update(time, delta)`, Babylon `scene.onBeforeRenderObservable` / `engine.runRenderLoop`). Avoid `setTimeout`/`setInterval` and `Date.now()`.
+- **Scale ALL movement/animation by delta time** (seconds since last frame) so speed is frame-rate independent (30fps laptop vs 144Hz monitor). e.g. `mesh.position.x += speed * delta`.
+- **Cap delta** to avoid huge jumps after a backgrounded tab: `delta = Math.min(delta, 0.1)`.
+- **Compute delta exactly once per frame** and reuse it everywhere.
+  - Three.js gotcha: `THREE.Clock.getDelta()` mutates state — calling it more than once per frame returns ~0 on later calls (very common bug). Newer `THREE.Timer` (Clock deprecated ~r183) has an explicit `.update()` so delta can be read multiple times safely.
+- **For physics/gameplay stability use a fixed timestep + accumulator** ("Fix Your Timestep"): run `fixedUpdate(FIXED_STEP)` (e.g. 1/60) in a `while (accumulator >= FIXED_STEP)` loop, render at display rate, optionally interpolate. Variable delta is fine for purely visual demos.
+- **Modularize**: give objects a `.update(delta)`/`.tick(delta)` method and iterate an "updatables" list; keep the top-level loop lean.
+- **On-demand rendering**: if nothing is animating, stop the loop / render only on change to save battery (Three.js `setAnimationLoop(null)`; R3F `frameloop="demand"`).
+
+**Reference pattern (Three.js, Timer + capped delta + fixed step):**
+```js
+const timer = new THREE.Timer();
+let accumulator = 0; const FIXED = 1/60;
+function animate() {
+  timer.update();
+  let delta = Math.min(timer.getDelta(), 0.25);
+  accumulator += delta;
+  while (accumulator >= FIXED) { fixedUpdate(FIXED); accumulator -= FIXED; } // physics/AI
+  updateVisuals(delta);
+  renderer.render(scene, camera);
+}
+renderer.setAnimationLoop(animate);
+```
+
+---
+
+## 2. First-person / WASD + mouse-look controls (Three.js)
+
+The canonical reference is the official `misc_controls_pointerlock` example (https://threejs.org/examples/misc_controls_pointerlock.html).
+
+**Key facts & rules:**
+- **`PointerLockControls` only handles the Pointer Lock API + mouse-look (yaw/pitch). It does NOT include WASD movement — you implement keyboard + translation yourself.**
+- Add **`controls.getObject()`** (the yaw container) to the scene, not the camera directly; the camera is a child for pitch.
+- Track keys with **boolean state flags** set in `keydown`/`keyup` (support both `KeyW`/`ArrowUp`, etc.). Do NOT move on the keydown event itself.
+- Move with **velocity + delta time** (acceleration + friction/damping), not a fixed distance per press — feels far better.
+- Use **`controls.moveForward()` / `controls.moveRight()`** — they respect current yaw (local XZ plane). Do NOT modify `camera.rotation`/`camera.position` directly for horizontal movement.
+- Pointer lock **requires a user gesture**: always show a "Click to play" blocker overlay; call `controls.lock()` on click; handle `'lock'`/`'unlock'` events and `pointerlockerror`; provide escape-to-unlock and a crosshair.
+- **Avoid the deprecated `FirstPersonControls`** (behaves like fly controls).
+- For real collisions/slopes/stairs, integrate a physics character controller: **Rapier.js `KinematicCharacterController`** (currently favored), or cannon-es (`PointerLockControlsCannon`), Ammo.js. Sync the body to `controls.getObject()`.
+- Encapsulate as a `FirstPersonController` class with `update(delta)`, `lock()`, `dispose()`, and tunable `speed`/`jumpHeight`. Add sprint (Shift), crouch, head-bob for feel.
+- R3F: use drei `<PointerLockControls />` + `useKeyboardControls` + `useFrame`.
+
+**Other camera rigs:**
+- **Orbit / product inspection:** Three.js `OrbitControls`; Babylon `ArcRotateCamera` (set `lower/upperRadiusLimit`, `lower/upperBetaLimit`, `inertia`, `panningSensibility`).
+- **Third-person follow:** lerp camera toward a target offset behind the player each frame; `camera.lookAt(player)`; Babylon has `FollowCamera`.
+- Keep the far plane / `camera.maxZ` (Babylon) as small as practical — improves culling, overdraw, and depth precision.
+
+---
+
+## 3. 3D orientation & coordinate conventions (a top source of "why is my model sideways/backwards" bugs)
+
+- **Three.js is right-handed, +Y up:** +X right, +Y up, +Z toward the viewer. Default camera sits at +Z looking toward −Z. (Differs from Unreal's Z-up, etc.) Changing global up (`Object3D.DefaultUp`) is discouraged — it affects helpers/grids.
+- **Forward-axis gotcha:**
+  - Most `Object3D` (Mesh/Group): **local forward is +Z** `(0,0,1)`. Model/rotate so the "front" aligns with +Z.
+  - **Camera** (and some lights): forward is **local −Z** `(0,0,-1)`. This is the classic "camera looks backwards" gotcha.
+- Many primitives (`ConeGeometry`, `CylinderGeometry`) point along **+Y** by default → rotate before use, e.g. `geo.rotateX(Math.PI/2)` to make +Y → +Z (align an arrow/cone's tip with forward).
+- **`object.lookAt(target)`** rotates in **world space** so the forward axis points at the target (uses `.up`, quaternions internally; does not move the object). For nested targets, first `target.getWorldPosition(v)`. To face a *direction* vector: `obj.lookAt(obj.position.clone().add(dir))`.
+- Imported glTF/GLB models may need an initial rotation to match +Z-forward. glTF/Blender export is right-handed Y-up, consistent with Three.js.
+- Debug with `AxesHelper` and `ArrowHelper` to visualize orientation quickly.
+
+---
+
+## 4. Performance (Three.js-centric, principles apply broadly)
+
+**The #1 killer is draw calls** (`renderer.info.render.calls`). Target **<100/frame** for smooth 60fps on most hardware; 500+ stutters; mobile is stricter.
+
+- **Share materials** aggressively (reuse one material instance across meshes).
+- **Instancing (`InstancedMesh`)** for many *identical* objects (trees, crowds, bullets) → one draw call; update via `setMatrixAt` + `instanceMatrix.needsUpdate`. Note: default frustum culling applies to the whole instanced mesh.
+- **`BatchedMesh`** (r156+) for *varied* geometries sharing one material, with per-object visibility + `perObjectFrustumCulled`.
+- **Merge geometries** (`BufferGeometryUtils.mergeGeometries`) for fully static scenery sharing a material (loses per-object culling — one bounding volume).
+- **Frustum culling** is automatic (`mesh.frustumCulled`); after modifying geometry call `computeBoundingBox()`/`computeBoundingSphere()`. Reduce `camera.far` where possible.
+- **Dispose GPU resources manually** — Three.js does NOT GC them. On removing objects/switching levels: `geometry.dispose()`, `material.dispose()`, and dispose all textures. Watch `renderer.info.memory`. Use **object pooling** for particles/enemies instead of create/destroy churn.
+- **Avoid allocations in the hot loop** (no `new Vector3()`/`new Matrix4()` per frame; reuse temporaries; Babylon has `TmpVectors` and `xxxToRef()`).
+- **LOD** (`THREE.LOD`) — swap lower-poly at distance. Compress geometry (Draco) and textures (**KTX2/Basis**); prefer texture atlases.
+- Limit lights; bake lighting/AO where possible; keep shadow maps small (and `RENDER_ONCE` refresh for static lights).
+- Add **Stats.js**/FPS counter during dev; profile with Spector.js / engine inspector; profile on target devices.
+
+**Babylon.js specifics:** prefer WebGPU w/ fallback + `powerPreference:"high-performance"`; `scene.performancePriority` (Intermediate/Aggressive); `scene.autoClear=false` when meshes cover viewport; `scene.skipPointerMovePicking=true` if no hover-picking; **thin instances** for static crowds; `mesh.freezeWorldMatrix()`, `material.freeze()`, `scene.freezeActiveMeshes()` for static content; `engine.setHardwareScalingLevel(2)` on low-end/mobile; `SceneOptimizer` to auto-degrade quality to hit a target FPS; keep `camera.maxZ` low. Camera "Behaviors" (Framing/Bouncing/AutoRotation) give polish for free.
+
+**Phaser specifics:** heavy **object pooling** (Groups with `maxSize`, recycle via `active/visible=false`), process only active objects, texture atlases (Texture Packer), destroy tweens/emitters on `SHUTDOWN`, smaller canvas + CSS upscaling, lazy-load per-level assets.
+
+---
+
+## 5. Engine / stack choice
+
+- **2D games → Phaser** (Phaser 3/4): scenes, Arcade/Matter physics, Scale Manager, huge ecosystem, great mobile support. Best default for 2D.
+- **3D games → Three.js** (most control, largest community) or **Babylon.js** (batteries-included: inspector, physics, WebGPU, camera behaviors, SceneOptimizer). **PlayCanvas** if you want a full editor/engine.
+- Physics: 2D → Arcade (simple) / Matter (rigid bodies); 3D → **Rapier.js** (fast, WASM, popular) / cannon-es / Ammo.js.
+- Tooling: **Vite + TypeScript**; PWA (manifest + service worker) for installable/offline mobile.
+
+**Phaser architecture (from best-practice write-ups):** one file per Scene extending `Phaser.Scene`; a scene stack of Boot → Preload (progress bar) → Menu → Game → parallel UI/HUD (`scene.launch`) → Pause/GameOver. Lifecycle: `init(data)` → `preload()` → `create(data)` → `update(time,delta)`; clean up on `SHUTDOWN`. Constants file for all string keys. Decouple scenes via an EventEmitter "EventsCenter" or `registry`, not direct references. Prefabs (custom GameObject subclasses) + FSM/ECS for complex logic instead of a giant `update()`.
+
+---
+
+## 6. Assets: generate vs. code vs. link
+
+- **Generate real images** for sprites/textures/backgrounds/UI where the builder can (matches Lovable/v0 philosophy: no placeholder images in the final product). For pixel art request specific specs ("clean 32×32 side-view run cycle, 8 frames, sprite sheet, transparent background").
+- **Don't hand-draw complex SVG/geometry** for illustrations or maps — use real assets or a library (echoes v0/Claude anti-slop rules).
+- **Optimize for the browser:** compressed textures (KTX2/Basis/WebP), power-of-two, atlases, keep total download small (aim <20–50MB). Draco/Meshopt for glTF.
+- **Placeholder > bad attempt** (Claude): if a good asset can't be produced, use a clean placeholder rather than an ugly hand-rolled one.
+- Set **`crossOrigin='anonymous'`** on images drawn to `<canvas>`/textures to avoid CORS taint (v0 rule).
+- 3D model pipeline: glTF/GLB (Y-up, right-handed) with Draco/Meshopt/KTX2; verify forward-axis orientation on import.
+
+---
+
+## 7. Mobile / responsive / touch
+
+- Distinguish the **canvas drawing buffer** (`canvas.width/height`) from **CSS display size**; account for `devicePixelRatio` to avoid blurry/tiny output. Rendering at a smaller internal resolution + CSS upscale is a valid perf win; `image-rendering: pixelated` for pixel art.
+- Choose a **base design resolution** + aspect ratio; **letterbox (FIT)** to avoid stretching. Phaser: `scale: { mode: Phaser.Scale.FIT, autoCenter: CENTER_BOTH, width, height }` and handle the `resize` event; listen for `orientationchange`.
+- Viewport meta: `width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no`; CSS `touch-action: none` and `preventDefault()` on touch to stop scroll/zoom.
+- **Touch controls:** virtual joystick (e.g. **nipplejs**, `mode:'static'` or `'dynamic'`), split screen (left = move, right = actions/aim), normalize input to −1..1 and apply with delta time, visual feedback on active. **Minimum touch/hit target 44px** (Claude/Apple HIG). Unify keyboard + touch + Gamepad API into one input state.
+- Test on real iOS Safari (audio unlock on gesture, WebGL context loss, touch coalescing) and low-end Android.
+
+---
+
+## 8. Common browser-game bugs to prevent (checklist)
+- Movement tied to frame rate (no delta) → runs too fast/slow on different displays.
+- `Clock.getDelta()` called multiple times per frame → things freeze/jitter.
+- Model faces wrong way → forgot +Z-forward convention / camera −Z; fix geometry rotation or `lookAt`.
+- Pointer lock never engages → missing user-gesture click / blocker overlay.
+- Memory leak / crash after level reload → geometries/materials/textures not disposed.
+- Frame drops → too many draw calls (needs instancing/batching/atlases), per-frame allocations, uncompressed textures.
+- Blurry or misaligned on mobile/retina → not handling devicePixelRatio / canvas resize.
+- CORS-tainted canvas → missing `crossOrigin='anonymous'`.
+- Physics tunneling/instability → variable timestep instead of fixed step.
+- Audio doesn't play on mobile → not unlocked on first user gesture.
+
+---
+
+## Sources
+- Three.js official: PointerLock example (https://threejs.org/examples/misc_controls_pointerlock.html), docs for `Timer`, `Object3D.lookAt`, `InstancedMesh`, `BatchedMesh` (https://threejs.org/docs/).
+- "Discover three.js" — animation loop / Loop class (https://discoverthreejs.com/book/first-steps/animation-loop/).
+- Three.js Discourse (Clock→Timer r183, setAnimationLoop vs RAF, coordinate-system threads) — https://discourse.threejs.org/.
+- Three.js perf write-ups: utsubo.com "100 tips" (https://www.utsubo.com/blog/threejs-best-practices-100-tips), threejsroadmap.com draw calls.
+- StackOverflow / Medium tutorials on PointerLock WASD and Rapier character controllers (https://medium.com/javascript-alliance/creating-a-first-person-character-controller-in-three-js-5d96534edfd8).
+- Babylon.js: official optimization guide (https://doc.babylonjs.com/features/featuresDeepDive/scene/optimize_your_scene), SceneOptimizer, camera input docs; 2025 forum best-practices thread (https://forum.babylonjs.com/t/best-practices-for-optimizing-babylon-js-scenes-not-just-on-lower-end-devices/58688); Babylon 9.0 notes.
+- Phaser: docs.phaser.io (Scenes, Arcade Physics), Phaser Discourse best-practices threads, franzeus.medium.com "How I optimized my Phaser 3 action game in 2025".
+- Mobile/touch: nipplejs (https://github.com/yoannmoinet/nipplejs), joshmorony.com Phaser scaling guide.
+- Fix Your Timestep (Gaffer On Games) — classic fixed-timestep reference.

package/skills/grok-controls/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: controls
+description: >
+  Player-facing input signs for browser games: WASD, vehicles, flight, FPS
+  mouse-look, and the #1 failure mode (inverted A/D). Mandatory control
+  self-tests and a tiny test interface so you can verify A turns left before
+  shipping. Load for ANY game with movement, steering, flying, driving, tanks,
+  boats, mechs, drones, planes, karts, third-person follow cams — not only
+  racing. Triggers on "controls", "WASD", "inverted", "steer", "flight",
+  "airplane", "kart", "vehicle", "yaw", "roll", "pitch", "mouse look", "A/D".
+metadata:
+  short-description: "Control signs, inverted A/D fix, vehicle/flight maps, mandatory self-test"
+user-invocable: false
+---
+
+# Controls (player-visible signs — do not ship inverted)
+
+**Read this end-to-end before writing movement/steer/flight code** for any game
+that uses WASD, arrows, a chase camera, or a flying craft. Do **not** skip this
+and only open `racing-kart` or `fps` — those genre files assume you already
+know these signs. Inverted A/D is the most common ship-blocker in vehicle and
+flight demos.
+
+Pair with **`building-games`** (loop, camera, 3D orientation) and
+**`building-games/references/input.md`** (keydown state, gamepad, touch). This
+skill owns **what left/right/up mean to the player** and **how you prove it**.
+
+---
+
+## 0. Hard rules (fail the build if broken)
+
+1. **Player-visible left/right is law.** From a **chase / behind** camera while
+   the craft moves **forward**:
+   - **A / ←** → nose (or bank) turns **left on screen**
+   - **D / →** → nose (or bank) turns **right on screen**
+2. **Never reuse FPS strafe as vehicle steer.** FPS “D → +right vector” is
+   **position** on the ground plane. Vehicle A/D is **yaw (or roll) rate**, not
+   a strafe offset. Mixing them is the #1 cause of inverted A/D.
+3. **You must run a control self-test (§5) before saying done.** Screenshot-only
+   QA is not enough. If A turns right, **flip the steer/roll sign**, retest,
+   then ship — do not invent a new coordinate story.
+
+---
+
+## 1. Shared 3D basis (use this everywhere)
+
+three.js: right-handed, **+Y up**, meshes face **+Z**, cameras look **−Z**.
+
+**Yaw-only heading on XZ** (ground vehicles, walkers, most arcade craft):
+
+```
+// yaw = 0 faces world −Z; +yaw is CCW about +Y (nose moves toward −X)
+forward = (-sin(yaw), 0, -cos(yaw))
+right   = ( cos(yaw), 0, -sin(yaw))   // = normalize(cross(forward, worldUp))
+```
+
+With a chase cam **behind** the craft (camera near `position - forward * dist`):
+
+| Player sees | World (this basis) | Input |
+|-------------|--------------------|--------|
+| Nose left   | **+yaw**           | **A / ←** must produce **+yaw** (or equivalent bank-left for planes) |
+| Nose right  | **−yaw**           | **D / →** must produce **−yaw** |
+
+If your basis differs, keep **one** consistent pair — but the **player-visible**
+row above is mandatory.
+
+---
+
+## 2. Genre maps
+
+### 2a. FPS / on-foot (strafe, not steer)
+
+```
+W = +forward, S = −forward, D = +right, A = −right   // position, not yaw
+mouse: yaw -= movementX * sens; pitch -= movementY * sens; clamp pitch
+```
+
+Body yaw for look; **movement uses yaw only** (do not apply pitch to walk).
+
+### 2b. Ground / water vehicle (kart, bike, jetski, boat, tank, rover, snowmobile)
+
+Arcade body with `heading`/`yaw` and forward `speed`:
+
+```js
+// Input (held keys → actions once per frame)
+let steer = 0; // -1..+1, player-visible
+if (keys.has('KeyA') || keys.has('ArrowLeft'))  steer += 1;  // LEFT
+if (keys.has('KeyD') || keys.has('ArrowRight')) steer -= 1;  // RIGHT
+// Optional: steer = clamp(steer + gamepadX, -1, 1) with same sign convention
+
+// Integrate (speedFactor ~ 0..1 from |speed|)
+const reverse = speed >= 0 ? 1 : -1; // wheel-left still feels left in reverse
+yaw += steer * turnRate * speedFactor * reverse * dt;
+
+// Move along heading
+const fx = -Math.sin(yaw), fz = -Math.cos(yaw);
+position.x += fx * speed * dt;
+position.z += fz * speed * dt;
+```
+
+**Canonical bug (do not copy):**
+
+```js
+// WRONG — this is what ships inverted A/D in the wild
+if (KeyA) steer -= 1;
+if (KeyD) steer += 1;
+yaw += steer * turnRate * dt;  // A → −yaw → nose RIGHT on chase cam
+```
+
+If you already wrote `KeyA → steer--`, either **swap the key mapping** or
+**negate once at integrate** (`yaw += -steer * …`) — then run §5. Do not flip
+twice (keys + integrate + bank mesh).
+
+### 2c. Fixed-wing flight (airplane, glider, RC plane)
+
+| Input | Action | Player expectation |
+|-------|--------|--------------------|
+| **A / ←** | **Roll left** (aileron) | Left wing down / bank left |
+| **D / →** | **Roll right** | Right wing down / bank right |
+| **W / ↑** | Pitch (pick one scheme and label HUD) | Usually nose down *or* pull-up — be consistent |
+| **S / ↓** | Opposite pitch | |
+| **Q / E** | Yaw / rudder (optional) | Q left, E right |
+
+- **A/D are not strafe** and not “ground steer with FPS signs.”
+- Apply roll in the craft’s **local forward axis** with a sign that matches
+  **bank left on A**. If the mesh banks the wrong way, flip **one** sign on the
+  roll apply (or on the A/D → roll mapping), not the whole basis.
+- Coordinated turn: positive bank should produce a turn that matches the bank
+  direction under the chase/external cam.
+
+### 2d. Heli / drone / 6DOF
+
+Document the scheme on a start overlay. Minimum:
+
+- Throttle/altitude on discrete keys must **not** stick “always up” after one
+  press (use held state or explicit up/down).
+- Strafe/yaw: **A left, D right** in the craft’s horizontal frame (player-visible).
+
+### 2e. 2D side-scroller / platformer
+
+**D / →** moves **right on screen**; **A / ←** moves **left**. Gravity only
+inverted if the genre is explicitly upside-down.
+
+---
+
+## 3. Camera must agree
+
+- Chase cam: `desired = craftPos + up*height + forward*(-followDist)`; lerp;
+  `lookAt(craft)`.
+- Compute `forward` **once** for both movement and camera — do not rebuild with
+  opposite yaw sign in the camera path.
+- Debug order: (1) keys register → (2) signs correct (§5) → (3) camera agrees.
+
+---
+
+## 4. Input plumbing (brief)
+
+- Track keys with a `Set` on `keydown`/`keyup` using **`event.code`**; clear on
+  `blur` / `visibilitychange`. Move in the game loop with **dt**, not in the
+  key handler.
+- Unify keyboard + touch + gamepad into **actions** (`throttle`, `steer`,
+  `pitch`, `roll`, …). See `building-games/references/input.md`.
+- Touch: left stick = move/steer, right = actions; ≥44px targets.
+
+---
+
+## 5. Mandatory control self-test (before “done”)
+
+Screenshot-only is **not** enough for any craft with A/D.
+
+### 5a. Player-visible checklist (every vehicle / flight build)
+
+While **moving forward** (speed > small epsilon), chase cam behind:
+
+| Hold | Must observe within ~0.5s |
+|------|---------------------------|
+| **A** | Nose or bank moves **left** on screen |
+| **D** | Nose or bank moves **right** on screen |
+| **W** (ground) | Speed increases / moves along facing |
+| **S** (ground) | Brakes or reverse (as designed) |
+
+If A fails: flip steer/roll sign **once**, retest both A and D.
+
+### 5b. Minimal test interface (implement this)
+
+Expose a tiny hook so you (and automated QA) can prove signs without guessing
+private closures:
+
+```js
+// e.g. src/game/controlsTest.ts — dev/QA only is fine
+export type ControlsProbe = {
+  getYaw: () => number;       // radians; or getHeading()
+  getSpeed: () => number;
+  /** Inject held actions instead of real keys; both stay applied until you
+   *  change them, so §5c can hold a key across frames and clear at the end. */
+  setSteer?: (v: number) => void; // -1..1, same sign as production
+  setKeys?: (codes: string[]) => void; // held until the next call; `[]` clears
+};
+
+declare global {
+  interface Window {
+    __controlsTest?: ControlsProbe;
+  }
+}
+```
+
+Wire `window.__controlsTest` from the game loop when `import.meta.env.DEV` or a
+`?qa=1` flag is set.
+
+### 5c. Automated smoke (run it)
+
+Drive the §5b probe with the preinstalled **`agent-browser`** CLI — that is the
+first move, not a hand-written script. **A thrown `eval` exits non-zero; a
+merely falsy one does not**, so assert by throwing. Run it as one `batch` — one
+CLI call, not one per verb — taking JSON on stdin; `--bail` stops at the first
+failing step and exits non-zero.
+
+```bash
+agent-browser batch --bail <<'JSON'   # find's label is case-sensitive: copy it from `snapshot -i`
+[["open","http://127.0.0.1:8080/"],
+ ["find","text","Start","click"],
+ ["eval","if (!window.__controlsTest?.setKeys) throw Error('no §5b probe: add setKeys')"],
+ ["eval","__controlsTest.setKeys(['KeyW'])"],
+ ["wait","600"],
+ ["eval","if (__controlsTest.getSpeed() <= 0.1) throw Error('W: no move')"],
+ ["eval","(async () => { const t = __controlsTest, y0 = t.getYaw(); t.setKeys(['KeyW','KeyA']); await new Promise(r => setTimeout(r, 300)); t.setKeys(['KeyW']); const d = t.getYaw() - y0, w = Math.atan2(Math.sin(d), Math.cos(d)); if (w < -0.05) throw Error('A turns RIGHT — inverted, got ' + w.toFixed(2)); if (w <= 0.05) throw Error('A barely turned (' + w.toFixed(2) + ') — hold longer or check the sim is running'); return 'A ok' })()"],
+ ["eval","__controlsTest.setKeys([])"],
+ ["screenshot","/workspace/screenshots/controls.png"],
+ ["close"]]
+JSON
+```
+
+**Hold keys through the probe, not with `keydown`** — `agent-browser keydown`
+does not reach §4's `Set`, so a correct game reads as broken. No `setKeys` on
+your probe? Add it (§5b), or dispatch the key event yourself — the browser-QA
+reference's **Keys** note has the mechanism and the form.
+
+The hold sits **inside** one `eval`: spread across commands it lasts however
+long they take, and the ±π wrap in `Math.atan2(Math.sin(d), Math.cos(d))`
+reads a craft that turned more than π as one turning the other way. The IIFE is
+what keeps the step re-runnable — a bare `const d = …` fails the second time
+with "already declared" — and `async` is what lets the hold run in page time.
+Repeat for **D** with `'KeyD'` and both comparisons mirrored (`w > 0.05` is
+inverted, `w >= -0.05` is barely), single-quoted so the JSON needs no escapes;
+for planes assert **roll**: A ⇒ bank left.
+
+**`A turns RIGHT`** is the sign error: flip **one** sign and re-run.
+**`A barely turned`** is not — the craft moved the right way, just less than
+0.05 rad in 300 ms, which a boat or a heavy rover will do; raise the hold, or
+check the sim is running, and flip nothing. Any other non-zero exit — no probe,
+a wedged daemon — means the check never ran: read the message first. Read the
+browser-QA reference `AGENTS.md` links before your first flow — verbs, argument
+shapes and the fallback are there.
+
+### 5d. What not to do
+
+- Do **not** only test “D increases some internal variable.”
+- Do **not** use FPS “D → +X when facing −Z” as the vehicle pass condition.
+- Do **not** flip mesh bank, camera, and steer all at once when fixing — change
+  **one** sign, retest.
+
+---
+
+## 6. Finish criteria (controls)
+
+- [ ] Opened **this** skill before writing movement/steer/flight.
+- [ ] Genre map chosen (§2) and start-screen / HUD labels match it.
+- [ ] Chase-cam A/D player-visible test **passed** (§5a).
+- [ ] `window.__controlsTest` (or equivalent) available in dev/QA and used once.
+- [ ] No inverted bank mesh relative to roll/steer input.
+- [ ] Keys are held-state + dt-scaled; no sticky thrust from a single Space tap
+      unless intentional and labeled.
+
+If any box is unchecked, the game is **not** done.

package/skills/grok-controls/agentsam.skill.json

@@ -0,0 +1,25 @@
+{
+  "schema": "agentsam.skill.v1",
+  "id": "grok-controls",
+  "name": "Grok \u00b7 controls",
+  "description": "Control signs, inverted A/D fix, vehicle/flight maps, mandatory self-test",
+  "icon": "skill",
+  "slash": {
+    "suggested": "/grok-controls"
+  },
+  "instructions": {
+    "source": "local_file",
+    "ref": "SKILL.md"
+  },
+  "execution": {
+    "mode": "turn",
+    "tools": [],
+    "operations": [],
+    "capabilities": []
+  },
+  "provenance": {
+    "source": "apps/local-studio/.grok/skills",
+    "vendor": "grok",
+    "status": "imported"
+  }
+}