@vgai/editor 0.2.0

package/template/server/rooms/arena-room.ts

@@ -0,0 +1,420 @@
+/**
+ * ArenaRoom — multiplayer tag game with game phases and NPC bots.
+ *
+ * Server-authoritative: the server owns tag state, validates proximity,
+ * runs the phase state machine, and makes NPC behavior decisions.
+ * Clients send position input; server broadcasts everything via Schema sync.
+ *
+ * Phase flow:
+ *   lobby → countdown (3s) → playing (60s) → scoreboard (5s) → countdown …
+ *
+ * Tag rules:
+ *   - One player is "it" (taggerId). Server checks proximity each tick.
+ *   - Tagged player becomes "it". 1.5s cooldown prevents instant re-tag.
+ *   - Non-taggers accumulate score each tick.
+ *
+ * NPCs:
+ *   - Configurable bot count (0–6), spawned on create, stored in the same players MapSchema.
+ *   - Server picks behavior (idle/patrol/chase/flee) + target position.
+ *   - Client handles smooth navmesh pathfinding.
+ */
+
+import { Room, type Client } from 'colyseus';
+import { Schema, MapSchema, type } from '@colyseus/schema';
+
+// --- Constants ---
+
+const COLORS = [0xff6644, 0x44ff99, 0x4499ff, 0xffee44, 0xff44bb, 0x44ffee, 0xaa44ff, 0xff4488];
+const NAMES = ['Coral', 'Mint', 'Sky', 'Gold', 'Rose', 'Teal', 'Violet', 'Crimson'];
+const NPC_COLOR = 0x888888;
+const MAX_NPCS = 6;
+const SPAWN_RADIUS = 5;
+
+const MIN_PLAYERS = 2; // humans + NPCs
+const COUNTDOWN_SECS = 3;
+const ROUND_SECS = 60;
+const SCOREBOARD_SECS = 5;
+
+const TAG_RADIUS_SQ = 2.25; // 1.5 meters squared
+const TAG_COOLDOWN_SECS = 1.5;
+const FLEE_RADIUS_SQ = 100; // 10 meters squared
+
+const SIM_INTERVAL_MS = 50; // 20 Hz
+
+// NPC patrol waypoint routes
+const PATROL_ROUTES = [
+  [
+    { x: -12, z: -12 },
+    { x: 12, z: -12 },
+    { x: 12, z: 12 },
+    { x: -12, z: 12 },
+  ],
+  [
+    { x: -8, z: 0 },
+    { x: 0, z: -8 },
+    { x: 8, z: 0 },
+    { x: 0, z: 8 },
+  ],
+];
+
+// --- Schema definitions ---
+
+export class ArenaPlayerSchema extends Schema {
+  @type('string') sessionId = '';
+  @type('string') name = '';
+  @type('uint32') color = 0;
+  @type('float32') x = 0;
+  @type('float32') y = 0;
+  @type('float32') z = 0;
+  @type('float32') rotY = 0;
+  @type('float32') speed = 0;
+  @type('uint8') isGrounded = 1;
+  @type('boolean') isNPC = false;
+  @type('uint16') score = 0;
+  @type('string') npcBehavior = 'idle';
+}
+
+export class ArenaState extends Schema {
+  @type({ map: ArenaPlayerSchema }) players = new MapSchema<ArenaPlayerSchema>();
+  @type('string') taggerId = '';
+  @type('float32') tagCooldown = 0;
+  @type('string') phase = 'lobby';
+  @type('float32') phaseTimer = 0;
+  @type('uint8') roundNumber = 0;
+  @type('string') hostId = '';
+}
+
+// --- NPC brain (server-side only, not synced) ---
+
+interface NPCBrain {
+  behavior: 'idle' | 'patrol' | 'chase' | 'flee';
+  waypointIndex: number;
+  routeIndex: number;
+  targetX: number;
+  targetZ: number;
+}
+
+// --- Helpers ---
+
+function randomSpawnPosition(): { x: number; y: number; z: number } {
+  const angle = Math.random() * Math.PI * 2;
+  return {
+    x: Math.cos(angle) * SPAWN_RADIUS,
+    y: 0,
+    z: Math.sin(angle) * SPAWN_RADIUS,
+  };
+}
+
+function randomTagger(state: ArenaState): string {
+  const ids = [...state.players.keys()];
+  if (ids.length === 0) return '';
+  return ids[Math.floor(Math.random() * ids.length)]!;
+}
+
+// --- Room ---
+
+export class ArenaRoom extends Room {
+  state = new ArenaState();
+  patchRate = 50;
+
+  private colorIndex = 0;
+  private npcBrains = new Map<string, NPCBrain>();
+
+  onCreate(options?: { botCount?: number }) {
+    // Spawn NPC bots (count from room creator, default 2, max 6)
+    const npcCount = Math.max(0, Math.min(MAX_NPCS, options?.botCount ?? 2));
+    this.spawnNPCs(npcCount);
+
+    // Handle start_game from host
+    this.onMessage('start_game', (client) => {
+      if (client.sessionId !== this.state.hostId) return;
+      if (this.state.phase !== 'lobby') return;
+      this.state.phase = 'countdown';
+      this.state.phaseTimer = COUNTDOWN_SECS;
+    });
+
+    // Handle client input messages
+    this.onMessage('input', (client, data: {
+      x: number; y: number; z: number;
+      rotY: number; speed: number; isGrounded: number;
+    }) => {
+      const player = this.state.players.get(client.sessionId);
+      if (player) {
+        player.x = data.x;
+        player.y = data.y;
+        player.z = data.z;
+        player.rotY = data.rotY;
+        player.speed = data.speed;
+        player.isGrounded = data.isGrounded;
+      }
+    });
+
+    // Server simulation loop (20 Hz)
+    const dt = SIM_INTERVAL_MS / 1000;
+    this.setSimulationInterval(() => {
+      this.updatePhase(dt);
+      this.updateTag(dt);
+      this.updateNPCs();
+      this.moveNPCsTowardTargets(dt);
+    }, SIM_INTERVAL_MS);
+  }
+
+  onJoin(client: Client, options?: { color?: number; name?: string }) {
+    const idx = this.colorIndex % COLORS.length;
+    const color = (options?.color != null) ? options.color : COLORS[idx]!;
+    const name = options?.name ?? NAMES[idx]!;
+    this.colorIndex++;
+
+    const pos = randomSpawnPosition();
+    const player = new ArenaPlayerSchema();
+    player.sessionId = client.sessionId;
+    player.name = name;
+    player.color = color;
+    player.x = pos.x;
+    player.y = pos.y;
+    player.z = pos.z;
+
+    this.state.players.set(client.sessionId, player);
+
+    // First human player becomes the host
+    if (!this.state.hostId) {
+      this.state.hostId = client.sessionId;
+    }
+  }
+
+  onLeave(client: Client, _code?: number) {
+    this.state.players.delete(client.sessionId);
+
+    // If tagger left, reassign
+    if (this.state.taggerId === client.sessionId && this.state.phase === 'playing') {
+      this.state.taggerId = randomTagger(this.state);
+      this.state.tagCooldown = TAG_COOLDOWN_SECS;
+    }
+
+    // If host left, reassign to next human player
+    if (this.state.hostId === client.sessionId) {
+      this.state.hostId = '';
+      for (const [id, p] of this.state.players) {
+        if (!p.isNPC) {
+          this.state.hostId = id;
+          break;
+        }
+      }
+    }
+  }
+
+  onDispose() {
+    // Room cleanup
+  }
+
+  // --- NPC spawning ---
+
+  private spawnNPCs(count: number) {
+    for (let i = 0; i < count; i++) {
+      const npcId = `npc_${i}`;
+      const npc = new ArenaPlayerSchema();
+      npc.sessionId = npcId;
+      npc.name = `Bot-${String.fromCharCode(65 + i)}`; // Bot-A, Bot-B, Bot-C, ...
+      npc.color = NPC_COLOR;
+      npc.isNPC = true;
+      const pos = randomSpawnPosition();
+      npc.x = pos.x;
+      npc.y = pos.y;
+      npc.z = pos.z;
+      this.state.players.set(npcId, npc);
+
+      const route = PATROL_ROUTES[i % PATROL_ROUTES.length]!;
+      this.npcBrains.set(npcId, {
+        behavior: 'idle',
+        waypointIndex: 0,
+        routeIndex: i % PATROL_ROUTES.length,
+        targetX: route[0]!.x,
+        targetZ: route[0]!.z,
+      });
+    }
+  }
+
+  // --- Phase state machine ---
+
+  private updatePhase(dt: number) {
+    switch (this.state.phase) {
+      case 'lobby':
+        // Wait for host to send 'start_game'
+        break;
+
+      case 'countdown':
+        this.state.phaseTimer -= dt;
+        if (this.state.phaseTimer <= 0) {
+          this.state.phase = 'playing';
+          this.state.phaseTimer = ROUND_SECS;
+          this.state.roundNumber++;
+          this.state.taggerId = randomTagger(this.state);
+          this.state.tagCooldown = TAG_COOLDOWN_SECS;
+          for (const player of this.state.players.values()) {
+            player.score = 0;
+            const pos = randomSpawnPosition();
+            player.x = pos.x;
+            player.y = pos.y;
+            player.z = pos.z;
+          }
+        }
+        break;
+
+      case 'playing':
+        this.state.phaseTimer -= dt;
+        if (this.state.phaseTimer <= 0 || this.state.players.size < MIN_PLAYERS) {
+          this.state.phase = 'scoreboard';
+          this.state.phaseTimer = SCOREBOARD_SECS;
+        }
+        break;
+
+      case 'scoreboard':
+        this.state.phaseTimer -= dt;
+        if (this.state.phaseTimer <= 0) {
+          if (this.state.players.size >= MIN_PLAYERS) {
+            this.state.phase = 'countdown';
+            this.state.phaseTimer = COUNTDOWN_SECS;
+          } else {
+            this.state.phase = 'lobby';
+            this.state.phaseTimer = 0;
+          }
+        }
+        break;
+    }
+  }
+
+  // --- Tag proximity check ---
+
+  private updateTag(dt: number) {
+    if (this.state.phase !== 'playing') return;
+
+    if (this.state.tagCooldown > 0) this.state.tagCooldown -= dt;
+
+    // Increment scores for non-taggers
+    for (const player of this.state.players.values()) {
+      if (player.sessionId !== this.state.taggerId) {
+        player.score++;
+      }
+    }
+
+    // Check tag proximity
+    if (this.state.tagCooldown > 0) return;
+
+    const tagger = this.state.players.get(this.state.taggerId);
+    if (!tagger) return;
+
+    for (const [id, player] of this.state.players) {
+      if (id === this.state.taggerId) continue;
+      const dx = tagger.x - player.x;
+      const dz = tagger.z - player.z;
+      if (dx * dx + dz * dz < TAG_RADIUS_SQ) {
+        this.state.taggerId = id;
+        this.state.tagCooldown = TAG_COOLDOWN_SECS;
+        break;
+      }
+    }
+  }
+
+  // --- NPC behavior decisions ---
+
+  private updateNPCs() {
+    for (const [id, npc] of this.state.players) {
+      if (!npc.isNPC) continue;
+      const brain = this.npcBrains.get(id);
+      if (!brain) continue;
+
+      if (this.state.phase !== 'playing') {
+        brain.behavior = 'idle';
+        npc.npcBehavior = 'idle';
+        npc.speed = 0;
+        continue;
+      }
+
+      const isTagged = this.state.taggerId === id;
+
+      if (isTagged) {
+        // CHASE: find nearest non-tagger
+        brain.behavior = 'chase';
+        let nearestDistSq = Infinity;
+        let nearest: ArenaPlayerSchema | null = null;
+        for (const [pid, p] of this.state.players) {
+          if (pid === id) continue;
+          const dx = npc.x - p.x;
+          const dz = npc.z - p.z;
+          const dSq = dx * dx + dz * dz;
+          if (dSq < nearestDistSq) {
+            nearestDistSq = dSq;
+            nearest = p;
+          }
+        }
+        if (nearest) {
+          brain.targetX = nearest.x;
+          brain.targetZ = nearest.z;
+        }
+        npc.speed = 6.25;
+      } else {
+        const tagger = this.state.players.get(this.state.taggerId);
+        if (tagger) {
+          const dx = npc.x - tagger.x;
+          const dz = npc.z - tagger.z;
+          const dSq = dx * dx + dz * dz;
+
+          if (dSq < FLEE_RADIUS_SQ) {
+            // FLEE
+            brain.behavior = 'flee';
+            const dist = Math.sqrt(dSq) || 1;
+            brain.targetX = Math.max(-18, Math.min(18, npc.x + (dx / dist) * 8));
+            brain.targetZ = Math.max(-18, Math.min(18, npc.z + (dz / dist) * 8));
+            npc.speed = 5.6;
+          } else {
+            // PATROL
+            brain.behavior = 'patrol';
+            const route = PATROL_ROUTES[brain.routeIndex]!;
+            const wp = route[brain.waypointIndex]!;
+            const dwx = npc.x - wp.x;
+            const dwz = npc.z - wp.z;
+            if (dwx * dwx + dwz * dwz < 4.0) {
+              brain.waypointIndex = (brain.waypointIndex + 1) % route.length;
+              const next = route[brain.waypointIndex]!;
+              brain.targetX = next.x;
+              brain.targetZ = next.z;
+            } else {
+              brain.targetX = wp.x;
+              brain.targetZ = wp.z;
+            }
+            npc.speed = 3.1;
+          }
+        } else {
+          brain.behavior = 'patrol';
+          npc.speed = 3.1;
+        }
+      }
+
+      npc.npcBehavior = brain.behavior;
+    }
+  }
+
+  // --- Server-side NPC movement (straight-line toward target) ---
+
+  private moveNPCsTowardTargets(dt: number) {
+    for (const [id, npc] of this.state.players) {
+      if (!npc.isNPC) continue;
+      const brain = this.npcBrains.get(id);
+      if (!brain || brain.behavior === 'idle') continue;
+
+      const dx = brain.targetX - npc.x;
+      const dz = brain.targetZ - npc.z;
+      const dist = Math.sqrt(dx * dx + dz * dz);
+      if (dist < 0.5) continue;
+
+      const moveSpeed = brain.behavior === 'chase' ? 5.0
+        : brain.behavior === 'flee' ? 4.5
+        : 2.5;
+
+      const step = Math.min(moveSpeed * dt, dist);
+      npc.x += (dx / dist) * step;
+      npc.z += (dz / dist) * step;
+      npc.rotY = Math.atan2(-dx, -dz);
+    }
+  }
+}

package/template/server/rooms/game-room.ts

@@ -0,0 +1,162 @@
+/**
+ * GameRoom — multiplayer arena with collectible orbs.
+ *
+ * Uses @colyseus/schema state sync (the idiomatic Colyseus pattern).
+ * Server mutates Schema state directly; Colyseus encodes deltas and
+ * syncs them to all clients automatically.
+ *
+ * Messages (client → server only):
+ *   position  { x, y, z }   — client movement input
+ *
+ * Everything else (players, orbs, scores) is synchronized via Schema
+ * state: new joiners receive the full state automatically, and ongoing
+ * changes are delta-encoded at the patch rate (~20 Hz).
+ */
+
+import { Room, type Client } from 'colyseus';
+import { Schema, MapSchema, type } from '@colyseus/schema';
+
+// --- Constants ---
+
+const COLORS = [0xff6644, 0x44ff99, 0x4499ff, 0xffee44, 0xff44bb, 0x44ffee, 0xaa44ff, 0xff4488];
+const NAMES  = ['Coral', 'Mint', 'Sky', 'Gold', 'Rose', 'Teal', 'Violet', 'Crimson'];
+const ARENA_HALF = 7.5;
+const SPAWN_RADIUS = 5;
+const MAX_ORBS = 6;
+const COLLECT_RADIUS_SQ = 1.0;
+const ORB_RESPAWN_MS = 3_000;
+const SIM_INTERVAL_MS = 50;
+
+// --- Schema definitions ---
+
+class PlayerSchema extends Schema {
+  @type('string') sessionId = '';
+  @type('string') name = '';
+  @type('uint32') color = 0;
+  @type('float32') x = 0;
+  @type('float32') y = 0;
+  @type('float32') z = 0;
+  @type('uint16') score = 0;
+}
+
+class OrbSchema extends Schema {
+  @type('string') id = '';
+  @type('float32') x = 0;
+  @type('float32') z = 0;
+}
+
+class GameState extends Schema {
+  @type({ map: PlayerSchema }) players = new MapSchema<PlayerSchema>();
+  @type({ map: OrbSchema }) orbs = new MapSchema<OrbSchema>();
+}
+
+// --- Helpers ---
+
+let nextOrbId = 0;
+
+function randomSpawnPosition(): { x: number; y: number; z: number } {
+  const angle = Math.random() * Math.PI * 2;
+  return {
+    x: Math.cos(angle) * SPAWN_RADIUS,
+    y: 0,
+    z: Math.sin(angle) * SPAWN_RADIUS,
+  };
+}
+
+function randomOrbPosition(): { x: number; z: number } {
+  return {
+    x: (Math.random() - 0.5) * ARENA_HALF * 1.6,
+    z: (Math.random() - 0.5) * ARENA_HALF * 1.6,
+  };
+}
+
+// --- Room ---
+
+export class GameRoom extends Room {
+  state = new GameState();
+  patchRate = 50;
+
+  private colorIndex = 0;
+  // Orb respawns are counted in simulation ticks, not `this.clock` timers:
+  // this room must also run browser-hosted under @vgai/p2p-colyseus
+  // (VGAI_P2P builds), whose compat `Room` has no `clock`. Drive ALL timing
+  // from `setSimulationInterval` — it exists in both runtimes.
+  private orbRespawnTicks: number[] = [];
+
+  onCreate() {
+    // Handle client messages
+    this.onMessage('position', (client, position: { x: number; y: number; z: number }) => {
+      const player = this.state.players.get(client.sessionId);
+      if (player) {
+        player.x = Math.max(-ARENA_HALF, Math.min(ARENA_HALF, position.x));
+        player.y = position.y;
+        player.z = Math.max(-ARENA_HALF, Math.min(ARENA_HALF, position.z));
+      }
+    });
+
+    // Spawn initial orbs
+    for (let i = 0; i < MAX_ORBS; i++) {
+      this.spawnOrb();
+    }
+
+    // Server game loop at 20 Hz — check orb collection, tick pending respawns
+    this.setSimulationInterval(() => {
+      for (let i = this.orbRespawnTicks.length - 1; i >= 0; i--) {
+        if (--this.orbRespawnTicks[i]! <= 0) {
+          this.orbRespawnTicks.splice(i, 1);
+          this.spawnOrb();
+        }
+      }
+
+      for (const [orbId, orb] of this.state.orbs) {
+        for (const player of this.state.players.values()) {
+          const dx = player.x - orb.x;
+          const dz = player.z - orb.z;
+          if (dx * dx + dz * dz < COLLECT_RADIUS_SQ) {
+            player.score++;
+            this.state.orbs.delete(orbId);
+            this.orbRespawnTicks.push(Math.ceil(ORB_RESPAWN_MS / SIM_INTERVAL_MS));
+            break; // one collection per orb per tick
+          }
+        }
+      }
+    }, SIM_INTERVAL_MS);
+  }
+
+  onJoin(client: Client, options?: { color?: number; name?: string }) {
+    const idx = this.colorIndex % COLORS.length;
+    const color = (options?.color != null) ? options.color : COLORS[idx]!;
+    const name = options?.name ?? NAMES[idx]!;
+    this.colorIndex++;
+
+    const pos = randomSpawnPosition();
+    const player = new PlayerSchema();
+    player.sessionId = client.sessionId;
+    player.name = name;
+    player.color = color;
+    player.x = pos.x;
+    player.y = pos.y;
+    player.z = pos.z;
+    player.score = 0;
+
+    this.state.players.set(client.sessionId, player);
+  }
+
+  onLeave(client: Client, _code?: number) {
+    this.state.players.delete(client.sessionId);
+  }
+
+  onDispose() {
+    // Room cleanup
+  }
+
+  private spawnOrb() {
+    const id = `orb_${nextOrbId++}`;
+    const pos = randomOrbPosition();
+    const orb = new OrbSchema();
+    orb.id = id;
+    orb.x = pos.x;
+    orb.z = pos.z;
+    this.state.orbs.set(id, orb);
+  }
+}

package/template/server/rooms.ts

@@ -0,0 +1,15 @@
+/**
+ * Room registry — defines all available Colyseus rooms, passed to
+ * `startColyseus({ rooms, ... })` (colyseus-setup.ts) to call server.define()
+ * for each. Imported by the e2e showcase harness
+ * (packages/editor/e2e/helpers/colyseus.ts) and the unit-test in-process
+ * loopback server (packages/editor/test/helpers/colyseus-loopback.ts).
+ */
+
+import { GameRoom } from './rooms/game-room.js';
+import { ArenaRoom } from './rooms/arena-room.js';
+
+export const rooms = [
+  { name: 'game_room', handler: GameRoom },
+  { name: 'arena_room', handler: ArenaRoom },
+];

package/template/server/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false,
+
+    "strict": true,
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["."]
+}

package/template/src/data/README.md

@@ -0,0 +1,40 @@
+# src/data — data assets
+
+Designer-tunable values live here: `<name>.data.json` (the values, with a
+`"$schema"` line) governed by `<name>.schema.ts` (Zod, engineer-owned) and its
+emitted `<name>.schema.json` (`npm run emit-schemas`, committed). `tuning.*` +
+`tuning.ts` (the engine `defineData` handle) are the shipped worked example —
+copy that trio for each new asset and register it in `assets.ts` (one list,
+feeding both `npm run emit-schemas` and the build-time check that fails
+`npm run build` loud on invalid data or a dangling `"file#key"` ref; `vgai
+doctor <folder>` runs the same checks). Never hardcode a tunable as a constant in
+game code — see "Tunable values → a data asset" in this project's CLAUDE.md,
+and `docs/DATA-TOOLS-DESIGN.md` in the engine checkout for the design.
+
+Two blessed shapes, and only these (they're what the editor's DATA tab can
+render as real widgets): a **singleton** — one `z.object` config whose fields
+are scalars (number/string/boolean/enum), optionally grouped one or two
+levels deep in nested `z.object`s (the tab renders groups as sub-forms) — or
+a **table** — `z.record(z.string(), rowSchema)` with a flat row schema,
+rendered as a grid (this Zod version's `z.record` needs a key schema AND a
+value schema — the single-arg `z.record(rowSchema)` shorthand is Zod-3-only
+and throws here). Anything the tab can't type (arrays, deep nesting, unions)
+degrades to a raw-JSON cell that refuses invalid commits — prefer
+flattening, or a table, when a designer should tune it.
+
+Table assets also get a spreadsheet-friendly bulk-edit path in the DATA tab:
+**Export CSV** downloads the whole table (`key,<row fields>` header, one row
+per data key); **Import CSV** is a WHOLE-TABLE REPLACE — any row the sheet
+doesn't mention is deleted — and ATOMIC: if any cell fails to coerce to its
+column's field kind (e.g. non-numeric text in a `number` column), nothing is
+written; fix the sheet and re-import. `"$schema"` is never a CSV column —
+it's carried over from the file automatically.
+
+Cross-asset fields (one table's row pointing at another asset — an enemy's
+drop pointing at an item) should use `dataRef('<target-stem>')`
+(`@engine/data/data-ref`) in the schema instead of a bare `z.string()`: the
+DATA tab then renders that field as a `stem#key` PICKER (listing the target
+file's own keys) instead of free text, and `vgai doctor`/`npm run build`
+catch it if the target file is ever renamed or deleted — not just if the key
+inside it goes missing. Read it back with `getRef(targetHandle, row.field)`
+(pass the target's own `defineData` handle, not a string) from game code.

package/template/src/data/assets.ts

@@ -0,0 +1,31 @@
+/**
+ * Data-asset registry — the ONE list of this project's data assets
+ * (docs/DATA-TOOLS-DESIGN.md §6.7). Two consumers, one list:
+ *
+ *   - `emit-schemas.ts` (root): emits each `<name>.schema.json` and
+ *     validates each `<name>.data.json` (`npm run emit-schemas`).
+ *   - `vite.config.ts`: feeds the engine's `vgaiDataCheck` build plugin, so
+ *     `npm run build` FAILS LOUD on a data file that no longer matches its
+ *     schema or a dangling `"file#key"` ref — drift is caught at build time,
+ *     not by a player.
+ *
+ * Adding a data asset: copy the `tuning.*` trio (see ./README.md), then add
+ * one line here. An unregistered `.data.json` still loads and hot-reloads,
+ * but gets no emitted schema and no build-time check (the build prints a
+ * warning naming this file).
+ *
+ * KEEP THIS MODULE SIDE-EFFECT-FREE and dependency-light (schemas + zod
+ * only): `vite.config.ts` imports it at config-load time, before any dev
+ * server or build exists.
+ */
+import type { z } from 'zod';
+import { TuningSchema } from './tuning.schema';
+
+export interface ProjectDataAsset {
+  /** Asset stem: the files are `src/data/<name>.data.json` / `<name>.schema.ts` / emitted `<name>.schema.json`. */
+  readonly name: string;
+  /** The governing Zod schema (the `.schema.ts` export). */
+  readonly schema: z.ZodType;
+}
+
+export const dataAssets: readonly ProjectDataAsset[] = [{ name: 'tuning', schema: TuningSchema }];

package/template/src/data/tuning.data.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "./tuning.schema.json",
+  "boxSpinSpeed": 0.8,
+  "boxColor": "#4488ff"
+}