@vulfram/engine 0.14.8-alpha → 0.19.2-alpha

package/src/engine/ecs/systems.ts

@@ -0,0 +1,26 @@
+import type { WorldState } from '../state';
+import type { ComponentSchema } from './components';
+
+/** Pipeline stage at which a system runs. */
+export type SystemStep = 'input' | 'update' | 'preRender' | 'postRender';
+
+/** System execution context provided each frame. */
+export interface SystemContext {
+  dt: number;
+  time: number;
+  worldId: number;
+}
+
+/** System function signature. */
+export type System = (state: WorldState, context: SystemContext) => void;
+
+/** Registry of components and systems. */
+export interface EngineRegistry {
+  components: Map<string, ComponentSchema>;
+  systems: {
+    input: System[];
+    update: System[];
+    preRender: System[];
+    postRender: System[];
+  };
+}

package/src/engine/intents/store.ts

@@ -0,0 +1,72 @@
+import type { Intent } from '../ecs';
+
+export type IntentType = Intent['type'];
+
+type IntentEntry<K extends IntentType> = {
+  seq: number;
+  intent: Extract<Intent, { type: K }>;
+};
+
+export class IntentStore {
+  private byType = new Map<IntentType, IntentEntry<IntentType>[]>();
+  private sequence = 0;
+  private total = 0;
+
+  enqueue(intent: Intent): void {
+    const key = intent.type as IntentType;
+    const list = this.byType.get(key);
+    const entry: IntentEntry<IntentType> = {
+      seq: this.sequence++,
+      intent: intent as Extract<Intent, { type: IntentType }>,
+    };
+    if (list) {
+      list.push(entry);
+    } else {
+      this.byType.set(key, [entry]);
+    }
+    this.total++;
+  }
+
+  take<K extends IntentType>(type: K): Extract<Intent, { type: K }>[] {
+    const list = this.byType.get(type);
+    if (!list || list.length === 0) {
+      return [];
+    }
+    this.byType.delete(type);
+    this.total -= list.length;
+    return list.map((entry) => entry.intent as Extract<Intent, { type: K }>);
+  }
+
+  takeMany<K extends IntentType>(
+    types: readonly K[],
+  ): Extract<Intent, { type: K }>[] {
+    const merged: IntentEntry<K>[] = [];
+    for (let i = 0; i < types.length; i++) {
+      const type = types[i];
+      if (type === undefined) continue;
+      const list = this.byType.get(type);
+      if (!list || list.length === 0) continue;
+      this.byType.delete(type);
+      this.total -= list.length;
+      for (let j = 0; j < list.length; j++) {
+        const entry = list[j];
+        if (entry) merged.push(entry as unknown as IntentEntry<K>);
+      }
+    }
+    merged.sort((a, b) => a.seq - b.seq);
+    return merged.map((entry) => entry.intent as Extract<Intent, { type: K }>);
+  }
+
+  size(): number {
+    return this.total;
+  }
+
+  clear(): void {
+    this.byType.clear();
+    this.total = 0;
+  }
+}
+
+export function createIntentStore(): IntentStore {
+  return new IntentStore();
+}

package/src/engine/state.ts

@@ -1,13 +1,14 @@
 import type { EngineTransport } from '@vulfram/transport-types';
 import type { CommandResponseEnvelope, EngineCmdEnvelope } from '../types/cmds';
 import type { EngineEvent } from '../types/events';
+import type { CmdRealmCreateArgs, RealmKind } from '../types/cmds/realm';
 import type {
   Component,
   ComponentType,
   EngineRegistry,
-  Intent,
   WorldEvent,
 } from './ecs';
+import type { IntentStore } from './intents/store';
 
 type EngineStatus = 'uninitialized' | 'initialized' | 'disposed';
 
@@ -28,8 +29,78 @@ type ResourceIdCounters = {
   texture: number;
 };
 
+export type RoutingIndex = {
+  dirty: boolean;
+  byWindowId: Map<number, number[]>;
+  byRealmId: Map<number, number[]>;
+  byTargetId: Map<number, number[]>;
+};
+
 export type WorldState = {
-  windowId: number;
+  worldId: number;
+  /**
+   * Realm kind for this world.
+   * `three-d` realms are used by World3D APIs and `two-d` realms by WorldUI APIs.
+   */
+  realmKind: RealmKind;
+  primaryWindowId?: number;
+  boundWindowIds: Set<number>;
+  /**
+   * Latest target-layer binding args keyed by targetId.
+   * Used to keep realm->target binds coherent when cameras are created later.
+   */
+  targetLayerBindings: Map<
+    number,
+    {
+      targetId: number;
+      layout: import('../types/cmds/target').TargetLayerLayout;
+      cameraId?: number;
+      environmentId?: number;
+    }
+  >;
+  /**
+   * Window target ownership keyed by targetId.
+   * Tracks which window a target is currently presenting into for routing purposes.
+   */
+  targetWindowBindings: Map<number, number>;
+  coreRealmId?: number;
+  realmCreateRetryCount: number;
+  nextRealmCreateRetryAtMs: number;
+  realmCreateArgs: CmdRealmCreateArgs;
+  coreSurfaceId?: number;
+  corePresentId?: number;
+  /**
+   * Constraint-solved world matrices keyed by entity id.
+   */
+  resolvedEntityTransforms: Map<number, Float32Array>;
+  /**
+   * Entities explicitly marked as dirty for constraint recomputation.
+   */
+  constraintDirtyEntities: Set<number>;
+  /**
+   * Scratch cache for per-tick constraint solve graph resolution.
+   */
+  constraintScratchResolved: Map<number, Float32Array>;
+  /**
+   * Scratch set used while resolving hierarchy recursion (cycle detection).
+   */
+  constraintScratchVisiting: Set<number>;
+  /**
+   * Entities with resolved matrix changes in the current tick.
+   */
+  constraintChangedEntities: Set<number>;
+  /**
+   * Parent -> children relationship index for hierarchy propagation.
+   */
+  constraintChildrenByParent: Map<number, Set<number>>;
+  /**
+   * Child -> parent relationship index for fast reparent operations.
+   */
+  constraintParentByChild: Map<number, number>;
+  /**
+   * Reusable scratch arrays used when syncing matrices to core.
+   */
+  sceneSyncMatrixScratch: Map<number, number[]>;
   entities: Set<number>;
   /**
    * Components stored by entityId -> componentType -> ComponentData
@@ -38,9 +109,9 @@ export type WorldState = {
   nextCoreId: number;
   systems: string[];
   /**
-   * Pending intents to be processed by systems in the next tick.
+   * Indexed intent store to query/consume by type with stable insertion order.
    */
-  pendingIntents: Intent[];
+  intentStore: IntentStore;
   /**
    * Internal world events for system-to-system communication.
    */
@@ -50,6 +121,7 @@ export type WorldState = {
    * Will be moved to the engine's global batch during the tick.
    */
   pendingCommands: EngineCmdEnvelope[];
+  pendingCommandsHead: number;
   /**
    * Events routed to this world in the current frame.
    */
@@ -64,17 +136,57 @@ export type EngineState = {
   status: EngineStatus;
   transport: EngineTransport | null;
   worlds: Map<number, WorldState>;
+  nextWorldId: number;
+  nextWindowId: number;
   nextEntityId: number;
   nextCommandId: number;
+  /**
+   * Global ID allocator for core-global resources/objects.
+   * Use for IDs that are not realm-scoped (material/geometry/texture/target/...).
+   */
+  nextGlobalId: number;
   /**
    * Global command batch for the current frame.
    */
   commandBatch: EngineCmdEnvelope[];
+  /**
+   * Tracks reserved window IDs to avoid logical ID collisions for host windows.
+   */
+  usedWindowIds: Set<number>;
+  /**
+   * Pending global commands not scoped to any specific world.
+   */
+  globalPendingCommands: EngineCmdEnvelope[];
+  globalPendingCommandsHead: number;
+  /**
+   * Window IDs confirmed by core `window-create` responses.
+   */
+  confirmedWindowIds: Set<number>;
+  /**
+   * Maps pending window-create command ids to requested window ids.
+   */
+  pendingWindowCreateByCommandId: Map<number, number>;
+  /**
+   * Maps pending window-close command ids to target window ids.
+   */
+  pendingWindowCloseByCommandId: Map<number, number>;
   /**
    * Maps command IDs to the world ID that created them.
    * This is used to route responses back to the correct world.
    */
   commandTracker: Map<number, number>;
+  /**
+   * Tracks global commands (not world-scoped) so their responses are not lost.
+   */
+  globalCommandTracker: Set<number>;
+  /**
+   * Buffered responses for global commands.
+   */
+  globalInboundResponses: CommandResponseEnvelope[];
+  /**
+   * Cached world routing index for event fanout.
+   */
+  routingIndex: RoutingIndex;
   /**
    * Registry for custom components and systems.
    */
@@ -99,8 +211,10 @@ export type EngineState = {
 export const REQUIRED_SYSTEMS = [
   'InputMirrorSystem',
   'CommandIntentSystem',
+  'UiBridgeSystem',
   'ResourceUploadSystem',
-  'CoreCommandBuilderSystem',
+  'ConstraintSolveSystem',
+  'SceneSyncSystem',
   'ResponseDecodeSystem',
   'WorldLifecycleSystem',
   'DiagnosticsSystem',
@@ -110,10 +224,27 @@ export const engineState: EngineState = {
   status: 'uninitialized',
   transport: null,
   worlds: new Map(),
+  nextWorldId: 1,
+  nextWindowId: 1,
   nextEntityId: 1,
   nextCommandId: 1,
+  nextGlobalId: 100,
   commandBatch: [],
+  usedWindowIds: new Set(),
+  globalPendingCommands: [],
+  globalPendingCommandsHead: 0,
+  confirmedWindowIds: new Set(),
+  pendingWindowCreateByCommandId: new Map(),
+  pendingWindowCloseByCommandId: new Map(),
   commandTracker: new Map(),
+  globalCommandTracker: new Set(),
+  globalInboundResponses: [],
+  routingIndex: {
+    dirty: true,
+    byWindowId: new Map(),
+    byRealmId: new Map(),
+    byTargetId: new Map(),
+  },
   registry: {
     components: new Map(),
     systems: {

package/src/engine/systems/command-intent.ts

@@ -5,15 +5,54 @@ import type {
   LightComponent,
   ModelComponent,
   System,
+  TransformComponent,
 } from '../ecs';
+import { toQuat, toVec3 } from './utils';
 
+const COMMAND_INTENT_TYPES = [
+  'create-entity',
+  'attach-tag',
+  'set-parent',
+  'update-transform',
+  'remove-entity',
+] as const;
+
+function wouldCreateParentCycle(
+  world: Parameters<System>[0],
+  childEntityId: number,
+  parentEntityId: number,
+): boolean {
+  let cursor: number | null = parentEntityId;
+  const visited = new Set<number>();
+
+  while (cursor !== null) {
+    if (cursor === childEntityId) {
+      return true;
+    }
+    if (visited.has(cursor)) {
+      return true;
+    }
+    visited.add(cursor);
+
+    const store = world.components.get(cursor);
+    const parent = store?.get('Parent') as { parentId: number } | undefined;
+    cursor = parent?.parentId ?? null;
+  }
+
+  return false;
+}
+
+/**
+ * Applies structural ECS intents that must mutate local world state before
+ * render-time command synthesis (entity lifecycle, tags, parent links, transforms).
+ */
 export const CommandIntentSystem: System = (world, context) => {
-  const intentsToRemove: number[] = [];
+  const realmId = world.coreRealmId;
+  const intents = world.intentStore.takeMany(COMMAND_INTENT_TYPES);
 
-  for (let i = 0; i < world.pendingIntents.length; i++) {
-    const intent = world.pendingIntents[i];
+  for (let i = 0; i < intents.length; i++) {
+    const intent = intents[i];
     if (!intent) continue;
-
     if (intent.type === 'create-entity') {
       world.entities.add(intent.entityId);
       // Initialize default transform
@@ -32,8 +71,117 @@ export const CommandIntentSystem: System = (world, context) => {
           visible: true,
         });
       }
-      intentsToRemove.push(i);
+      world.constraintDirtyEntities.add(intent.entityId);
+    } else if (intent.type === 'attach-tag') {
+      let store = world.components.get(intent.entityId);
+      if (!store) {
+        store = new Map();
+        world.components.set(intent.entityId, store);
+      }
+      store.set('Tag', {
+        type: 'Tag',
+        name: intent.props.name ?? '',
+        labels: new Set(intent.props.labels ?? []),
+      });
+    } else if (intent.type === 'set-parent') {
+      let store = world.components.get(intent.entityId);
+      if (!store) {
+        store = new Map();
+        world.components.set(intent.entityId, store);
+      }
+      if (intent.parentId === null) {
+        const oldParentId = world.constraintParentByChild.get(intent.entityId);
+        if (oldParentId !== undefined) {
+          const siblings = world.constraintChildrenByParent.get(oldParentId);
+          siblings?.delete(intent.entityId);
+          if (siblings && siblings.size === 0) {
+            world.constraintChildrenByParent.delete(oldParentId);
+          }
+          world.constraintParentByChild.delete(intent.entityId);
+        }
+        store.delete('Parent');
+      } else {
+        if (intent.parentId === intent.entityId) {
+          console.error(
+            `[World ${context.worldId}] Invalid parent constraint: entity ${intent.entityId} cannot parent itself.`,
+          );
+          continue;
+        }
+        if (wouldCreateParentCycle(world, intent.entityId, intent.parentId)) {
+          console.error(
+            `[World ${context.worldId}] Invalid parent constraint: cycle detected for child ${intent.entityId} and parent ${intent.parentId}.`,
+          );
+          continue;
+        }
+        store.set('Parent', {
+          type: 'Parent',
+          parentId: intent.parentId,
+        });
+
+        const oldParentId = world.constraintParentByChild.get(intent.entityId);
+        if (oldParentId !== undefined && oldParentId !== intent.parentId) {
+          const siblings = world.constraintChildrenByParent.get(oldParentId);
+          siblings?.delete(intent.entityId);
+          if (siblings && siblings.size === 0) {
+            world.constraintChildrenByParent.delete(oldParentId);
+          }
+        }
+        world.constraintParentByChild.set(intent.entityId, intent.parentId);
+        let children = world.constraintChildrenByParent.get(intent.parentId);
+        if (!children) {
+          children = new Set();
+          world.constraintChildrenByParent.set(intent.parentId, children);
+        }
+        children.add(intent.entityId);
+      }
+      world.constraintDirtyEntities.add(intent.entityId);
+    } else if (intent.type === 'update-transform') {
+      const store = world.components.get(intent.entityId);
+      if (!store) {
+        continue;
+      }
+      const transform = store.get('Transform') as TransformComponent | undefined;
+      if (!transform) {
+        continue;
+      }
+
+      const nextProps = { ...intent.props };
+      if (nextProps.position) {
+        nextProps.position = toVec3(nextProps.position);
+      }
+      if (nextProps.rotation) {
+        nextProps.rotation = toQuat(nextProps.rotation);
+      }
+      if (nextProps.scale) {
+        nextProps.scale = toVec3(nextProps.scale);
+      }
+      Object.assign(transform, nextProps);
+      world.constraintDirtyEntities.add(intent.entityId);
     } else if (intent.type === 'remove-entity') {
+      if (realmId === undefined) continue;
+
+      // Detach all children linked to this entity to keep hierarchy state coherent.
+      const children = world.constraintChildrenByParent.get(intent.entityId);
+      if (children) {
+        for (const childId of children) {
+          const childStore = world.components.get(childId);
+          childStore?.delete('Parent');
+          world.constraintParentByChild.delete(childId);
+          world.constraintDirtyEntities.add(childId);
+        }
+        world.constraintChildrenByParent.delete(intent.entityId);
+      }
+
+      const parentId = world.constraintParentByChild.get(intent.entityId);
+      if (parentId !== undefined) {
+        const siblings = world.constraintChildrenByParent.get(parentId);
+        siblings?.delete(intent.entityId);
+        if (siblings && siblings.size === 0) {
+          world.constraintChildrenByParent.delete(parentId);
+        }
+        world.constraintParentByChild.delete(intent.entityId);
+      }
+
       const store = world.components.get(intent.entityId);
       if (store) {
         // Emit disposal commands for all components with IDs
@@ -42,19 +190,19 @@ export const CommandIntentSystem: System = (world, context) => {
             if (type === 'Model') {
               const modelComp = comp as ModelComponent;
               enqueueCommand(context.worldId, 'cmd-model-dispose', {
-                windowId: context.worldId,
+                realmId,
                 modelId: modelComp.id,
               });
             } else if (type === 'Camera') {
               const cameraComp = comp as CameraComponent;
               enqueueCommand(context.worldId, 'cmd-camera-dispose', {
-                windowId: context.worldId,
+                realmId,
                 cameraId: cameraComp.id,
               });
             } else if (type === 'Light') {
               const lightComp = comp as LightComponent;
               enqueueCommand(context.worldId, 'cmd-light-dispose', {
-                windowId: context.worldId,
+                realmId,
                 lightId: lightComp.id,
               });
             }
@@ -63,12 +211,9 @@ export const CommandIntentSystem: System = (world, context) => {
         world.components.delete(intent.entityId);
       }
       world.entities.delete(intent.entityId);
-      intentsToRemove.push(i);
+      world.resolvedEntityTransforms.delete(intent.entityId);
+      world.sceneSyncMatrixScratch.delete(intent.entityId);
+      world.constraintDirtyEntities.add(intent.entityId);
     }
   }
-
-  for (let i = intentsToRemove.length - 1; i >= 0; i--) {
-    const idx = intentsToRemove[i];
-    if (idx !== undefined) world.pendingIntents.splice(idx, 1);
-  }
 };

package/src/engine/systems/constraint-solve.ts

@@ -0,0 +1,167 @@
+import { mat4 } from 'gl-matrix';
+import type { ParentComponent, System, TransformComponent } from '../ecs';
+import { mat4EqualsApprox, getEntityLocalTransformMatrix } from './utils';
+
+type ConstraintStrategyContext = {
+  worldId: number;
+  entityId: number;
+};
+
+interface ConstraintStrategy {
+  name: string;
+  apply(a: mat4, b: mat4, context: ConstraintStrategyContext): mat4;
+}
+
+const ParentConstraintStrategy: ConstraintStrategy = {
+  name: 'parent',
+  apply(a, b) {
+    const out = mat4.create();
+    mat4.multiply(out, a, b);
+    return out;
+  },
+};
+
+type ResolveState = {
+  worldId: number;
+  world: Parameters<System>[0];
+  affected: Set<number>;
+  resolved: Map<number, mat4>;
+  visiting: Set<number>;
+  cycleLogged: boolean;
+};
+
+function resolveEntityMatrix(state: ResolveState, entityId: number): mat4 {
+  if (!state.affected.has(entityId)) {
+    const existing = state.world.resolvedEntityTransforms.get(entityId);
+    if (existing) {
+      return existing as unknown as mat4;
+    }
+  }
+
+  const cached = state.resolved.get(entityId);
+  if (cached) {
+    return cached;
+  }
+
+  if (state.visiting.has(entityId)) {
+    if (!state.cycleLogged) {
+      console.error(
+        `[World ${state.worldId}] Constraint cycle detected in parent hierarchy. Falling back to local transforms for cyclic nodes.`,
+      );
+      state.cycleLogged = true;
+    }
+    return getEntityLocalTransformMatrix(state.world, entityId);
+  }
+
+  state.visiting.add(entityId);
+  const local = getEntityLocalTransformMatrix(state.world, entityId);
+  const store = state.world.components.get(entityId);
+  const parent = store?.get('Parent') as ParentComponent | undefined;
+
+  let resolved = local;
+  if (parent) {
+    const parentStore = state.world.components.get(parent.parentId);
+    const parentTransform = parentStore?.get('Transform') as
+      | TransformComponent
+      | undefined;
+    if (parentTransform) {
+      const parentMatrix = resolveEntityMatrix(state, parent.parentId);
+      resolved = ParentConstraintStrategy.apply(parentMatrix, local, {
+        worldId: state.worldId,
+        entityId,
+      });
+    }
+  }
+
+  state.visiting.delete(entityId);
+  state.resolved.set(entityId, resolved);
+  return resolved;
+}
+
+function collectAffectedEntities(world: Parameters<System>[0]): Set<number> {
+  const affected = new Set<number>();
+  const queue: number[] = [];
+
+  for (const entityId of world.constraintDirtyEntities) {
+    affected.add(entityId);
+    queue.push(entityId);
+  }
+
+  for (let i = 0; i < queue.length; i++) {
+    const parentId = queue[i]!;
+    const children = world.constraintChildrenByParent.get(parentId);
+    if (!children) continue;
+    for (const childId of children) {
+      if (affected.has(childId)) continue;
+      affected.add(childId);
+      queue.push(childId);
+    }
+  }
+
+  return affected;
+}
+
+/**
+ * Resolves transform constraints into world matrices.
+ *
+ * Current built-in strategy:
+ * - `parent`: composes parent world matrix with child local matrix (`A * B`).
+ *
+ * The solver walks dependencies from higher nodes to leaves and caches each
+ * resolved entity matrix so render sync can emit final transforms to core.
+ */
+export const ConstraintSolveSystem: System = (world, context) => {
+  if (world.constraintDirtyEntities.size === 0) {
+    world.constraintChangedEntities.clear();
+    return;
+  }
+
+  const matrices = world.resolvedEntityTransforms;
+  const changed = world.constraintChangedEntities;
+  changed.clear();
+  const affected = collectAffectedEntities(world);
+
+  const resolveState: ResolveState = {
+    worldId: context.worldId,
+    world,
+    affected,
+    resolved: world.constraintScratchResolved,
+    visiting: world.constraintScratchVisiting,
+    cycleLogged: false,
+  };
+  resolveState.resolved.clear();
+  resolveState.visiting.clear();
+
+  for (const entityId of affected) {
+    if (!world.entities.has(entityId)) {
+      if (matrices.delete(entityId)) {
+        changed.add(entityId);
+      }
+      continue;
+    }
+
+    const store = world.components.get(entityId);
+    const transform = store?.get('Transform') as TransformComponent | undefined;
+    if (!transform) {
+      if (matrices.delete(entityId)) {
+        changed.add(entityId);
+      }
+      continue;
+    }
+
+    const resolved = resolveEntityMatrix(resolveState, entityId);
+    const previousSnapshot = matrices.get(entityId);
+    if (!previousSnapshot) {
+      matrices.set(entityId, new Float32Array(resolved));
+      changed.add(entityId);
+      continue;
+    }
+
+    if (!mat4EqualsApprox(previousSnapshot, resolved)) {
+      previousSnapshot.set(resolved);
+      changed.add(entityId);
+    }
+  }
+
+  world.constraintDirtyEntities.clear();
+};