@vulfram/engine 0.5.8-alpha → 0.17.1-alpha

package/README.md

@@ -0,0 +1,106 @@
+# @vulfram/engine
+
+Functional engine for the Vulfram core, focused on a simple API for creating worlds, entities, and mounting to targets.
+
+## Installation
+
+```bash
+bun add @vulfram/engine @vulfram/transport-wasm
+```
+
+Use the transport that fits your environment (`transport-wasm`, `transport-bun`, `transport-napi`).
+
+## Simple example
+
+```ts
+import { initEngine, tick } from '@vulfram/engine/core';
+import { createWindow } from '@vulfram/engine/window';
+import { mountWorldToWindow } from '@vulfram/engine/mount';
+import * as World3D from '@vulfram/engine/world3d';
+import { transportWasm } from '@vulfram/transport-wasm';
+
+initEngine({ transport: transportWasm });
+
+const world = World3D.create3DWorld();
+const { windowId } = createWindow({
+  title: 'Vulfram Engine - Simple Demo',
+  size: [1280, 720],
+  position: [100, 100],
+  initialState: 'windowed',
+});
+
+mountWorldToWindow(world, windowId);
+
+const camera = World3D.create3DEntity(world);
+World3D.create3DCamera(world, camera, {
+  kind: 'perspective',
+  near: 0.1,
+  far: 100,
+  order: 0,
+});
+World3D.update3DTransform(world, camera, {
+  position: [0, 1.2, 4],
+  rotation: [0, 0, 0, 1],
+  scale: [1, 1, 1],
+});
+
+const light = World3D.create3DEntity(world);
+World3D.create3DLight(world, light, {
+  kind: 'directional',
+  color: [1, 1, 1],
+  intensity: 2,
+});
+World3D.update3DTransform(world, light, {
+  position: [3, 6, 2],
+  rotation: [0, 0, 0, 1],
+  scale: [1, 1, 1],
+});
+
+const geom = World3D.create3DGeometry(world, { type: 'primitive', shape: 'cube' });
+const mat = World3D.create3DMaterial(world, {
+  kind: 'standard',
+  options: {
+    type: 'standard',
+    content: {
+      baseColor: [0.9, 0.2, 0.2, 1],
+      surfaceType: 'opaque',
+      flags: 0,
+    },
+  },
+});
+
+const cube = World3D.create3DEntity(world);
+World3D.create3DModel(world, cube, { geometryId: geom, materialId: mat });
+World3D.update3DTransform(world, cube, {
+  position: [0, 0, 0],
+  rotation: [0, 0, 0, 1],
+  scale: [1, 1, 1],
+});
+
+let last = performance.now();
+function frame(now: number) {
+  const dt = now - last;
+  last = now;
+  tick(now, dt);
+  requestAnimationFrame(frame);
+}
+requestAnimationFrame(frame);
+```
+
+## Public module structure
+
+- `@vulfram/engine/core`: init, tick, dispose, system/component registration
+- `@vulfram/engine/window`: window APIs
+- `@vulfram/engine/world3d`: 3D world APIs
+- `@vulfram/engine/world-ui`: UI world APIs
+- `@vulfram/engine/mount`: world binding to targets/windows
+- `@vulfram/engine/ecs`: ECS types
+- `@vulfram/engine/types`: command/event types
+
+## Documentation
+
+Temporary documentation URL:
+
+- https://vulppi.dev/vulfram/docs
+
+When the final engine documentation URL is available, this README will be updated.

package/package.json

@@ -1,17 +1,68 @@
 {
   "name": "@vulfram/engine",
-  "version": "0.5.8-alpha",
+  "version": "0.17.1-alpha",
   "module": "src/index.ts",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "default": "./src/index.ts",
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    },
+    "./core": {
+      "default": "./src/core.ts",
+      "import": "./src/core.ts",
+      "types": "./src/core.ts"
+    },
+    "./window": {
+      "default": "./src/window.ts",
+      "import": "./src/window.ts",
+      "types": "./src/window.ts"
+    },
+    "./mount": {
+      "default": "./src/mount.ts",
+      "import": "./src/mount.ts",
+      "types": "./src/mount.ts"
+    },
+    "./world3d": {
+      "default": "./src/world3d.ts",
+      "import": "./src/world3d.ts",
+      "types": "./src/world3d.ts"
+    },
+    "./world-ui": {
+      "default": "./src/world-ui.ts",
+      "import": "./src/world-ui.ts",
+      "types": "./src/world-ui.ts"
+    },
+    "./ecs": {
+      "default": "./src/ecs.ts",
+      "import": "./src/ecs.ts",
+      "types": "./src/ecs.ts"
+    },
+    "./types": {
+      "default": "./src/types/index.ts",
+      "import": "./src/types/index.ts",
+      "types": "./src/types/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
-    "@vulfram/transport-types": "^0.2.2",
+    "@vulfram/transport-types": "^0.2.5",
     "gl-matrix": "^3.4.4",
-    "glob": "^13.0.0",
+    "glob": "^13.0.6",
     "msgpackr": "^1.11.8"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.8"
+    "@types/bun": "^1.3.10"
   }
 }

package/src/core.ts

@@ -0,0 +1,14 @@
+export {
+  disposeEngine,
+  initEngine,
+  registerComponent,
+  registerSystem,
+  tick,
+  uploadBuffer,
+} from './engine/api';
+export { EngineError } from './engine/errors';
+export type {
+  BufferResult,
+  EngineTransport,
+  EngineTransportFactory,
+} from '@vulfram/transport-types';

package/src/ecs.ts

@@ -0,0 +1 @@
+export * from './engine/ecs';

package/src/engine/api.ts

@@ -1,6 +1,7 @@
 import type { EngineTransportFactory } from '@vulfram/transport-types';
 import {
   collectCommands,
+  markRoutingIndexDirty,
   routeEvents,
   routeResponses,
 } from './bridge/dispatch';
@@ -15,8 +16,57 @@ import { EngineError } from './errors';
 import { engineState, REQUIRED_SYSTEMS, type WorldState } from './state';
 import * as CoreSystems from './systems';
 import type { UploadType } from '../types/kinds';
+import type { RealmKind } from '../types/cmds/realm';
+import { asWorldId, type WorldId } from './world/types';
 
-export * from './world/entities';
+export * from './window/manager';
+
+function recalculateWorldWindowBindings(world: WorldState): void {
+  world.boundWindowIds.clear();
+  for (const windowId of world.targetWindowBindings.values()) {
+    world.boundWindowIds.add(windowId);
+  }
+
+  if (world.boundWindowIds.size === 0) {
+    world.primaryWindowId = undefined;
+    return;
+  }
+
+  let primary = Number.POSITIVE_INFINITY;
+  for (const windowId of world.boundWindowIds) {
+    if (windowId < primary) {
+      primary = windowId;
+    }
+  }
+  world.primaryWindowId = primary;
+}
+
+function findLowestConfirmedWindowId(): number | undefined {
+  if (engineState.confirmedWindowIds.size === 0) {
+    return undefined;
+  }
+  let minWindowId = Number.POSITIVE_INFINITY;
+  for (const windowId of engineState.confirmedWindowIds) {
+    if (windowId < minWindowId) {
+      minWindowId = windowId;
+    }
+  }
+  return Number.isFinite(minWindowId) ? minWindowId : undefined;
+}
+
+/**
+ * Shared realm creation options used by `createWorld3D` and `createWorldUI`.
+ */
+export type CreateWorldOptions = {
+  /** Optional output surface id when provided by host integration. */
+  outputSurfaceId?: number;
+  /** Core scheduling hint for realm priority. */
+  importance?: number;
+  /** Core-side cache policy value. */
+  cachePolicy?: number;
+  /** Bit flags forwarded to realm creation in core. */
+  flags?: number;
+};
 
 /**
  * Initializes the engine runtime and registers core systems.
@@ -35,9 +85,24 @@ export function initEngine(config: {
   // Reset Engine State for fresh start (important if re-initializing after dispose)
   engineState.worlds.clear();
   engineState.commandBatch = [];
+  engineState.usedWindowIds.clear();
+  engineState.confirmedWindowIds.clear();
+  engineState.pendingWindowCreateByCommandId.clear();
+  engineState.pendingWindowCloseByCommandId.clear();
+  engineState.globalPendingCommands = [];
+  engineState.globalPendingCommandsHead = 0;
   engineState.commandTracker.clear();
+  engineState.globalCommandTracker.clear();
+  engineState.globalInboundResponses = [];
+  engineState.nextWorldId = 1;
+  engineState.nextWindowId = 1;
   engineState.nextEntityId = 1;
   engineState.nextCommandId = 1;
+  engineState.nextGlobalId = 100;
+  engineState.routingIndex.byWindowId.clear();
+  engineState.routingIndex.byRealmId.clear();
+  engineState.routingIndex.byTargetId.clear();
+  engineState.routingIndex.dirty = true;
   engineState.registry.systems.input = [];
   engineState.registry.systems.update = [];
   engineState.registry.systems.preRender = [];
@@ -60,9 +125,11 @@ export function initEngine(config: {
   // Register Core Systems
   registerSystem('input', CoreSystems.InputMirrorSystem);
   registerSystem('update', CoreSystems.CommandIntentSystem);
+  registerSystem('update', CoreSystems.UiBridgeSystem);
   registerSystem('update', CoreSystems.WorldLifecycleSystem);
   registerSystem('update', CoreSystems.ResourceUploadSystem);
-  registerSystem('preRender', CoreSystems.CoreCommandBuilderSystem);
+  registerSystem('preRender', CoreSystems.ConstraintSolveSystem);
+  registerSystem('preRender', CoreSystems.SceneSyncSystem);
   registerSystem('postRender', CoreSystems.ResponseDecodeSystem);
   registerSystem('postRender', CoreSystems.DiagnosticsSystem);
 }
@@ -80,7 +147,19 @@ export function disposeEngine(): void {
   engineState.transport = null;
   engineState.worlds.clear();
   engineState.commandBatch = [];
+  engineState.usedWindowIds.clear();
+  engineState.confirmedWindowIds.clear();
+  engineState.pendingWindowCreateByCommandId.clear();
+  engineState.pendingWindowCloseByCommandId.clear();
+  engineState.globalPendingCommands = [];
+  engineState.globalPendingCommandsHead = 0;
   engineState.commandTracker.clear();
+  engineState.globalCommandTracker.clear();
+  engineState.globalInboundResponses = [];
+  engineState.routingIndex.byWindowId.clear();
+  engineState.routingIndex.byRealmId.clear();
+  engineState.routingIndex.byTargetId.clear();
+  engineState.routingIndex.dirty = true;
   engineState.status = 'disposed';
 }
 
@@ -93,7 +172,13 @@ export function registerComponent(name: string, schema: ComponentSchema): void {
 }
 
 /**
- * Registers a system to run at a specific pipeline step.
+ * Registers a custom system into the engine pipeline.
+ *
+ * Stage semantics:
+ * - `input`: consume mirrored inbound events/state for the current frame.
+ * - `update`: mutate ECS state and emit intents.
+ * - `preRender`: resolve constraints and emit core commands.
+ * - `postRender`: consume command responses and diagnostics.
  */
 export function registerSystem(step: SystemStep, system: System): void {
   requireInitialized();
@@ -119,12 +204,6 @@ function uploadTypeToId(type: UploadType): number {
   }
 }
 
-/**
- * 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.).
  */
@@ -148,17 +227,41 @@ export function uploadBuffer(
   }
 }
 
-/**
- * Creates a world bound to a window ID. Returns the world ID.
- */
-export function createWorld(windowId: number): number {
+function createRealmWorld(kind: RealmKind, config: CreateWorldOptions = {}): WorldId {
   requireInitialized();
-  if (engineState.worlds.has(windowId)) {
-    throw new EngineError('WorldExists', `World ${windowId} already exists.`);
-  }
+
+  const worldId = engineState.nextWorldId++;
+  // Core compatibility: when at least one window exists, pick the lowest ID as host window
+  // if the caller did not provide an explicit surface. This keeps world API window-agnostic
+  // while satisfying render graph bootstrap paths that still rely on host-window mapping.
+  const inferredHostWindowId = findLowestConfirmedWindowId();
 
   const world: WorldState = {
-    windowId,
+    worldId,
+    realmKind: kind,
+    primaryWindowId: undefined,
+    boundWindowIds: new Set(),
+    targetLayerBindings: new Map(),
+    targetWindowBindings: new Map(),
+    coreRealmId: undefined,
+    realmCreateArgs: {
+      kind,
+      hostWindowId: inferredHostWindowId,
+      outputSurfaceId: config.outputSurfaceId,
+      importance: config.importance,
+      cachePolicy: config.cachePolicy,
+      flags: config.flags,
+    },
+    coreSurfaceId: undefined,
+    corePresentId: undefined,
+    resolvedEntityTransforms: new Map(),
+    constraintDirtyEntities: new Set(),
+    constraintScratchResolved: new Map(),
+    constraintScratchVisiting: new Set(),
+    constraintChangedEntities: new Set(),
+    constraintChildrenByParent: new Map(),
+    constraintParentByChild: new Map(),
+    sceneSyncMatrixScratch: new Map(),
     entities: new Set(),
     components: new Map(),
     nextCoreId: 100,
@@ -166,18 +269,72 @@ export function createWorld(windowId: number): number {
     pendingIntents: [],
     internalEvents: [],
     pendingCommands: [],
+    pendingCommandsHead: 0,
     inboundEvents: [],
     inboundResponses: [],
+    realmCreateRetryCount: 0,
+    nextRealmCreateRetryAtMs: 0,
   };
 
-  engineState.worlds.set(windowId, world);
-  return windowId;
+  engineState.worlds.set(worldId, world);
+  markRoutingIndexDirty();
+  world.pendingCommands.push({
+    id: engineState.nextCommandId++,
+    type: 'cmd-realm-create',
+    content: world.realmCreateArgs,
+  });
+  return asWorldId(worldId);
+}
+
+/**
+ * Creates a `three-d` realm world and queues `cmd-realm-create`.
+ *
+ * This function only allocates local runtime state and enqueues the create command.
+ * The core realm is resolved asynchronously after at least one `tick`.
+ *
+ * Preconditions:
+ * - `initEngine` must have been called.
+ *
+ * Side effects:
+ * - Allocates a new world ID.
+ * - Registers the world in engine state.
+ * - Enqueues `cmd-realm-create` for the new world.
+ *
+ * @param config Optional create options.
+ * @returns Numeric world ID associated with a core `three-d` realm.
+ */
+export function createWorld3D(config?: CreateWorldOptions): WorldId {
+  return createRealmWorld('three-d', config);
+}
+
+/**
+ * Creates a `two-d` realm world for UI-centric pipelines and queues `cmd-realm-create`.
+ *
+ * This world type is intended for the dedicated WorldUI functional APIs.
+ * The core realm is resolved asynchronously after at least one `tick`.
+ *
+ * Preconditions:
+ * - `initEngine` must have been called.
+ *
+ * Side effects:
+ * - Allocates a new world ID.
+ * - Registers the world in engine state.
+ * - Enqueues `cmd-realm-create` for the new world.
+ *
+ * @param config Optional create options.
+ * @returns Numeric world ID associated with a core `two-d` realm.
+ */
+export function createWorldUI(config?: CreateWorldOptions): WorldId {
+  return createRealmWorld('two-d', config);
 }
 
 /**
- * Main engine tick.
- * Orchestrates event routing, world updates, command collection, and core synchronization.
+ * Creates a default `three-d` world.
  */
+export function createWorld(config?: CreateWorldOptions): WorldId {
+  return createWorld3D(config);
+}
+
 /**
  * Advances the engine by one frame.
  * Call once per frame with monotonic time and delta in milliseconds.
@@ -185,6 +342,8 @@ export function createWorld(windowId: number): number {
 export function tick(timeMs: number, deltaMs: number): void {
   requireInitialized();
   const transport = engineState.transport!;
+  const coreTimeMs = Math.max(0, Math.floor(timeMs));
+  const coreDeltaMs = Math.max(0, Math.floor(deltaMs));
 
   // 1. Engine Phase: Receive from Core (Input Pipeline)
   // We process events and responses received since last frame
@@ -199,9 +358,10 @@ export function tick(timeMs: number, deltaMs: number): void {
     const responses = deserializeResponses(responsesResult.buffer);
     routeResponses(responses);
   }
+  processGlobalResponses();
 
   // 2. Engine Phase: Clock & Context Preparation
-  const cappedDelta = Math.min(deltaMs, 100);
+  const cappedDelta = Math.min(coreDeltaMs, 100);
   engineState.clock.lastTime = timeMs;
   engineState.clock.lastDelta = cappedDelta;
   engineState.clock.frameCount++;
@@ -238,6 +398,14 @@ export function tick(timeMs: number, deltaMs: number): void {
       );
       for (const cmd of engineState.commandBatch) {
         engineState.commandTracker.delete(cmd.id);
+        engineState.globalCommandTracker.delete(cmd.id);
+        const pendingCreateWindowId =
+          engineState.pendingWindowCreateByCommandId.get(cmd.id);
+        if (pendingCreateWindowId !== undefined) {
+          engineState.usedWindowIds.delete(pendingCreateWindowId);
+          engineState.pendingWindowCreateByCommandId.delete(cmd.id);
+        }
+        engineState.pendingWindowCloseByCommandId.delete(cmd.id);
       }
       if (engineState.flags.debugEnabled) {
         console.group('[Vulfram Debug] Failed Batch');
@@ -254,7 +422,50 @@ export function tick(timeMs: number, deltaMs: number): void {
   }
 
   // 5. Core Phase: Execute Tick
-  transport.vulframTick(timeMs, deltaMs);
+  transport.vulframTick(coreTimeMs, coreDeltaMs);
+}
+
+function processGlobalResponses(): void {
+  for (let i = 0; i < engineState.globalInboundResponses.length; i++) {
+    const res = engineState.globalInboundResponses[i]!;
+    const content = res.content as { success?: boolean; message?: string };
+    if (res.type === 'window-create') {
+      const pendingWindowId = engineState.pendingWindowCreateByCommandId.get(res.id);
+      if (pendingWindowId !== undefined) {
+        if (content.success) {
+          engineState.confirmedWindowIds.add(pendingWindowId);
+        } else {
+          engineState.usedWindowIds.delete(pendingWindowId);
+        }
+        engineState.pendingWindowCreateByCommandId.delete(res.id);
+      }
+    } else if (res.type === 'window-close') {
+      const pendingWindowId = engineState.pendingWindowCloseByCommandId.get(res.id);
+      if (pendingWindowId !== undefined) {
+        if (content.success) {
+          engineState.usedWindowIds.delete(pendingWindowId);
+          engineState.confirmedWindowIds.delete(pendingWindowId);
+          for (const world of engineState.worlds.values()) {
+            for (const [targetId, windowId] of world.targetWindowBindings) {
+              if (windowId === pendingWindowId) {
+                world.targetWindowBindings.delete(targetId);
+                world.targetLayerBindings.delete(targetId);
+              }
+            }
+            recalculateWorldWindowBindings(world);
+          }
+          markRoutingIndexDirty();
+        }
+        engineState.pendingWindowCloseByCommandId.delete(res.id);
+      }
+    }
+    if (content && typeof content.success === 'boolean' && !content.success) {
+      console.error(
+        `[Global] Command ${res.type} (ID: ${res.id}) failed: ${content.message}`,
+      );
+    }
+  }
+  engineState.globalInboundResponses.length = 0;
 }
 
 /**