@vulfram/engine 0.14.8-alpha → 0.19.2-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/index.ts

@@ -1,6 +1,35 @@
 export { EngineError } from './engine/errors';
-export * from './engine/api';
 export * from './engine/ecs';
+export * as Mount from './engine/world/mount';
+export * as World3D from './engine/world/world3d';
+export * as WorldUI from './engine/world/world-ui';
+export {
+  disposeEngine,
+  initEngine,
+  registerComponent,
+  registerSystem,
+  tick,
+  uploadBuffer,
+} from './engine/api';
+export {
+  closeWindow,
+  createWindow,
+  focusWindow,
+  requestAttention,
+  updateWindow,
+} from './engine/window/manager';
+export type {
+  CommandId,
+  EntityId,
+  GeometryId,
+  MaterialId,
+  TargetId,
+  TextureId,
+  WindowId,
+  World3DId,
+  WorldId,
+  WorldUIId,
+} from './engine/world/types';
 export * as Types from './types';
 export type {
   BufferResult,

package/src/mount.ts

@@ -0,0 +1,2 @@
+export * from './engine/world/mount';
+export type { TargetId, WindowId, WorldId } from './engine/world/types';

package/src/types/cmds/audio.ts

@@ -19,13 +19,13 @@ export interface CmdAudioListenerUpdateArgs {
 
 /** Command payload for binding the listener to a model. */
 export interface CmdAudioListenerCreateArgs {
-  windowId: number;
+  realmId: number;
   modelId: number;
 }
 
 /** Command payload for disposing the listener binding. */
 export interface CmdAudioListenerDisposeArgs {
-  windowId: number;
+  realmId: number;
 }
 
 export interface CmdResultAudioListenerCreate {
@@ -43,30 +43,26 @@ export interface CmdResultAudioListenerUpdate {
   message: string;
 }
 
-/** Command payload for creating an audio resource from uploaded bytes. */
-export interface CmdAudioResourceCreateArgs {
+/** Upsert payload accepted by the core (`create` or `update`). */
+export type CmdAudioListenerUpsertArgs =
+  | CmdAudioListenerCreateArgs
+  | CmdAudioListenerUpdateArgs;
+
+/** Backward-compatible aliases. */
+export type CmdResultAudioListenerUpsert = CmdResultAudioListenerUpdate;
+
+/** Command payload for creating/updating an audio resource from uploaded bytes. */
+export interface CmdAudioResourceUpsertArgs {
   resourceId: number;
   bufferId: number;
   totalBytes?: number;
   offsetBytes?: number;
 }
 
-export interface CmdResultAudioResourceCreate {
+export interface CmdResultAudioResourceUpsert {
   success: boolean;
   message: string;
   pending: boolean;
-}
-
-/** Command payload for pushing a stream chunk. */
-export interface CmdAudioResourcePushArgs {
-  resourceId: number;
-  bufferId: number;
-  offsetBytes: number;
-}
-
-export interface CmdResultAudioResourcePush {
-  success: boolean;
-  message: string;
   receivedBytes: number;
   totalBytes: number;
   complete: boolean;
@@ -74,7 +70,7 @@ export interface CmdResultAudioResourcePush {
 
 /** Command payload for creating a source bound to a model. */
 export interface CmdAudioSourceCreateArgs {
-  windowId: number;
+  realmId: number;
   sourceId: number;
   modelId: number;
   position: [number, number, number];
@@ -93,12 +89,14 @@ export interface CmdResultAudioSourceCreate {
 /** Command payload for updating source params. */
 export interface CmdAudioSourceUpdateArgs {
   sourceId: number;
-  position: [number, number, number];
-  velocity: [number, number, number];
-  orientation: [number, number, number, number];
-  gain: number;
-  pitch: number;
-  spatial: AudioSpatialParams;
+  realmId?: number;
+  modelId?: number;
+  position?: [number, number, number];
+  velocity?: [number, number, number];
+  orientation?: [number, number, number, number];
+  gain?: number;
+  pitch?: number;
+  spatial?: AudioSpatialParams;
 }
 
 export interface CmdResultAudioSourceUpdate {
@@ -106,59 +104,86 @@ export interface CmdResultAudioSourceUpdate {
   message: string;
 }
 
-/** Command payload for starting playback. */
-export interface CmdAudioSourcePlayArgs {
+/** Upsert payload accepted by the core (`create` or `update`). */
+export type CmdAudioSourceUpsertArgs =
+  | CmdAudioSourceCreateArgs
+  | CmdAudioSourceUpdateArgs;
+
+/** Backward-compatible aliases. */
+export type CmdResultAudioSourceUpsert = CmdResultAudioSourceUpdate;
+
+export type AudioSourceTransportAction = 'play' | 'pause' | 'stop';
+
+/** Command payload for playback transport control. */
+export interface CmdAudioSourceTransportArgs {
   sourceId: number;
-  resourceId: number;
+  action: AudioSourceTransportAction;
+  resourceId?: number;
   timelineId?: number;
-  intensity: number;
+  intensity?: number;
   delayMs?: number;
-  mode: AudioPlayMode;
+  mode?: AudioPlayMode;
 }
 
-export interface CmdResultAudioSourcePlay {
+export interface CmdResultAudioSourceTransport {
   success: boolean;
   message: string;
 }
 
-/** Command payload for pausing playback. */
-export interface CmdAudioSourcePauseArgs {
+/** Command payload for disposing a source. */
+export interface CmdAudioSourceDisposeArgs {
   sourceId: number;
-  timelineId?: number;
 }
 
-export interface CmdResultAudioSourcePause {
+export interface CmdResultAudioSourceDispose {
   success: boolean;
   message: string;
 }
 
-/** Command payload for stopping playback. */
-export interface CmdAudioSourceStopArgs {
-  sourceId: number;
-  timelineId?: number;
+/** Command payload for disposing an audio resource. */
+export interface CmdAudioResourceDisposeArgs {
+  resourceId: number;
 }
 
-export interface CmdResultAudioSourceStop {
+export interface CmdResultAudioResourceDispose {
   success: boolean;
   message: string;
 }
 
-/** Command payload for disposing a source. */
-export interface CmdAudioSourceDisposeArgs {
-  sourceId: number;
+/** Command payload for listing current audio runtime state. */
+export interface CmdAudioStateGetArgs {
+  includeListener?: boolean;
+  includeSources?: boolean;
+  includeStreams?: boolean;
 }
 
-export interface CmdResultAudioSourceDispose {
-  success: boolean;
-  message: string;
+export interface AudioListenerBindingState {
+  realmId: number;
+  modelId: number;
 }
 
-/** Command payload for disposing an audio resource. */
-export interface CmdAudioResourceDisposeArgs {
+export interface AudioSourceStateEntry {
+  sourceId: number;
+  realmId?: number;
+  modelId?: number;
+  position: [number, number, number];
+  velocity: [number, number, number];
+  orientation: [number, number, number, number];
+  gain: number;
+  pitch: number;
+}
+
+export interface AudioStreamStateEntry {
   resourceId: number;
+  receivedBytes: number;
+  totalBytes: number;
+  complete: boolean;
 }
 
-export interface CmdResultAudioResourceDispose {
+export interface CmdResultAudioStateGet {
   success: boolean;
   message: string;
+  listener?: AudioListenerBindingState;
+  sources: AudioSourceStateEntry[];
+  streams: AudioStreamStateEntry[];
 }