@vulfram/engine 0.5.6-alpha

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@vulfram/engine",
+  "version": "0.5.6-alpha",
+  "module": "src/index.ts",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "type": "module",
+  "dependencies": {
+    "@vulfram/transport-types": "^0.2.1",
+    "gl-matrix": "^3.4.4",
+    "glob": "^13.0.0",
+    "msgpackr": "^1.11.8"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.6"
+  }
+}

package/src/engine/api.ts

@@ -0,0 +1,282 @@
+import type { EngineTransportFactory } from '@vulfram/transport-types';
+import {
+  collectCommands,
+  routeEvents,
+  routeResponses,
+} from './bridge/dispatch';
+import { requireInitialized } from './bridge/guards';
+import {
+  deserializeEvents,
+  deserializeResponses,
+  serializeBatch,
+} from './bridge/protocol';
+import type { ComponentSchema, System, SystemContext, SystemStep } from './ecs';
+import { EngineError } from './errors';
+import { engineState, REQUIRED_SYSTEMS, type WorldState } from './state';
+import * as CoreSystems from './systems';
+import type { UploadType } from '../types/kinds';
+
+export * from './world/entities';
+
+/**
+ * Initializes the engine runtime and registers core systems.
+ * Call once before creating worlds or issuing commands.
+ */
+export function initEngine(config: {
+  /** Transport factory for the runtime (WASM, Bun, N-API, etc.). */
+  transport: EngineTransportFactory;
+  /** Enables verbose debug logs and extra diagnostics. */
+  debug?: boolean;
+}): void {
+  if (engineState.status === 'initialized') {
+    throw new EngineError('AlreadyInitialized', 'Engine already initialized.');
+  }
+
+  // Reset Engine State for fresh start (important if re-initializing after dispose)
+  engineState.worlds.clear();
+  engineState.commandBatch = [];
+  engineState.commandTracker.clear();
+  engineState.nextEntityId = 1;
+  engineState.nextCommandId = 1;
+  engineState.registry.systems.input = [];
+  engineState.registry.systems.update = [];
+  engineState.registry.systems.preRender = [];
+  engineState.registry.systems.postRender = [];
+
+  engineState.flags.debugEnabled = config.debug ?? false;
+
+  const transport = config.transport();
+  const result = transport.vulframInit();
+  if (result !== 0) {
+    throw new EngineError(
+      'InitFailed',
+      `vulframInit failed with code ${result}.`,
+    );
+  }
+
+  engineState.transport = transport;
+  engineState.status = 'initialized';
+
+  // Register Core Systems
+  registerSystem('input', CoreSystems.InputMirrorSystem);
+  registerSystem('update', CoreSystems.CommandIntentSystem);
+  registerSystem('update', CoreSystems.WorldLifecycleSystem);
+  registerSystem('update', CoreSystems.ResourceUploadSystem);
+  registerSystem('preRender', CoreSystems.CoreCommandBuilderSystem);
+  registerSystem('postRender', CoreSystems.ResponseDecodeSystem);
+  registerSystem('postRender', CoreSystems.DiagnosticsSystem);
+}
+
+/**
+ * Disposes the engine and releases the active transport.
+ * After dispose, you must call initEngine again to use the engine.
+ */
+export function disposeEngine(): void {
+  requireInitialized();
+  const transport = engineState.transport;
+  if (transport) {
+    transport.vulframDispose();
+  }
+  engineState.transport = null;
+  engineState.worlds.clear();
+  engineState.commandBatch = [];
+  engineState.commandTracker.clear();
+  engineState.status = 'disposed';
+}
+
+/**
+ * Registers a custom component schema for editor tooling or extensions.
+ */
+export function registerComponent(name: string, schema: ComponentSchema): void {
+  requireInitialized();
+  engineState.registry.components.set(name, schema);
+}
+
+/**
+ * Registers a system to run at a specific pipeline step.
+ */
+export function registerSystem(step: SystemStep, system: System): void {
+  requireInitialized();
+  engineState.registry.systems[step].push(system);
+}
+
+function uploadTypeToId(type: UploadType): number {
+  switch (type) {
+    case 'raw':
+      return 0;
+    case 'shader-source':
+      return 1;
+    case 'geometry-data':
+      return 2;
+    case 'vertex-data':
+      return 3;
+    case 'index-data':
+      return 4;
+    case 'image-data':
+      return 5;
+    case 'binary-asset':
+      return 6;
+  }
+}
+
+/**
+ * Uploads a raw buffer to the engine's GPU memory or internal storage.
+ * @param bufferId Unique ID for this buffer.
+ * @param type Type of data in the buffer (ImageData, VertexData, etc).
+ * @param data The raw binary data.
+ */
+/**
+ * Uploads a raw buffer to the core for later use (textures, geometry, etc.).
+ */
+export function uploadBuffer(
+  bufferId: number,
+  type: UploadType,
+  data: Uint8Array | Buffer,
+): void {
+  requireInitialized();
+  const transport = engineState.transport!;
+  const bufferData = data instanceof Uint8Array ? Buffer.from(data) : data;
+  const result = transport.vulframUploadBuffer(
+    bufferId,
+    uploadTypeToId(type),
+    bufferData,
+  );
+  if (result !== 0) {
+    throw new EngineError(
+      'UploadFailed',
+      `vulframUploadBuffer failed for ID ${bufferId} with code ${result}.`,
+    );
+  }
+}
+
+/**
+ * Creates a world bound to a window ID. Returns the world ID.
+ */
+export function createWorld(windowId: number): number {
+  requireInitialized();
+  if (engineState.worlds.has(windowId)) {
+    throw new EngineError('WorldExists', `World ${windowId} already exists.`);
+  }
+
+  const world: WorldState = {
+    windowId,
+    entities: new Set(),
+    components: new Map(),
+    nextCoreId: 100,
+    systems: [...REQUIRED_SYSTEMS],
+    pendingIntents: [],
+    internalEvents: [],
+    pendingCommands: [],
+    inboundEvents: [],
+    inboundResponses: [],
+  };
+
+  engineState.worlds.set(windowId, world);
+  return windowId;
+}
+
+/**
+ * Main engine tick.
+ * Orchestrates event routing, world updates, command collection, and core synchronization.
+ */
+/**
+ * Advances the engine by one frame.
+ * Call once per frame with monotonic time and delta in milliseconds.
+ */
+export function tick(timeMs: number, deltaMs: number): void {
+  requireInitialized();
+  const transport = engineState.transport!;
+
+  // 1. Engine Phase: Receive from Core (Input Pipeline)
+  // We process events and responses received since last frame
+  const eventsResult = transport.vulframReceiveEvents();
+  if (eventsResult.result === 0 && eventsResult.buffer.length > 0) {
+    const events = deserializeEvents(eventsResult.buffer);
+    routeEvents(events);
+  }
+
+  const responsesResult = transport.vulframReceiveQueue();
+  if (responsesResult.result === 0 && responsesResult.buffer.length > 0) {
+    const responses = deserializeResponses(responsesResult.buffer);
+    routeResponses(responses);
+  }
+
+  // 2. Engine Phase: Clock & Context Preparation
+  const cappedDelta = Math.min(deltaMs, 100);
+  engineState.clock.lastTime = timeMs;
+  engineState.clock.lastDelta = cappedDelta;
+  engineState.clock.frameCount++;
+
+  const context: SystemContext = {
+    dt: cappedDelta / 1000,
+    time: timeMs / 1000,
+    worldId: 0,
+  };
+
+  // 3. World Phase: System Execution
+  engineState.flags.isExecutingSystems = true;
+  try {
+    for (const [worldId, world] of engineState.worlds) {
+      context.worldId = worldId;
+      executeSystemStep(world, context, 'input');
+      executeSystemStep(world, context, 'update');
+      executeSystemStep(world, context, 'preRender');
+      executeSystemStep(world, context, 'postRender');
+    }
+  } finally {
+    engineState.flags.isExecutingSystems = false;
+  }
+
+  // 4. Engine Phase: Collect & Send (Output Pipeline)
+  collectCommands();
+
+  if (engineState.commandBatch.length > 0) {
+    const batchBuffer = serializeBatch(engineState.commandBatch);
+    const result = transport.vulframSendQueue(batchBuffer);
+    if (result !== 0) {
+      console.error(
+        `[Vulfram] vulframSendQueue failed with result ${result}. This usually indicates a MessagePack serialization mismatch between Host and Core.`,
+      );
+      for (const cmd of engineState.commandBatch) {
+        engineState.commandTracker.delete(cmd.id);
+      }
+      if (engineState.flags.debugEnabled) {
+        console.group('[Vulfram Debug] Failed Batch');
+        console.debug('Result:', result);
+        console.debug('Batch Size:', batchBuffer.length, 'bytes');
+        console.debug(
+          'Command Types:',
+          engineState.commandBatch.map((c) => c.type),
+        );
+        console.groupEnd();
+      }
+    }
+    engineState.commandBatch = [];
+  }
+
+  // 5. Core Phase: Execute Tick
+  transport.vulframTick(timeMs, deltaMs);
+}
+
+/**
+ * Executes a specific group of systems with error handling.
+ */
+function executeSystemStep(
+  world: WorldState,
+  context: SystemContext,
+  step: SystemStep,
+): void {
+  const systems = engineState.registry.systems[step];
+  for (const system of systems) {
+    try {
+      system(world, context);
+    } catch (err) {
+      console.error(
+        `[SystemError] World ${context.worldId} | Step: ${step} | System: ${
+          system.name || 'anonymous'
+        }\n`,
+        err,
+      );
+    }
+  }
+}

package/src/engine/bridge/dispatch.ts

@@ -0,0 +1,115 @@
+import type { CommandResponseEnvelope, EngineCmd } from '../../types/cmds';
+import type { EngineEvent } from '../../types/events';
+import { engineState } from '../state';
+import { getWorldOrThrow, requireInitialized } from './guards';
+
+/**
+ * Limits for Backpressure management.
+ */
+const MAX_BATCH_COMMANDS = 2048;
+
+/**
+ * Enqueues a command to be sent to the core in the next tick.
+ * Ensures the command is routed through the specific world.
+ */
+export function enqueueCommand<T extends EngineCmd['type']>(
+  worldId: number,
+  type: T,
+  content: Extract<EngineCmd, { type: T }>['content'],
+): number {
+  requireInitialized();
+  const world = getWorldOrThrow(worldId);
+  const id = engineState.nextCommandId++;
+
+  // Contract: windowId must match worldId (windowId) if present in content
+  const typedContent = content as Record<string, unknown>;
+  if ('windowId' in typedContent) {
+    typedContent.windowId = world.windowId;
+  }
+
+  world.pendingCommands.push({ id, type, content });
+  return id;
+}
+
+/**
+ * Collects pending commands from all worlds into the global engine batch.
+ * Implements BatchAggregatorSystem and basic BackpressureSystem logic.
+ */
+export function collectCommands(): void {
+  let collectedCount = 0;
+
+  for (const [worldId, world] of engineState.worlds) {
+    if (collectedCount >= MAX_BATCH_COMMANDS) {
+      // Backpressure: If we reached the limit, stop collecting for this frame.
+      // Remaining commands will wait for the next frame.
+      break;
+    }
+
+    if (world.pendingCommands.length > 0) {
+      // Determine how many we can take from this world
+      const remainingSpace = MAX_BATCH_COMMANDS - collectedCount;
+      const amountToTake = Math.min(
+        world.pendingCommands.length,
+        remainingSpace,
+      );
+
+      const cmdsToPush = world.pendingCommands.splice(0, amountToTake);
+      for (const cmd of cmdsToPush) {
+        engineState.commandBatch.push(cmd);
+        engineState.commandTracker.set(cmd.id, worldId);
+      }
+      collectedCount += amountToTake;
+    }
+  }
+}
+
+/**
+ * Routes core events to their respective worlds based on windowId.
+ */
+export function routeEvents(events: EngineEvent[]): void {
+  for (const event of events) {
+    // Determine windowId from event content
+    // Events have structure: { type, content: { event, data: { windowId, ... } } }
+    let windowId: number | undefined;
+
+    if ('data' in event.content && event.content.data) {
+      const eventData = event.content.data as unknown as Record<
+        string,
+        unknown
+      >;
+      windowId =
+        typeof eventData.windowId === 'number' ? eventData.windowId : undefined;
+    } else if ('windowId' in event.content) {
+      const eventContent = event.content as Record<string, unknown>;
+      windowId =
+        typeof eventContent.windowId === 'number'
+          ? eventContent.windowId
+          : undefined;
+    }
+
+    if (windowId !== undefined) {
+      const world = engineState.worlds.get(windowId);
+      if (world) {
+        world.inboundEvents.push(event);
+      }
+    } else {
+      // Global events (if any) could be handled here
+    }
+  }
+}
+
+/**
+ * Routes core responses back to the world that initiated the command.
+ */
+export function routeResponses(responses: CommandResponseEnvelope[]): void {
+  for (const res of responses) {
+    const worldId = engineState.commandTracker.get(res.id);
+    if (worldId !== undefined) {
+      const world = engineState.worlds.get(worldId);
+      if (world) {
+        world.inboundResponses.push(res);
+      }
+      engineState.commandTracker.delete(res.id);
+    }
+  }
+}

package/src/engine/bridge/guards.ts

@@ -0,0 +1,28 @@
+import { EngineError } from '../errors';
+import { engineState, type WorldState } from '../state';
+
+export function requireInitialized(): void {
+  if (engineState.status === 'disposed') {
+    throw new EngineError('Disposed', 'Engine has been disposed.');
+  }
+  if (engineState.status !== 'initialized') {
+    throw new EngineError('NotInitialized', 'Engine is not initialized.');
+  }
+}
+
+export function getWorldOrThrow(worldId: number): WorldState {
+  const world = engineState.worlds.get(worldId);
+  if (!world) {
+    throw new EngineError('WorldNotFound', `World ${worldId} not found.`);
+  }
+  return world;
+}
+
+export function ensureEntity(world: WorldState, entityId: number): void {
+  if (!world.entities.has(entityId)) {
+    throw new EngineError(
+      'EntityNotFound',
+      `Entity ${entityId} not found in World ${world.windowId}.`,
+    );
+  }
+}

package/src/engine/bridge/protocol.ts

@@ -0,0 +1,130 @@
+import { Packr, Unpackr } from 'msgpackr';
+import type {
+  CommandResponseEnvelope,
+  EngineCmdEnvelope,
+} from '../../types/cmds';
+import type { EngineEvent } from '../../types/events';
+import { engineState } from '../state';
+
+/**
+ * Vulfram Core/ABI Invariants:
+ *
+ * 1. Threading:
+ *    - The Core expects to be ticked and communicated with from a single host thread (Main Thread).
+ *    - FFI/N-API calls are synchronous but the logic they trigger in the core (GPU work) is asynchronous.
+ *
+ * 2. Temporal Stability (Tick):
+ *    - `vulframTick` must be called once per frame.
+ *    - Incorrect or skipped ticks can lead to uneven animations, input lag, or resource starvation.
+ *
+ * 3. Command Batching:
+ *    - All High-Level Logic commands are batched into a single MessagePack-encoded buffer.
+ *    - The batch is sent once per frame via `vulframSendQueue`.
+ *    - Maximum batch size is defined by the Core (currently 64KB for safety, but adjustable).
+ *
+ * 4. Events & Responses:
+ *    - Responses: Every command sent in a batch will eventually produce a response in `vulframReceiveQueue`.
+ *      Responses are matched back to commands using the `id` field in the envelope.
+ *    - Events: System-level events (Keyboard, Mouse, Window resize) are polled via `vulframReceiveEvents`.
+ *
+ * 5. Resource Uploads:
+ *    - Larger data (Textures, Geometry data) are sent via `vulframUploadBuffer` to avoid bloating the command batch.
+ *    - These are out-of-band and acknowledged via specific events or response IDs.
+ *
+ * 6. ID Management:
+ *    - The Host (this ECS) is responsible for generating and managing Logical IDs for all entities, components, and resources.
+ *    - The Core uses these IDs to track objects. Reusing an ID without disposing of the previous object will cause errors or undefined behavior.
+ */
+
+/**
+ * Batch Scheme:
+ * A batch is simply an array of EngineCmdEnvelope objects.
+ */
+export type CoreCommandBatch = EngineCmdEnvelope[];
+
+const packr = new Packr({ useRecords: false });
+const unpackr = new Unpackr({ useRecords: false });
+
+/**
+ * Minimal Command Payload Requirement:
+ * Commands that interact with the scene or windows MUST include a `windowId`.
+ * This allows the Core to route the command to the correct world/surface.
+ */
+export interface BaseCommandArgs {
+  windowId: number;
+}
+
+/**
+ * Serializes a batch of commands into a Buffer ready for vulframSendQueue.
+ */
+export function serializeBatch(batch: CoreCommandBatch): Buffer {
+  if (engineState.flags.debugEnabled) {
+    const types = batch.map((cmd) => cmd.type);
+    const hasModel =
+      types.includes('cmd-model-create') || types.includes('cmd-model-update');
+    const hasResource = types.some(
+      (type) =>
+        type === 'cmd-primitive-geometry-create' ||
+        type === 'cmd-geometry-create' ||
+        type === 'cmd-material-create' ||
+        type === 'cmd-texture-create-from-buffer' ||
+        type === 'cmd-texture-create-solid-color',
+    );
+    if (hasModel || hasResource) {
+      console.debug('[Debug] BatchTypes', types);
+      const modelCreate = batch.find((cmd) => cmd.type === 'cmd-model-create');
+      if (modelCreate) {
+        console.debug(
+          '[Debug] ModelCreatePayload',
+          JSON.stringify(modelCreate.content),
+        );
+      }
+      const primitiveGeo = batch.find(
+        (cmd) => cmd.type === 'cmd-primitive-geometry-create',
+      );
+      if (primitiveGeo) {
+        console.debug(
+          '[Debug] GeometryPayload',
+          JSON.stringify(primitiveGeo.content),
+        );
+      }
+      const materialCreate = batch.find(
+        (cmd) => cmd.type === 'cmd-material-create',
+      );
+      if (materialCreate) {
+        console.debug(
+          '[Debug] MaterialPayload',
+          JSON.stringify(materialCreate.content),
+        );
+      }
+      const textureCreate = batch.find(
+        (cmd) => cmd.type === 'cmd-texture-create-from-buffer',
+      );
+      if (textureCreate) {
+        console.debug(
+          '[Debug] TexturePayload',
+          JSON.stringify(textureCreate.content),
+        );
+      }
+    }
+  }
+  return packr.pack(batch);
+}
+
+/**
+ * Deserializes responses from vulframReceiveQueue.
+ */
+export function deserializeResponses(
+  buffer: Buffer,
+): CommandResponseEnvelope[] {
+  if (buffer.length === 0) return [];
+  return unpackr.unpack(buffer);
+}
+
+/**
+ * Deserializes events from vulframReceiveEvents.
+ */
+export function deserializeEvents(buffer: Buffer): EngineEvent[] {
+  if (buffer.length === 0) return [];
+  return unpackr.unpack(buffer);
+}