@volter/game-editor 0.5.65

package/template/src/contributions/use-game-modules.ts

@@ -0,0 +1,80 @@
+/**
+ * THE ONE HOOK an editor contribution needs: this game's RUNNING module
+ * instances. Everything else about a dev surface is yours to imagine.
+ *
+ * The method (owner ruling: as native as possible, no imposed system):
+ * imagine what THIS game's studio would hang on its wall — the readings,
+ * the setup cheats, the dials, the charts — then write each surface as a
+ * plain TSX contribution in this folder (`*.inspector.tsx`,
+ * `*.utility.tsx`, `*.document.tsx`), in the game's own vocabulary, added
+ * when there is something to show. A contribution is ordinary React
+ * reading the game's own exported modules through this hook; agents reach
+ * the same modules through `vgai eval`'s
+ * `game.run(async ({ modules }) => await modules('src/sim/host.ts'))` — `modules` is an
+ * ASYNC RESOLVER taking a served path, never a table: the `await` is not
+ * optional, and reading a member off the unawaited promise throws a message
+ * saying so. `modules.loaded` lists the paths the running mount can hand you.
+ * There is no registry, no declaration call, and no prescribed sections.
+ * The worked reference is the datacenter-tycoon game's `src/tools/`.
+ *
+ * Why the hook exists at all: contributions load under the EDITOR's
+ * importer while the game's modules load under the mount's stamped URLs —
+ * a direct `import '../sim/host'` from a contribution would be a phantom
+ * second copy. `importGameModule` resolves the VERBATIM url the running
+ * graph loaded, so what a contribution reads IS the game. It takes
+ * `play.instanceId` EXPLICITLY: in a packaged editor the shell bundle and
+ * this source-served module are two copies of `game-module-access`, so
+ * injected module state cannot cross — the id the SDK already hands every
+ * contribution is the one channel that works in both hosts.
+ */
+import { importGameModule } from '@editor/game-module-access';
+import { useEffect, useState } from 'react';
+
+/** Load the running mount's instances of the named modules. `null` until
+ *  loaded; `error` when the mount refuses (not playing, module never
+ *  imported by the game). Re-resolves when `play` identity changes.
+ *
+ *  `play.instanceId` is passed to `importGameModule` EXPLICITLY: in a
+ *  packaged editor the shell bundle and this source-served module are two
+ *  copies of `game-module-access`, so the shell's injected focused-instance
+ *  provider is invisible here — the id the SDK already hands the face is
+ *  the one channel that works in both hosts. */
+export function useGameModules<T extends Record<string, string>>(
+  play: { readonly instanceId: string } | null,
+  paths: T,
+): { mods: { [K in keyof T]: Record<string, unknown> } | null; error: string | null } {
+  const [state, setState] = useState<{
+    mods: { [K in keyof T]: Record<string, unknown> } | null;
+    error: string | null;
+  }>({ mods: null, error: null });
+  const key = JSON.stringify(paths);
+  useEffect(() => {
+    if (!play) {
+      setState({ mods: null, error: null });
+      return;
+    }
+    let cancelled = false;
+    void (async () => {
+      try {
+        const entries = await Promise.all(
+          Object.entries(paths).map(async ([name, path]) => [
+            name,
+            await importGameModule(path, play.instanceId),
+          ]),
+        );
+        if (!cancelled) {
+          setState({ mods: Object.fromEntries(entries) as never, error: null });
+        }
+      } catch (error) {
+        if (!cancelled) {
+          setState({ mods: null, error: error instanceof Error ? error.message : String(error) });
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [play, key]);
+  return state;
+}

package/template/src/data/README.md

@@ -0,0 +1,17 @@
+# src/data — game data
+
+Rules and content live here as ordinary TypeScript literals, in modules
+named for the game concept: `player.ts`, `weapons.ts`, `levels.ts`.
+Create them when the brief supplies data. TypeScript checks their structure;
+editor panels read the data without determining how it is organized.
+
+- **Reading:** import the literal and read fields directly from the
+  mechanic that cares. Read per frame if you want live edits to land.
+- **Live dials:** write an ordinary editor contribution over the module
+  (`src/contributions/use-game-modules.ts` is the hook; writes on the running
+  module's object are live for the play).
+- **Committing a number:** edit the file. Vite HMR delivers it.
+
+Adding a table: write the literal, export its row type
+(`export type Row = (typeof rows)[keyof typeof rows];`), read it from the
+game. Nothing to register anywhere.

package/template/src/input.ts

@@ -0,0 +1,97 @@
+/**
+ * THIS GAME'S OWN INPUT STORE — the one place its actions are declared and
+ * held. Mechanics read it directly ({@link actionPressed}); the QA tester
+ * actuates it ({@link setVirtualAction}); the session input door
+ * reaches the SAME store by importing this running module through
+ * `game.run(({ modules }) => ...)`. No vgai import anywhere — input is
+ * application state, and the host merely gives the developer access to the
+ * module instance the game already uses.
+ *
+ * The neutral scaffold declares NO actions yet: a game should not inherit a
+ * control scheme before its brief supplies one. Add your actions to
+ * {@link gameActions}, map keys in {@link keyActions}, and read
+ * `actionPressed('jump')` from the mechanic that cares.
+ */
+
+/** Every input action this game declares. Empty until the game earns one. */
+export const gameActions = [] as const satisfies readonly string[];
+export type GameAction = (typeof gameActions)[number];
+
+export type ActionValue = boolean | number | { readonly x: number; readonly y: number };
+
+const virtual = new Map<string, ActionValue>();
+const keysDown = new Set<string>();
+
+/** Physical key code → action. Empty until {@link gameActions} has entries. */
+const keyActions: Readonly<Record<string, GameAction>> = {};
+
+export function isGameAction(value: string): value is GameAction {
+  return (gameActions as readonly string[]).includes(value);
+}
+
+function requireAction(action: string): GameAction {
+  if (!isGameAction(action)) {
+    throw new Error(
+      `Unknown input action "${action}" — this game declares ${
+        gameActions.length === 0 ? 'none yet (add yours in src/input.ts)' : gameActions.join(', ')
+      }.`,
+    );
+  }
+  return action;
+}
+
+/** The tester's and the session door's write path. */
+export function setVirtualAction(action: string, value: ActionValue): void {
+  virtual.set(requireAction(action), value);
+}
+
+/** Let go of everything virtual — a human taking the seat back never inherits
+ *  a held key. */
+export function clearVirtualActions(): void {
+  virtual.clear();
+}
+
+/** What a mechanic reads each frame: virtual actuation OR the real keyboard. */
+export function actionPressed(action: GameAction): boolean {
+  const held = virtual.get(action);
+  if (held === true) return true;
+  for (const [code, mapped] of Object.entries(keyActions)) {
+    if (mapped === action && keysDown.has(code)) return true;
+  }
+  return false;
+}
+
+/**
+ * Attach the physical keyboard half of the store, and hand back the detach.
+ *
+ * The caller is `<GameKeyboard/>` in `src/world.tsx`, whose effect cleanup runs
+ * the returned function when the world unmounts. That lifetime is the whole
+ * point: this used to attach at MODULE LOAD and nothing ever called the detach,
+ * so every Play→stop left three window listeners behind and the editor's realm
+ * audit reclaimed them with a standing console warning
+ * (`Instance 1 stopped without releasing 3 window/document listeners`). A
+ * listener whose owner cannot end it is a leak however small its handler is —
+ * attach it from the thing that unmounts.
+ *
+ * `target` is a parameter (not a captured `window`) so a test can attach a fake.
+ */
+export function attachKeyboard(target: Window): () => void {
+  const onKeyDown = (event: KeyboardEvent) => {
+    if (keyActions[event.code]) keysDown.add(event.code);
+  };
+  const onKeyUp = (event: KeyboardEvent) => {
+    keysDown.delete(event.code);
+  };
+  const onBlur = () => {
+    keysDown.clear();
+  };
+  target.addEventListener('keydown', onKeyDown);
+  target.addEventListener('keyup', onKeyUp);
+  target.addEventListener('blur', onBlur);
+  return () => {
+    target.removeEventListener('keydown', onKeyDown);
+    target.removeEventListener('keyup', onKeyUp);
+    target.removeEventListener('blur', onBlur);
+    keysDown.clear();
+  };
+}

package/template/src/lib/audio/capability.json

@@ -0,0 +1,4 @@
+{
+  "id": "audio",
+  "version": "0.1.1"
+}

package/template/src/lib/audio/sfx.ts

@@ -0,0 +1,255 @@
+/**
+ * The game's own SFX voice: a small Web Audio graph this project owns, and the
+ * `SystemAdapters.audio` registration that lets the host silence it.
+ *
+ * ## Why the game owns the context
+ *
+ * This world is an R3F root. An R3F root renders through react-three-fiber
+ * against the HOST's renderer, and the host supplies no mixer of its own —
+ * audio is the game's, built with Web Audio directly inside the tree. That is
+ * the seam doctrine working as designed: an absent capability is absent, not
+ * faked by the host.
+ *
+ * ## Why it is still mutable from the editor
+ *
+ * A game-owned context is only orphaned if nothing can see it. `SystemAdapters`
+ * is the seam for exactly this: the game DECLARES what it implements through
+ * its entry's `systems` export (`export const systems = { audio:
+ * sfxAudioSystem() }` in `src/systems.ts`), and from the moment the host
+ * installs it the editor's mute button, the Audio debugger tab and
+ * `Game.play.pause()`'s silence-on-pause all reach this graph — without the
+ * host fabricating a mixer it does not have, and without a component calling
+ * a host registration.
+ *
+ * The graph is deliberately tiny: one gain node (the game's whole "sfx bus")
+ * into the destination. Mute rides that node, so muting composes with the
+ * per-voice envelopes below instead of fighting them.
+ */
+
+import type { AudioAdapter, AudioGraphNode } from '@volter/editor-project/adapter';
+
+/** A one-shot blip: a falling/rising saw with an exponential decay. Frequencies
+ *  in Hz, `duration` in seconds, `volume` linear (0–1), `end` the frequency to
+ *  glide to (defaults to a steady tone). A no-op when this environment has no
+ *  Web Audio at all — headless CI, an SSR pass — which is why callers never
+ *  guard. */
+export type PlayTone = (frequency: number, duration: number, volume: number, end?: number) => void;
+
+export interface GainDuckOptions {
+  /** Gain while ducked, in linear amplitude. */
+  duckGain?: number;
+  /** Seconds to reach the ducked level. */
+  attack?: number;
+  /** Seconds to remain ducked before restoring. */
+  hold?: number;
+  /** Seconds to restore the resting gain. */
+  release?: number;
+}
+
+/**
+ * Coordinate ducking on an ordinary Web Audio gain parameter. The project
+ * keeps the native AudioParam — this helper only owns the easy-to-get-wrong
+ * cancel/hold/restore automation for repeated triggers.
+ */
+export function createGainDucker(
+  context: BaseAudioContext,
+  gain: AudioParam,
+  options: GainDuckOptions = {},
+): { trigger(): void; dispose(): void } {
+  const restingGain = gain.value;
+  const duckGain = Math.max(0, options.duckGain ?? 0.35);
+  const attack = Math.max(0, options.attack ?? 0.02);
+  const hold = Math.max(0, options.hold ?? 0.12);
+  const release = Math.max(0, options.release ?? 0.25);
+
+  return {
+    trigger(): void {
+      const now = context.currentTime;
+      gain.cancelAndHoldAtTime(now);
+      gain.linearRampToValueAtTime(duckGain, now + attack);
+      gain.setValueAtTime(duckGain, now + attack + hold);
+      gain.linearRampToValueAtTime(restingGain, now + attack + hold + release);
+    },
+    dispose(): void {
+      const now = context.currentTime;
+      gain.cancelScheduledValues(now);
+      gain.setValueAtTime(restingGain, now);
+    },
+  };
+}
+
+/** What {@link createGameSfx} hands back: the voice, the adapter to register,
+ *  and the teardown the mounting component owns. */
+export interface GameSfx {
+  readonly tone: PlayTone;
+  /** Expose this through the root entry's `systems.audio` so
+   *  host mute/pause reach the graph. `null` when there is no real context to
+   *  silence — registering a no-op adapter would tell the host this world's
+   *  audio is under control when there is no audio at all. */
+  readonly adapter: AudioAdapter | null;
+  /** Close the context. Nothing else owns it. */
+  dispose(): void;
+}
+
+/** The silent stand-in for an environment with no Web Audio (jsdom, a headless
+ *  bot run). It reports no adapter, so `Game.play.pause()` says out loud that
+ *  this world has no audio seam rather than pretending it silenced one. */
+const SILENT: GameSfx = {
+  tone: () => {},
+  adapter: null,
+  dispose: () => {},
+};
+
+export function createGameSfx({ maxVoices = 24 }: { maxVoices?: number } = {}): GameSfx {
+  const Ctor: typeof AudioContext | undefined =
+    typeof AudioContext !== 'undefined' ? AudioContext : undefined;
+  if (!Ctor) return SILENT;
+
+  const context = new Ctor();
+  const bus = context.createGain();
+  bus.gain.value = 1;
+  bus.connect(context.destination);
+
+  let muted = false;
+  let priorGain = bus.gain.value;
+  let voiceSequence = 0;
+  const voiceLimit = Math.max(1, Math.floor(maxVoices));
+  const voices: Array<{
+    id: number;
+    oscillator: OscillatorNode;
+    gain: GainNode;
+  }> = [];
+
+  const releaseVoice = (voice: (typeof voices)[number]): void => {
+    const index = voices.indexOf(voice);
+    if (index >= 0) voices.splice(index, 1);
+    voice.oscillator.disconnect();
+    voice.gain.disconnect();
+  };
+
+  const stopVoice = (voice: (typeof voices)[number]): void => {
+    voice.oscillator.onended = null;
+    try {
+      voice.oscillator.stop();
+    } catch {
+      // It ended between the pool check and the stop call.
+    }
+    releaseVoice(voice);
+  };
+
+  const adapter: AudioAdapter = {
+    resume: () => {
+      if (context.state === 'suspended') void context.resume();
+    },
+    setMuted(next: boolean): void {
+      if (next === muted) return;
+      muted = next;
+      // Restore to whatever the bus held before muting, never a hardcoded 1 —
+      // so a pause taken while already user-muted resumes muted.
+      if (next) {
+        priorGain = bus.gain.value;
+        bus.gain.value = 0;
+      } else {
+        bus.gain.value = priorGain;
+      }
+    },
+    isMuted: () => muted,
+    graphSnapshot(): AudioGraphNode[] {
+      return [
+        {
+          id: 'destination',
+          type: 'AudioDestinationNode',
+          label: 'Output',
+          outputs: [],
+          state: context.state,
+        },
+        { id: 'sfx', type: 'GainNode', label: 'Game SFX', outputs: ['destination'] },
+        ...voices.map((voice) => ({
+          id: `voice-${voice.id}`,
+          type: 'OscillatorNode',
+          label: `One-shot voice ${voice.id} (${voices.length}/${voiceLimit})`,
+          outputs: ['sfx'],
+          state: 'started',
+        })),
+      ];
+    },
+  };
+
+  return {
+    tone(frequency, duration, volume, end = frequency): void {
+      // Autoplay policy starts every context suspended; the page has had user
+      // activation long before a shot is fired, so this is the cheap unlock.
+      if (context.state === 'suspended') void context.resume();
+      while (voices.length >= voiceLimit) stopVoice(voices[0]!);
+      const now = context.currentTime;
+      const oscillator = context.createOscillator();
+      const gain = context.createGain();
+      const voice = { id: ++voiceSequence, oscillator, gain };
+      voices.push(voice);
+      oscillator.onended = () => releaseVoice(voice);
+      oscillator.type = 'sawtooth';
+      oscillator.frequency.setValueAtTime(frequency, now);
+      oscillator.frequency.exponentialRampToValueAtTime(Math.max(20, end), now + duration);
+      gain.gain.setValueAtTime(volume, now);
+      gain.gain.exponentialRampToValueAtTime(0.0001, now + duration);
+      oscillator.connect(gain).connect(bus);
+      oscillator.start(now);
+      oscillator.stop(now + duration);
+    },
+    adapter,
+    dispose(): void {
+      for (const voice of [...voices]) stopVoice(voice);
+      bus.disconnect();
+      void context.close();
+    },
+  };
+}
+
+// --- The one voice, module-owned ---------------------------------------------
+//
+// Created on first use, kept for the page's lifetime: browsers cap live
+// AudioContexts, an Edit→Play remount reuses the same graph, and the entry's
+// `systems` export needs the adapter to exist when the host installs it —
+// which is right after mount, long before the first gunshot.
+
+let active: GameSfx | null = null;
+
+/** The game's one voice. */
+export function gameSfx(): GameSfx {
+  active ??= createGameSfx();
+  return active;
+}
+
+/** Play one tone through the game's voice — the call every mechanic makes. */
+export const gameTone: PlayTone = (frequency, duration, volume, end) => {
+  gameSfx().tone(frequency, duration, volume, end);
+};
+
+/**
+ * The entry `systems` export's audio slot: a LAZY forwarding adapter over the
+ * voice (constructed on first actual call, so importing the entry in Edit
+ * mode builds no AudioContext), or the positive absence for an environment
+ * with no Web Audio at all (jsdom, a headless bot run) — decided without
+ * constructing anything, stated, never simulated.
+ */
+export function sfxAudioSystem(): AudioAdapter | { present: false; evidence: string } {
+  if (typeof AudioContext === 'undefined') {
+    return {
+      present: false,
+      evidence:
+        'no Web Audio in this environment — `typeof AudioContext === "undefined"` ' +
+        '(src/lib/audio/sfx.ts)',
+    };
+  }
+  const live = (): AudioAdapter => {
+    const adapter = gameSfx().adapter;
+    if (!adapter) throw new Error('sfx: the Web Audio voice failed to construct.');
+    return adapter;
+  };
+  return {
+    resume: () => live().resume?.(),
+    setMuted: (next) => live().setMuted(next),
+    isMuted: () => live().isMuted(),
+    graphSnapshot: () => live().graphSnapshot?.() ?? [],
+  };
+}

package/template/src/lib/react-root/capability.json

@@ -0,0 +1,4 @@
+{
+  "id": "react-root",
+  "version": "0.2.5"
+}

package/template/src/lib/react-root/index.ts

@@ -0,0 +1,20 @@
+/**
+ * React as the implementer of this project's `dom` roots.
+ *
+ * A `dom` root is one of the three things the host can hand you: an
+ * `HTMLElement` (the others being a `<canvas>` and a shared `three`
+ * instance). What mounts into that element is entirely your choice — the
+ * engine has no opinion and ships no default, which is why this file lives in
+ * your project rather than in the engine.
+ *
+ * React is the shipped choice because the editor's JSX authoring
+ * (OID-addressed hierarchy, style/className write-back to source) is built on
+ * it. Nothing forces it: register your own factory for `'dom'` and the same
+ * root mounts Vue, Svelte, or plain DOM. You lose the JSX authoring panels
+ * until that stack supplies its own authoring adapter — the panel is the
+ * reward for implementing the adapter, and the game runs regardless.
+ *
+ * Thirty lines, and every one of them is React's own API — `createRoot`,
+ * `flushSync`, `unmount`. Copied in, yours to edit.
+ */
+export { createReactRootAdapter, registerReactAdapter } from './react-root-adapter';

package/template/src/lib/react-root/react-root-adapter.tsx

@@ -0,0 +1,57 @@
+import { WorldProvider } from '@volter/game-runtime/react/world-state';
+import type { GameDomHostContext } from '@volter/game-runtime/runtime/host-context';
+import type { MountedReactGame, ReactRootAdapter } from '@volter/game-runtime/runtime/create-runtime';
+import { isAdapterRegistered, registerAdapter } from '@volter/game-runtime/runtime/mount-game';
+import { type ComponentType, createElement } from 'react';
+import { flushSync } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+
+interface ReactEntryModule {
+  readonly default?: ComponentType;
+}
+
+/** Construct one canonical React root adapter for direct host composition. */
+export function createReactRootAdapter(id: string, Entry: ComponentType): ReactRootAdapter {
+  return {
+    id,
+    async mount(host: GameDomHostContext): Promise<MountedReactGame> {
+      if (!host.game) throw new Error(`React root "${id}" requires a Game host.`);
+      const reactRoot = createRoot(host.container);
+      flushSync(() => {
+        reactRoot.render(createElement(WorldProvider, { game: host.game! }, createElement(Entry)));
+      });
+      return {
+        kind: 'dom',
+        container: host.container,
+        drivesOwnLoop: false,
+        dispose: () => reactRoot.unmount(),
+      };
+    },
+  };
+}
+
+/**
+ * Register React as the factory for this project's `dom` roots. Call once at
+ * module load, before mounting — ADD the call to your `src/main.ts` yourself:
+ * the scaffold's main.ts registers only `three`, and installing this
+ * capability does not edit it.
+ *
+ * Registration is what makes a `dom` root mount at all; the engine ships no
+ * default. Swap React out by not calling this and registering your own
+ * factory for `'dom'` instead — the host hands that factory an `HTMLElement`
+ * and asks for a dispose, which is all `createApp().mount(el)` or
+ * `new Svelte({ target })` needs.
+ */
+export function registerReactAdapter(): void {
+  if (isAdapterRegistered('dom')) return;
+  registerAdapter('dom', (root, { entryModule }) => {
+    const Entry = (entryModule as ReactEntryModule | undefined)?.default;
+    if (!Entry) {
+      throw new Error(
+        `React root "${root.id}" entry "${root.entry ?? '(missing)'}" must default-export a component.`,
+      );
+    }
+
+    return { kind: 'dom', adapter: createReactRootAdapter(root.id, Entry) };
+  });
+}