@crowdedkingdoms/construct 0.0.0 → 0.2.0-dev.1

package/src/engine/SceneRouter.ts

@@ -0,0 +1,113 @@
+/**
+ * Loads one scene at a time into the game root and keeps the platform session
+ * informed of which one. Scenes are constructed lazily from factories so an
+ * unused renderer never initialises (or, with code-splitting, never loads).
+ */
+import type { GameScene, SceneContext, SceneFactory, SceneSize } from './GameScene';
+import { Emitter } from '../platform/util/Emitter';
+
+export interface SceneRouterEvents {
+  /** Fired after a scene has mounted. */
+  scene: GameScene;
+  /** Fired when a load fails; the previous scene stays mounted if it can. */
+  error: { sceneId: string; error: unknown };
+}
+
+export class SceneRouter {
+  readonly events = new Emitter<SceneRouterEvents>();
+  private readonly factories = new Map<string, SceneFactory>();
+  private readonly instances = new Map<string, GameScene>();
+  private active: GameScene | null = null;
+  private loading: Promise<GameScene> | null = null;
+  private context: SceneContext | null = null;
+  private size: SceneSize = { width: 1, height: 1, rightInset: 0 };
+
+  register(id: string, factory: SceneFactory): void {
+    this.factories.set(id, factory);
+  }
+
+  ids(): string[] {
+    return [...this.factories.keys()];
+  }
+
+  /** Called once by the loop before the first `load`. */
+  bind(context: SceneContext, size: SceneSize): void {
+    this.context = context;
+    this.size = size;
+  }
+
+  get current(): GameScene | null {
+    return this.active;
+  }
+
+  get isLoading(): boolean {
+    return this.loading !== null;
+  }
+
+  /**
+   * Switch scenes. The new scene mounts with the local player at `spawn` (or
+   * where the scene decides when omitted). Concurrent loads are serialised.
+   */
+  async load(
+    id: string,
+    spawn?: { x: number; y: number; z: number; yaw?: number },
+  ): Promise<GameScene> {
+    if (this.loading) await this.loading.catch(() => undefined);
+    if (this.active?.id === id) return this.active;
+    const context = this.context;
+    if (!context) throw new Error('SceneRouter.bind() before load()');
+    const factory = this.factories.get(id);
+    if (!factory) throw new Error(`No scene registered as "${id}"`);
+
+    const run = (async () => {
+      const previous = this.active;
+      let scene = this.instances.get(id);
+      if (!scene) {
+        scene = factory();
+        this.instances.set(id, scene);
+      }
+      const previousPose = previous?.localPose();
+      try {
+        previous?.unmount();
+        this.active = null;
+        await scene.mount(context, this.size);
+        if (spawn) scene.setLocalPosition(spawn);
+        this.active = scene;
+        this.events.emit('scene', scene);
+        return scene;
+      } catch (error) {
+        // Never leave the player staring at nothing: put the previous scene
+        // back where it was, then report.
+        try {
+          scene.unmount();
+        } catch {
+          // best effort
+        }
+        if (previous) {
+          await previous.mount(context, this.size);
+          if (previousPose) previous.setLocalPosition(previousPose);
+          this.active = previous;
+        }
+        this.events.emit('error', { sceneId: id, error });
+        throw error;
+      }
+    })();
+    this.loading = run;
+    try {
+      return await run;
+    } finally {
+      if (this.loading === run) this.loading = null;
+    }
+  }
+
+  resize(size: SceneSize): void {
+    this.size = size;
+    this.active?.resize(size);
+  }
+
+  dispose(): void {
+    this.active?.unmount();
+    this.active = null;
+    this.instances.clear();
+  }
+}

package/src/engine/controls.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+
+import { Controls, helpLines, isControl } from './controls';
+
+describe('controls', () => {
+  it('maps chat to T and both Enters, and activate to E only', () => {
+    expect(isControl('chat', 'KeyT')).toBe(true);
+    expect(isControl('chat', 'Enter')).toBe(true);
+    expect(isControl('chat', 'NumpadEnter')).toBe(true);
+    expect(isControl('activate', 'KeyE')).toBe(true);
+    expect(isControl('activate', 'Enter')).toBe(false);
+    expect(Controls.voice).toContain('KeyV');
+    expect(Controls.webcam).toContain('KeyB');
+  });
+
+  it('lists holodeck look/zoom and paint pan without mixing them', () => {
+    const holodeck = helpLines('holodeck').join('\n');
+    const paint = helpLines('paint').join('\n');
+    expect(holodeck).toMatch(/right mouse/);
+    expect(holodeck).toMatch(/Scroll/);
+    expect(holodeck).toMatch(/E — activate/);
+    expect(holodeck).toMatch(/claimed chunk/);
+    expect(paint).toMatch(/middle-drag/);
+    expect(paint).not.toMatch(/activate a pad/);
+  });
+});

package/src/engine/controls.ts

@@ -0,0 +1,63 @@
+/**
+ * The one place key and mouse bindings are named. Scenes and the HUD read
+ * this map; they do not invent codes. `KeyboardEvent.code` (physical keys)
+ * so WASD stays WASD on an AZERTY layout.
+ */
+export const Controls = {
+  moveForward: ['KeyW', 'ArrowUp'],
+  moveBack: ['KeyS', 'ArrowDown'],
+  moveLeft: ['KeyA', 'ArrowLeft'],
+  moveRight: ['KeyD', 'ArrowRight'],
+  run: ['ShiftLeft', 'ShiftRight'],
+  activate: ['KeyE'],
+  chat: ['KeyT', 'Enter', 'NumpadEnter'],
+  webcam: ['KeyB'],
+  voice: ['KeyV'],
+  studio: ['KeyM'],
+  holodeck: ['KeyH'],
+  help: ['F1', 'Slash'],
+  escape: ['Escape'],
+} as const;
+
+export type ControlAction = keyof typeof Controls;
+
+export function codesFor(action: ControlAction): readonly string[] {
+  return Controls[action];
+}
+
+export function isControl(action: ControlAction, code: string): boolean {
+  return (Controls[action] as readonly string[]).includes(code);
+}
+
+export type HelpScene = 'holodeck' | 'paint';
+
+/** Lines shown in the F1 / ? overlay. */
+export function helpLines(scene: HelpScene): string[] {
+  const shared = [
+    'WASD / arrows — move',
+    'Shift — run (holodeck)',
+    'T or Enter — chat',
+    'B — webcam',
+    'V — voice',
+    'M — Crowdy Studio (Ask / Build / Play agent in the dock)',
+    'F1 or ? — this help',
+    'Escape — close help, unlock look',
+  ];
+  if (scene === 'paint') {
+    return [
+      'Click / drag — paint · right-drag — erase',
+      '1–8 — colours · 0 — eraser',
+      'Scroll — zoom · middle-drag or Alt+click — pan',
+      'H — back to holodeck',
+      ...shared,
+    ];
+  }
+  return [
+    'Hold right mouse — look',
+    'Left click — grid mods (click-to-charge)',
+    'Amber box — your claimed chunk',
+    'Scroll — zoom camera',
+    'E — activate a pad',
+    ...shared,
+  ];
+}

package/src/grid/GridProgramRunner.ts

@@ -0,0 +1,205 @@
+/**
+ * Page side of JS grid programs (DN-10 §5): player-authored JavaScript that
+ * uses the full CrowdyJS SDK inside one grid.
+ *
+ * Each program runs in its own hidden `sandbox="allow-scripts"` iframe (an
+ * opaque origin with no network, see `buildGridProgramCsp`). Its CrowdyJS
+ * talks over a MessagePort that `hostGridProgram` relays with a grid-scoped
+ * token, so the server confines everything it does to the grid. The runner
+ * also answers the Crowdy Studio agent's grid requests (crowdy-dsh bridge v4).
+ */
+import type { CrowdyClient } from '@crowdedkingdoms/crowdyjs';
+import type {
+  CrowdyStudioDshGridHost,
+  DshGridContext,
+  DshGridProgramStatus,
+} from '@crowdedkingdoms/crowdyjs/crowdy-dsh';
+import { hostGridProgram, type GridProgramHost } from '@crowdedkingdoms/crowdyjs/grid-program';
+
+import { GRID_PROGRAM_SOURCE, type GridProgramSandboxMessage } from './sandboxProtocol';
+
+export interface GridProgramRunnerOptions {
+  /** The page's client (holds the player's app token); resolved per call. */
+  client: () => CrowdyClient;
+  appId: () => string;
+  /** ck-api GraphQL endpoints the relay dials (a function follows endpoint changes). */
+  graphqlUrl: string | (() => string);
+  graphqlWsUrl: string | (() => string);
+  /** URL of the sandbox page, usually `${import.meta.env.BASE_URL}grid-program.html`. */
+  sandboxUrl: string;
+  /** Where the hidden iframes are attached (default document.body). */
+  container?: () => HTMLElement;
+  /** Whether the signed-in player owns a grid (for `grid.context`). */
+  owns?: (gridId: string) => boolean;
+  /** Called when a program's state changes (for a HUD line). */
+  onChange?: (status: DshGridProgramStatus) => void;
+}
+
+interface RunningProgram {
+  key: string;
+  gridId: string;
+  status: DshGridProgramStatus;
+  iframe: HTMLIFrameElement;
+  host: GridProgramHost | null;
+  listener: (event: MessageEvent) => void;
+}
+
+const LOG_LINES = 200;
+const READY_TIMEOUT_MS = 15_000;
+
+export class GridProgramRunner implements CrowdyStudioDshGridHost {
+  private readonly running = new Map<string, RunningProgram>();
+
+  constructor(private readonly options: GridProgramRunnerOptions) {}
+
+  async context(gridId: string): Promise<DshGridContext | null> {
+    const scope = this.options.client().grid(this.options.appId(), gridId);
+    const token = await scope.mintToken(60).catch(() => null);
+    if (!token) return null;
+    const [channels, sessions] = await Promise.all([
+      scope.channels.list().catch(() => []),
+      scope.sessions.list({ status: 'active' }).catch(() => []),
+    ]);
+    return {
+      appId: this.options.appId(),
+      gridId,
+      low: token.lowChunk,
+      high: token.highChunk,
+      owned: this.options.owns?.(gridId) ?? false,
+      channels: channels.map((c) => ({ groupId: String(c.groupId), name: c.name })),
+      sessions: sessions.map((s) => ({
+        sessionId: s.sessionId,
+        name: s.name ?? null,
+        status: s.status,
+      })),
+    };
+  }
+
+  async runProgram(input: {
+    gridId: string;
+    path: string;
+    source: string;
+    stop?: boolean;
+  }): Promise<DshGridProgramStatus> {
+    const key = `${input.gridId}:${input.path}`;
+    this.stop(key);
+    if (input.stop) return { path: input.path, running: false, log: [] };
+    return this.start(key, input.gridId, input.path, input.source);
+  }
+
+  programs(): DshGridProgramStatus[] {
+    return [...this.running.values()].map((p) => ({ ...p.status, log: [...p.status.log] }));
+  }
+
+  /** Stop every program (leaving a grid, signing out). */
+  stopAll(gridId?: string): void {
+    for (const program of [...this.running.values()]) {
+      if (gridId === undefined || program.gridId === gridId) this.stop(program.key);
+    }
+  }
+
+  private stop(key: string): void {
+    const program = this.running.get(key);
+    if (!program) return;
+    program.host?.stop();
+    window.removeEventListener('message', program.listener);
+    program.iframe.remove();
+    program.status = { ...program.status, running: false };
+    this.running.delete(key);
+    this.options.onChange?.(program.status);
+  }
+
+  private async start(
+    key: string,
+    gridId: string,
+    path: string,
+    source: string,
+  ): Promise<DshGridProgramStatus> {
+    const iframe = document.createElement('iframe');
+    iframe.setAttribute('sandbox', 'allow-scripts');
+    iframe.setAttribute('aria-hidden', 'true');
+    iframe.title = `grid program ${path}`;
+    iframe.style.cssText = 'position:absolute;width:0;height:0;border:0;visibility:hidden';
+    iframe.src = this.options.sandboxUrl;
+    const status: DshGridProgramStatus = {
+      path,
+      running: false,
+      startedAt: new Date().toISOString(),
+      log: [],
+    };
+    let resolveReady!: () => void;
+    const ready = new Promise<void>((resolve) => (resolveReady = resolve));
+    const program: RunningProgram = {
+      key,
+      gridId,
+      status,
+      iframe,
+      host: null,
+      listener: (event: MessageEvent) => {
+        if (event.source !== iframe.contentWindow) return;
+        const data = event.data as ({ source?: string } & GridProgramSandboxMessage) | null;
+        if (!data || data.source !== GRID_PROGRAM_SOURCE) return;
+        switch (data.type) {
+          case 'ready':
+            resolveReady();
+            return;
+          case 'started':
+            program.status = { ...program.status, running: true };
+            break;
+          case 'log':
+            program.status = {
+              ...program.status,
+              log: [...program.status.log, `[${data.level}] ${data.line}`].slice(-LOG_LINES),
+            };
+            break;
+          case 'error':
+            program.status = {
+              ...program.status,
+              lastError: data.message,
+              log: [...program.status.log, `[error] ${data.message}`].slice(-LOG_LINES),
+            };
+            break;
+        }
+        this.options.onChange?.(program.status);
+      },
+    };
+    this.running.set(key, program);
+    window.addEventListener('message', program.listener);
+    (this.options.container?.() ?? document.body).appendChild(iframe);
+
+    const timedOut = await Promise.race([
+      ready.then(() => false),
+      new Promise<boolean>((resolve) => setTimeout(() => resolve(true), READY_TIMEOUT_MS)),
+    ]);
+    if (timedOut) {
+      program.status = { ...program.status, lastError: 'the sandbox page did not load' };
+      this.stop(key);
+      return program.status;
+    }
+    const channel = new MessageChannel();
+    program.host = await hostGridProgram({
+      port: channel.port1,
+      scope: this.options.client().grid(this.options.appId(), gridId),
+      graphqlUrl: endpoint(this.options.graphqlUrl),
+      graphqlWsUrl: endpoint(this.options.graphqlWsUrl),
+      onRefused: (reason) => {
+        program.status = {
+          ...program.status,
+          log: [...program.status.log, `[relay] refused: ${reason}`].slice(-LOG_LINES),
+        };
+      },
+    });
+    iframe.contentWindow?.postMessage(
+      { source: GRID_PROGRAM_SOURCE, type: 'init', program: source, path },
+      '*',
+      [channel.port2],
+    );
+    // Give the program a moment to report `started` or an import error.
+    await new Promise((resolve) => setTimeout(resolve, 750));
+    return { ...program.status, log: [...program.status.log] };
+  }
+}
+
+function endpoint(value: string | (() => string)): string {
+  return typeof value === 'function' ? value() : value;
+}

package/src/grid/sandboxProtocol.ts

@@ -0,0 +1,9 @@
+/** window.postMessage traffic between the game page and a grid program sandbox. */
+export const GRID_PROGRAM_SOURCE = 'construct-grid-program';
+
+/** Sandbox -> page (the CrowdyJS traffic itself rides the MessagePort, not this). */
+export type GridProgramSandboxMessage =
+  | { type: 'ready' }
+  | { type: 'started' }
+  | { type: 'log'; level: 'log' | 'info' | 'warn' | 'error'; line: string }
+  | { type: 'error'; message: string };

package/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * `@crowdedkingdoms/construct` — the Construct framework.
+ *
+ * The platform layer every Crowded Kingdoms browser game needs (hosted
+ * sign-in, app entry, World Stores presence, voice / webcam / chat, the
+ * Crowdy Studio dock with app and grid mods, JS grid programs) and the engine
+ * loop around it. Deep imports (`@crowdedkingdoms/construct/platform/...`,
+ * `/engine/...`, `/grid/...`) reach every module; this barrel re-exports the
+ * pieces a game wires at boot.
+ */
+
+// Engine
+export { GameLoop } from './engine/GameLoop';
+export { SceneRouter, type SceneRouterEvents } from './engine/SceneRouter';
+export {
+  Input,
+  isTextEntry,
+  isPointerLockOn,
+  type KeyHandler,
+  type PointerState,
+} from './engine/Input';
+export { Controls, helpLines, type ControlAction } from './engine/controls';
+export type {
+  GameScene,
+  SceneContext,
+  SceneFactory,
+  SceneHud,
+  SceneSize,
+} from './engine/GameScene';
+
+// Session, network, presence
+export { GameSession, type GameSessionEvents } from './platform/GameSession';
+export {
+  NetworkManager,
+  messageOf,
+  type AppRoute,
+  type BootstrapInfo,
+  type SessionUser,
+} from './platform/network/NetworkManager';
+export { AuthService } from './platform/auth/AuthService';
+export {
+  worldSession,
+  hasWorldSession,
+  disposeWorldSession,
+  instanceStore,
+  type RemotePlayer,
+  type SaveState,
+} from './platform/realtime/WorldStores';
+export { NEUTRAL_POSE, POSE_BYTES, poseCodec, type Pose } from './platform/realtime/actorCodec';
+export {
+  chunkKey,
+  worldToChunk,
+  worldToVoxel,
+  type ChunkCoord,
+  type Vec3,
+} from './platform/realtime/space';
+export { ensureEnvScope, readScoped, writeScoped } from './platform/envScope';
+
+// Social and media
+export { ChatService, type ChatMessage } from './platform/social/ChatService';
+export { VoiceService } from './platform/media/VoiceService';
+export { WebcamService } from './platform/media/WebcamService';
+
+// The world hub (ck-exec)
+export {
+  WorldHub,
+  configureWorldHub,
+  worldHubAddress,
+  type WorldHubAddress,
+} from './platform/exec/worldHub';
+
+// Crowdy Studio, mods, grids
+export { StudioService, type StudioHooks, type StudioState } from './platform/studio/StudioService';
+export { GridService, type GridSnapshot } from './platform/studio/GridService';
+export {
+  toBrokerBounds,
+  hasAnyStudioPermission,
+  type GridBounds,
+  type StudioPermissions,
+} from './platform/studio/permissions';
+export {
+  routeClientHostCall,
+  routeWithFallback,
+  runConsentedGridMod,
+  type ClientModHostReads,
+  type ClientModHostWrites,
+} from './platform/studio/clientModHost';
+export { GridProgramRunner, type GridProgramRunnerOptions } from './grid/GridProgramRunner';