@vulfram/engine 0.14.8-alpha → 0.19.2-alpha

package/src/engine/ecs/index.ts

@@ -1,518 +1,3 @@
-import type { ViewPosition } from '../../types/cmds/camera';
-import type { GeometryPrimitiveEntry } from '../../types/cmds/geometry';
-import type { MaterialOptions } from '../../types/cmds/material';
-import type { ShadowConfig } from '../../types/cmds/shadow';
-import type { ForwardAtlasOptions } from '../../types/cmds/texture';
-import type { EnvironmentConfig } from '../../types/cmds/environment';
-import type {
-  CameraKind,
-  LightKind,
-  MaterialKind,
-  TextureCreateMode,
-  NotificationLevel,
-  WindowState,
-  CursorGrabMode,
-  CursorIcon,
-  UserAttentionType,
-} from '../../types/kinds';
-import type { WorldState } from '../state';
-
-/**
- * Standard ECS components for Vulfram.
- *
- * Rules:
- * 1. Components are plain data.
- * 2. They are NEVER modified directly by the user during a frame.
- * 3. Changes are requested via Intents.
- */
-
-/**
- * Transform component data used to position entities.
- */
-export interface TransformProps {
-  position?: [number, number, number];
-  rotation?: [number, number, number, number]; // Quaternion
-  scale?: [number, number, number];
-  layerMask?: number;
-  visible?: boolean;
-}
-
-/**
- * Fully-resolved transform component stored in the ECS.
- */
-export interface TransformComponent extends Required<
-  Omit<TransformProps, never>
-> {
-  type: 'Transform';
-}
-
-/**
- * Parent link data used for hierarchical transforms.
- */
-export interface ParentProps {
-  parentId: number;
-}
-
-/**
- * Parent component stored in the ECS.
- */
-export interface ParentComponent extends ParentProps {
-  type: 'Parent';
-}
-
-/**
- * Camera component configuration.
- */
-export interface CameraProps {
-  kind?: CameraKind;
-  near?: number;
-  far?: number;
-  order?: number;
-  viewPosition?: ViewPosition;
-  orthoScale?: number;
-}
-
-/**
- * Camera component stored in the ECS.
- */
-export interface CameraComponent extends Required<
-  Omit<CameraProps, 'viewPosition'>
-> {
-  type: 'Camera';
-  id: number; // Core Camera ID
-  viewPosition?: ViewPosition;
-  skipUpdate?: boolean; // Internal flag to skip next transform update
-}
-
-/**
- * Light component configuration.
- */
-export interface LightProps {
-  kind?: LightKind;
-  color?: [number, number, number];
-  intensity?: number;
-  range?: number;
-  castShadow?: boolean;
-  direction?: [number, number, number];
-  spotInnerOuter?: [number, number];
-}
-
-/**
- * Light component stored in the ECS.
- */
-export interface LightComponent extends Required<Omit<LightProps, never>> {
-  type: 'Light';
-  id: number; // Core Light ID
-  skipUpdate?: boolean; // Internal flag to skip next transform update
-}
-
-/**
- * Model component configuration.
- */
-export interface ModelProps {
-  geometryId: number;
-  materialId?: number;
-  castShadow?: boolean;
-  receiveShadow?: boolean;
-  castOutline?: boolean;
-  outlineColor?: [number, number, number, number];
-}
-
-/**
- * Model component stored in the ECS.
- */
-export interface ModelComponent extends Required<
-  Omit<ModelProps, 'materialId'>
-> {
-  type: 'Model';
-  id: number; // Core Model ID
-  materialId?: number;
-  skipUpdate?: boolean; // Internal flag to skip next transform update
-}
-
-/**
- * Tag component configuration.
- */
-export interface TagProps {
-  name?: string;
-  labels?: string[];
-}
-
-/**
- * Tag component stored in the ECS.
- */
-export interface TagComponent {
-  type: 'Tag';
-  name: string;
-  labels: Set<string>;
-}
-
-/**
- * InputState: Stores the current input state for a world.
- * This is updated each frame based on incoming events.
- */
-export interface InputStateComponent {
-  type: 'InputState';
-  keysPressed: Set<number>; // KeyCodes currently held down
-  keysJustPressed: Set<number>; // KeyCodes pressed this frame
-  keysJustReleased: Set<number>; // KeyCodes released this frame
-  mouseButtons: Set<number>; // Mouse buttons currently held
-  mousePosition: [number, number]; // Current mouse position
-  mouseJustPressed: Set<number>; // Mouse buttons pressed this frame
-  mouseJustReleased: Set<number>; // Mouse buttons released this frame
-  mouseDelta: [number, number]; // Mouse movement delta this frame
-  scrollDelta: [number, number]; // Scroll delta this frame
-}
-
-/**
- * WindowState: Stores window events and state.
- */
-export interface WindowStateComponent {
-  type: 'WindowState';
-  focused: boolean;
-  size: [number, number];
-  position: [number, number];
-  scaleFactor: number;
-  closeRequested: boolean;
-  resizedThisFrame: boolean;
-  movedThisFrame: boolean;
-  focusChangedThisFrame: boolean;
-}
-
-/**
- * Resource Properties
- */
-
-/**
- * Base properties shared by resources.
- */
-export interface BaseResourceProps {
-  label?: string;
-}
-
-/**
- * Material resource configuration.
- */
-export interface MaterialProps extends BaseResourceProps {
-  kind: MaterialKind;
-  options: MaterialOptions;
-}
-
-/**
- * Options for cube primitive geometry.
- */
-export interface CubeOptions {
-  size?: [number, number, number];
-}
-
-/**
- * Options for plane primitive geometry.
- */
-export interface PlaneOptions {
-  size?: [number, number, number];
-  subdivisions?: number;
-}
-
-/**
- * Options for sphere primitive geometry.
- */
-export interface SphereOptions {
-  radius?: number;
-  sectors?: number;
-  stacks?: number;
-}
-
-/**
- * Options for cylinder primitive geometry.
- */
-export interface CylinderOptions {
-  radius?: number;
-  height?: number;
-  segments?: number;
-}
-
-/**
- * Options for torus primitive geometry.
- */
-export interface TorusOptions {
-  majorRadius?: number;
-  minorRadius?: number;
-  radialSegments?: number;
-  tubularSegments?: number;
-}
-
-/**
- * Options for pyramid primitive geometry.
- */
-export interface PyramidOptions {
-  size?: [number, number, number];
-  subdivisions?: number;
-}
-
-/**
- * Geometry resource configuration (primitive or custom).
- */
-export type GeometryProps = BaseResourceProps &
-  (
-    | {
-        type: 'custom';
-        entries: GeometryPrimitiveEntry[];
-      }
-    | ({ type: 'primitive' } & (
-        | { shape: 'cube'; options?: CubeOptions }
-        | { shape: 'plane'; options?: PlaneOptions }
-        | { shape: 'sphere'; options?: SphereOptions }
-        | { shape: 'cylinder'; options?: CylinderOptions }
-        | { shape: 'torus'; options?: TorusOptions }
-        | { shape: 'pyramid'; options?: PyramidOptions }
-      ))
-  );
-
-/**
- * Texture resource configuration.
- */
-export interface TextureProps extends BaseResourceProps {
-  srgb?: boolean;
-  mode?: TextureCreateMode;
-  atlasOptions?: ForwardAtlasOptions;
-  source:
-    | { type: 'buffer'; bufferId: number }
-    | { type: 'color'; color: [number, number, number, number] };
-}
-
-/**
- * Union of all built-in component types.
- */
-export type Component =
-  | TransformComponent
-  | ParentComponent
-  | CameraComponent
-  | LightComponent
-  | ModelComponent
-  | TagComponent
-  | InputStateComponent
-  | WindowStateComponent
-  | CustomComponent;
-
-/**
- * Custom components are dynamic and registered via schema.
- */
-/**
- * Custom component payload stored in the ECS.
- */
-export interface CustomComponent {
-  type: string;
-  data: Record<string, unknown>;
-}
-
-/**
- * String literal type for component identifiers.
- */
-export type ComponentType = Component['type'];
-
-/**
- * Extension Schemas
- */
-
-/**
- * Supported property types for custom schemas.
- */
-export type PropertyType =
-  | 'number'
-  | 'string'
-  | 'boolean'
-  | 'vec2'
-  | 'vec3'
-  | 'vec4'
-  | 'quat'
-  | 'entity'
-  | 'resource'
-  | 'array'
-  | 'object';
-
-/**
- * Schema entry describing a custom component field.
- */
-export interface SchemaProperty {
-  type: PropertyType;
-  default?: unknown;
-  optional?: boolean;
-}
-
-/**
- * Schema definition for a custom component.
- */
-export interface ComponentSchema {
-  [key: string]: SchemaProperty;
-}
-
-/**
- * Window update properties.
- */
-export interface WindowProps {
-  title?: string;
-  position?: [number, number];
-  size?: [number, number];
-  state?: WindowState;
-  resizable?: boolean;
-  decorations?: boolean;
-  cursorVisible?: boolean;
-  cursorGrab?: CursorGrabMode;
-  icon?: number;
-  cursorIcon?: CursorIcon;
-}
-
-/**
- * Window creation properties.
- */
-export interface CreateWindowProps {
-  title: string;
-  size: [number, number];
-  position: [number, number];
-  canvasId?: string;
-  borderless?: boolean;
-  resizable?: boolean;
-  transparent?: boolean;
-  initialState?: WindowState;
-}
-
-/**
- * Intents:
- * Requests to change the state of the World.
- * Systems process Intents and generate Core Commands.
- */
-
-export type Intent =
-  | { type: 'create-window'; props: CreateWindowProps }
-  | { type: 'close-window' }
-  | { type: 'update-window'; props: WindowProps }
-  | { type: 'request-attention'; attentionType?: UserAttentionType }
-  | { type: 'focus-window' }
-  | { 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: 'custom';
-      name: string;
-      data: Record<string, unknown>;
-    };
-
-/**
- * Internal World Events:
- * Events emitted by systems or the engine to be consumed by other systems.
- */
-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;
-    };
-
-/**
- * System Types
- */
-
-/**
- * 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; // Delta time in seconds
-  time: number; // Total time in seconds
-  worldId: number;
-}
-
-/**
- * A System is a function that processes the WorldState.
- * It can emit new Intents, generate Core Commands, or interpret Events.
- */
-/**
- * System function signature.
- */
-export type System = (state: WorldState, context: SystemContext) => void;
-
-/**
- * Registration Hooks
- */
-
-/**
- * Registry of components and systems.
- */
-export interface EngineRegistry {
-  components: Map<string, ComponentSchema>;
-  systems: {
-    input: System[];
-    update: System[];
-    preRender: System[];
-    postRender: System[];
-  };
-}
+export * from './components';
+export * from './intents';
+export * from './systems';

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