@genex-ai/cli-demo 0.10.0 → 0.12.1

package/dist/index.js

@@ -1095,6 +1095,17 @@ async function detectEmbedSdkVersion(cwd = process.cwd()) {
     return null;
   }
 }
+async function detectMultiplayer(cwd = process.cwd()) {
+  try {
+    const raw = await fs8.readFile(path9.join(cwd, "package.json"), "utf8");
+    const pkg = JSON.parse(raw);
+    return Boolean(
+      pkg.dependencies?.["@genex-ai/multiplayer"] ?? pkg.devDependencies?.["@genex-ai/multiplayer"]
+    );
+  } catch {
+    return false;
+  }
+}
 async function runPublish(opts) {
   const log = createLogger({ quiet: opts.quiet });
   log.plain(c.bold("genex publish"));
@@ -1132,8 +1143,10 @@ async function runPublish(opts) {
     if (opts.title) body.title = opts.title;
     if (opts.description) body.description = opts.description;
     if (opts.regenerateCover) body.regenerateCover = true;
+    if (opts.categories?.length) body.categories = opts.categories;
     const embedSdkVersion = await detectEmbedSdkVersion();
     if (embedSdkVersion) body.embedSdkVersion = embedSdkVersion;
+    body.multiplayer = await detectMultiplayer();
     res = await fetch(`${apiUrl}/api/projects/${meta.id}/publish`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
@@ -1486,6 +1499,8 @@ ${c.bold("Options for `preview` / `publish`")}
   --no-push            (publish) Skip build + push; only flip the gallery flag.
   --title <title>      (publish) Gallery title.
   --description <text> (publish) Gallery description.
+  --categories <list>  (publish) 1-3 gallery categories, comma-separated.
+                       Valid: games, assets, physics, terrain, lighting, vfx.
   --regenerate-cover   (publish) Re-mint the disc cover (concept changed).
   --api-url <url>      (publish) Override the API base URL.
   --env <path>         Token env file (default: ~/.genex/env).
@@ -1506,6 +1521,7 @@ ${c.bold("Examples")}
   genex init my-game --api-url http://localhost:3000 --auth-url http://localhost:5173
   genex preview
   genex publish
+  genex publish --categories games,vfx
   genex publish --no-push --title "My Game"
   genex model "weathered wooden barrel with iron bands"
   genex skybox "golden hour over a misty mountain range"
@@ -1529,6 +1545,7 @@ function parseArgs(argv) {
     "--name",
     "--title",
     "--description",
+    "--categories",
     "--timeout",
     "--duration"
   ]);
@@ -1623,6 +1640,9 @@ function applyValueFlag(options, flag, value) {
     case "--description":
       options.description = value;
       break;
+    case "--categories":
+      options.categories = value.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+      break;
     case "--timeout": {
       const n = Number(value);
       if (!Number.isFinite(n) || n <= 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.10.0",
+  "version": "0.12.1",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {
@@ -15,6 +15,14 @@
   "engines": {
     "node": ">=20"
   },
+  "scripts": {
+    "build": "tsup",
+    "prepack": "pnpm build",
+    "start": "node src/index.ts",
+    "dev": "node --watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.ts"
+  },
   "keywords": [
     "cli",
     "claude",
@@ -38,12 +46,5 @@
   "bugs": {
     "url": "https://github.com/me-ai-org/genex-demo/issues"
   },
-  "homepage": "https://github.com/me-ai-org/genex-demo/tree/main/apps/cli#readme",
-  "scripts": {
-    "build": "tsup",
-    "start": "node src/index.ts",
-    "dev": "node --watch src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "node --test test/*.test.ts"
-  }
-}
+  "homepage": "https://github.com/me-ai-org/genex-demo/tree/main/apps/cli#readme"
+}

package/templates/skills/genex-getting-started/SKILL.md

@@ -45,6 +45,19 @@ npx genex texture "mossy cobblestone" --terrain # a tiling surface texture
 Each has a focused skill with the exact loader code — `$genex-ai-model`,
 `$genex-ai-skybox`, `$genex-ai-sfx`, `$genex-ai-texture`.
 
+## Publishing
+
+`npx genex preview` deploys to your unlisted draft URL; `npx genex publish`
+lists the game in the public gallery. When publishing, pick 1–3 gallery
+categories from what you actually built — `games`, `assets`, `physics`,
+`terrain`, `lighting`, `vfx` — and pass them comma-separated:
+
+```bash
+npx genex publish --categories games,vfx
+```
+
+If unsure, use `games` (also the server's fallback for anything unrecognized).
+
 Your own files were left untouched. `genex init` only adds missing files and
 refreshes the genex-owned ones.
 

package/templates/skills/genex-threejs-embed-auth/SKILL.md

@@ -1,24 +1,31 @@
 ---
 name: genex-threejs-embed-auth
-description: Wire up signed-in identity for a Genex game via @genex-ai/embed-sdk. Load this UNCONDITIONALLY for every game, multiplayer or not, BEFORE writing any boot code — identity is required for play, saving progress, and multiplayer; there is no anonymous mode.
+description: Wire up player identity for a Genex game via @genex-ai/embed-sdk. Load this UNCONDITIONALLY for every game, multiplayer or not, BEFORE writing any boot code — every player gets an identity (signed-in account or guest); saving progress requires sign-in, and multiplayer requires the SDK's token either way.
 ---
 
 # Genex Three.js Embed Auth
 
 `@genex-ai/embed-sdk` is how a Genex game learns **who is playing it**. Every
-game needs it — there is **no anonymous play**: without a signed-in identity
-the game is not playable, cannot save progress, and cannot join multiplayer.
-The SDK handles both contexts with one `initEmbed(...)` call:
-
-- **Embedded in the Genex dashboard (an iframe):** a silent handshake with the
-  dashboard signs the player in within a couple of seconds — no login screen.
-- **Standalone (someone opens the game's link directly):** the SDK redirects
-  through Genex sign-in (first-time visitors sign up there) and returns to the
-  game automatically. This is a real page navigation, by design — game code
-  does not need to handle any of it.
-
-While identity is resolving (or missing) the SDK shows its own full-screen
+game needs it. Published games are playable by **guests** (no account — the
+SDK mints a temporary identity like `Guest-1234` automatically), while
+**signing in** unlocks saving/loading progress; multiplayer works for both,
+using the SDK's token. The SDK handles every context with one
+`initEmbed(...)` call:
+
+- **Embedded in the Genex dashboard (an iframe):** a silent handshake signs
+  the viewer in within a couple of seconds — or drops a signed-out viewer
+  straight into guest play. No login screen either way.
+- **Standalone (someone opens the game's link directly):** the visit bounces
+  once through Genex (at the CDN edge in production, so the game only loads
+  AFTER identity is resolved; the SDK does the same bounce itself in local
+  dev) — signed-in visitors arrive already authenticated on ANY game with
+  zero clicks; everyone else arrives as a guest with a small dismissible
+  "sign in to save progress" popover (rendered by the SDK — don't build your
+  own). Nobody ever hits a login wall on a published game.
+
+While identity is resolving (or blocked) the SDK shows its own full-screen
 overlay over the game, so never build a separate "connecting" screen for auth.
+Guest sessions have **no** overlay — the game just plays.
 
 ## Install
 
@@ -50,42 +57,69 @@ initEmbed({
 });
 ```
 
+Also give `<body>` a dark background in `index.html` (e.g.
+`<body style="margin:0;background:#080a14">`) — it makes the pre-boot frame
+(before any JS runs) match the SDK's own loading overlay instead of flashing
+white, and every Genex surface assumes a dark canvas anyway.
+
 Scene setup and asset loading may continue immediately after this call — auth
-never blocks rendering. Gate the **identity-dependent** parts (multiplayer
-connect, saving/loading progress, showing the player's name) on `waitForAuth()`:
+never blocks rendering. There are **two gates**, and picking the right one
+matters:
 
 ```ts
-import { waitForAuth, getColyseusAuth, getEmbedToken } from "@genex-ai/embed-sdk";
-
-const { user } = await waitForAuth();   // resolves when signed in; rejects if blocked
-// user.id / user.name are the real Genex identity
+import { waitForPlayer, waitForAuth, getColyseusAuth, getEmbedToken } from "@genex-ai/embed-sdk";
+
+// PLAYER gate — resolves for guests AND signed-in players. Use for
+// multiplayer connect() and player-name UI. This is the gate almost
+// everything wants.
+const { user, guest } = await waitForPlayer();
+// user.id / user.name — real account identity, or guest:<id> / "Guest-1234"
+
+// ACCOUNT gate — resolves ONLY for signed-in players (stays pending for
+// guests; resolves later if they sign in mid-game). Use ONLY for /state
+// saving/loading and other account-bound features.
+const { user: account } = await waitForAuth();
 ```
 
+**NEVER gate scene boot or `connect()` on `waitForAuth()`** — for a guest it
+stays pending forever and your game would sit empty. `waitForPlayer()` is the
+boot-path gate; `waitForAuth()` guards saves only.
+
 ## API surface (exact — do not invent methods)
 
 - `initEmbed({ slug, apiUrl, dashboardOrigins })` — call once, first. All three
   fields required (from `genex.config.ts`).
-- `waitForAuth()` → `Promise<{ user }>` — THE gate for `connect()` and `/state`
-  calls. Rejects if the session ends up blocked — catch it and let the SDK's
-  overlay handle the UX (don't build your own sign-in UI).
+- `waitForPlayer()` → `Promise<{ user, guest }>` — THE gate for `connect()`
+  and player-name UI; resolves for guests and accounts alike, rejects only if
+  the session ends up blocked.
+- `waitForAuth()` → `Promise<{ user }>` — the gate for `/state` calls and
+  account-bound features. Stays PENDING for guests (resolves live if they
+  sign in); rejects if blocked. Catch rejections and let the SDK's overlay
+  handle the UX (don't build your own sign-in UI).
 - `isEmbedded()` → `boolean` — structural "is in an iframe" check; NOT the same
   question as "is signed in".
-- `getAuthState()` → `"pending" | "authenticated" | "blocked"` — synchronous.
-- `getUser()` → `{ id, name, image? } | null` — non-null only when authenticated.
+- `getAuthState()` → `"pending" | "authenticated" | "guest" | "blocked"` —
+  synchronous.
+- `getUser()` → `{ id, name, image? } | null` — non-null once authenticated OR
+  guest. Guest ids are prefixed `guest:`.
 - `getEmbedToken()` → `string | undefined` — for `Authorization: Bearer` on
-  `GET`/`PUT ${GENEX.apiUrl}/api/projects/${GENEX.slug}/state` (both REQUIRE it).
+  `GET`/`PUT ${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`. Defined for
+  guests too, but `/state` answers guests with `403 { "error": "guest_no_save" }`
+  — that's why saves gate on `waitForAuth()`, not on the token existing.
 - `getColyseusAuth()` → `{ embedToken } | undefined` — pass as `connect()`'s
-  `auth` option (REQUIRED — the relay rejects tokenless joins). Read it fresh
-  at every `connect()` call; tokens rotate automatically (~every 10 minutes).
-- `on(event, cb)` → unsubscribe fn. Events: `"authenticated"`, `"blocked"`,
-  `"error"`.
+  `auth` option (REQUIRED — the relay rejects tokenless joins; guest tokens
+  are accepted). Read it fresh at every `connect()` call; tokens rotate
+  automatically (~every 10 minutes).
+- `on(event, cb)` → unsubscribe fn. Events: `"authenticated"`, `"guest"`,
+  `"blocked"`, `"error"`. A mid-game sign-in fires `"authenticated"` after
+  `"guest"` — progress saving can start right then, no reload.
 
 From `@genex-ai/embed-sdk/sentry` (crash reporting; exactly these two):
 
 - `initGameSentry({ slug, dsn?, environment? })` — call once, BEFORE
   `initEmbed()`. Only `slug` is required; the shared Genex Sentry project DSN
-  is built in. Errors, tracing, and session replay all start here; the signed-in
-  user is attached automatically after auth (no code needed).
+  is built in. Errors, tracing, and session replay all start here; the current
+  player (account or guest) is attached automatically (no code needed).
 - `sentryCanvasSnapshot(canvas)` — session replay records the DOM, not the 3D
   canvas; call this once per frame at the END of the render loop so replays
   show actual gameplay. Works for BOTH WebGL and WebGPU renderers; internally
@@ -100,6 +134,31 @@ function animate() {
 }
 ```
 
+## Saving progress with guests around
+
+Guests play but cannot save — design the save path accordingly:
+
+```ts
+// Fire-and-forget save that is simply OFF for guests:
+async function saveProgress(data: unknown) {
+  const token = getEmbedToken();
+  if (getAuthState() !== "authenticated" || !token) return; // guest: skip silently
+  await fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`, {
+    method: "PUT",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(data),
+  });
+}
+
+// And start loading/saving the moment a guest upgrades mid-game:
+waitForAuth().then(({ user }) => {
+  // signed in (possibly after starting as a guest) — load their save now
+}).catch(() => { /* blocked — SDK overlay owns the UX */ });
+```
+
+The SDK already tells guests to sign in (its popover / the dashboard's card) —
+don't add another prompt.
+
 ## Crash reporting rules
 
 - `initGameSentry` has token scrubbing built in (the sign-in return-trip pass
@@ -136,13 +195,17 @@ If `src/genex.config.ts` is somehow missing (e.g. it was deleted), re-run
 
 ## Standalone behavior (what to expect, not something to code)
 
-Opening the game's link directly (not from the dashboard) bounces through the
-Genex sign-in page and back before the game becomes playable — including during
-your own local `npm run dev` checks (sign in once; the bounce is instant after
-that). The return trip carries a one-time pass in the URL that the SDK consumes
-and removes immediately. Don't code around any of this: no `?`/`#` URL params
-of yours will be affected, and `isEmbedded()` / the return-trip handling are
-internal SDK concerns.
+Opening a published game's link directly (not from the dashboard) shows a
+brief "Loading…" overlay while the SDK round-trips through Genex once, then
+the game starts: already-signed-in visitors come back authenticated (zero
+clicks — on every game), everyone else comes back playing as a guest with the
+SDK's own top-right "sign in to save progress" popover. The return trip
+carries a one-time pass (or an inert guest marker) in the URL that the SDK
+consumes and removes immediately. Unpublished drafts are the exception:
+strangers can't play them, so a draft link shows the SDK's sign-in gate
+instead. Don't code around any of this: no `?`/`#` URL params of yours will
+be affected, and `isEmbedded()` / the return-trip handling are internal SDK
+concerns.
 
 ## Checklist
 
@@ -151,24 +214,33 @@ internal SDK concerns.
 - [ ] `sentryCanvasSnapshot(renderer.domElement)` runs after `renderer.render()`
       in the main loop (WebGL and WebGPU alike).
 - [ ] `genex.config.ts` includes `dashboardOrigins` (from `.genex/project.json`).
-- [ ] Everything identity-dependent awaits `waitForAuth()` (multiplayer `connect`,
-      `/state` load/save, player-name UI).
-- [ ] `/state` fetches send `Authorization: Bearer ${getEmbedToken()}`.
+- [ ] Multiplayer `connect()` and player-name UI await `waitForPlayer()` —
+      NEVER `waitForAuth()` (guests would hang forever).
+- [ ] `/state` load/save gates on `waitForAuth()` / `getAuthState() ===
+      "authenticated"` and sends `Authorization: Bearer ${getEmbedToken()}`;
+      guests skip saves silently (the server answers them `403 guest_no_save`).
 - [ ] No token value is ever logged or sent to analytics.
-- [ ] No custom sign-in/anonymous-fallback UI — the SDK overlay + dashboard own that.
+- [ ] No custom sign-in prompt, guest badge, or auth overlay — the SDK popover/
+      overlay and the dashboard own all of that UX.
 
 ## Troubleshooting
 
-- **Game loads then immediately navigates away (standalone/local dev)** — that's
-  the sign-in bounce working as designed. Sign in once in the browser; it
-  returns to the game automatically.
-- **`waitForAuth()` rejects / state is `"blocked"`** — the visitor declined or
-  failed sign-in, or the dashboard session ended. The SDK overlay (or the
-  dashboard, when embedded) shows the sign-in prompt; the game just stays
-  paused behind it. Don't retry in a loop.
+- **Game loads then immediately navigates away (standalone/local dev)** — the
+  identity bounce, working as designed for EVERY standalone visit. It returns
+  to the game automatically (signed-in or as a guest) within a second.
+- **`waitForAuth()` never resolves** — the player is a GUEST; that's the
+  designed behavior. Anything that must run for guests belongs behind
+  `waitForPlayer()` instead.
+- **State is `"blocked"` / `waitForPlayer()` rejects** — an unpublished draft
+  opened by a non-owner, or auth infrastructure was unreachable. The SDK
+  overlay (or the dashboard, when embedded) shows the sign-in prompt; the game
+  just stays paused behind it. Don't retry in a loop.
 - **Multiplayer join rejected with 401** — `connect()` ran before
-  `waitForAuth()` resolved, without `auth: getColyseusAuth()!`, or with a stale
-  cached token on reconnect (read it fresh each call).
-- **`/state` returns 401/403** — missing `Authorization` header (401) or the
-  token belongs to a different game (403): `GENEX.slug` doesn't match this
-  project.
+  `waitForPlayer()` resolved, without `auth: getColyseusAuth()!`, or with a
+  stale cached token on reconnect (read it fresh each call).
+- **Multiplayer join rejected with 403 "guest capacity"** — the room is at its
+  guest limit; only signing in gets the player a seat right now. Surface the
+  relay's message as-is.
+- **`/state` returns 401/403** — missing `Authorization` header (401), a guest
+  token (403 `guest_no_save` — expected, skip saves for guests), or the token
+  belongs to a different game (403): `GENEX.slug` doesn't match this project.

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

@@ -44,17 +44,19 @@ npm i @genex-ai/multiplayer
 Pick your own per-player state shape (any JSON). `room` is the **project slug**
 (printed by `genex init`) — same id = same room, different ids are fully isolated.
 
-**Joining requires a signed-in identity — the relay rejects joins without one.**
+**Joining requires the SDK's player identity — the relay rejects tokenless
+joins, but accepts guests** (accountless players named like `Guest-1234`).
 Load the `genex-threejs-embed-auth` skill first (it sets up `initEmbed(...)`),
-then gate `connect()` on `waitForAuth()`:
+then gate `connect()` on `waitForPlayer()` — NOT `waitForAuth()`, which stays
+pending for guests and would keep them out of multiplayer forever:
 
 ```ts
 import { connect } from "@genex-ai/multiplayer";
-import { waitForAuth, getColyseusAuth } from "@genex-ai/embed-sdk";
+import { waitForPlayer, getColyseusAuth } from "@genex-ai/embed-sdk";
 
 type State = { x: number; z: number; q: number[] };  // YOUR per-player state (rotation as quaternion)
 
-const { user } = await waitForAuth();  // identity gate — rejects if the session is blocked
+const { user } = await waitForPlayer();  // player gate (guest OR signed-in) — rejects only if blocked
 const room = await connect<State>({
   url: GENEX.colyseusUrl,     // e.g. "wss://demo-colyseus.glotech.world" — see config wiring below
   room: GENEX.slug,           // the project slug — everyone with this id shares a room
@@ -207,9 +209,11 @@ file layout.
 The relay is in-memory: room state is gone when everyone leaves or the server restarts. For a world
 that persists, save/load one JSON blob keyed by the project slug, from **one authority** (the host):
 
-Both calls **require the embed identity** (`Authorization: Bearer` with the token from
-`getEmbedToken()`) — there is no anonymous read or save. Call them only after
-`await waitForAuth()` (see the `genex-threejs-embed-auth` skill):
+Both calls **require a signed-in identity** (`Authorization: Bearer` with the token
+from `getEmbedToken()`) — guests play multiplayer but cannot read or write saves
+(the server answers their token `403 guest_no_save`). Gate them on
+`await waitForAuth()` — the ACCOUNT gate, deliberately stricter than the
+`waitForPlayer()` gate `connect()` uses (see the `genex-threejs-embed-auth` skill):
 
 ```ts
 import { getEmbedToken } from "@genex-ai/embed-sdk";
@@ -239,8 +243,9 @@ single writer.
 ## Checklist
 
 - [ ] `npm i @genex-ai/multiplayer` (≥ 0.4.0 for objects/host); config wired into the build.
-- [ ] `connect()` runs AFTER `await waitForAuth()` and passes `auth: getColyseusAuth()!`
-      (the relay rejects tokenless joins — see `genex-threejs-embed-auth`).
+- [ ] `connect()` runs AFTER `await waitForPlayer()` (never `waitForAuth()` — guests would
+      hang) and passes `auth: getColyseusAuth()!` (the relay rejects tokenless joins —
+      see `genex-threejs-embed-auth`).
 - [ ] `room` is the **project slug**.
 - [ ] `me.set` on a fixed **10–20 Hz** tick; full object each time.
 - [ ] Skip yourself in `room.players` (`id === room.id`).
@@ -255,6 +260,7 @@ single writer.
 ## Troubleshooting auth
 
 - **`connect()` rejects with 401/403** — 401 "auth required"/"invalid token": you joined
-  without `auth` or before `waitForAuth()` resolved (or the token expired mid-reconnect —
+  without `auth` or before `waitForPlayer()` resolved (or the token expired mid-reconnect —
   read `getColyseusAuth()` fresh at every connect). 403 "wrong game": the `room` value
-  doesn't match this game's own slug.
+  doesn't match this game's own slug. 403 "guest capacity": the room is at its guest
+  limit — signing in gets the player a seat; surface the message as-is.