@genex-ai/cli-demo 0.80.0-dev.211 → 0.81.0-dev.214

package/dist/index.js

@@ -1109,7 +1109,7 @@ async function writeProject(meta, cwd = process.cwd()) {
 import fs7 from "fs/promises";
 import path7 from "path";
 var DEFAULT_DASHBOARD_ORIGIN = new URL(DEFAULT_AUTH_URL).origin;
-function renderGenexConfig() {
+function renderGenexConfig(slug) {
   return `// src/genex.config.ts \u2014 written by \`genex init\`. DO NOT hardcode URLs here.
 //
 // Build once, run anywhere. The games host injects the serving environment into
@@ -1117,14 +1117,21 @@ function renderGenexConfig() {
 // bundle), so ONE build is correct on every stand \u2014 promoting a game is a copy,
 // never a rebuild, and an immutable bundle can never pin the wrong environment.
 // Vite env still overrides, but is loaded ONLY by \`npm run dev\`:
-//   .env                    -> VITE_GENEX_SLUG (this game's identity; committed)
+//   .env                    -> VITE_GENEX_SLUG (local override for \`npm run dev\`)
 //   .env.development.local  -> local-stack URL overrides (dev mode ONLY; gitignored)
+//
+// The slug is ALSO baked as a literal below, on purpose: \`genex preview/publish\`
+// excludes .env from the source push (it's treated as a secret file), so a clone of
+// the published repo has no .env. Reading the slug from env ALONE would then build
+// \`slug: undefined\` -> the guest-session call posts {} -> 400 -> guests can't play a
+// remixed game. The literal keeps a bare clone rebuilding into a working game; the
+// env var still wins locally.
 const injected: { apiUrl?: string; dashboardOrigins?: string[] } =
   (typeof window !== "undefined" && (window as { __GENEX__?: unknown }).__GENEX__) as
     | { apiUrl?: string; dashboardOrigins?: string[] }
     | undefined ?? {};
 export const GENEX = {
-  slug: import.meta.env.VITE_GENEX_SLUG as string,
+  slug: (import.meta.env.VITE_GENEX_SLUG as string | undefined) ?? ${JSON.stringify(slug)},
   apiUrl:
     (import.meta.env.VITE_GENEX_API_URL as string | undefined) ??
     injected.apiUrl ??
@@ -1170,7 +1177,7 @@ async function writeIfAbsent(file, content, log) {
 }
 async function writeGameConfigFiles(meta, log, cwd = process.cwd()) {
   await fs7.mkdir(path7.join(cwd, "src"), { recursive: true });
-  await writeIfAbsent(path7.join(cwd, "src", "genex.config.ts"), renderGenexConfig(), log);
+  await writeIfAbsent(path7.join(cwd, "src", "genex.config.ts"), renderGenexConfig(meta.slug), log);
   await writeIfAbsent(path7.join(cwd, ".env"), renderSlugEnv(meta.slug), log);
   const overrides = renderDevOverrides(meta);
   if (overrides) {
@@ -2999,11 +3006,29 @@ async function walkFiles(dir) {
   return out;
 }
 async function collectUiAuditFindings(assetDir, srcDir, cwd = process.cwd()) {
+  const viewportFindings = [];
+  try {
+    const indexHtml = await fs10.readFile(path10.join(cwd, "index.html"), "utf8");
+    if (!/<meta[^>]+name=["']viewport["']/i.test(indexHtml)) {
+      viewportFindings.push({
+        kind: "viewport-meta",
+        message: `index.html has no viewport meta \u2014 phones will render a zoomed-out desktop canvas. Add: <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">`
+      });
+    } else if (!/viewport-fit\s*=/i.test(indexHtml)) {
+      viewportFindings.push({
+        kind: "viewport-meta",
+        message: `index.html's viewport meta lacks viewport-fit=cover \u2014 env(safe-area-inset-*) (touch-kit widget offsets) is 0 without it. Append ", viewport-fit=cover" to the meta's content.`
+      });
+    }
+  } catch {
+  }
   const absAssets = path10.resolve(cwd, assetDir);
   try {
-    if (!(await fs10.stat(absAssets)).isDirectory()) return null;
+    if (!(await fs10.stat(absAssets)).isDirectory()) {
+      return viewportFindings.length > 0 ? viewportFindings : null;
+    }
   } catch {
-    return null;
+    return viewportFindings.length > 0 ? viewportFindings : null;
   }
   const srcFiles = (await walkFiles(path10.resolve(cwd, srcDir))).filter(
     (p) => AUDIT_SRC_EXTS.has(path10.extname(p).toLowerCase())
@@ -3023,7 +3048,7 @@ async function collectUiAuditFindings(assetDir, srcDir, cwd = process.cwd()) {
     }
   }
   const referenced = (basename) => sources.some((s) => s.text.includes(basename));
-  const findings = [];
+  const findings = [...viewportFindings];
   const assetFiles = await walkFiles(absAssets);
   const maskReported = /* @__PURE__ */ new Set();
   for (const p of assetFiles) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.80.0-dev.211",
+  "version": "0.81.0-dev.214",
   "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/controllers/character/character-controller.ts

@@ -88,6 +88,36 @@ type ResolvedMovementInput = {
 /** Crouch input interpretation — see {@link CharacterControllerOptions.crouchMode}. */
 export type CrouchMode = "toggle" | "hold";
 
+/**
+ * The over-the-network snapshot of a character. Publish it every fixed tick with
+ * `room.me.set(character.netState())`; apply a remote's smoothed copy with
+ * `applyNetState(remoteObject, players.get(id).state)`.
+ *
+ * `y` is the SETTLED body height while grounded: the float-spring's idle up/down
+ * oscillation is removed, so a standing remote player does NOT bob in place.
+ * Publish this — never `currPos`, which is the raw physics capsule and bobs on
+ * its suspension spring. Numbers are rounded to ~cm; rotation is a 4-number
+ * quaternion (never a scalar yaw — that lerps the long way across ±π). The six
+ * booleans drive a remote's CharacterAnimations.
+ */
+export interface NetState {
+  x: number;
+  y: number;
+  z: number;
+  q: [number, number, number, number];
+  onGround: boolean;
+  falling: boolean;
+  moving: boolean;
+  running: boolean;
+  jumping: boolean;
+  crouching: boolean;
+}
+
+/** Round a networked number to ~cm precision (raw floats serialize as 17-digit JSON). */
+function roundNet(v: number): number {
+  return Math.round(v * 100) / 100;
+}
+
 export interface CharacterRecoveryEvent {
   reason: "non-finite" | "out-of-bounds";
   position: { x: number; y: number; z: number };
@@ -484,6 +514,8 @@ export class CharacterController {
   private slideFrictionCoef = 0;
   private standingPointFriction = 0;
   private readonly standingPoint = new THREE.Vector3();
+  /** Scratch for {@link netPos} — the float-oscillation-free networked position. */
+  private readonly _netPos = new THREE.Vector3();
   private readonly characterMassImpulse = new THREE.Vector3();
   private readonly movingObjectPosition = new THREE.Vector3();
   private readonly movingObjectVelocity = new THREE.Vector3();
@@ -648,6 +680,29 @@ export class CharacterController {
   get currPos(): THREE.Vector3 {
     return this.currentPos;
   }
+  /**
+   * Body position to PUBLISH over the network. Identical to {@link currPos} while
+   * airborne (jump/fall arcs must survive), but while grounded the up-axis
+   * component is snapped to the SETTLED float height above the ground — removing
+   * the suspension-spring idle oscillation that otherwise makes a standing remote
+   * player bob up and down. Publish this (via {@link netState}), never `currPos`.
+   * Live vector — copy it if you keep it. Follows custom gravity (up = bodyYAxis).
+   */
+  get netPos(): THREE.Vector3 {
+    this._netPos.copy(this.currentPos);
+    if (this._isOnGround) {
+      // currPos bobs because the float spring holds the capsule a VARYING gap
+      // above the ground each step. standingPoint is the STATIC ground contact;
+      // the settled center→ground gap (along up) is groundFloatingDistance −
+      // rayOriginOffset. Shift the up component by (settled − current) so the
+      // published height is the settled one, not the oscillating one.
+      const gapNow =
+        this._netPos.dot(this.characterYAxis) - this.standingPoint.dot(this.characterYAxis);
+      const gapSettled = this.groundFloatingDistance - this.rayOriginOffset;
+      this._netPos.addScaledVector(this.characterYAxis, gapSettled - gapNow);
+    }
+    return this._netPos;
+  }
   /** Body rotation (this step). Live quaternion. */
   get currQuat(): THREE.Quaternion {
     return this.currentQuat;
@@ -799,6 +854,32 @@ export class CharacterController {
   // Public methods
   // ────────────────────────────────────────────────────────────────────────
 
+  /**
+   * The snapshot to PUBLISH for multiplayer, in one call:
+   * `room.me.set(character.netState())` — on the fixed 10–20 Hz tick, never per
+   * frame. Position is {@link netPos} (float-oscillation-free, so remotes never
+   * bob), rotation is a 4-number quaternion, plus the six animation booleans a
+   * remote feeds to its own CharacterAnimations. Numbers are rounded to ~cm to
+   * keep the wire small. This is the ONLY position you should network — reaching
+   * for `currPos` here is the classic "standing remote player bobs" bug.
+   */
+  netState(): NetState {
+    const p = this.netPos;
+    const q = this.currentQuat;
+    return {
+      x: roundNet(p.x),
+      y: roundNet(p.y),
+      z: roundNet(p.z),
+      q: [roundNet(q.x), roundNet(q.y), roundNet(q.z), roundNet(q.w)],
+      onGround: this.isOnGround,
+      falling: this.isFalling,
+      moving: this.isMoving,
+      running: this.runActive,
+      jumping: this.jumpActive,
+      crouching: this.crouchActive,
+    };
+  }
+
   /**
    * Merge movement intents into the input state. Only fields you pass are
    * changed, so different input sources (keyboard, joystick, buttons) can each
@@ -1927,3 +2008,19 @@ export class CharacterController {
     d.velocityArrow.setLength(this._relativeVel.length() / this.targetMoveSpeed(this._runActive));
   }
 }
+
+/**
+ * Apply a remote player's networked snapshot to their VISUAL object (a plain
+ * Object3D — never a CharacterController; remotes are interpolated visuals, not
+ * simulated). Read the SMOOTHED copy the SDK exposes so motion glides:
+ * `applyNetState(remoteObject, players.get(id).state)`. The six booleans
+ * (`s.onGround`, `s.falling`, …) feed that remote's CharacterAnimations
+ * separately — see the character-controller skill's multiplayer rule.
+ */
+export function applyNetState(target: THREE.Object3D, s: NetState): void {
+  target.position.set(s.x, s.y, s.z);
+  // normalize: netState() rounds each quaternion component to ~cm precision, so the 4-tuple is
+  // almost never exactly unit — Three.js bakes a non-unit quaternion straight into the matrix as a
+  // small (~0.4%) scale that shifts as the remote turns. One call keeps remotes at true scale.
+  target.quaternion.set(s.q[0], s.q[1], s.q[2], s.q[3]).normalize();
+}

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

@@ -615,7 +615,8 @@ after a bad single costs the whole chain).
   Use the returned hex verbatim for the DOM text over that region.
 - `npx genex ui trim --in <png>` — crop to alpha content + report real dims.
 - `npx genex ui audit [--dir public/assets/hud] [--src src]` — the mechanical
-  wiring scan (unreferenced sprites/masks, naive %-fill patterns); warn-only,
+  wiring scan (unreferenced sprites/masks, naive %-fill patterns, and a
+  missing/incomplete mobile viewport meta in the root `index.html`); warn-only,
   `--strict` exits 1 on findings.
 
 ## Troubleshooting

package/templates/skills/genex-threejs-character-controller/SKILL.md

@@ -318,11 +318,16 @@ it. Simulating remote players' physics locally guarantees divergence — every
 client would compute a different world. Never render every remote with your
 own avatar file: players picked their looks, show them.
 
-- Publish your own `currPos` + `currQuat` as a four-number quaternion on the fixed 10–20 Hz tick,
-  not per frame. Never reduce multiplayer rotation to scalar yaw.
-- To animate remotes, sync the six animation booleans (`isOnGround`,
-  `isFalling`, `isMoving`, `runActive`, `jumpActive`, `crouchActive`) and feed
-  them to a per-remote `CharacterAnimations` — see the animations reference.
+- **Publish `character.netState()`** on the fixed 10–20 Hz tick (never per frame):
+  `room.me.set(character.netState())`. It bundles the network-safe position, a four-number
+  quaternion, and the six animation booleans in one call. It uses `netPos`, **not** `currPos` —
+  `currPos` is the raw physics capsule whose Y bobs on the float-suspension spring, so publishing
+  it makes a *standing* remote player visibly bob up and down. `netState()` snaps the grounded Y to
+  the settled height (raw while airborne, so jumps still arc). Never reduce rotation to a scalar yaw.
+- On each remote, apply the SDK's **smoothed** copy with
+  `applyNetState(remoteObject, players.get(id).state)` (sets position + rotation), and feed the same
+  six booleans (`onGround`, `falling`, `moving`, `running`, `jumping`, `crouching`) to that remote's
+  `CharacterAnimations` — see the animations reference. Never publish `currPos` directly.
 - Only the owning client runs `MotionActionDriver`. Remotes play the same
   one-shot event while following smoothed owner-authored position/rotation;
   their animation mixer never moves them through the world.

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -620,6 +620,12 @@ than silently disappearing. The budget math that matters:
    `players.get(id).state` directly (already smoothed); every object from `objects.get(id).state`.
 4. **Create-or-reuse one mesh per id**; remove a player's mesh on `'leave'`.
 
+> **Physics character?** If your player is the `genex controller character` capsule, do NOT
+> hand-build the state from the body position — publish `room.me.set(character.netState())` and
+> apply remotes with `applyNetState(mesh, players.get(id).state)`. The controller's raw `currPos.y`
+> bobs on its float-suspension spring; `netState()` publishes a settled ground Y so a standing remote
+> doesn't bob. See `$genex-threejs-character-controller` → "Multiplayer rule".
+
 ## Rotation: sync a quaternion, not an angle
 
 Send rotation as a 4-number quaternion `q: mesh.quaternion.toArray()`; on the remote do

package/templates/skills/genex-threejs-touch-controls/SKILL.md

@@ -149,6 +149,13 @@ z-order stays: drag zone (5) under joystick/buttons (10) under pause menus.
 - **Safe-area insets are built in** — default positions clear notches and the
   home indicator. If you position widgets yourself near screen edges, keep
   `env(safe-area-inset-*)` in the calc.
+- **Viewport meta is a prerequisite** — every `env(safe-area-inset-*)` value is
+  silently **0** unless the page's viewport meta carries `viewport-fit=cover`.
+  Ship `<meta name="viewport" content="width=device-width, initial-scale=1,
+  viewport-fit=cover">` in the game's own `index.html`: the platform edge-injects
+  a default for published games, but the local dev server doesn't go through
+  that edge — without your own meta, widgets hug the notch in local testing
+  and look different from production.
 - **The drag zone swallows its touches** — taps inside it don't reach the
   canvas. If the game also needs taps there (tap to shoot), read them from the
   zone (`onChange` + a small-movement threshold) or shrink the zone.