@vulfram/engine 0.14.8-alpha → 0.19.2-alpha

package/src/engine/world/world3d.ts

@@ -0,0 +1,529 @@
+import { createWorld3D as createWorld3DRaw } from '../api';
+import type {
+  CameraProps,
+  GeometryProps,
+  LightProps,
+  MaterialProps,
+  ModelProps,
+  TagProps,
+  TextureProps,
+  TransformProps,
+} from '../ecs';
+import type {
+  CmdAudioListenerUpdateArgs,
+  CmdAudioResourceUpsertArgs,
+  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 { 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,
+  audioSourceCreate as audioSourceCreateRaw,
+  audioSourcePlay as audioSourcePlayRaw,
+  configureEnvironment as configureEnvironmentRaw,
+  configureShadows as configureShadowsRaw,
+  createCamera as createCameraRaw,
+  createEntity as createEntityRaw,
+  createGeometry as createGeometryRaw,
+  createLight as createLightRaw,
+  createMaterial as createMaterialRaw,
+  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,
+  listLights as listLightsRaw,
+  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 {
+  CommandId,
+  EntityId,
+  GeometryId,
+  MaterialId,
+  TextureId,
+  World3DId,
+} from './types';
+import {
+  asCommandId,
+  asEntityId,
+  asGeometryId,
+  asMaterialId,
+  asTextureId,
+  asWorld3DId,
+  asWorldNumber,
+} from './types';
+
+export type Create3DWorldOptions = {
+  importance?: number;
+  cachePolicy?: number;
+  flags?: number;
+};
+
+type Create3DAudioSourceArgs = Omit<
+  CmdAudioSourceCreateArgs,
+  'realmId' | 'modelId'
+> &
+  ({ modelId: number } | { entityId: EntityId });
+
+/**
+ * Creates a 3D world.
+ *
+ * The world is realm-backed internally, but realm details are hidden from this API.
+ * Use `Mount.mountWorld(...)` to present this world into one or more targets.
+ */
+export function create3DWorld(options?: Create3DWorldOptions): World3DId {
+  return asWorld3DId(createWorld3DRaw(options));
+}
+
+/** Creates an entity in a 3D world. */
+export function create3DEntity(worldId: World3DId): EntityId {
+  return asEntityId(createEntityRaw(asWorldNumber(worldId)));
+}
+
+/** Removes an entity and all mirrored components from a 3D world. */
+export function remove3DEntity(worldId: World3DId, entityId: EntityId): void {
+  removeEntityRaw(asWorldNumber(worldId), entityId as number);
+}
+
+/** Upserts camera component intent for an entity in a 3D world. */
+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 {
+  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 {
+  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 {
+  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 {
+  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,
+  );
+}
+
+/** Creates a material resource and returns its typed id. */
+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 {
+  return asGeometryId(createGeometryRaw(asWorldNumber(worldId), props));
+}
+
+/** Creates a texture resource and returns its typed id. */
+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 {
+  configureEnvironmentRaw(asWorldNumber(worldId), config);
+}
+
+/** Configures shadows for a 3D world. */
+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 {
+  drawGizmoLineRaw(asWorldNumber(worldId), args);
+}
+
+/** Draws a debug axis-aligned bounding box gizmo. */
+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 {
+  return asCommandId(poseUpdateRaw(asWorldNumber(worldId), args));
+}
+
+/** Requests a model list from core for this world. */
+export function list3DModels(worldId: World3DId): CommandId {
+  return asCommandId(listModelsRaw(asWorldNumber(worldId)));
+}
+
+/** Requests a material list from core for this world. */
+export function list3DMaterials(worldId: World3DId): CommandId {
+  return asCommandId(listMaterialsRaw(asWorldNumber(worldId)));
+}
+
+/** Requests a texture list from core for this world. */
+export function list3DTextures(worldId: World3DId): CommandId {
+  return asCommandId(listTexturesRaw(asWorldNumber(worldId)));
+}
+
+/** Requests a geometry list from core for this world. */
+export function list3DGeometries(worldId: World3DId): CommandId {
+  return asCommandId(listGeometriesRaw(asWorldNumber(worldId)));
+}
+
+/** Requests a light list from core for this world. */
+export function list3DLights(worldId: World3DId): CommandId {
+  return asCommandId(listLightsRaw(asWorldNumber(worldId)));
+}
+
+/** Requests a camera list from core for this world. */
+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));
+}
+
+/** Returns current size for this world's primary window. */
+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,
+  args: { level: NotificationLevel; title: string; message: string },
+): void {
+  sendNotificationRaw(asWorldNumber(worldId), args);
+}
+
+/** Updates audio listener parameters. */
+export function update3DAudioListener(
+  worldId: World3DId,
+  args: CmdAudioListenerUpdateArgs,
+): CommandId {
+  return asCommandId(audioListenerUpdateRaw(asWorldNumber(worldId), args));
+}
+
+/** Creates or updates an audio resource. */
+export function create3DAudioResource(
+  worldId: World3DId,
+  args: CmdAudioResourceUpsertArgs,
+): CommandId {
+  return asCommandId(audioResourceCreateRaw(asWorldNumber(worldId), args));
+}
+
+/** Creates an audio source with realm id resolved internally from world state. */
+export function create3DAudioSource(
+  worldId: World3DId,
+  args: Create3DAudioSourceArgs,
+): CommandId {
+  const rawWorldId = asWorldNumber(worldId);
+  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, {
+      ...baseArgs,
+      modelId,
+      realmId,
+    }),
+  );
+}
+
+/** Starts playback on an audio source. */
+export function play3DAudioSource(
+  worldId: World3DId,
+  args: Omit<CmdAudioSourceTransportArgs, 'action'>,
+): CommandId {
+  return asCommandId(audioSourcePlayRaw(asWorldNumber(worldId), args));
+}