@genex-ai/cli-demo 0.28.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.28.0",
+  "version": "0.30.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-getting-started/SKILL.md

@@ -69,6 +69,24 @@ keep its renderer, structure, and conventions — extend, don't rebuild.
 Running `genex init` in such a folder only wires identity/publishing and
 refreshes the genex-owned skills; the game's own files are never touched.
 
+## Hosting your game's source
+
+By default `genex init` creates a **managed repo** for your source — you push to
+it over HTTPS with a token the API mints per push, so it works from any device
+with no SSH key, and `preview`/`publish` save the source there automatically.
+
+To keep the source in **your own git repo** instead, pass it at init:
+
+```bash
+npx genex init my-game --repo https://git.example.com/you/my-game.git
+```
+
+Then `preview`/`publish` push the source to **your** repo using the git
+credentials `git push` already uses on this machine (https or ssh). Point it at a
+repo dedicated to this game — each publish overwrites its `main` with the current
+source. Without push access, publish stops with a clear error and nothing ships.
+The playable game is served by Genex either way.
+
 ## Publishing
 
 Before your first `genex preview`, the play URL (`https://<slug>.genex.technology/`)

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

@@ -40,7 +40,7 @@ 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).
+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; soft ownership handoff — claim-on-touch objects glide instead of teleporting — since 0.8.4).
 
 ## Trust model (say it plainly in your game's copy)
 
@@ -300,16 +300,22 @@ For host-simulated NPCs, the host claims and drives each enemy as an `object`; w
 leaves, its enemies are reassigned to the new host, which reads their `stateRaw` and keeps
 simulating. See the co-op recipe in [references/genre-recipes.md](references/genre-recipes.md).
 
-### Contested physics (two players pushing ONE thing) — host-authoritative
+### Pushable / contested physics — pick the tier
 
-Claim-on-touch is perfect for one-touch objects (kick a ball). It **breaks down under
-sustained contact** — two players pushing the same crate steal ownership back and forth and
-the crate judders. For contested objects, ONE simulation must own the contest: the **host**
-runs the physics for those objects; everyone else sends **inputs**
-(`room.inputs.send({ push })`), which the relay routes to the host only; the host applies
-them on `room.onHostTick(...)` and publishes results via `objects` (smooth for everyone).
-Full recipe — including surviving host migration and wiring the Rapier controllers —
-in [references/host-physics.md](references/host-physics.md).
+Claim-on-touch is the default for any **ownable** body — a ball, a box, a prop, a pickup — even when
+players take turns bumping it: whoever touches it owns + simulates it with real Rapier physics, and
+since `@genex-ai/multiplayer` 0.8.4 the ownership handoff **glides** (a soft handoff) instead of
+teleporting. Give it a Rapier proxy that is `dynamic` while you own it (your character shoves it through
+the solver) and a `kinematicPosition` follower of the smoothed `state` when you don't.
+
+Reserve **host-authoritative** for a genuine *simultaneous* contest — two players pushing ONE crate
+*against each other*, sumo, tug-of-war — where "whoever touched last owns it" is the wrong model. There
+one neutral simulation (the host) runs the physics; everyone else sends **inputs**
+(`room.inputs.send({ push })`), which the relay routes to the host only; the host applies them on
+`room.onHostTick(...)` and publishes results via `objects` (smooth for everyone).
+
+Both patterns — the claim-on-touch Rapier proxy and the host-authoritative contest, plus surviving host
+migration and wiring the vendored controllers — are in [references/host-physics.md](references/host-physics.md).
 
 ## Smoothness is felt, not seen — hand the feel to a human
 
@@ -397,7 +403,7 @@ host-driven saving works as long as ANY account is in the room.
 - [ ] `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.
+- [ ] Pushable/ownable objects (ball, box, prop) use claim-on-touch + a Rapier proxy (the soft handoff glides the handoff); only a genuine simultaneous tug-of-war (sumo) uses the host-authoritative pattern. See host-physics.md.
 - [ ] 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

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

@@ -1,22 +1,118 @@
-# Host-authoritative physics — contested objects + networked controllers
+# Networked physics — pushable/ownable objects, contested objects + controllers
 
-Two networking tiers exist for moving things, and picking the right one per object is the
+Three networking tiers exist for moving things, and picking the right one per object is the
 whole trick:
 
-| Object kind | Tier | Why |
+| Object kind | Tier | How |
 | --- | --- | --- |
-| One-touch (kick a ball, throw a crate once) | **claim-on-touch** (`objects.claim` on contact, owner simulates) | lowest latency — your kick lands instantly |
-| Sustained contact / contested (two players pushing one crate, tug-of-war, sumo, shared vehicles) | **host-authoritative** (this doc) | one simulation owns the contest — no ownership ping-pong, physics stays consistent |
+| **Pushable / ownable body** — a ball, a crate you shove, a physics prop, a pickup; one player interacts at a time (even if players take turns) | **claim-on-touch + a Rapier proxy** (Tier 1) | whoever touches it owns + simulates it locally with REAL physics; the soft handoff glides ownership changes |
+| **Genuine simultaneous contest** — two players pushing ONE object *against each other*: sumo, tug-of-war, a shared crate nobody should "own" | **host-authoritative** (Tier 2) | one neutral simulation (the host) runs the contest; everyone else sends inputs |
+| **Your own controller** — the vendored character / vehicle / drone rig | **publish-and-playback** (Tier 3) | each player simulates their OWN rig; remotes replay the pose |
 
-Claim-on-touch under sustained contact means every contact steals ownership, resets the
-simulation, and the object judders between two owners' views. Host-authoritative kills that
-by construction: **the host runs the ONE Rapier world for contested objects; everyone else
-sends inputs.**
+The old advice was "claim-on-touch breaks down under sustained contact, use host-authoritative for
+anything contested." That was true only because an ownership handoff used to **teleport** the object
+— the interpolation buffer reset on every claim. **Since `@genex-ai/multiplayer` 0.8.4 the handoff is
+a soft handoff: the render glides across the ownership change instead of snapping** — so claim-on-touch
+is now the right default for any *ownable* body (a ball, a box, a prop), even when players take turns
+bumping it. Reserve host-authoritative (Tier 2) for a genuine *simultaneous* tug-of-war where handing
+ownership to "whoever touched last" is itself the wrong model.
 
-## The pattern (complete)
+## Tier 1 — pushable / ownable body (claim-on-touch + a Rapier proxy)
 
-Every client runs this same code — `onHostTick` only fires on the current host, so there is
-no "am I host?" bookkeeping and host migration is automatic:
+The object is a REAL Rapier body on every client, and its body TYPE follows ownership:
+
+- **You own it → a `dynamic` body.** Your (dynamic) character capsule collides with it and Rapier's
+  solver resolves the push on the fixed substep — real momentum, spin, friction, bounce, zero latency.
+  A *regular pushable object*, not a dribble and not an attachment.
+- **You don't own it → a `kinematicPosition` body** you drive each frame to the smoothed
+  `objects.get(id).state`. It's solid, so your character physically bumps it — and that bump fires your
+  claim.
+
+This is ONE body that IS the render — not a second "prediction" body running alongside the stream
+(that would be double-simulation, the sibling of double-smoothing). When you own it you draw the dynamic
+body; when you don't you draw the smoothed stream and park the kinematic body on it.
+
+```ts
+import RAPIER from "@dimforge/rapier3d-compat";
+// Proxy body: kinematic to start (owned by nobody, or by someone else).
+const body = physics.createBody({ type: "kinematicPosition", position: [x, y, z], ccd: true });
+ballCollider(physics.world, body, RADIUS, { friction: 0.5, restitution: 0.35, density: 0.6 });
+let wasTouching = false, wasMine = false, claimCd = 0;
+
+// Per-frame, BEFORE physics.step (so the kinematic proxy is in place for the character to hit it):
+function updateBall(dt: number) {
+  let v = room.objects.get("ball");
+  let mine = !!v?.isMine;
+
+  // Rising-EDGE claim: sustained contact yields NO new rising edge, so ONE owner holds it
+  // (no per-frame ownership ping-pong). A short cooldown throttles a steal-war.
+  const touching = onFoot && feet.distanceTo(ballMesh.position) < RADIUS + REACH;
+  if (claimCd > 0) claimCd -= dt;
+  if (touching && !wasTouching && !mine && claimCd <= 0) {
+    room.objects.claim("ball");            // optimistic: isMine flips true locally THIS frame
+    claimCd = 0.25;
+    v = room.objects.get("ball"); mine = !!v?.isMine;
+  }
+  wasTouching = touching;
+
+  if (mine && !wasMine) {
+    // Gained ownership → dynamic. SEED velocity from the wire (NEVER zero, or a rolling ball
+    // stalls on the handoff); keep the position where the proxy already renders (no snap).
+    body.setBodyType(RAPIER.RigidBodyType.Dynamic, true);
+    const raw = v?.stateRaw;
+    body.setLinvel({ x: raw?.vx ?? 0, y: raw?.vy ?? 0, z: raw?.vz ?? 0 }, true);
+  } else if (!mine && wasMine) {
+    body.setBodyType(RAPIER.RigidBodyType.KinematicPositionBased, true);  // lost → follower
+  }
+  wasMine = mine;
+
+  if (mine) {
+    ballMesh.position.copy(body.translation());          // draw the dynamic body I simulate
+    ballMesh.quaternion.copy(body.rotation());
+  } else if (v?.state) {
+    ballMesh.position.set(v.state.x, v.state.y, v.state.z); // draw the smoothed stream
+    body.setNextKinematicTranslation(ballMesh.position);    // keep the proxy on it → I can bump → claim
+  }
+}
+
+// Owner-gated publish on your fixed tick (30Hz for a fast ball) — moved-only + a ~2Hz keepalive.
+// Publish VELOCITY too, so the next owner seeds from it and the handoff doesn't stall.
+if (room.objects.get("ball")?.isMine) {
+  const t = body.translation(), q = body.rotation(), lv = body.linvel();
+  room.objects.set("ball", { x: r2(t.x), y: r2(t.y), z: r2(t.z),
+    q: [r2(q.x), r2(q.y), r2(q.z), r2(q.w)], vx: r2(lv.x), vy: r2(lv.y), vz: r2(lv.z) });
+}
+const r2 = (v: number) => Math.round(v * 100) / 100;
+```
+
+Rules that make it correct:
+
+- **Rising-edge claim + a short cooldown** (~0.25s), never "am I touching": sustained contact must not
+  re-claim every frame. Add a minimum-hold (~0.5s) before you'll `release`, so a shove finishes under
+  your sim.
+- **Never zero velocity on claim** — seed `linvel` from the published `vx/vy/vz`, or a rolling ball snaps
+  to a dead stop on every handoff.
+- **Publish velocity, not just position** — the next owner seeds from it, so the object keeps its motion
+  across the handoff.
+- **Release-on-rest** (optional): once you own an object that's been at rest + untouched a couple of
+  seconds, `room.objects.release("ball")` so ownership doesn't pile up on a lone wanderer — its last
+  state persists on the wire for the next toucher, who re-claims.
+- **Distributed by construction:** each client publishes only what it currently owns, so the message
+  budget spreads across players instead of funnelling every object through one host's send budget. This
+  is why Tier 1 scales to many pushable objects where a host-authoritative fleet (Tier 2) would blow one
+  client's rate cap.
+- **Do NOT `registerBody(proxy, mesh)`** — drive the mesh yourself (from the body when you own it, from
+  the stream when you don't). Registering it fights the SDK's smoothing on the stream half.
+
+## Tier 2 — genuine simultaneous contest (host-authoritative)
+
+For a real tug-of-war — two players pushing ONE crate *against each other*, sumo — handing ownership to
+"whoever touched last" is the wrong model: a single neutral simulation must own the contest. The **host**
+runs the ONE Rapier world for those objects; everyone else sends **inputs**, which the relay routes to
+the current host only.
+
+Every client runs this same code — `onHostTick` only fires on the current host, so there is no "am I
+host?" bookkeeping and host migration is automatic:
 
 ```ts
 // ---- inputs: NON-hosts (and the host itself) report intent, ~10-15Hz or on action ----
@@ -69,13 +165,16 @@ Rules that make it correct:
   via `stateRaw`.
 - **Latency honesty:** a non-host's push lands after ~RTT to the relay. At casual scale that
   reads as weight, not lag. The host's own pushes are instant — that asymmetry is the tier's
-  price; don't fight it with client-side guessing.
-- **Rate budget:** the host publishes N contested objects at 20–30 Hz; keep N modest (≤ ~10)
-  and state flat + quantized. Inputs are single-receiver and cheap.
-- **Do not** run a second Rapier body for a contested object on non-hosts "for prediction" —
-  that's the double-simulation version of double-smoothing. Draw `state`.
+  price. (Tier 1 has no such asymmetry — the owner IS the simulator — which is another reason to
+  prefer it for a plain pushable body.)
+- **Rate budget:** the host publishes N contested objects at 20–30 Hz; keep N modest (≤ ~8) and
+  state flat + quantized. Inputs are single-receiver and cheap.
+- **Do not** run a second Rapier body for a Tier-2 object on non-hosts "for prediction" — that's the
+  double-simulation version of double-smoothing. Non-hosts draw `state`. (This is the opposite of the
+  Tier-1 proxy, which is a single body that IS the render for the object you OWN — not a shadow sim of
+  one the host owns.)
 
-## Networked controllers (the vendored character / vehicle / drone)
+## Tier 3 — networked controllers (the vendored character / vehicle / drone)
 
 The `genex controller` controllers are **local-only physics** — each player simulates their
 OWN rig (self-authoritative, zero latency). Networking them is publish-and-playback, never
@@ -131,5 +230,5 @@ What to publish per controller:
 
 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
-contested vehicle contact, that's the host-authoritative tier above, with the vehicles as
-host-simulated objects and player inputs over `inputs.send`.
+contested vehicle contact, that's Tier 2 above, with the vehicles as host-simulated objects and
+player inputs over `inputs.send`.

package/templates/skills/genex-threejs-skill-router/references/routing-map.md

@@ -87,7 +87,9 @@ enemies). That skill covers the rules that keep it smooth (draw `state` directly
 yourself and objects you own from a local object, quaternion rotation, `stateRaw` for
 hit-tests), the per-genre recipes (sports/ball, shooter, co-op), config wiring, and the
 persistent-world API. Reconnection is built into the SDK (render `reconnecting`/
-`reconnected`, never rebuild it), and **contested physics** (two players pushing one
-object — sumo, tug-of-war, shared crates) routes to its host-authoritative pattern
-(`inputs` + `onHostTick`, see that skill's host-physics reference) — never claim-on-touch.
+`reconnected`, never rebuild it). **Pushable/ownable bodies** (a ball, a box, a prop) use
+claim-on-touch + a Rapier proxy — the soft handoff glides the ownership change; only a genuine
+**simultaneous** contest (two players pushing one crate against each other — sumo, tug-of-war)
+uses the host-authoritative pattern (`inputs` + `onHostTick`). Both are in that skill's
+host-physics reference.
 Use only the APIs that skill documents — do not invent transport methods.