@vulfram/engine 0.14.8-alpha → 0.17.1-alpha

package/src/engine/systems/resource-upload.ts

@@ -1,8 +1,81 @@
 import type { TextureCreateMode } from '../../types/kinds';
+import type {
+  PrimitiveOptions,
+} from '../../types/cmds/geometry';
 import { enqueueCommand } from '../bridge/dispatch';
-import type { System } from '../ecs';
+import type { GeometryProps, System } from '../ecs';
 import { normalizeMaterialOptions, normalizePrimitiveOptions } from './utils';
 
+function buildPrimitiveOptions(
+  primitiveProps: Extract<GeometryProps, { type: 'primitive' }>,
+): PrimitiveOptions {
+  const { shape, options } = primitiveProps;
+  if (shape === 'cube') {
+    return {
+      type: 'cube',
+      content: {
+        size: options?.size ?? [1.0, 1.0, 1.0],
+        subdivisions: 1,
+      },
+    };
+  }
+  if (shape === 'plane') {
+    return {
+      type: 'plane',
+      content: {
+        size: options?.size ?? [1.0, 1.0, 1.0],
+        subdivisions: options?.subdivisions ?? 1,
+      },
+    };
+  }
+  if (shape === 'sphere') {
+    return {
+      type: 'sphere',
+      content: {
+        radius: options?.radius ?? 0.5,
+        sectors: options?.sectors ?? 32,
+        stacks: options?.stacks ?? 16,
+      },
+    };
+  }
+  if (shape === 'cylinder') {
+    return {
+      type: 'cylinder',
+      content: {
+        radius: options?.radius ?? 0.5,
+        height: options?.height ?? 1.0,
+        sectors: options?.sectors ?? options?.segments ?? 32,
+      },
+    };
+  }
+  if (shape === 'torus') {
+    return {
+      type: 'torus',
+      content: {
+        majorRadius: options?.majorRadius ?? 0.5,
+        minorRadius: options?.minorRadius ?? 0.25,
+        majorSegments: options?.majorSegments ?? options?.radialSegments ?? 32,
+        minorSegments: options?.minorSegments ?? options?.tubularSegments ?? 16,
+      },
+    };
+  }
+  return {
+    type: 'pyramid',
+    content: {
+      size: options?.size ?? [1.0, 1.0, 1.0],
+      subdivisions: options?.subdivisions ?? 1,
+    },
+  };
+}
+
+/**
+ * Processes resource intents and emits corresponding core resource commands.
+ *
+ * Covered resources:
+ * - material
+ * - geometry (custom and primitive)
+ * - texture (from buffer or solid color)
+ */
 export const ResourceUploadSystem: System = (world, context) => {
   const intentsToRemove: number[] = [];
 
@@ -20,8 +93,7 @@ export const ResourceUploadSystem: System = (world, context) => {
         },
       };
 
-      enqueueCommand(context.worldId, 'cmd-material-create', {
-        windowId: context.worldId,
+      enqueueCommand(context.worldId, 'cmd-material-upsert', {
         materialId: intent.resourceId,
         label: intent.props.label || `Mat ${intent.resourceId}`,
         kind: intent.props.kind ?? 'standard',
@@ -30,52 +102,23 @@ export const ResourceUploadSystem: System = (world, context) => {
       intentsToRemove.push(i);
     } else if (intent.type === 'dispose-material') {
       enqueueCommand(context.worldId, 'cmd-material-dispose', {
-        windowId: context.worldId,
         materialId: intent.resourceId,
       });
       intentsToRemove.push(i);
     } else if (intent.type === 'create-geometry') {
       if (intent.props.type === 'primitive') {
-        const shape = intent.props.shape ?? 'cube';
-        let content: any;
-
-        const shapeOptions = intent.props.options;
-        if (shapeOptions) {
-          content = shapeOptions;
-        } else {
-          if (shape === 'cube' || shape === 'plane' || shape === 'pyramid') {
-            content = { size: [1.0, 1.0, 1.0], subdivisions: 1 };
-          } else if (shape === 'sphere') {
-            content = { radius: 0.5, sectors: 32, stacks: 16 };
-          } else if (shape === 'torus') {
-            content = {
-              majorRadius: 0.5,
-              minorRadius: 0.25,
-              majorSegments: 32,
-              minorSegments: 16,
-            };
-          } else if (shape === 'cylinder') {
-            content = { radius: 0.5, height: 1.0, sectors: 32 };
-          } else {
-            content = { size: [1.0, 1.0, 1.0], subdivisions: 1 };
-          }
-        }
-
-        const options = normalizePrimitiveOptions({
-          type: shape,
-          content: content,
-        } as any);
+        const options = normalizePrimitiveOptions(
+          buildPrimitiveOptions(intent.props),
+        );
 
         enqueueCommand(context.worldId, 'cmd-primitive-geometry-create', {
-          windowId: context.worldId,
           geometryId: intent.resourceId,
           label: intent.props.label || `Geo ${intent.resourceId}`,
-          shape: shape,
+          shape: intent.props.shape,
           options: options,
         });
       } else {
-        enqueueCommand(context.worldId, 'cmd-geometry-create', {
-          windowId: context.worldId,
+        enqueueCommand(context.worldId, 'cmd-geometry-upsert', {
           geometryId: intent.resourceId,
           label: intent.props.label || `Geo ${intent.resourceId}`,
           entries: intent.props.entries,
@@ -84,14 +127,19 @@ export const ResourceUploadSystem: System = (world, context) => {
       intentsToRemove.push(i);
     } else if (intent.type === 'dispose-geometry') {
       enqueueCommand(context.worldId, 'cmd-geometry-dispose', {
-        windowId: context.worldId,
         geometryId: intent.resourceId,
       });
       intentsToRemove.push(i);
     } else if (intent.type === 'create-texture') {
       if (intent.props.source.type === 'color') {
-        enqueueCommand(context.worldId, 'cmd-texture-create-solid-color', {
-          windowId: context.worldId,
+        const cmd: {
+          textureId: number;
+          label: string;
+          color: [number, number, number, number];
+          srgb: boolean;
+          mode?: TextureCreateMode;
+          atlasOptions?: { tilePx: number; layers: number };
+        } = {
           textureId: intent.resourceId,
           label: intent.props.label || `Tex ${intent.resourceId}`,
           color: Array.from(intent.props.source.color) as [
@@ -101,10 +149,16 @@ export const ResourceUploadSystem: System = (world, context) => {
             number,
           ],
           srgb: intent.props.srgb ?? true,
-        });
+        };
+        if (intent.props.mode !== undefined) {
+          cmd.mode = intent.props.mode;
+        }
+        if (intent.props.atlasOptions !== undefined) {
+          cmd.atlasOptions = intent.props.atlasOptions;
+        }
+        enqueueCommand(context.worldId, 'cmd-texture-create-solid-color', cmd);
       } else {
         const cmd: {
-          windowId: number;
           textureId: number;
           label: string;
           bufferId: number;
@@ -112,7 +166,6 @@ export const ResourceUploadSystem: System = (world, context) => {
           mode?: TextureCreateMode;
           atlasOptions?: { tilePx: number; layers: number };
         } = {
-          windowId: context.worldId,
           textureId: intent.resourceId,
           label: intent.props.label || `Tex ${intent.resourceId}`,
           bufferId: intent.props.source.bufferId,
@@ -129,7 +182,6 @@ export const ResourceUploadSystem: System = (world, context) => {
       intentsToRemove.push(i);
     } else if (intent.type === 'dispose-texture') {
       enqueueCommand(context.worldId, 'cmd-texture-dispose', {
-        windowId: context.worldId,
         textureId: intent.resourceId,
       });
       intentsToRemove.push(i);

package/src/engine/systems/response-decode.ts

@@ -1,28 +1,82 @@
 import type { System } from '../ecs';
+import { enqueueCommand, markRoutingIndexDirty } from '../bridge/dispatch';
 import { engineState } from '../state';
 
+const MAX_REALM_CREATE_RETRIES = 8;
+const BASE_REALM_RETRY_DELAY_MS = 32;
+
+/**
+ * Decodes and applies command responses routed to a world.
+ *
+ * Responsibilities:
+ * - track realm/window ids returned by core
+ * - retry realm creation on transient host-window races
+ * - complete deferred target binds after target-upsert acknowledgements
+ */
 export const ResponseDecodeSystem: System = (world, context) => {
-  while (world.inboundResponses.length > 0) {
-    const res = world.inboundResponses.shift()!;
+  for (let i = 0; i < world.inboundResponses.length; i++) {
+    const res = world.inboundResponses[i]!;
     const content = res.content as { success?: boolean; message?: string };
 
-    if (engineState.flags.debugEnabled) {
-      const debugKey = '__vulframDebugRespAllCount';
-      const count =
-        (globalThis as unknown as Record<string, number>)[debugKey] || 0;
-      if (count < 10) {
-        console.debug('[Debug] Response', res.type, JSON.stringify(content));
-        (globalThis as unknown as Record<string, number>)[debugKey] = count + 1;
-      }
-    }
-
     if (content && typeof content.success === 'boolean' && !content.success) {
+      if (
+        res.type === 'realm-create' &&
+        world.coreRealmId === undefined &&
+        typeof content.message === 'string' &&
+        content.message.includes('Host window') &&
+        content.message.includes('not found')
+      ) {
+        if (world.realmCreateRetryCount < MAX_REALM_CREATE_RETRIES) {
+          const nowMs = engineState.clock.lastTime;
+          if (nowMs >= world.nextRealmCreateRetryAtMs) {
+            const retryDelay =
+              BASE_REALM_RETRY_DELAY_MS * (1 << world.realmCreateRetryCount);
+            world.realmCreateRetryCount += 1;
+            world.nextRealmCreateRetryAtMs = nowMs + retryDelay;
+            enqueueCommand(
+              context.worldId,
+              'cmd-realm-create',
+              world.realmCreateArgs,
+            );
+          }
+        } else if (world.realmCreateRetryCount === MAX_REALM_CREATE_RETRIES) {
+          console.error(
+            `[World ${context.worldId}] realm-create retries exhausted (${MAX_REALM_CREATE_RETRIES}). Last error: ${content.message}`,
+          );
+          world.realmCreateRetryCount += 1;
+        }
+        continue;
+      }
       console.error(
         `[World ${context.worldId}] Command ${res.type} (ID: ${res.id}) failed: ${content.message}`,
       );
-    } else {
-      // DEBUG: Print all successes too for now
-      // console.debug(`[World ${context.worldId}] Command ${res.type} (ID: ${res.id}) succeeded.`);
+    } else if (res.type === 'realm-create') {
+      const created = res.content as { realmId?: number };
+      if (typeof created.realmId === 'number') {
+        world.coreRealmId = created.realmId;
+        world.realmCreateRetryCount = 0;
+        world.nextRealmCreateRetryAtMs = 0;
+        markRoutingIndexDirty();
+      }
+    } else if (res.type === 'window-create') {
+      const created = res.content as {
+        realmId?: number;
+        surfaceId?: number;
+        presentId?: number;
+      };
+      if (typeof created.realmId === 'number') {
+        world.coreRealmId = created.realmId;
+        world.realmCreateRetryCount = 0;
+        world.nextRealmCreateRetryAtMs = 0;
+        markRoutingIndexDirty();
+      }
+      if (typeof created.surfaceId === 'number') {
+        world.coreSurfaceId = created.surfaceId;
+      }
+      if (typeof created.presentId === 'number') {
+        world.corePresentId = created.presentId;
+      }
     }
   }
+  world.inboundResponses.length = 0;
 };

package/src/engine/systems/scene-sync.ts

@@ -0,0 +1,306 @@
+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,
+} from '../ecs';
+import {
+  getResolvedEntityTransformMatrix,
+  toVec2,
+  toVec3,
+  toVec4,
+} from './utils';
+
+function copyMatrixToScratch(
+  world: Parameters<System>[0],
+  entityId: number,
+  matrix: ArrayLike<number>,
+): number[] {
+  let scratch = world.sceneSyncMatrixScratch.get(entityId);
+  if (!scratch) {
+    scratch = new Array<number>(16);
+    world.sceneSyncMatrixScratch.set(entityId, scratch);
+  }
+  for (let i = 0; i < 16; i++) {
+    scratch[i] = matrix[i] ?? 0;
+  }
+  return scratch;
+}
+
+/**
+ * Synchronizes ECS scene state with core scene objects.
+ *
+ * This system consumes attach/detach/gizmo intents and emits upsert/dispose
+ * commands. It also pushes transform updates for entities whose resolved
+ * constraint matrix changed in the current tick.
+ */
+export const SceneSyncSystem: System = (world, context) => {
+  const intentsToRemove: number[] = [];
+  const realmId = world.coreRealmId;
+  if (realmId === undefined) return;
+
+  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 = getResolvedEntityTransformMatrix(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-upsert', {
+        realmId,
+        modelId,
+        geometryId: intent.props.geometryId,
+        materialId: intent.props.materialId,
+        transform: copyMatrixToScratch(world, intent.entityId, 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 = getResolvedEntityTransformMatrix(world, intent.entityId);
+
+      enqueueCommand(context.worldId, 'cmd-camera-upsert', {
+        realmId,
+        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: copyMatrixToScratch(world, intent.entityId, 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,
+      });
+
+      // Auto-attach the first available camera to realm target layers that were bound
+      // before a camera existed (common when presenting world before scene setup).
+      for (const binding of world.targetLayerBindings.values()) {
+        if (binding.cameraId !== undefined) continue;
+        enqueueCommand(context.worldId, 'cmd-target-layer-upsert', {
+          realmId,
+          targetId: binding.targetId,
+          layout: binding.layout,
+          cameraId,
+          environmentId: binding.environmentId,
+        });
+        binding.cameraId = cameraId;
+      }
+
+      intentsToRemove.push(i);
+    } else if (intent.type === 'attach-light') {
+      const lightId = world.nextCoreId++;
+      const transform = getResolvedEntityTransformMatrix(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: {
+        realmId: 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];
+      } = {
+        realmId,
+        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-upsert', 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 === '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', {
+              realmId,
+              modelId: modelComp.id,
+            });
+          } else if (intent.componentType === 'Camera') {
+            const cameraComp = comp as CameraComponent;
+            enqueueCommand(context.worldId, 'cmd-camera-dispose', {
+              realmId,
+              cameraId: cameraComp.id,
+            });
+          } else if (intent.componentType === 'Light') {
+            const lightComp = comp as LightComponent;
+            enqueueCommand(context.worldId, 'cmd-light-dispose', {
+              realmId,
+              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 (const entityId of world.constraintChangedEntities) {
+    const store = world.components.get(entityId);
+    if (!store) continue;
+
+    const matrix = getResolvedEntityTransformMatrix(world, entityId);
+    let matrixArray: number[] | undefined;
+
+    const model = store.get('Model') as ModelComponent | undefined;
+    if (model) {
+      if (model.skipUpdate) {
+        model.skipUpdate = false;
+      } else {
+        matrixArray = matrixArray ?? copyMatrixToScratch(world, entityId, matrix);
+        enqueueCommand(context.worldId, 'cmd-model-upsert', {
+          realmId,
+          modelId: model.id,
+          transform: matrixArray,
+        });
+      }
+    }
+
+    const camera = store.get('Camera') as CameraComponent | undefined;
+    if (camera) {
+      if (camera.skipUpdate) {
+        camera.skipUpdate = false;
+      } else {
+        matrixArray = matrixArray ?? copyMatrixToScratch(world, entityId, matrix);
+        enqueueCommand(context.worldId, 'cmd-camera-upsert', {
+          realmId,
+          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-upsert', {
+          realmId,
+          lightId: light.id,
+          position: [pos[0], pos[1], pos[2], 1],
+        });
+      }
+    }
+  }
+
+  for (let i = intentsToRemove.length - 1; i >= 0; i--) {
+    const idx = intentsToRemove[i];
+    if (idx !== undefined) world.pendingIntents.splice(idx, 1);
+  }
+};
+
+/** Backward-compatible alias while migrating existing integrations. */
+export const CoreCommandBuilderSystem = SceneSyncSystem;