@vibevibes/runtime 0.2.0

package/src/tick-engine.ts

@@ -0,0 +1,216 @@
+/**
+ * Tick Engine — server-side tick loop for experiences with netcode: "tick".
+ *
+ * Runs at a fixed tick rate, executing tool calls from the tick context.
+ * The tick engine provides the timing infrastructure; experiences define
+ * what happens each tick via their tool handlers.
+ */
+
+import type { ToolCtx, ToolEvent } from "@vibevibes/sdk";
+import type { EventEmitter } from "events";
+
+// ── Interfaces ────────────────────────────────────────────────────────────────
+
+/** ToolEvent extended with observation field (computed server-side after tool execution). */
+interface TickToolEvent extends ToolEvent {
+  observation?: Record<string, unknown>;
+}
+
+/** Minimal Room interface — what the tick engine needs from a room. */
+export interface TickRoom {
+  readonly id: string;
+  readonly experienceId: string;
+  readonly config: Record<string, unknown>;
+  sharedState: Record<string, unknown>;
+  participantList(): string[];
+  broadcastToAll(message: Record<string, unknown>): void;
+  broadcastStateUpdate?(extra: { changedBy: string; tick?: unknown }, forceFullState?: boolean): void;
+  appendEvent(event: TickToolEvent): void;
+  enqueueExecution<T>(fn: () => Promise<T>): Promise<T>;
+}
+
+/** Minimal experience interface — what the tick engine needs. */
+export interface TickExperience {
+  module: {
+    manifest: { id: string };
+    tools: Array<{
+      name: string;
+      input_schema?: { parse?: (input: unknown) => unknown };
+      handler: (ctx: ToolCtx, input: unknown) => Promise<unknown>;
+    }>;
+    observe?: (state: Record<string, unknown>, event: TickToolEvent, actorId: string) => Record<string, unknown>;
+  };
+}
+
+// ── Tick Engine ───────────────────────────────────────────────────────────────
+
+const TICK_ACTOR_ID = "_tick-engine";
+const TICK_OWNER = "_system";
+
+export class TickEngine {
+  private room: TickRoom;
+  private experience: TickExperience;
+  private roomEvents: EventEmitter;
+  private interval: ReturnType<typeof setTimeout> | null = null;
+  private tickCount = 0;
+  private tickRateMs: number;
+  private startedAt: number = 0;
+  private _running = false;
+  private _stopped = false;
+  private _stateSetThisTick = false;
+
+  constructor(
+    room: TickRoom,
+    experience: TickExperience,
+    roomEvents: EventEmitter,
+    tickRateMs: number = 50,
+  ) {
+    this.room = room;
+    this.experience = experience;
+    this.roomEvents = roomEvents;
+    this.tickRateMs = tickRateMs;
+  }
+
+  /** Start the tick loop. Uses self-correcting setTimeout to prevent timing drift. */
+  start(): void {
+    if (this.interval) return;
+    this._stopped = false;
+    this.tickCount = 0;
+    this.startedAt = Date.now();
+    this.scheduleNext();
+  }
+
+  /** Schedule the next tick with drift correction. */
+  private scheduleNext(): void {
+    if (this._stopped) return;
+    const expected = this.startedAt + (this.tickCount + 1) * this.tickRateMs;
+    const delay = Math.max(0, expected - Date.now());
+    this.interval = setTimeout(() => {
+      this.tick().then(() => this.scheduleNext(), () => this.scheduleNext());
+    }, delay);
+  }
+
+  /** Stop the tick loop. */
+  stop(): void {
+    this._stopped = true;
+    this._running = false;
+    if (this.interval) {
+      clearTimeout(this.interval);
+      this.interval = null;
+    }
+  }
+
+  /** Mark dirty — no-op in simplified engine, kept for API compat. */
+  markDirty(): void {}
+
+  /** Get current tick status. */
+  getStatus(): {
+    enabled: boolean;
+    tickRateMs: number;
+    tickCount: number;
+  } {
+    return {
+      enabled: this.interval !== null,
+      tickRateMs: this.tickRateMs,
+      tickCount: this.tickCount,
+    };
+  }
+
+  /** Execute one tick cycle. */
+  private async tick(): Promise<void> {
+    if (this._running) return;
+    this._running = true;
+    try {
+      this.tickCount++;
+    } finally {
+      this._running = false;
+    }
+  }
+
+  /** Execute a tool call internally (no HTTP round-trip). */
+  async executeTool(
+    toolName: string,
+    input: Record<string, unknown>,
+    callerActorId?: string,
+    expiredFlag?: { value: boolean },
+  ): Promise<{ output?: unknown; error?: string }> {
+    const tool = this.experience.module.tools.find((t) => t.name === toolName);
+    if (!tool) {
+      return { error: `Tool '${toolName}' not found` };
+    }
+
+    const actorId = callerActorId || TICK_ACTOR_ID;
+    const owner = callerActorId || TICK_OWNER;
+
+    try {
+      let validatedInput: Record<string, unknown> = input as Record<string, unknown>;
+      if (tool.input_schema?.parse) {
+        validatedInput = tool.input_schema.parse(input) as Record<string, unknown>;
+      }
+
+      const self = this;
+      const ctxBase = {
+        roomId: this.room.id,
+        actorId,
+        owner,
+        state: null as unknown as Record<string, unknown>,
+        setState: (newState: Record<string, unknown>) => {
+          if (expiredFlag?.value) return;
+          self.room.sharedState = newState;
+          self._stateSetThisTick = true;
+        },
+        timestamp: Date.now(),
+        memory: {},
+        setMemory: () => {},
+        roomConfig: this.room.config || {},
+      };
+      Object.defineProperty(ctxBase, 'state', {
+        get() { return self.room.sharedState; },
+        enumerable: true,
+        configurable: true,
+      });
+      const ctx = ctxBase as ToolCtx;
+
+      const output = await tool.handler(ctx, validatedInput);
+
+      const event: TickToolEvent = {
+        id: `tick-${this.tickCount}-${toolName}-${Math.random().toString(36).slice(2, 6)}`,
+        ts: Date.now(),
+        actorId: TICK_ACTOR_ID,
+        owner: TICK_OWNER,
+        tool: toolName,
+        input: validatedInput,
+        output,
+      };
+
+      if (this.experience.module.observe) {
+        try {
+          event.observation = this.experience.module.observe(this.room.sharedState, event, actorId);
+        } catch {
+          // Don't fail tick if observe throws
+        }
+      }
+
+      this.room.appendEvent(event);
+      this.roomEvents.emit(`room:${this.room.id}`);
+
+      return { output };
+    } catch (err: unknown) {
+      const errorMsg = err instanceof Error ? err.message : String(err);
+
+      const event: TickToolEvent = {
+        id: `tick-${this.tickCount}-${toolName}-${Math.random().toString(36).slice(2, 6)}`,
+        ts: Date.now(),
+        actorId: TICK_ACTOR_ID,
+        owner: TICK_OWNER,
+        tool: toolName,
+        input,
+        error: errorMsg,
+      };
+      this.room.appendEvent(event);
+      this.roomEvents.emit(`room:${this.room.id}`);
+
+      return { error: errorMsg };
+    }
+  }
+}