@vulfram/engine 0.14.8-alpha → 0.17.1-alpha

package/src/engine/world/entities.ts

@@ -1,26 +1,66 @@
 import type { ShadowConfig } from '../../types/cmds/shadow';
 import type { EnvironmentConfig } from '../../types/cmds/environment';
+import type {
+  CmdEnvironmentDisposeArgs,
+} from '../../types/cmds/environment';
+import type {
+  CmdTargetDisposeArgs,
+  CmdTargetLayerDisposeArgs,
+  CmdTargetLayerUpsertArgs,
+  CmdTargetUpsertArgs,
+  TargetLayerLayout,
+} from '../../types/cmds/target';
 import type {
   CmdAudioListenerCreateArgs,
   CmdAudioListenerDisposeArgs,
+  CmdAudioListenerUpsertArgs,
   CmdAudioListenerUpdateArgs,
-  CmdAudioResourceCreateArgs,
+  CmdAudioResourceUpsertArgs,
   CmdAudioResourceDisposeArgs,
-  CmdAudioResourcePushArgs,
+  CmdAudioSourceTransportArgs,
   CmdAudioSourceCreateArgs,
   CmdAudioSourceDisposeArgs,
-  CmdAudioSourcePauseArgs,
-  CmdAudioSourcePlayArgs,
-  CmdAudioSourceStopArgs,
+  CmdAudioSourceUpsertArgs,
   CmdAudioSourceUpdateArgs,
+  CmdAudioStateGetArgs,
 } from '../../types/cmds/audio';
 import type { CmdPoseUpdateArgs } from '../../types/cmds/model';
-import type { NotificationLevel, UserAttentionType } from '../../types/kinds';
+import type {
+  CmdSystemDiagnosticsSetArgs,
+  CmdUploadBufferDiscardAllArgs,
+} from '../../types/cmds/system';
+import type { CmdTextureBindTargetArgs } from '../../types/cmds/texture';
+import type {
+  CmdUiAccessKitActionRequestArgs,
+  CmdUiApplyOpsArgs,
+  CmdUiClipboardPasteArgs,
+  CmdUiDebugSetArgs,
+  CmdUiDocumentCreateArgs,
+  CmdUiDocumentDisposeArgs,
+  CmdUiDocumentGetLayoutRectsArgs,
+  CmdUiDocumentGetTreeArgs,
+  CmdUiDocumentSetRectArgs,
+  CmdUiDocumentSetThemeArgs,
+  CmdUiEventTraceSetArgs,
+  CmdUiFocusGetArgs,
+  CmdUiFocusSetArgs,
+  CmdUiImageCreateFromBufferArgs,
+  CmdUiImageDisposeArgs,
+  CmdUiScreenshotReplyArgs,
+  CmdUiThemeDefineArgs,
+  CmdUiThemeDisposeArgs,
+} from '../../types/cmds/ui';
+import type { NotificationLevel } from '../../types/kinds';
+import { EngineError } from '../errors';
 import { getWorldOrThrow, requireInitialized } from '../bridge/guards';
-import { enqueueCommand } from '../bridge/dispatch';
+import {
+  enqueueCommand,
+  enqueueGlobalCommand,
+  markRoutingIndexDirty,
+} from '../bridge/dispatch';
 import type {
+  CameraComponent,
   CameraProps,
-  CreateWindowProps,
   GeometryProps,
   InputStateComponent,
   Intent,
@@ -30,10 +70,35 @@ import type {
   TagProps,
   TextureProps,
   TransformProps,
-  WindowProps,
+  UiFocusCycleMode,
   WindowStateComponent,
 } from '../ecs';
 import { engineState } from '../state';
+import type { GamepadEvent, SystemEvent, UiEvent } from '../../types/events';
+
+function allocateGlobalId(): number {
+  return engineState.nextGlobalId++;
+}
+
+function recalculateWorldWindowBindings(world: ReturnType<typeof getWorldOrThrow>): void {
+  world.boundWindowIds.clear();
+  for (const windowId of world.targetWindowBindings.values()) {
+    world.boundWindowIds.add(windowId);
+  }
+
+  if (world.boundWindowIds.size === 0) {
+    world.primaryWindowId = undefined;
+    return;
+  }
+
+  let primary = Number.POSITIVE_INFINITY;
+  for (const windowId of world.boundWindowIds) {
+    if (windowId < primary) {
+      primary = windowId;
+    }
+  }
+  world.primaryWindowId = primary;
+}
 
 /**
  * Emits an intent to the specified world.
@@ -57,6 +122,272 @@ export function getModelId(worldId: number, entityId: number): number | null {
   return model?.id ?? null;
 }
 
+/**
+ * Returns the core realm id associated with this world, if already created.
+ */
+export function getWorldRealmId(worldId: number): number | null {
+  requireInitialized();
+  const world = getWorldOrThrow(worldId);
+  return world.coreRealmId ?? null;
+}
+
+/**
+ * Returns true when the world has a resolved core realm id.
+ */
+export function isWorldReady(worldId: number): boolean {
+  return getWorldRealmId(worldId) !== null;
+}
+
+/**
+ * Upserts a target used to present world output.
+ */
+export function upsertTarget(worldId: number, args: CmdTargetUpsertArgs): number {
+  const id = enqueueCommand(worldId, 'cmd-target-upsert', args);
+  const world = getWorldOrThrow(worldId);
+  if (args.kind === 'window' && args.windowId !== undefined) {
+    world.targetWindowBindings.set(args.targetId, args.windowId);
+    recalculateWorldWindowBindings(world);
+    markRoutingIndexDirty();
+  } else {
+    if (world.targetWindowBindings.delete(args.targetId)) {
+      recalculateWorldWindowBindings(world);
+    }
+    markRoutingIndexDirty();
+  }
+  return id;
+}
+
+/**
+ * Disposes a target.
+ */
+export function disposeTarget(worldId: number, args: CmdTargetDisposeArgs): number {
+  const world = getWorldOrThrow(worldId);
+  world.targetLayerBindings.delete(args.targetId);
+  if (world.targetWindowBindings.delete(args.targetId)) {
+    recalculateWorldWindowBindings(world);
+  }
+  markRoutingIndexDirty();
+  return enqueueCommand(worldId, 'cmd-target-dispose', args);
+}
+
+/**
+ * Binds this world's realm to a target layer.
+ */
+export function bindWorldToTarget(
+  worldId: number,
+  args: Omit<CmdTargetLayerUpsertArgs, 'realmId'>,
+): number {
+  const world = getWorldOrThrow(worldId);
+  const realmId = getWorldRealmId(worldId);
+  if (realmId === null) {
+    throw new EngineError(
+      'WorldNotReady',
+      `World ${worldId} realm is not ready. Call tick() and wait for realm-create response.`,
+    );
+  }
+
+  const resolvedCameraId = args.cameraId ?? findPreferredCameraId(worldId);
+  const resolvedArgs: Omit<CmdTargetLayerUpsertArgs, 'realmId'> = {
+    ...args,
+    cameraId: resolvedCameraId,
+  };
+
+  world.targetLayerBindings.set(args.targetId, {
+    targetId: args.targetId,
+    layout: args.layout,
+    cameraId: resolvedCameraId,
+    environmentId: args.environmentId,
+  });
+  markRoutingIndexDirty();
+
+  return enqueueCommand(worldId, 'cmd-target-layer-upsert', {
+    realmId,
+    ...resolvedArgs,
+  });
+}
+
+/**
+ * Unbinds this world's realm from a target layer.
+ */
+export function unbindWorldFromTarget(
+  worldId: number,
+  args: Omit<CmdTargetLayerDisposeArgs, 'realmId'>,
+): number {
+  const world = getWorldOrThrow(worldId);
+  const realmId = getWorldRealmId(worldId);
+  if (realmId === null) {
+    throw new EngineError(
+      'WorldNotReady',
+      `World ${worldId} realm is not ready. Call tick() and wait for realm-create response.`,
+    );
+  }
+  world.targetLayerBindings.delete(args.targetId);
+  if (world.targetWindowBindings.delete(args.targetId)) {
+    recalculateWorldWindowBindings(world);
+  }
+  markRoutingIndexDirty();
+  return enqueueCommand(worldId, 'cmd-target-layer-dispose', {
+    realmId,
+    ...args,
+  });
+}
+
+function findPreferredCameraId(worldId: number): number | undefined {
+  const world = getWorldOrThrow(worldId);
+  let bestId: number | undefined;
+  let bestOrder = Number.POSITIVE_INFINITY;
+  for (const store of world.components.values()) {
+    const camera = store.get('Camera') as CameraComponent | undefined;
+    if (!camera) continue;
+    if (
+      camera.order < bestOrder ||
+      (camera.order === bestOrder &&
+        (bestId === undefined || camera.id < bestId))
+    ) {
+      bestOrder = camera.order;
+      bestId = camera.id;
+    }
+  }
+  return bestId;
+}
+
+/**
+ * Convenience helper: presents this world in a window via target/layer bind.
+ */
+export function presentWorldInWindow(
+  worldId: number,
+  args: {
+    windowId: number;
+    targetId?: number;
+    layout?: TargetLayerLayout;
+    cameraId?: number;
+    environmentId?: number;
+  },
+): { targetId: number; upsertCommandId: number; bindCommandId: number } {
+  requireInitialized();
+  const targetId = args.targetId ?? allocateGlobalId();
+  const upsertCommandId = upsertTarget(worldId, {
+    targetId,
+    kind: 'window',
+    windowId: args.windowId,
+  });
+  const bindCommandId = bindWorldToTarget(worldId, {
+    targetId,
+    layout: args.layout ?? {
+      left: { unit: 'percent', value: 0 },
+      top: { unit: 'percent', value: 0 },
+      width: { unit: 'percent', value: 100 },
+      height: { unit: 'percent', value: 100 },
+      zIndex: 0,
+      blendMode: 0,
+    },
+    cameraId: args.cameraId,
+    environmentId: args.environmentId,
+  });
+  return { targetId, upsertCommandId, bindCommandId };
+}
+
+/**
+ * Disposes a world and optionally releases its bound realm/targets.
+ * This operation is immediate on host state; core-side disposal commands are queued globally.
+ */
+export function disposeWorld(
+  worldId: number,
+  opts: {
+    disposeRealm?: boolean;
+    disposeTargets?: boolean;
+    warnOnUndisposedResources?: boolean;
+    strictResourceLifecycle?: boolean;
+  } = {},
+): void {
+  requireInitialized();
+  const world = getWorldOrThrow(worldId);
+  const disposeRealm = opts.disposeRealm ?? true;
+  const disposeTargets = opts.disposeTargets ?? true;
+  const strictResourceLifecycle = opts.strictResourceLifecycle ?? false;
+  const warnOnUndisposedResources = opts.warnOnUndisposedResources ?? true;
+
+  let retainedCoreObjectCount = 0;
+  for (const store of world.components.values()) {
+    for (const comp of store.values()) {
+      if ('id' in comp && typeof comp.id === 'number') {
+        retainedCoreObjectCount++;
+      }
+    }
+  }
+  const hasRetainedTargets = world.targetLayerBindings.size > 0;
+  const hasPendingWork =
+    world.pendingIntents.length > 0 || world.pendingCommands.length > 0;
+
+  if (
+    (!disposeRealm && (retainedCoreObjectCount > 0 || hasPendingWork)) ||
+    (!disposeTargets && hasRetainedTargets)
+  ) {
+    const message =
+      `disposeWorld(${worldId}) called without fully releasing resources. ` +
+      `retainRealm=${!disposeRealm} retainTargets=${!disposeTargets} ` +
+      `trackedCoreObjects=${retainedCoreObjectCount} ` +
+      `targetBindings=${world.targetLayerBindings.size} ` +
+      `pendingIntents=${world.pendingIntents.length} ` +
+      `pendingCommands=${world.pendingCommands.length}`;
+    if (strictResourceLifecycle) {
+      throw new EngineError('WorldDisposeLifecycleRisk', message);
+    }
+    if (warnOnUndisposedResources) {
+      console.warn(`[World ${worldId}] ${message}`);
+    }
+  }
+
+  if (disposeTargets) {
+    for (const targetId of world.targetLayerBindings.keys()) {
+      let isShared = false;
+      for (const [otherWorldId, otherWorld] of engineState.worlds) {
+        if (otherWorldId === worldId) continue;
+        if (otherWorld.targetLayerBindings.has(targetId)) {
+          isShared = true;
+          break;
+        }
+      }
+      if (!isShared) {
+        enqueueGlobalCommand('cmd-target-dispose', { targetId });
+      }
+    }
+  }
+
+  if (disposeRealm && world.coreRealmId !== undefined) {
+    enqueueGlobalCommand('cmd-realm-dispose', { realmId: world.coreRealmId });
+  }
+
+  for (const [cmdId, trackedWorldId] of engineState.commandTracker) {
+    if (trackedWorldId === worldId) {
+      engineState.commandTracker.delete(cmdId);
+    }
+  }
+
+  engineState.worlds.delete(worldId);
+  markRoutingIndexDirty();
+}
+
+/**
+ * Configures global runtime diagnostics and pointer tracing.
+ */
+export function setSystemDiagnostics(
+  args: CmdSystemDiagnosticsSetArgs,
+): number {
+  requireInitialized();
+  return enqueueGlobalCommand('cmd-system-diagnostics-set', args);
+}
+
+/**
+ * Requests the core to discard all pending upload buffers.
+ */
+export function discardAllUploadBuffers(
+  args: CmdUploadBufferDiscardAllArgs = {},
+): number {
+  requireInitialized();
+  return enqueueGlobalCommand('cmd-upload-buffer-discard-all', args);
+}
+
 /**
  * Sends an audio listener update command.
  */
@@ -64,7 +395,17 @@ export function audioListenerUpdate(
   worldId: number,
   args: CmdAudioListenerUpdateArgs,
 ): number {
-  return enqueueCommand(worldId, 'cmd-audio-listener-update', args);
+  return enqueueCommand(worldId, 'cmd-audio-listener-upsert', args);
+}
+
+/**
+ * Binds a texture id to a texture target output.
+ */
+export function bindTextureToTarget(
+  worldId: number,
+  args: CmdTextureBindTargetArgs,
+): number {
+  return enqueueCommand(worldId, 'cmd-texture-bind-target', args);
 }
 
 /**
@@ -74,7 +415,17 @@ export function audioListenerCreate(
   worldId: number,
   args: CmdAudioListenerCreateArgs,
 ): number {
-  return enqueueCommand(worldId, 'cmd-audio-listener-create', args);
+  return enqueueCommand(worldId, 'cmd-audio-listener-upsert', args);
+}
+
+/**
+ * Upserts audio listener params or binding.
+ */
+export function audioListenerUpsert(
+  worldId: number,
+  args: CmdAudioListenerUpsertArgs,
+): number {
+  return enqueueCommand(worldId, 'cmd-audio-listener-upsert', args);
 }
 
 /**
@@ -92,9 +443,9 @@ export function audioListenerDispose(
  */
 export function audioResourceCreate(
   worldId: number,
-  args: CmdAudioResourceCreateArgs,
+  args: CmdAudioResourceUpsertArgs,
 ): number {
-  return enqueueCommand(worldId, 'cmd-audio-resource-create', args);
+  return enqueueCommand(worldId, 'cmd-audio-resource-upsert', args);
 }
 
 /**
@@ -102,9 +453,9 @@ export function audioResourceCreate(
  */
 export function audioResourcePush(
   worldId: number,
-  args: CmdAudioResourcePushArgs,
+  args: CmdAudioResourceUpsertArgs,
 ): number {
-  return enqueueCommand(worldId, 'cmd-audio-resource-push', args);
+  return enqueueCommand(worldId, 'cmd-audio-resource-upsert', args);
 }
 
 /**
@@ -124,7 +475,7 @@ export function audioSourceCreate(
   worldId: number,
   args: CmdAudioSourceCreateArgs,
 ): number {
-  return enqueueCommand(worldId, 'cmd-audio-source-create', args);
+  return enqueueCommand(worldId, 'cmd-audio-source-upsert', args);
 }
 
 /**
@@ -134,7 +485,17 @@ export function audioSourceUpdate(
   worldId: number,
   args: CmdAudioSourceUpdateArgs,
 ): number {
-  return enqueueCommand(worldId, 'cmd-audio-source-update', args);
+  return enqueueCommand(worldId, 'cmd-audio-source-upsert', args);
+}
+
+/**
+ * Upserts audio source params or binding.
+ */
+export function audioSourceUpsert(
+  worldId: number,
+  args: CmdAudioSourceUpsertArgs,
+): number {
+  return enqueueCommand(worldId, 'cmd-audio-source-upsert', args);
 }
 
 /**
@@ -142,9 +503,12 @@ export function audioSourceUpdate(
  */
 export function audioSourcePlay(
   worldId: number,
-  args: CmdAudioSourcePlayArgs,
+  args: Omit<CmdAudioSourceTransportArgs, 'action'>,
 ): number {
-  return enqueueCommand(worldId, 'cmd-audio-source-play', args);
+  return enqueueCommand(worldId, 'cmd-audio-source-transport', {
+    ...args,
+    action: 'play',
+  });
 }
 
 /**
@@ -152,9 +516,12 @@ export function audioSourcePlay(
  */
 export function audioSourcePause(
   worldId: number,
-  args: CmdAudioSourcePauseArgs,
+  args: Omit<CmdAudioSourceTransportArgs, 'action'>,
 ): number {
-  return enqueueCommand(worldId, 'cmd-audio-source-pause', args);
+  return enqueueCommand(worldId, 'cmd-audio-source-transport', {
+    ...args,
+    action: 'pause',
+  });
 }
 
 /**
@@ -162,9 +529,22 @@ export function audioSourcePause(
  */
 export function audioSourceStop(
   worldId: number,
-  args: CmdAudioSourceStopArgs,
+  args: Omit<CmdAudioSourceTransportArgs, 'action'>,
+): number {
+  return enqueueCommand(worldId, 'cmd-audio-source-transport', {
+    ...args,
+    action: 'stop',
+  });
+}
+
+/**
+ * Requests a snapshot of audio runtime state.
+ */
+export function audioStateGet(
+  worldId: number,
+  args: CmdAudioStateGetArgs = {},
 ): number {
-  return enqueueCommand(worldId, 'cmd-audio-source-stop', args);
+  return enqueueCommand(worldId, 'cmd-audio-state-get', args);
 }
 
 /**
@@ -185,72 +565,80 @@ export function poseUpdate(worldId: number, args: CmdPoseUpdateArgs): number {
 }
 
 /**
- * Emits an intent to create a window in the core.
+ * Requests a list of resources from the engine for debugging.
  */
-export function createWindow(worldId: number, props: CreateWindowProps): void {
+export function requestResourceList(
+  worldId: number,
+  resourceType:
+    | 'model'
+    | 'material'
+    | 'texture'
+    | 'geometry'
+    | 'light'
+    | 'camera',
+): void {
   emitIntent(worldId, {
-    type: 'create-window',
-    props,
+    type: 'request-resource-list',
+    resourceType,
   });
 }
 
-/**
- * Emits an intent to close the window associated with this world.
- */
-export function closeWindow(worldId: number): void {
-  emitIntent(worldId, {
-    type: 'close-window',
+function resolveWorldWindowId(worldId: number): number {
+  const world = getWorldOrThrow(worldId);
+  if (world.primaryWindowId === undefined) {
+    for (const windowId of world.targetWindowBindings.values()) {
+      return windowId;
+    }
+    if (world.realmCreateArgs.hostWindowId !== undefined) {
+      return world.realmCreateArgs.hostWindowId;
+    }
+    throw new EngineError(
+      'WindowNotFound',
+      `World ${worldId} has no window binding available for this command.`,
+    );
+  }
+  return world.primaryWindowId;
+}
+
+/** Requests model list for a world window context. */
+export function listModels(worldId: number): number {
+  return enqueueCommand(worldId, 'cmd-model-list', {
+    windowId: resolveWorldWindowId(worldId),
   });
 }
 
-/**
- * Updates window properties.
- */
-export function updateWindow(worldId: number, props: WindowProps): void {
-  emitIntent(worldId, {
-    type: 'update-window',
-    props,
+/** Requests material list for a world window context. */
+export function listMaterials(worldId: number): number {
+  return enqueueCommand(worldId, 'cmd-material-list', {
+    windowId: resolveWorldWindowId(worldId),
   });
 }
 
-/**
- * Requests user attention for the window.
- */
-export function requestAttention(
-  worldId: number,
-  attentionType?: UserAttentionType,
-): void {
-  emitIntent(worldId, {
-    type: 'request-attention',
-    attentionType,
+/** Requests texture list for a world window context. */
+export function listTextures(worldId: number): number {
+  return enqueueCommand(worldId, 'cmd-texture-list', {
+    windowId: resolveWorldWindowId(worldId),
   });
 }
 
-/**
- * Focuses the window.
- */
-export function focusWindow(worldId: number): void {
-  emitIntent(worldId, {
-    type: 'focus-window',
+/** Requests geometry list for a world window context. */
+export function listGeometries(worldId: number): number {
+  return enqueueCommand(worldId, 'cmd-geometry-list', {
+    windowId: resolveWorldWindowId(worldId),
   });
 }
 
-/**
- * Requests a list of resources from the engine for debugging.
- */
-export function requestResourceList(
-  worldId: number,
-  resourceType:
-    | 'model'
-    | 'material'
-    | 'texture'
-    | 'geometry'
-    | 'light'
-    | 'camera',
-): void {
-  emitIntent(worldId, {
-    type: 'request-resource-list',
-    resourceType,
+/** Requests light list for a world window context. */
+export function listLights(worldId: number): number {
+  return enqueueCommand(worldId, 'cmd-light-list', {
+    windowId: resolveWorldWindowId(worldId),
+  });
+}
+
+/** Requests camera list for a world window context. */
+export function listCameras(worldId: number): number {
+  return enqueueCommand(worldId, 'cmd-camera-list', {
+    windowId: resolveWorldWindowId(worldId),
   });
 }
 
@@ -317,6 +705,237 @@ export function configureEnvironment(
   });
 }
 
+/**
+ * Disposes an environment profile.
+ * If omitted, defaults to this world id (engine convention).
+ */
+export function disposeEnvironment(
+  worldId: number,
+  args: CmdEnvironmentDisposeArgs = { environmentId: worldId },
+): number {
+  return enqueueCommand(worldId, 'cmd-environment-dispose', args);
+}
+
+/**
+ * Defines or updates a UI theme.
+ */
+export function uiDefineTheme(worldId: number, args: CmdUiThemeDefineArgs): void {
+  emitIntent(worldId, { type: 'ui-theme-define', args });
+}
+
+/**
+ * Disposes a UI theme.
+ */
+export function uiDisposeTheme(worldId: number, args: CmdUiThemeDisposeArgs): void {
+  emitIntent(worldId, { type: 'ui-theme-dispose', args });
+}
+
+/**
+ * Creates a UI document.
+ */
+export function uiCreateDocument(worldId: number, args: CmdUiDocumentCreateArgs): void {
+  emitIntent(worldId, { type: 'ui-document-create', args });
+}
+
+/**
+ * Disposes a UI document.
+ */
+export function uiDisposeDocument(worldId: number, args: CmdUiDocumentDisposeArgs): void {
+  emitIntent(worldId, { type: 'ui-document-dispose', args });
+}
+
+/**
+ * Updates document rectangle.
+ */
+export function uiSetDocumentRect(worldId: number, args: CmdUiDocumentSetRectArgs): void {
+  emitIntent(worldId, { type: 'ui-document-set-rect', args });
+}
+
+/**
+ * Updates document theme.
+ */
+export function uiSetDocumentTheme(worldId: number, args: CmdUiDocumentSetThemeArgs): void {
+  emitIntent(worldId, { type: 'ui-document-set-theme', args });
+}
+
+/**
+ * Applies document ops.
+ */
+export function uiApplyOps(worldId: number, args: CmdUiApplyOpsArgs): void {
+  emitIntent(worldId, { type: 'ui-apply-ops', args });
+}
+
+/**
+ * Requests UI document tree for introspection.
+ */
+export function uiGetDocumentTree(worldId: number, args: CmdUiDocumentGetTreeArgs): void {
+  emitIntent(worldId, { type: 'ui-document-get-tree', args });
+}
+
+/**
+ * Requests UI layout rects for introspection.
+ */
+export function uiGetLayoutRects(
+  worldId: number,
+  args: CmdUiDocumentGetLayoutRectsArgs,
+): void {
+  emitIntent(worldId, { type: 'ui-document-get-layout-rects', args });
+}
+
+/**
+ * Enables/disables runtime UI debug overlays.
+ */
+export function uiSetDebug(worldId: number, args: CmdUiDebugSetArgs): void {
+  emitIntent(worldId, { type: 'ui-debug-set', args });
+}
+
+/**
+ * Sets focused UI node.
+ */
+export function uiSetFocus(worldId: number, args: CmdUiFocusSetArgs): void {
+  emitIntent(worldId, { type: 'ui-focus-set', args });
+}
+
+/**
+ * Requests current UI focus state.
+ */
+export function uiGetFocus(worldId: number, args: CmdUiFocusGetArgs = {}): void {
+  emitIntent(worldId, { type: 'ui-focus-get', args });
+}
+
+/**
+ * Configures UI event trace level/sampling.
+ */
+export function uiSetEventTrace(worldId: number, args: CmdUiEventTraceSetArgs): void {
+  emitIntent(worldId, { type: 'ui-event-trace-set', args });
+}
+
+/**
+ * Creates a UI image from uploaded bytes.
+ */
+export function uiCreateImageFromBuffer(
+  worldId: number,
+  args: CmdUiImageCreateFromBufferArgs,
+): void {
+  emitIntent(worldId, { type: 'ui-image-create-from-buffer', args });
+}
+
+/**
+ * Disposes a UI image.
+ */
+export function uiDisposeImage(worldId: number, args: CmdUiImageDisposeArgs): void {
+  emitIntent(worldId, { type: 'ui-image-dispose', args });
+}
+
+/**
+ * Delivers host clipboard paste event to UI.
+ */
+export function uiClipboardPaste(worldId: number, args: CmdUiClipboardPasteArgs): void {
+  emitIntent(worldId, { type: 'ui-clipboard-paste', args });
+}
+
+/**
+ * Delivers screenshot response bytes to UI.
+ */
+export function uiScreenshotReply(worldId: number, args: CmdUiScreenshotReplyArgs): void {
+  emitIntent(worldId, { type: 'ui-screenshot-reply', args });
+}
+
+/**
+ * Delivers AccessKit action request to UI.
+ */
+export function uiAccessKitActionRequest(
+  worldId: number,
+  args: CmdUiAccessKitActionRequestArgs,
+): void {
+  emitIntent(worldId, { type: 'ui-access-kit-action-request', args });
+}
+
+/**
+ * Registers or updates a UI form scope used for tab navigation.
+ */
+export function uiFormUpsert(
+  worldId: number,
+  form: {
+    formId: string;
+    windowId: number;
+    realmId: number;
+    documentId: number;
+    disabled?: boolean;
+    cycleMode?: UiFocusCycleMode;
+    activeFieldsetId?: string;
+  },
+): void {
+  emitIntent(worldId, { type: 'ui-form-upsert', form });
+}
+
+/**
+ * Disposes a registered UI form scope.
+ */
+export function uiFormDispose(worldId: number, formId: string): void {
+  emitIntent(worldId, { type: 'ui-form-dispose', formId });
+}
+
+/**
+ * Registers or updates fieldset metadata.
+ */
+export function uiFieldsetUpsert(
+  worldId: number,
+  fieldset: {
+    formId: string;
+    fieldsetId: string;
+    disabled?: boolean;
+    legendNodeId?: number;
+  },
+): void {
+  emitIntent(worldId, { type: 'ui-fieldset-upsert', fieldset });
+}
+
+/**
+ * Disposes fieldset metadata.
+ */
+export function uiFieldsetDispose(
+  worldId: number,
+  formId: string,
+  fieldsetId: string,
+): void {
+  emitIntent(worldId, { type: 'ui-fieldset-dispose', formId, fieldsetId });
+}
+
+/**
+ * Registers or updates focusable node metadata.
+ */
+export function uiFocusableUpsert(
+  worldId: number,
+  focusable: {
+    formId: string;
+    nodeId: number;
+    tabIndex?: number;
+    fieldsetId?: string;
+    disabled?: boolean;
+    orderHint?: number;
+  },
+): void {
+  emitIntent(worldId, { type: 'ui-focusable-upsert', focusable });
+}
+
+/**
+ * Disposes focusable node metadata.
+ */
+export function uiFocusableDispose(worldId: number, nodeId: number): void {
+  emitIntent(worldId, { type: 'ui-focusable-dispose', nodeId });
+}
+
+/**
+ * Advances focus within a form scope using tab ordering.
+ */
+export function uiFocusNext(
+  worldId: number,
+  args: { windowId: number; backwards?: boolean; formId?: string },
+): void {
+  emitIntent(worldId, { type: 'ui-focus-next', ...args });
+}
+
 /**
  * Draws a debug gizmo line for one frame.
  */
@@ -465,6 +1084,12 @@ export function setParent(
   entityId: number,
   parentId: number | null,
 ): void {
+  if (parentId !== null && parentId === entityId) {
+    throw new EngineError(
+      'InvalidParent',
+      `Entity ${entityId} cannot be parent of itself.`,
+    );
+  }
   emitIntent(worldId, {
     type: 'set-parent',
     entityId,
@@ -481,8 +1106,8 @@ export function setParent(
  */
 export function createMaterial(worldId: number, props: MaterialProps): number {
   requireInitialized();
-  const world = getWorldOrThrow(worldId);
-  const resourceId = world.nextCoreId++;
+  getWorldOrThrow(worldId);
+  const resourceId = allocateGlobalId();
 
   emitIntent(worldId, {
     type: 'create-material',
@@ -498,8 +1123,8 @@ export function createMaterial(worldId: number, props: MaterialProps): number {
  */
 export function createGeometry(worldId: number, props: GeometryProps): number {
   requireInitialized();
-  const world = getWorldOrThrow(worldId);
-  const resourceId = world.nextCoreId++;
+  getWorldOrThrow(worldId);
+  const resourceId = allocateGlobalId();
 
   emitIntent(worldId, {
     type: 'create-geometry',
@@ -515,8 +1140,8 @@ export function createGeometry(worldId: number, props: GeometryProps): number {
  */
 export function createTexture(worldId: number, props: TextureProps): number {
   requireInitialized();
-  const world = getWorldOrThrow(worldId);
-  const resourceId = world.nextCoreId++;
+  getWorldOrThrow(worldId);
+  const resourceId = allocateGlobalId();
 
   emitIntent(worldId, {
     type: 'create-texture',
@@ -669,3 +1294,121 @@ export function getWindowScaleFactor(worldId: number): number {
   const state = getWindowState(worldId);
   return state?.scaleFactor ?? 1.0;
 }
+
+function getGamepadState(worldId: number):
+  | {
+      connected: Map<number, { name: string }>;
+      buttons: Map<number, Map<number, { pressed: boolean; value: number }>>;
+      axes: Map<number, Map<number, number>>;
+      eventsThisFrame: GamepadEvent[];
+    }
+  | undefined {
+  requireInitialized();
+  const world = getWorldOrThrow(worldId);
+  const worldStore = world.components.get(WORLD_ENTITY_ID);
+  return worldStore?.get('GamepadState') as
+    | {
+        connected: Map<number, { name: string }>;
+        buttons: Map<number, Map<number, { pressed: boolean; value: number }>>;
+        axes: Map<number, Map<number, number>>;
+        eventsThisFrame: GamepadEvent[];
+      }
+    | undefined;
+}
+
+function getSystemEventState(worldId: number):
+  | {
+      eventsThisFrame: SystemEvent[];
+      lastError?: {
+        scope: string;
+        message: string;
+        commandId?: number;
+        commandType?: string;
+      };
+    }
+  | undefined {
+  requireInitialized();
+  const world = getWorldOrThrow(worldId);
+  const worldStore = world.components.get(WORLD_ENTITY_ID);
+  return worldStore?.get('SystemEventState') as
+    | {
+        eventsThisFrame: SystemEvent[];
+        lastError?: {
+          scope: string;
+          message: string;
+          commandId?: number;
+          commandType?: string;
+        };
+      }
+    | undefined;
+}
+
+function getUiEventState(worldId: number):
+  | { eventsThisFrame: UiEvent[] }
+  | undefined {
+  requireInitialized();
+  const world = getWorldOrThrow(worldId);
+  const worldStore = world.components.get(WORLD_ENTITY_ID);
+  return worldStore?.get('UiEventState') as
+    | { eventsThisFrame: UiEvent[] }
+    | undefined;
+}
+
+export function getGamepadEvents(worldId: number): GamepadEvent[] {
+  return getGamepadState(worldId)?.eventsThisFrame ?? [];
+}
+
+/** Lists currently connected gamepads sorted by id. */
+export function getConnectedGamepads(
+  worldId: number,
+): Array<{ gamepadId: number; name: string }> {
+  const connected = getGamepadState(worldId)?.connected;
+  if (!connected) return [];
+  const out: Array<{ gamepadId: number; name: string }> = [];
+  for (const [gamepadId, info] of connected) {
+    out.push({ gamepadId, name: info.name });
+  }
+  out.sort((a, b) => a.gamepadId - b.gamepadId);
+  return out;
+}
+
+/** Returns current value of a gamepad axis or 0 when unavailable. */
+export function getGamepadAxis(
+  worldId: number,
+  gamepadId: number,
+  axis: number,
+): number {
+  return getGamepadState(worldId)?.axes.get(gamepadId)?.get(axis) ?? 0;
+}
+
+/** Returns whether a gamepad button is currently pressed. */
+export function isGamepadButtonPressed(
+  worldId: number,
+  gamepadId: number,
+  button: number,
+): boolean {
+  return (
+    getGamepadState(worldId)?.buttons.get(gamepadId)?.get(button)?.pressed ??
+    false
+  );
+}
+
+/** Returns system events mirrored in the current frame. */
+export function getSystemEvents(worldId: number): SystemEvent[] {
+  return getSystemEventState(worldId)?.eventsThisFrame ?? [];
+}
+
+/** Returns the last system error seen by the world, if any. */
+export function getLastSystemError(worldId: number): {
+  scope: string;
+  message: string;
+  commandId?: number;
+  commandType?: string;
+} | null {
+  return getSystemEventState(worldId)?.lastError ?? null;
+}
+
+/** Returns UI events mirrored in the current frame. */
+export function getUiEvents(worldId: number): UiEvent[] {
+  return getUiEventState(worldId)?.eventsThisFrame ?? [];
+}