@vulfram/engine 0.19.3-alpha → 0.20.1-alpha

package/src/engine/world/world-ui.ts

@@ -1,5 +1,11 @@
 import { createWorldUI as createWorldUIRaw } from '../api';
 import type { UiFocusCycleMode } from '../ecs';
+import type {
+  CmdRealmRenderGraphBindArgs,
+  CmdRenderGraphDisposeArgs,
+  CmdRenderGraphListArgs,
+  CmdRenderGraphUpsertArgs,
+} from '../../types/cmds/render-graph';
 import type {
   CmdUiAccessKitActionRequestArgs,
   CmdUiApplyOpsArgs,
@@ -25,6 +31,7 @@ import { EngineError } from '../errors';
 import { getWorldOrThrow } from '../bridge/guards';
 import {
   getUiEvents as getUiEventsRaw,
+  getWorldRealmId as getWorldRealmIdRaw,
   uiAccessKitActionRequest as uiAccessKitActionRequestRaw,
   uiApplyOps as uiApplyOpsRaw,
   uiClipboardPaste as uiClipboardPasteRaw,
@@ -41,18 +48,22 @@ import {
   uiFocusNext as uiFocusNextRaw,
   uiFormDispose as uiFormDisposeRaw,
   uiFormUpsert as uiFormUpsertRaw,
+  bindRealmRenderGraph as bindRealmRenderGraphRaw,
+  disposeRenderGraph as disposeRenderGraphRaw,
   uiGetDocumentTree as uiGetDocumentTreeRaw,
   uiGetFocus as uiGetFocusRaw,
   uiGetLayoutRects as uiGetLayoutRectsRaw,
+  listRenderGraphs as listRenderGraphsRaw,
   uiScreenshotReply as uiScreenshotReplyRaw,
   uiSetDebug as uiSetDebugRaw,
   uiSetDocumentRect as uiSetDocumentRectRaw,
   uiSetDocumentTheme as uiSetDocumentThemeRaw,
   uiSetEventTrace as uiSetEventTraceRaw,
   uiSetFocus as uiSetFocusRaw,
+  upsertRenderGraph as upsertRenderGraphRaw,
 } from './entities';
-import type { WorldUIId } from './types';
-import { asWorldNumber, asWorldUIId } from './types';
+import type { CommandId, WorldUIId } from './types';
+import { asCommandId, asWorldNumber, asWorldUIId } from './types';
 
 type CreateUIWorldOptions = {
   importance?: number;
@@ -102,6 +113,43 @@ export function createUIWorld(options?: CreateUIWorldOptions): WorldUIId {
   return asWorldUIId(createWorldUIRaw(options));
 }
 
+/** Returns resolved core realm id for this UI world, or `null` if not ready yet. */
+export function getUIWorldRealmId(worldId: WorldUIId): number | null {
+  return getWorldRealmIdRaw(asWorldNumber(worldId));
+}
+
+/** Creates or updates a render graph definition in core. */
+export function upsertUIRenderGraph(
+  worldId: WorldUIId,
+  args: CmdRenderGraphUpsertArgs,
+): CommandId {
+  return asCommandId(upsertRenderGraphRaw(asWorldNumber(worldId), args));
+}
+
+/** Disposes a render graph definition from core. */
+export function disposeUIRenderGraph(
+  worldId: WorldUIId,
+  args: CmdRenderGraphDisposeArgs,
+): CommandId {
+  return asCommandId(disposeRenderGraphRaw(asWorldNumber(worldId), args));
+}
+
+/** Requests render graph catalog from core. */
+export function listUIRenderGraphs(
+  worldId: WorldUIId,
+  args: CmdRenderGraphListArgs = {},
+): CommandId {
+  return asCommandId(listRenderGraphsRaw(asWorldNumber(worldId), args));
+}
+
+/** Binds realm to a render graph id. */
+export function bindUIRealmRenderGraph(
+  worldId: WorldUIId,
+  args: CmdRealmRenderGraphBindArgs,
+): CommandId {
+  return asCommandId(bindRealmRenderGraphRaw(asWorldNumber(worldId), args));
+}
+
 /** Defines a theme in a UI world. */
 export function defineUITheme(
   worldId: WorldUIId,

package/src/engine/world/world3d.ts

@@ -26,6 +26,12 @@ import type {
   CmdGizmoDrawLineArgs,
 } from '../../types/cmds/gizmo';
 import type { CmdPoseUpdateArgs } from '../../types/cmds/model';
+import type {
+  CmdRealmRenderGraphBindArgs,
+  CmdRenderGraphDisposeArgs,
+  CmdRenderGraphListArgs,
+  CmdRenderGraphUpsertArgs,
+} from '../../types/cmds/render-graph';
 import type { ShadowConfig } from '../../types/cmds/shadow';
 import type { CmdTargetMeasurementArgs } from '../../types/cmds/target';
 import type { NotificationLevel } from '../../types/kinds';
@@ -46,6 +52,7 @@ import {
   createModel as createModelRaw,
   createTexture as createTextureRaw,
   createTag as createTagRaw,
+  disposeRenderGraph as disposeRenderGraphRaw,
   disposeGeometry as disposeGeometryRaw,
   disposeMaterial as disposeMaterialRaw,
   disposeTexture as disposeTextureRaw,
@@ -65,6 +72,8 @@ import {
   getPointerTargetPosition as getPointerTargetPositionRaw,
   getPointerTargetUv as getPointerTargetUvRaw,
   getPointerWindowSize as getPointerWindowSizeRaw,
+  getWindowLifecycleState as getWindowLifecycleStateRaw,
+  getWindowPointerCaptureState as getWindowPointerCaptureStateRaw,
   getWindowSize as getWindowSizeRaw,
   getWorldRealmId as getWorldRealmIdRaw,
   isImeEnabled as isImeEnabledRaw,
@@ -77,12 +86,15 @@ import {
   listLights as listLightsRaw,
   listMaterials as listMaterialsRaw,
   listModels as listModelsRaw,
+  listRenderGraphs as listRenderGraphsRaw,
   listTextures as listTexturesRaw,
   measureTarget as measureTargetRaw,
   poseUpdate as poseUpdateRaw,
   removeEntity as removeEntityRaw,
   sendNotification as sendNotificationRaw,
   setParent as setParentRaw,
+  bindRealmRenderGraph as bindRealmRenderGraphRaw,
+  upsertRenderGraph as upsertRenderGraphRaw,
   upsertInputTargetListener as upsertInputTargetListenerRaw,
   listInputTargetListeners as listInputTargetListenersRaw,
   updateTransform as updateTransformRaw,
@@ -313,6 +325,38 @@ export function list3DCameras(worldId: World3DId): CommandId {
   return asCommandId(listCamerasRaw(asWorldNumber(worldId)));
 }
 
+/** Creates or updates a render graph definition in core. */
+export function upsert3DRenderGraph(
+  worldId: World3DId,
+  args: CmdRenderGraphUpsertArgs,
+): CommandId {
+  return asCommandId(upsertRenderGraphRaw(asWorldNumber(worldId), args));
+}
+
+/** Disposes a render graph definition from core. */
+export function dispose3DRenderGraph(
+  worldId: World3DId,
+  args: CmdRenderGraphDisposeArgs,
+): CommandId {
+  return asCommandId(disposeRenderGraphRaw(asWorldNumber(worldId), args));
+}
+
+/** Requests render graph catalog from core. */
+export function list3DRenderGraphs(
+  worldId: World3DId,
+  args: CmdRenderGraphListArgs = {},
+): CommandId {
+  return asCommandId(listRenderGraphsRaw(asWorldNumber(worldId), args));
+}
+
+/** Binds realm to a render graph id. */
+export function bind3DRealmRenderGraph(
+  worldId: World3DId,
+  args: CmdRealmRenderGraphBindArgs,
+): CommandId {
+  return asCommandId(bindRealmRenderGraphRaw(asWorldNumber(worldId), args));
+}
+
 /** Requests target measurement for this world context. */
 export function measure3DTarget(
   worldId: World3DId,
@@ -403,6 +447,20 @@ export function get3DWindowSize(worldId: World3DId): [number, number] {
   return getWindowSizeRaw(asWorldNumber(worldId));
 }
 
+/** Returns latest lifecycle state reported by the window subsystem. */
+export function get3DWindowLifecycleState(
+  worldId: World3DId,
+): 'minimized' | 'maximized' | 'windowed' | 'fullscreen' | 'windowed-fullscreen' | null {
+  return getWindowLifecycleStateRaw(asWorldNumber(worldId));
+}
+
+/** Returns latest pointer-capture snapshot reported by the window subsystem. */
+export function get3DWindowPointerCaptureState(
+  worldId: World3DId,
+): { mode: 'none' | 'confined' | 'locked'; active: boolean; reason?: string } | null {
+  return getWindowPointerCaptureStateRaw(asWorldNumber(worldId));
+}
+
 /** Returns current pointer position in window space. */
 export function get3DPointerPosition(worldId: World3DId): [number, number] {
   return getPointerPositionRaw(asWorldNumber(worldId));

package/src/types/cmds/environment.ts

@@ -14,9 +14,18 @@ export interface SkyboxConfig {
   groundColor: [number, number, number];
   horizonColor: [number, number, number];
   skyColor: [number, number, number];
+  horizonGroundThreshold?: number;
+  horizonSkyThreshold?: number;
+  directionalLights?: SkyboxDirectionalLightSun[];
   cubemapTextureId?: number | null;
 }
 
+export interface SkyboxDirectionalLightSun {
+  lightId: number;
+  solidSize?: number;
+  gradientSize?: number;
+}
+
 /** Post-processing configuration. */
 export interface PostProcessConfig {
   filterEnabled: boolean;

package/src/types/cmds/index.ts

@@ -8,6 +8,7 @@ import * as Lite from './light';
 import * as Mat from './material';
 import * as Mod from './model';
 import * as Realm from './realm';
+import * as RenderGraph from './render-graph';
 import * as Sys from './system';
 import * as Target from './target';
 import * as Tex from './texture';
@@ -133,6 +134,22 @@ export type EngineCmd =
   | { type: 'cmd-shadow-configure'; content: import('./shadow').CmdShadowConfigureArgs }
   | { type: 'cmd-realm-create'; content: Realm.CmdRealmCreateArgs }
   | { type: 'cmd-realm-dispose'; content: Realm.CmdRealmDisposeArgs }
+  | {
+      type: 'cmd-render-graph-upsert';
+      content: RenderGraph.CmdRenderGraphUpsertArgs;
+    }
+  | {
+      type: 'cmd-render-graph-dispose';
+      content: RenderGraph.CmdRenderGraphDisposeArgs;
+    }
+  | {
+      type: 'cmd-render-graph-list';
+      content: RenderGraph.CmdRenderGraphListArgs;
+    }
+  | {
+      type: 'cmd-realm-render-graph-bind';
+      content: RenderGraph.CmdRealmRenderGraphBindArgs;
+    }
   | { type: 'cmd-target-upsert'; content: Target.CmdTargetUpsertArgs }
   | {
       type: 'cmd-target-measurement';
@@ -277,6 +294,22 @@ export type CommandResponse =
     }
   | { type: 'realm-create'; content: Realm.CmdResultRealmCreate }
   | { type: 'realm-dispose'; content: Realm.CmdResultRealmDispose }
+  | {
+      type: 'render-graph-upsert';
+      content: RenderGraph.CmdResultRenderGraphUpsert;
+    }
+  | {
+      type: 'render-graph-dispose';
+      content: RenderGraph.CmdResultRenderGraphDispose;
+    }
+  | {
+      type: 'render-graph-list';
+      content: RenderGraph.CmdResultRenderGraphList;
+    }
+  | {
+      type: 'realm-render-graph-bind';
+      content: RenderGraph.CmdResultRealmRenderGraphBind;
+    }
   | { type: 'target-upsert'; content: Target.CmdResultTargetUpsert }
   | {
       type: 'target-measurement';

package/src/types/cmds/render-graph.ts

@@ -37,13 +37,47 @@ export interface RenderGraphDesc {
   fallback?: boolean;
 }
 
-export interface CmdRenderGraphSetArgs {
-  windowId: number;
+export interface CmdRenderGraphUpsertArgs {
+  renderGraphId: number;
   graph: RenderGraphDesc;
 }
 
-export interface CmdResultRenderGraphSet {
+export interface CmdResultRenderGraphUpsert {
+  success: boolean;
+  message: string;
+}
+
+export interface CmdRenderGraphDisposeArgs {
+  renderGraphId: number;
+}
+
+export interface CmdResultRenderGraphDispose {
+  success: boolean;
+  message: string;
+}
+
+export interface CmdRenderGraphListArgs {}
+
+export interface RenderGraphEntry {
+  renderGraphId: number;
+  descHash: number;
+  passCount: number;
+  passIds: string[];
+  boundRealmIds: number[];
+}
+
+export interface CmdResultRenderGraphList {
+  success: boolean;
+  message: string;
+  renderGraphs: RenderGraphEntry[];
+}
+
+export interface CmdRealmRenderGraphBindArgs {
+  realmId: number;
+  renderGraphId: number;
+}
+
+export interface CmdResultRealmRenderGraphBind {
   success: boolean;
-  fallbackUsed: boolean;
   message: string;
 }

package/src/types/events/system.ts

@@ -17,7 +17,7 @@ export type UiViewportCommand =
   | { type: 'focus' }
   | { type: 'screenshot' }
   | { type: 'cursor-visible'; content: { value: boolean } }
-  | { type: 'cursor-grab'; content: { mode: CursorGrabMode } }
+  | { type: 'cursor-grab'; content: { mode: CursorGrabMode | string } }
   | { type: 'ime-allowed'; content: { value: boolean } }
   | {
       type: 'ime-rect';

package/src/types/events/window.ts

@@ -1,3 +1,5 @@
+import type { CursorGrabMode, WindowState } from '../kinds';
+
 /** Payload for window create event. */
 export interface WindowEventOnCreateData {
   windowId: number;
@@ -76,6 +78,25 @@ export interface WindowEventOnThemeChangeData {
   darkMode: boolean;
 }
 
+/** Payload for lifecycle state change event. */
+export interface WindowEventOnStateChangeData {
+  windowId: number;
+  state: WindowState;
+}
+
+/** Pointer capture snapshot from window runtime. */
+export interface WindowPointerCaptureState {
+  mode: CursorGrabMode;
+  active: boolean;
+  reason?: string;
+}
+
+/** Payload for pointer capture mode/activation updates. */
+export interface WindowEventOnPointerCaptureChangeData {
+  windowId: number;
+  capture: WindowPointerCaptureState;
+}
+
 /** Discriminated union of window events. */
 export type WindowEvent =
   | { event: 'on-create'; data: WindowEventOnCreateData }
@@ -93,4 +114,9 @@ export type WindowEvent =
   | { event: 'on-file-drop'; data: WindowEventOnFileDropData }
   | { event: 'on-file-hover'; data: WindowEventOnFileHoverData }
   | { event: 'on-file-hover-cancel'; data: WindowEventOnFileHoverCancelData }
-  | { event: 'on-theme-change'; data: WindowEventOnThemeChangeData };
+  | { event: 'on-theme-change'; data: WindowEventOnThemeChangeData }
+  | { event: 'on-state-change'; data: WindowEventOnStateChangeData }
+  | {
+      event: 'on-pointer-capture-change';
+      data: WindowEventOnPointerCaptureChangeData;
+    };