@crowdedkingdoms/construct 0.0.0 → 0.2.0-dev.1

package/src/platform/studio/ConstructPlayerHostAdapter.ts

@@ -0,0 +1,392 @@
+/**
+ * The Construct implementation of `crowdy.player-host/1`.
+ *
+ * Ask/Play may observe nearby players and the current grid. Play may walk,
+ * look, stop, and send proximity chat — the same paths a human uses. No
+ * inventory, combat, craft, mount, or teleport: this starter does not have
+ * those services. Effects never touch the token, GraphQL, or the mod worker.
+ */
+import {
+  CrowdyAgentError,
+  toAgentError,
+  type CrowdyAgentPreemptionReason,
+  type GameCommandResultV1,
+  type GameCommandV1,
+  type GameObservationV1,
+  type ObserveRequestV1,
+  type PlayerHostAdapterV1,
+  type PlayerHostCapabilitiesV1,
+  type PlayerHostCommandCapabilityV1,
+  type PlayerHostLeaseScope,
+  type ValidatedGateV1,
+} from '@crowdedkingdoms/crowdyjs/player-host';
+
+import type { AgentLocomotion } from './agentLocomotion';
+import type { GridSnapshot } from './GridService';
+
+export const CONSTRUCT_AGENT_TOOL_NAMES = Object.freeze([
+  'game.capabilities.get',
+  'game.observe',
+  'game.control.move',
+  'game.control.look',
+  'game.control.stop',
+  'game.chat.send',
+] as const);
+
+export const CONSTRUCT_OBSERVATION_MAX_AGE_MS = 1_500;
+export const CONSTRUCT_MAX_NEARBY_ACTORS = 32;
+export const CONSTRUCT_MAX_NEARBY_VOXELS = 0;
+
+const COMMAND_CAPABILITIES = Object.freeze([
+  command('MOVE', 'game.control.move', 'locomotion', 8),
+  command('LOOK', 'game.control.look', 'locomotion', 12),
+  command('STOP', 'game.control.stop', undefined, 100),
+  command('CHAT_SEND', 'game.chat.send', 'communicate', 2),
+] satisfies readonly PlayerHostCommandCapabilityV1[]);
+
+export interface ConstructObservedActor {
+  readonly actorId: string;
+  readonly position: { x: number; y: number; z: number };
+  readonly label?: string;
+}
+
+export interface ConstructObservationFrame {
+  readonly playerId: string;
+  readonly position: { x: number; y: number; z: number };
+  readonly velocity: { x: number; y: number; z: number };
+  readonly yaw: number;
+  readonly pitch: number;
+  readonly grid: GridSnapshot | null;
+  readonly nearbyActors: readonly ConstructObservedActor[];
+  readonly humanInputActive: boolean;
+  readonly textInputFocused: boolean;
+  readonly modalOpen: boolean;
+}
+
+export interface ConstructPlayerHostAdapterOptions {
+  readonly frame: () => ConstructObservationFrame;
+  readonly locomotion: AgentLocomotion;
+  readonly sendChat: (text: string) => Promise<void>;
+  readonly now?: () => number;
+  readonly maxRememberedObservations?: number;
+}
+
+interface RememberedObservation {
+  readonly observation: GameObservationV1;
+  readonly frame: ConstructObservationFrame;
+}
+
+export class ConstructPlayerHostAdapter implements PlayerHostAdapterV1 {
+  readonly contractVersion = 'crowdy.player-host/1' as const;
+  private readonly observations = new Map<string, RememberedObservation>();
+  private sequence = 0;
+  private readonly now: () => number;
+
+  constructor(private readonly options: ConstructPlayerHostAdapterOptions) {
+    this.now = options.now ?? Date.now;
+  }
+
+  async capabilities(): Promise<PlayerHostCapabilitiesV1> {
+    const frame = this.options.frame();
+    return capabilitiesFor(frame, this.now());
+  }
+
+  async observe(request: ObserveRequestV1): Promise<GameObservationV1> {
+    const frame = this.options.frame();
+    const capabilities = capabilitiesFor(frame, this.now());
+    const observedAtMs = this.now();
+    const observationId = `construct-obs-${observedAtMs}-${++this.sequence}`;
+    const maxActors = Math.min(
+      CONSTRUCT_MAX_NEARBY_ACTORS,
+      clampInt(request.maxNearbyActors, 0, CONSTRUCT_MAX_NEARBY_ACTORS),
+    );
+    const nearbyActors = [...frame.nearbyActors]
+      .map((actor) => ({
+        actor,
+        distance: distance(frame.position, actor.position),
+      }))
+      .sort(
+        (left, right) =>
+          left.distance - right.distance || left.actor.actorId.localeCompare(right.actor.actorId),
+      )
+      .slice(0, maxActors)
+      .map(({ actor, distance: d }) => ({
+        actorId: actor.actorId.slice(0, 128),
+        kind: 'PLAYER' as const,
+        position: vec(actor.position),
+        distance: dec(d),
+        disposition: 'NEUTRAL' as const,
+        ...(actor.label ? { label: actor.label.slice(0, 128) } : {}),
+      }));
+
+    const observation: GameObservationV1 = {
+      contractVersion: 'crowdy.game-observation/1',
+      observationId,
+      capabilityRevision: capabilities.revision,
+      controlledEntityId: frame.playerId.slice(0, 128),
+      observedAt: new Date(observedAtMs).toISOString(),
+      expiresAt: new Date(observedAtMs + CONSTRUCT_OBSERVATION_MAX_AGE_MS).toISOString(),
+      player: {
+        position: vec(frame.position),
+        velocity: vec(frame.velocity),
+        look: { yaw: dec(frame.yaw), pitch: dec(frame.pitch) },
+        health: '1',
+        alive: true,
+      },
+      controlledEntity: {
+        kind: 'PLAYER',
+        position: vec(frame.position),
+        velocity: vec(frame.velocity),
+      },
+      ...(frame.grid
+        ? {
+            grid: {
+              gridRef: frame.grid.gridId,
+              low: vec({
+                x: Number(frame.grid.bounds.low.x),
+                y: Number(frame.grid.bounds.low.y),
+                z: Number(frame.grid.bounds.low.z),
+              }),
+              high: vec({
+                x: Number(frame.grid.bounds.high.x),
+                y: Number(frame.grid.bounds.high.y),
+                z: Number(frame.grid.bounds.high.z),
+              }),
+              effectiveScopes: scopesFor(frame.grid),
+            },
+          }
+        : {}),
+      nearbyActors,
+      nearbyVoxels: [],
+      inputState: {
+        modalOpen: frame.modalOpen,
+        textInputFocused: frame.textInputFocused,
+        humanInputActive: frame.humanInputActive,
+      },
+    };
+    this.observations.set(observationId, { observation, frame });
+    while (this.observations.size > (this.options.maxRememberedObservations ?? 32)) {
+      const oldest = this.observations.keys().next().value;
+      if (!oldest) break;
+      this.observations.delete(oldest);
+    }
+    return observation;
+  }
+
+  async dispatch(command: GameCommandV1, gate: ValidatedGateV1): Promise<GameCommandResultV1> {
+    if (command.kind === 'STOP') {
+      this.clearAgentIntent('HUMAN_STOP');
+      return success(command);
+    }
+    try {
+      this.assertGate(command, gate);
+      const remembered = this.observations.get(command.observationId);
+      if (!remembered) {
+        throw new CrowdyAgentError(
+          'AGENT_OBSERVATION_STALE',
+          'The Construct no longer retains that observation',
+        );
+      }
+      const current = this.options.frame();
+      const revision = capabilityRevisionFor(current);
+      if (
+        command.capabilityRevision !== remembered.observation.capabilityRevision ||
+        command.controlledEntityId !== remembered.observation.controlledEntityId
+      ) {
+        throw new CrowdyAgentError(
+          'AGENT_CONTROL_TARGET_CHANGED',
+          'Command capability or controlled entity differs from its observation',
+        );
+      }
+      if (
+        revision !== command.capabilityRevision ||
+        current.playerId !== command.controlledEntityId
+      ) {
+        this.clearAgentIntent('CONTROL_TARGET_CHANGED');
+        throw new CrowdyAgentError(
+          'AGENT_CONTROL_TARGET_CHANGED',
+          'Host capability or controlled entity changed before dispatch',
+        );
+      }
+      if (Date.parse(remembered.observation.expiresAt) <= this.now()) {
+        throw new CrowdyAgentError(
+          'AGENT_OBSERVATION_STALE',
+          'Observation expired before dispatch',
+        );
+      }
+      if (current.humanInputActive) {
+        this.clearAgentIntent('HUMAN_INPUT');
+        throw new CrowdyAgentError('AGENT_PREEMPTED', 'Human input took control');
+      }
+      if (current.modalOpen || current.textInputFocused) {
+        throw new CrowdyAgentError(
+          'AGENT_CONTEXT_CHANGED',
+          'A modal or text field currently blocks agent control',
+        );
+      }
+      return await this.route(command);
+    } catch (error) {
+      return denied(command, error);
+    }
+  }
+
+  clearAgentIntent(_reason: CrowdyAgentPreemptionReason): void {
+    this.options.locomotion.clear();
+  }
+
+  invalidateObservations(): void {
+    this.observations.clear();
+  }
+
+  private async route(
+    command: Exclude<GameCommandV1, { kind: 'STOP' }>,
+  ): Promise<GameCommandResultV1> {
+    if (command.kind === 'MOVE') {
+      this.options.locomotion.applyMove({
+        direction: command.direction,
+        intensity: command.intensity,
+        durationMs: command.durationMs,
+        nowMs: this.now(),
+      });
+      return success(command);
+    }
+    if (command.kind === 'LOOK') {
+      this.options.locomotion.applyLook({
+        deltaYaw: command.deltaYaw,
+        deltaPitch: command.deltaPitch,
+      });
+      return success(command);
+    }
+    if (command.kind === 'CHAT_SEND') {
+      if (command.channel !== 'LOCAL') {
+        throw new CrowdyAgentError(
+          'AGENT_SCOPE_DENIED',
+          'The Construct only offers proximity (LOCAL) chat',
+        );
+      }
+      await this.options.sendChat(command.text);
+      return success(command);
+    }
+    throw new CrowdyAgentError(
+      'AGENT_HOST_UNAVAILABLE',
+      `The Construct does not advertise ${command.kind}`,
+    );
+  }
+
+  private assertGate(
+    command: Exclude<GameCommandV1, { kind: 'STOP' }>,
+    gate: ValidatedGateV1,
+  ): void {
+    if (
+      gate.contractVersion !== 'crowdy.validated-gate/1' ||
+      gate.observationId !== command.observationId
+    ) {
+      throw new CrowdyAgentError('AGENT_CONTEXT_STALE', 'Mismatched validated control gate');
+    }
+    const capability = COMMAND_CAPABILITIES.find((row) => row.kind === command.kind);
+    if (!capability) {
+      throw new CrowdyAgentError('AGENT_HOST_UNAVAILABLE', `Not advertised: ${command.kind}`);
+    }
+    if (capability.requiredScope && !gate.scopes.includes(capability.requiredScope)) {
+      throw new CrowdyAgentError(
+        'AGENT_LEASE_SCOPE_MISSING',
+        `${command.kind} requires ${capability.requiredScope}`,
+        { requiredScope: capability.requiredScope },
+      );
+    }
+  }
+}
+
+export function capabilityRevisionFor(frame: ConstructObservationFrame): string {
+  const payload = [
+    'construct-host-v1',
+    frame.playerId,
+    frame.grid?.gridId ?? 'no-grid',
+    ...(frame.grid ? scopesFor(frame.grid) : []),
+  ].join('|');
+  let hash = 0xcbf29ce484222325n;
+  for (const byte of new TextEncoder().encode(payload)) {
+    hash ^= BigInt(byte);
+    hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+  }
+  return `construct-host-v1-${hash.toString(16).padStart(16, '0')}`;
+}
+
+function capabilitiesFor(frame: ConstructObservationFrame, atMs: number): PlayerHostCapabilitiesV1 {
+  return {
+    contractVersion: 'crowdy.player-host/1',
+    gameId: 'the-construct',
+    revision: capabilityRevisionFor(frame),
+    controlledEntityId: frame.playerId.slice(0, 128),
+    commands: COMMAND_CAPABILITIES,
+    observation: {
+      maxAgeMs: CONSTRUCT_OBSERVATION_MAX_AGE_MS,
+      maxNearbyActors: CONSTRUCT_MAX_NEARBY_ACTORS,
+      maxNearbyVoxels: CONSTRUCT_MAX_NEARBY_VOXELS,
+    },
+    advertisedAt: new Date(atMs).toISOString(),
+  };
+}
+
+function scopesFor(grid: GridSnapshot): PlayerHostLeaseScope[] {
+  const scopes: PlayerHostLeaseScope[] = ['observe'];
+  if (grid.owned || grid.permissions.server.canWrite || grid.permissions.client.canWrite) {
+    scopes.push('locomotion', 'communicate');
+  }
+  return scopes;
+}
+
+function command(
+  kind: PlayerHostCommandCapabilityV1['kind'],
+  toolName: string,
+  requiredScope: PlayerHostLeaseScope | undefined,
+  rateLimitPerSecond: number,
+): PlayerHostCommandCapabilityV1 {
+  return {
+    kind,
+    toolName,
+    ...(requiredScope ? { requiredScope } : {}),
+    risk: 'WORLD_CONTROL',
+    approval: 'NONE',
+    rateLimitPerSecond,
+  };
+}
+
+function success(command: GameCommandV1): GameCommandResultV1 {
+  return {
+    contractVersion: 'crowdy.game-command-result/1',
+    status: 'SUCCEEDED',
+    commandKind: command.kind,
+    ...('observationId' in command ? { observationId: command.observationId } : {}),
+  };
+}
+
+function denied(command: GameCommandV1, error: unknown): GameCommandResultV1 {
+  return {
+    contractVersion: 'crowdy.game-command-result/1',
+    status: 'DENIED',
+    commandKind: command.kind,
+    ...('observationId' in command ? { observationId: command.observationId } : {}),
+    error: toAgentError(error, 'AGENT_TOOL_FAILED'),
+  };
+}
+
+function vec(value: { x: number; y: number; z: number }) {
+  return { x: dec(value.x), y: dec(value.y), z: dec(value.z) };
+}
+
+function dec(value: number): string {
+  return Number.isFinite(value) ? String(value) : '0';
+}
+
+function distance(
+  a: { x: number; y: number; z: number },
+  b: { x: number; y: number; z: number },
+): number {
+  return Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
+}
+
+function clampInt(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(max, Math.max(min, Math.trunc(value)));
+}

package/src/platform/studio/GridService.test.ts

@@ -0,0 +1,131 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+// The SDK root barrel drags Monaco into a unit test; the network layer only needs the constants.
+vi.mock('@crowdedkingdoms/crowdyjs', () => ({
+  CROWDY_DEFAULT_HTTP_ORIGIN: 'https://ck.test.example',
+  CROWDY_DEFAULT_TIER: 'test',
+}));
+
+const { GridService } = await import('./GridService');
+
+interface HubClaim {
+  gridId: string;
+  chunk: { x: number; y: number; z: number };
+  ownerUserId: string;
+  ownerName: string;
+}
+
+/** A network whose world hub keeps a registry the way `exec/construct` does. */
+function network(userId = '42') {
+  const claims: HubClaim[] = [];
+  const logs: string[] = [];
+  const hub = {
+    call: vi.fn(async (method: string, args: Record<string, unknown> = {}) => {
+      if (method === 'claims') {
+        const at = args.chunk as HubClaim['chunk'];
+        const rows = claims.filter((c) => !at || (c.chunk.x === at.x && c.chunk.z === at.z));
+        return { claims: rows, total: claims.length };
+      }
+      if (method === 'record_claim') {
+        if (claims.some((c) => c.gridId === args.gridId && c.ownerUserId !== userId))
+          throw new Error('AppError: grid is recorded for another player');
+        if (!claims.some((c) => c.gridId === args.gridId)) {
+          claims.push({
+            gridId: String(args.gridId),
+            chunk: args.chunk as HubClaim['chunk'],
+            ownerUserId: userId,
+            ownerName: String(args.ownerName),
+          });
+        }
+        return { recorded: true };
+      }
+      if (method === 'release_claim') {
+        const i = claims.findIndex((c) => c.gridId === args.gridId);
+        if (i >= 0 && claims[i]!.ownerUserId !== userId)
+          throw new Error("AppError: only the claim's owner may release it");
+        if (i >= 0) claims.splice(i, 1);
+        return { released: i >= 0 };
+      }
+      throw new Error(`unexpected ${method}`);
+    }),
+  };
+  const marketplace = {
+    claimGridChunk: vi.fn(async () => ({
+      gridId: '91159989710848',
+      lowChunk: { x: '3', y: '0', z: '-2' },
+      highChunk: { x: '3', y: '0', z: '-2' },
+      effectivePermissionKeys: ['write_server_code', 'run_server_code'],
+      policy: 'SELF_CLAIM',
+    })),
+    releaseClaimedGrid: vi.fn(async () => true),
+  };
+  const gameApps = {
+    nearbyPermissions: vi.fn(async () => {
+      throw new Error('manage_apps required');
+    }),
+  };
+  const net = {
+    appId: '77',
+    user: { userId, gamertag: 'neo' },
+    game: { marketplace, gameApps },
+    worldHub: hub,
+    log: (line: string) => logs.push(line),
+  };
+  return { net: net as never, hub, claims, logs, marketplace };
+}
+
+const AT = { x: 3, y: 0, z: -2 };
+
+describe('GridService on the world hub registry', () => {
+  beforeEach(() => localStorage.clear());
+
+  it('records a claim for the caller and finds it again', async () => {
+    const { net, hub, claims } = network();
+    const grids = new GridService(net);
+    const snapshot = await grids.claimHere(AT, 'neo the one with a very long name indeed');
+    expect(snapshot).toMatchObject({ gridId: '91159989710848', owned: true });
+    expect(hub.call).toHaveBeenCalledWith('record_claim', {
+      gridId: '91159989710848',
+      chunk: AT,
+      ownerName: 'neo the one with a very long nam',
+    });
+    expect(claims).toHaveLength(1);
+    expect(await grids.lookup(AT)).toMatchObject({ gridId: '91159989710848', owned: true });
+  });
+
+  it('shows a visitor the owner from the registry, with no code keys', async () => {
+    const owner = network('42');
+    await new GridService(owner.net).claimHere(AT, 'neo');
+    localStorage.clear();
+    const visitor = network('43');
+    visitor.claims.push(...owner.claims);
+    const grid = await new GridService(visitor.net).lookup(AT);
+    expect(grid).toMatchObject({ gridId: '91159989710848', owned: false, ownerName: 'neo' });
+    expect(grid?.permissions.server.canWrite).toBe(false);
+    expect(await new GridService(visitor.net).lookup({ x: 9, y: 0, z: 9 })).toBeNull();
+  });
+
+  it('caches a chunk briefly and releases through the platform, then the registry', async () => {
+    const { net, hub, claims, marketplace } = network();
+    const grids = new GridService(net);
+    await grids.claimHere(AT, 'neo');
+    await grids.lookup(AT);
+    await grids.lookup(AT);
+    expect(hub.call.mock.calls.filter(([m]) => m === 'claims')).toHaveLength(1);
+    await grids.release('91159989710848');
+    expect(marketplace.releaseClaimedGrid).toHaveBeenCalledWith({
+      appId: '77',
+      gridId: '91159989710848',
+    });
+    expect(claims).toHaveLength(0);
+    expect(grids.ownedGrids()).toHaveLength(0);
+  });
+
+  it('keeps a claim working when the registry refuses the row, and says why', async () => {
+    const { net, claims, logs } = network('42');
+    claims.push({ gridId: '91159989710848', chunk: AT, ownerUserId: '43', ownerName: 'smith' });
+    const snapshot = await new GridService(net).claimHere(AT, 'neo');
+    expect(snapshot.owned).toBe(true);
+    expect(logs.some((line) => /claim registry write failed: AppError/.test(line))).toBe(true);
+  });
+});