@volter/game-editor 0.5.65

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

@@ -0,0 +1,274 @@
+/**
+ * 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
+ *   __vgai:debugCommand { name, args, requestId } — a `locus: 'server'`
+ *     debug command's client leg (the "Multiplayer locus" note,
+ *     build plan Task 4.2); see
+ *     `DEBUG_COMMANDS`/`onCreate` below.
+ *
+ * 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;
+/** How much room a joining player gets from the nearest orb — twice the
+ *  collect radius, so a spawn never sits on the edge of a pickup either. */
+const SPAWN_CLEARANCE_SQ = COLLECT_RADIUS_SQ * 4;
+/** Evenly spaced candidate angles `chooseSpawnPosition` scans. Enough that a
+ *  clear angle always falls inside the widest gap the orbs can leave. */
+const SPAWN_ANGLE_SAMPLES = 64;
+
+// --- 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;
+
+/**
+ * The `locus: 'server'` debug-command table (Task 4.2) — one worked example,
+ * `give-score`, demonstrating the same declared-fixture rule as client-side
+ * debug commands: mutates the AUTHORITATIVE
+ * (server) copy of state, never client prediction. Gated by
+ * `allowDebugCommands` — see `onCreate` — so a production `npm run server`
+ * boot never accepts these unless explicitly opted in.
+ */
+const DEBUG_COMMANDS: Record<string, (room: GameRoom, client: Client, args: unknown[]) => unknown> =
+  {
+    'give-score': (room, client, args) => {
+      const amount = typeof args[0] === 'number' ? args[0] : 1;
+      const player = room.state.players.get(client.sessionId);
+      if (!player) throw new Error(`give-score: no player for session "${client.sessionId}"`);
+      player.score += amount;
+      return { score: player.score };
+    },
+  };
+
+/**
+ * Pick a spawn point on the spawn circle that is CLEAR of every orb.
+ *
+ * A raw random angle can drop a joining player straight onto a pickup, and
+ * the very next simulation tick collects it: a free point nobody's rules
+ * awarded, and — because the roll happens at join — a room whose score is
+ * non-deterministic from tick zero. That is exactly what made
+ * `tests/logic/room.test.ts` fail intermittently, and no assertion tolerance
+ * would have fixed it, because the defect is here.
+ *
+ * The spawn stays random: `angleOffset` is a random angle, and this only
+ * rejects the angles that land on a pickup. Scanning a fixed number of evenly
+ * spaced candidates (rather than re-rolling until clear) makes the search
+ * terminate in bounded time; if every candidate were blocked — impossible
+ * with the current constants, but the code must not pretend otherwise — the
+ * roomiest one wins.
+ *
+ * Pure, and exported, so the clearance is provable in `tests/logic/` without
+ * booting a server.
+ */
+export function chooseSpawnPosition(
+  orbs: Iterable<{ x: number; z: number }>,
+  angleOffset: number = Math.random() * Math.PI * 2,
+): { x: number; y: number; z: number } {
+  const placed = [...orbs];
+  let best = { x: SPAWN_RADIUS, y: 0, z: 0 };
+  let bestClearanceSq = -1;
+  for (let i = 0; i < SPAWN_ANGLE_SAMPLES; i++) {
+    const angle = angleOffset + (i * Math.PI * 2) / SPAWN_ANGLE_SAMPLES;
+    const candidate = {
+      x: Math.cos(angle) * SPAWN_RADIUS,
+      y: 0,
+      z: Math.sin(angle) * SPAWN_RADIUS,
+    };
+    let clearanceSq = Number.POSITIVE_INFINITY;
+    for (const orb of placed) {
+      const dx = candidate.x - orb.x;
+      const dz = candidate.z - orb.z;
+      clearanceSq = Math.min(clearanceSq, dx * dx + dz * dz);
+    }
+    if (clearanceSq >= SPAWN_CLEARANCE_SQ) return candidate;
+    if (clearanceSq > bestClearanceSq) {
+      bestClearanceSq = clearanceSq;
+      best = candidate;
+    }
+  }
+  return best;
+}
+
+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, so
+  // the room's timing is driven entirely by `setSimulationInterval` and is
+  // reproducible from the tick count alone.
+  private orbRespawnTicks: number[] = [];
+
+  onCreate(options?: { allowDebugCommands?: boolean }) {
+    // Off by default (FROZEN DECISION: env-var OR room-option) — the loopback harness/
+    // the loopback harness (`../loopback.ts`) opt in via the room option; a
+    // plain `npm run server` boot never accepts debug commands unless
+    // VGAI_ALLOW_DEBUG_COMMANDS is set in its environment.
+    const debugCommandsAllowed =
+      options?.allowDebugCommands === true || Boolean(process.env['VGAI_ALLOW_DEBUG_COMMANDS']);
+
+    // 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));
+      }
+    });
+
+    this.onMessage(
+      '__vgai:debugCommand',
+      (client, message: { name: string; args?: unknown[]; requestId: string }) => {
+        if (!debugCommandsAllowed) {
+          client.send('__vgai:debugCommandResult', {
+            requestId: message.requestId,
+            ok: false,
+            error: 'debug commands disabled',
+          });
+          return;
+        }
+        const handler = DEBUG_COMMANDS[message.name];
+        if (!handler) {
+          client.send('__vgai:debugCommandResult', {
+            requestId: message.requestId,
+            ok: false,
+            error: `debug: no server command registered under "${message.name}"`,
+          });
+          return;
+        }
+        try {
+          const result = handler(this, client, message.args ?? []);
+          client.send('__vgai:debugCommandResult', {
+            requestId: message.requestId,
+            ok: true,
+            result,
+          });
+        } catch (err) {
+          client.send('__vgai:debugCommandResult', {
+            requestId: message.requestId,
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      },
+    );
+
+    // 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 = chooseSpawnPosition(this.state.orbs.values());
+    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 { ArenaRoom } from './rooms/arena-room.js';
+import { GameRoom } from './rooms/game-room.js';
+
+export const rooms = [
+  { name: 'game_room', handler: GameRoom, matchBy: ['vgaiPlaytest'] },
+  { name: 'arena_room', handler: ArenaRoom, matchBy: ['vgaiPlaytest'] },
+];

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/bot/QaTester.tsx

@@ -0,0 +1,35 @@
+/**
+ * The QA tester's HANDS ON THE FRAME — the one piece of the playtesting loop
+ * that must live in the world tree, because acting through input each sim
+ * tick IS frame work. Everything else about the tester (its doors, its run
+ * state, its repertoire) is plain application code in
+ * `src/bot/tester-station.ts`, reached directly as a running module by the
+ * Tester contribution and `vgai eval`.
+ *
+ * The tester's hands run in the INPUT phase — before everything. Fiber sorts
+ * `useFrame` callbacks ascending, and this world's own behavior hooks sit at
+ * 0 (game logic / animation) or -1 (a movement solve landing before
+ * `<Physics>` steps). A virtual action must already be written when the first
+ * of those reads it, so the tester runs below the lot of them. Negative by
+ * necessity, never positive: a positive priority takes over rendering and
+ * blacks out the world (check-idioms W8).
+ *
+ * Cost when idle: one no-op frame callback. Nothing rendered.
+ */
+
+import { useFrame } from '@react-three/fiber';
+import { useEffect } from 'react';
+import { stepTester, stopTesterForUnmount } from './tester-station';
+
+const TESTER_FRAME_PRIORITY = -100;
+
+export function QaTester() {
+  // A run cannot outlive the frame that steps it: stopping Play unmounts this
+  // component, and the cleanup ends any run still seated so the next session
+  // starts clean.
+  useEffect(() => stopTesterForUnmount, []);
+  useFrame((_, dt) => {
+    stepTester(dt);
+  }, TESTER_FRAME_PRIORITY);
+  return null;
+}

package/template/src/bot/behaviors.ts

@@ -0,0 +1,203 @@
+/**
+ * The QA TESTER's REPERTOIRE — everything this game's bot knows how to do,
+ * as ordinary game-owned code.
+ *
+ * The tester is the person holding the controller: it plays THIS game, at sim
+ * speed, through the real input pipeline. What it can be asked to do is
+ * game-specific by nature, so this file is a plain `Record<string, behavior>`.
+ * There is deliberately NO behavior tree, utility system,
+ * goal stack, or standardized brain here: a behavior is a function that gets
+ * stepped once per tick and returns whether it is still going. A game that
+ * wants a planner writes one inside its own behavior; nothing here needs to
+ * know.
+ *
+ * The repertoire ACCRETES per mechanic. When a slice ships a mechanic, the
+ * tester learns to exercise it — a new entry below, in the same breath as that
+ * mechanic's exported setup function and readout. That is what makes "give the bot a goal"
+ * a thing the developer can say at the REPL instead of hand-flying the game.
+ *
+ * A behavior may ONLY act through `ctx.hands` (virtual input, which merges
+ * into the same keys feed a human's keyboard drives) and read whatever state
+ * the game exposes. It never teleports, never writes game state, and never
+ * calls a setup function: buying ARRIVAL at a situation is the developer's
+ * job (ordinary exported functions reached from the REPL), and playing it is
+ * the tester's.
+ *
+ * Goals are started with `hireTester` from `tester-station.ts`; the repertoire
+ * is returned by `describeTester`. Both are ordinary exports on the running
+ * module — see `src/bot/QaTester.tsx`.
+ */
+
+import { z } from 'zod';
+
+/** What a behavior reports after one tick. `running` means "give me another
+ *  tick"; the other two end the run. */
+export type TesterOutcome = 'running' | 'done' | 'failed';
+
+/** One sim tick, as the behavior sees it. `dt` is the fixed step the engine
+ *  loop just ran; `elapsed` is sim seconds since this goal started — the unit
+ *  every budget in a behavior should be written in. */
+export interface TesterTick {
+  readonly dt: number;
+  readonly elapsed: number;
+}
+
+/**
+ * The tester's HANDS: the only way a behavior is allowed to touch the game.
+ *
+ * Every method here is a virtual actuation of one of the game's OWN declared
+ * input actions, which the engine merges into the same reads a real key
+ * produces (edges included). There is no state-write door on this interface on
+ * purpose — see this module's header.
+ */
+export interface TesterHands {
+  /** Every input action this game actually declared. A behavior that needs an
+   *  action should check this rather than assume: driving an undeclared action
+   *  throws, which fails the run loudly. */
+  actions(): readonly string[];
+  /** Hold (or level-set) an action — `true`/`false` for a digital action, a
+   *  number for a scalar, `{x, y}` for a vector2. Exactly what holding and
+   *  releasing a key does. */
+  set(action: string, value: boolean | number | { x: number; y: number }): void;
+  /** One honest press, carried through a full tick. */
+  tap(action: string): void;
+  /** Let go of everything this tester is holding. */
+  release(): void;
+}
+
+/** What a behavior is handed when it is created. */
+export interface TesterContext {
+  readonly hands: TesterHands;
+  /** Publish what the tester is doing, to `bot.status` and the in-game HUD.
+   *  Cheap; call it when something changes, not every tick. */
+  report(patch: { step?: string; progress?: number; note?: string }): void;
+}
+
+/**
+ * One thing the tester knows how to do.
+ *
+ * `create` runs once when the goal starts and returns the per-tick step
+ * function, so anything the behavior needs to remember is an ordinary closure
+ * variable. `params` (when declared) is parsed by the driver BEFORE `create`,
+ * so a mistyped goal fails at the door with zod's own message rather than
+ * halfway through a run.
+ */
+export interface TesterBehavior<P = unknown> {
+  /** One line, written for the developer choosing a goal — say what the tester
+   *  will DO and name the params it takes. This is the discovery surface. */
+  readonly summary: string;
+  readonly params?: z.ZodType;
+  create(ctx: TesterContext, params: P): (tick: TesterTick) => TesterOutcome;
+}
+
+const sweepParams = z
+  .object({
+    actions: z
+      .array(z.string())
+      .optional()
+      .describe('Which declared actions to press, in order. Defaults to all of them.'),
+    holdSimSeconds: z
+      .number()
+      .positive()
+      .default(0.75)
+      .describe('How long to hold each action, in sim seconds.'),
+  })
+  .strict();
+
+type SweepParams = z.infer<typeof sweepParams>;
+
+/**
+ * `sweep` — the STARTER behavior, and the one a real game deletes first.
+ *
+ * It holds each of the game's declared input actions in turn for a sim-time
+ * budget, reporting as it goes. That is a genuinely useful first goal (it
+ * proves the controller is wired: bindings exist, something consumes them,
+ * the world reacts), and it is deliberately the least intelligent thing a
+ * tester can do — pressing every button is not playing the game. The moment
+ * this project has a mechanic, replace this with a goal named after what the
+ * tester is trying to ACHIEVE (`reach-the-ledge`, `kill-the-first-wave`), and
+ * let the repertoire grow from there.
+ *
+ * On the neutral starter world it fails, loudly and correctly: a project that
+ * declares no input actions has no controller for a tester to hold, and
+ * reporting `done` for having pressed nothing would be a lie the whole live
+ * loop is built to prevent.
+ */
+const sweep: TesterBehavior<SweepParams> = {
+  summary:
+    'Hold each declared input action in turn for a sim-time budget — the starter goal that ' +
+    'proves the controller is wired. Params: {actions?: string[], holdSimSeconds?: number}. ' +
+    "Replace it with this game's first real goal (see src/bot/behaviors.ts).",
+  params: sweepParams,
+  create(ctx, params) {
+    const actions = params.actions ?? [...ctx.hands.actions()];
+    const hold = params.holdSimSeconds;
+
+    if (actions.length === 0) {
+      return () => {
+        ctx.report({
+          note:
+            'this project declares no input actions, so the tester has no controller to hold — ' +
+            'declare your actions in src/input.ts (and read them from the mechanic that cares), ' +
+            'then give the tester a goal that plays the mechanic it drives',
+        });
+        return 'failed';
+      };
+    }
+
+    let index = -1;
+    let releaseAt = 0;
+
+    return (tick) => {
+      if (tick.elapsed < releaseAt) return 'running';
+
+      const finished = actions[index];
+      if (finished !== undefined) ctx.hands.set(finished, false);
+
+      index += 1;
+      const next = actions[index];
+      if (next === undefined) {
+        ctx.report({ progress: actions.length, note: 'swept every declared action' });
+        return 'done';
+      }
+
+      releaseAt = tick.elapsed + hold;
+      ctx.hands.set(next, true);
+      ctx.report({ step: `hold ${next}`, progress: index });
+      return 'running';
+    };
+  },
+};
+
+/**
+ * THE repertoire. Add a behavior by adding a key — nothing else registers it,
+ * and nothing outside this file decides what a goal means.
+ */
+export const testerBehaviors: Record<string, TesterBehavior> = {
+  sweep,
+};
+
+/** The repertoire as data, for the Tester contribution and the live REPL. */
+export function describeTesterBehaviors(): Array<{ name: string; summary: string }> {
+  return Object.entries(testerBehaviors).map(([name, behavior]) => ({
+    name,
+    summary: behavior.summary,
+  }));
+}
+
+/**
+ * Look up a goal by name, or throw naming the whole repertoire — an unknown
+ * goal is a typo or a behavior nobody has written yet, and both are answered
+ * by seeing what the tester actually knows.
+ */
+export function resolveTesterBehavior(name: string): TesterBehavior {
+  const behavior = testerBehaviors[name];
+  if (behavior) return behavior;
+  const known = Object.keys(testerBehaviors);
+  throw new Error(
+    `hireTester: this game's tester has no behavior named "${name}". ` +
+      (known.length === 0
+        ? 'Its repertoire is empty — add one in src/bot/behaviors.ts.'
+        : `It knows: ${known.join(', ')}. Add another in src/bot/behaviors.ts.`),
+  );
+}