@vulfram/engine 0.17.1-alpha → 0.19.2-alpha

package/README.md

@@ -5,10 +5,10 @@ Functional engine for the Vulfram core, focused on a simple API for creating wor
 ## Installation
 
 ```bash
-bun add @vulfram/engine @vulfram/transport-wasm
+bun add @vulfram/engine @vulfram/transport-browser
 ```
 
-Use the transport that fits your environment (`transport-wasm`, `transport-bun`, `transport-napi`).
+Use the transport that fits your environment (`transport-browser`, `transport-bun`, `transport-napi`).
 
 ## Simple example
 
@@ -17,7 +17,7 @@ import { initEngine, tick } from '@vulfram/engine/core';
 import { createWindow } from '@vulfram/engine/window';
 import { mountWorldToWindow } from '@vulfram/engine/mount';
 import * as World3D from '@vulfram/engine/world3d';
-import { transportWasm } from '@vulfram/transport-wasm';
+import { transportWasm } from '@vulfram/transport-browser';
 
 initEngine({ transport: transportWasm });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vulfram/engine",
-  "version": "0.17.1-alpha",
+  "version": "0.19.2-alpha",
   "module": "src/index.ts",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -47,6 +47,11 @@
       "import": "./src/types/index.ts",
       "types": "./src/types/index.ts"
     },
+    "./helpers": {
+      "default": "./src/helpers/index.ts",
+      "import": "./src/helpers/index.ts",
+      "types": "./src/helpers/index.ts"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -57,12 +62,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@vulfram/transport-types": "^0.2.5",
+    "@vulfram/transport-types": "^0.2.6",
     "gl-matrix": "^3.4.4",
-    "glob": "^13.0.6",
     "msgpackr": "^1.11.8"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.10"
+    "@types/bun": "^1.3.10",
+    "glob": "^13.0.6"
   }
 }

package/src/engine/api.ts

@@ -14,6 +14,7 @@ import {
 import type { ComponentSchema, System, SystemContext, SystemStep } from './ecs';
 import { EngineError } from './errors';
 import { engineState, REQUIRED_SYSTEMS, type WorldState } from './state';
+import { createIntentStore } from './intents/store';
 import * as CoreSystems from './systems';
 import type { UploadType } from '../types/kinds';
 import type { RealmKind } from '../types/cmds/realm';
@@ -41,25 +42,10 @@ function recalculateWorldWindowBindings(world: WorldState): void {
   world.primaryWindowId = primary;
 }
 
-function findLowestConfirmedWindowId(): number | undefined {
-  if (engineState.confirmedWindowIds.size === 0) {
-    return undefined;
-  }
-  let minWindowId = Number.POSITIVE_INFINITY;
-  for (const windowId of engineState.confirmedWindowIds) {
-    if (windowId < minWindowId) {
-      minWindowId = windowId;
-    }
-  }
-  return Number.isFinite(minWindowId) ? minWindowId : undefined;
-}
-
 /**
  * Shared realm creation options used by `createWorld3D` and `createWorldUI`.
  */
 export type CreateWorldOptions = {
-  /** Optional output surface id when provided by host integration. */
-  outputSurfaceId?: number;
   /** Core scheduling hint for realm priority. */
   importance?: number;
   /** Core-side cache policy value. */
@@ -227,14 +213,13 @@ export function uploadBuffer(
   }
 }
 
-function createRealmWorld(kind: RealmKind, config: CreateWorldOptions = {}): WorldId {
+function createRealmWorld(
+  kind: RealmKind,
+  config: CreateWorldOptions = {},
+): WorldId {
   requireInitialized();
 
   const worldId = engineState.nextWorldId++;
-  // Core compatibility: when at least one window exists, pick the lowest ID as host window
-  // if the caller did not provide an explicit surface. This keeps world API window-agnostic
-  // while satisfying render graph bootstrap paths that still rely on host-window mapping.
-  const inferredHostWindowId = findLowestConfirmedWindowId();
 
   const world: WorldState = {
     worldId,
@@ -246,8 +231,6 @@ function createRealmWorld(kind: RealmKind, config: CreateWorldOptions = {}): Wor
     coreRealmId: undefined,
     realmCreateArgs: {
       kind,
-      hostWindowId: inferredHostWindowId,
-      outputSurfaceId: config.outputSurfaceId,
       importance: config.importance,
       cachePolicy: config.cachePolicy,
       flags: config.flags,
@@ -266,7 +249,7 @@ function createRealmWorld(kind: RealmKind, config: CreateWorldOptions = {}): Wor
     components: new Map(),
     nextCoreId: 100,
     systems: [...REQUIRED_SYSTEMS],
-    pendingIntents: [],
+    intentStore: createIntentStore(),
     internalEvents: [],
     pendingCommands: [],
     pendingCommandsHead: 0,
@@ -430,7 +413,9 @@ function processGlobalResponses(): void {
     const res = engineState.globalInboundResponses[i]!;
     const content = res.content as { success?: boolean; message?: string };
     if (res.type === 'window-create') {
-      const pendingWindowId = engineState.pendingWindowCreateByCommandId.get(res.id);
+      const pendingWindowId = engineState.pendingWindowCreateByCommandId.get(
+        res.id,
+      );
       if (pendingWindowId !== undefined) {
         if (content.success) {
           engineState.confirmedWindowIds.add(pendingWindowId);
@@ -440,7 +425,9 @@ function processGlobalResponses(): void {
         engineState.pendingWindowCreateByCommandId.delete(res.id);
       }
     } else if (res.type === 'window-close') {
-      const pendingWindowId = engineState.pendingWindowCloseByCommandId.get(res.id);
+      const pendingWindowId = engineState.pendingWindowCloseByCommandId.get(
+        res.id,
+      );
       if (pendingWindowId !== undefined) {
         if (content.success) {
           engineState.usedWindowIds.delete(pendingWindowId);

package/src/engine/bridge/dispatch.ts

@@ -1,6 +1,5 @@
 import type { CommandResponseEnvelope, EngineCmd } from '../../types/cmds';
 import type { EngineEvent } from '../../types/events';
-import { EngineError } from '../errors';
 import { engineState } from '../state';
 import { getWorldOrThrow, requireInitialized } from './guards';
 
@@ -88,13 +87,9 @@ export function enqueueCommand<T extends EngineCmd['type']>(
     typedContent.windowId = world.primaryWindowId;
   }
   if ('realmId' in typedContent && typedContent.realmId == null) {
-    if (world.coreRealmId === undefined) {
-      throw new EngineError(
-        'WorldNotReady',
-        `World ${worldId} realm is not ready yet. Wait for at least one tick after createWorld.`,
-      );
-    }
-    typedContent.realmId = world.coreRealmId;
+    // Avoid host-side readiness guards: keep logical-id flow stable.
+    // Core validates realm existence and may apply internal fallbacks.
+    typedContent.realmId = world.coreRealmId ?? world.worldId;
   }
 
   world.pendingCommands.push({

package/src/engine/ecs/components.ts

@@ -0,0 +1,340 @@
+import type { ViewPosition } from '../../types/cmds/camera';
+import type { GeometryPrimitiveEntry } from '../../types/cmds/geometry';
+import type { MaterialOptions } from '../../types/cmds/material';
+import type { ForwardAtlasOptions } from '../../types/cmds/texture';
+import type { GamepadEvent, SystemEvent, UiEvent } from '../../types/events';
+import type {
+  CameraKind,
+  LightKind,
+  MaterialKind,
+  TextureCreateMode,
+} from '../../types/kinds';
+import type { JsonObject, JsonValue } from '../../types/json';
+
+/** Transform component data used to position entities. */
+export interface TransformProps {
+  position?: [number, number, number];
+  rotation?: [number, number, number, number];
+  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;
+  viewPosition?: ViewPosition;
+  skipUpdate?: boolean;
+}
+
+/** 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;
+  skipUpdate?: boolean;
+}
+
+/** 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;
+  materialId?: number;
+  skipUpdate?: boolean;
+}
+
+/** 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. */
+export interface InputStateComponent {
+  type: 'InputState';
+  keysPressed: Set<number>;
+  keysJustPressed: Set<number>;
+  keysJustReleased: Set<number>;
+  pointerButtons: Set<number>;
+  pointerPosition: [number, number];
+  pointerDelta: [number, number];
+  pointerJustPressed: Set<number>;
+  pointerJustReleased: Set<number>;
+  pointerWindowId?: number;
+  pointerWindowSize?: [number, number];
+  pointerTargetId?: number;
+  pointerPositionTarget?: [number, number];
+  pointerTargetSize?: [number, number];
+  pointerTargetUv?: [number, number];
+  pointerTargetDelta?: [number, number];
+  scrollDelta: [number, number];
+  imeEnabled: boolean;
+  imePreeditText?: string;
+  imeCursorRange?: [number, number];
+  imeCommitText?: string;
+}
+
+/** 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 }>;
+}
+
+/** 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;
+  segments?: number;
+}
+
+/** Options for torus primitive geometry. */
+export interface TorusOptions {
+  majorRadius?: number;
+  minorRadius?: number;
+  majorSegments?: number;
+  minorSegments?: 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] };
+}
+
+/** Custom component payload stored in the ECS. */
+export interface CustomComponent {
+  type: string;
+  data: JsonObject;
+}
+
+/** Union of all built-in component types. */
+export type Component =
+  | TransformComponent
+  | ParentComponent
+  | CameraComponent
+  | LightComponent
+  | ModelComponent
+  | TagComponent
+  | InputStateComponent
+  | WindowStateComponent
+  | GamepadStateComponent
+  | SystemEventStateComponent
+  | UiEventStateComponent
+  | UiStateComponent
+  | CustomComponent;
+
+/** String literal type for component identifiers. */
+export type ComponentType = Component['type'];
+
+/** 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;
+}