@genex-ai/cli-demo 1.36.5 → 1.36.6-dev.862

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

@@ -401,13 +401,39 @@ and friends join it; the lobby is persistent (rounds replay, nobody is evicted):
 
 ```ts
 import { createPrivate, joinPrivate } from "@genex-ai/multiplayer";
-const lobby = await createPrivate<MyState>({ urls, room: slug, auth: () => getColyseusAuth() });  // live NOW
-showCode(lobby.code);                                                   // share this
-// a friend, elsewhere:
-const lobby = await joinPrivate<MyState>(code, { urls, room: slug, auth: () => getColyseusAuth() });
+import { share, getEntry } from "@genex-ai/embed-sdk";              // 0.32.0+
+const opts = { urls, room: slug, auth: () => getColyseusAuth() };
+
+// host
+const lobby = await createPrivate<MyState>(opts);                    // live NOW
+showCode(lobby.code);                 // always show the code too: the way in when a link will not do
+inviteBtn.onclick = async () => {     // share() starts inside the click, before any await
+  const { status, url } = await share({ text: "Join my lobby", params: { lobby: lobby.code } });
+  if (status === "copied") toast("Invite link copied");
+  if (status === "unavailable") showLink(url);       // no share sheet, no clipboard: show the link
+};
+
+// friend: ONE way in, for the code from a link and for a code typed by hand
+async function enter(code: string) {
+  if (!/^[\w-]{1,32}$/.test(code)) return null;      // a link is text anyone can write: take a code, nothing else
+  try { return await joinPrivate<MyState>(code, opts); }
+  catch { showNotice("That lobby is no longer open"); return null; }
+}
+// at boot, after waitForPlayer(): did they arrive on an invite link?
+const invited = getEntry().params.get("lobby");
+const joined = invited ? await enter(invited) : null;  // null → the menu, with its "Enter code" field
 // same handle API as matchmake(): lobby.session, lobby.matchmaking, eliminated()/score()/finish(), cancel()
 ```
 
+`share()` builds the link itself — the game's page on Genex plus `?lobby=<code>`, or the
+address the game is on where that is a preview address or a creator's own domain — and
+`getEntry()` hands the parameter back to whoever opens it. **Never build the invite from
+`location.href`**: on the game's page that is the frame's bare address, not the page a friend
+should land on. `lobby` is this example's name; any name works except the ones Genex keeps
+(`$genex-threejs-embed-auth`, `references/shells.md`). `joinPrivate` REJECTS when the code leads
+to no lobby this player can reach — it closed, or its host is on another region's relay — so
+catch it and show the menu, and keep the typed code as the second way in.
+
 ## Connect
 
 Pick your own per-player state shape (any JSON). `room` is the **project slug**
@@ -674,10 +700,22 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
   mesh — everyone uploads to everyone, and reliability, not bandwidth, breaks first). The
   room still holds 64 players; the 7th `join()` is refused, so handle `voice:rejected`
   instead of retrying. `join()` MUST run inside a click/tap — browsers gate both the mic
-  prompt and audio playback on a user gesture — and it REJECTS when the player denies the
-  mic, which is an ordinary outcome to show, not an error to swallow. For a 3D game use
-  `npx genex controller voice` (proximity audio + push-to-talk); it joins with
-  `{ spatial: true }` and drives a `THREE.PositionalAudio` per speaker. **TURN is automatic
+  prompt and audio playback on a user gesture — and it REJECTS when the microphone is
+  refused, which is an ordinary outcome to show, not an error to swallow. **Two refusals are
+  not the player's.** On its Genex page a game gets the microphone only when its BUILD
+  declared it: `npx genex preview` / `npx genex publish` declare it when the game's own
+  source calls `.voice.join()` with nothing or with options written at the call, and print
+  what the build is given — read that line. `voice.join(opts)` with the options in a
+  variable is not seen: declare the microphone in `package.json` then. When the
+  page withheld it, `join()` rejects with an error whose `name` is `VoiceNotDelegatedError`
+  (SDK 0.16.2+, Chromium browsers; elsewhere it arrives as the browser's own error): show
+  "Voice chat is not available here", never "allow your microphone" — the player was never
+  asked. And the Genex app refuses the microphone for every game: hide the voice button when
+  `getShell()` from `@genex-ai/embed-sdk` is `"app"`. The declaration rule, and the
+  `package.json` line for a call the CLI cannot see, are in `$genex-threejs-embed-auth`
+  (`references/shells.md`).
+  For a 3D game use `npx genex controller voice` (proximity audio + push-to-talk); it joins
+  with `{ spatial: true }` and drives a `THREE.PositionalAudio` per speaker. **TURN is automatic
   — do not pass `iceServers`**: `join()` fetches short-lived relay credentials from the
   platform before opening any peer connection, which is what lets the ~15% of players behind
   symmetric NAT or carrier CGNAT be heard at all (in a mesh they fail every leg, so they

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

@@ -1,6 +1,6 @@
 ---
 name: genex-threejs-touch-controls
-description: Make a Genex Three.js game playable on phones — vendored touch primitives via `npx genex controller touch` (floating/static joystick, virtual buttons, drag zone, rotate-device overlay) plus per-genre wiring recipes (movement, camera look, taps, paddles, action buttons, touch pause). Use when wiring default touch controls into a new game, whenever someone asks to make a game playable on mobile/phone/tablet, or before shipping a game whose input is keyboard/mouse-only.
+description: Make a Genex Three.js game playable on phones — vendored touch primitives via `npx genex controller touch` (floating/static joystick, virtual buttons, drag zone, rotate-device overlay) plus per-genre wiring recipes (movement, camera look, taps, paddles, action buttons, touch pause, tilt). Use when wiring default touch controls into a new game, whenever someone asks to make a game playable on mobile/phone/tablet, or before shipping a game whose input is keyboard/mouse-only.
 ---
 
 # Genex Three.js Touch Controls
@@ -116,6 +116,68 @@ If the game is merely suboptimal sideways, skip the overlay and just resize.
 The web cannot force an orientation (fullscreen-only lock, none on iOS Safari)
 — the overlay asks; it never traps.
 
+## Tilt controls
+
+Steering by tilting the phone is an extra on top of the stick, never a
+replacement for it: the sensor is the one input a phone can silently not have.
+Four rules, all in the block below.
+
+1. **Ask inside the Start tap.** An iPhone hands a page no motion events until
+   the player allows them, and it asks only when `requestPermission()` is
+   called from a tap inside the game. Called at boot it is refused without a
+   prompt.
+2. **A refusal, or silence, is "no sensor".** A browser can answer "granted"
+   and then send nothing, and a desktop can send events full of `null`. Trust
+   tilt only after a real reading has arrived.
+3. **Keep the joystick.** It stays on screen and wins whenever it is touched.
+4. **Hold the screen awake.** Tilt play has no touches, so the phone dims and
+   locks mid-game unless the game asks it not to.
+
+```ts
+import { keepAwake } from "@genex-ai/embed-sdk"; // 0.32.0+
+
+const tilt = { x: 0, y: 0, live: false };   // x/y in [-1, 1], same sense as joy.x / joy.y
+const TILT_FULL = 25;                       // degrees of lean for full deflection
+let rest: { x: number; y: number } | null = null; // how the phone was held at the first reading
+
+type MotionGate = { requestPermission?: () => Promise<"granted" | "denied"> };
+
+// Call from the Start/Play tap handler, before any await in that handler.
+async function enableTilt(): Promise<void> {
+  void keepAwake(true);                     // released with keepAwake(false) on the menu / pause
+  const gate = (window as unknown as { DeviceOrientationEvent?: MotionGate }).DeviceOrientationEvent;
+  if (!gate) return;                        // no sensor API: the joystick is the control
+  try {
+    if (typeof gate.requestPermission === "function" && (await gate.requestPermission()) !== "granted") return;
+  } catch { return; }                       // refused, or not inside a tap
+  window.addEventListener("deviceorientation", (e) => {
+    if (e.beta == null || e.gamma == null) return; // a desktop fires events with nulls
+    // The reading is in the DEVICE's axes; turn it into the screen's.
+    const a = screen.orientation?.angle ?? 0;
+    const x = a === 90 ? e.beta : a === 270 ? -e.beta : a === 180 ? -e.gamma : e.gamma;
+    const y = a === 90 ? -e.gamma : a === 270 ? e.gamma : a === 180 ? -e.beta : e.beta;
+    rest ??= { x, y };                      // "level" is however the player was holding it
+    const unit = (v: number) => Math.max(-1, Math.min(1, v / TILT_FULL));
+    tilt.x = unit(x - rest.x);
+    tilt.y = -unit(y - rest.y);             // leaning the top edge away from you = up, like the stick
+    tilt.live = true;
+  });
+}
+
+// each frame, where the stick is read:
+const steer = joy.x !== 0 ? joy.x : tilt.live ? tilt.x : 0;
+```
+
+Clear `rest` when the device rotates or the player taps a "recentre" button,
+so level is re-taken from the next reading. **Check the directions on a real
+phone, in the orientation the game is played in** — a desktop browser has no
+sensor, so nothing in a local test exercises this. Lean-right must steer
+screen-right (the screen-direction contract in
+`$genex-threejs-camera-direction`); a flipped feel is a sign to fix in the
+mapping above, never a device quirk. What each Genex shell does with the
+sensors and the wake lock is in `$genex-threejs-embed-auth`
+(`references/shells.md`).
+
 ## Match the game's style
 
 The touch controls are UI like any other — restyle them from the same style

package/templates/skills/genex-tool-llm/SKILL.md

@@ -13,11 +13,12 @@ model has to run for the player.
 ## What the platform does
 
 A game hosted on Genex can call a language model from inside the running game
-and get back text or JSON. **The player pays and the player approves**: coins
-from their Genex wallet, or their own Claude / ChatGPT subscription, chosen on
-an approval sheet Genex draws that the game cannot render, skin or bypass.
-Either one call at a time, or one standing budget the player approves once and
-the game then spends against without another popup. The game holds no provider
+and get back text or JSON. **The player pays and the player approves**: credits
+from their Genex account, billed as each call is used and never past the
+per-call ceiling the game declares, or their own Claude / ChatGPT subscription,
+chosen on an approval sheet Genex draws that the game cannot render, skin or
+bypass. Either one call at a time, or one standing budget the player approves
+once and the game then spends against without another popup. The game holds no provider
 key, sees no credential, and never talks to a model vendor.
 
 That is the whole reason this is a platform feature and not something you wire
@@ -40,9 +41,9 @@ Any of these means a model at PLAY time, however it is phrased:
 Say this and stop:
 
 > A model running while people play is built into the Genex platform — the
-> player pays, with Genex coins or their own Claude/ChatGPT subscription, and
-> approves it on a Genex sheet; your game just calls `generate()`. Want it
-> that way?
+> player pays, with their Genex credits or their own Claude/ChatGPT
+> subscription, and approves it on a Genex sheet; your game just calls
+> `generate()`. Want it that way?
 
 Wait for the answer. Do not start building either version first, and do not
 expand the offer into a pitch — one line, one question.
@@ -64,7 +65,8 @@ expand the offer into a pitch — one line, one question.
    ask before you do if you have not already.
 3. Load `$genex-llm-in-games` — it arrives with the conversion and owns the
    build: the SDK surface, one-time calls versus a standing budget, measuring
-   the price before the game declares it, and honest handling of every refusal.
+   the per-call ceiling before the game declares it, and honest handling of
+   every refusal.
 
 **The game has to be a static browser build.** A hosted game is files served
 from the edge; there is no server of yours inside it. So the familiar pattern —

package/templates/skills/genex-updates/SKILL.md

@@ -38,7 +38,7 @@ update, so update immediately.)
 Run exactly the command the nudge printed, from the game project root:
 
 ```bash
-npm i -D @genex-ai/cli-demo@latest   # the genex CLI (a dev dependency)
+npm i -D @genex-ai/cli-demo@dev   # the genex CLI (a dev dependency)
 npm i @genex-ai/embed-sdk@latest     # identity/saves SDK (ships inside the game)
 npm i @genex-ai/multiplayer@latest   # multiplayer SDK (only if the game uses it)
 ```