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

package/templates/skills/genex-threejs-game-content/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: genex-threejs-game-content
+description: Turn a content-shaped request — quests, NPCs, dialogue, shops, loot, XP — into a countable content contract and the data-driven systems that ship it. Use when the ask names game content in the plural or a content genre (RPG, adventure, story, open world), BEFORE the asset batch, and before calling such a game done.
+---
+
+# Genex Three.js Game Content
+
+The most common way a content-shaped request fails is not bad code — it is the
+ask silently shrinking: "quests" ships as one hardcoded integer, "NPCs" as
+empty textured huts, "a big world" as one small fogged plane, while every
+visual floor passes, because content is invisible to a screenshot. This skill
+gives content the same teeth the look has: a countable contract written up
+front, data-driven systems that make each contract line cheap to ship, and a
+floor that gates publish.
+
+## The content contract — write it before the asset batch
+
+Run this the moment the game concept is locked, in the SAME plan message as
+`$genex-threejs-game-ui`'s UI gate, whenever the request names 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, a survival
+game). **Walk every plural noun of the request and make each one a countable
+line.** The template:
+
+```
+CONTENT CONTRACT — <game>
+world:       <size class, as a number: one arena | a district (~500 m) | open world (km-class — $genex-threejs-open-world)>
+locations:   <N, named: village, crypt, bandit camp, watchtower, boss lair…>
+quests:      <N total — a main chain of M gated steps + side quests; each giver named>
+NPCs:        <N speaking (quest givers, merchants) + M flavor villagers>
+enemies:     <N types + where they spawn; which are bosses and what makes each boss FIGHT differently>
+progression: <what grows: XP/levels, gear tiers, learnable abilities — the numbers and their rewards>
+economy:     <currency sources AND sinks — what the player earns and what they spend it on>
+minute ten:  <one sentence: what is the player DOING ten minutes in, and why is it different from minute one?>
+```
+
+Rules that make the contract real:
+
+- **It comes before the asset batch.** The asset set derives from the
+  contract — a world with six locations and four enemy types needs a
+  different `npx genex model` list than one arena, and finding that out after
+  the batch means the world gets shaped around the wrong assets.
+- **Every line is a floor.** Publish and the final handoff wait for the
+  contract's countables exactly the way they wait for the sprite HUD: a
+  request that said "quests" is not done with one; a request that said "big
+  world" is not done with an arena.
+- **Scope belongs to the user.** Building a small first slice is the right
+  ORDER (`$genex-threejs-game-ui`'s v0 beat still applies) — but the slice is
+  a milestone on the way to the contract, never a quiet replacement for it.
+  If the full ask genuinely doesn't fit, shrinking any line is a structured
+  question to the user with real options — never a silent cut justified as
+  "standard practice".
+- **Minute ten is the design test.** If the honest answer is "the same sixty
+  seconds, again", the contract needs another beat (a new area unlocks, a
+  quest chain escalates, a build comes online) before any polish work.
+
+## Data-driven, or you won't finish in one session
+
+The reason a solo agent can ship seven quests and seventeen items in an
+afternoon is architecture, not typing speed:
+
+- **Systems read tables; content lives in tables.** The quest engine, the
+  dialogue walker, the merchant screen, and the spawner are each written
+  ONCE; quest #5, item #12, and enemy #4 are table rows. If adding a quest
+  means touching engine code, the engine is wrong.
+- **Hand-author the beats, table-drive the bulk, seed the placement.** Quest
+  prose, boss mechanics, and location identities deserve human-quality
+  authoring; stats, stocks, and rewards are data; trees, rocks, and chest
+  scatter come from a seeded RNG so "more world" costs zero authoring.
+- **One event bus.** Quests advance on events the game already emits
+  (`enemy:died`, `item:pickup`, `chest:opened`, `npc:talked`, `zone:entered`)
+  — the quest system subscribes; combat and loot never know quests exist.
+  This is also what makes quest logic testable in isolation.
+
+The full engine — quest defs + state machine, dialogue trees with quest
+hooks, merchant stocks, XP curve — is in
+[references/content-tables.md](references/content-tables.md) as copy-paste
+modules. Copy them and fill the tables; don't re-derive the shape.
+
+## Quests: defs + events, never an integer
+
+The minimum honest quest system is a table of defs and an event-driven state
+machine (`locked → available → active → ready → done`), with prereq gating for
+the main chain:
+
+```ts
+type Objective =
+  | { kind: "kill"; target: string; count: number }
+  | { kind: "collect"; item: string; count: number }
+  | { kind: "reach"; location: string }
+  | { kind: "talk"; npc: string };
+
+type QuestDef = {
+  id: string;
+  giver: string;            // NPC id — every quest has a face, not a board
+  prereq?: string;          // quest id that must be done first (main chain)
+  title: string;
+  brief: string;            // 2–3 sentences of authored prose, not filler
+  objective: Objective;
+  rewards: { gold?: number; xp?: number; items?: string[] };
+};
+```
+
+Progress comes only from the event bus (see the reference for the ~60-line
+engine). A tracked quest gets a compass/journal marker
+(`$genex-threejs-game-ui` inventories the journal as a screen element), and
+turn-in happens in dialogue — handing in a quest should feel like talking to
+a person, not watching a counter flip.
+
+## Dialogue: trees with quest hooks
+
+Quest givers and merchants speak. The walker is a dozen lines (reference file)
+over nodes of `{ text, options: [{ label, next | action }] }`; what makes it a
+QUEST system is three dynamic option states injected per NPC: **offer** (quest
+available → "I might have work for you"), **remind** (active → restate the
+objective), **turn-in** (ready → hand rewards, open the next chain link). Add
+a couple of lore branches per named NPC — three authored lines is the
+difference between a person and a signpost. A quest board is an acceptable
+extra for arcade-shaped games; it is never the replacement for speaking
+NPCs when the ask said "NPCs".
+
+## Items, shops, and an economy that closes
+
+An item catalog (id, kind, price, stats), stack-based inventory, and merchant
+stock tables per vendor NPC — all data (reference file). The rule that keeps
+it a game: **currency needs sinks.** Gold the player can only accumulate is a
+score with a coin icon; gold that buys potions, a better sword, and a spell
+tome is an economy. Price the first upgrade to be affordable after the first
+quest, and let drops + chest loot + quest rewards all feed the same wallet.
+
+## Progression: something must grow
+
+Pick at least one growth axis and wire its rewards into the quest/enemy
+tables: an XP curve (`xpNext = 100 * level ** 1.4` is a fine default) with
+flat stat gains per level, gear tiers on the merchant, or learnable abilities
+gated behind tomes/trainers. The contract names which; "nothing grows" is what
+makes minute ten feel like minute one.
+
+## NPCs: the minimum that reads as alive
+
+A named NPC with a role, a home spot, an idle bob, a face-the-player turn
+within a few meters, and dialogue reads as a person — schedules and pathing
+are optional upgrades, speech is not. Place speaking NPCs (givers, merchants)
+by hand at their locations; scatter flavor villagers with one-line barks from
+a table. An empty textured hut village fails the "NPCs" line of any contract.
+For host-simulated NPCs/enemies in multiplayer, `$genex-threejs-multiplayer`
+owns the authority rules.
+
+## Content that can't dead-end — check before shipping
+
+- A kill/collect quest counts progress made BEFORE acceptance (or the brief
+  says why not) — "kill 5 bandits" accepted after clearing the camp must not
+  strand at 0/5.
+- A quest item from a unique source (a boss drop, a one-time chest) must
+  persist until picked up — the source never respawns, so expiring the drop
+  dead-ends the chain.
+- The main chain gates on prereqs, not on geography alone — reaching the
+  final lair early should show a locked door or a warning, not a sequence
+  break that skips the story.
+- The turn-in NPC is reachable after the objective (didn't die in the wave,
+  isn't locked behind the boss arena).
+- Saves restore quest state AND its world side-effects — the opened chest
+  stays open, the armed boss stays armed. Quest stages, inventory, XP, and
+  gold go in the per-player slot via `$genex-threejs-embed-auth`.
+
+## Wiring into the rest of the pack
+
+- World layout, terrain, and location placement at scale:
+  `$genex-threejs-open-world` (the contract's `world:` line decides whether
+  it loads).
+- Quest journal, tracker, toasts, vendor screens: inventory them at
+  `$genex-threejs-game-ui`'s gate — they are screen elements like any other.
+- Level-ups, quest completion, and boss kills are exactly the "moments" the
+  feel pass layers feedback on: `$genex-threejs-game-feel` + a real
+  `npx genex sfx` fanfare (`$genex-ai-sfx`).
+- Location set pieces and speaking-NPC meshes: `$genex-ai-model` /
+  `$genex-ai-character` — generated assets decorate the contract's landmarks;
+  they never decide how many exist.
+
+## Failure modes to catch
+
+- "Quests" (plural, in the ask) shipped as one quest — a stage integer with
+  hardcoded strings and no giver.
+- A village of textured huts where nobody speaks.
+- A gold counter with nothing to spend it on.
+- No growth axis: the player at minute thirty plays exactly like minute one.
+- The contract posted, then quietly abandoned when the first slice previewed
+  well — the slice is a milestone, not the destination.
+- Contract lines silently shrunk without a structured question to the user.

package/templates/skills/genex-threejs-game-content/references/content-tables.md

@@ -0,0 +1,269 @@
+# Genex game content — copy-paste systems
+
+Four small modules that turn contract lines into shipped content: an event
+bus, a quest engine, a dialogue walker with quest hooks, and items/economy +
+XP. Copy them, fill the tables, and keep content OUT of engine code — adding
+a quest, an item, or a vendor must always be a table edit.
+
+All snippets are plain vanilla-ts (no enums, no decorators) and assume a
+single shared game-state object `G` you already have (player stats, wallet,
+the scene). Adapt names, not shapes.
+
+## 1. Event bus — the only coupling
+
+```ts
+// events.ts — combat, loot, and movement EMIT; quests and UI SUBSCRIBE.
+type GameEvent =
+  | { type: "enemy:died"; enemyKind: string }
+  | { type: "item:pickup"; item: string; count: number }
+  | { type: "chest:opened"; chestId: string }
+  | { type: "npc:talked"; npc: string }
+  | { type: "zone:entered"; location: string };
+
+type Handler = (e: GameEvent) => void;
+const handlers: Handler[] = [];
+
+export function onEvent(h: Handler): void {
+  handlers.push(h);
+}
+export function emit(e: GameEvent): void {
+  for (const h of handlers) h(e);
+}
+```
+
+## 2. Quest engine — defs are data, progress is events
+
+```ts
+// quests.ts
+import { onEvent } from "./events.ts";
+
+type Objective =
+  | { kind: "kill"; target: string; count: number }
+  | { kind: "collect"; item: string; count: number }
+  | { kind: "reach"; location: string }
+  | { kind: "talk"; npc: string };
+
+type QuestDef = {
+  id: string;
+  giver: string;
+  prereq?: string;
+  title: string;
+  brief: string;
+  turnIn: string; // authored prose for the hand-in moment
+  objective: Objective;
+  rewards: { gold?: number; xp?: number; items?: string[] };
+};
+
+// CONTENT — the whole quest list lives here. Main chain via prereq; the
+// prose is authored, not generated filler. Counts must match the contract.
+export const QUESTS: QuestDef[] = [
+  {
+    id: "q_wolves",
+    giver: "elder",
+    title: "Teeth in the Tall Grass",
+    brief:
+      "Wolves have taken the shepherd's flock and now they circle the palisade at dusk. Thin the pack before someone's child is next.",
+    turnIn: "Five pelts. The flock sleeps easy tonight — and so do we. Take this.",
+    objective: { kind: "kill", target: "wolf", count: 5 },
+    rewards: { gold: 40, xp: 60 },
+  },
+  {
+    id: "q_amulet",
+    giver: "elder",
+    prereq: "q_wolves",
+    title: "What the Crypt Keeps",
+    brief:
+      "Our founder's amulet lies in the old crypt east of the fields. The dead have grown restless around it — bring it back, and mind the narrow dark.",
+    turnIn: "The amulet… after all these years. You have the village's gratitude, and its coin.",
+    objective: { kind: "collect", item: "founder_amulet", count: 1 },
+    rewards: { gold: 80, xp: 120, items: ["potion_health"] },
+  },
+  // …side quests: no prereq, different givers, different objective kinds.
+];
+
+type QuestStatus = "locked" | "available" | "active" | "ready" | "done";
+type QuestState = { status: QuestStatus; progress: number };
+
+export const questState = new Map<string, QuestState>();
+for (const q of QUESTS) {
+  questState.set(q.id, { status: q.prereq ? "locked" : "available", progress: 0 });
+}
+
+const def = (id: string): QuestDef => QUESTS.find((q) => q.id === id)!;
+
+export function accept(id: string): void {
+  const s = questState.get(id)!;
+  if (s.status !== "available") return;
+  s.status = "active";
+  // Contract check "can't dead-end": count pre-acceptance progress where the
+  // fiction allows it (kills already made), or reset knowingly.
+}
+
+export function turnIn(id: string): { gold: number; xp: number; items: string[] } | null {
+  const s = questState.get(id)!;
+  if (s.status !== "ready") return null;
+  s.status = "done";
+  for (const q of QUESTS) {
+    if (q.prereq === id && questState.get(q.id)!.status === "locked") {
+      questState.get(q.id)!.status = "available"; // next chain link opens
+    }
+  }
+  const r = def(id).rewards;
+  return { gold: r.gold ?? 0, xp: r.xp ?? 0, items: r.items ?? [] };
+}
+
+function bump(q: QuestDef, s: QuestState, amount = 1): void {
+  const needed = "count" in q.objective ? q.objective.count : 1;
+  s.progress = Math.min(needed, s.progress + amount);
+  if (s.progress >= needed) s.status = "ready"; // journal + marker flip to "return"
+}
+
+onEvent((e) => {
+  for (const q of QUESTS) {
+    const s = questState.get(q.id)!;
+    if (s.status !== "active") continue;
+    const o = q.objective;
+    if (o.kind === "kill" && e.type === "enemy:died" && e.enemyKind === o.target) bump(q, s);
+    if (o.kind === "collect" && e.type === "item:pickup" && e.item === o.item) bump(q, s, e.count);
+    if (o.kind === "reach" && e.type === "zone:entered" && e.location === o.location) bump(q, s);
+    if (o.kind === "talk" && e.type === "npc:talked" && e.npc === o.npc) bump(q, s);
+  }
+});
+```
+
+Journal UI, the tracked-quest compass marker, and toasts subscribe to the
+same state — inventory them as screen elements at `$genex-threejs-game-ui`'s
+gate. Persist `[...questState]` (plus world side-effects like opened chests)
+in the per-player slot via `$genex-threejs-embed-auth`.
+
+## 3. Dialogue walker — quest states become options
+
+```ts
+// dialogue.ts
+import { QUESTS, questState, accept, turnIn } from "./quests.ts";
+
+type DialogueOption = { label: string; next?: DialogueNode; action?: () => void };
+type DialogueNode = { text: string; options: DialogueOption[] };
+
+// CONTENT — per-NPC roots: greeting + a couple of authored lore branches.
+// Three real lines is the difference between a person and a signpost.
+const ROOTS: Record<string, DialogueNode> = {
+  elder: {
+    text: "Maren watches the road as she talks. “Strangers used to mean trade. Lately they mean trouble.”",
+    options: [
+      {
+        label: "Tell me about this village.",
+        next: {
+          text: "“Three generations behind this palisade. The crypt east of here is older than all of it — and lately, louder.”",
+          options: [],
+        },
+      },
+    ],
+  },
+  // blacksmith, herbalist… — every giver and merchant has a root.
+};
+
+// The whole walker: render node.text + numbered options; a click (or the
+// 1–9 key) runs option.action?.(), then shows option.next or closes. Emit
+// { type: "npc:talked", npc } when a conversation OPENS — that's what "talk"
+// objectives listen for.
+export function pickOption(node: DialogueNode, index: number): DialogueNode | null {
+  const opt = node.options[index];
+  if (!opt) return node;
+  opt.action?.();
+  return opt.next ?? null; // null = close the dialogue panel
+}
+
+export function openDialogue(npc: string): DialogueNode {
+  const root = ROOTS[npc];
+  const options = [...root.options];
+  for (const q of QUESTS) {
+    if (q.giver !== npc) continue;
+    const s = questState.get(q.id)!;
+    if (s.status === "available") {
+      options.unshift({
+        label: `[Quest] ${q.title}`,
+        next: {
+          text: q.brief,
+          options: [
+            { label: "I'll do it.", action: () => accept(q.id) },
+            { label: "Not now." },
+          ],
+        },
+      });
+    } else if (s.status === "active") {
+      options.unshift({ label: `[${q.title}] Remind me.`, next: { text: q.brief, options: [] } });
+    } else if (s.status === "ready") {
+      options.unshift({
+        label: `[Complete] ${q.title}`,
+        next: { text: q.turnIn, options: [] },
+        action: () => {
+          const r = turnIn(q.id);
+          // …grant r.gold / r.xp / r.items through your wallet + inventory.
+        },
+      });
+    }
+  }
+  return { text: root.text, options };
+}
+```
+
+## 4. Items, merchants, XP — the economy that closes
+
+```ts
+// items.ts
+type ItemDef = {
+  id: string;
+  kind: "weapon" | "armor" | "potion" | "quest" | "tome";
+  name: string;
+  price: number; // what merchants charge — the SINK side of the economy
+  stats?: { dmg?: number; armor?: number; heal?: number };
+};
+
+export const ITEMS: ItemDef[] = [
+  { id: "sword_iron", kind: "weapon", name: "Iron Sword", price: 120, stats: { dmg: 18 } },
+  { id: "potion_health", kind: "potion", name: "Health Draught", price: 25, stats: { heal: 40 } },
+  { id: "founder_amulet", kind: "quest", name: "Founder's Amulet", price: 0 },
+  // …the catalog. Price the first upgrade to land right after the first quest's gold.
+];
+
+// Merchant stock is per-NPC data — a second vendor is one more entry.
+export const STOCKS: Record<string, string[]> = {
+  blacksmith: ["sword_iron", "armor_leather"],
+  herbalist: ["potion_health", "potion_mana"],
+};
+
+// XP curve + level rewards: one growth axis, wired to quest/enemy rewards.
+export const xpNext = (level: number): number => Math.round(100 * level ** 1.4);
+export function addXp(player: { level: number; xp: number; maxHp: number; hp: number }, amount: number): void {
+  player.xp += amount;
+  while (player.xp >= xpNext(player.level)) {
+    player.xp -= xpNext(player.level);
+    player.level += 1;
+    player.maxHp += 12;
+    player.hp = player.maxHp; // level-up heals — a reward the player FEELS
+  }
+}
+```
+
+## Seeded placement — bulk content for free
+
+Scatter the non-authored bulk (chests, camps, flavor spawns) with a seeded
+RNG so the world is deterministic across loads and machines:
+
+```ts
+export function seededRng(seed: number): () => number {
+  let s = seed >>> 0;
+  return () => {
+    s = (s * 1664525 + 1013904223) >>> 0;
+    return s / 0xffffffff;
+  };
+}
+// const rng = seededRng(1337): place 10 chests at rng()-driven offsets around
+// locations, skip water/steep slopes via the world's height/biome lookups
+// ($genex-threejs-open-world), and hand-place only the authored few.
+```
+
+Hand-authored where it matters (quest prose, boss mechanics, unique loot),
+tables for the bulk, seeds for the scatter — that split is what lets one
+session ship the whole contract.

package/templates/skills/genex-threejs-open-world/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: genex-threejs-open-world
+description: Build a big explorable world that stays fast — seeded heightfield terrain with chunk streaming, biomes, points of interest, instanced scatter, and honest world bounds. Use when the ask says big or open world, multiple regions or locations, exploration, or any map beyond one arena — before the first terrain code, instead of one flat plane with fog.
+---
+
+# Genex Three.js Open World
+
+"Big world" in a request is a size class, not a mood. A 300 m plane with fog
+pulled in to hide the walls is an arena wearing a costume — the player finds
+the invisible wall in the first two minutes, and no amount of dressing
+survives that. This skill is the recipe for a world that is actually big —
+kilometers-class, streamed, varied — at a cost one session can afford.
+
+## Decide the scale first, as a number
+
+Put the world's size in the plan (and in the content contract's `world:` line
+when `$genex-threejs-game-content` is loaded — a big world exists to hold
+content, so the two skills almost always load together):
+
+- **One arena** (~100–300 m): only when the ask says so (a shooter map, a
+  sports pitch, a boss rush). Never the silent fallback for "big world".
+- **A district** (~500 m – 1 km): a town + surroundings; streaming optional.
+- **Open world** (2–4 km bounded): the default meaning of "big/open world" —
+  a dozen locations, real travel time between them, streamed terrain. Beyond
+  ~4 km you're spending budget on emptiness; density beats acreage.
+
+Bound the world honestly: an edge-mountain ring, a coastline, or a cliff
+reads as "the world ends here" — an invisible wall on a flat horizon reads as
+a bug. Fog is atmosphere and draw-distance management
+(`$genex-threejs-atmosphere-aerial-perspective` for the real thing), never a
+wall to hide how small the map is.
+
+## The scaling law: procedural fabric, generated landmarks
+
+The single decision that determines whether a big world is affordable:
+
+- **The world's FABRIC is procedural** — a seeded heightfield, instanced
+  vegetation, scattered rocks and props built from primitives and the
+  procedural skills (`$genex-threejs-procedural-vegetation`,
+  `$genex-threejs-procedural-geometry`). Procedural fabric costs the same at
+  4 km as at 300 m; that is what makes the size class reachable.
+- **Generated assets are LANDMARKS** — `npx genex model` set pieces placed at
+  points of interest (the village well, the boss lair gate, the shrine), a
+  ground texture (`npx genex texture --terrain`, UVs from `worldUV` — never a
+  hand-picked repeat), a skybox. Hero assets decorate the world's landmarks;
+  they never decide the world's size, because a world assembled from
+  hand-placed generated meshes caps out at a diorama.
+
+Wire generated pieces in as upgrades over procedural placeholders (the
+standard swap discipline), so the world is walkable at full size from the
+first hour.
+
+## One height function to rule everything
+
+Terrain is a seeded fBm heightfield (`$genex-threejs-procedural-fields` owns
+the noise craft) with ridges for drama, an edge-mountain ring for the bound,
+and **flattened pads blended in around each location** so structures sit on
+level ground. The load-bearing rule: **exactly one canonical
+`getHeightAt(x, z)`** that chunk meshing, physics grounding, placement
+scatter, NPC spawns, and the minimap all share. The moment a second height
+formula exists, trees float and feet sink — every large-world bug report
+starts there.
+
+Full copy-paste module — noise, fBm, location flattening, chunk manager,
+instanced scatter — in
+[references/terrain-streaming.md](references/terrain-streaming.md).
+
+## Stream chunks, budget the frame
+
+Build the terrain as fixed-size chunks (128 m is a good default) around the
+player: load radius ~5 chunks (~600 m view with fog), unload behind, and
+build queued chunks inside a **per-frame time budget** (a few ms) so streaming
+never hitches the game. Seam rule: compute normals with a one-vertex apron
+into the neighbor chunk, or every chunk border shows as a lighting crease.
+Far distance is fog + the skybox — a low-res far ring is an upgrade, not a
+requirement.
+
+Physics grounding: keep the character/vehicle on the ground via the canonical
+`getHeightAt` (cheap, always loaded) or per-chunk Rapier heightfield
+colliders (`$genex-threejs-physics-rapier`) when projectiles and ragdolls
+need real collision — but never build colliders for chunks the player isn't
+near.
+
+## Biomes: variety from two noise fields
+
+Two low-frequency noise fields (temperature, moisture) + altitude + slope
+give 4–7 biomes from one lookup: meadow, forest, marsh, desert, alpine, snow.
+The biome function drives everything downstream from ONE place — vertex
+colors or texture blend, vegetation species and density
+(`$genex-threejs-procedural-vegetation`, instanced), enemy spawn tables and
+ambient audio per biome (that's the content hookup). "Different locations" in
+an ask is only half-answered by placed structures; the other half is the
+ground itself changing as you travel.
+
+## Points of interest: the world's content skeleton
+
+A data table of locations — id, name, position, radius, builder function —
+is the spine the content contract hangs from (quest givers live somewhere;
+"locations: 8" means eight entries here):
+
+- **Density beats acreage:** a point of interest every ~300–500 m of travel
+  on the natural routes. A 4 km world with three POIs is emptier than a 1 km
+  world with eight.
+- Each location: terrain pad flattened (blend into the heightfield — see the
+  reference), a hand-authored builder (walls, tents, standing stones — merged
+  primitive geometry + generated landmark pieces), spawns, loot, and its
+  compass/minimap marker.
+- Light budget: point lights per location, hard cap world-wide (~6 active) —
+  swap distant ones for emissive materials (`$genex-threejs-lighting-design`
+  owns the walk).
+- Roads or worn paths between major POIs guide travel and double as the
+  navigation answer ("follow the road north beats a quest arrow").
+
+## Performance floors (the size class depends on them)
+
+- **Instancing for everything repeated**: trees, grass, rocks are
+  `InstancedMesh` per chunk — thousands of draw calls is the classic
+  big-world death; hundreds is the target.
+- **Merge static location geometry** per material into a handful of meshes.
+- Shadows at scale need a strategy, not defaults: a tight shadow camera
+  following the player, or cascades — `$genex-threejs-shadow-systems`.
+- Keep per-frame allocation out of the loop (reuse vectors), and keep chunk
+  building inside its time budget.
+- Phone-survivable stays the bar: pixel ratio cap, texture ≤ 2048², and the
+  chunk radius is the quality knob to shrink first.
+
+## Day/night: cheap and almost expected
+
+A big explorable world reads twice as alive with a sun cycle: one animated
+`DirectionalLight` angle + a palette lerp (sky, fog, ambient) + practical
+lights that matter at night. It's ~50 lines against the lighting rig
+(`$genex-threejs-lighting-design`), and it makes travel time feel like time.
+Optional — but when the ask says "like the big RPGs", this is one of the
+three things they mean.
+
+## Failure modes to catch
+
+- A flat plane with invisible walls and close fog shipped as "big world" —
+  the defining failure this skill exists to prevent.
+- Two height functions (mesh vs physics vs placement) drifting apart —
+  floating trees, buried chests.
+- Hand-placing every tree at world scale — placement must be seeded scatter
+  with biome rules, or the world stays empty.
+- Per-chunk geometry that never unloads or shares materials — memory climbs,
+  draw calls explode.
+- POIs as map dots only — a named location with nothing to do fails the
+  content contract it was meant to serve (`$genex-threejs-game-content`).
+- Seams: normal creases at every chunk border (missing apron), or texture
+  tiling picked by eye instead of `worldUV` (`$genex-ai-texture`).