@genex-ai/cli-demo 0.26.0 → 0.27.0

package/dist/index.js

@@ -598,7 +598,7 @@ async function createDraftProject(opts) {
           "Content-Type": "application/json",
           Authorization: `Bearer ${token}`
         },
-        body: JSON.stringify({ name })
+        body: JSON.stringify(opts.repoUrl ? { name, repoUrl: opts.repoUrl } : { name })
       });
     } catch (err) {
       log.warn(`Couldn't reach the API at ${apiUrl} to create the project.`);
@@ -924,15 +924,20 @@ async function runInit(opts) {
     apiUrl,
     token,
     name: projectName,
+    repoUrl: opts.repo?.trim() || void 0,
     colyseusUrl,
     dashboardUrl: authBaseUrl,
     log
   });
-  if (meta) {
-    const { path: metaPath } = await writeProject(meta);
-    log.dim(`  saved ${c.cyan(metaPath)}`);
-    await writeGameConfigFiles(meta, log);
+  if (!meta) {
+    log.plain("");
+    log.warn("Setup finished, but creating your game failed \u2014 fix the error above and re-run `genex init`.");
+    process.exitCode = 1;
+    return;
   }
+  const { path: metaPath } = await writeProject(meta);
+  log.dim(`  saved ${c.cyan(metaPath)}`);
+  await writeGameConfigFiles(meta, log);
   log.plain("");
   log.success("All set. \u{1F680}");
 }
@@ -1259,12 +1264,13 @@ async function callPublish(ctx, commit, opts, log) {
 }
 async function pushSource(cwd, ctx, log) {
   const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+  const target = await fetchPushUrl(ctx, log);
+  if (!target) return false;
+  const { pushUrl, managed } = target;
   const failed = () => {
     log.error("Couldn't save your game's source \u2014 please try again.");
     return false;
   };
-  const pushUrl = await fetchPushUrl(ctx, log);
-  if (!pushUrl) return false;
   const gitDir = await fs9.mkdtemp(path10.join(os2.tmpdir(), "genex-source-"));
   const base = { GIT_DIR: gitDir };
   const ident = {
@@ -1277,7 +1283,7 @@ async function pushSource(cwd, ctx, log) {
     if ((await run("git", ["init", "-q"], base)).code !== 0) return failed();
     await fs9.writeFile(
       path10.join(gitDir, "info", "exclude"),
-      // .env* are secrets — the managed repo is public. `!` keeps the non-secret template.
+      // .env* are secrets — never publish them; `!` keeps the non-secret template.
       ["node_modules/", "dist/", ".git/", ".genex/", ".env", ".env.*", "!.env.example", ""].join("\n")
     );
     const env = { ...base, GIT_WORK_TREE: cwd, GIT_INDEX_FILE: path10.join(gitDir, "index-source") };
@@ -1290,7 +1296,14 @@ async function pushSource(cwd, ctx, log) {
     const commit = (await run("git", ["commit-tree", tree, "-m", "source"], { ...base, ...ident })).out.trim();
     await run("git", ["update-ref", "refs/heads/main", commit], base);
     const push = await run("git", ["push", "-q", pushUrl, "+refs/heads/main:main"], base);
-    return push.code === 0 ? true : failed();
+    if (push.code === 0) return true;
+    if (!managed) {
+      log.error(
+        "Couldn't push to your repo. Check that you have push access (SSH key or git credentials) and that the repo exists."
+      );
+      return false;
+    }
+    return failed();
   } catch {
     return failed();
   } finally {
@@ -1322,7 +1335,7 @@ async function fetchPushUrl(ctx, log) {
     log.error("The API didn't return a push URL.");
     return null;
   }
-  return data.pushUrl;
+  return { pushUrl: data.pushUrl, managed: data.managed !== false };
 }
 async function isDir2(p) {
   try {
@@ -2055,6 +2068,8 @@ ${c.bold("Options for the generators (`model` `skybox` `sfx` `texture`)")}
 ${c.bold("Options for `init`")}
   <name>               Project name (positional; default: current directory name).
   --name <name>        Same as the positional name.
+  --repo <url>         Host the source in your own git repo (https/ssh) instead of a managed one;
+                       preview/publish push there with your git credentials.
   --agents <list>      Agents to install skills for (claude,codex,cursor; default: auto-detect).
   --dir <path>         Single destination workspace (overrides --agents).
   --env <path>         Token env file (default: ~/.genex/env).
@@ -2136,6 +2151,7 @@ function parseArgs(argv) {
     "--colyseus-url",
     "--agents",
     "--name",
+    "--repo",
     "--title",
     "--description",
     "--categories",
@@ -2235,6 +2251,9 @@ function applyValueFlag(options, flag, value) {
     case "--name":
       options.name = value;
       break;
+    case "--repo":
+      options.repo = value;
+      break;
     case "--title":
       options.title = value;
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

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

@@ -34,9 +34,12 @@ example, the shared-object/ball code, rotation, and host usage. Read
 ## Install
 
 ```bash
-npm i @genex-ai/multiplayer
+npm i @genex-ai/multiplayer@^0.8.0
 ```
 
+> Pin `@^0.8.0` (not a bare `npm i`): `inputs`/`onHostTick`, auto-reconnect, and the `reconnecting`
+> events this skill relies on landed in 0.8. An older resolve would throw `room.onHostTick is not a function` at runtime.
+
 This skill targets `@genex-ai/multiplayer` **≥ 0.8.0** (`objects`/`host` since 0.4; `matchmake()` since 0.5; presets + `score()`/`finish()` since 0.6; `createPrivate()`/`joinPrivate()` since 0.7; matchmake auto-retry + `retry()` since 0.7.1; auto-reconnect + `inputs`/`onHostTick` since 0.8).
 
 ## Trust model (say it plainly in your game's copy)
@@ -148,6 +151,7 @@ room.on("reconnecting", ({ attempt }) => showOverlay(`Reconnecting… (${attempt
 room.on("reconnected", () => hideOverlay());
 room.on("disconnect", (code) => {
   // Terminal: server restart, revoked session, or the link never came back.
+  if (code === 4409) flushSaves(); // replaced by this player's OTHER tab/device — flush now
   // To play again, read a FRESH token and connect() anew — never reuse the old auth object.
   showMenu("Connection lost");
 });
@@ -160,7 +164,9 @@ glide on; don't tear the scene down. A deliberate `room.leave()` never auto-reco
 **One seat per player (enforced server-side):** joining the same game again — a second tab,
 another device, or a page reload — instantly evicts the previous session (it gets
 `disconnect`, code 4409). You never need to handle "the same player twice" and a reload
-never leaves a ghost avatar behind.
+never leaves a ghost avatar behind. If the evicted tab was the host and holds unsaved world
+state, flush it in the `disconnect` handler (code 4409, above): that tab is still alive, so an
+async `saveWorldState` completes — otherwise a debounced save in flight is lost.
 
 ## Which channel for which data
 
@@ -187,7 +193,10 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
   `{ id, name, state, stateRaw }`: `state` is auto-smoothed (remotes) / live (you); `stateRaw` is
   the raw latest (hit-tests, discrete values).
 - `room.objects` — shared objects nobody owns until claimed (a ball, an NPC):
-  - `claim(id)` — take ownership (last claim wins; call on kick/contact).
+  - `claim(id)` — take ownership (last claim wins; call on kick/contact). Claiming is optimistic:
+    you own it locally the instant you call it, but if another player claimed the same tick the
+    server's last-claim-wins verdict can revoke you — a `set()` you sent before losing the race is
+    dropped. For contested objects, keep publishing while `isMine` stays true, not just once.
   - `set(id, state)` — publish it (only lands while you own it; full flat object each call).
   - `get(id)` → `{ id, owner, isMine, state, stateRaw }` or `undefined`. `state` is auto-smoothed
     (or live if `isMine`); `stateRaw` is the raw latest.
@@ -212,6 +221,24 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
 - `room.onHostTick(hz, cb)` — run a fixed simulation tick only while you are the host
   (auto-starts/stops across host migration). Returns a disposer.
 
+## Your message budget (every publish is one relay message)
+
+Every `me.set`, `objects.set`, `objects.claim`, `send`, and `inputs.send` costs **one relay
+message**, and the relay caps each connection at **~120 messages/second sustained** (drops
+above that — you'll see a console warning "the relay dropped N of your messages"). The
+budget math that matters:
+
+- Your own state (`me.set`) at 15 Hz + ONE driven/owned moving object at 15 Hz = 30/s. Fine.
+- The pattern that blows the budget: **republishing IDLE objects every tick.** A host that
+  owns several parked vehicles/props must NOT `objects.set` each of them at full tick rate —
+  publish an object **when it changed**, plus a low-rate keepalive (~1–2 Hz) so late joiners
+  converge. Unchanged pose ⇒ no message.
+- If you see the drop warning, count your sends-per-tick: streams × tick-rate must stay well
+  under 120/s with headroom for claims and events.
+- Over budget, the relay spreads the loss across ALL your streams (everything gets choppy at
+  once) rather than freezing one — so a single stuttering object is your cue to check the whole
+  budget, not just that object. The warning is the signal; don't design at the edge of the cap.
+
 ## The loop you must build (input → local → tick → render)
 
 1. **Input mutates a local object only** (`me.x += …`). Never network on keypress.
@@ -259,7 +286,10 @@ details are in [references/realtime-patterns.md](references/realtime-patterns.md
 ## Host authority (scores, rounds, enemies)
 
 One client is the `host`. Let *only* the host write agreed state and simulate shared enemies, so
-there's a single source of truth:
+there's a single source of truth. **But: a host is only the authority for objects it OWNS.**
+If another player owns/drives an object (their claim landed), the host renders it from the
+stream like everyone else — a host branch that pins "its" objects to a local pose without
+checking `owner`/`isMine` shows every other player's driving as a frozen object:
 
 ```ts
 if (room.isHost) room.shared.set("round", nextRound);   // only the host advances the round
@@ -364,10 +394,12 @@ host-driven saving works as long as ANY account is in the room.
 
 ## Checklist
 
-- [ ] `npm i @genex-ai/multiplayer` (≥ 0.8.0 — auto-reconnect, `inputs`, `onHostTick`); config wired into the build.
+- [ ] `npm i @genex-ai/multiplayer@^0.8.0` (auto-reconnect, `inputs`, `onHostTick` — pin `^0.8.0`, a bare install can resolve older); config wired into the build.
 - [ ] `reconnecting`/`reconnected`/`disconnect` render an overlay (don't tear the scene down).
 - [ ] Numbers rounded (~2 decimals) before `me.set`/`objects.set`.
 - [ ] Contested (sustained-contact) objects use the host-physics pattern, not claim-on-touch.
+- [ ] Idle/unchanged objects republish at ≤2 Hz keepalive, never every tick (message budget).
+- [ ] Host renders objects OWNED BY OTHERS from the stream (authority follows ownership).
 - [ ] `connect()` runs AFTER `await waitForPlayer()` (never `waitForAuth()` — guests would
       hang) and passes `auth: getColyseusAuth()!` (the relay rejects tokenless joins —
       see `genex-threejs-embed-auth`).

package/templates/skills/genex-threejs-multiplayer/references/host-physics.md

@@ -81,29 +81,53 @@ The `genex controller` controllers are **local-only physics** — each player si
 OWN rig (self-authoritative, zero latency). Networking them is publish-and-playback, never
 remote simulation:
 
+The vendored controllers expose their pose as `currPos` (a `THREE.Vector3`) and `currQuat` (a
+`THREE.Quaternion`) — **not** `.position` / `.quaternion` — plus boolean state getters. Character
+animation is driven by **five booleans**, not a single enum; publish the booleans and let remotes
+reconstruct the animation. There is **no** `rig.animState`, no `remoteAnimator.play(...)`, and no
+vehicle `wheelSpinPhase` getter.
+
 ```ts
-// You: after your controller's update, on the fixed tick (~15Hz)
+// You: after your controller's update(), on the fixed tick (~15Hz).
+const p = character.currPos;   // THREE.Vector3   (Vehicle/Drone: same getters)
+const q = character.currQuat;  // THREE.Quaternion
 room.me.set({
-  x: r2(rig.position.x), y: r2(rig.position.y), z: r2(rig.position.z),
-  q: rig.quaternion.toArray().map(r2),      // quaternion — never a scalar yaw
-  anim: rig.animState,                       // discrete → remotes read via stateRaw
-  // vehicle extras: steer: r2(steerAngle), wheel: r2(wheelSpinPhase)
+  x: r2(p.x), y: r2(p.y), z: r2(p.z),
+  q: [r2(q.x), r2(q.y), r2(q.z), r2(q.w)],   // quaternion array — never a scalar yaw
+  // character animation = 5 booleans (the CharacterController exposes each as a getter):
+  g: character.isOnGround, f: character.isFalling, m: character.isMoving,
+  r: character.runActive,  j: character.jumpActive,
 });
 
-// Remote players: drive a VISUAL-ONLY rig from smoothed state — no Rapier body, no
-// controller instance for remotes. Wheels/limbs animate from the published params.
-const p = room.players.get(id)!;
-remoteMesh.position.set(p.state.x, p.state.y, p.state.z);
-remoteMesh.quaternion.fromArray(p.state.q);
-remoteAnimator.play(p.stateRaw.anim);        // discrete values from stateRaw
+// Remote players: a VISUAL-ONLY avatar — NO Rapier body, NO controller instance for remotes.
+// Position/rotation from smoothed state; animation from the synced flags via the avatar's own
+// update(flags, dt). The character-controller skill's animations reference owns the flag set.
+const pl = room.players.get(id)!;
+remoteAvatar.group.position.set(pl.state.x, pl.state.y, pl.state.z);
+remoteAvatar.group.quaternion.fromArray(pl.state.q);
+const raw = pl.stateRaw; // discrete flags: read RAW, never smoothed
+remoteAvatar.update(
+  { isOnGround: !!raw.g, isFalling: !!raw.f, isMoving: !!raw.m, runActive: !!raw.r, jumpActive: !!raw.j },
+  dt,
+);
 ```
 
 What to publish per controller:
 
-- **character**: `x/y/z`, `q`, `anim` (state-machine id), optionally `speed` for blend trees.
-- **vehicle**: body `x/y/z` + `q`, `steer` angle, a `wheel` spin phase (remotes spin wheels
-  procedurally — never sync per-wheel transforms).
-- **drone**: `x/y/z`, `q`, rotor throttle if the visual needs it.
+- **character**: `currPos` → `x/y/z`, `currQuat` → `q`, and the five booleans above
+  (`isOnGround`/`isFalling`/`isMoving`/`runActive`/`jumpActive`). Remotes rebuild the animation
+  with `avatar.update(flags, dt)` — see the `genex-threejs-character-controller` animations
+  reference for the flag set (single source of truth; don't invent a `play(anim)` call).
+- **vehicle**: body `currPos` → `x/y/z` + `currQuat` → `q`. For visible steering, publish the
+  front wheel's `car.wheels.get(frontWheelId)?.steerAngle`; spin the wheels on remotes
+  procedurally from the body's speed (position delta) — there is no spin-phase getter, and you
+  never sync per-wheel transforms.
+- **drone**: `currPos` → `x/y/z`, `currQuat` → `q`, and `drone.hoverThrottle` if the rotor visual
+  needs it. Remote rotor spin is procedural, like vehicle wheels.
+
+> Remote **visuals** for vehicle wheels / drone rotors are author-built (a spinning mesh you drive
+> from synced speed/throttle) — the controllers build those internally from a live Rapier body,
+> which remotes don't have. Only the body pose + the flags/params above come over the wire.
 
 Player-vs-player physical contact (bumping cars) stays approximate at this tier — each
 client is authoritative over itself, so contacts are cosmetic. If a game's core loop IS