@vulfram/engine 0.14.8-alpha → 0.17.1-alpha

package/src/engine/world/world3d.ts

@@ -0,0 +1,280 @@
+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 { 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 { NotificationLevel } from '../../types/kinds';
+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,
+  drawGizmoAabb as drawGizmoAabbRaw,
+  drawGizmoLine as drawGizmoLineRaw,
+  getModelId as getModelIdRaw,
+  getWindowSize as getWindowSizeRaw,
+  getWorldRealmId as getWorldRealmIdRaw,
+  isKeyPressed as isKeyPressedRaw,
+  isWindowCloseRequested as isWindowCloseRequestedRaw,
+  listCameras as listCamerasRaw,
+  listGeometries as listGeometriesRaw,
+  listLights as listLightsRaw,
+  listMaterials as listMaterialsRaw,
+  listModels as listModelsRaw,
+  listTextures as listTexturesRaw,
+  poseUpdate as poseUpdateRaw,
+  removeEntity as removeEntityRaw,
+  sendNotification as sendNotificationRaw,
+  setParent as setParentRaw,
+  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 = {
+  outputSurfaceId?: number;
+  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));
+}
+
+/** 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)));
+}
+
+/** 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 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));
+}
+
+/** 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);
+  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);
+
+  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));
+}

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[];
 }

package/src/types/cmds/camera.ts

@@ -15,6 +15,7 @@ export interface ViewPosition {
 
 /** Command payload for creating a camera. */
 export interface CmdCameraCreateArgs {
+  realmId: number;
   cameraId: number;
   label?: string;
   transform: number[]; // Mat4 (16 elements)
@@ -27,14 +28,9 @@ export interface CmdCameraCreateArgs {
   orthoScale: number;
 }
 
-/** Result payload for camera create. */
-export interface CmdResultCameraCreate {
-  success: boolean;
-  message: string;
-}
-
 /** Command payload for updating a camera. */
 export interface CmdCameraUpdateArgs {
+  realmId: number;
   cameraId: number;
   label?: string;
   transform?: number[];
@@ -47,14 +43,22 @@ export interface CmdCameraUpdateArgs {
   orthoScale?: number;
 }
 
-/** Result payload for camera update. */
-export interface CmdResultCameraUpdate {
+/** Result payload for camera upsert. */
+export interface CmdResultCameraUpsert {
   success: boolean;
   message: string;
 }
 
+/** Upsert payload accepted by the core (`create` or `update`). */
+export type CmdCameraUpsertArgs = CmdCameraCreateArgs | CmdCameraUpdateArgs;
+
+/** Backward-compatible aliases. */
+export type CmdResultCameraCreate = CmdResultCameraUpsert;
+export type CmdResultCameraUpdate = CmdResultCameraUpsert;
+
 /** Command payload for disposing a camera. */
 export interface CmdCameraDisposeArgs {
+  realmId: number;
   cameraId: number;
 }
 

package/src/types/cmds/environment.ts

@@ -55,24 +55,30 @@ export interface PostProcessConfig {
 export interface EnvironmentConfig {
   msaa: MsaaConfig;
   skybox: SkyboxConfig;
+  clearColor: [number, number, number, number];
   post: PostProcessConfig;
 }
 
 /** Command payload for creating environment settings. */
 export interface CmdEnvironmentCreateArgs {
-  windowId: number;
+  environmentId: number;
   config: EnvironmentConfig;
 }
 
 /** Command payload for updating environment settings. */
 export interface CmdEnvironmentUpdateArgs {
-  windowId: number;
+  environmentId: number;
   config: EnvironmentConfig;
 }
 
+/** Upsert payload accepted by the core (`create` or `update`). */
+export type CmdEnvironmentUpsertArgs =
+  | CmdEnvironmentCreateArgs
+  | CmdEnvironmentUpdateArgs;
+
 /** Command payload for disposing environment settings. */
 export interface CmdEnvironmentDisposeArgs {
-  windowId: number;
+  environmentId: number;
 }
 
 /** Result payload for environment commands. */

package/src/types/cmds/geometry.ts

@@ -32,35 +32,35 @@ export interface GeometryPrimitiveEntry {
 
 /** 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[];
+  entries?: GeometryPrimitiveEntry[];
 }
 
-/** Result payload for geometry update. */
-export interface CmdResultGeometryUpdate {
+/** Result payload for geometry upsert. */
+export interface CmdResultGeometryUpsert {
   success: boolean;
   message: string;
 }
 
+/** Upsert payload accepted by the core (`create` or `update`). */
+export type CmdGeometryUpsertArgs =
+  | CmdGeometryCreateArgs
+  | CmdGeometryUpdateArgs;
+
+/** Backward-compatible aliases. */
+export type CmdResultGeometryCreate = CmdResultGeometryUpsert;
+export type CmdResultGeometryUpdate = CmdResultGeometryUpsert;
+
 /** Command payload for disposing geometry. */
 export interface CmdGeometryDisposeArgs {
-  windowId: number;
   geometryId: number;
 }
 
@@ -121,11 +121,10 @@ export type PrimitiveOptions =
 
 /** Command payload for creating a primitive geometry. */
 export interface CmdPrimitiveGeometryCreateArgs {
-  windowId: number;
   geometryId: number;
   label?: string;
   shape: PrimitiveShape;
-  options: PrimitiveOptions;
+  options?: PrimitiveOptions;
 }
 
 /** Result payload for primitive geometry create. */