@genex-ai/cli-demo 0.62.0-dev.143 → 0.62.0-dev.144

package/templates/skills/genex-threejs-open-world/references/terrain-streaming.md

@@ -0,0 +1,215 @@
+# Genex open-world terrain — copy-paste streaming heightfield
+
+One module: seeded noise → fBm heightfield with location pads → chunked,
+time-budgeted streaming with seam-free normals → instanced scatter. Plain
+vanilla-ts, three.js only. Copy it, then tune the named constants at the top —
+they are the whole difficulty/size surface.
+
+## Constants + the canonical height function
+
+```ts
+// world-terrain.ts
+import * as THREE from "three";
+
+export const WORLD_SEED = 1337;      // one seed → same world on every machine
+export const WORLD_BOUND = 2048;     // half-size: playable area is 4096×4096 m
+export const CHUNK = 128;            // chunk side in meters
+export const CHUNK_RES = 32;         // vertices per side (33×33 grid)
+export const VIEW_CHUNKS = 5;        // load radius → ~600 m view with fog
+
+// --- seeded value noise + fBm (swap in $genex-threejs-procedural-fields'
+// simplex if it's already loaded; the shape below is what matters) ---
+const hash2 = (x: number, y: number): number => {
+  let h = (Math.imul(x, 374761393) + Math.imul(y, 668265263) + WORLD_SEED) | 0;
+  h = Math.imul(h ^ (h >>> 13), 1274126177);
+  return ((h ^ (h >>> 16)) >>> 0) / 0xffffffff;
+};
+const smooth = (t: number): number => t * t * (3 - 2 * t);
+function valueNoise(x: number, y: number): number {
+  const xi = Math.floor(x), yi = Math.floor(y);
+  const tx = smooth(x - xi), ty = smooth(y - yi);
+  const a = hash2(xi, yi), b = hash2(xi + 1, yi);
+  const c = hash2(xi, yi + 1), d = hash2(xi + 1, yi + 1);
+  return (a + (b - a) * tx) * (1 - ty) + (c + (d - c) * tx) * ty; // 0..1
+}
+function fbm(x: number, y: number, octaves = 5): number {
+  let sum = 0, amp = 0.5, freq = 1;
+  for (let i = 0; i < octaves; i++) {
+    sum += amp * (valueNoise(x * freq, y * freq) * 2 - 1);
+    amp *= 0.5; freq *= 2;
+  }
+  return sum; // ~-1..1
+}
+
+// --- location pads: level ground for structures, BLENDED into the field ---
+type Pad = { x: number; z: number; radius: number; height: number };
+export const PADS: Pad[] = []; // fill from your POI table before first chunk build
+
+function baseHeight(x: number, z: number): number {
+  const n = fbm(x * 0.0016, z * 0.0016);            // rolling base, ~600 m features
+  const ridge = 1 - Math.abs(fbm(x * 0.004, z * 0.004)); // sharp ridge lines
+  let h = n * 26 + ridge * ridge * 18;
+  // edge-mountain ring: the honest world bound the player can SEE
+  const edge = Math.max(Math.abs(x), Math.abs(z)) / WORLD_BOUND; // 0..1
+  if (edge > 0.85) h += ((edge - 0.85) / 0.15) ** 2 * 90;
+  return h;
+}
+
+/**
+ * THE canonical height. Chunk meshing, physics grounding, scatter, spawns,
+ * and the minimap all call THIS — a second height formula anywhere is how
+ * trees float and feet sink.
+ */
+export function getHeightAt(x: number, z: number): number {
+  let h = baseHeight(x, z);
+  for (const p of PADS) {
+    const d = Math.hypot(x - p.x, z - p.z);
+    if (d < p.radius) {
+      const t = smooth(1 - d / p.radius); // 1 at center → 0 at rim
+      h = h * (1 - t) + p.height * t;     // flat pad blended into the hills
+    }
+  }
+  return h;
+}
+```
+
+## Chunk manager — streamed, time-budgeted, seam-free
+
+```ts
+// world-chunks.ts
+const chunkKey = (cx: number, cz: number): string => `${cx},${cz}`;
+const live = new Map<string, THREE.Mesh>();
+const queue: Array<{ cx: number; cz: number }> = [];
+const material = new THREE.MeshStandardMaterial({ vertexColors: true });
+
+function buildChunk(cx: number, cz: number): THREE.Mesh {
+  const geo = new THREE.PlaneGeometry(CHUNK, CHUNK, CHUNK_RES, CHUNK_RES);
+  geo.rotateX(-Math.PI / 2);
+  const pos = geo.attributes.position;
+  const colors = new Float32Array(pos.count * 3);
+  const x0 = cx * CHUNK, z0 = cz * CHUNK;
+  for (let i = 0; i < pos.count; i++) {
+    const wx = x0 + pos.getX(i), wz = z0 + pos.getZ(i);
+    const h = getHeightAt(wx, wz);
+    pos.setY(i, h);
+    const c = biomeColor(wx, wz, h); // your biome lookup (see below)
+    colors.set([c.r, c.g, c.b], i * 3);
+  }
+  geo.setAttribute("color", new THREE.BufferAttribute(colors, 3));
+  // Seam rule: analytic normals from the SAME height field (an implicit
+  // one-vertex apron) — computeVertexNormals() per chunk creases every border.
+  const nrm = geo.attributes.normal;
+  const eps = CHUNK / CHUNK_RES;
+  for (let i = 0; i < pos.count; i++) {
+    const wx = x0 + pos.getX(i), wz = z0 + pos.getZ(i);
+    const hx = getHeightAt(wx + eps, wz) - getHeightAt(wx - eps, wz);
+    const hz = getHeightAt(wx, wz + eps) - getHeightAt(wx, wz - eps);
+    const n = new THREE.Vector3(-hx, 2 * eps, -hz).normalize();
+    nrm.setXYZ(i, n.x, n.y, n.z);
+  }
+  const mesh = new THREE.Mesh(geo, material);
+  mesh.position.set(x0, 0, z0);
+  mesh.receiveShadow = true;
+  return mesh;
+}
+
+/** Call every frame. Streams chunks around the player inside a ms budget. */
+export function updateChunks(scene: THREE.Scene, px: number, pz: number, budgetMs = 5): void {
+  const ccx = Math.round(px / CHUNK), ccz = Math.round(pz / CHUNK);
+  for (let dz = -VIEW_CHUNKS; dz <= VIEW_CHUNKS; dz++) {
+    for (let dx = -VIEW_CHUNKS; dx <= VIEW_CHUNKS; dx++) {
+      const key = chunkKey(ccx + dx, ccz + dz);
+      if (!live.has(key) && !queue.some((q) => chunkKey(q.cx, q.cz) === key)) {
+        queue.push({ cx: ccx + dx, cz: ccz + dz });
+      }
+    }
+  }
+  const start = performance.now();
+  while (queue.length && performance.now() - start < budgetMs) {
+    const { cx, cz } = queue.shift()!;
+    const mesh = buildChunk(cx, cz);
+    live.set(chunkKey(cx, cz), mesh);
+    scene.add(mesh);
+    // scatterChunk(scene, cx, cz) — instanced vegetation, below
+  }
+  for (const [key, mesh] of live) {
+    const [cx, cz] = key.split(",").map(Number);
+    if (Math.max(Math.abs(cx - ccx), Math.abs(cz - ccz)) > VIEW_CHUNKS + 1) {
+      scene.remove(mesh);
+      mesh.geometry.dispose(); // material is shared — never dispose it here
+      live.delete(key);
+    }
+  }
+}
+```
+
+## Biomes — one lookup drives color, scatter, and spawns
+
+```ts
+type Biome = "meadow" | "forest" | "marsh" | "desert" | "alpine";
+export function biomeAt(x: number, z: number, h: number): Biome {
+  if (h > 55) return "alpine";
+  const temp = valueNoise(x * 0.0006 + 100, z * 0.0006);     // slow fields:
+  const moist = valueNoise(x * 0.0006, z * 0.0006 + 100);    // ~1.5 km regions
+  if (temp > 0.62 && moist < 0.4) return "desert";
+  if (moist > 0.62 && h < 12) return "marsh";
+  if (moist > 0.45) return "forest";
+  return "meadow";
+}
+const BIOME_TINT: Record<Biome, THREE.Color> = {
+  meadow: new THREE.Color(0x5d7f3a), forest: new THREE.Color(0x3f5f31),
+  marsh: new THREE.Color(0x4a5a3c), desert: new THREE.Color(0xb59a63),
+  alpine: new THREE.Color(0x8d8d94),
+};
+function biomeColor(x: number, z: number, h: number): THREE.Color {
+  const c = BIOME_TINT[biomeAt(x, z, h)].clone();
+  // slope → rock, shoreline → sand: cheap reads that sell the terrain
+  return c;
+}
+```
+
+Spawn tables and ambient audio key off `biomeAt` too — that is the content
+hookup (`$genex-threejs-game-content`'s enemy line usually reads "wolves in
+the forest, bandits on the roads": this function is where that sentence
+becomes true).
+
+## Instanced scatter — a forest for one draw call
+
+```ts
+export function scatterChunk(scene: THREE.Scene, cx: number, cz: number): void {
+  const rng = seededRng((cx * 73856093) ^ (cz * 19349663) ^ WORLD_SEED);
+  const spots: THREE.Matrix4[] = [];
+  for (let i = 0; i < 40; i++) {
+    const x = (cx + rng()) * CHUNK, z = (cz + rng()) * CHUNK;
+    const h = getHeightAt(x, z);
+    if (biomeAt(x, z, h) !== "forest") continue;
+    if (PADS.some((p) => Math.hypot(x - p.x, z - p.z) < p.radius + 6)) continue;
+    const s = 0.8 + rng() * 0.7;
+    spots.push(new THREE.Matrix4().compose(
+      new THREE.Vector3(x, h, z),
+      new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), rng() * Math.PI * 2),
+      new THREE.Vector3(s, s, s),
+    ));
+  }
+  if (!spots.length) return;
+  const tree = new THREE.InstancedMesh(sharedTreeGeometry, sharedTreeMaterial, spots.length);
+  spots.forEach((m, i) => tree.setMatrixAt(i, m));
+  tree.castShadow = true;
+  scene.add(tree); // track per chunk-key and remove alongside the chunk
+}
+```
+
+(`seededRng` is the one from `$genex-threejs-game-content`'s reference —
+share it. `sharedTreeGeometry`/`sharedTreeMaterial` are module-level ONE-time
+allocations: per-chunk geometry allocation is the classic memory leak here.
+Real trees come from `$genex-threejs-procedural-vegetation`; a cone-on-
+cylinder placeholder is fine until it loads.)
+
+## Grounding the player
+
+For the character/vehicle, the cheap path is the canonical function itself —
+`y = getHeightAt(x, z)` plus a small offset for walking, with slopes from the
+same finite differences as the normals. Move to per-chunk Rapier heightfield
+colliders (`$genex-threejs-physics-rapier`) when projectiles, ragdolls, or
+rolling props need true collision — build them only for the chunks around the
+player, and from the SAME `getHeightAt`, never a copy.

package/templates/skills/genex-threejs-skill-router/SKILL.md

@@ -43,6 +43,8 @@ map, execution order, and acceptance gate.
 | eye adaptation, tone mapping, LUT grading, output color | `$genex-threejs-exposure-color-grading` |
 | shared depth/normal/velocity ownership and multi-pass ordering | `$genex-threejs-image-pipeline` |
 | fixed-view diagnostics, seed sweeps, temporal and budget evidence | `$genex-threejs-visual-validation` |
+| game content named in the plural or a content genre: quests, objectives, NPCs, dialogue, shops, inventory, loot, XP/progression, an RPG/adventure/story game — **mandatory whenever the ask names content**, and its content contract is written before the asset batch | `$genex-threejs-game-content` |
+| a big/open world: kilometers of terrain, multiple regions or locations, exploration, points of interest, biomes, world streaming | `$genex-threejs-open-world` |
 | the 2D interface — HUD, menus, pause/win/lose screens, loaders, lobby, on-screen text and buttons, UI state flow — **mandatory for every game**, and its "Plan the UI first" gate runs right after the concept is locked | `$genex-threejs-game-ui` |
 | a cinematic menu — main menu/title/pause/victory/defeat/lobby/credits with a looping generated video backdrop behind DOM buttons | `$genex-ai-menu` |
 | a cohesive art-directed HUD — generated sprite set (matched frames, masks, icons in one style) wired with masked fills | `$genex-ai-hud` |
@@ -73,6 +75,24 @@ while the game is being built — they never block a playable v0, and the game i
 not done, published, or handed off until they've been picked up (`npx genex wait`)
 and wired in.
 
+**Content is mandatory routing when the ask names it:** if the request names
+game content in the plural — quests, enemies, bosses, locations, spells, items,
+factions — or a content genre (an RPG, an adventure, an open world, a story
+game), load `$genex-threejs-game-content` and write its **content contract**
+into the same plan message as the UI gate, BEFORE the asset batch: every
+plural noun of the request becomes a countable line (how many quests and what
+chain, which locations, what progression), plus the minute-ten answer. Those
+lines are hard floors exactly like the sprite HUD — the game is not done,
+published, or handed off while a contract line is missing, and shrinking one
+is a structured question to the user, never a silent cut ("vertical slice
+first" is a build order, not a smaller destination). A request that says
+**big/open world** also loads `$genex-threejs-open-world` and fixes the
+world's scale as a number in the same plan — world size comes from streamed
+terrain, never from fog hiding the edges of a small plane. This routing
+exists because the failure it prevents is invisible to every visual gate: a
+"Skyrim-like big world with quests" can pass every look floor as a
+300-meter single-quest vignette.
+
 **The look is planned up front too:** right after the UI gate, lock the visual
 direction in the same plan block — the camera rig + pointer bucket
 (`$genex-threejs-camera-direction`), the renderer baseline (tone mapping,

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

@@ -16,7 +16,22 @@ Three.js release or branch, and do not blindly copy demo architecture.
 ## Execution order
 
 1. Define the game contract: player verb, win/interaction loop, target device,
-   camera distance, scene scale, motion, and frame budget.
+   camera distance, scene scale, motion, and frame budget. **When the request
+   names content in the plural (quests, enemies, locations, bosses, items) or
+   a content genre (RPG, adventure, open world, story game), the contract has
+   a second half — the content contract from `$genex-threejs-game-content`:**
+   every plural noun becomes a countable line (N quests and their chain, N
+   named locations, N enemy types and which are bosses, the progression axis,
+   the economy's sources and sinks), plus the minute-ten answer ("what is the
+   player doing ten minutes in?"). Write it BEFORE step 3's art enqueue and
+   before the asset batch — the asset set derives from it, and a world shaped
+   around the wrong assets can't be reshaped later. A **big/open world** ask
+   additionally fixes the world's scale class as a number here via
+   `$genex-threejs-open-world` — kilometers of streamed terrain, never one
+   fogged plane. Scope belongs to the user: shipping fewer or smaller than
+   the ask requires their explicit OK through a structured question — a
+   "vertical slice first" is a build order, never a license to shrink the
+   destination silently.
 2. Wire player identity before any boot code: `$genex-threejs-embed-auth` is
    mandatory for every game (`initEmbed(...)` + the `waitForPlayer()` gate) —
    saves, leaderboards, and multiplayer auth all come from it.
@@ -189,6 +204,18 @@ without them (Cursor), the same order simply runs sequentially and the
 - **Verification runner.** Browser evidence — screenshots, control presses,
   the menu loop-seam watch, in-situ checks of placed art — can run in a
   subagent while the main agent keeps building.
+- **Content module fan-out (big scopes).** When the content contract names a
+  big world or several content systems, serial hand-typing is what runs out
+  of session: split the gameplay modules across parallel subagents instead —
+  one each for world/terrain, quest + dialogue DATA, enemies/AI, items/
+  economy — against a short written module contract (the shared state
+  object's shape, the event names, the content tables from
+  `$genex-threejs-game-content`, exact file ownership). Ship the
+  walking-skeleton v0 preview FIRST, then let the content agents land behind
+  it — the preview cadence and a long parallel build are not in conflict:
+  the user walks the skeleton while the world grows. Each subagent reports
+  deviations from the module contract; the main agent reconciles and stays
+  the only writer of the entry point.
 
 Hard rules: **one writer per file** — each subagent owns a disjoint file set
 (the HUD worker owns the hud modules and `public/assets/hud/`, the shepherd
@@ -209,7 +236,13 @@ and the look floor (the step-4 renderer baseline + named post stack actually
 built; every placed 2D/media piece — decals, posters, in-world screens —
 screenshot-verified in situ; no UI element left as default browser CSS; no
 placeholder primitive left where a generated asset was
-planned)**. These floors gate `npx genex publish` and the
+planned)**, **plus the content floor whenever a step-1 content contract
+exists: every countable line of the contract is present and reachable in the
+shipped game, or the user explicitly re-scoped it in chat. "Big world"
+shipped as one small fogged arena, "quests" shipped as a single kill
+counter, a village of textured huts where nobody speaks — each is a scope
+violation the same way a CSS-placeholder HUD is, and it gates publish the
+same way.** These floors gate `npx genex publish` and the
 final handoff of a session the same way — "I never said it was done" is not
 an exemption. The list below applies to routed *visual-system* scenes, and each
 system-specific item (debug views, seed manifests, tier knobs) applies only when
@@ -233,8 +266,9 @@ A routed Genex scene is incomplete until it exposes:
 **Publishing IS calling it done.** Before `npx genex publish`, every completion
 gate above must pass — sprite HUD wired, Escape pause working, branded loader
 with its key art, fonts loaded, renderer baseline + one built post effect,
-world dressing placed or validly waived. If any is still pending, say which
-and publish only after an explicit go-ahead.
+world dressing placed or validly waived, and the content contract's
+countables present or explicitly re-scoped by the user. If any is still
+pending, say which and publish only after an explicit go-ahead.
 
 Do not invent unavailable Genex service APIs. When preparing a game for Genex
 publishing or multiplayer, inspect the project first. Prefer clean boundaries: