@crowdedkingdoms/construct 0.0.0 → 0.2.1-dev.1

package/src/platform/realtime/actorCodec.ts

@@ -0,0 +1,142 @@
+/**
+ * The Construct's replication state: what every player broadcasts about
+ * itself a few times a second, and what every scene renders for everyone else.
+ *
+ * Declared ONCE as a binary struct (spatial packets have a ~1.1 KB budget, so
+ * poses never travel as JSON). Both scenes consume the same `Pose`; the
+ * `program` byte says which scene the actor is standing in so the holodeck can
+ * show who is "inside a program" and the program can hide people who are not.
+ *
+ * Layout (little-endian, 64 bytes):
+ *   0-11  position xyz  f32
+ *   12-15 yaw           f32
+ *   16-19 pitch         f32
+ *   20-31 velocity xyz  f32
+ *   32    flags         u8   (bit0 moving, bit1 in-program, bit2 studio-open)
+ *   33    program       u8   (0 = holodeck, 1.. = program id)
+ *   34    tint          u8   (avatar colour index)
+ *   35    reserved      u8
+ *   36-59 name          24 bytes UTF-8, NUL padded
+ *   60-63 reserved
+ */
+import {
+  bytes,
+  f32,
+  reserved,
+  structCodec,
+  u8,
+  type StateCodec,
+} from '@crowdedkingdoms/crowdyjs/stores';
+
+export const FLAG_MOVING = 1 << 0;
+export const FLAG_IN_PROGRAM = 1 << 1;
+export const FLAG_STUDIO_OPEN = 1 << 2;
+
+export const NAME_BYTES = 24;
+
+export interface Pose {
+  x: number;
+  y: number;
+  z: number;
+  yaw: number;
+  pitch: number;
+  vx: number;
+  vy: number;
+  vz: number;
+  flags: number;
+  program: number;
+  tint: number;
+  name: string;
+}
+
+export const NEUTRAL_POSE: Pose = {
+  x: 0,
+  y: 0,
+  z: 0,
+  yaw: 0,
+  pitch: 0,
+  vx: 0,
+  vy: 0,
+  vz: 0,
+  flags: 0,
+  program: 0,
+  tint: 0,
+  name: '',
+};
+
+const wire = structCodec({
+  x: f32(),
+  y: f32(),
+  z: f32(),
+  yaw: f32(),
+  pitch: f32(),
+  vx: f32(),
+  vy: f32(),
+  vz: f32(),
+  flags: u8(),
+  program: u8(),
+  tint: u8(),
+  pad0: reserved(1),
+  name: bytes(NAME_BYTES),
+  pad1: reserved(4),
+});
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export function encodeName(name: string, length: number = NAME_BYTES): Uint8Array {
+  const out = new Uint8Array(length);
+  // Trim by bytes, never splitting a multi-byte sequence: encode progressively.
+  let cut = name;
+  let encoded = encoder.encode(cut);
+  while (encoded.length > length && cut.length > 0) {
+    cut = cut.slice(0, -1);
+    encoded = encoder.encode(cut);
+  }
+  out.set(encoded.subarray(0, length));
+  return out;
+}
+
+export function decodeName(raw: Uint8Array): string {
+  let end = raw.indexOf(0);
+  if (end < 0) end = raw.length;
+  return decoder.decode(raw.subarray(0, end));
+}
+
+/** The typed codec World Stores use for `self` and `actors`. */
+export const poseCodec: StateCodec<Pose> = {
+  encode: (pose) =>
+    wire.encode({
+      x: pose.x,
+      y: pose.y,
+      z: pose.z,
+      yaw: pose.yaw,
+      pitch: pose.pitch,
+      vx: pose.vx,
+      vy: pose.vy,
+      vz: pose.vz,
+      flags: pose.flags & 0xff,
+      program: pose.program & 0xff,
+      tint: pose.tint & 0xff,
+      name: encodeName(pose.name),
+    }),
+  decode: (data) => {
+    const raw = wire.decode(data);
+    return {
+      x: raw.x,
+      y: raw.y,
+      z: raw.z,
+      yaw: raw.yaw,
+      pitch: raw.pitch,
+      vx: raw.vx,
+      vy: raw.vy,
+      vz: raw.vz,
+      flags: raw.flags,
+      program: raw.program,
+      tint: raw.tint,
+      name: decodeName(raw.name),
+    };
+  },
+};
+
+export const POSE_BYTES: number = wire.byteLength;

package/src/platform/realtime/space.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  chunkDistance,
+  chunkInput,
+  chunkKey,
+  sameChunk,
+  worldToChunk,
+  worldToVoxel,
+} from './space';
+
+describe('space', () => {
+  it('maps world positions to 16-unit chunks with floor semantics', () => {
+    expect(worldToChunk({ x: 0, y: 0, z: 0 })).toEqual({ x: 0, y: 0, z: 0 });
+    expect(worldToChunk({ x: 15.9, y: 1, z: -0.1 })).toEqual({ x: 0, y: 0, z: -1 });
+    expect(worldToChunk({ x: -16, y: 32, z: 17 })).toEqual({ x: -1, y: 2, z: 1 });
+  });
+
+  it('maps world positions to in-chunk voxel cells, including negatives', () => {
+    expect(worldToVoxel({ x: 3.2, y: 0, z: 17 })).toEqual({ x: 3, y: 0, z: 1 });
+    expect(worldToVoxel({ x: -1, y: 0, z: -16 })).toEqual({ x: 15, y: 0, z: 0 });
+  });
+
+  it('produces the string wire form and stable keys', () => {
+    expect(chunkInput({ x: -1, y: 0, z: 7 })).toEqual({ x: '-1', y: '0', z: '7' });
+    expect(chunkKey({ x: -1, y: 0, z: 7 })).toBe('-1,0,7');
+    expect(sameChunk({ x: 1, y: 2, z: 3 }, { x: '1', y: '2', z: '3' })).toBe(true);
+  });
+
+  it('uses Chebyshev distance like the platform fan-out', () => {
+    expect(chunkDistance({ x: 0, y: 0, z: 0 }, { x: 3, y: -1, z: 2 })).toBe(3);
+  });
+});

package/src/platform/realtime/space.ts

@@ -0,0 +1,63 @@
+/**
+ * World <-> chunk math. Everything realtime on Crowded Kingdoms is addressed
+ * to a chunk and fanned out within `distance` chunks; the game decides what a
+ * chunk means in world units. The Construct uses 16 units per chunk on all
+ * three axes and keeps the holodeck floor at world y in [0, 16), i.e. chunk
+ * layer 0.
+ */
+import type { ChunkCoordinatesInput } from '@crowdedkingdoms/crowdyjs';
+
+import { CHUNK_SIZE } from '../config';
+
+export interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+export interface ChunkCoord {
+  x: number;
+  y: number;
+  z: number;
+}
+
+export function worldToChunk(position: Vec3, size: number = CHUNK_SIZE): ChunkCoord {
+  return {
+    x: Math.floor(position.x / size),
+    y: Math.floor(position.y / size),
+    z: Math.floor(position.z / size),
+  };
+}
+
+/** World position -> the voxel cell inside its chunk (0..size-1 on each axis). */
+export function worldToVoxel(position: Vec3, size: number = CHUNK_SIZE): ChunkCoord {
+  const mod = (v: number) => ((Math.floor(v) % size) + size) % size;
+  return { x: mod(position.x), y: mod(position.y), z: mod(position.z) };
+}
+
+/** The wire form: chunk coordinates travel as decimal strings (int64). */
+export function chunkInput(chunk: ChunkCoord | ChunkCoordinatesInput): ChunkCoordinatesInput {
+  return { x: String(chunk.x), y: String(chunk.y), z: String(chunk.z) };
+}
+
+export function chunkFromInput(
+  chunk: ChunkCoordinatesInput | { x: unknown; y: unknown; z: unknown },
+): ChunkCoord {
+  return { x: Number(chunk.x), y: Number(chunk.y), z: Number(chunk.z) };
+}
+
+export function chunkKey(chunk: ChunkCoord | ChunkCoordinatesInput): string {
+  return `${chunk.x},${chunk.y},${chunk.z}`;
+}
+
+export function sameChunk(
+  a: ChunkCoord | ChunkCoordinatesInput,
+  b: ChunkCoord | ChunkCoordinatesInput,
+): boolean {
+  return String(a.x) === String(b.x) && String(a.y) === String(b.y) && String(a.z) === String(b.z);
+}
+
+/** Chebyshev distance in chunks — the metric the platform fans out with. */
+export function chunkDistance(a: ChunkCoord, b: ChunkCoord): number {
+  return Math.max(Math.abs(a.x - b.x), Math.abs(a.y - b.y), Math.abs(a.z - b.z));
+}

package/src/platform/social/ChatService.ts

@@ -0,0 +1,92 @@
+/**
+ * Proximity text chat over the realtime plane.
+ *
+ * A text packet is addressed to the sender's chunk and fanned out within
+ * `distance` chunks — the same spatial delivery as poses, which is why chat
+ * "just works" in whichever scene the player is standing in. Names are not on
+ * the wire: the receiver looks the sender's uuid up in the players lane.
+ */
+import { REPLICATION_DISTANCE } from '../config';
+import { NetworkManager } from '../network/NetworkManager';
+import { chunkInput, type ChunkCoord } from '../realtime/space';
+import { remotePlayers, worldSession } from '../realtime/WorldStores';
+import { Emitter } from '../util/Emitter';
+
+export interface ChatMessage {
+  id: number;
+  uuid: string;
+  name: string;
+  text: string;
+  at: number;
+  self: boolean;
+}
+
+export const MAX_CHAT_TEXT = 240;
+
+export class ChatService {
+  readonly events = new Emitter<{ message: ChatMessage }>();
+  private readonly history: ChatMessage[] = [];
+  private nextId = 1;
+  private sequence = 0;
+  private unsubscribe: (() => void) | null = null;
+
+  constructor(private readonly network: NetworkManager = NetworkManager.instance) {}
+
+  start(): void {
+    if (this.unsubscribe) return;
+    this.unsubscribe = this.network.on('text', (n) => {
+      const session = worldSession();
+      const self = n.uuid === session.self.uuid;
+      const name = self
+        ? session.self.state.name || 'you'
+        : remotePlayers().find((p) => p.uuid === n.uuid)?.pose.name || shortUuid(n.uuid);
+      this.push({ uuid: n.uuid, name, text: n.text, self });
+    });
+  }
+
+  stop(): void {
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+  }
+
+  messages(): readonly ChatMessage[] {
+    return this.history;
+  }
+
+  /** Send from the chunk the local actor currently stands in. */
+  async send(text: string, chunk?: ChunkCoord): Promise<void> {
+    const trimmed = text.trim().slice(0, MAX_CHAT_TEXT);
+    if (!trimmed) return;
+    const session = worldSession();
+    const at = chunk ? chunkInput(chunk) : session.self.chunk;
+    if (!at) throw new Error('Join the world before chatting');
+    this.sequence = (this.sequence + 1) % 256;
+    await this.network.game.udp.sendTextPacket({
+      appId: this.network.appId!,
+      chunk: at,
+      uuid: session.self.uuid,
+      text: trimmed,
+      sequenceNumber: this.sequence,
+      distance: REPLICATION_DISTANCE,
+    });
+    // The platform echoes our own text back as a notification, which is what
+    // appends it to history — no optimistic insert, so what you see is what
+    // everyone else saw.
+  }
+
+  /** Local-only line (system notices), never sent. */
+  system(text: string): void {
+    this.push({ uuid: '', name: 'construct', text, self: false });
+  }
+
+  private push(entry: Omit<ChatMessage, 'id' | 'at'>): void {
+    const message: ChatMessage = { id: this.nextId++, at: Date.now(), ...entry };
+    this.history.push(message);
+    if (this.history.length > 200) this.history.shift();
+    this.events.emit('message', message);
+  }
+}
+
+function shortUuid(uuid: string): string {
+  return `player-${uuid.slice(0, 6)}`;
+}

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

@@ -0,0 +1,56 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { ClientModLifecycle } from './ClientModLifecycle';
+
+const d = (id: string, artifactHash = 'a', capabilityHash = 'c') => ({
+  attachmentId: id,
+  artifactHash,
+  capabilityHash,
+});
+
+describe('ClientModLifecycle', () => {
+  it('stops every worker when the grid changes', () => {
+    const life = new ClientModLifecycle();
+    expect(life.enterGrid('g1')).toBe(true);
+    const scope = life.scope('g1')!;
+    const stop = vi.fn();
+    expect(life.track(scope, d('m1'), { stop })).toBe(true);
+    expect(life.enterGrid('g1')).toBe(false);
+    expect(life.enterGrid('g2')).toBe(true);
+    expect(stop).toHaveBeenCalledTimes(1);
+    expect(life.runningCount).toBe(0);
+  });
+
+  it('rejects a worker that finished starting after the grid changed', () => {
+    const life = new ClientModLifecycle();
+    life.enterGrid('g1');
+    const stale = life.scope('g1')!;
+    life.enterGrid('g2');
+    const stop = vi.fn();
+    expect(life.track(stale, d('m1'), { stop })).toBe(false);
+    expect(stop).toHaveBeenCalled();
+  });
+
+  it('reconciles by immutable hashes', () => {
+    const life = new ClientModLifecycle();
+    life.enterGrid('g1');
+    const scope = life.scope('g1')!;
+    const stopA = vi.fn();
+    const stopB = vi.fn();
+    life.track(scope, d('a'), { stop: stopA });
+    life.track(scope, d('b'), { stop: stopB });
+    expect(life.reconcile(scope, [d('a'), d('b', 'a2')])).toBe(true);
+    expect(stopA).not.toHaveBeenCalled();
+    expect(stopB).toHaveBeenCalled();
+    expect(life.has('a')).toBe(true);
+    expect(life.has('b')).toBe(false);
+  });
+
+  it('is inert after shutdown', () => {
+    const life = new ClientModLifecycle();
+    life.enterGrid('g1');
+    life.shutdown();
+    expect(life.enterGrid('g2')).toBe(false);
+    expect(life.scope('g2')).toBeNull();
+  });
+});

package/src/platform/studio/ClientModLifecycle.ts

@@ -0,0 +1,102 @@
+/**
+ * Owns the worker handles of grid-attached CLIENT mods independently of any
+ * scene. Every metadata refresh reconciles immutable hashes; changing grids
+ * synchronously tears everything down; a worker that finishes starting after
+ * a grid change (or shutdown) is stopped instead of attached stale.
+ */
+export interface ClientModDescriptor {
+  attachmentId: string;
+  artifactHash: string;
+  capabilityHash: string;
+}
+
+export interface ClientModHandle {
+  stop: () => void;
+}
+
+export interface ClientModScope {
+  gridId: string;
+  generation: number;
+}
+
+interface RunningClientMod extends ClientModDescriptor, ClientModHandle {}
+
+export class ClientModLifecycle {
+  private readonly running = new Map<string, RunningClientMod>();
+  private activeGridId: string | null = null;
+  private generation = 0;
+  private stopped = false;
+
+  /** Returns true when the grid actually changed (callers reset their caches). */
+  enterGrid(gridId: string | null): boolean {
+    if (this.stopped) return false;
+    if (gridId === this.activeGridId) return false;
+    this.stopAll();
+    this.activeGridId = gridId;
+    this.generation++;
+    return true;
+  }
+
+  get currentGridId(): string | null {
+    return this.activeGridId;
+  }
+
+  has(attachmentId: string): boolean {
+    return this.running.has(attachmentId);
+  }
+
+  get runningCount(): number {
+    return this.running.size;
+  }
+
+  scope(gridId: string): ClientModScope | null {
+    if (this.stopped || gridId !== this.activeGridId) return null;
+    return { gridId, generation: this.generation };
+  }
+
+  isCurrent(scope: ClientModScope): boolean {
+    return (
+      !this.stopped && scope.gridId === this.activeGridId && scope.generation === this.generation
+    );
+  }
+
+  track(scope: ClientModScope, descriptor: ClientModDescriptor, handle: ClientModHandle): boolean {
+    if (!this.isCurrent(scope) || this.running.has(descriptor.attachmentId)) {
+      handle.stop();
+      return false;
+    }
+    this.running.set(descriptor.attachmentId, { ...descriptor, ...handle });
+    return true;
+  }
+
+  /** Stop mods that disappeared or changed hash; returns false if scope is stale. */
+  reconcile(scope: ClientModScope, descriptors: readonly ClientModDescriptor[]): boolean {
+    if (!this.isCurrent(scope)) return false;
+    const current = new Map(descriptors.map((d) => [d.attachmentId, d]));
+    for (const [attachmentId, running] of this.running) {
+      const next = current.get(attachmentId);
+      if (
+        !next ||
+        next.artifactHash !== running.artifactHash ||
+        next.capabilityHash !== running.capabilityHash
+      ) {
+        running.stop();
+        this.running.delete(attachmentId);
+      }
+    }
+    return true;
+  }
+
+  private stopAll(): void {
+    for (const running of this.running.values()) running.stop();
+    this.running.clear();
+  }
+
+  shutdown(): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.activeGridId = null;
+    this.generation++;
+    this.stopAll();
+  }
+}

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

@@ -0,0 +1,159 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { AgentLocomotion } from './agentLocomotion';
+import {
+  CONSTRUCT_AGENT_TOOL_NAMES,
+  ConstructPlayerHostAdapter,
+  capabilityRevisionFor,
+  type ConstructObservationFrame,
+} from './ConstructPlayerHostAdapter';
+import { studioPermissions } from './permissions';
+import type { GridSnapshot } from './GridService';
+
+function grid(owned = true): GridSnapshot {
+  return {
+    gridId: '99',
+    bounds: { low: { x: '0', y: '0', z: '0' }, high: { x: '0', y: '0', z: '0' } },
+    permissions: studioPermissions(['write_server_code', 'run_server_code']),
+    owned,
+  };
+}
+
+function frame(over: Partial<ConstructObservationFrame> = {}): ConstructObservationFrame {
+  return {
+    playerId: 'player-1',
+    position: { x: 1, y: 0, z: 2 },
+    velocity: { x: 0, y: 0, z: 0 },
+    yaw: 0.5,
+    pitch: -0.1,
+    grid: grid(),
+    nearbyActors: [{ actorId: 'p2', position: { x: 3, y: 0, z: 2 }, label: 'Ada' }],
+    humanInputActive: false,
+    textInputFocused: false,
+    modalOpen: false,
+    ...over,
+  };
+}
+
+function setup(over: Partial<ConstructObservationFrame> = {}) {
+  const current = { value: frame(over) };
+  const locomotion = new AgentLocomotion();
+  const sendChat = vi.fn(async () => undefined);
+  const adapter = new ConstructPlayerHostAdapter({
+    frame: () => current.value,
+    locomotion,
+    sendChat,
+    now: () => 1_000,
+  });
+  return { adapter, current, locomotion, sendChat };
+}
+
+describe('ConstructPlayerHostAdapter', () => {
+  it('advertises only observe, move, look, stop, and local chat', async () => {
+    const { adapter } = setup();
+    const capabilities = await adapter.capabilities();
+    expect(capabilities.gameId).toBe('the-construct');
+    expect(capabilities.commands.map((c) => c.toolName)).toEqual(
+      CONSTRUCT_AGENT_TOOL_NAMES.slice(2),
+    );
+    expect(
+      capabilities.commands.some((c) => /inventory|combat|craft|mount|teleport/i.test(c.toolName)),
+    ).toBe(false);
+  });
+
+  it('observes nearby players and the current grid', async () => {
+    const { adapter } = setup();
+    const observation = await adapter.observe({
+      detail: 'STANDARD',
+      maxNearbyActors: 8,
+      maxNearbyVoxels: 8,
+    });
+    expect(observation.contractVersion).toBe('crowdy.game-observation/1');
+    expect(observation.nearbyActors).toHaveLength(1);
+    expect(observation.nearbyActors[0]?.label).toBe('Ada');
+    expect(observation.grid?.gridRef).toBe('99');
+    expect(observation.nearbyVoxels).toEqual([]);
+  });
+
+  it('applies MOVE to locomotion and denies GROUP chat', async () => {
+    const { adapter, locomotion, sendChat } = setup();
+    const observation = await adapter.observe({
+      detail: 'MINIMAL',
+      maxNearbyActors: 0,
+      maxNearbyVoxels: 0,
+    });
+    const gate = {
+      contractVersion: 'crowdy.validated-gate/1' as const,
+      clientEpoch: '1',
+      leaseId: 'lease-1',
+      scopes: ['locomotion', 'communicate'] as const,
+      contextVersion: '1',
+      observationId: observation.observationId,
+      validatedAt: new Date().toISOString(),
+    };
+    const moved = await adapter.dispatch(
+      {
+        kind: 'MOVE',
+        observationId: observation.observationId,
+        capabilityRevision: observation.capabilityRevision,
+        controlledEntityId: observation.controlledEntityId,
+        direction: 'FORWARD',
+        intensity: 1,
+        durationMs: 200,
+      },
+      gate,
+    );
+    expect(moved.status).toBe('SUCCEEDED');
+    expect(locomotion.sample(1_050).y).toBe(1);
+
+    const chat = await adapter.dispatch(
+      {
+        kind: 'CHAT_SEND',
+        observationId: observation.observationId,
+        capabilityRevision: observation.capabilityRevision,
+        controlledEntityId: observation.controlledEntityId,
+        channel: 'GROUP',
+        text: 'nope',
+      },
+      { ...gate, scopes: ['communicate'] },
+    );
+    expect(chat.status).toBe('DENIED');
+    expect(sendChat).not.toHaveBeenCalled();
+  });
+
+  it('preempts when human input is active', async () => {
+    const { adapter, current } = setup();
+    const observation = await adapter.observe({
+      detail: 'MINIMAL',
+      maxNearbyActors: 0,
+      maxNearbyVoxels: 0,
+    });
+    current.value = { ...current.value, humanInputActive: true };
+    const result = await adapter.dispatch(
+      {
+        kind: 'LOOK',
+        observationId: observation.observationId,
+        capabilityRevision: observation.capabilityRevision,
+        controlledEntityId: observation.controlledEntityId,
+        deltaYaw: 10,
+        deltaPitch: 0,
+      },
+      {
+        contractVersion: 'crowdy.validated-gate/1',
+        clientEpoch: '1',
+        scopes: ['locomotion'],
+        contextVersion: '1',
+        observationId: observation.observationId,
+        validatedAt: new Date().toISOString(),
+      },
+    );
+    expect(result.status).toBe('DENIED');
+    expect(result.error?.code).toBe('AGENT_PREEMPTED');
+  });
+
+  it('changes capability revision when the grid changes', () => {
+    const a = capabilityRevisionFor(frame());
+    const b = capabilityRevisionFor(frame({ grid: null }));
+    expect(a).not.toBe(b);
+  });
+});