@vulfram/engine 0.5.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

@@ -0,0 +1,189 @@
+import type { AudioPlayMode } from '../kinds';
+
+export interface AudioSpatialParams {
+  minDistance: number;
+  maxDistance: number;
+  rolloff: number;
+  coneInner: number;
+  coneOuter: number;
+  coneOuterGain: number;
+}
+
+/** Command payload for updating the listener transform explicitly. */
+export interface CmdAudioListenerUpdateArgs {
+  position: [number, number, number];
+  velocity: [number, number, number];
+  forward: [number, number, number];
+  up: [number, number, number];
+}
+
+/** Command payload for binding the listener to a model. */
+export interface CmdAudioListenerCreateArgs {
+  realmId: number;
+  modelId: number;
+}
+
+/** Command payload for disposing the listener binding. */
+export interface CmdAudioListenerDisposeArgs {
+  realmId: number;
+}
+
+export interface CmdResultAudioListenerCreate {
+  success: boolean;
+  message: string;
+}
+
+export interface CmdResultAudioListenerDispose {
+  success: boolean;
+  message: string;
+}
+
+export interface CmdResultAudioListenerUpdate {
+  success: boolean;
+  message: string;
+}
+
+/** 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 CmdResultAudioResourceUpsert {
+  success: boolean;
+  message: string;
+  pending: boolean;
+  receivedBytes: number;
+  totalBytes: number;
+  complete: boolean;
+}
+
+/** Command payload for creating a source bound to a model. */
+export interface CmdAudioSourceCreateArgs {
+  realmId: number;
+  sourceId: number;
+  modelId: number;
+  position: [number, number, number];
+  velocity: [number, number, number];
+  orientation: [number, number, number, number];
+  gain: number;
+  pitch: number;
+  spatial: AudioSpatialParams;
+}
+
+export interface CmdResultAudioSourceCreate {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for updating source params. */
+export interface CmdAudioSourceUpdateArgs {
+  sourceId: number;
+  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 {
+  success: boolean;
+  message: string;
+}
+
+/** 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;
+  action: AudioSourceTransportAction;
+  resourceId?: number;
+  timelineId?: number;
+  intensity?: number;
+  delayMs?: number;
+  mode?: AudioPlayMode;
+}
+
+export interface CmdResultAudioSourceTransport {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for disposing a source. */
+export interface CmdAudioSourceDisposeArgs {
+  sourceId: number;
+}
+
+export interface CmdResultAudioSourceDispose {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for disposing an audio resource. */
+export interface CmdAudioResourceDisposeArgs {
+  resourceId: number;
+}
+
+export interface CmdResultAudioResourceDispose {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for listing current audio runtime state. */
+export interface CmdAudioStateGetArgs {
+  includeListener?: boolean;
+  includeSources?: boolean;
+  includeStreams?: boolean;
+}
+
+export interface AudioListenerBindingState {
+  realmId: number;
+  modelId: number;
+}
+
+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 CmdResultAudioStateGet {
+  success: boolean;
+  message: string;
+  listener?: AudioListenerBindingState;
+  sources: AudioSourceStateEntry[];
+  streams: AudioStreamStateEntry[];
+}

package/src/types/cmds/camera.ts

@@ -1,4 +1,5 @@
 import type { CameraKind } from '../kinds';
+import type { ResourceEntry } from './resources';
 
 /** Viewport value expressed as relative (0..1) or absolute pixels. */
 export interface ViewValue {
@@ -14,7 +15,7 @@ export interface ViewPosition {
 
 /** Command payload for creating a camera. */
 export interface CmdCameraCreateArgs {
-  windowId: number;
+  realmId: number;
   cameraId: number;
   label?: string;
   transform: number[]; // Mat4 (16 elements)
@@ -27,16 +28,11 @@ 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 {
-  windowId: number;
+  realmId: number;
   cameraId: number;
+  label?: string;
   transform?: number[];
   kind?: CameraKind;
   flags?: number;
@@ -47,15 +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 {
-  windowId: number;
+  realmId: number;
   cameraId: number;
 }
 
@@ -66,11 +69,13 @@ export interface CmdResultCameraDispose {
 }
 
 /** Command payload for listing cameras. */
-export interface CmdCameraListArgs {}
+export interface CmdCameraListArgs {
+  windowId: number;
+}
 
 /** Result payload for camera list. */
 export interface CmdResultCameraList {
   success: boolean;
   message: string;
-  content: number[]; // List of camera IDs
+  cameras: ResourceEntry[];
 }

package/src/types/cmds/environment.ts

@@ -11,31 +11,74 @@ export interface SkyboxConfig {
   mode: SkyboxMode;
   intensity: number;
   rotation: number;
-  tint: [number, number, number];
+  groundColor: [number, number, number];
+  horizonColor: [number, number, number];
+  skyColor: [number, number, number];
   cubemapTextureId?: number | null;
 }
 
+/** Post-processing configuration. */
+export interface PostProcessConfig {
+  filterEnabled: boolean;
+  filterExposure: number;
+  filterGamma: number;
+  filterSaturation: number;
+  filterContrast: number;
+  filterVignette: number;
+  filterGrain: number;
+  filterChromaticAberration: number;
+  filterBlur: number;
+  filterSharpen: number;
+  filterTonemapMode: number;
+  outlineEnabled: boolean;
+  outlineStrength: number;
+  outlineThreshold: number;
+  outlineWidth: number;
+  outlineQuality: number;
+  filterPosterizeSteps: number;
+  cellShading: boolean;
+  ssaoEnabled: boolean;
+  ssaoStrength: number;
+  ssaoRadius: number;
+  ssaoBias: number;
+  ssaoPower: number;
+  ssaoBlurRadius: number;
+  ssaoBlurDepthThreshold: number;
+  bloomEnabled: boolean;
+  bloomThreshold: number;
+  bloomKnee: number;
+  bloomIntensity: number;
+  bloomScatter: number;
+}
+
 /** Environment configuration for a window. */
 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. */