@vulfram/engine 0.5.6-alpha

package/src/engine/ecs/index.ts

@@ -0,0 +1,516 @@
+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;
+}
+
+/**
+ * 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?: string;
+  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[];
+  };
+}

package/src/engine/errors.ts

@@ -0,0 +1,10 @@
+/** Error type thrown by the engine runtime. */
+export class EngineError extends Error {
+  code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+    this.name = 'EngineError';
+  }
+}

package/src/engine/state.ts

@@ -0,0 +1,135 @@
+import type { EngineTransport } from '@vulfram/transport-types';
+import type { CommandResponseEnvelope, EngineCmdEnvelope } from '../types/cmds';
+import type { EngineEvent } from '../types/events';
+import type {
+  Component,
+  ComponentType,
+  EngineRegistry,
+  Intent,
+  WorldEvent,
+} from './ecs';
+
+type EngineStatus = 'uninitialized' | 'initialized' | 'disposed';
+
+/**
+ * Component storage indexed by Entity ID.
+ */
+export type ComponentStore = Map<ComponentType, Component>;
+
+type ComponentIdCounters = {
+  camera: number;
+  light: number;
+  model: number;
+};
+
+type ResourceIdCounters = {
+  material: number;
+  geometry: number;
+  texture: number;
+};
+
+export type WorldState = {
+  windowId: number;
+  entities: Set<number>;
+  /**
+   * Components stored by entityId -> componentType -> ComponentData
+   */
+  components: Map<number, ComponentStore>;
+  nextCoreId: number;
+  systems: string[];
+  /**
+   * Pending intents to be processed by systems in the next tick.
+   */
+  pendingIntents: Intent[];
+  /**
+   * Internal world events for system-to-system communication.
+   */
+  internalEvents: WorldEvent[];
+  /**
+   * Pending commands generated by this world in the current frame.
+   * Will be moved to the engine's global batch during the tick.
+   */
+  pendingCommands: EngineCmdEnvelope[];
+  /**
+   * Events routed to this world in the current frame.
+   */
+  inboundEvents: EngineEvent[];
+  /**
+   * Responses routed to this world in the current frame.
+   */
+  inboundResponses: CommandResponseEnvelope[];
+};
+
+export type EngineState = {
+  status: EngineStatus;
+  transport: EngineTransport | null;
+  worlds: Map<number, WorldState>;
+  nextEntityId: number;
+  nextCommandId: number;
+  /**
+   * Global command batch for the current frame.
+   */
+  commandBatch: EngineCmdEnvelope[];
+  /**
+   * Maps command IDs to the world ID that created them.
+   * This is used to route responses back to the correct world.
+   */
+  commandTracker: Map<number, number>;
+  /**
+   * Registry for custom components and systems.
+   */
+  registry: EngineRegistry;
+  /**
+   * Engine clock information.
+   */
+  clock: {
+    lastTime: number;
+    lastDelta: number;
+    frameCount: number;
+  };
+  /**
+   * Internal flags for protection and debugging.
+   */
+  flags: {
+    isExecutingSystems: boolean;
+    debugEnabled: boolean;
+  };
+};
+
+export const REQUIRED_SYSTEMS = [
+  'InputMirrorSystem',
+  'CommandIntentSystem',
+  'ResourceUploadSystem',
+  'CoreCommandBuilderSystem',
+  'ResponseDecodeSystem',
+  'WorldLifecycleSystem',
+  'DiagnosticsSystem',
+];
+
+export const engineState: EngineState = {
+  status: 'uninitialized',
+  transport: null,
+  worlds: new Map(),
+  nextEntityId: 1,
+  nextCommandId: 1,
+  commandBatch: [],
+  commandTracker: new Map(),
+  registry: {
+    components: new Map(),
+    systems: {
+      input: [],
+      update: [],
+      preRender: [],
+      postRender: [],
+    },
+  },
+  clock: {
+    lastTime: 0,
+    lastDelta: 0,
+    frameCount: 0,
+  },
+  flags: {
+    isExecutingSystems: false,
+    debugEnabled: false,
+  },
+};