@vulfram/engine 0.17.1-alpha → 0.19.3-alpha

package/src/engine/world/world3d.ts

@@ -15,11 +15,22 @@ import type {
   CmdAudioSourceCreateArgs,
   CmdAudioSourceTransportArgs,
 } from '../../types/cmds/audio';
+import type {
+  CmdInputTargetListenerDisposeArgs,
+  CmdInputTargetListenerListArgs,
+  CmdInputTargetListenerUpsertArgs,
+} from '../../types/cmds/input';
 import type { EnvironmentConfig } from '../../types/cmds/environment';
-import type { CmdGizmoDrawAabbArgs, CmdGizmoDrawLineArgs } from '../../types/cmds/gizmo';
+import type {
+  CmdGizmoDrawAabbArgs,
+  CmdGizmoDrawLineArgs,
+} from '../../types/cmds/gizmo';
 import type { CmdPoseUpdateArgs } from '../../types/cmds/model';
 import type { ShadowConfig } from '../../types/cmds/shadow';
+import type { CmdTargetMeasurementArgs } from '../../types/cmds/target';
 import type { NotificationLevel } from '../../types/kinds';
+export { KeyCode } from '../../types/events/keyboard';
+import type { SystemEvent } from '../../types/events/system';
 import {
   audioListenerUpdate as audioListenerUpdateRaw,
   audioResourceCreate as audioResourceCreateRaw,
@@ -35,12 +46,31 @@ import {
   createModel as createModelRaw,
   createTexture as createTextureRaw,
   createTag as createTagRaw,
+  disposeGeometry as disposeGeometryRaw,
+  disposeMaterial as disposeMaterialRaw,
+  disposeTexture as disposeTextureRaw,
   drawGizmoAabb as drawGizmoAabbRaw,
   drawGizmoLine as drawGizmoLineRaw,
+  disposeInputTargetListener as disposeInputTargetListenerRaw,
+  getSystemEvents as getSystemEventsRaw,
+  getImeCommitText as getImeCommitTextRaw,
+  getImeCursorRange as getImeCursorRangeRaw,
+  getImePreeditText as getImePreeditTextRaw,
   getModelId as getModelIdRaw,
+  getPointerDelta as getPointerDeltaRaw,
+  getPointerPosition as getPointerPositionRaw,
+  getPointerTargetSize as getPointerTargetSizeRaw,
+  getPointerTargetDelta as getPointerTargetDeltaRaw,
+  getPointerTargetId as getPointerTargetIdRaw,
+  getPointerTargetPosition as getPointerTargetPositionRaw,
+  getPointerTargetUv as getPointerTargetUvRaw,
+  getPointerWindowSize as getPointerWindowSizeRaw,
   getWindowSize as getWindowSizeRaw,
   getWorldRealmId as getWorldRealmIdRaw,
+  isImeEnabled as isImeEnabledRaw,
   isKeyPressed as isKeyPressedRaw,
+  isPointerButtonJustPressed as isPointerButtonJustPressedRaw,
+  isPointerButtonPressed as isPointerButtonPressedRaw,
   isWindowCloseRequested as isWindowCloseRequestedRaw,
   listCameras as listCamerasRaw,
   listGeometries as listGeometriesRaw,
@@ -48,10 +78,13 @@ import {
   listMaterials as listMaterialsRaw,
   listModels as listModelsRaw,
   listTextures as listTexturesRaw,
+  measureTarget as measureTargetRaw,
   poseUpdate as poseUpdateRaw,
   removeEntity as removeEntityRaw,
   sendNotification as sendNotificationRaw,
   setParent as setParentRaw,
+  upsertInputTargetListener as upsertInputTargetListenerRaw,
+  listInputTargetListeners as listInputTargetListenersRaw,
   updateTransform as updateTransformRaw,
 } from './entities';
 import type {
@@ -73,14 +106,16 @@ import {
 } from './types';
 
 export type Create3DWorldOptions = {
-  outputSurfaceId?: number;
   importance?: number;
   cachePolicy?: number;
   flags?: number;
 };
 
-type Create3DAudioSourceArgs = Omit<CmdAudioSourceCreateArgs, 'realmId' | 'modelId'>
-  & ({ modelId: number } | { entityId: EntityId });
+type Create3DAudioSourceArgs = Omit<
+  CmdAudioSourceCreateArgs,
+  'realmId' | 'modelId'
+> &
+  ({ modelId: number } | { entityId: EntityId });
 
 /**
  * Creates a 3D world.
@@ -103,72 +138,148 @@ export function remove3DEntity(worldId: World3DId, entityId: EntityId): void {
 }
 
 /** Upserts camera component intent for an entity in a 3D world. */
-export function create3DCamera(worldId: World3DId, entityId: EntityId, props: CameraProps): void {
+export function create3DCamera(
+  worldId: World3DId,
+  entityId: EntityId,
+  props: CameraProps,
+): void {
   createCameraRaw(asWorldNumber(worldId), entityId as number, props);
 }
 
 /** Upserts light component intent for an entity in a 3D world. */
-export function create3DLight(worldId: World3DId, entityId: EntityId, props: LightProps): void {
+export function create3DLight(
+  worldId: World3DId,
+  entityId: EntityId,
+  props: LightProps,
+): void {
   createLightRaw(asWorldNumber(worldId), entityId as number, props);
 }
 
 /** Upserts model component intent for an entity in a 3D world. */
-export function create3DModel(worldId: World3DId, entityId: EntityId, props: ModelProps): void {
+export function create3DModel(
+  worldId: World3DId,
+  entityId: EntityId,
+  props: ModelProps,
+): void {
   createModelRaw(asWorldNumber(worldId), entityId as number, props);
 }
 
 /** Upserts transform component intent for an entity in a 3D world. */
-export function update3DTransform(worldId: World3DId, entityId: EntityId, props: TransformProps): void {
+export function update3DTransform(
+  worldId: World3DId,
+  entityId: EntityId,
+  props: TransformProps,
+): void {
   updateTransformRaw(asWorldNumber(worldId), entityId as number, props);
 }
 
 /** Attaches or updates a tag component in a 3D world. */
-export function create3DTag(worldId: World3DId, entityId: EntityId, props: TagProps): void {
+export function create3DTag(
+  worldId: World3DId,
+  entityId: EntityId,
+  props: TagProps,
+): void {
   createTagRaw(asWorldNumber(worldId), entityId as number, props);
 }
 
 /** Sets parent-child relationship between entities. */
-export function set3DParent(worldId: World3DId, childEntityId: EntityId, parentEntityId: EntityId | null): void {
-  setParentRaw(asWorldNumber(worldId), childEntityId as number, parentEntityId as number | null);
+export function set3DParent(
+  worldId: World3DId,
+  childEntityId: EntityId,
+  parentEntityId: EntityId | null,
+): void {
+  setParentRaw(
+    asWorldNumber(worldId),
+    childEntityId as number,
+    parentEntityId as number | null,
+  );
 }
 
 /** Creates a material resource and returns its typed id. */
-export function create3DMaterial(worldId: World3DId, props: MaterialProps): MaterialId {
+export function create3DMaterial(
+  worldId: World3DId,
+  props: MaterialProps,
+): MaterialId {
   return asMaterialId(createMaterialRaw(asWorldNumber(worldId), props));
 }
 
 /** Creates a geometry resource and returns its typed id. */
-export function create3DGeometry(worldId: World3DId, props: GeometryProps): GeometryId {
+export function create3DGeometry(
+  worldId: World3DId,
+  props: GeometryProps,
+): GeometryId {
   return asGeometryId(createGeometryRaw(asWorldNumber(worldId), props));
 }
 
 /** Creates a texture resource and returns its typed id. */
-export function create3DTexture(worldId: World3DId, props: TextureProps): TextureId {
+export function create3DTexture(
+  worldId: World3DId,
+  props: TextureProps,
+): TextureId {
   return asTextureId(createTextureRaw(asWorldNumber(worldId), props));
 }
 
+/** Disposes a material resource from a 3D world. */
+export function dispose3DMaterial(
+  worldId: World3DId,
+  materialId: MaterialId,
+): void {
+  disposeMaterialRaw(asWorldNumber(worldId), materialId as number);
+}
+
+/** Disposes a geometry resource from a 3D world. */
+export function dispose3DGeometry(
+  worldId: World3DId,
+  geometryId: GeometryId,
+): void {
+  disposeGeometryRaw(asWorldNumber(worldId), geometryId as number);
+}
+
+/** Disposes a texture resource from a 3D world. */
+export function dispose3DTexture(
+  worldId: World3DId,
+  textureId: TextureId,
+): void {
+  disposeTextureRaw(asWorldNumber(worldId), textureId as number);
+}
+
 /** Configures environment/post-processing for a 3D world. */
-export function configure3DEnvironment(worldId: World3DId, config: EnvironmentConfig): void {
+export function configure3DEnvironment(
+  worldId: World3DId,
+  config: EnvironmentConfig,
+): void {
   configureEnvironmentRaw(asWorldNumber(worldId), config);
 }
 
 /** Configures shadows for a 3D world. */
-export function configure3DShadows(worldId: World3DId, config: ShadowConfig): void {
+export function configure3DShadows(
+  worldId: World3DId,
+  config: ShadowConfig,
+): void {
   configureShadowsRaw(asWorldNumber(worldId), config);
 }
 
 /** Draws a debug line gizmo. */
-export function draw3DGizmoLine(worldId: World3DId, args: CmdGizmoDrawLineArgs): void {
+export function draw3DGizmoLine(
+  worldId: World3DId,
+  args: CmdGizmoDrawLineArgs,
+): void {
   drawGizmoLineRaw(asWorldNumber(worldId), args);
 }
 
 /** Draws a debug axis-aligned bounding box gizmo. */
-export function draw3DGizmoAabb(worldId: World3DId, args: CmdGizmoDrawAabbArgs): void {
+export function draw3DGizmoAabb(
+  worldId: World3DId,
+  args: CmdGizmoDrawAabbArgs,
+): void {
   drawGizmoAabbRaw(asWorldNumber(worldId), args);
 }
 
 /** Updates pose data for XR/trackers. */
-export function update3DPose(worldId: World3DId, args: CmdPoseUpdateArgs): CommandId {
+export function update3DPose(
+  worldId: World3DId,
+  args: CmdPoseUpdateArgs,
+): CommandId {
   return asCommandId(poseUpdateRaw(asWorldNumber(worldId), args));
 }
 
@@ -202,11 +313,86 @@ export function list3DCameras(worldId: World3DId): CommandId {
   return asCommandId(listCamerasRaw(asWorldNumber(worldId)));
 }
 
+/** Requests target measurement for this world context. */
+export function measure3DTarget(
+  worldId: World3DId,
+  args: CmdTargetMeasurementArgs,
+): CommandId {
+  return asCommandId(measureTargetRaw(asWorldNumber(worldId), args));
+}
+
+/** Creates or updates a pointer listener routed by target id. */
+export function upsert3DInputTargetListener(
+  worldId: World3DId,
+  args: CmdInputTargetListenerUpsertArgs,
+): CommandId {
+  return asCommandId(
+    upsertInputTargetListenerRaw(asWorldNumber(worldId), args),
+  );
+}
+
+/** Disposes a pointer listener routed by target id. */
+export function dispose3DInputTargetListener(
+  worldId: World3DId,
+  args: CmdInputTargetListenerDisposeArgs,
+): CommandId {
+  return asCommandId(
+    disposeInputTargetListenerRaw(asWorldNumber(worldId), args),
+  );
+}
+
+/** Requests current pointer listener list from core. */
+export function list3DInputTargetListeners(
+  worldId: World3DId,
+  args: CmdInputTargetListenerListArgs = {},
+): CommandId {
+  return asCommandId(
+    listInputTargetListenersRaw(asWorldNumber(worldId), args),
+  );
+}
+
+/**
+ * Returns system events filtered to input-target-listener-event.
+ */
+export function get3DTargetPointerEvents(
+  worldId: World3DId,
+): Extract<SystemEvent, { event: 'input-target-listener-event' }>[] {
+  const events = getSystemEventsRaw(asWorldNumber(worldId));
+  return events.filter(
+    (
+      event,
+    ): event is Extract<SystemEvent, { event: 'input-target-listener-event' }> =>
+      event.event === 'input-target-listener-event',
+  );
+}
+
 /** Returns true while a key is pressed in this world input state. */
 export function is3DKeyPressed(worldId: World3DId, keyCode: number): boolean {
   return isKeyPressedRaw(asWorldNumber(worldId), keyCode);
 }
 
+/** Returns true while IME composition is active in this world. */
+export function is3DImeEnabled(worldId: World3DId): boolean {
+  return isImeEnabledRaw(asWorldNumber(worldId));
+}
+
+/** Returns current IME preedit text, if any. */
+export function get3DImePreeditText(worldId: World3DId): string | null {
+  return getImePreeditTextRaw(asWorldNumber(worldId));
+}
+
+/** Returns current IME cursor range inside preedit text, if available. */
+export function get3DImeCursorRange(
+  worldId: World3DId,
+): [number, number] | null {
+  return getImeCursorRangeRaw(asWorldNumber(worldId));
+}
+
+/** Returns last IME committed text for the current frame, if any. */
+export function get3DImeCommitText(worldId: World3DId): string | null {
+  return getImeCommitTextRaw(asWorldNumber(worldId));
+}
+
 /** Returns true when close was requested for this world's primary window. */
 export function is3DWindowCloseRequested(worldId: World3DId): boolean {
   return isWindowCloseRequestedRaw(asWorldNumber(worldId));
@@ -217,6 +403,72 @@ export function get3DWindowSize(worldId: World3DId): [number, number] {
   return getWindowSizeRaw(asWorldNumber(worldId));
 }
 
+/** Returns current pointer position in window space. */
+export function get3DPointerPosition(worldId: World3DId): [number, number] {
+  return getPointerPositionRaw(asWorldNumber(worldId));
+}
+
+/** Returns real drawn window size from the latest pointer event, if available. */
+export function get3DPointerWindowSize(
+  worldId: World3DId,
+): [number, number] | null {
+  return getPointerWindowSizeRaw(asWorldNumber(worldId));
+}
+
+/** Returns pointer delta in window space for the current frame. */
+export function get3DPointerDelta(worldId: World3DId): [number, number] {
+  return getPointerDeltaRaw(asWorldNumber(worldId));
+}
+
+/** Returns pointer position relative to routed target, if available. */
+export function get3DPointerTargetPosition(
+  worldId: World3DId,
+): [number, number] | null {
+  return getPointerTargetPositionRaw(asWorldNumber(worldId));
+}
+
+/** Returns real drawn target size from the latest pointer event, if available. */
+export function get3DPointerTargetSize(
+  worldId: World3DId,
+): [number, number] | null {
+  return getPointerTargetSizeRaw(asWorldNumber(worldId));
+}
+
+/** Returns pointer delta relative to routed target for the current frame. */
+export function get3DPointerTargetDelta(
+  worldId: World3DId,
+): [number, number] | null {
+  return getPointerTargetDeltaRaw(asWorldNumber(worldId));
+}
+
+/** Returns routed target id under pointer, when available. */
+export function get3DPointerTargetId(worldId: World3DId): number | null {
+  return getPointerTargetIdRaw(asWorldNumber(worldId));
+}
+
+/** Returns pointer UV (0..1) in routed target space, when available. */
+export function get3DPointerTargetUv(
+  worldId: World3DId,
+): [number, number] | null {
+  return getPointerTargetUvRaw(asWorldNumber(worldId));
+}
+
+/** Returns true while a pointer button is pressed in this world. */
+export function is3DPointerButtonPressed(
+  worldId: World3DId,
+  button: number,
+): boolean {
+  return isPointerButtonPressedRaw(asWorldNumber(worldId), button);
+}
+
+/** Returns true when a pointer button was pressed in this frame. */
+export function is3DPointerButtonJustPressed(
+  worldId: World3DId,
+  button: number,
+): boolean {
+  return isPointerButtonJustPressedRaw(asWorldNumber(worldId), button);
+}
+
 /** Sends a host notification scoped to this world. */
 export function send3DNotification(
   worldId: World3DId,
@@ -247,20 +499,17 @@ export function create3DAudioSource(
   args: Create3DAudioSourceArgs,
 ): CommandId {
   const rawWorldId = asWorldNumber(worldId);
-  const realmId = getWorldRealmIdRaw(rawWorldId);
-  if (realmId == null) {
-    throw new Error('World is not ready for audio source creation.');
-  }
-
-  const modelId = 'modelId' in args
-    ? args.modelId
-    : getModelIdRaw(rawWorldId, args.entityId as number);
-  if (modelId == null) {
-    throw new Error('Audio source entity has no resolved model yet.');
-  }
-  const baseArgs = 'modelId' in args
-    ? args
-    : (({ entityId: _entityId, ...rest }) => rest)(args);
+  const realmId = getWorldRealmIdRaw(rawWorldId) ?? rawWorldId;
+
+  const modelId =
+    'modelId' in args
+      ? args.modelId
+      : (getModelIdRaw(rawWorldId, args.entityId as number) ??
+        (args.entityId as number));
+  const baseArgs =
+    'modelId' in args
+      ? args
+      : (({ entityId: _entityId, ...rest }) => rest)(args);
 
   return asCommandId(
     audioSourceCreateRaw(rawWorldId, {