@genex-ai/cli-demo 0.71.0 → 0.74.0-dev.190

package/dist/index.js

@@ -8,7 +8,7 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import { fileURLToPath } from "url";
-var RAW_CHANNEL = "latest";
+var RAW_CHANNEL = "dev";
 var CLI_CHANNEL = RAW_CHANNEL === "dev" ? "dev" : "latest";
 var STANDS = {
   prod: { api: "https://api.genex.games", dashboard: "https://genex.games" },
@@ -1497,6 +1497,261 @@ import crypto3 from "crypto";
 import fs9 from "fs/promises";
 import os4 from "os";
 import path10 from "path";
+
+// ../../packages/mobile-scan/src/image-dims.ts
+function u32be(b, o) {
+  return (b[o] << 24 | b[o + 1] << 16 | b[o + 2] << 8 | b[o + 3]) >>> 0;
+}
+function u32le(b, o) {
+  return (b[o] | b[o + 1] << 8 | b[o + 2] << 16 | b[o + 3] << 24) >>> 0;
+}
+function u16be(b, o) {
+  return b[o] << 8 | b[o + 1];
+}
+function u16le(b, o) {
+  return b[o] | b[o + 1] << 8;
+}
+function isPng(b) {
+  return b.length > 24 && b[0] === 137 && b[1] === 80 && b[2] === 78 && b[3] === 71 && b[4] === 13 && b[5] === 10 && b[6] === 26 && b[7] === 10;
+}
+var KTX2_MAGIC = [171, 75, 84, 88, 32, 50, 48, 187, 13, 10, 26, 10];
+function parseImageDims(bytes) {
+  if (bytes.length < 30) return null;
+  if (isPng(bytes)) {
+    return { width: u32be(bytes, 16), height: u32be(bytes, 20) };
+  }
+  if (bytes[0] === 255 && bytes[1] === 216) {
+    let i = 2;
+    while (i + 9 < bytes.length) {
+      if (bytes[i] !== 255) {
+        i++;
+        continue;
+      }
+      const marker = bytes[i + 1];
+      if (marker === 255) {
+        i++;
+        continue;
+      }
+      if (marker === 216 || marker >= 208 && marker <= 217) {
+        i += 2;
+        continue;
+      }
+      const isSof = marker >= 192 && marker <= 195 || marker >= 197 && marker <= 199 || marker >= 201 && marker <= 203 || marker >= 205 && marker <= 207;
+      if (isSof) {
+        return { width: u16be(bytes, i + 7), height: u16be(bytes, i + 5) };
+      }
+      i += 2 + u16be(bytes, i + 2);
+    }
+    return null;
+  }
+  if (bytes[0] === 82 && // RIFF….WEBP
+  bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 70 && bytes[8] === 87 && bytes[9] === 69 && bytes[10] === 66 && bytes[11] === 80) {
+    const fourcc = String.fromCharCode(bytes[12], bytes[13], bytes[14], bytes[15]);
+    if (fourcc === "VP8X" && bytes.length >= 30) {
+      const w = 1 + (bytes[24] | bytes[25] << 8 | bytes[26] << 16);
+      const h = 1 + (bytes[27] | bytes[28] << 8 | bytes[29] << 16);
+      return { width: w, height: h };
+    }
+    if (fourcc === "VP8 " && bytes.length >= 30) {
+      return { width: u16le(bytes, 26) & 16383, height: u16le(bytes, 28) & 16383 };
+    }
+    if (fourcc === "VP8L" && bytes.length >= 25 && bytes[20] === 47) {
+      const b0 = bytes[21];
+      const b1 = bytes[22];
+      const b2 = bytes[23];
+      const b3 = bytes[24];
+      const width = 1 + ((b1 & 63) << 8 | b0);
+      const height = 1 + ((b3 & 15) << 10 | b2 << 2 | (b1 & 192) >> 6);
+      return { width, height };
+    }
+    return null;
+  }
+  if (KTX2_MAGIC.every((v, idx) => bytes[idx] === v)) {
+    return { width: u32le(bytes, 20), height: u32le(bytes, 24), ktx2: true };
+  }
+  return null;
+}
+
+// ../../packages/mobile-scan/src/glb.ts
+function u32le2(b, o) {
+  return (b[o] | b[o + 1] << 8 | b[o + 2] << 16 | b[o + 3] << 24) >>> 0;
+}
+function scanGlb(bytes) {
+  if (bytes.length < 20 || u32le2(bytes, 0) !== 1179937895) return null;
+  try {
+    const jsonLen = u32le2(bytes, 12);
+    if (u32le2(bytes, 16) !== 1313821514) return null;
+    const json = JSON.parse(new TextDecoder().decode(bytes.subarray(20, 20 + jsonLen)));
+    let bin = null;
+    const binHeader = 20 + jsonLen;
+    if (binHeader + 8 <= bytes.length && u32le2(bytes, binHeader + 4) === 5130562) {
+      bin = bytes.subarray(binHeader + 8, binHeader + 8 + u32le2(bytes, binHeader));
+    }
+    const images = [];
+    for (const img of json.images ?? []) {
+      if (img.bufferView == null || !bin) continue;
+      const view = json.bufferViews?.[img.bufferView];
+      if (!view?.byteLength) continue;
+      const slice = bin.subarray(view.byteOffset ?? 0, (view.byteOffset ?? 0) + view.byteLength);
+      const dims = parseImageDims(slice);
+      if (dims) images.push({ ...dims, mimeType: img.mimeType, bytes: view.byteLength });
+    }
+    let triangles = 0;
+    for (const mesh of json.meshes ?? []) {
+      for (const prim of mesh.primitives ?? []) {
+        const accessor = prim.indices != null ? json.accessors?.[prim.indices] : json.accessors?.[prim.attributes?.POSITION ?? -1];
+        if (accessor?.count) triangles += Math.floor(accessor.count / 3);
+      }
+    }
+    return {
+      triangles,
+      binBytes: bin?.byteLength ?? 0,
+      images,
+      extensions: json.extensionsUsed ?? []
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ../../packages/mobile-scan/src/scan.ts
+var GENEX_GENERATION_URL_RE = /https:\/\/assets\.genex\.technology\/generations\/([A-Za-z0-9._-]+)\/([A-Za-z0-9._@-]+)/g;
+var SKYBOX_ROLE = "skybox-equirect";
+var MOBILE_RUNG_SUFFIX_RE = /@(\d+)$/;
+var MOBILE_BUDGET_MB = { broad: 300, modern: 700 };
+var TEXT_EXT = /\.(js|mjs|cjs|html|css|json|txt)$/i;
+var IMAGE_EXT = /\.(png|jpe?g|webp|ktx2)$/i;
+var VIDEO_EXT = /\.(mp4|webm|mov)$/i;
+var AUDIO_EXT = /\.(mp3|ogg|wav|m4a)$/i;
+var GLB_EXT = /\.(glb|gltf)$/i;
+function scanBundle(files) {
+  const images = [];
+  const glbs = [];
+  const videos = [];
+  const audio = [];
+  const urls = /* @__PURE__ */ new Set();
+  let text = "";
+  let totalBytes = 0;
+  for (const f of files) {
+    totalBytes += f.bytes.byteLength;
+    if (IMAGE_EXT.test(f.relPath)) {
+      const dims = parseImageDims(f.bytes);
+      if (dims) images.push({ path: f.relPath, bytes: f.bytes.byteLength, ...dims });
+      continue;
+    }
+    if (GLB_EXT.test(f.relPath)) {
+      glbs.push({ path: f.relPath, bytes: f.bytes.byteLength, scan: scanGlb(f.bytes) });
+      continue;
+    }
+    if (VIDEO_EXT.test(f.relPath)) {
+      videos.push({ path: f.relPath, bytes: f.bytes.byteLength });
+      continue;
+    }
+    if (AUDIO_EXT.test(f.relPath)) {
+      audio.push({ path: f.relPath, bytes: f.bytes.byteLength });
+      continue;
+    }
+    if (TEXT_EXT.test(f.relPath)) {
+      text += new TextDecoder().decode(f.bytes.subarray(0, 8 * 1024 * 1024));
+      text += "\n";
+    }
+  }
+  for (const m of text.matchAll(GENEX_GENERATION_URL_RE)) urls.add(m[0]);
+  const dprMatch = text.match(/setPixelRatio\(\s*Math\.min\([^,)]+,\s*([\d.]+)\s*\)/);
+  const markers = {
+    rendererBackend: text.includes("WebGPURenderer") || text.includes("getContext('webgpu')") || text.includes('"webgpu"') ? "webgpu" : "webgl",
+    postStack: /EffectComposer|postprocessing|PostProcessing|RenderPipeline/.test(text),
+    dprCapLiteral: dprMatch?.[1] ? Number(dprMatch[1]) : null,
+    contextLossHandler: text.includes("webglcontextlost") || text.includes("device.lost"),
+    ktx2Loader: text.includes("KTX2Loader") || text.includes(".ktx2"),
+    touchHints: /joystick/i.test(text) || text.includes("touchstart") && text.includes("touch-action"),
+    adaptiveQuality: text.includes("__GENEX_QUALITY__")
+  };
+  return {
+    images,
+    glbs,
+    videos,
+    audio,
+    genexAssetUrls: [...urls],
+    markers,
+    totalBytes,
+    fileCount: files.length
+  };
+}
+
+// ../../packages/mobile-scan/src/estimate.ts
+var MB = 1024 * 1024;
+var CSS_W = 430;
+var CSS_H = 932;
+var WORST_SKYBOX_BYTES = 8192 * 4096 * 4 * 1.33;
+var WORST_IMAGE_BYTES = 2048 * 2048 * 4 * 1.33;
+var KTX2_DISCOUNT = 6;
+function textureBytes(w, h, ktx2) {
+  const raw = w * h * 4 * 1.33;
+  return ktx2 ? raw / KTX2_DISCOUNT : raw;
+}
+function estimateVram(scan, externalDims) {
+  let bundled = 0;
+  let maxDim = 0;
+  for (const img of scan.images) {
+    bundled += textureBytes(img.width, img.height, img.ktx2);
+    maxDim = Math.max(maxDim, img.width, img.height);
+  }
+  let glbTex = 0;
+  let geometry = 0;
+  for (const glb of scan.glbs) {
+    if (!glb.scan) {
+      geometry += glb.bytes;
+      continue;
+    }
+    const ktx2 = glb.scan.extensions.some((e) => e.includes("KHR_texture_basisu"));
+    for (const img of glb.scan.images) {
+      glbTex += textureBytes(img.width, img.height, img.ktx2 || ktx2);
+      maxDim = Math.max(maxDim, img.width, img.height);
+    }
+    geometry += Math.max(0, glb.scan.binBytes - glb.scan.images.reduce((s, i) => s + i.bytes, 0));
+  }
+  let external = 0;
+  const unresolved = [];
+  for (const url of scan.genexAssetUrls) {
+    const role = url.split("/").pop() ?? "";
+    if (MOBILE_RUNG_SUFFIX_RE.test(role)) continue;
+    const dims = externalDims.get(url);
+    if (dims) {
+      external += textureBytes(dims.width, dims.height, dims.ktx2);
+      maxDim = Math.max(maxDim, dims.width, dims.height);
+    } else {
+      unresolved.push(url);
+      external += role === SKYBOX_ROLE ? WORST_SKYBOX_BYTES : WORST_IMAGE_BYTES;
+      maxDim = Math.max(maxDim, role === SKYBOX_ROLE ? 8192 : 2048);
+    }
+  }
+  const dpr = Math.min(scan.markers.dprCapLiteral ?? 2, 3);
+  const surface = CSS_W * CSS_H * dpr * dpr * 4;
+  const framebuffers = surface * (3 + (scan.markers.postStack ? 4 : 0));
+  const shadow = 2048 * 2048 * 4;
+  const total = bundled + glbTex + external + framebuffers + shadow + geometry;
+  return {
+    estVramMb: Math.round(total / MB),
+    breakdown: {
+      bundledTexturesMb: Math.round(bundled / MB),
+      glbTexturesMb: Math.round(glbTex / MB),
+      externalTexturesMb: Math.round(external / MB),
+      framebuffersMb: Math.round(framebuffers / MB),
+      shadowDefaultMb: Math.round(shadow / MB),
+      geometryMb: Math.round(geometry / MB)
+    },
+    unresolvedExternals: unresolved,
+    textureMaxDim: maxDim
+  };
+}
+function tierFor(estVramMb) {
+  if (estVramMb < MOBILE_BUDGET_MB.broad) return "mobile-broad";
+  if (estVramMb < MOBILE_BUDGET_MB.modern) return "mobile-modern";
+  return "over-budget";
+}
+
+// src/lib/deploy.ts
 function run(cmd, args, env) {
   return new Promise((resolve) => {
     let child;
@@ -1514,6 +1769,48 @@ function run(cmd, args, env) {
     child.on("close", (code2) => resolve({ code: code2 ?? -1, out, err }));
   });
 }
+function printMobilePreflight(files, log) {
+  try {
+    const scan = scanBundle(files.map((f) => ({ relPath: f.relPath, bytes: f.bytes })));
+    const externalDims = /* @__PURE__ */ new Map();
+    for (const url of scan.genexAssetUrls) {
+      const role = url.split("/").pop() ?? "";
+      if (scan.markers.adaptiveQuality && role === SKYBOX_ROLE) {
+        externalDims.set(url, { width: 2048, height: 1024 });
+      } else {
+        externalDims.set(url, null);
+      }
+    }
+    const est = estimateVram(scan, externalDims);
+    const tier = tierFor(est.estVramMb);
+    const line = `Mobile preflight: ~${est.estVramMb} MB est. GPU memory on phones (budget: <${MOBILE_BUDGET_MB.broad} MB broad, <${MOBILE_BUDGET_MB.modern} MB modern) \u2014 ${tier}.`;
+    if (tier === "mobile-broad") {
+      log.dim(`  ${line}`);
+      return;
+    }
+    log.warn(line);
+    for (const url of est.unresolvedExternals) {
+      const role = url.split("/").pop() ?? "";
+      if (role === SKYBOX_ROLE) {
+        log.warn(
+          `  Skybox loaded full-size (${url.slice(0, 80)}\u2026): ~178 MB decoded on phones. Load it through pickAsset (genex-threejs-adaptive-quality) so phones get the @2048 rung.`
+        );
+      }
+    }
+    if (est.textureMaxDim > 2048) {
+      log.warn(`  Largest texture is ${est.textureMaxDim}px \u2014 phones want \u22642048 (props \u22641024).`);
+    }
+    if (scan.markers.postStack && scan.markers.dprCapLiteral == null) {
+      log.warn(
+        "  Post stack detected with no devicePixelRatio cap \u2014 cap at 1.5 on phones (genex-threejs-adaptive-quality)."
+      );
+    }
+    if (!scan.markers.contextLossHandler) {
+      log.warn("  No context-loss handler found \u2014 one GPU reset shows a dead canvas on phones.");
+    }
+  } catch {
+  }
+}
 var EXCLUDE_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", ".genex", "dist"]);
 function isSecretEnvFile(name) {
   return name === ".env" || name.startsWith(".env.") && name !== ".env.example";
@@ -1544,6 +1841,7 @@ async function deployGame(ctx, opts, log) {
     log.error(`No index.html in ${rel} \u2014 a game needs one to serve. Nothing deployed.`);
     return false;
   }
+  printMobilePreflight(files, log);
   const commit = contentCommit(files);
   log.step("Requesting an upload token\u2026");
   const grant = await getUploadToken(ctx, commit, log);
@@ -1687,7 +1985,8 @@ async function callPublish(ctx, commit, opts, log) {
         commit,
         matchmaking: opts.matchmaking ?? null,
         ...opts.embedSdkVersion ? { embedSdkVersion: opts.embedSdkVersion } : {},
-        ...opts.multiplayer !== void 0 ? { multiplayer: opts.multiplayer } : {}
+        ...opts.multiplayer !== void 0 ? { multiplayer: opts.multiplayer } : {},
+        ...opts.mobileControls !== void 0 ? { mobileControls: opts.mobileControls } : {}
       })
     });
   } catch (err) {
@@ -2033,6 +2332,32 @@ async function detectMatchmaking(log, cwd = process.cwd()) {
   }
   return null;
 }
+var TOUCH_KIT_MARKERS = /controllers\/touch\/|controllers\/character\/touch-joystick|TouchJoystick|VirtualButton|DragZone|RotateOverlay/;
+async function detectMobileControls(cwd = process.cwd()) {
+  try {
+    const raw = await fs11.readFile(path12.join(cwd, "package.json"), "utf8");
+    const pkg = JSON.parse(raw);
+    if (pkg.genex?.mobileControls === true) return true;
+  } catch {
+  }
+  const srcDir = path12.join(cwd, "src");
+  let entries;
+  try {
+    entries = await fs11.readdir(srcDir, { recursive: true });
+  } catch {
+    return false;
+  }
+  for (const rel of entries) {
+    if (rel.includes("node_modules")) continue;
+    if (!/\.(ts|js|mts|mjs|tsx|jsx)$/.test(rel)) continue;
+    try {
+      const content = await fs11.readFile(path12.join(srcDir, rel), "utf8");
+      if (TOUCH_KIT_MARKERS.test(content)) return true;
+    } catch {
+    }
+  }
+  return false;
+}
 var GAME_STATE_CALLS = /savePlayerState|saveWorldState|submitScore/;
 async function detectGameStateUsage(cwd = process.cwd()) {
   const srcDir = path12.join(cwd, "src");
@@ -2217,6 +2542,7 @@ async function detectFeatures(log, cwd = process.cwd()) {
     multiplayer: await detectMultiplayer(cwd),
     matchmaking: await detectMatchmaking(log, cwd),
     gameStateUsed: await detectGameStateUsage(cwd),
+    mobileControls: await detectMobileControls(cwd),
     uiPhases: await detectUiPhases(cwd),
     surfaces: await detectSurfaceScan(cwd),
     generations: await detectGenerationAudit(cwd)
@@ -2360,7 +2686,8 @@ async function runPublish(opts) {
         noBuild: opts.noBuild,
         matchmaking: detections.matchmaking,
         embedSdkVersion: detections.embedSdkVersion,
-        multiplayer: detections.multiplayer
+        multiplayer: detections.multiplayer,
+        mobileControls: detections.mobileControls
       },
       log
     );
@@ -2392,6 +2719,7 @@ async function runPublish(opts) {
     body.multiplayer = detections.multiplayer;
     body.matchmaking = detections.matchmaking ?? null;
     body.gameStateUsed = detections.gameStateUsed;
+    body.mobileControls = detections.mobileControls;
     res = await apiFetch(`${apiUrl}/api/projects/${meta.id}/publish`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
@@ -2445,7 +2773,8 @@ async function runPreview(opts) {
       noBuild: opts.noBuild,
       matchmaking: detections.matchmaking,
       embedSdkVersion: detections.embedSdkVersion,
-      multiplayer: detections.multiplayer
+      multiplayer: detections.multiplayer,
+      mobileControls: detections.mobileControls
     },
     log
   );
@@ -12694,7 +13023,8 @@ var CONTROLLER_KINDS = [
   "car",
   "drone",
   "touch",
-  "networked-physics"
+  "networked-physics",
+  "quality"
 ];
 var SHARED = [
   "shared/math.ts",
@@ -12787,6 +13117,17 @@ var CONTROLLER_FILE_SETS = {
       `physics.onBeforeStep(() => { drone.setMovement(keyboard.getDroneMovement()); drone.update(); });`
     ]
   },
+  quality: {
+    code: ["quality/tier.ts", "quality/governor.ts", "quality/pick-asset.ts"],
+    assets: [],
+    skill: "genex-threejs-adaptive-quality",
+    sketch: [
+      `const tier = detectTier(); // phone-low | phone | desktop \u2014 manual Quality setting wins`,
+      `renderer.setPixelRatio(Math.min(window.devicePixelRatio, tier.dprCap)); // antialias: tier.antialias at creation`,
+      `const gov = new QualityGovernor(tier, { setDprScale: (m) => renderer.setPixelRatio(Math.min(window.devicePixelRatio, tier.dprCap * m)) }, renderer);`,
+      `// per frame: gov.frame(deltaMs); skybox: loadTextureWithFallback(SKYBOX_URL, tier, (u) => loader.loadAsync(u))`
+    ]
+  },
   touch: {
     code: [...TOUCH_KIT, NOTICE],
     assets: [],
@@ -13678,7 +14019,10 @@ async function runExplore(opts) {
     const meta = [
       p.categories.join(", "),
       p.license ?? "",
-      p.sourceAuthor ? `originally by ${p.sourceAuthor}` : ""
+      p.sourceAuthor ? `originally by ${p.sourceAuthor}` : "",
+      // Reuse signal for mobile-targeted games: cloning a desktop-only/heavy
+      // system into a phone game imports its memory profile too.
+      p.mobileReadiness && p.mobileReadiness.state !== "unknown" ? `[mobile: ${p.mobileReadiness.state}]` : ""
     ].filter(Boolean).join(" \xB7 ");
     log.plain(`${c.bold(`${i + 1}. ${p.title}`)} \u2014 ${meta}`);
     if (p.description) log.plain(`   ${p.description.slice(0, 160)}`);
@@ -14671,11 +15015,13 @@ ${c.bold("Usage")}
                                      enqueued (done/running/queued/failed) \u2014 a single
                                      API refresh, never blocks, never bills.
   genex controller <type> [--force]  Install a bundled controller
-                                     (character|car|drone|touch|networked-physics)
+                                     (character|car|drone|touch|networked-physics|quality)
                                      into src/controllers (+ assets into public/assets).
                                      "touch" = the standalone mobile touch kit (joystick,
                                      buttons, drag zone, rotate overlay) for games
-                                     without a physics controller.
+                                     without a physics controller. "quality" = the
+                                     adaptive-quality kit (device tier, runtime governor,
+                                     per-tier asset rungs) every game wires at boot.
                                      Character defaults to the player's VRM + UAL pack.
   genex controller character --character <id>
                                      Install the Meshy-native controller variant.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.71.0",
+  "version": "0.74.0-dev.190",
   "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": {
@@ -42,6 +42,7 @@
   "devDependencies": {
     "@dimforge/rapier3d-compat": "^0.19.3",
     "@genex/meshy-animation-catalog": "workspace:*",
+    "@genex/mobile-scan": "workspace:*",
     "@genex-ai/multiplayer": "workspace:*",
     "@pixiv/three-vrm": "^3.5.4",
     "@types/pngjs": "^6.0.5",

package/templates/controllers/character/follow-camera.ts

@@ -674,13 +674,24 @@ export class FollowCamera {
 
   /**
    * Suspend or resume aim without disabling the camera. Call `setPaused(true)`
-   * when a menu opens or the player starts driving; call `setPaused(false)` INSIDE
-   * the closing click/keypress handler (browsers only grant re-lock from a user
-   * gesture). While paused, canvas clicks do NOT re-lock. No-op when aim is "off"
-   * or "unavailable".
+   * when a menu opens (the BOOT menu counts) or the player starts driving; call
+   * `setPaused(false)` INSIDE the closing click/keypress handler (browsers only
+   * grant re-lock from a user gesture). While paused, canvas clicks do NOT
+   * re-lock. No-op when aim is "off" or "unavailable".
+   *
+   * IDEMPOTENT: a same-value call is a complete no-op — safe to drive from a
+   * phase binding (`setPaused(phase !== "playing")`) that may fire repeatedly.
+   * This is load-bearing, not a nicety: an unguarded `setPaused(false)` per
+   * render frame re-requested the lock every frame, and because ANY DOM click
+   * (a Settings button) grants ~5s of transient activation, the next frame
+   * grabbed the pointer over the open menu. The resume re-lock therefore only
+   * fires on a real paused→unpaused transition; a game that never called
+   * `setPaused(true)` gets its re-lock from the canvas click (+ the cue), by
+   * design.
    */
   setPaused(paused: boolean): void {
     if (this._aimState === "off" || this._aimState === "unavailable") return;
+    if (paused === this._pausedByGame) return; // idempotent — same-value calls are no-ops
     this._pausedByGame = paused;
     if (paused) {
       this._retryArmed = false; // a menu/vehicle owns input now — no gesture retry

package/templates/controllers/character/vrm/vrm-loader.ts

@@ -4,9 +4,17 @@
 // orientation, and runs the standard perf cleanup — so the rest of the
 // controller treats every avatar (VRM 0.x or 1.0) identically.
 //
+// Mobile-readiness: everyone in a Genex room renders the SAME avatar file, so
+// this module caches per URL — the file downloads once (loadVrm), and remote
+// players should use loadVrmClone, which shares one set of GPU geometry +
+// textures across N remotes (~1 avatar of VRAM instead of N). Before this,
+// each remote re-downloaded AND re-parsed the VRM into duplicate GPU memory —
+// a real jetsam contributor at high player counts.
+//
 // Needs `npm i @pixiv/three-vrm` (peer of three, which the scaffold already has).
 import * as THREE from "three";
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import * as SkeletonUtils from "three/addons/utils/SkeletonUtils.js";
 import { VRMLoaderPlugin, VRMUtils } from "@pixiv/three-vrm";
 import type { VRM } from "@pixiv/three-vrm";
 
@@ -17,28 +25,83 @@ export interface LoadedVrm {
   vrm: VRM;
 }
 
-/**
- * Load a `.vrm` and return its scene + VRM instance, ready to animate.
- *
- * `VRMUtils.rotateVRM0` bakes the VRM 0.x 180° flip into BOTH the model and its
- * humanoid rig, so the avatar faces -Z (three's forward, same as every other
- * model) and the UAL retargeter (vrm-retarget.ts) needs no per-version handling.
- */
-export async function loadVrm(url: string): Promise<LoadedVrm> {
+// One network fetch + decode per URL, however many avatars spawn.
+const bufferCache = new Map<string, Promise<ArrayBuffer>>();
+// One PARSED base VRM per URL — the clone source for remote players.
+const baseCache = new Map<string, Promise<LoadedVrm>>();
+
+function fetchVrmBuffer(url: string): Promise<ArrayBuffer> {
+  let cached = bufferCache.get(url);
+  if (!cached) {
+    cached = fetch(url).then((r) => {
+      if (!r.ok) throw new Error(`VRM fetch failed: ${r.status} ${url}`);
+      return r.arrayBuffer();
+    });
+    cached.catch(() => bufferCache.delete(url)); // failed fetches retry next call
+    bufferCache.set(url, cached);
+  }
+  return cached;
+}
+
+async function parseVrm(url: string): Promise<LoadedVrm> {
   const loader = new GLTFLoader();
   loader.register((parser) => new VRMLoaderPlugin(parser));
 
-  const gltf = await loader.loadAsync(url);
+  const buffer = await fetchVrmBuffer(url);
+  const gltf = await loader.parseAsync(buffer.slice(0), url);
   const vrm = gltf.userData.vrm as VRM;
 
   VRMUtils.rotateVRM0(vrm);
   VRMUtils.removeUnnecessaryVertices(vrm.scene);
   VRMUtils.combineSkeletons(vrm.scene);
 
-  // Skinned avatars can pop out at glancing camera angles otherwise.
+  // Skinned meshes can pop out at glancing camera angles (animated bounds) —
+  // but ONLY skinned meshes need the exemption. Blanket-disabling culling on
+  // every node made ALL loaded avatars draw every frame regardless of
+  // visibility, a per-remote GPU-time tax on phones.
   vrm.scene.traverse((obj) => {
-    obj.frustumCulled = false;
+    if ((obj as THREE.SkinnedMesh).isSkinnedMesh) obj.frustumCulled = false;
   });
 
   return { scene: vrm.scene, vrm };
 }
+
+/**
+ * Load a `.vrm` and return its scene + VRM instance, ready to animate.
+ * Full-fidelity (spring bones, humanoid) — the LOCAL player's avatar, or any
+ * avatar you retarget clips onto. The file itself is fetched once per URL.
+ *
+ * `VRMUtils.rotateVRM0` bakes the VRM 0.x 180° flip into BOTH the model and its
+ * humanoid rig, so the avatar faces -Z (three's forward, same as every other
+ * model) and the UAL retargeter (vrm-retarget.ts) needs no per-version handling.
+ */
+export async function loadVrm(url: string): Promise<LoadedVrm> {
+  return parseVrm(url);
+}
+
+/**
+ * Visual-only clone for REMOTE players: parses the URL once (cached), then
+ * returns `SkeletonUtils.clone` of the base — its own bones and mixer target,
+ * but SHARED geometry, materials, and textures (N remotes ≈ 1 avatar of GPU
+ * memory). Trade-off, on purpose: clones carry no VRM instance, so spring
+ * bones (hair/cloth sway) don't simulate on remotes — retarget animation clips
+ * ONCE on the base (`(await loadVrmClone.base(url)).vrm`, or your local
+ * loadVrm result when it's the same file) and play them on each clone's own
+ * `THREE.AnimationMixer`; track names match by construction.
+ */
+export async function loadVrmClone(url: string): Promise<{ scene: THREE.Group }> {
+  const base = await loadVrmCloneBase(url);
+  return { scene: SkeletonUtils.clone(base.scene) as THREE.Group };
+}
+
+/** The shared parsed base behind loadVrmClone — retarget clips against ITS vrm. */
+export function loadVrmCloneBase(url: string): Promise<LoadedVrm> {
+  let cached = baseCache.get(url);
+  if (!cached) {
+    cached = parseVrm(url);
+    cached.catch(() => baseCache.delete(url));
+    baseCache.set(url, cached);
+  }
+  return cached;
+}
+loadVrmClone.base = loadVrmCloneBase;