@vulfram/engine 0.17.1-alpha → 0.19.2-alpha

package/src/engine/ecs/index.ts

@@ -1,661 +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 { GamepadEvent, SystemEvent, UiEvent } from '../../types/events';
-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 {
-  CameraKind,
-  LightKind,
-  MaterialKind,
-  TextureCreateMode,
-  NotificationLevel,
-} from '../../types/kinds';
-import type { JsonObject, JsonValue } from '../../types/json';
-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;
-}
-
-/**
- * Gamepad state mirrored from core gamepad events.
- */
-export interface GamepadStateComponent {
-  type: 'GamepadState';
-  connected: Map<number, { name: string }>;
-  buttons: Map<number, Map<number, { pressed: boolean; value: number }>>;
-  axes: Map<number, Map<number, number>>;
-  eventsThisFrame: GamepadEvent[];
-}
-
-/**
- * System events mirrored for host-level integrations.
- */
-export interface SystemEventStateComponent {
-  type: 'SystemEventState';
-  eventsThisFrame: SystemEvent[];
-  lastError?: {
-    scope: string;
-    message: string;
-    commandId?: number;
-    commandType?: string;
-  };
-}
-
-/**
- * UI events mirrored from core UI event channel.
- */
-export interface UiEventStateComponent {
-  type: 'UiEventState';
-  eventsThisFrame: UiEvent[];
-}
-
-/**
- * Focus traversal behavior when reaching first/last input.
- */
-export type UiFocusCycleMode = 'wrap' | 'clamp';
-
-/**
- * Form scope state used to control focus traversal.
- */
-export interface UiFormScope {
-  formId: string;
-  windowId: number;
-  realmId: number;
-  documentId: number;
-  disabled: boolean;
-  cycleMode: UiFocusCycleMode;
-  activeFieldsetId?: string;
-  activeNodeId?: number;
-}
-
-/**
- * Fieldset scope metadata.
- */
-export interface UiFieldsetScope {
-  formId: string;
-  fieldsetId: string;
-  disabled: boolean;
-  legendNodeId?: number;
-}
-
-/**
- * Focusable node metadata for tab ordering.
- */
-export interface UiFocusableNode {
-  formId: string;
-  nodeId: number;
-  tabIndex: number;
-  fieldsetId?: string;
-  disabled: boolean;
-  orderHint: number;
-}
-
-/**
- * UI runtime state mirrored in the ECS world.
- */
-export interface UiStateComponent {
-  type: 'UiState';
-  forms: Map<string, UiFormScope>;
-  fieldsets: Map<string, UiFieldsetScope>;
-  nodes: Map<number, UiFocusableNode>;
-  focusByWindow: Map<number, { formId: string; nodeId: number }>;
-}
-
-/**
- * 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;
-  sectors?: number;
-  /** @deprecated use `sectors` */
-  segments?: number;
-}
-
-/**
- * Options for torus primitive geometry.
- */
-export interface TorusOptions {
-  majorRadius?: number;
-  minorRadius?: number;
-  majorSegments?: number;
-  minorSegments?: number;
-  /** @deprecated use `majorSegments` */
-  radialSegments?: number;
-  /** @deprecated use `minorSegments` */
-  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
-  | GamepadStateComponent
-  | SystemEventStateComponent
-  | UiEventStateComponent
-  | UiStateComponent
-  | CustomComponent;
-
-/**
- * Custom components are dynamic and registered via schema.
- */
-/**
- * Custom component payload stored in the ECS.
- */
-export interface CustomComponent {
-  type: string;
-  data: JsonObject;
-}
-
-/**
- * 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?: JsonValue;
-  optional?: boolean;
-}
-
-/**
- * Schema definition for a custom component.
- */
-export interface ComponentSchema {
-  [key: string]: SchemaProperty;
-}
-
-/**
- * Intents:
- * Requests to change the state of the World.
- * Systems process Intents and generate Core Commands.
- */
-
-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:
- * 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';