@vulfram/engine 0.14.8-alpha → 0.17.1-alpha

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();
+};

package/src/engine/systems/core-command-builder.ts

@@ -1,268 +1,9 @@
-import { mat4, vec3 } from 'gl-matrix';
-import type { CameraKind, LightKind } from '../../types/kinds';
-import { enqueueCommand } from '../bridge/dispatch';
-import type {
-  CameraComponent,
-  Component,
-  LightComponent,
-  ModelComponent,
-  System,
-  TransformComponent,
-} from '../ecs';
-import { getEntityTransformMatrix, toQuat, toVec2, toVec3, toVec4 } from './utils';
-
-export const CoreCommandBuilderSystem: System = (world, context) => {
-  const intentsToRemove: number[] = [];
-
-  for (let i = 0; i < world.pendingIntents.length; i++) {
-    const intent = world.pendingIntents[i];
-    if (!intent) continue;
-
-    if (intent.type === 'attach-model') {
-      const modelId = world.nextCoreId++;
-      const transform = getEntityTransformMatrix(world, intent.entityId);
-      const castShadow = intent.props.castShadow ?? true;
-      const receiveShadow = intent.props.receiveShadow ?? true;
-      const castOutline = intent.props.castOutline ?? false;
-      const outlineColor = intent.props.outlineColor ?? ([0, 0, 0, 0] as const);
-
-      enqueueCommand(context.worldId, 'cmd-model-create', {
-        windowId: context.worldId,
-        modelId,
-        geometryId: intent.props.geometryId,
-        materialId: intent.props.materialId,
-        transform: Array.from(transform),
-        layerMask: 0x7fffffff,
-        castShadow,
-        receiveShadow,
-        castOutline,
-        outlineColor: [...outlineColor] as [number, number, number, number],
-      });
-
-      let store = world.components.get(intent.entityId);
-      if (!store) {
-        store = new Map();
-        world.components.set(intent.entityId, store);
-      }
-      store.set('Model', {
-        type: 'Model',
-        id: modelId,
-        geometryId: intent.props.geometryId,
-        materialId: intent.props.materialId,
-        castShadow: intent.props.castShadow ?? true,
-        receiveShadow: intent.props.receiveShadow ?? true,
-        castOutline,
-        outlineColor: [...outlineColor] as [number, number, number, number],
-        skipUpdate: true,
-      });
-
-      intentsToRemove.push(i);
-    } else if (intent.type === 'attach-camera') {
-      const cameraId = world.nextCoreId++;
-      const transform = getEntityTransformMatrix(world, intent.entityId);
-
-      enqueueCommand(context.worldId, 'cmd-camera-create', {
-        cameraId,
-        label: `Cam ${cameraId}`,
-        kind: intent.props.kind ?? ('perspective' as CameraKind),
-        flags: 0,
-        nearFar: [intent.props.near ?? 0.1, intent.props.far ?? 1000],
-        order: intent.props.order ?? 0,
-        transform: Array.from(transform),
-        layerMask: 0x7fffffff,
-        orthoScale: 1.0,
-      });
-
-      let store = world.components.get(intent.entityId);
-      if (!store) {
-        store = new Map();
-        world.components.set(intent.entityId, store);
-      }
-      store.set('Camera', {
-        type: 'Camera',
-        id: cameraId,
-        kind: intent.props.kind ?? ('perspective' as CameraKind),
-        near: intent.props.near ?? 0.1,
-        far: intent.props.far ?? 1000,
-        order: intent.props.order ?? 0,
-        orthoScale: 1.0,
-        skipUpdate: true,
-      });
-
-      intentsToRemove.push(i);
-    } else if (intent.type === 'attach-light') {
-      const lightId = world.nextCoreId++;
-      const transform = getEntityTransformMatrix(world, intent.entityId);
-
-      const pos = vec3.create();
-      mat4.getTranslation(pos, transform);
-      const direction = intent.props.direction
-        ? toVec3(intent.props.direction)
-        : ([0, 0, -1] as [number, number, number]);
-      const color = intent.props.color
-        ? toVec3(intent.props.color)
-        : ([1, 1, 1] as [number, number, number]);
-
-      const lightCmd: {
-        windowId: number;
-        lightId: number;
-        kind: LightKind;
-        color: [number, number, number, number];
-        intensity: number;
-        range: number;
-        castShadow: boolean;
-        position: [number, number, number, number];
-        layerMask: number;
-        direction?: [number, number, number, number];
-        spotInnerOuter?: [number, number];
-      } = {
-        windowId: context.worldId,
-        lightId,
-        kind: intent.props.kind ?? ('directional' as LightKind),
-        color: [...color, 1] as [number, number, number, number],
-        intensity: intent.props.intensity ?? 1.0,
-        range: intent.props.range ?? 10.0,
-        castShadow: intent.props.castShadow ?? true,
-        position: [pos[0], pos[1], pos[2], 1],
-        layerMask: 0x7fffffff,
-      };
-      if (direction) {
-        const [dirX, dirY, dirZ] = direction;
-        lightCmd.direction = [dirX, dirY, dirZ, 0];
-      }
-      if (intent.props.spotInnerOuter) {
-        lightCmd.spotInnerOuter = toVec2(intent.props.spotInnerOuter);
-      }
-      enqueueCommand(context.worldId, 'cmd-light-create', lightCmd);
-
-      let store = world.components.get(intent.entityId);
-      if (!store) {
-        store = new Map();
-        world.components.set(intent.entityId, store);
-      }
-      store.set('Light', {
-        type: 'Light',
-        id: lightId,
-        kind: intent.props.kind ?? ('directional' as LightKind),
-        color,
-        intensity: intent.props.intensity ?? 1.0,
-        range: intent.props.range ?? 10.0,
-        castShadow: intent.props.castShadow ?? true,
-        direction,
-        spotInnerOuter: intent.props.spotInnerOuter
-          ? toVec2(intent.props.spotInnerOuter)
-          : [0.2, 0.6],
-        skipUpdate: true,
-      });
-
-      intentsToRemove.push(i);
-    } else if (intent.type === 'update-transform') {
-      const store = world.components.get(intent.entityId);
-      if (store) {
-        const transform = store.get('Transform') as
-          | TransformComponent
-          | undefined;
-        if (transform) {
-          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);
-          const matrix = getEntityTransformMatrix(world, intent.entityId);
-          const matrixArray = Array.from(matrix);
-
-          const model = store.get('Model') as ModelComponent | undefined;
-          if (model) {
-            if (model.skipUpdate) {
-              model.skipUpdate = false;
-            } else {
-              enqueueCommand(context.worldId, 'cmd-model-update', {
-                windowId: context.worldId,
-                modelId: model.id,
-                transform: matrixArray,
-              });
-            }
-          }
-          const camera = store.get('Camera') as CameraComponent | undefined;
-          if (camera) {
-            if (camera.skipUpdate) {
-              camera.skipUpdate = false;
-            } else {
-              enqueueCommand(context.worldId, 'cmd-camera-update', {
-                cameraId: camera.id,
-                transform: matrixArray,
-              });
-            }
-          }
-          const light = store.get('Light') as LightComponent | undefined;
-          if (light) {
-            if (light.skipUpdate) {
-              light.skipUpdate = false;
-            } else {
-              const pos = vec3.create();
-              mat4.getTranslation(pos, matrix);
-              enqueueCommand(context.worldId, 'cmd-light-update', {
-                windowId: context.worldId,
-                lightId: light.id,
-                position: [pos[0], pos[1], pos[2], 1],
-              });
-            }
-          }
-        }
-      }
-      intentsToRemove.push(i);
-    } else if (intent.type === 'detach-component') {
-      const store = world.components.get(intent.entityId);
-      if (store) {
-        const comp = store.get(intent.componentType) as Component | undefined;
-        if (comp && 'id' in comp) {
-          if (intent.componentType === 'Model') {
-            const modelComp = comp as ModelComponent;
-            enqueueCommand(context.worldId, 'cmd-model-dispose', {
-              windowId: context.worldId,
-              modelId: modelComp.id,
-            });
-          } else if (intent.componentType === 'Camera') {
-            const cameraComp = comp as CameraComponent;
-            enqueueCommand(context.worldId, 'cmd-camera-dispose', {
-              cameraId: cameraComp.id,
-            });
-          } else if (intent.componentType === 'Light') {
-            const lightComp = comp as LightComponent;
-            enqueueCommand(context.worldId, 'cmd-light-dispose', {
-              windowId: context.worldId,
-              lightId: lightComp.id,
-            });
-          }
-        }
-        store.delete(intent.componentType);
-      }
-      intentsToRemove.push(i);
-    } else if (intent.type === 'gizmo-draw-line') {
-      enqueueCommand(context.worldId, 'cmd-gizmo-draw-line', {
-        start: toVec3(intent.start),
-        end: toVec3(intent.end),
-        color: toVec4(intent.color),
-      });
-      intentsToRemove.push(i);
-    } else if (intent.type === 'gizmo-draw-aabb') {
-      enqueueCommand(context.worldId, 'cmd-gizmo-draw-aabb', {
-        min: toVec3(intent.min),
-        max: toVec3(intent.max),
-        color: toVec4(intent.color),
-      });
-      intentsToRemove.push(i);
-    }
-  }
-
-  for (let i = intentsToRemove.length - 1; i >= 0; i--) {
-    const idx = intentsToRemove[i];
-    if (idx !== undefined) world.pendingIntents.splice(idx, 1);
-  }
-};
+/**
+ * Backward-compatible module shim.
+ *
+ * The canonical implementation now lives in `scene-sync.ts`.
+ */
+export {
+  CoreCommandBuilderSystem,
+  SceneSyncSystem,
+} from './scene-sync';

package/src/engine/systems/diagnostics.ts

@@ -2,16 +2,35 @@ import type { EngineCmd } from '../../types/cmds';
 import { enqueueCommand } from '../bridge/dispatch';
 import type { System } from '../ecs';
 
+/**
+ * Handles diagnostic intents that query core-side resource lists.
+ *
+ * This system is intentionally narrow: it transforms
+ * `request-resource-list` intents into typed `cmd-*-list` commands.
+ */
 export const DiagnosticsSystem: System = (world, context) => {
   const intentsToRemove: number[] = [];
 
   for (let i = 0; i < world.pendingIntents.length; i++) {
     const intent = world.pendingIntents[i];
     if (intent?.type === 'request-resource-list') {
+      let windowId = world.primaryWindowId;
+      if (windowId === undefined) {
+        for (const boundWindowId of world.targetWindowBindings.values()) {
+          windowId = boundWindowId;
+          break;
+        }
+      }
+      if (windowId === undefined) {
+        windowId = world.realmCreateArgs.hostWindowId;
+      }
+      if (windowId === undefined) {
+        continue;
+      }
       const type = intent.resourceType;
       const cmdType = `cmd-${type}-list` as EngineCmd['type'];
       enqueueCommand(context.worldId, cmdType, {
-        windowId: context.worldId,
+        windowId,
       });
       intentsToRemove.push(i);
     }
@@ -21,22 +40,4 @@ export const DiagnosticsSystem: System = (world, context) => {
     const idx = intentsToRemove[i];
     if (idx !== undefined) world.pendingIntents.splice(idx, 1);
   }
-
-  // Simple diagnostic log every 600 frames
-  if (world.entities.size > 0 && world.nextCoreId > 2) {
-    // We only log if there is something interesting
-    const globalCounters = globalThis as unknown as Record<string, number>;
-    const frame = globalCounters.vulframFrameCount || 0;
-    globalCounters.vulframFrameCount = frame + 1;
-
-    if (frame % 600 === 0) {
-      console.debug(
-        `[Diagnostics] World ${context.worldId} | Entities: ${
-          world.entities.size
-        } | Intents: ${world.pendingIntents.length} | Core objects: ${
-          world.nextCoreId - 2
-        }`,
-      );
-    }
-  }
 };

package/src/engine/systems/index.ts

@@ -1,7 +1,9 @@
 export { InputMirrorSystem } from './input-mirror';
 export { CommandIntentSystem } from './command-intent';
-export { CoreCommandBuilderSystem } from './core-command-builder';
+export { ConstraintSolveSystem } from './constraint-solve';
+export { SceneSyncSystem, CoreCommandBuilderSystem } from './scene-sync';
 export { ResourceUploadSystem } from './resource-upload';
+export { UiBridgeSystem } from './ui-bridge';
 export { ResponseDecodeSystem } from './response-decode';
 export { WorldLifecycleSystem } from './world-lifecycle';
 export { DiagnosticsSystem } from './diagnostics';

package/src/engine/systems/input-mirror.ts

@@ -1,19 +1,31 @@
 import type { KeyboardEvent } from '../../types/events/keyboard';
 import type { PointerEvent } from '../../types/events/pointer';
+import type { GamepadEvent } from '../../types/events/gamepad';
+import type { SystemEvent } from '../../types/events/system';
+import type { UiEvent } from '../../types/events/ui';
 import type { WindowEvent } from '../../types/events/window';
 import type {
+  GamepadStateComponent,
   InputStateComponent,
+  SystemEventStateComponent,
   System,
+  UiEventStateComponent,
   WindowStateComponent,
 } from '../ecs';
 
 /**
- * InputMirrorSystem: Processes input events and updates InputState component
+ * Mirrors inbound core events into world-level ECS state components.
+ *
+ * This system owns runtime input snapshots for keyboard, pointer, window,
+ * gamepad, system, and UI event streams.
  */
 export const InputMirrorSystem: System = (world) => {
   // Ensure InputState component exists for the world
   let inputState: InputStateComponent | undefined;
   let windowState: WindowStateComponent | undefined;
+  let gamepadState: GamepadStateComponent | undefined;
+  let systemEventState: SystemEventStateComponent | undefined;
+  let uiEventState: UiEventStateComponent | undefined;
 
   // Find or create InputState (attached to a special entity ID 0)
   const WORLD_ENTITY_ID = 0;
@@ -57,6 +69,38 @@ export const InputMirrorSystem: System = (world) => {
     worldStore.set('WindowState', windowState);
   }
 
+  gamepadState = worldStore.get('GamepadState') as GamepadStateComponent;
+  if (!gamepadState) {
+    gamepadState = {
+      type: 'GamepadState',
+      connected: new Map(),
+      buttons: new Map(),
+      axes: new Map(),
+      eventsThisFrame: [],
+    };
+    worldStore.set('GamepadState', gamepadState);
+  }
+
+  systemEventState = worldStore.get(
+    'SystemEventState',
+  ) as SystemEventStateComponent;
+  if (!systemEventState) {
+    systemEventState = {
+      type: 'SystemEventState',
+      eventsThisFrame: [],
+    };
+    worldStore.set('SystemEventState', systemEventState);
+  }
+
+  uiEventState = worldStore.get('UiEventState') as UiEventStateComponent;
+  if (!uiEventState) {
+    uiEventState = {
+      type: 'UiEventState',
+      eventsThisFrame: [],
+    };
+    worldStore.set('UiEventState', uiEventState);
+  }
+
   // Clear "just pressed/released" from previous frame
   inputState.keysJustPressed.clear();
   inputState.keysJustReleased.clear();
@@ -68,10 +112,13 @@ export const InputMirrorSystem: System = (world) => {
   windowState.movedThisFrame = false;
   windowState.focusChangedThisFrame = false;
   windowState.closeRequested = false;
+  gamepadState.eventsThisFrame.length = 0;
+  systemEventState.eventsThisFrame.length = 0;
+  uiEventState.eventsThisFrame.length = 0;
 
   // Process inbound events
-  while (world.inboundEvents.length > 0) {
-    const event = world.inboundEvents.shift();
+  for (let i = 0; i < world.inboundEvents.length; i++) {
+    const event = world.inboundEvents[i];
     if (!event) continue;
 
     // Keyboard events
@@ -148,5 +195,56 @@ export const InputMirrorSystem: System = (world) => {
         windowState.scaleFactor = winEvent.data.scaleFactor;
       }
     }
+    // Gamepad events
+    else if (event.type === 'gamepad') {
+      const gpEvent = event.content as GamepadEvent;
+      gamepadState.eventsThisFrame.push(gpEvent);
+      if (gpEvent.event === 'on-connect') {
+        gamepadState.connected.set(gpEvent.data.gamepadId, {
+          name: gpEvent.data.name,
+        });
+      } else if (gpEvent.event === 'on-disconnect') {
+        gamepadState.connected.delete(gpEvent.data.gamepadId);
+        gamepadState.buttons.delete(gpEvent.data.gamepadId);
+        gamepadState.axes.delete(gpEvent.data.gamepadId);
+      } else if (gpEvent.event === 'on-button') {
+        const id = gpEvent.data.gamepadId;
+        let buttons = gamepadState.buttons.get(id);
+        if (!buttons) {
+          buttons = new Map();
+          gamepadState.buttons.set(id, buttons);
+        }
+        buttons.set(gpEvent.data.button, {
+          pressed: gpEvent.data.state === 'pressed',
+          value: gpEvent.data.value,
+        });
+      } else if (gpEvent.event === 'on-axis') {
+        const id = gpEvent.data.gamepadId;
+        let axes = gamepadState.axes.get(id);
+        if (!axes) {
+          axes = new Map();
+          gamepadState.axes.set(id, axes);
+        }
+        axes.set(gpEvent.data.axis, gpEvent.data.value);
+      }
+    }
+    // System events
+    else if (event.type === 'system') {
+      const sysEvent = event.content as SystemEvent;
+      systemEventState.eventsThisFrame.push(sysEvent);
+      if (sysEvent.event === 'error') {
+        systemEventState.lastError = {
+          scope: sysEvent.data.scope,
+          message: sysEvent.data.message,
+          commandId: sysEvent.data.commandId,
+          commandType: sysEvent.data.commandType,
+        };
+      }
+    }
+    // UI events
+    else if (event.type === 'ui') {
+      uiEventState.eventsThisFrame.push(event.content as UiEvent);
+    }
   }
+  world.inboundEvents.length = 0;
 };