@genex-ai/cli-demo 0.98.0-dev.284 → 0.99.0-dev.286

package/dist/index.js

@@ -4908,7 +4908,12 @@ function splitArgs(text) {
 var lineOf = (content, index) => content.slice(0, index).split("\n").length;
 var DEPTH_RATIO_LIMIT = 1e6;
 async function detectSurfaceScan(cwd = process.cwd()) {
-  const found = { guessedRepeat: [], squarePoints: [], depthRange: [] };
+  const found = {
+    guessedRepeat: [],
+    squarePoints: [],
+    depthRange: [],
+    mediaElementAudio: []
+  };
   const srcDir = path15.join(cwd, "src");
   let entries;
   try {
@@ -4955,6 +4960,18 @@ async function detectSurfaceScan(cwd = process.cwd()) {
         ratio
       });
     }
+    const threeAudioImport = /import\s+(?:type\s+)?\{[^}]*\bAudio\b[^}]*\}\s+from\s*["']three["']/.test(
+      content
+    );
+    const mediaRe = /\bnew\s+Audio\s*\(|\bdocument\s*\.\s*createElement\s*\(\s*["'`]audio["'`]\s*\)/g;
+    while (m = mediaRe.exec(content)) {
+      const isCtor = m[0].startsWith("new");
+      if (isCtor && threeAudioImport) continue;
+      found.mediaElementAudio.push({
+        where: `${rel}:${lineOf(content, m.index)}`,
+        detail: isCtor ? "new Audio(...)" : 'document.createElement("audio")'
+      });
+    }
   }
   return found;
 }
@@ -5079,6 +5096,12 @@ function surfaceNudges(log, s) {
       `Particles will render as hard SQUARES: ${list} builds a PointsMaterial with no map/alphaMap, so every point is an opaque camera-facing quad. Give it a soft sprite (genex image --transparent) or a round gl_PointCoord cutout \u2014 and check the particle belongs there at all: genex-threejs-procedural-vfx decides that per moment.`
     );
   }
+  if (s.mediaElementAudio.length) {
+    const list = s.mediaElementAudio.map((d) => `${d.where} \u2014 ${d.detail}`).join("; ");
+    log.warn(
+      `HTML <audio> elements are carrying this game's sound: ${list}. On iPhone an <audio> element is a handle on the operating system's media pipeline in ANOTHER PROCESS: every write to .volume or .playbackRate is a cross-process call, and play() is slow and asynchronous. A sound driven from a live value \u2014 wheels from speed, engine from RPM \u2014 writes 60-120 of those a second and stutters the whole game, while one-shots arrive late. It disguises itself as a graphics problem perfectly: only while moving, identical at every quality setting, desktop fine. THREE.Audio/PositionalAudio on one AudioListener have none of this \u2014 genex-ai-sfx ships the pooled one-shot, the live-value loop, and the decode-during-the-menu preload.`
+    );
+  }
   for (const d of s.depthRange) {
     log.warn(
       `Camera depth range ${d.detail} (far/near = ${d.ratio.toExponential(1)}) at ${d.where} is past what a 24-bit depth buffer can serve \u2014 touching surfaces will z-fight and flicker, and it reads fine right up until it doesn't. near is the expensive knob (resolvable depth \u2248 z\xB2 / (near \xD7 2^24)), so raise near to the closest the camera can actually get. If the range is genuinely astronomical, that is what WebGLRenderer's logarithmicDepthBuffer is for: genex-threejs-camera-direction.`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.98.0-dev.284",
+  "version": "0.99.0-dev.286",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/skills/genex-ai-music/SKILL.md

@@ -87,6 +87,11 @@ document.addEventListener("visibilitychange", () => {
 });
 ```
 
+Decode the track (and every sfx clip) while the **menu** is up, not on PLAY:
+`loadAsync` runs `decodeAudioData`, which does not need a running `AudioContext` —
+only playing does. `$genex-ai-sfx` has the preload-everything recipe; run the
+music through the same pass so the first second of gameplay waits on nothing.
+
 **Menu reuse:** the same `music` object at lower volume (`setVolume(0.18)`)
 during the menu phase, restored to the setting's value on PLAY — zero extra
 generations. If the loop point is audible (the track came back with an
@@ -98,9 +103,11 @@ intro/outro despite the prompt), crossfade the tail into the head with a second
 A game with generated audio and no volume control is a failure mode. The
 settings screen gets **two sliders — Music and SFX** (music default 0.30, sfx
 ~0.7), persisted (localStorage or the save slot) and applied live:
-`music.setVolume(v)` for the music bed; keep every sfx's volume routed through
-one shared multiplier. `$genex-threejs-game-ui` carries this as a hard settings
-rule — wire the sliders in the same milestone as the track.
+`music.setVolume(v)` for the music bed, and one shared `sfxVolume` multiplier
+every sound effect is scaled by (the `playSfx` / live-value recipes in
+`$genex-ai-sfx` already read it — keep it a single exported value, never a
+number copied into each call site). `$genex-threejs-game-ui` carries this as a
+hard settings rule — wire the sliders in the same milestone as the track.
 
 ## Publish checklist
 

package/templates/skills/genex-ai-sfx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: genex-ai-sfx
-description: Generate a real sound effect (mp3) from a text prompt with `npx genex sfx`, then play it in Three.js (positional or global audio). Use when the user wants a specific sound — a gunshot, footstep, pickup chime, explosion, engine hum, UI click, whoosh — triggered on a game event.
+description: Generate a real sound effect (mp3) from a text prompt with `npx genex sfx`, then wire it in Three.js — one-shots, rapid repeats, and a looping sound whose pitch and volume track a live value (engine, wheels, wind). Use for any specific sound triggered by a game event, and whenever audio must react continuously to gameplay without stuttering phones.
 ---
 
 # Genex AI · SFX
@@ -54,8 +54,105 @@ if (!sound.isPlaying) sound.play();
 **Global** (UI/non-spatial — same volume everywhere): use `new THREE.Audio(listener)`
 instead of `PositionalAudio` and don't attach it to a mesh.
 
-Reuse one loaded `buffer` across many plays; create a fresh `Audio`/`PositionalAudio`
-(or call `sound.play()` again once stopped) per trigger.
+Reuse one loaded `buffer` across many plays — the three recipes below are how.
+
+## Never drive game sound through an `<audio>` element
+
+`new Audio(url)`, `document.createElement("audio")`, an `<audio>` tag — same object,
+all wrong here. On iPhone it is a **handle on the OS media pipeline in another
+process**: writing `.volume`/`.playbackRate` is a **cross-process call** (a sound
+driven from a live value writes 60–120 of those a second and stutters the whole
+game), and `play()` is **async and slow**, so one-shots land after the event.
+
+It disguises itself as a graphics problem: only while moving, identical at every
+quality setting, desktop fine. The one-second tell — **the music plays throughout
+and costs nothing**, same object and same code path, because its volume and pitch
+never change. *A sound playing is free; a sound written to every frame is not.*
+
+`THREE.Audio`/`PositionalAudio` are WebAudio and have none of this — use them for
+everything, including UI clicks.
+
+## Decode everything before the player needs it
+
+A clip that hasn't finished decoding stalls on its first play — exactly the first
+second of gameplay. **Decoding needs no running `AudioContext`, only playing does**,
+so decode while the menu is up:
+
+```ts
+import * as THREE from "three";
+
+const listener = new THREE.AudioListener();
+camera.add(listener); // ONE listener serves every sound and the music
+
+const CLIPS = {
+  jump: "https://assets.genex.technology/generations/<id>/audio-sfx",
+  wheels: "https://assets.genex.technology/generations/<id>/audio-sfx",
+} as const;
+type ClipName = keyof typeof CLIPS;
+
+const buffers = new Map<ClipName, AudioBuffer>();
+
+/** Call this while the menu/loading screen is up — no user gesture needed. */
+export async function preloadAudio(): Promise<void> {
+  const loader = new THREE.AudioLoader();
+  await Promise.all(
+    Object.entries(CLIPS).map(async ([name, url]) => {
+      buffers.set(name as ClipName, await loader.loadAsync(url));
+    }),
+  );
+}
+```
+
+## Rapid repeats: pool the voices
+
+Footsteps, hits and gunfire re-trigger faster than a clip ends, one `THREE.Audio`
+plays once at a time, and a fresh one per shot allocates during combat. Keep a
+small pool per clip and reuse whatever is idle:
+
+```ts
+const pool = new Map<ClipName, THREE.Audio[]>();
+
+export function playSfx(name: ClipName, volume = 0.7): void {
+  const buffer = buffers.get(name);
+  if (!buffer) return; // still decoding — silence beats a stall
+  const voices = pool.get(name) ?? [];
+  let voice = voices.find((v) => !v.isPlaying);
+  if (!voice) {
+    voice = new THREE.Audio(listener);
+    voice.setBuffer(buffer);
+    voices.push(voice);
+    pool.set(name, voices);
+  }
+  voice.setVolume(volume * sfxVolume); // sfxVolume = the settings slider
+  voice.play();
+}
+```
+
+Positional one-shots: same pool built from `THREE.PositionalAudio`, `mesh.add(voice)`.
+
+## A sound that tracks a live value
+
+Engine, wheels, wind, rotor wash, a charging weapon — start the loop **once**, then
+write to it every frame. Both calls below are AudioParam writes on the audio thread:
+no allocation, no cross-process call.
+
+```ts
+const wheels = new THREE.Audio(listener);
+wheels.setBuffer(buffers.get("wheels")!);
+wheels.setLoop(true);
+wheels.setVolume(0);
+wheels.play(); // ONCE, from the first user gesture — never per frame
+
+// in the render loop:
+const speed01 = THREE.MathUtils.clamp(speed / topSpeed, 0, 1);
+wheels.setVolume(speed01 * 0.6 * sfxVolume);
+wheels.setPlaybackRate(0.8 + speed01 * 0.7); // pitch rises with speed
+```
+
+If the driving value can jump (a gear change, a hit, a respawn), a step is an
+audible click — glide instead:
+`wheels.gain.gain.setTargetAtTime(target, listener.context.currentTime, 0.05)`.
+To silence a loop, ride the volume to 0 and leave it running — never `stop()`/`play()`.
 
 ## Publish checklist
 
@@ -86,3 +183,8 @@ Reuse one loaded `buffer` across many plays; create a fresh `Audio`/`PositionalA
   first play from a click/keydown. Confirm the camera has an `AudioListener`.
 - **Too quiet/loud** — `sound.setVolume(0..1)`; for positional, tune
   `setRefDistance` / `setRolloffFactor`.
+- **Stutters on a phone while moving, at every quality setting** — audio, not
+  graphics: see the `<audio>` section above (`$genex-threejs-adaptive-quality` has
+  the same triage from the performance side).
+- **A sound is late the first time, then fine** — it was still decoding. Preload
+  during the menu.

package/templates/skills/genex-threejs-adaptive-quality/SKILL.md

@@ -17,6 +17,28 @@ This is a completion gate like the post stack: every game wires the tier at
 boot before it is called done. It costs three lines, not a testing burden —
 you still verify on desktop only.
 
+## Arriving here because a phone stutters? Rule out audio first
+
+Not every mobile performance problem is a rendering problem, and one impostor
+costs whole afternoons — shadows, bloom, draw calls, physics and memory all get
+investigated before anyone looks at the sound. Read these three symptoms
+together before you touch a single quality knob:
+
+- it only happens **while moving** (or while some value is continuously changing),
+- it is **identical at every quality setting**, including the lowest,
+- **desktop is fine.**
+
+That is the signature of an `<audio>` element being written to every frame — on
+iPhone each `.volume`/`.playbackRate` write is a call into another process. The
+one-second confirmation: **the music plays throughout and costs nothing**, because
+music's volume and pitch never change, so nothing is ever written to it. Same
+object, same code path, opposite cost. `$genex-ai-sfx` has the fix and the
+WebAudio recipes; nothing in this skill will help.
+
+Genuine graphics symptoms look different: a quality setting changes it, it is
+worse when more is on screen, and it degrades over minutes (thermal) rather than
+tracking one input.
+
 ## Install
 
 ```bash
@@ -205,3 +227,6 @@ runtime).
 - Testing quality tiers by resizing the desktop window → tiers key off touch +
   OS, not viewport. Trust desktop verification plus the preflight report
   `genex preview` prints.
+- Stepping quality down to chase a stutter the quality settings never change →
+  that is the audio impostor above, and every rung you spend on it makes the
+  game uglier without touching the cause.

package/templates/skills/genex-threejs-vehicle-controllers/references/drone.md

@@ -167,3 +167,9 @@ propeller: `finalThrottle` (0..1 mixer output — rotor-wash/audio intensity),
 `worldThrustPos`/`worldThrustDir` (where and which way to emit), and
 `thrustImpulse`. `drone.hoverThrottle` reads the last computed hover value.
 All vectors are reused internal instances — copy, never mutate.
+
+Driving rotor audio from `finalThrottle` is a per-frame write, so it must go
+through WebAudio: start ONE looped `THREE.Audio` and call
+`setVolume`/`setPlaybackRate` on it each frame — never an `<audio>` element,
+whose `.volume`/`.playbackRate` writes are cross-process calls on iPhone and
+stutter the whole game. `$genex-ai-sfx` has the live-value loop recipe.