@vulfram/engine 0.17.1-alpha → 0.19.2-alpha

package/src/engine/ecs/intents.ts

@@ -0,0 +1,184 @@
+import type {
+  CmdUiAccessKitActionRequestArgs,
+  CmdUiApplyOpsArgs,
+  CmdUiClipboardPasteArgs,
+  CmdUiDebugSetArgs,
+  CmdUiDocumentCreateArgs,
+  CmdUiDocumentDisposeArgs,
+  CmdUiDocumentGetLayoutRectsArgs,
+  CmdUiDocumentGetTreeArgs,
+  CmdUiDocumentSetRectArgs,
+  CmdUiDocumentSetThemeArgs,
+  CmdUiEventTraceSetArgs,
+  CmdUiFocusGetArgs,
+  CmdUiFocusSetArgs,
+  CmdUiImageCreateFromBufferArgs,
+  CmdUiImageDisposeArgs,
+  CmdUiScreenshotReplyArgs,
+  CmdUiThemeDefineArgs,
+  CmdUiThemeDisposeArgs,
+} from '../../types/cmds/ui';
+import type { EnvironmentConfig } from '../../types/cmds/environment';
+import type { ShadowConfig } from '../../types/cmds/shadow';
+import type { NotificationLevel } from '../../types/kinds';
+import type { JsonObject } from '../../types/json';
+import type {
+  CameraProps,
+  ComponentType,
+  GeometryProps,
+  LightProps,
+  MaterialProps,
+  ModelProps,
+  TagProps,
+  TextureProps,
+  TransformProps,
+  UiFocusCycleMode,
+} from './components';
+
+export type Intent =
+  | { type: 'configure-environment'; config: EnvironmentConfig }
+  | {
+      type: 'request-resource-list';
+      resourceType:
+        | 'model'
+        | 'material'
+        | 'texture'
+        | 'geometry'
+        | 'light'
+        | 'camera';
+    }
+  | { type: 'create-entity'; worldId: number; entityId: number }
+  | { type: 'remove-entity'; entityId: number }
+  | {
+      type: 'update-transform';
+      entityId: number;
+      props: TransformProps;
+    }
+  | {
+      type: 'attach-camera';
+      entityId: number;
+      props: CameraProps;
+    }
+  | {
+      type: 'attach-model';
+      entityId: number;
+      props: ModelProps;
+    }
+  | {
+      type: 'attach-light';
+      entityId: number;
+      props: LightProps;
+    }
+  | {
+      type: 'attach-tag';
+      entityId: number;
+      props: TagProps;
+    }
+  | { type: 'create-material'; resourceId: number; props: MaterialProps }
+  | { type: 'create-geometry'; resourceId: number; props: GeometryProps }
+  | { type: 'create-texture'; resourceId: number; props: TextureProps }
+  | { type: 'dispose-material'; resourceId: number }
+  | { type: 'dispose-texture'; resourceId: number }
+  | { type: 'dispose-geometry'; resourceId: number }
+  | { type: 'detach-component'; entityId: number; componentType: ComponentType }
+  | { type: 'set-parent'; entityId: number; parentId: number | null }
+  | {
+      type: 'send-notification';
+      level: NotificationLevel;
+      title: string;
+      message: string;
+    }
+  | { type: 'configure-shadows'; config: ShadowConfig }
+  | {
+      type: 'gizmo-draw-line';
+      start: [number, number, number];
+      end: [number, number, number];
+      color: [number, number, number, number];
+    }
+  | {
+      type: 'gizmo-draw-aabb';
+      min: [number, number, number];
+      max: [number, number, number];
+      color: [number, number, number, number];
+    }
+  | { type: 'ui-theme-define'; args: CmdUiThemeDefineArgs }
+  | { type: 'ui-theme-dispose'; args: CmdUiThemeDisposeArgs }
+  | { type: 'ui-document-create'; args: CmdUiDocumentCreateArgs }
+  | { type: 'ui-document-dispose'; args: CmdUiDocumentDisposeArgs }
+  | { type: 'ui-document-set-rect'; args: CmdUiDocumentSetRectArgs }
+  | { type: 'ui-document-set-theme'; args: CmdUiDocumentSetThemeArgs }
+  | { type: 'ui-document-get-tree'; args: CmdUiDocumentGetTreeArgs }
+  | {
+      type: 'ui-document-get-layout-rects';
+      args: CmdUiDocumentGetLayoutRectsArgs;
+    }
+  | { type: 'ui-apply-ops'; args: CmdUiApplyOpsArgs }
+  | { type: 'ui-debug-set'; args: CmdUiDebugSetArgs }
+  | { type: 'ui-focus-set'; args: CmdUiFocusSetArgs }
+  | { type: 'ui-focus-get'; args: CmdUiFocusGetArgs }
+  | { type: 'ui-event-trace-set'; args: CmdUiEventTraceSetArgs }
+  | { type: 'ui-image-create-from-buffer'; args: CmdUiImageCreateFromBufferArgs }
+  | { type: 'ui-image-dispose'; args: CmdUiImageDisposeArgs }
+  | { type: 'ui-clipboard-paste'; args: CmdUiClipboardPasteArgs }
+  | { type: 'ui-screenshot-reply'; args: CmdUiScreenshotReplyArgs }
+  | {
+      type: 'ui-access-kit-action-request';
+      args: CmdUiAccessKitActionRequestArgs;
+    }
+  | {
+      type: 'ui-form-upsert';
+      form: {
+        formId: string;
+        windowId: number;
+        realmId: number;
+        documentId: number;
+        disabled?: boolean;
+        cycleMode?: UiFocusCycleMode;
+        activeFieldsetId?: string;
+      };
+    }
+  | { type: 'ui-form-dispose'; formId: string }
+  | {
+      type: 'ui-fieldset-upsert';
+      fieldset: {
+        formId: string;
+        fieldsetId: string;
+        disabled?: boolean;
+        legendNodeId?: number;
+      };
+    }
+  | { type: 'ui-fieldset-dispose'; formId: string; fieldsetId: string }
+  | {
+      type: 'ui-focusable-upsert';
+      focusable: {
+        formId: string;
+        nodeId: number;
+        tabIndex?: number;
+        fieldsetId?: string;
+        disabled?: boolean;
+        orderHint?: number;
+      };
+    }
+  | { type: 'ui-focusable-dispose'; nodeId: number }
+  | {
+      type: 'ui-focus-next';
+      windowId: number;
+      backwards?: boolean;
+      formId?: string;
+    }
+  | {
+      type: 'custom';
+      name: string;
+      data: JsonObject;
+    };
+
+/** Internal World Events. */
+export type WorldEvent =
+  | { type: 'entity-created'; entityId: number }
+  | { type: 'entity-destroyed'; entityId: number }
+  | { type: 'component-added'; entityId: number; componentType: ComponentType }
+  | {
+      type: 'component-removed';
+      entityId: number;
+      componentType: ComponentType;
+    };

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

@@ -6,9 +6,9 @@ import type {
   Component,
   ComponentType,
   EngineRegistry,
-  Intent,
   WorldEvent,
 } from './ecs';
+import type { IntentStore } from './intents/store';
 
 type EngineStatus = 'uninitialized' | 'initialized' | 'disposed';
 
@@ -109,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.
    */

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

@@ -9,6 +9,14 @@ import type {
 } 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,
@@ -39,13 +47,12 @@ function wouldCreateParentCycle(
  * 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
@@ -65,7 +72,6 @@ export const CommandIntentSystem: System = (world, context) => {
         });
       }
       world.constraintDirtyEntities.add(intent.entityId);
-      intentsToRemove.push(i);
     } else if (intent.type === 'attach-tag') {
       let store = world.components.get(intent.entityId);
       if (!store) {
@@ -77,7 +83,6 @@ export const CommandIntentSystem: System = (world, context) => {
         name: intent.props.name ?? '',
         labels: new Set(intent.props.labels ?? []),
       });
-      intentsToRemove.push(i);
     } else if (intent.type === 'set-parent') {
       let store = world.components.get(intent.entityId);
       if (!store) {
@@ -100,14 +105,12 @@ export const CommandIntentSystem: System = (world, context) => {
           console.error(
             `[World ${context.worldId}] Invalid parent constraint: entity ${intent.entityId} cannot parent itself.`,
           );
-          intentsToRemove.push(i);
           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}.`,
           );
-          intentsToRemove.push(i);
           continue;
         }
         store.set('Parent', {
@@ -132,7 +135,6 @@ export const CommandIntentSystem: System = (world, context) => {
         children.add(intent.entityId);
       }
       world.constraintDirtyEntities.add(intent.entityId);
-      intentsToRemove.push(i);
     } else if (intent.type === 'update-transform') {
       const store = world.components.get(intent.entityId);
       if (!store) {
@@ -155,7 +157,6 @@ export const CommandIntentSystem: System = (world, context) => {
       }
       Object.assign(transform, nextProps);
       world.constraintDirtyEntities.add(intent.entityId);
-      intentsToRemove.push(i);
     } else if (intent.type === 'remove-entity') {
       if (realmId === undefined) continue;
 
@@ -213,12 +214,6 @@ export const CommandIntentSystem: System = (world, context) => {
       world.resolvedEntityTransforms.delete(intent.entityId);
       world.sceneSyncMatrixScratch.delete(intent.entityId);
       world.constraintDirtyEntities.add(intent.entityId);
-      intentsToRemove.push(i);
     }
   }
-
-  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/diagnostics.ts

@@ -9,10 +9,9 @@ import type { System } from '../ecs';
  * `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];
+  const intents = world.intentStore.take('request-resource-list');
+  for (let i = 0; i < intents.length; i++) {
+    const intent = intents[i];
     if (intent?.type === 'request-resource-list') {
       let windowId = world.primaryWindowId;
       if (windowId === undefined) {
@@ -21,9 +20,6 @@ export const DiagnosticsSystem: System = (world, context) => {
           break;
         }
       }
-      if (windowId === undefined) {
-        windowId = world.realmCreateArgs.hostWindowId;
-      }
       if (windowId === undefined) {
         continue;
       }
@@ -32,12 +28,6 @@ export const DiagnosticsSystem: System = (world, context) => {
       enqueueCommand(context.worldId, cmdType, {
         windowId,
       });
-      intentsToRemove.push(i);
     }
   }
-
-  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/input-mirror.ts

@@ -20,6 +20,85 @@ import type {
  * gamepad, system, and UI event streams.
  */
 export const InputMirrorSystem: System = (world) => {
+  const resolveWindowSize = (data: {
+    windowWidth?: number;
+    windowHeight?: number;
+  }): [number, number] | undefined => {
+    if (
+      typeof data.windowWidth === 'number' &&
+      typeof data.windowHeight === 'number'
+    ) {
+      return [data.windowWidth, data.windowHeight];
+    }
+    return undefined;
+  };
+
+  const resolveTargetSize = (data: {
+    targetWidth?: number;
+    targetHeight?: number;
+  }): [number, number] | undefined => {
+    if (
+      typeof data.targetWidth === 'number' &&
+      typeof data.targetHeight === 'number'
+    ) {
+      return [data.targetWidth, data.targetHeight];
+    }
+    return undefined;
+  };
+
+  const applyPointerPosition = (
+    inputState: InputStateComponent,
+    globalPosition: [number, number],
+    targetPosition?: [number, number],
+    targetId?: number,
+    targetUv?: [number, number],
+    windowSize?: [number, number],
+    targetSize?: [number, number],
+  ): void => {
+    const oldGlobalPosition = inputState.pointerPosition;
+    inputState.pointerDelta = [
+      globalPosition[0] - oldGlobalPosition[0],
+      globalPosition[1] - oldGlobalPosition[1],
+    ];
+    inputState.pointerPosition = globalPosition;
+    inputState.pointerWindowSize = windowSize;
+
+    if (targetPosition) {
+      const previousTargetId = inputState.pointerTargetId;
+      const previousTargetPosition = inputState.pointerPositionTarget;
+      if (
+        previousTargetId === targetId &&
+        previousTargetPosition !== undefined
+      ) {
+        inputState.pointerTargetDelta = [
+          targetPosition[0] - previousTargetPosition[0],
+          targetPosition[1] - previousTargetPosition[1],
+        ];
+      } else {
+        inputState.pointerTargetDelta = [0, 0];
+      }
+      inputState.pointerPositionTarget = targetPosition;
+      inputState.pointerTargetId = targetId;
+      inputState.pointerTargetSize = targetSize;
+      inputState.pointerTargetUv = targetUv;
+      return;
+    }
+
+    inputState.pointerPositionTarget = undefined;
+    inputState.pointerTargetDelta = undefined;
+    inputState.pointerTargetId = undefined;
+    inputState.pointerTargetSize = undefined;
+    inputState.pointerTargetUv = undefined;
+  };
+
+  const clearPointerTargetState = (inputState: InputStateComponent): void => {
+    inputState.pointerPositionTarget = undefined;
+    inputState.pointerTargetDelta = undefined;
+    inputState.pointerTargetId = undefined;
+    inputState.pointerTargetSize = undefined;
+    inputState.pointerTargetUv = undefined;
+  };
+
   // Ensure InputState component exists for the world
   let inputState: InputStateComponent | undefined;
   let windowState: WindowStateComponent | undefined;
@@ -43,12 +122,15 @@ export const InputMirrorSystem: System = (world) => {
       keysPressed: new Set(),
       keysJustPressed: new Set(),
       keysJustReleased: new Set(),
-      mouseButtons: new Set(),
-      mousePosition: [0, 0],
-      mouseJustPressed: new Set(),
-      mouseJustReleased: new Set(),
-      mouseDelta: [0, 0],
+      pointerButtons: new Set(),
+      pointerPosition: [0, 0],
+      pointerDelta: [0, 0],
+      pointerJustPressed: new Set(),
+      pointerJustReleased: new Set(),
+      pointerWindowSize: undefined,
+      pointerTargetSize: undefined,
       scrollDelta: [0, 0],
+      imeEnabled: false,
     };
     worldStore.set('InputState', inputState);
   }
@@ -104,10 +186,14 @@ export const InputMirrorSystem: System = (world) => {
   // Clear "just pressed/released" from previous frame
   inputState.keysJustPressed.clear();
   inputState.keysJustReleased.clear();
-  inputState.mouseJustPressed.clear();
-  inputState.mouseJustReleased.clear();
-  inputState.mouseDelta = [0, 0];
+  inputState.pointerJustPressed.clear();
+  inputState.pointerJustReleased.clear();
+  inputState.pointerDelta = [0, 0];
+  inputState.pointerTargetDelta = inputState.pointerPositionTarget
+    ? [0, 0]
+    : undefined;
   inputState.scrollDelta = [0, 0];
+  inputState.imeCommitText = undefined;
   windowState.resizedThisFrame = false;
   windowState.movedThisFrame = false;
   windowState.focusChangedThisFrame = false;
@@ -137,6 +223,21 @@ export const InputMirrorSystem: System = (world) => {
           inputState.keysPressed.delete(keyCode);
           inputState.keysJustReleased.add(keyCode);
         }
+      } else if (kbEvent.event === 'on-ime-enable') {
+        inputState.imeEnabled = true;
+      } else if (kbEvent.event === 'on-ime-preedit') {
+        inputState.imeEnabled = true;
+        inputState.imePreeditText = kbEvent.data.text;
+        inputState.imeCursorRange = kbEvent.data.cursorRange;
+      } else if (kbEvent.event === 'on-ime-commit') {
+        inputState.imeEnabled = true;
+        inputState.imeCommitText = kbEvent.data.text;
+        inputState.imePreeditText = undefined;
+        inputState.imeCursorRange = undefined;
+      } else if (kbEvent.event === 'on-ime-disable') {
+        inputState.imeEnabled = false;
+        inputState.imePreeditText = undefined;
+        inputState.imeCursorRange = undefined;
       }
     }
 
@@ -145,25 +246,43 @@ export const InputMirrorSystem: System = (world) => {
       const ptrEvent = event.content as PointerEvent;
 
       if (ptrEvent.event === 'on-move') {
-        const oldPos = inputState.mousePosition;
-        const newPos = ptrEvent.data.position;
-        inputState.mouseDelta = [newPos[0] - oldPos[0], newPos[1] - oldPos[1]];
-        inputState.mousePosition = newPos;
+        inputState.pointerWindowId = ptrEvent.data.windowId;
+        applyPointerPosition(
+          inputState,
+          ptrEvent.data.position,
+          ptrEvent.data.positionTarget,
+          ptrEvent.data.trace?.targetId,
+          ptrEvent.data.trace?.uv,
+          resolveWindowSize(ptrEvent.data),
+          resolveTargetSize(ptrEvent.data),
+        );
       } else if (ptrEvent.event === 'on-button') {
         const button = ptrEvent.data.button;
         const pressed = ptrEvent.data.state === 'pressed';
 
         if (pressed) {
-          if (!inputState.mouseButtons.has(button)) {
-            inputState.mouseJustPressed.add(button);
+          if (!inputState.pointerButtons.has(button)) {
+            inputState.pointerJustPressed.add(button);
           }
-          inputState.mouseButtons.add(button);
+          inputState.pointerButtons.add(button);
         } else {
-          inputState.mouseButtons.delete(button);
-          inputState.mouseJustReleased.add(button);
+          inputState.pointerButtons.delete(button);
+          inputState.pointerJustReleased.add(button);
         }
-        inputState.mousePosition = ptrEvent.data.position;
+        inputState.pointerWindowId = ptrEvent.data.windowId;
+        applyPointerPosition(
+          inputState,
+          ptrEvent.data.position,
+          ptrEvent.data.positionTarget,
+          ptrEvent.data.trace?.targetId,
+          ptrEvent.data.trace?.uv,
+          resolveWindowSize(ptrEvent.data),
+          resolveTargetSize(ptrEvent.data),
+        );
       } else if (ptrEvent.event === 'on-scroll') {
+        inputState.pointerWindowId = ptrEvent.data.windowId;
+        inputState.pointerWindowSize = resolveWindowSize(ptrEvent.data);
+        inputState.pointerTargetSize = resolveTargetSize(ptrEvent.data);
         const delta = ptrEvent.data.delta;
         if (delta.type === 'line') {
           inputState.scrollDelta = delta.value;
@@ -171,6 +290,25 @@ export const InputMirrorSystem: System = (world) => {
           // Convert pixel to approximate line delta (rough estimate)
           inputState.scrollDelta = [delta.value[0] / 20, delta.value[1] / 20];
         }
+      } else if (ptrEvent.event === 'on-touch') {
+        inputState.pointerWindowId = ptrEvent.data.windowId;
+        applyPointerPosition(
+          inputState,
+          ptrEvent.data.position,
+          ptrEvent.data.positionTarget,
+          ptrEvent.data.trace?.targetId,
+          ptrEvent.data.trace?.uv,
+          resolveWindowSize(ptrEvent.data),
+          resolveTargetSize(ptrEvent.data),
+        );
+      } else if (ptrEvent.event === 'on-leave') {
+        inputState.pointerWindowId = ptrEvent.data.windowId;
+        inputState.pointerWindowSize = resolveWindowSize(ptrEvent.data);
+        clearPointerTargetState(inputState);
+      } else if (ptrEvent.event === 'on-enter') {
+        inputState.pointerWindowId = ptrEvent.data.windowId;
+        inputState.pointerWindowSize = resolveWindowSize(ptrEvent.data);
+        inputState.pointerTargetSize = resolveTargetSize(ptrEvent.data);
       }
     }