@vulfram/engine 0.5.6-alpha

package/src/types/cmds/geometry.ts

@@ -0,0 +1,144 @@
+import type { PrimitiveShape } from '../kinds';
+
+/** Primitive attribute semantic identifiers. */
+export type GeometryPrimitiveType =
+  | 'index'
+  | 'position'
+  | 'normal'
+  | 'tangent'
+  | 'color'
+  | 'uv'
+  | 'skin-joints'
+  | 'skin-weights';
+
+/** Convenience mapping for primitive attribute identifiers. */
+export const GeometryPrimitiveType = {
+  Index: 'index' as const,
+  Position: 'position' as const,
+  Normal: 'normal' as const,
+  Tangent: 'tangent' as const,
+  Color: 'color' as const,
+  UV: 'uv' as const,
+  SkinJoints: 'skin-joints' as const,
+  SkinWeights: 'skin-weights' as const,
+};
+
+/** Geometry buffer entry describing a single attribute stream. */
+export interface GeometryPrimitiveEntry {
+  primitiveType: GeometryPrimitiveType;
+  bufferId: number;
+}
+
+/** Command payload for creating geometry from buffers. */
+export interface CmdGeometryCreateArgs {
+  windowId: number;
+  geometryId: number;
+  label?: string;
+  entries: GeometryPrimitiveEntry[];
+}
+
+/** Result payload for geometry create. */
+export interface CmdResultGeometryCreate {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for updating geometry buffers or label. */
+export interface CmdGeometryUpdateArgs {
+  windowId: number;
+  geometryId: number;
+  label?: string;
+  entries: GeometryPrimitiveEntry[];
+}
+
+/** Result payload for geometry update. */
+export interface CmdResultGeometryUpdate {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for disposing geometry. */
+export interface CmdGeometryDisposeArgs {
+  windowId: number;
+  geometryId: number;
+}
+
+/** Result payload for geometry dispose. */
+export interface CmdResultGeometryDispose {
+  success: boolean;
+  message: string;
+}
+
+/** Options for cube primitive generation. */
+export interface CubeOptions {
+  size: [number, number, number]; // Vec3 in Rust
+  subdivisions: number;
+}
+
+/** Options for plane primitive generation. */
+export interface PlaneOptions {
+  size: [number, number, number]; // Vec3 in Rust
+  subdivisions: number;
+}
+
+/** Options for sphere primitive generation. */
+export interface SphereOptions {
+  radius: number;
+  sectors: number;
+  stacks: number;
+}
+
+/** Options for cylinder primitive generation. */
+export interface CylinderOptions {
+  radius: number;
+  height: number;
+  sectors: number;
+}
+
+/** Options for torus primitive generation. */
+export interface TorusOptions {
+  majorRadius: number;
+  minorRadius: number;
+  majorSegments: number;
+  minorSegments: number;
+}
+
+/** Options for pyramid primitive generation. */
+export interface PyramidOptions {
+  size: [number, number, number]; // Vec3 in Rust
+  subdivisions: number;
+}
+
+/** Union of all primitive geometry options. */
+export type PrimitiveOptions =
+  | { type: 'cube'; content: CubeOptions }
+  | { type: 'plane'; content: PlaneOptions }
+  | { type: 'sphere'; content: SphereOptions }
+  | { type: 'cylinder'; content: CylinderOptions }
+  | { type: 'torus'; content: TorusOptions }
+  | { type: 'pyramid'; content: PyramidOptions };
+
+/** Command payload for creating a primitive geometry. */
+export interface CmdPrimitiveGeometryCreateArgs {
+  windowId: number;
+  geometryId: number;
+  label?: string;
+  shape: PrimitiveShape;
+  options: PrimitiveOptions;
+}
+
+/** Result payload for primitive geometry create. */
+export interface CmdResultPrimitiveGeometryCreate {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for listing geometry resources. */
+export interface CmdGeometryListArgs {}
+
+/** Result payload for geometry list. */
+export interface CmdResultGeometryList {
+  success: boolean;
+  message: string;
+  content: number[]; // List of geometry IDs
+}

package/src/types/cmds/gizmo.ts

@@ -0,0 +1,18 @@
+/** Command payload for drawing a debug line gizmo. */
+export interface CmdGizmoDrawLineArgs {
+  start: [number, number, number];
+  end: [number, number, number];
+  color: [number, number, number, number];
+}
+
+/** Command payload for drawing a debug AABB gizmo. */
+export interface CmdGizmoDrawAabbArgs {
+  min: [number, number, number];
+  max: [number, number, number];
+  color: [number, number, number, number];
+}
+
+/** Result payload for gizmo draw commands. */
+export interface CmdResultGizmoDraw {
+  status: number;
+}

package/src/types/cmds/index.ts

@@ -0,0 +1,231 @@
+import * as Sys from './system';
+import * as Win from './window';
+import * as Cam from './camera';
+import * as Mod from './model';
+import * as Lite from './light';
+import * as Mat from './material';
+import * as Tex from './texture';
+import * as Geo from './geometry';
+import * as Shad from './shadow';
+import * as Giz from './gizmo';
+import * as Env from './environment';
+
+export * from './system';
+export * from './window';
+export * from './camera';
+export * from './model';
+export * from './light';
+export * from './material';
+export * from './texture';
+export * from './geometry';
+export * from './shadow';
+export * from './gizmo';
+export * from './environment';
+
+/** Discriminated union of all core commands. */
+export type EngineCmd =
+  | { type: 'cmd-notification-send'; content: Sys.CmdNotificationSendArgs }
+  | { type: 'cmd-window-create'; content: Win.CmdWindowCreateArgs }
+  | { type: 'cmd-window-close'; content: Win.CmdWindowCloseArgs }
+  | { type: 'cmd-window-set-title'; content: Win.CmdWindowSetTitleArgs }
+  | { type: 'cmd-window-set-position'; content: Win.CmdWindowSetPositionArgs }
+  | { type: 'cmd-window-get-position'; content: Win.CmdWindowGetPositionArgs }
+  | { type: 'cmd-window-set-size'; content: Win.CmdWindowSetSizeArgs }
+  | { type: 'cmd-window-get-size'; content: Win.CmdWindowGetSizeArgs }
+  | {
+      type: 'cmd-window-get-outer-size';
+      content: Win.CmdWindowGetOuterSizeArgs;
+    }
+  | {
+      type: 'cmd-window-get-surface-size';
+      content: Win.CmdWindowGetSurfaceSizeArgs;
+    }
+  | { type: 'cmd-window-set-state'; content: Win.CmdWindowSetStateArgs }
+  | { type: 'cmd-window-get-state'; content: Win.CmdWindowGetStateArgs }
+  | { type: 'cmd-window-set-icon'; content: Win.CmdWindowSetIconArgs }
+  | {
+      type: 'cmd-window-set-decorations';
+      content: Win.CmdWindowSetDecorationsArgs;
+    }
+  | {
+      type: 'cmd-window-has-decorations';
+      content: Win.CmdWindowHasDecorationsArgs;
+    }
+  | { type: 'cmd-window-set-resizable'; content: Win.CmdWindowSetResizableArgs }
+  | { type: 'cmd-window-is-resizable'; content: Win.CmdWindowIsResizableArgs }
+  | {
+      type: 'cmd-window-request-attention';
+      content: Win.CmdWindowRequestAttentionArgs;
+    }
+  | { type: 'cmd-window-focus'; content: Win.CmdWindowFocusArgs }
+  | {
+      type: 'cmd-window-set-cursor-visible';
+      content: Win.CmdWindowSetCursorVisibleArgs;
+    }
+  | {
+      type: 'cmd-window-set-cursor-grab';
+      content: Win.CmdWindowSetCursorGrabArgs;
+    }
+  | {
+      type: 'cmd-window-set-cursor-icon';
+      content: Win.CmdWindowSetCursorIconArgs;
+    }
+  | { type: 'cmd-camera-create'; content: Cam.CmdCameraCreateArgs }
+  | { type: 'cmd-camera-update'; content: Cam.CmdCameraUpdateArgs }
+  | { type: 'cmd-camera-dispose'; content: Cam.CmdCameraDisposeArgs }
+  | { type: 'cmd-model-create'; content: Mod.CmdModelCreateArgs }
+  | { type: 'cmd-model-update'; content: Mod.CmdModelUpdateArgs }
+  | { type: 'cmd-model-dispose'; content: Mod.CmdModelDisposeArgs }
+  | { type: 'cmd-light-create'; content: Lite.CmdLightCreateArgs }
+  | { type: 'cmd-light-update'; content: Lite.CmdLightUpdateArgs }
+  | { type: 'cmd-light-dispose'; content: Lite.CmdLightDisposeArgs }
+  | { type: 'cmd-material-create'; content: Mat.CmdMaterialCreateArgs }
+  | { type: 'cmd-material-update'; content: Mat.CmdMaterialUpdateArgs }
+  | { type: 'cmd-material-dispose'; content: Mat.CmdMaterialDisposeArgs }
+  | {
+      type: 'cmd-texture-create-from-buffer';
+      content: Tex.CmdTextureCreateFromBufferArgs;
+    }
+  | {
+      type: 'cmd-texture-create-solid-color';
+      content: Tex.CmdTextureCreateSolidColorArgs;
+    }
+  | { type: 'cmd-texture-dispose'; content: Tex.CmdTextureDisposeArgs }
+  | { type: 'cmd-geometry-create'; content: Geo.CmdGeometryCreateArgs }
+  | { type: 'cmd-geometry-update'; content: Geo.CmdGeometryUpdateArgs }
+  | { type: 'cmd-geometry-dispose'; content: Geo.CmdGeometryDisposeArgs }
+  | {
+      type: 'cmd-primitive-geometry-create';
+      content: Geo.CmdPrimitiveGeometryCreateArgs;
+    }
+  | { type: 'cmd-environment-create'; content: Env.CmdEnvironmentCreateArgs }
+  | { type: 'cmd-environment-update'; content: Env.CmdEnvironmentUpdateArgs }
+  | { type: 'cmd-environment-dispose'; content: Env.CmdEnvironmentDisposeArgs }
+  | { type: 'cmd-shadow-configure'; content: Shad.CmdShadowConfigureArgs }
+  | { type: 'cmd-model-list'; content: Mod.CmdModelListArgs }
+  | { type: 'cmd-material-list'; content: Mat.CmdMaterialListArgs }
+  | { type: 'cmd-texture-list'; content: Tex.CmdTextureListArgs }
+  | { type: 'cmd-geometry-list'; content: Geo.CmdGeometryListArgs }
+  | { type: 'cmd-light-list'; content: Lite.CmdLightListArgs }
+  | { type: 'cmd-camera-list'; content: Cam.CmdCameraListArgs }
+  | { type: 'cmd-gizmo-draw-line'; content: Giz.CmdGizmoDrawLineArgs }
+  | { type: 'cmd-gizmo-draw-aabb'; content: Giz.CmdGizmoDrawAabbArgs };
+
+/** Discriminated union of all core command responses. */
+export type CommandResponse =
+  | { type: 'notification-send'; content: Sys.CmdResultNotificationSend }
+  | { type: 'window-create'; content: Win.CmdResultWindowCreate }
+  | { type: 'window-close'; content: Win.CmdResultWindowClose }
+  | { type: 'window-set-title'; content: Win.CmdResultWindowSetTitle }
+  | { type: 'window-set-position'; content: Win.CmdResultWindowSetPosition }
+  | { type: 'window-get-position'; content: Win.CmdResultWindowGetPosition }
+  | { type: 'window-set-size'; content: Win.CmdResultWindowSetSize }
+  | { type: 'window-get-size'; content: Win.CmdResultWindowGetSize }
+  | { type: 'window-get-outer-size'; content: Win.CmdResultWindowGetOuterSize }
+  | {
+      type: 'window-get-surface-size';
+      content: Win.CmdResultWindowGetSurfaceSize;
+    }
+  | { type: 'window-set-state'; content: Win.CmdResultWindowSetState }
+  | { type: 'window-get-state'; content: Win.CmdResultWindowGetState }
+  | { type: 'window-set-icon'; content: Win.CmdResultWindowSetIcon }
+  | {
+      type: 'window-set-decorations';
+      content: Win.CmdResultWindowSetDecorations;
+    }
+  | {
+      type: 'window-has-decorations';
+      content: Win.CmdResultWindowHasDecorations;
+    }
+  | { type: 'window-set-resizable'; content: Win.CmdResultWindowSetResizable }
+  | { type: 'window-is-resizable'; content: Win.CmdResultWindowIsResizable }
+  | {
+      type: 'window-request-attention';
+      content: Win.CmdResultWindowRequestAttention;
+    }
+  | { type: 'window-focus'; content: Win.CmdResultWindowFocus }
+  | {
+      type: 'window-set-cursor-visible';
+      content: Win.CmdResultWindowSetCursorVisible;
+    }
+  | {
+      type: 'window-set-cursor-grab';
+      content: Win.CmdResultWindowSetCursorGrab;
+    }
+  | {
+      type: 'window-set-cursor-icon';
+      content: Win.CmdResultWindowSetCursorIcon;
+    }
+  | { type: 'camera-create'; content: Cam.CmdResultCameraCreate }
+  | { type: 'camera-update'; content: Cam.CmdResultCameraUpdate }
+  | { type: 'camera-dispose'; content: Cam.CmdResultCameraDispose }
+  | { type: 'model-create'; content: Mod.CmdResultModelCreate }
+  | { type: 'model-update'; content: Mod.CmdResultModelUpdate }
+  | { type: 'model-dispose'; content: Mod.CmdResultModelDispose }
+  | { type: 'light-create'; content: Lite.CmdResultLightCreate }
+  | { type: 'light-update'; content: Lite.CmdResultLightUpdate }
+  | { type: 'light-dispose'; content: Lite.CmdResultLightDispose }
+  | { type: 'material-create'; content: Mat.CmdResultMaterialCreate }
+  | { type: 'material-update'; content: Mat.CmdResultMaterialUpdate }
+  | { type: 'material-dispose'; content: Mat.CmdResultMaterialDispose }
+  | {
+      type: 'texture-create-from-buffer';
+      content: Tex.CmdResultTextureCreateFromBuffer;
+    }
+  | {
+      type: 'texture-create-solid-color';
+      content: Tex.CmdResultTextureCreateSolidColor;
+    }
+  | { type: 'texture-dispose'; content: Tex.CmdResultTextureDispose }
+  | { type: 'geometry-create'; content: Geo.CmdResultGeometryCreate }
+  | { type: 'geometry-update'; content: Geo.CmdResultGeometryUpdate }
+  | { type: 'geometry-dispose'; content: Geo.CmdResultGeometryDispose }
+  | {
+      type: 'primitive-geometry-create';
+      content: Geo.CmdResultPrimitiveGeometryCreate;
+    }
+  | { type: 'environment-create'; content: Env.CmdResultEnvironment }
+  | { type: 'environment-update'; content: Env.CmdResultEnvironment }
+  | { type: 'environment-dispose'; content: Env.CmdResultEnvironment }
+  | { type: 'shadow-configure'; content: Shad.CmdResultShadowConfigure }
+  | { type: 'model-list'; content: Mod.CmdResultModelList }
+  | { type: 'material-list'; content: Mat.CmdResultMaterialList }
+  | { type: 'texture-list'; content: Tex.CmdResultTextureList }
+  | { type: 'geometry-list'; content: Geo.CmdResultGeometryList }
+  | { type: 'light-list'; content: Lite.CmdResultLightList }
+  | { type: 'camera-list'; content: Cam.CmdResultCameraList }
+  | { type: 'gizmo-draw-line'; content: Giz.CmdResultGizmoDraw }
+  | { type: 'gizmo-draw-aabb'; content: Giz.CmdResultGizmoDraw };
+
+/** Envelope used when batching commands to the core. */
+export interface EngineCmdEnvelope {
+  id: number;
+  type: EngineCmd['type'];
+  content: EngineCmd['content'];
+}
+
+/** Envelope used when decoding responses from the core. */
+export interface CommandResponseEnvelope {
+  id: number;
+  type: CommandResponse['type'];
+  content: CommandResponse['content'];
+}
+
+/** Batch of commands sent in a single tick. */
+export type EngineBatchCmds = EngineCmdEnvelope[];
+
+/** Batch of responses received from the core. */
+export type EngineBatchResponses = CommandResponseEnvelope[];
+
+/** Result codes returned by core entrypoints. */
+export enum VulframResult {
+  Success = 0,
+  UnknownError = 1,
+  NotInitialized = 2,
+  AlreadyInitialized = 3,
+  WrongThread = 4,
+  CmdInvalidMessagePackError = 5,
+  BufferNotFound = 6,
+  BufferIdCollision = 7,
+  InvalidUploadType = 8,
+}

package/src/types/cmds/light.ts

@@ -0,0 +1,69 @@
+import type { LightKind } from '../kinds';
+
+/** Command payload for creating a light. */
+export interface CmdLightCreateArgs {
+  windowId: number;
+  lightId: number;
+  label?: string;
+  kind?: LightKind;
+  position?: [number, number, number, number]; // Vec4
+  direction?: [number, number, number, number]; // Vec4
+  color?: [number, number, number, number]; // Vec4
+  groundColor?: [number, number, number, number]; // Vec4
+  intensity?: number;
+  range?: number;
+  spotInnerOuter?: [number, number]; // Vec2
+  layerMask: number;
+  castShadow?: boolean;
+}
+
+/** Result payload for light create. */
+export interface CmdResultLightCreate {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for updating a light. */
+export interface CmdLightUpdateArgs {
+  windowId: number;
+  lightId: number;
+  label?: string;
+  kind?: LightKind;
+  position?: [number, number, number, number];
+  direction?: [number, number, number, number];
+  color?: [number, number, number, number];
+  groundColor?: [number, number, number, number];
+  intensity?: number;
+  range?: number;
+  spotInnerOuter?: [number, number];
+  layerMask?: number;
+  castShadow?: boolean;
+}
+
+/** Result payload for light update. */
+export interface CmdResultLightUpdate {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for disposing a light. */
+export interface CmdLightDisposeArgs {
+  windowId: number;
+  lightId: number;
+}
+
+/** Result payload for light dispose. */
+export interface CmdResultLightDispose {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for listing lights. */
+export interface CmdLightListArgs {}
+
+/** Result payload for light list. */
+export interface CmdResultLightList {
+  success: boolean;
+  message: string;
+  content: number[]; // List of light IDs
+}

package/src/types/cmds/material.ts

@@ -0,0 +1,98 @@
+import type { MaterialKind, TransparencyMode, SamplerMode } from '../kinds';
+
+/** Standard material options. */
+export interface StandardOptions {
+  baseColor: [number, number, number, number];
+  surfaceType: TransparencyMode;
+  specColor?: [number, number, number, number] | null;
+  specPower?: number | null;
+  baseTexId?: number | null;
+  baseSampler?: SamplerMode | null;
+  specTexId?: number | null;
+  specSampler?: SamplerMode | null;
+  normalTexId?: number | null;
+  normalSampler?: SamplerMode | null;
+  toonRampTexId?: number | null;
+  toonRampSampler?: SamplerMode | null;
+  flags: number;
+  toonParams?: [number, number, number, number] | null;
+}
+
+/** PBR material options. */
+export interface PbrOptions {
+  baseColor: [number, number, number, number];
+  surfaceType: TransparencyMode;
+  emissiveColor: [number, number, number, number];
+  metallic: number;
+  roughness: number;
+  ao: number;
+  normalScale: number;
+  baseTexId: number;
+  baseSampler: SamplerMode;
+  normalTexId: number;
+  normalSampler: SamplerMode;
+  metallicRoughnessTexId: number;
+  metallicRoughnessSampler: SamplerMode;
+  emissiveTexId: number;
+  emissiveSampler: SamplerMode;
+  aoTexId: number;
+  aoSampler: SamplerMode;
+  flags: number;
+}
+
+/** Union of material option payloads. */
+export type MaterialOptions =
+  | { type: 'standard'; content: StandardOptions }
+  | { type: 'pbr'; content: PbrOptions };
+
+/** Command payload for creating a material. */
+export interface CmdMaterialCreateArgs {
+  windowId: number;
+  materialId: number;
+  label?: string;
+  kind: MaterialKind;
+  options?: MaterialOptions;
+}
+
+/** Result payload for material create. */
+export interface CmdResultMaterialCreate {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for updating a material. */
+export interface CmdMaterialUpdateArgs {
+  windowId: number;
+  materialId: number;
+  label?: string;
+  kind?: MaterialKind;
+  options?: MaterialOptions;
+}
+
+/** Result payload for material update. */
+export interface CmdResultMaterialUpdate {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for disposing a material. */
+export interface CmdMaterialDisposeArgs {
+  windowId: number;
+  materialId: number;
+}
+
+/** Result payload for material dispose. */
+export interface CmdResultMaterialDispose {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for listing materials. */
+export interface CmdMaterialListArgs {}
+
+/** Result payload for material list. */
+export interface CmdResultMaterialList {
+  success: boolean;
+  message: string;
+  content: number[]; // List of material IDs
+}

package/src/types/cmds/model.ts

@@ -0,0 +1,59 @@
+/** Command payload for creating a model. */
+export interface CmdModelCreateArgs {
+  windowId: number ;
+  modelId: number ;
+  label?: string;
+  geometryId: number;
+  materialId?: number;
+  transform: number[]; // Mat4
+  layerMask: number;
+  castShadow: boolean;
+  receiveShadow: boolean;
+}
+
+/** Result payload for model create. */
+export interface CmdResultModelCreate {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for updating a model. */
+export interface CmdModelUpdateArgs {
+  windowId: number ;
+  modelId: number ;
+  label?: string;
+  geometryId?: number;
+  materialId?: number;
+  transform?: number[];
+  layerMask?: number;
+  castShadow?: boolean;
+  receiveShadow?: boolean;
+}
+
+/** Result payload for model update. */
+export interface CmdResultModelUpdate {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for disposing a model. */
+export interface CmdModelDisposeArgs {
+  windowId: number ;
+  modelId: number ;
+}
+
+/** Result payload for model dispose. */
+export interface CmdResultModelDispose {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for listing models. */
+export interface CmdModelListArgs {}
+
+/** Result payload for model list. */
+export interface CmdResultModelList {
+  success: boolean;
+  message: string;
+  content: number[]; // List of model IDs
+}

package/src/types/cmds/shadow.ts

@@ -0,0 +1,22 @@
+/** Shadow rendering configuration. */
+export interface ShadowConfig {
+  tileResolution: number;
+  atlasTilesW: number;
+  atlasTilesH: number;
+  atlasLayers: number;
+  virtualGridSize: number;
+  smoothing: number;
+  normalBias: number;
+}
+
+/** Command payload for shadow configuration. */
+export interface CmdShadowConfigureArgs {
+  windowId: number;
+  config: ShadowConfig;
+}
+
+/** Result payload for shadow configuration. */
+export interface CmdResultShadowConfigure {
+  success: boolean;
+  message: string;
+}

package/src/types/cmds/system.ts

@@ -0,0 +1,15 @@
+import type { NotificationLevel } from '../kinds';
+
+/** Command payload for sending a notification. */
+export interface CmdNotificationSendArgs {
+  id?: string;
+  title: string;
+  body: string;
+  level: NotificationLevel;
+  timeout?: number;
+}
+
+/** Result payload for notification send. */
+export interface CmdResultNotificationSend {
+  success: boolean;
+}