@vulfram/engine 0.17.1-alpha → 0.19.3-alpha

package/src/helpers/raycast.ts

@@ -0,0 +1,442 @@
+import {
+  mat4,
+  vec3,
+  vec4,
+  type ReadonlyMat4,
+  type ReadonlyVec2,
+  type ReadonlyVec3,
+  type vec3 as Vec3,
+} from 'gl-matrix';
+
+export interface Ray3 {
+  origin: Vec3;
+  direction: Vec3;
+}
+
+export interface RayHit {
+  distance: number;
+  point: Vec3;
+}
+
+export interface PointerRaycastInput {
+  pointer: ReadonlyVec2;
+  viewMatrix: ReadonlyMat4;
+  projectionMatrix: ReadonlyMat4;
+  viewportSize: ReadonlyVec2;
+  viewportOrigin?: ReadonlyVec2;
+}
+
+export interface PointerRaycastWgpuInput extends PointerRaycastInput {}
+
+/**
+ * Builds a right-handed perspective projection in ZO depth range (0..1),
+ * with optional reverse-Z by swapping near/far.
+ *
+ * Matches glam::Mat4::perspective_rh semantics used by core.
+ */
+export function createPerspectiveRhZo(
+  fovYRadians: number,
+  aspect: number,
+  near: number,
+  far: number,
+): mat4 {
+  const f = 1 / Math.tan(fovYRadians / 2);
+  const out = mat4.create();
+
+  out[0] = f / Math.max(1e-8, aspect);
+  out[1] = 0;
+  out[2] = 0;
+  out[3] = 0;
+
+  out[4] = 0;
+  out[5] = f;
+  out[6] = 0;
+  out[7] = 0;
+
+  out[8] = 0;
+  out[9] = 0;
+  out[10] = far / (near - far);
+  out[11] = -1;
+
+  out[12] = 0;
+  out[13] = 0;
+  out[14] = (near * far) / (near - far);
+  out[15] = 0;
+
+  return out;
+}
+
+export interface PointerEventRaycastData {
+  position: ReadonlyVec2;
+  positionTarget?: ReadonlyVec2;
+  windowWidth?: number;
+  windowHeight?: number;
+  targetWidth?: number;
+  targetHeight?: number;
+}
+
+export interface PointerEventRaycastInput {
+  pointerEvent: PointerEventRaycastData;
+  viewMatrix: ReadonlyMat4;
+  projectionMatrix: ReadonlyMat4;
+  fallbackViewportSize?: ReadonlyVec2;
+  viewportOrigin?: ReadonlyVec2;
+}
+
+function pointOnRay(ray: Ray3, distance: number): Vec3 {
+  return vec3.fromValues(
+    ray.origin[0]! + ray.direction[0]! * distance,
+    ray.origin[1]! + ray.direction[1]! * distance,
+    ray.origin[2]! + ray.direction[2]! * distance,
+  );
+}
+
+/**
+ * Creates a world-space ray from pointer coordinates plus camera matrices.
+ *
+ * Returns `null` if the camera matrix cannot be inverted.
+ */
+export function createPointerRay(input: PointerRaycastInput): Ray3 | null {
+  const pointerX = input.pointer[0]!;
+  const pointerY = input.pointer[1]!;
+  const viewportWidth = input.viewportSize[0]!;
+  const viewportHeight = input.viewportSize[1]!;
+  const viewportSource = input.viewportOrigin;
+  const viewportX = viewportSource ? viewportSource[0]! : 0;
+  const viewportY = viewportSource ? viewportSource[1]! : 0;
+
+  if (viewportWidth <= 0 || viewportHeight <= 0) {
+    return null;
+  }
+
+  const normalizedX = ((pointerX - viewportX) / viewportWidth) * 2 - 1;
+  const normalizedY = 1 - ((pointerY - viewportY) / viewportHeight) * 2;
+
+  const viewProjection = mat4.multiply(
+    mat4.create(),
+    input.projectionMatrix,
+    input.viewMatrix,
+  );
+  const inverseViewProjection = mat4.invert(mat4.create(), viewProjection);
+  if (!inverseViewProjection) {
+    return null;
+  }
+
+  const nearClip = vec4.fromValues(normalizedX, normalizedY, -1, 1);
+  const farClip = vec4.fromValues(normalizedX, normalizedY, 1, 1);
+
+  const nearWorld4 = vec4.transformMat4(vec4.create(), nearClip, inverseViewProjection);
+  const farWorld4 = vec4.transformMat4(vec4.create(), farClip, inverseViewProjection);
+  if (nearWorld4[3] === 0 || farWorld4[3] === 0) {
+    return null;
+  }
+
+  const nearWorld = vec3.fromValues(
+    nearWorld4[0] / nearWorld4[3],
+    nearWorld4[1] / nearWorld4[3],
+    nearWorld4[2] / nearWorld4[3],
+  );
+  const farWorld = vec3.fromValues(
+    farWorld4[0] / farWorld4[3],
+    farWorld4[1] / farWorld4[3],
+    farWorld4[2] / farWorld4[3],
+  );
+
+  const direction = vec3.normalize(
+    vec3.create(),
+    vec3.subtract(vec3.create(), farWorld, nearWorld),
+  );
+
+  return {
+    origin: nearWorld,
+    direction,
+  };
+}
+
+/**
+ * Creates a world-space ray using WGPU reverse-Z clip conventions.
+ *
+ * This mirrors core picking logic:
+ * - NDC depth near=1 and far=0
+ * - direction corrected to follow camera forward when needed
+ */
+export function createPointerRayWgpuReverseZ(
+  input: PointerRaycastWgpuInput,
+): Ray3 | null {
+  const pointerX = input.pointer[0]!;
+  const pointerY = input.pointer[1]!;
+  const viewportWidth = input.viewportSize[0]!;
+  const viewportHeight = input.viewportSize[1]!;
+  const viewportSource = input.viewportOrigin;
+  const viewportX = viewportSource ? viewportSource[0]! : 0;
+  const viewportY = viewportSource ? viewportSource[1]! : 0;
+
+  if (viewportWidth <= 0 || viewportHeight <= 0) {
+    return null;
+  }
+
+  const normalizedX = ((pointerX - viewportX) / viewportWidth) * 2 - 1;
+  const normalizedY = 1 - ((pointerY - viewportY) / viewportHeight) * 2;
+
+  const viewProjection = mat4.multiply(
+    mat4.create(),
+    input.projectionMatrix,
+    input.viewMatrix,
+  );
+  const inverseViewProjection = mat4.invert(mat4.create(), viewProjection);
+  if (!inverseViewProjection) {
+    return null;
+  }
+
+  const nearClip = vec4.fromValues(normalizedX, normalizedY, 1, 1);
+  const farClip = vec4.fromValues(normalizedX, normalizedY, 0, 1);
+
+  const nearWorld4 = vec4.transformMat4(vec4.create(), nearClip, inverseViewProjection);
+  const farWorld4 = vec4.transformMat4(vec4.create(), farClip, inverseViewProjection);
+  if (nearWorld4[3] === 0 || farWorld4[3] === 0) {
+    return null;
+  }
+
+  const nearWorld = vec3.fromValues(
+    nearWorld4[0] / nearWorld4[3],
+    nearWorld4[1] / nearWorld4[3],
+    nearWorld4[2] / nearWorld4[3],
+  );
+  const farWorld = vec3.fromValues(
+    farWorld4[0] / farWorld4[3],
+    farWorld4[1] / farWorld4[3],
+    farWorld4[2] / farWorld4[3],
+  );
+
+  let direction = vec3.normalize(
+    vec3.create(),
+    vec3.subtract(vec3.create(), farWorld, nearWorld),
+  );
+
+  const inverseView = mat4.invert(mat4.create(), input.viewMatrix);
+  if (!inverseView) {
+    return null;
+  }
+  const origin4 = vec4.transformMat4(
+    vec4.create(),
+    vec4.fromValues(0, 0, 0, 1),
+    inverseView,
+  );
+  if (origin4[3] === 0) {
+    return null;
+  }
+  const origin = vec3.fromValues(
+    origin4[0] / origin4[3],
+    origin4[1] / origin4[3],
+    origin4[2] / origin4[3],
+  );
+
+  const forward4 = vec4.transformMat4(
+    vec4.create(),
+    vec4.fromValues(0, 0, -1, 0),
+    inverseView,
+  );
+  const cameraForward = vec3.normalize(
+    vec3.create(),
+    vec3.fromValues(forward4[0], forward4[1], forward4[2]),
+  );
+  if (vec3.squaredLength(cameraForward) > 1e-8 && vec3.dot(direction, cameraForward) < 0) {
+    direction = vec3.scale(vec3.create(), direction, -1);
+  }
+
+  if (vec3.squaredLength(direction) <= 1e-8) {
+    return null;
+  }
+
+  return { origin, direction };
+}
+
+/**
+ * Creates a world-space ray using pointer event dimensions from core.
+ *
+ * Priority:
+ * 1) target-space pointer + target size (most accurate for routed targets)
+ * 2) window-space pointer + window size
+ * 3) fallback viewport size (if provided)
+ *
+ * Uses WGPU reverse-Z conventions to match core picking.
+ */
+export function createPointerRayFromEvent(
+  input: PointerEventRaycastInput,
+): Ray3 | null {
+  const event = input.pointerEvent;
+  const targetWidth = event.targetWidth;
+  const targetHeight = event.targetHeight;
+  const windowWidth = event.windowWidth;
+  const windowHeight = event.windowHeight;
+
+  if (
+    event.positionTarget &&
+    typeof targetWidth === 'number' &&
+    typeof targetHeight === 'number' &&
+    targetWidth > 0 &&
+    targetHeight > 0
+  ) {
+    return createPointerRayWgpuReverseZ({
+      pointer: event.positionTarget,
+      viewMatrix: input.viewMatrix,
+      projectionMatrix: input.projectionMatrix,
+      viewportSize: [targetWidth, targetHeight],
+      viewportOrigin: [0, 0],
+    });
+  }
+
+  if (
+    typeof windowWidth === 'number' &&
+    typeof windowHeight === 'number' &&
+    windowWidth > 0 &&
+    windowHeight > 0
+  ) {
+    return createPointerRayWgpuReverseZ({
+      pointer: event.position,
+      viewMatrix: input.viewMatrix,
+      projectionMatrix: input.projectionMatrix,
+      viewportSize: [windowWidth, windowHeight],
+      viewportOrigin: input.viewportOrigin,
+    });
+  }
+
+  if (input.fallbackViewportSize) {
+    return createPointerRayWgpuReverseZ({
+      pointer: event.position,
+      viewMatrix: input.viewMatrix,
+      projectionMatrix: input.projectionMatrix,
+      viewportSize: input.fallbackViewportSize,
+      viewportOrigin: input.viewportOrigin,
+    });
+  }
+
+  return null;
+}
+
+/**
+ * Intersects a ray against a plane defined by one point and one normal.
+ *
+ * Returns `null` when the ray is parallel to the plane or the hit is behind the ray.
+ */
+export function intersectRayPlane(
+  ray: Ray3,
+  planePoint: ReadonlyVec3,
+  planeNormal: ReadonlyVec3,
+): RayHit | null {
+  const origin = vec3.fromValues(ray.origin[0], ray.origin[1], ray.origin[2]);
+  const direction = vec3.fromValues(ray.direction[0], ray.direction[1], ray.direction[2]);
+  const normal = vec3.normalize(
+    vec3.create(),
+    vec3.fromValues(planeNormal[0], planeNormal[1], planeNormal[2]),
+  );
+  const point = vec3.fromValues(planePoint[0], planePoint[1], planePoint[2]);
+
+  const denominator = vec3.dot(direction, normal);
+  if (Math.abs(denominator) < 1e-6) {
+    return null;
+  }
+
+  const distance =
+    vec3.dot(vec3.subtract(vec3.create(), point, origin), normal) / denominator;
+  if (distance < 0) {
+    return null;
+  }
+
+  return {
+    distance,
+    point: pointOnRay(ray, distance),
+  };
+}
+
+/**
+ * Intersects a ray with a sphere and returns the closest hit in front of the ray origin.
+ */
+export function intersectRaySphere(
+  ray: Ray3,
+  center: ReadonlyVec3,
+  radius: number,
+): RayHit | null {
+  const origin = vec3.fromValues(ray.origin[0], ray.origin[1], ray.origin[2]);
+  const direction = vec3.fromValues(ray.direction[0], ray.direction[1], ray.direction[2]);
+  const sphereCenter = vec3.fromValues(center[0], center[1], center[2]);
+
+  const oc = vec3.subtract(vec3.create(), origin, sphereCenter);
+  const a = vec3.dot(direction, direction);
+  const b = 2 * vec3.dot(oc, direction);
+  const c = vec3.dot(oc, oc) - radius * radius;
+  const discriminant = b * b - 4 * a * c;
+
+  if (discriminant < 0) {
+    return null;
+  }
+
+  const sqrtDiscriminant = Math.sqrt(discriminant);
+  const t0 = (-b - sqrtDiscriminant) / (2 * a);
+  const t1 = (-b + sqrtDiscriminant) / (2 * a);
+
+  const distance = t0 >= 0 ? t0 : t1 >= 0 ? t1 : -1;
+  if (distance < 0) {
+    return null;
+  }
+
+  return {
+    distance,
+    point: pointOnRay(ray, distance),
+  };
+}
+
+/**
+ * Intersects a ray with an axis-aligned bounding box.
+ */
+export function intersectRayAabb(
+  ray: Ray3,
+  min: ReadonlyVec3,
+  max: ReadonlyVec3,
+): RayHit | null {
+  const origin = ray.origin;
+  const direction = ray.direction;
+
+  let tMin = -Infinity;
+  let tMax = Infinity;
+
+  const axes = [0, 1, 2] as const;
+  for (const axis of axes) {
+    const o = origin[axis]!;
+    const d = direction[axis]!;
+    const minAxis = min[axis]!;
+    const maxAxis = max[axis]!;
+
+    if (Math.abs(d) < 1e-8) {
+      if (o < minAxis || o > maxAxis) {
+        return null;
+      }
+      continue;
+    }
+
+    const invD = 1 / d;
+    let t0 = (minAxis - o) * invD;
+    let t1 = (maxAxis - o) * invD;
+    if (t0 > t1) {
+      const tmp = t0;
+      t0 = t1;
+      t1 = tmp;
+    }
+
+    tMin = Math.max(tMin, t0);
+    tMax = Math.min(tMax, t1);
+    if (tMax < tMin) {
+      return null;
+    }
+  }
+
+  const distance = tMin >= 0 ? tMin : tMax >= 0 ? tMax : -1;
+  if (distance < 0) {
+    return null;
+  }
+
+  return {
+    distance,
+    point: pointOnRay(ray, distance),
+  };
+}

package/src/types/cmds/geometry.ts

@@ -8,7 +8,7 @@ export type GeometryPrimitiveType =
   | 'normal'
   | 'tangent'
   | 'color'
-  | 'uv'
+  | 'u-v'
   | 'skin-joints'
   | 'skin-weights';
 
@@ -19,7 +19,7 @@ export const GeometryPrimitiveType = {
   Normal: 'normal' as const,
   Tangent: 'tangent' as const,
   Color: 'color' as const,
-  UV: 'uv' as const,
+  UV: 'u-v' as const,
   SkinJoints: 'skin-joints' as const,
   SkinWeights: 'skin-weights' as const,
 };

package/src/types/cmds/index.ts

@@ -3,6 +3,7 @@ import * as Cam from './camera';
 import * as Env from './environment';
 import * as Geo from './geometry';
 import * as Giz from './gizmo';
+import * as Input from './input';
 import * as Lite from './light';
 import * as Mat from './material';
 import * as Mod from './model';
@@ -18,6 +19,7 @@ export * from './camera';
 export * from './environment';
 export * from './geometry';
 export * from './gizmo';
+export * from './input';
 export * from './light';
 export * from './material';
 export * from './model';
@@ -44,11 +46,27 @@ export type EngineCmd =
       type: 'cmd-system-diagnostics-set';
       content: Sys.CmdSystemDiagnosticsSetArgs;
     }
+  | {
+      type: 'cmd-system-build-version-get';
+      content: Sys.CmdSystemBuildVersionGetArgs;
+    }
   | { type: 'cmd-window-create'; content: Win.CmdWindowCreateArgs }
   | { type: 'cmd-window-close'; content: Win.CmdWindowCloseArgs }
   | { type: 'cmd-window-measurement'; content: Win.CmdWindowMeasurementArgs }
   | { type: 'cmd-window-cursor'; content: Win.CmdWindowCursorArgs }
   | { type: 'cmd-window-state'; content: Win.CmdWindowStateArgs }
+  | {
+      type: 'cmd-input-target-listener-upsert';
+      content: Input.CmdInputTargetListenerUpsertArgs;
+    }
+  | {
+      type: 'cmd-input-target-listener-dispose';
+      content: Input.CmdInputTargetListenerDisposeArgs;
+    }
+  | {
+      type: 'cmd-input-target-listener-list';
+      content: Input.CmdInputTargetListenerListArgs;
+    }
   | {
       type: 'cmd-upload-buffer-discard-all';
       content: Sys.CmdUploadBufferDiscardAllArgs;
@@ -116,6 +134,10 @@ export type EngineCmd =
   | { type: 'cmd-realm-create'; content: Realm.CmdRealmCreateArgs }
   | { type: 'cmd-realm-dispose'; content: Realm.CmdRealmDisposeArgs }
   | { type: 'cmd-target-upsert'; content: Target.CmdTargetUpsertArgs }
+  | {
+      type: 'cmd-target-measurement';
+      content: Target.CmdTargetMeasurementArgs;
+    }
   | { type: 'cmd-target-dispose'; content: Target.CmdTargetDisposeArgs }
   | {
       type: 'cmd-target-layer-upsert';
@@ -168,11 +190,27 @@ export type CommandResponse =
       type: 'system-diagnostics-set';
       content: Sys.CmdResultSystemDiagnosticsSet;
     }
+  | {
+      type: 'system-build-version-get';
+      content: Sys.CmdResultSystemBuildVersionGet;
+    }
   | { type: 'window-create'; content: Win.CmdResultWindowCreate }
   | { type: 'window-close'; content: Win.CmdResultWindowClose }
   | { type: 'window-measurement'; content: Win.CmdResultWindowMeasurement }
   | { type: 'window-cursor'; content: Win.CmdResultWindowCursor }
   | { type: 'window-state'; content: Win.CmdResultWindowState }
+  | {
+      type: 'input-target-listener-upsert';
+      content: Input.CmdResultInputTargetListenerUpsert;
+    }
+  | {
+      type: 'input-target-listener-dispose';
+      content: Input.CmdResultInputTargetListenerDispose;
+    }
+  | {
+      type: 'input-target-listener-list';
+      content: Input.CmdResultInputTargetListenerList;
+    }
   | {
       type: 'upload-buffer-discard-all';
       content: Sys.CmdResultUploadBufferDiscardAll;
@@ -240,6 +278,10 @@ export type CommandResponse =
   | { type: 'realm-create'; content: Realm.CmdResultRealmCreate }
   | { type: 'realm-dispose'; content: Realm.CmdResultRealmDispose }
   | { type: 'target-upsert'; content: Target.CmdResultTargetUpsert }
+  | {
+      type: 'target-measurement';
+      content: Target.CmdResultTargetMeasurement;
+    }
   | { type: 'target-dispose'; content: Target.CmdResultTargetDispose }
   | {
       type: 'target-layer-upsert';

package/src/types/cmds/input.ts

@@ -0,0 +1,39 @@
+export interface CmdInputTargetListenerUpsertArgs {
+  listenerId: number;
+  targetId: number;
+  enabled?: boolean;
+  events?: string[];
+  samplePercent?: number;
+}
+
+export interface CmdResultInputTargetListenerUpsert {
+  success: boolean;
+  message: string;
+}
+
+export interface CmdInputTargetListenerDisposeArgs {
+  listenerId: number;
+}
+
+export interface CmdResultInputTargetListenerDispose {
+  success: boolean;
+  message: string;
+}
+
+export interface CmdInputTargetListenerListArgs {
+  targetId?: number;
+}
+
+export interface InputTargetListenerSnapshot {
+  listenerId: number;
+  targetId: number;
+  enabled: boolean;
+  events: string[];
+  samplePercent: number;
+}
+
+export interface CmdResultInputTargetListenerList {
+  success: boolean;
+  message: string;
+  listeners: InputTargetListenerSnapshot[];
+}

package/src/types/cmds/material.ts

@@ -28,16 +28,16 @@ export interface PbrOptions {
   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;
+  baseTexId?: number | null;
+  baseSampler?: SamplerMode | null;
+  normalTexId?: number | null;
+  normalSampler?: SamplerMode | null;
+  metallicRoughnessTexId?: number | null;
+  metallicRoughnessSampler?: SamplerMode | null;
+  emissiveTexId?: number | null;
+  emissiveSampler?: SamplerMode | null;
+  aoTexId?: number | null;
+  aoSampler?: SamplerMode | null;
   flags: number;
 }
 

package/src/types/cmds/realm.ts

@@ -2,8 +2,6 @@ export type RealmKind = 'three-d' | 'two-d';
 
 export interface CmdRealmCreateArgs {
   kind: RealmKind;
-  outputSurfaceId?: number;
-  hostWindowId?: number;
   importance?: number;
   cachePolicy?: number;
   flags?: number;

package/src/types/cmds/system.ts

@@ -33,6 +33,16 @@ export interface CmdResultSystemDiagnosticsSet {
   message: string;
 }
 
+/** Command payload for retrieving core build version. */
+export interface CmdSystemBuildVersionGetArgs {}
+
+/** Result payload for build version query. */
+export interface CmdResultSystemBuildVersionGet {
+  success: boolean;
+  message: string;
+  buildVersion: string;
+}
+
 /** Command payload for discarding all pending upload buffers. */
 export interface CmdUploadBufferDiscardAllArgs {}
 

package/src/types/cmds/target.ts

@@ -49,6 +49,20 @@ export interface CmdResultTargetUpsert {
   message: string;
 }
 
+export interface CmdTargetMeasurementArgs {
+  targetId: number;
+  getSize?: boolean;
+  getWindowSize?: boolean;
+}
+
+export interface CmdResultTargetMeasurement {
+  success: boolean;
+  message: string;
+  size?: [number, number];
+  windowSize?: [number, number];
+  sourceKind?: string;
+}
+
 export interface CmdTargetDisposeArgs {
   targetId: number;
 }

package/src/types/events/keyboard.ts

@@ -120,8 +120,8 @@ export enum KeyCode {
   ControlLeft = 55,
   ControlRight = 56,
   Enter = 57,
-  SuperLeft = 58,
-  SuperRight = 59,
+  MetaLeft = 58,
+  MetaRight = 59,
   ShiftLeft = 60,
   ShiftRight = 61,
   Space = 62,