@ignifx/core 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/dist/{environment-C9AjYJgV.js → environment-Cq2BmA96.js} +2 -2
  2. package/dist/{environment-C9AjYJgV.js.map → environment-Cq2BmA96.js.map} +1 -1
  3. package/dist/hdr-output-DDpIo4Q5.js +300 -0
  4. package/dist/hdr-output-DDpIo4Q5.js.map +1 -0
  5. package/dist/{ignifx-error-Dq2qJMkZ.js → ignifx-error-oYdVnT1S.js} +16 -1
  6. package/dist/ignifx-error-oYdVnT1S.js.map +1 -0
  7. package/dist/index.d.ts +343 -4
  8. package/dist/index.d.ts.map +1 -1
  9. package/dist/index.js +842 -165
  10. package/dist/index.js.map +1 -1
  11. package/dist/material-CGk5mAah.js +204 -0
  12. package/dist/material-CGk5mAah.js.map +1 -0
  13. package/dist/{material-plugin-BOCB7Stt.js → material-plugin-BUlqLsap.js} +3 -204
  14. package/dist/material-plugin-BUlqLsap.js.map +1 -0
  15. package/dist/{post-effect-compiler-Dw6zW2cG.js → post-effect-compiler-CRek8VxQ.js} +2 -2
  16. package/dist/{post-effect-compiler-Dw6zW2cG.js.map → post-effect-compiler-CRek8VxQ.js.map} +1 -1
  17. package/dist/render-path-Dx0learj.js +135 -0
  18. package/dist/render-path-Dx0learj.js.map +1 -0
  19. package/dist/render-texture-IuR0iFVa.js +174 -0
  20. package/dist/render-texture-IuR0iFVa.js.map +1 -0
  21. package/dist/{shader-material-BxQn9FT4.js → shader-material-BPb_oEZQ.js} +2 -2
  22. package/dist/{shader-material-BxQn9FT4.js.map → shader-material-BPb_oEZQ.js.map} +1 -1
  23. package/dist/{shader-material-DRZmqA_S.js → shader-material-CDQ0Y5kN.js} +3 -3
  24. package/dist/{shader-material-DRZmqA_S.js.map → shader-material-CDQ0Y5kN.js.map} +1 -1
  25. package/dist/{shader-pragma-DrFm5f5m.js → shader-pragma-BKCoZTTA.js} +2 -2
  26. package/dist/{shader-pragma-DrFm5f5m.js.map → shader-pragma-BKCoZTTA.js.map} +1 -1
  27. package/dist/{surface-shader-BgZchRBe.js → surface-shader-CwQ03yHG.js} +5 -4
  28. package/dist/{surface-shader-BgZchRBe.js.map → surface-shader-CwQ03yHG.js.map} +1 -1
  29. package/package.json +1 -1
  30. package/dist/ignifx-error-Dq2qJMkZ.js.map +0 -1
  31. package/dist/material-plugin-BOCB7Stt.js.map +0 -1
package/dist/index.js CHANGED
@@ -1,13 +1,15 @@
1
- import { a as CORE_ERROR_MESSAGES, c as THIRD_PARTY_ERROR_PREFIX, i as isIgnifxError, l as isValidErrorCode, n as assertNever, o as CoreErrorCode, r as formatErrorMessage, s as ErrorRange, t as IgnifxError } from "./ignifx-error-Dq2qJMkZ.js";
1
+ import { a as CORE_ERROR_MESSAGES, c as THIRD_PARTY_ERROR_PREFIX, i as isIgnifxError, l as isValidErrorCode, n as assertNever, o as CoreErrorCode, r as formatErrorMessage, s as ErrorRange, t as IgnifxError } from "./ignifx-error-oYdVnT1S.js";
2
2
  import { _ as smoothStep, a as clamp, c as deltaAngleDegrees, d as lerpAngleDegrees, f as moveTowards, g as sign, h as repeat, i as approximately, l as inverseLerp, m as radToDeg, n as EPSILON, o as clamp01, p as pingPong, r as RAD_TO_DEG, s as degToRad, t as DEG_TO_RAD, u as lerp, v as wrapAngleDegrees } from "./math-utils-BcDnL-gi.js";
3
3
  import { $ as basisToQuatToRef, A as setMeshReceiveShadows, B as localPosition, C as overrideSubtreeMaterials, D as setMeshId, E as setMeshBounds, F as updateMeshPositions$1, G as readWorldMatrix, H as localScale, I as updateMeshUvs$1, J as setNodeSelfVisible, K as reparentKeepingWorld, L as createNode, M as setMeshSubtreeVisible, N as updateMeshColors$1, O as setMeshMaterial, P as updateMeshNormals$1, Q as Mat4, R as disposeNode, S as disposeMeshTemplate, T as removeMeshFromScene, U as parentNode, V as localRotation, W as readNodeTag, X as worldMatrixVersion, Y as tagNode, Z as MAT4_IDENTITY, _ as createMeshFromGeometry, a as VEC3_ONE, b as createTorusMesh, c as VEC3_ZERO, d as cloneMeshUnderNode, f as collectSubtreeMeshes, g as createGroundMesh, h as createCylinderMesh, i as VEC3_LEFT, j as setMeshRenderOrder, k as setMeshPickable, l as Vec3, m as createCapsuleMesh, n as VEC3_DOWN, o as VEC3_RIGHT, p as createBoxMesh, q as setNodeName, r as VEC3_FORWARD, s as VEC3_UP, t as VEC3_BACKWARD, u as addMeshToScene, v as createPlaneMesh, w as recomputeMeshBounds, x as detachMeshBounds, y as createSphereMesh, z as linkParent } from "./vec3-T2PasQZv.js";
4
4
  import { t as Color } from "./color-DrR6GFTd.js";
5
- import { a as readSceneImageProcessing, c as setSceneEnvironmentRotation, l as setSceneFog, n as installSceneEnvironment, o as setSceneClearColor, r as loadSceneEnvironment, s as setSceneEnvironmentBlur, t as TONE_MAPPING_NAMES, u as setSceneImageProcessingOptions } from "./environment-C9AjYJgV.js";
6
- import { a as defineMaterialPlugin, c as MATERIAL_ALPHA_MODES, d as createStandardMaterialFromProps, f as markMaterialDirty, g as setPbrMetallicRoughness, h as setPbrBaseColor, i as MATERIAL_PLUGIN_SAMPLER_BUDGET, l as createDefaultMaterial, m as setMaterialAlpha, n as MATERIAL_PLUGIN_DEFAULT_PRIORITY, o as isLiteMaterialPluginPoint, r as MATERIAL_PLUGIN_RESERVED_NAMES, t as LITE_MATERIAL_PLUGIN_POINTS, u as createPbrMaterialFromProps } from "./material-plugin-BOCB7Stt.js";
5
+ import { a as readSceneImageProcessing, c as setSceneEnvironmentRotation, l as setSceneFog, n as installSceneEnvironment, o as setSceneClearColor, r as loadSceneEnvironment, s as setSceneEnvironmentBlur, t as TONE_MAPPING_NAMES, u as setSceneImageProcessingOptions } from "./environment-Cq2BmA96.js";
6
+ import { a as markMaterialDirty, c as setPbrBaseColor, i as createStandardMaterialFromProps, l as setPbrMetallicRoughness, n as createDefaultMaterial, r as createPbrMaterialFromProps, s as setMaterialAlpha, t as MATERIAL_ALPHA_MODES } from "./material-CGk5mAah.js";
7
7
  import { t as setOwnJsonProperty } from "./json-CzZZ6K4x.js";
8
8
  import { a as postEffectValuesCodec, i as declaredTextureBinding, n as POST_EFFECT_FUNCTION, o as asJsonArray, r as customEffect, s as asJsonObject, t as POST_EFFECT_BUILTIN_UNIFORMS } from "./post-effect-BHl7U56q.js";
9
+ import { n as installOffscreenRenderPath } from "./render-path-Dx0learj.js";
9
10
  import { a as SHADER_BLEND_MODES, c as SHADER_KINDS, d as SURFACE_HOOK_NAMES, f as SURFACE_UNIFORM_BLOCK, i as SHADER_ATTRIBUTE_NAMES, l as SHADER_TEXTURE_FALLBACKS, o as SHADER_CULL_MODES, r as LITE_SYSTEM_UNIFORM_NAMES, s as SHADER_INSTANCING_MODES, t as IGNIFX_UNIFORM_NAMES, u as SHADER_UNIFORM_TYPES } from "./shader-declaration-5q__jycG.js";
10
- import { acquireTexture, addTask, addToScene, buildFrameGraphTask, captureScreenshot, cloneTransformNode, createBloomPostProcessTask, createCopyToTextureTask, createCsmDirectionalShadowGenerator, createDirectionalLight, createEngine, createEsmDirectionalShadowGenerator, createFontFromBuffer, createFreeCamera, createGpuPicker, createHemisphericLight, createImageProcessingTask, createMeshFromData, createNullEngine, createPcfDirectionalShadowGenerator, createPcfSpotlightShadowGenerator, createPointLight, createRenderTarget, createRenderTask, createSceneContext, createSmaaPostProcessTask, createSpotLight, createStorageBuffer, createTexture2DFromPixels, disableOrthographicCamera, disposeEngine, disposePicker, disposeScene, disposeStorageBuffer, enableBoneControl, enableDeviceLostSceneRecovery, enableMaterialPlugins, enableMaterialStencil, enableOrthographicCamera, enablePbrLightmap, enableSkeletonShadows, enableStandardSkeleton, forceWebGpuDeviceLossForTesting, getEffectiveAspectRatio, getFrameGraph, getProjectionMatrix, getRenderTaskGpuTimings, getViewMatrix, getViewProjectionMatrix, isPbrMaterial, isShaderMaterial, loadTexture2D, onBeforeRender, pickAsync, pickWithRay, rebuildSceneRenderables, registerScene, registerSceneWithShadowSupport, releaseTexture, removeFromScene, resizeEngine, resolveCameraViewport, setGpuTimingEnabled, setShadowTaskCasterMeshes, setSubtreeVisible, setSurfaceSize, startEngine, stopEngine, updateStorageBuffer, updateTexture2DFromPixels } from "@babylonjs/lite";
11
+ import { a as defineMaterialPlugin, i as MATERIAL_PLUGIN_SAMPLER_BUDGET, n as MATERIAL_PLUGIN_DEFAULT_PRIORITY, o as isLiteMaterialPluginPoint, r as MATERIAL_PLUGIN_RESERVED_NAMES, t as LITE_MATERIAL_PLUGIN_POINTS } from "./material-plugin-BUlqLsap.js";
12
+ import { acquireTexture, addTask, addToScene, buildFrameGraphTask, captureScreenshot, cloneTransformNode, createBloomPostProcessTask, createCsmDirectionalShadowGenerator, createDirectionalLight, createEngine, createEsmDirectionalShadowGenerator, createFontFromBuffer, createFreeCamera, createGpuPicker, createHemisphericLight, createImageProcessingTask, createMeshFromData, createNullEngine, createPcfDirectionalShadowGenerator, createPcfSpotlightShadowGenerator, createPointLight, createRenderTarget, createSceneContext, createSmaaPostProcessTask, createSpotLight, createStorageBuffer, createTexture2DFromPixels, disableOrthographicCamera, disposeEngine, disposePicker, disposeScene, disposeStorageBuffer, enableBoneControl, enableDeviceLostSceneRecovery, enableMaterialPlugins, enableMaterialStencil, enableOrthographicCamera, enablePbrLightmap, enableSkeletonShadows, enableStandardSkeleton, forceWebGpuDeviceLossForTesting, getEffectiveAspectRatio, getFrameGraph, getProjectionMatrix, getRenderTaskGpuTimings, getViewMatrix, getViewProjectionMatrix, isPbrMaterial, isShaderMaterial, loadTexture2D, onBeforeRender, pickAsync, pickWithRay, rebuildSceneRenderables, registerScene, registerSceneWithShadowSupport, releaseTexture, removeFromScene, resizeEngine, resolveCameraViewport, setGpuTimingEnabled, setShadowTaskCasterMeshes, setSubtreeVisible, setSurfaceSize, startEngine, stopEngine, updateStorageBuffer, updateTexture2DFromPixels } from "@babylonjs/lite";
11
13
  //#region src/signal/signal.ts
12
14
  /** One attached handler. `handler === null` marks the entry dead and awaiting compaction. */
13
15
  var Connection = class {
@@ -3527,6 +3529,8 @@ var ComponentRegistry = class {
3527
3529
  schema,
3528
3530
  requires: statics.requires === void 0 ? EMPTY_TYPES : Object.freeze([...statics.requires]),
3529
3531
  allowMultiple: statics.allowMultiple ?? true,
3532
+ title: ownString(type, "title"),
3533
+ description: ownString(type, "description"),
3530
3534
  ancestors,
3531
3535
  trackedFields: schema === null ? EMPTY_NAMES : collectTrackedFields(schema),
3532
3536
  isScript,
@@ -3653,6 +3657,19 @@ function readStatics$1(type) {
3653
3657
  return type;
3654
3658
  }
3655
3659
  /**
3660
+ * Reads a string static the class declares itself. A subclass inherits its parent's statics in
3661
+ * JavaScript, and a parent's title would misname the subclass in an inspector.
3662
+ *
3663
+ * @param type - The component class.
3664
+ * @param name - The static's name.
3665
+ * @returns The class's own value, or `null` when it declares none or it is not a string.
3666
+ */
3667
+ function ownString(type, name) {
3668
+ if (!Object.hasOwn(type, name)) return null;
3669
+ const value = readStatics$1(type)[name];
3670
+ return typeof value === "string" ? value : null;
3671
+ }
3672
+ /**
3656
3673
  * Reports whether a class implements a callback, from its cached bit mask.
3657
3674
  *
3658
3675
  * @param info - The class info, or `null` for a plain component.
@@ -4799,7 +4816,7 @@ function createServiceKey(name) {
4799
4816
  *
4800
4817
  * @public
4801
4818
  */
4802
- const VERSION = "0.12.0";
4819
+ const VERSION = "0.14.0";
4803
4820
  //#endregion
4804
4821
  //#region src/assets/delivery-system.ts
4805
4822
  /**
@@ -6182,10 +6199,32 @@ function createRay() {
6182
6199
  var Camera = class Camera extends Component {
6183
6200
  /** The namespaced registration id. */
6184
6201
  static typeId = "ignifx/Camera";
6202
+ /** What the component does, in one line, for an inspector. */
6203
+ static description = "The camera an entity renders the world through; the entity's transform is the view.";
6185
6204
  /** At most one camera per entity: two views from one transform would be the same view. */
6186
6205
  static allowMultiple = false;
6187
6206
  /** The serialized field declarations (ADR-0004). */
6188
6207
  static schema = cameraSchema();
6208
+ /**
6209
+ * The texture this camera renders into every frame, instead of the canvas, or `null` for the
6210
+ * canvas (`docs/architecture/07-rendering.md` §2.11).
6211
+ *
6212
+ * @remarks
6213
+ * A camera with a render target is never the main camera, whatever its `priority`; it draws the
6214
+ * same scene from its own view into the texture, at the texture's aspect, in every frame it is
6215
+ * enabled. Runtime state: it is not serialized. Create the texture with
6216
+ * `app.renderer.createRenderTexture`.
6217
+ *
6218
+ * @example
6219
+ * ```ts
6220
+ * const minimap = app.renderer.createRenderTexture(256, 256);
6221
+ * overhead.renderTarget = minimap;
6222
+ * const pixels = await minimap.readPixels();
6223
+ * ```
6224
+ *
6225
+ * @beta
6226
+ */
6227
+ renderTarget = null;
6189
6228
  /** Applies the schema defaults, exactly as `Component.define` would. */
6190
6229
  constructor() {
6191
6230
  super();
@@ -6352,7 +6391,12 @@ var Camera = class Camera extends Component {
6352
6391
  * @internal
6353
6392
  */
6354
6393
  sync(renderer) {
6355
- renderer.readTargetSize(this.#targetSize);
6394
+ const target = this.renderTarget;
6395
+ if (target === null) renderer.readTargetSize(this.#targetSize);
6396
+ else {
6397
+ this.#targetSize.width = target.width;
6398
+ this.#targetSize.height = target.height;
6399
+ }
6356
6400
  this.#apply();
6357
6401
  }
6358
6402
  /** Writes every field whose value differs from the one last applied. */
@@ -6819,6 +6863,8 @@ const SKYBOX_SIZE_DEFAULT = 20;
6819
6863
  var Environment = class Environment extends Component {
6820
6864
  /** The namespaced registration id. */
6821
6865
  static typeId = "ignifx/Environment";
6866
+ /** What the component does, in one line, for an inspector. */
6867
+ static description = "The world's image-based lighting, skybox, fog, image processing, and clear colour.";
6822
6868
  /** One per entity, and effectively one per world: the fields are all scene state. */
6823
6869
  static allowMultiple = false;
6824
6870
  /** The serialized field declarations (ADR-0004). */
@@ -7164,7 +7210,7 @@ let surfaceLayer = null;
7164
7210
  * @internal
7165
7211
  */
7166
7212
  async function loadShaderSupport() {
7167
- const loaded = shaderLayer ?? await import("./shader-material-DRZmqA_S.js").then((n) => n.n);
7213
+ const loaded = shaderLayer ?? await import("./shader-material-CDQ0Y5kN.js").then((n) => n.n);
7168
7214
  shaderLayer = loaded;
7169
7215
  await loaded.loadShaderMaterialAdapter();
7170
7216
  return loaded;
@@ -7187,7 +7233,7 @@ function shaderSupport() {
7187
7233
  * @internal
7188
7234
  */
7189
7235
  async function loadSurfaceShaderSupport() {
7190
- const loaded = surfaceLayer ?? await import("./surface-shader-BgZchRBe.js");
7236
+ const loaded = surfaceLayer ?? await import("./surface-shader-CwQ03yHG.js");
7191
7237
  surfaceLayer = loaded;
7192
7238
  return loaded;
7193
7239
  }
@@ -8944,13 +8990,13 @@ function disposeScenePicker(picker) {
8944
8990
  *
8945
8991
  * Everything here is `@internal`.
8946
8992
  *
8947
- * ## Why these need a device (verified against `@babylonjs/lite@1.27.0`)
8993
+ * ## Why these need a device (verified against `@babylonjs/lite@1.34.0`)
8948
8994
  *
8949
- * - `isGpuTimingSupported` and `getRenderTaskGpuTimings` both start with
8950
- * `engine._device.features.has("timestamp-query")` (`lib/engine/engine.js`,
8951
- * `lib/engine/gpu-task-timing.js`). SwiftShader does not expose that feature, so on the CI
8952
- * software adapter the snapshot's `status` is `"unsupported"` — which is why coding standards §10
8953
- * says GPU-timing assertions are skipped there.
8995
+ * - `isGpuTimingSupported` and `getRenderTaskGpuTimings` both check
8996
+ * `engine._device.features.has("timestamp-query")` (`lib/engine/gpu-task-timing.js`). Chromium's
8997
+ * SwiftShader now offers that feature too (GI spike S4, 2026-11-02), but its timings measure a
8998
+ * software rasteriser, so coding standards §10 still skips GPU-timing assertions there; real
8999
+ * numbers come from the host-GPU `gpu-budget` project (§7).
8954
9000
  * - `setSurfaceSize` writes `canvas.width`/`canvas.height` (`lib/engine/surface.js`), and a null
8955
9001
  * engine has no canvas at all.
8956
9002
  * - `resizeEngine` walks the engine's surfaces and re-reads each canvas's client size; for an
@@ -10054,8 +10100,9 @@ function toPcfConfig(settings) {
10054
10100
  * Maps the shared settings onto a cascaded shadow map's configuration.
10055
10101
  *
10056
10102
  * @remarks
10057
- * `cascades` becomes `numCascades` and `maxDistance` becomes `shadowMaxZ`; Lite clamps the cascade
10058
- * count to four (`index.d.ts` 3515).
10103
+ * `cascades` becomes `numCascades`, `maxDistance` becomes `shadowMaxZ`, `cascadeLambda` becomes
10104
+ * `lambda` and `cascadeBlend` becomes `cascadeBlendPercentage`; Lite clamps the cascade count to
10105
+ * four (`index.d.ts` 4202–4227).
10059
10106
  *
10060
10107
  * @param settings - The declared settings.
10061
10108
  * @returns Lite's configuration.
@@ -10069,6 +10116,9 @@ function toCsmConfig(settings) {
10069
10116
  if (settings.darkness !== void 0) config.darkness = settings.darkness;
10070
10117
  if (settings.cascades !== void 0) config.numCascades = settings.cascades;
10071
10118
  if (settings.maxDistance !== void 0) config.shadowMaxZ = settings.maxDistance;
10119
+ if (settings.stabilizeCascades !== void 0) config.stabilizeCascades = settings.stabilizeCascades;
10120
+ if (settings.cascadeLambda !== void 0) config.lambda = settings.cascadeLambda;
10121
+ if (settings.cascadeBlend !== void 0) config.cascadeBlendPercentage = settings.cascadeBlend;
10072
10122
  return config;
10073
10123
  }
10074
10124
  /**
@@ -10219,6 +10269,20 @@ function readTaskTimings(engine) {
10219
10269
  tasks
10220
10270
  };
10221
10271
  }
10272
+ /**
10273
+ * Loads the render-to-texture module (`docs/architecture/07-rendering.md` §2.11).
10274
+ *
10275
+ * @remarks
10276
+ * It is loaded on first use, so a game that never renders to a texture ships none of it
10277
+ * (`CONSTITUTION.md` §2.5).
10278
+ *
10279
+ * @returns The function that creates a texture's render pass.
10280
+ *
10281
+ * @internal
10282
+ */
10283
+ async function loadRenderTextureFactory() {
10284
+ return (await import("./render-texture-IuR0iFVa.js")).createLiteRenderTexture;
10285
+ }
10222
10286
  //#endregion
10223
10287
  //#region src/render/image-processing-color.ts
10224
10288
  /** Lite's gamma: a plain 2.2 power, not the piecewise sRGB curve. */
@@ -10278,6 +10342,26 @@ function imageProcessedColor(r, g, b, a, state, out) {
10278
10342
  return out;
10279
10343
  }
10280
10344
  /**
10345
+ * Decodes an sRGB colour the way Lite's PBR fog block decodes its fog colour, for a clear colour
10346
+ * that is image processed later on the GPU (`rendering.hdr`).
10347
+ *
10348
+ * @param r - The sRGB red component, 0 to 1.
10349
+ * @param g - The sRGB green component, 0 to 1.
10350
+ * @param b - The sRGB blue component, 0 to 1.
10351
+ * @param a - The alpha, passed through.
10352
+ * @param out - Receives the linear colour.
10353
+ * @returns `out`.
10354
+ *
10355
+ * @internal
10356
+ */
10357
+ function linearClearColor(r, g, b, a, out) {
10358
+ out.r = decode(r);
10359
+ out.g = decode(g);
10360
+ out.b = decode(b);
10361
+ out.a = a;
10362
+ return out;
10363
+ }
10364
+ /**
10281
10365
  * Lite's fog-colour decode.
10282
10366
  *
10283
10367
  * @param value - The encoded channel.
@@ -10389,6 +10473,186 @@ function saturate(value) {
10389
10473
  return Math.min(Math.max(value, 0), 1);
10390
10474
  }
10391
10475
  //#endregion
10476
+ //#region src/render/render-texture.ts
10477
+ /**
10478
+ * The largest side of a render texture, in pixels.
10479
+ *
10480
+ * @public
10481
+ */
10482
+ const RENDER_TEXTURE_MAX_SIZE = 4096;
10483
+ /**
10484
+ * Checks a render texture's size.
10485
+ *
10486
+ * @param width - The requested width.
10487
+ * @param height - The requested height.
10488
+ * @throws IgnifxError with code `IGX-0730` for a side that is not a whole number from 1 to
10489
+ * {@link RENDER_TEXTURE_MAX_SIZE}.
10490
+ *
10491
+ * @internal
10492
+ */
10493
+ function assertRenderTextureSize(width, height) {
10494
+ const isSide = (side) => Number.isSafeInteger(side) && side >= 1 && side <= 4096;
10495
+ if (!isSide(width) || !isSide(height)) throw new IgnifxError(CoreErrorCode.invalidRenderTextureSize, `A render texture of ${String(width)}x${String(height)}: each side must be a whole number from 1 to ${String(RENDER_TEXTURE_MAX_SIZE)}.`, { context: {
10496
+ member: "app.renderer.createRenderTexture()",
10497
+ width,
10498
+ height,
10499
+ max: RENDER_TEXTURE_MAX_SIZE
10500
+ } });
10501
+ }
10502
+ /**
10503
+ * Tells each live texture which enabled, attached camera renders into it this frame.
10504
+ *
10505
+ * @param cameras - Every camera in the world, in creation order; the last one per texture wins.
10506
+ * @param live - The renderer's live textures; a camera aiming at any other is ignored.
10507
+ *
10508
+ * @internal
10509
+ */
10510
+ function bindFrameCameras(cameras, live) {
10511
+ for (const camera of cameras) {
10512
+ const target = camera.renderTarget;
10513
+ const lite = camera.lite.camera;
10514
+ if (target instanceof RenderTextureImpl && live.has(target) && lite !== null && camera.isEnabledInHierarchy) target.setFrameCamera(lite);
10515
+ }
10516
+ }
10517
+ /**
10518
+ * The renderer's render texture: the per-frame camera choice and the one-frame requests.
10519
+ *
10520
+ * @internal
10521
+ */
10522
+ var RenderTextureImpl = class {
10523
+ width;
10524
+ height;
10525
+ #owner;
10526
+ #pass = null;
10527
+ #creating = null;
10528
+ /** The camera whose `renderTarget` this is, as the current frame's sync found it. */
10529
+ #frameCamera = null;
10530
+ #requests = [];
10531
+ #isDisposed = false;
10532
+ /**
10533
+ * Creates the texture; its GPU pass is created on first use.
10534
+ *
10535
+ * @param owner - The renderer.
10536
+ * @param width - The checked width.
10537
+ * @param height - The checked height.
10538
+ */
10539
+ constructor(owner, width, height) {
10540
+ this.#owner = owner;
10541
+ this.width = width;
10542
+ this.height = height;
10543
+ }
10544
+ get isDisposed() {
10545
+ return this.#isDisposed;
10546
+ }
10547
+ /**
10548
+ * Resolves the texture's GPU pass, creating it once.
10549
+ *
10550
+ * @param member - The API member asking, for the error.
10551
+ * @returns The pass.
10552
+ */
10553
+ async pass(member) {
10554
+ this.assertUsable(member);
10555
+ this.#creating ??= this.#owner.createPass(this.width, this.height, member).then((pass) => {
10556
+ if (this.#isDisposed) pass.dispose();
10557
+ else this.#pass = pass;
10558
+ return pass;
10559
+ }, (error) => {
10560
+ this.#creating = null;
10561
+ throw error;
10562
+ });
10563
+ const pass = await this.#creating;
10564
+ this.assertUsable(member);
10565
+ return pass;
10566
+ }
10567
+ /**
10568
+ * Queues a render through a camera on the next frame.
10569
+ *
10570
+ * @param camera - The Lite camera.
10571
+ * @returns A promise that settles once that frame has been submitted.
10572
+ */
10573
+ request(camera) {
10574
+ return new Promise((resolve) => {
10575
+ this.#requests.push({
10576
+ camera,
10577
+ resolve
10578
+ });
10579
+ });
10580
+ }
10581
+ /**
10582
+ * Notes the camera that renders into this texture every frame. The render sync system calls it
10583
+ * for every enabled camera whose `renderTarget` this is, before {@link RenderTextureImpl.flush}.
10584
+ *
10585
+ * @param camera - The Lite camera.
10586
+ */
10587
+ setFrameCamera(camera) {
10588
+ this.#frameCamera = camera;
10589
+ if (this.#pass === null && this.#creating === null) this.pass("Camera.renderTarget").catch(() => null);
10590
+ }
10591
+ /**
10592
+ * Points the pass at this frame's camera: the oldest request's, else the `renderTarget` one's,
10593
+ * else none. Requests for that camera settle once the frame is submitted.
10594
+ */
10595
+ flush() {
10596
+ const pass = this.#pass;
10597
+ const requested = this.#requests[0]?.camera ?? null;
10598
+ const camera = requested ?? this.#frameCamera;
10599
+ this.#frameCamera = null;
10600
+ if (pass === null) return;
10601
+ pass.setCamera(camera);
10602
+ if (requested === null) return;
10603
+ const served = [];
10604
+ for (let index = this.#requests.length - 1; index >= 0; index -= 1) {
10605
+ const pending = this.#requests[index];
10606
+ if (pending !== void 0 && pending.camera === requested) {
10607
+ served.push(pending);
10608
+ this.#requests.splice(index, 1);
10609
+ }
10610
+ }
10611
+ queueMicrotask(() => {
10612
+ for (const pending of served) pending.resolve();
10613
+ });
10614
+ }
10615
+ async readPixels() {
10616
+ const data = await (await this.pass("RenderTexture.readPixels()")).read();
10617
+ return {
10618
+ width: this.width,
10619
+ height: this.height,
10620
+ data
10621
+ };
10622
+ }
10623
+ dispose() {
10624
+ if (this.#isDisposed) return;
10625
+ this.#isDisposed = true;
10626
+ this.#pass?.dispose();
10627
+ this.#pass = null;
10628
+ this.#owner.release(this);
10629
+ for (const pending of this.#requests.splice(0)) pending.resolve();
10630
+ }
10631
+ /**
10632
+ * Refuses a disposed texture.
10633
+ *
10634
+ * @param member - The API member asking.
10635
+ * @throws IgnifxError with code `IGX-0731` once disposed.
10636
+ */
10637
+ assertUsable(member) {
10638
+ if (this.#isDisposed) throw renderTextureUnusableError(member);
10639
+ }
10640
+ };
10641
+ /**
10642
+ * The error for a disposed or foreign render texture.
10643
+ *
10644
+ * @param member - The API member asking.
10645
+ * @returns The error.
10646
+ *
10647
+ * @internal
10648
+ */
10649
+ function renderTextureUnusableError(member) {
10650
+ return new IgnifxError(CoreErrorCode.renderTextureUnusable, `${member}: the render texture is disposed or belongs to another app.`, {
10651
+ context: { member },
10652
+ hint: "Create a render texture with this app's app.renderer.createRenderTexture() and keep it until you dispose it."
10653
+ });
10654
+ }
10655
+ //#endregion
10392
10656
  //#region src/render/rendering-settings.ts
10393
10657
  /**
10394
10658
  * The `rendering` project settings section (`docs/architecture/04-extensions.md` §5,
@@ -10473,7 +10737,8 @@ function defaultRenderingSettings() {
10473
10737
  b: 0,
10474
10738
  a: 1
10475
10739
  },
10476
- brdfLut: DEFAULT_BRDF_LUT_ADDRESS
10740
+ brdfLut: DEFAULT_BRDF_LUT_ADDRESS,
10741
+ hdr: false
10477
10742
  };
10478
10743
  }
10479
10744
  /**
@@ -10513,7 +10778,8 @@ function renderingSettingsSchema() {
10513
10778
  useFloatingOrigin: bool(false, { tooltip: "Eye-relative upload; needs useHighPrecisionMatrix." }),
10514
10779
  requiredLimits: map(f64(0, { min: 0 }), { tooltip: "Extra WebGPU device limits to request." }),
10515
10780
  clearColor: color(DEFAULT_CLEAR_COLOR, { tooltip: "The colour the scene is cleared to, in sRGB. A Camera or Environment overrides it." }),
10516
- brdfLut: str(DEFAULT_BRDF_LUT_ADDRESS, { tooltip: "Address of the RGBD BRDF lookup table." })
10781
+ brdfLut: str(DEFAULT_BRDF_LUT_ADDRESS, { tooltip: "Address of the RGBD BRDF lookup table." }),
10782
+ hdr: bool(false, { tooltip: "Render in HDR (rgba16float) and tone map in one final pass. PBR materials only for now." })
10517
10783
  });
10518
10784
  }
10519
10785
  /**
@@ -10697,6 +10963,20 @@ var RendererImpl = class {
10697
10963
  #pickIdentities = /* @__PURE__ */ new WeakMap();
10698
10964
  /** The open overlays, by their Lite scene. */
10699
10965
  #overlays = /* @__PURE__ */ new Map();
10966
+ /** The render textures this renderer created and has not disposed. */
10967
+ #renderTextures = /* @__PURE__ */ new Set();
10968
+ /** What the render textures ask of this renderer. */
10969
+ #renderTextureOwner = {
10970
+ createPass: async (width, height, member) => {
10971
+ this.#assertRenderLoop(member);
10972
+ const create = await loadRenderTextureFactory();
10973
+ this.#assertRenderLoop(member);
10974
+ return create(this.engine, this.scene, width, height);
10975
+ },
10976
+ release: (texture) => {
10977
+ this.#renderTextures.delete(texture);
10978
+ }
10979
+ };
10700
10980
  #warmUp = null;
10701
10981
  #syncSystem = null;
10702
10982
  /** Adapter chunks a component asked for; `app.start()` waits for them before it reconciles. */
@@ -11034,6 +11314,82 @@ var RendererImpl = class {
11034
11314
  return captureFrame(this.engine);
11035
11315
  }
11036
11316
  /**
11317
+ * Creates an offscreen texture a camera can render into.
11318
+ *
11319
+ * @param width - The width, in pixels.
11320
+ * @param height - The height, in pixels.
11321
+ * @returns The texture.
11322
+ * @throws IgnifxError with code `IGX-0730` for a side out of range, `IGX-0106` once disposed.
11323
+ */
11324
+ createRenderTexture(width, height) {
11325
+ if (this.#isDisposed) throw new IgnifxError(CoreErrorCode.appDisposed, "The app has been disposed; app.renderer.createRenderTexture() is no longer available.", { context: { member: "app.renderer.createRenderTexture()" } });
11326
+ assertRenderTextureSize(width, height);
11327
+ const texture = new RenderTextureImpl(this.#renderTextureOwner, width, height);
11328
+ this.#renderTextures.add(texture);
11329
+ return texture;
11330
+ }
11331
+ /**
11332
+ * Renders the scene through a camera into a texture on the next frame.
11333
+ *
11334
+ * @param camera - The camera.
11335
+ * @param texture - The texture.
11336
+ * @returns A promise that settles once the frame has been submitted.
11337
+ * @throws IgnifxError with code `IGX-0729`, `IGX-0731` or `IGX-0732`; see the interface.
11338
+ */
11339
+ async renderToTexture(camera, texture) {
11340
+ const member = "app.renderer.renderToTexture()";
11341
+ const owned = this.#ownedRenderTexture(texture, member);
11342
+ const lite = camera.lite.camera;
11343
+ if (lite === null) throw new IgnifxError(CoreErrorCode.renderTextureCameraDetached, "renderToTexture() needs a camera attached to an entity.", {
11344
+ context: { member },
11345
+ hint: "Pass a Camera component that is on an entity, before the entity is destroyed."
11346
+ });
11347
+ this.#assertRenderLoop(member);
11348
+ await owned.pass(member);
11349
+ await owned.request(lite);
11350
+ }
11351
+ /**
11352
+ * Points every render texture's pass at this frame's camera. The `PreRender` sync calls it after
11353
+ * the main camera is chosen.
11354
+ *
11355
+ * @param cameras - Every camera in the world, in creation order.
11356
+ *
11357
+ * @internal
11358
+ */
11359
+ syncRenderTextures(cameras) {
11360
+ if (this.isHeadless || this.#renderTextures.size === 0) return;
11361
+ bindFrameCameras(cameras, this.#renderTextures);
11362
+ for (const texture of this.#renderTextures) texture.flush();
11363
+ }
11364
+ /**
11365
+ * Narrows a texture to one this renderer made and has not disposed.
11366
+ *
11367
+ * @param texture - The texture.
11368
+ * @param member - The API member asking.
11369
+ * @returns The texture.
11370
+ * @throws IgnifxError with code `IGX-0731` otherwise.
11371
+ */
11372
+ #ownedRenderTexture(texture, member) {
11373
+ if (!(texture instanceof RenderTextureImpl) || !this.#renderTextures.has(texture)) throw renderTextureUnusableError(member);
11374
+ return texture;
11375
+ }
11376
+ /**
11377
+ * Refuses render-to-texture work that no frame would ever carry out.
11378
+ *
11379
+ * @param member - The API member asking.
11380
+ * @throws IgnifxError with code `IGX-0729` on a headless or disposed app, or while no render loop
11381
+ * runs.
11382
+ */
11383
+ #assertRenderLoop(member) {
11384
+ if (this.isHeadless || this.#isDisposed || !this.#isLoopRunning || !this.#isSceneRegistered) throw new IgnifxError(CoreErrorCode.renderTextureNeedsRenderLoop, `${member} needs a canvas-backed app whose render loop is running.`, {
11385
+ context: {
11386
+ member,
11387
+ headless: this.isHeadless
11388
+ },
11389
+ hint: this.isHeadless ? "A headless app draws nothing. Create the app with a canvas." : "Call it after app.start() has resolved, and not after app.stop()."
11390
+ });
11391
+ }
11392
+ /**
11037
11393
  * The latest per-task GPU timing snapshot.
11038
11394
  *
11039
11395
  * @returns The snapshot.
@@ -11313,6 +11669,7 @@ var RendererImpl = class {
11313
11669
  }
11314
11670
  /**
11315
11671
  * Re-applies the clear colour when the scene's image processing changed since it was written.
11672
+ * With `rendering.hdr` on it runs the HDR output pass's per-frame update instead.
11316
11673
  *
11317
11674
  * @remarks
11318
11675
  * The `PreRender` system calls it every frame, after the `Environment` has written its image
@@ -11322,6 +11679,11 @@ var RendererImpl = class {
11322
11679
  * @internal
11323
11680
  */
11324
11681
  refreshClearColor() {
11682
+ const hdr = this.#presenter?.hdr ?? null;
11683
+ if (hdr !== null) {
11684
+ hdr.update(this.#isSceneRegistered);
11685
+ return;
11686
+ }
11325
11687
  const current = readSceneImageProcessing(this.scene, this.#processingScratch);
11326
11688
  if (!sameImageProcessing(current, this.#clearProcessing)) this.#writeClearColor(current);
11327
11689
  }
@@ -11336,6 +11698,11 @@ var RendererImpl = class {
11336
11698
  applied.contrast = processing.contrast;
11337
11699
  applied.curve = processing.curve;
11338
11700
  const authored = this.#authoredClear;
11701
+ if ((this.#presenter?.hdr ?? null) !== null) {
11702
+ const out = linearClearColor(authored.r, authored.g, authored.b, authored.a, this.#processedClear);
11703
+ setSceneClearColor(this.scene, out.r, out.g, out.b, out.a);
11704
+ return;
11705
+ }
11339
11706
  const out = imageProcessedColor(authored.r, authored.g, authored.b, authored.a, processing, this.#processedClear);
11340
11707
  setSceneClearColor(this.scene, out.r, out.g, out.b, out.a);
11341
11708
  }
@@ -11482,6 +11849,7 @@ var RendererImpl = class {
11482
11849
  this.#isDisposed = true;
11483
11850
  this.#afterRebuild.length = 0;
11484
11851
  for (const overlay of this.#overlays.values()) overlay.dispose();
11852
+ for (const texture of this.#renderTextures) texture.dispose();
11485
11853
  const picker = this.#picker;
11486
11854
  this.#picker = null;
11487
11855
  if (picker !== null) disposeScenePicker(picker);
@@ -11640,6 +12008,8 @@ function noMatrices() {
11640
12008
  var InstancedMeshRenderer = class InstancedMeshRenderer extends Component {
11641
12009
  /** The namespaced registration id. */
11642
12010
  static typeId = "ignifx/InstancedMeshRenderer";
12011
+ /** What the component does, in one line, for an inspector. */
12012
+ static description = "Draws one mesh many times from a caller-owned matrix slab, in a single draw call, with optional GPU culling and a coarser mesh for far instances.";
11643
12013
  /** Several instanced renderers on one entity draw several clouds from one transform. */
11644
12014
  static allowMultiple = true;
11645
12015
  /** The serialized field declarations (ADR-0004). */
@@ -12650,7 +13020,10 @@ function toShadowSettings(declared) {
12650
13020
  bias: declared.bias,
12651
13021
  normalBias: declared.normalBias,
12652
13022
  darkness: declared.darkness,
12653
- cascades: declared.cascades
13023
+ cascades: declared.cascades,
13024
+ stabilizeCascades: declared.stabilizeCascades,
13025
+ cascadeLambda: declared.cascadeLambda,
13026
+ cascadeBlend: declared.cascadeBlend
12654
13027
  };
12655
13028
  if (declared.maxDistance > 0) settings.maxDistance = declared.maxDistance;
12656
13029
  return settings;
@@ -12706,6 +13079,8 @@ const TRANSLATION_COLUMN = 12;
12706
13079
  var Light = class Light extends Component {
12707
13080
  /** The namespaced registration id. */
12708
13081
  static typeId = "ignifx/Light";
13082
+ /** What the component does, in one line, for an inspector. */
13083
+ static description = "A directional, point, spot, or hemispheric light, with optional shadow casting.";
12709
13084
  /** At most one light per entity: two lights from one transform want two entities. */
12710
13085
  static allowMultiple = false;
12711
13086
  /** The serialized field declarations (ADR-0004). */
@@ -13094,6 +13469,17 @@ function lightSchema() {
13094
13469
  maxDistance: f32(0, {
13095
13470
  min: 0,
13096
13471
  tooltip: "Shadow distance in metres; 0 takes Lite's default."
13472
+ }),
13473
+ stabilizeCascades: bool(false, { tooltip: "CSM only: a stable cascade fit, so shadow edges do not shimmer as the camera moves." }),
13474
+ cascadeLambda: f32(.5, {
13475
+ min: 0,
13476
+ max: 1,
13477
+ tooltip: "CSM only: cascade split spacing, 0 even to 1 logarithmic (more detail near the camera)."
13478
+ }),
13479
+ cascadeBlend: f32(.1, {
13480
+ min: 0,
13481
+ max: 1,
13482
+ tooltip: "CSM only: the fraction of a cascade that fades into the next; 0 shows hard seams."
13097
13483
  })
13098
13484
  }, { tooltip: "Shadow casting; point and hemispheric lights cannot cast (IGX-0703)." }),
13099
13485
  includeOnly: array(entityRef(), [], { tooltip: "Light only these entities' renderers." }),
@@ -14810,7 +15196,7 @@ let effectLayer = null;
14810
15196
  * @internal
14811
15197
  */
14812
15198
  async function loadPostEffectSupport() {
14813
- const [compiler, effects] = await Promise.all([compilerLayer ?? import("./post-effect-compiler-Dw6zW2cG.js"), effectLayer ?? import("./effect-task-CMbuO6Kb.js")]);
15199
+ const [compiler, effects] = await Promise.all([compilerLayer ?? import("./post-effect-compiler-CRek8VxQ.js"), effectLayer ?? import("./effect-task-CMbuO6Kb.js")]);
14814
15200
  compilerLayer = compiler;
14815
15201
  effectLayer = effects;
14816
15202
  }
@@ -14948,7 +15334,7 @@ function createShaderLoader() {
14948
15334
  type: SHADER_ASSET_TYPE,
14949
15335
  extensions: SHADER_FILE_EXTENSIONS,
14950
15336
  async load(ctx) {
14951
- const [source, pragma] = await Promise.all([ctx.fetchText(), import("./shader-pragma-DrFm5f5m.js")]);
15337
+ const [source, pragma] = await Promise.all([ctx.fetchText(), import("./shader-pragma-BKCoZTTA.js")]);
14952
15338
  const declaration = pragma.parseShaderDeclaration(source, ctx.address);
14953
15339
  await loadShaderSupport();
14954
15340
  if (declaration.kind === "surface") await loadSurfaceShaderSupport();
@@ -15934,6 +16320,8 @@ function asMesh(node) {
15934
16320
  var MeshRenderer = class MeshRenderer extends Component {
15935
16321
  /** The namespaced registration id. */
15936
16322
  static typeId = "ignifx/MeshRenderer";
16323
+ /** What the component does, in one line, for an inspector. */
16324
+ static description = "Draws one clone of a mesh asset with a material.";
15937
16325
  /** Several renderers on one entity draw several meshes from one transform, which is useful. */
15938
16326
  static allowMultiple = true;
15939
16327
  /** The serialized field declarations (ADR-0004). */
@@ -16358,6 +16746,8 @@ const NO_SKELETONS = Object.freeze([]);
16358
16746
  var Model = class Model extends Component {
16359
16747
  /** The namespaced registration id. */
16360
16748
  static typeId = "ignifx/Model";
16749
+ /** What the component does, in one line, for an inspector. */
16750
+ static description = "One instance of a loaded glTF, cloned under the entity's node.";
16361
16751
  /** One model per entity: a second instance under the same transform wants its own entity. */
16362
16752
  static allowMultiple = false;
16363
16753
  /** The serialized field declarations (ADR-0004). */
@@ -17251,6 +17641,8 @@ function nextLink(engine, links, source) {
17251
17641
  var PostProcessStack = class PostProcessStack extends Component {
17252
17642
  /** The namespaced registration id. */
17253
17643
  static typeId = "ignifx/PostProcessStack";
17644
+ /** What the component does, in one line, for an inspector. */
17645
+ static description = "Bloom, SMAA, image processing, and custom .post.wgsl effects, inserted into the scene's frame graph.";
17254
17646
  /** One chain per camera entity; a second would fight the first for the swapchain. */
17255
17647
  static allowMultiple = false;
17256
17648
  /** The serialized field declarations (ADR-0004). */
@@ -17724,6 +18116,7 @@ var RenderSyncSystem = class {
17724
18116
  }
17725
18117
  castersChanged = this.#hasEsmMaterialChanged(lights) || castersChanged;
17726
18118
  this.#selectCamera(world, cameras);
18119
+ renderer.syncRenderTextures(cameras);
17727
18120
  topologyChanged = this.#applyEnvironment(world) || topologyChanged;
17728
18121
  renderer.refreshClearColor();
17729
18122
  this.#applyStacks(world);
@@ -17753,6 +18146,7 @@ var RenderSyncSystem = class {
17753
18146
  const camera = cameras[index];
17754
18147
  if (camera === void 0 || !camera.isEnabledInHierarchy) continue;
17755
18148
  camera.sync(renderer);
18149
+ if (camera.renderTarget !== null) continue;
17756
18150
  if (best === null || camera.priority > best.priority) best = camera;
17757
18151
  }
17758
18152
  world.setMainCamera(best);
@@ -21571,6 +21965,8 @@ function transformIsNotRemovable() {
21571
21965
  var Transform = class extends Component {
21572
21966
  /** The registration id of the one component every entity carries. */
21573
21967
  static typeId = "ignifx/Transform";
21968
+ /** What the component does, in one line, for an inspector. */
21969
+ static description = "The entity's local position, rotation, and scale; every entity has exactly one, stored as its transform block.";
21574
21970
  /** An entity has exactly one transform. */
21575
21971
  static allowMultiple = false;
21576
21972
  /** Creates an unbound transform. The entity constructor binds it to a Lite node immediately. */
@@ -23660,6 +24056,44 @@ const Visit = {
23660
24056
  placed: 2
23661
24057
  };
23662
24058
  /**
24059
+ * The app each live extension object is installed in.
24060
+ *
24061
+ * @remarks
24062
+ * The one piece of state shared between apps, because the question "is this object already in
24063
+ * another app?" has no answer inside a single app. An extension object may keep per-app state in
24064
+ * its factory's closure (`physics()` does), so installing it twice would let the second app take
24065
+ * over the first one's services. Created on first use (coding standards §4: nothing allocated at
24066
+ * module scope), and keyed weakly, so a dropped extension is collected.
24067
+ */
24068
+ let installedExtensions = null;
24069
+ /**
24070
+ * Records that an app installs extension objects, refusing any another live app already installed.
24071
+ *
24072
+ * @param list - The extensions.
24073
+ * @param app - The installing app.
24074
+ * @throws IgnifxError with code `IGX-0411` for an object another live app installed.
24075
+ */
24076
+ function claimExtensions(list, app) {
24077
+ const installed = installedExtensions ??= /* @__PURE__ */ new WeakMap();
24078
+ for (const extension of list) {
24079
+ const owner = installed.get(extension);
24080
+ if (owner !== void 0 && owner !== app) throw new IgnifxError(CoreErrorCode.extensionInstalledTwice, `The ${extension.name} extension object is already installed in another app that has not been disposed.`, {
24081
+ context: { extension: extension.name },
24082
+ hint: "Call the extension's factory again for each app, for example physics() once per createApp."
24083
+ });
24084
+ }
24085
+ for (const extension of list) installed.set(extension, app);
24086
+ }
24087
+ /**
24088
+ * Forgets an app's extension objects, so a new app may install them.
24089
+ *
24090
+ * @param list - The extensions.
24091
+ * @param app - The app being disposed.
24092
+ */
24093
+ function releaseExtensions(list, app) {
24094
+ for (const extension of list) if (installedExtensions?.get(extension) === app) installedExtensions.delete(extension);
24095
+ }
24096
+ /**
23663
24097
  * The extension host of one app.
23664
24098
  *
23665
24099
  * @internal
@@ -23691,12 +24125,29 @@ var ExtensionHost = class {
23691
24125
  *
23692
24126
  * @param list - The implicit core extension followed by the game's list.
23693
24127
  * @returns A promise that settles once every `register` hook has finished.
23694
- * @throws IgnifxError with code `IGX-0406` on a duplicate name, `IGX-0403` on a missing required
24128
+ * @throws IgnifxError with code `IGX-0411` for an extension object another live app installed,
24129
+ * `IGX-0406` on a duplicate name, `IGX-0403` on a missing required
23695
24130
  * extension, `IGX-0402` on a `requires` cycle, or `IGX-0404` on an `engine` mismatch in
23696
24131
  * development.
23697
24132
  */
23698
24133
  async register(list) {
23699
24134
  const sorted = this.#sort(list);
24135
+ const app = this.#options.app;
24136
+ claimExtensions(sorted, app);
24137
+ try {
24138
+ await this.#registerSorted(sorted);
24139
+ } catch (error) {
24140
+ releaseExtensions(sorted, app);
24141
+ throw error;
24142
+ }
24143
+ }
24144
+ /**
24145
+ * Validates and registers sorted extensions, in order.
24146
+ *
24147
+ * @param sorted - The extensions, dependencies first.
24148
+ * @returns A promise that settles once every `register` hook has finished.
24149
+ */
24150
+ async #registerSorted(sorted) {
23700
24151
  for (let index = 0; index < sorted.length; index += 1) {
23701
24152
  const extension = sorted[index];
23702
24153
  if (extension !== void 0) this.#checkEngineRange(extension);
@@ -23764,6 +24215,7 @@ var ExtensionHost = class {
23764
24215
  this.#reportTeardown(error);
23765
24216
  }
23766
24217
  this.#disposers.length = 0;
24218
+ releaseExtensions(this.#sorted, this.#options.app);
23767
24219
  }
23768
24220
  /**
23769
24221
  * Whether {@link ExtensionHost.dispose} has begun, for the context's dispose-time checks.
@@ -25114,132 +25566,6 @@ function isWebGpuAvailable() {
25114
25566
  return typeof navigator !== "undefined" && "gpu" in navigator;
25115
25567
  }
25116
25568
  //#endregion
25117
- //#region src/lite/gpu/render-path.ts
25118
- /**
25119
- * The offscreen render path (`docs/architecture/07-rendering.md` §2.7): the frame graph a scene gets
25120
- * when the project declares `rendering.features.postProcessing`.
25121
- *
25122
- * Everything here needs a device.
25123
- *
25124
- * ## Why the default render task is not good enough
25125
- *
25126
- * `createSceneContext` appends a task named `"scene"` that draws straight into the surface's
25127
- * swapchain target — `surface.scRT` for a single-sample surface, or an MSAA colour target that
25128
- * resolves into `scRT` (`lib/scene/scene-core.js` 74-79). Either way the scene's colour ends up in
25129
- * the swapchain texture, and a post-process pass cannot read it: `createSurface` configures the
25130
- * canvas context with no `usage` (`lib/engine/surface.js` 30), so the swapchain texture is
25131
- * `RENDER_ATTACHMENT` only. Binding it as a sampled texture fails WebGPU validation, the whole
25132
- * frame's command buffer is rejected, and the page presents black. That is exactly what the Phase 2
25133
- * visual suite measured, and it is why this module exists.
25134
- *
25135
- * Lite offers no way to retarget the default task after the fact — `RenderTaskConfig.rt` is read
25136
- * when the task is created, and `FrameGraph`'s public surface is only `build`/`execute`/`dispose`
25137
- * (`index.d.ts` 5367). So the scene is created with `defaultRenderTask: false` and this module
25138
- * builds the replacement.
25139
- *
25140
- * ## The graph it builds
25141
- *
25142
- * ```text
25143
- * [shadow] → scene ──→ sceneColor ──→ present ──→ swapchain
25144
- * └─ (a PostProcessStack appends its effects here, and disables present)
25145
- * ```
25146
- *
25147
- * - `scene` is a normal `createRenderTask`. With MSAA it draws into a multisampled colour target
25148
- * that owns its depth and resolves into `sceneColor` through `rst`; without MSAA it draws into
25149
- * `sceneColor` directly with a separate depth target, which is the same split Lite's own default
25150
- * uses (`RenderTaskConfig.depth`, `index.d.ts` 9782).
25151
- * - `sceneColor` is an ordinary `createRenderTarget`, so `buildRenderTarget` allocates it with
25152
- * `RENDER_ATTACHMENT | TEXTURE_BINDING | COPY_SRC | COPY_DST` (`lib/engine/render-target.js`) —
25153
- * the `TEXTURE_BINDING` the swapchain lacks.
25154
- * - `present` is a `createCopyToTextureTask` from `sceneColor` to the swapchain. Copying *into* the
25155
- * swapchain is supported and takes the blit path (`lib/frame-graph/copy-to-texture-task.js`,
25156
- * `swapAsView`); copying *out of* it is refused (Lite error 80), which is the same limit stated
25157
- * from the other side.
25158
- * - The swapchain is written every frame whatever else happens: with no chain, `present` does it;
25159
- * with a chain, the chain's last effect does it and `present` is switched off
25160
- * ({@link ScenePresenter.setPresentEnabled}).
25161
- *
25162
- * ## Resize
25163
- *
25164
- * Every target here is sized by passing the **surface** as `RenderTargetDescriptor.size`, which
25165
- * `resolveSize` re-reads from `canvas.width`/`canvas.height` on every `buildRenderTarget`
25166
- * (`lib/engine/render-target.js`). A surface resize calls the scene's `_resize`, which is
25167
- * `frameGraph.build()` (`lib/scene/scene-core.js` 67-68): every target is reallocated at the new
25168
- * size and every task re-records, which is also what refreshes the bind groups that captured the old
25169
- * texture views. Nothing here has to observe the canvas itself, and nothing is eagerly allocated —
25170
- * `createRenderTargetTexture` would be, and Lite rejects a surface as its size for exactly that
25171
- * reason.
25172
- */
25173
- /** The depth/stencil format Lite's own default render task uses (`lib/scene/scene-core.js` 76-77). */
25174
- const DEPTH_STENCIL_FORMAT = "depth24plus-stencil8";
25175
- /**
25176
- * Builds the scene's render task into an offscreen target and the blit that composites it, and
25177
- * appends both to the scene's frame graph.
25178
- *
25179
- * @remarks
25180
- * Call it immediately after `createSceneContext(engine, { defaultRenderTask: false })` and before
25181
- * `registerScene`: `addTask` appends, so calling it first is what puts `"scene"` ahead of everything
25182
- * a feature adds later, and `registerSceneWithShadowSupport` still unshifts its own `"shadow"` task
25183
- * in front of both.
25184
- *
25185
- * @param engine - The engine, which is also the primary surface.
25186
- * @param scene - The scene created with no default render task.
25187
- * @returns The presenter a `PostProcessStack` builds its chain against.
25188
- *
25189
- * @example
25190
- * ```ts
25191
- * const scene = createSceneContext(engine, { defaultRenderTask: false });
25192
- * const presenter = installOffscreenRenderPath(engine, scene);
25193
- * ```
25194
- *
25195
- * @internal
25196
- */
25197
- function installOffscreenRenderPath(engine, scene) {
25198
- const isMultisampled = engine.msaaSamples > 1;
25199
- const sceneColor = createRenderTarget({
25200
- lbl: "ignifx:scene-color",
25201
- format: engine.format,
25202
- samples: 1,
25203
- size: engine
25204
- });
25205
- const config = {
25206
- name: "scene",
25207
- rt: isMultisampled ? createRenderTarget({
25208
- lbl: "ignifx:scene-color-msaa",
25209
- format: engine.format,
25210
- dFormat: DEPTH_STENCIL_FORMAT,
25211
- samples: engine.msaaSamples,
25212
- size: engine
25213
- }) : sceneColor
25214
- };
25215
- if (isMultisampled) config.rst = sceneColor;
25216
- else config.depth = createRenderTarget({
25217
- lbl: "ignifx:scene-depth",
25218
- dFormat: DEPTH_STENCIL_FORMAT,
25219
- samples: 1,
25220
- size: engine
25221
- });
25222
- addTask(scene, createRenderTask(config, engine, scene));
25223
- const present = createCopyToTextureTask({
25224
- name: "ignifx:present",
25225
- sourceTexture: sceneColor,
25226
- targetTexture: engine.scRT
25227
- }, engine, scene);
25228
- addTask(scene, present);
25229
- let isPresentEnabled = true;
25230
- return {
25231
- sceneColor,
25232
- swapchain: engine.scRT,
25233
- setPresentEnabled(enabled) {
25234
- isPresentEnabled = enabled;
25235
- present.executionEnabled = enabled;
25236
- },
25237
- get isPresentEnabled() {
25238
- return isPresentEnabled;
25239
- }
25240
- };
25241
- }
25242
- //#endregion
25243
25569
  //#region src/lite/render.ts
25244
25570
  /**
25245
25571
  * The GPU half of the Babylon Lite adapter: the two calls that need a real WebGPU device. They are
@@ -25333,6 +25659,8 @@ function createHeadlessEngine() {
25333
25659
  * @param options - Device and surface options; see `createWebGpuEngine`.
25334
25660
  * @param features - Which render path to build.
25335
25661
  * @param features.postProcessing - `true` to render into an offscreen target and composite it.
25662
+ * @param features.hdr - `true` to render into an `rgba16float` target and tone map it in a final
25663
+ * pass (`./gpu/hdr-output.ts`, its own chunk, loaded only then). Implies the offscreen path.
25336
25664
  * @returns The engine, the scene, and the presenter when there is one.
25337
25665
  * @throws IgnifxError with code `IGX-0701` when WebGPU is unavailable.
25338
25666
  *
@@ -25341,13 +25669,17 @@ function createHeadlessEngine() {
25341
25669
  async function createRenderEngine(canvas, options, features) {
25342
25670
  assertWebGpuAvailable();
25343
25671
  const engine = await createWebGpuEngine(canvas, options);
25344
- const offscreen = features?.postProcessing === true;
25672
+ const hdr = features?.hdr === true;
25673
+ const offscreen = hdr || features?.postProcessing === true;
25345
25674
  const scene = createRenderScene(engine, { offscreen });
25675
+ let presenter = null;
25676
+ if (hdr) presenter = (await import("./hdr-output-DDpIo4Q5.js")).installHdrRenderPath(engine, scene);
25677
+ else if (offscreen) presenter = installOffscreenRenderPath(engine, scene);
25346
25678
  return {
25347
25679
  engine,
25348
25680
  scene,
25349
25681
  isHeadless: false,
25350
- presenter: offscreen ? installOffscreenRenderPath(engine, scene) : null
25682
+ presenter
25351
25683
  };
25352
25684
  }
25353
25685
  /**
@@ -33688,6 +34020,8 @@ var AppImpl = class {
33688
34020
  #deviceLoss = null;
33689
34021
  #isLoopRunning = false;
33690
34022
  #isRunning = false;
34023
+ /** Whether `onStart` has run: it runs once per app, so a start after `stop()` only restarts the loop. */
34024
+ #hasStarted = false;
33691
34025
  #isDisposed = false;
33692
34026
  /**
33693
34027
  * Runs one ignifx frame from Babylon Lite's render loop.
@@ -33891,6 +34225,10 @@ var AppImpl = class {
33891
34225
  * Runs extension `onStart` hooks and starts the frame loop
33892
34226
  * (`docs/architecture/01-lifecycle-and-time.md` §1).
33893
34227
  *
34228
+ * @remarks
34229
+ * A no-op while the app runs. After `stop()` it restarts the loop where it stopped: `onStart`
34230
+ * hooks run only on the first start, and the render scene stays registered.
34231
+ *
33894
34232
  * @returns A promise that settles once the first frame has been submitted. In headless mode there
33895
34233
  * is no loop to start, so it settles once the hooks have run.
33896
34234
  * @throws IgnifxError with code `IGX-0106` when the app has been disposed.
@@ -33898,13 +34236,16 @@ var AppImpl = class {
33898
34236
  async start() {
33899
34237
  this.#assertUsable("app.start()");
33900
34238
  if (this.#isRunning) return;
33901
- await this.#host.start();
34239
+ if (!this.#hasStarted) {
34240
+ await this.#host.start();
34241
+ this.#hasStarted = true;
34242
+ }
33902
34243
  this.#isRunning = true;
33903
34244
  this.#applicationListeners(true);
33904
34245
  const handles = this.#handles;
33905
34246
  if (this.isHeadless || handles === null) return;
33906
34247
  if (this.#frameCallback !== null) throw new IgnifxError(CoreErrorCode.appNotReady, "app.start() already registered this world's frame callback.", { context: { member: "app.start()" } });
33907
- await this.#registerRenderScene(handles);
34248
+ if (!rendererInternals(this.renderer).isSceneRegistered) await this.#registerRenderScene(handles);
33908
34249
  this.#frameCallback = registerFrameCallback(handles.scene, this.#onLiteFrame);
33909
34250
  this.#isLoopRunning = true;
33910
34251
  rendererInternals(this.renderer).setLoopRunning(true);
@@ -33980,7 +34321,10 @@ var AppImpl = class {
33980
34321
  if (this.#mode === "development") await enableLiteErrorDecoding();
33981
34322
  const canvas = this.#canvas;
33982
34323
  const renderer = rendererInternals(this.renderer);
33983
- this.#handles = canvas === null ? createHeadlessEngine() : await createRenderEngine(canvas, this.#engineOptions(rendering), { postProcessing: renderer.renderingFeatures.postProcessing });
34324
+ this.#handles = canvas === null ? createHeadlessEngine() : await createRenderEngine(canvas, this.#engineOptions(rendering), {
34325
+ postProcessing: renderer.renderingFeatures.postProcessing,
34326
+ hdr: rendering.hdr
34327
+ });
33984
34328
  if (canvas !== null) this.platform.setWebGpu(await probeWebGpuInfo());
33985
34329
  this.assets.attachEngine(this.#handles.engine);
33986
34330
  renderer.attachHandles(this.#handles.engine, this.#handles.scene, this.#handles.presenter);
@@ -34823,18 +35167,18 @@ function transformSchema() {
34823
35167
  function describeSchemas() {
34824
35168
  return {
34825
35169
  "ignifx/Transform": describeSchema("ignifx/Transform", transformSchema(), {
34826
- description: "The entity's local position, rotation, and scale; every entity has exactly one, stored as its transform block.",
35170
+ description: Transform.description,
34827
35171
  allowMultiple: false,
34828
35172
  package: "@ignifx/core",
34829
35173
  builtIn: true
34830
35174
  }),
34831
- "ignifx/Camera": describeSchema("ignifx/Camera", Camera.schema, { description: "The camera an entity renders the world through; the entity's transform is the view." }),
34832
- "ignifx/Light": describeSchema("ignifx/Light", Light.schema, { description: "A directional, point, spot, or hemispheric light, with optional shadow casting." }),
34833
- "ignifx/MeshRenderer": describeSchema("ignifx/MeshRenderer", MeshRenderer.schema, { description: "Draws one clone of a mesh asset with a material." }),
34834
- "ignifx/InstancedMeshRenderer": describeSchema("ignifx/InstancedMeshRenderer", InstancedMeshRenderer.schema, { description: "Draws one mesh many times from a caller-owned matrix slab, in a single draw call, with optional GPU culling and a coarser mesh for far instances." }),
34835
- "ignifx/Model": describeSchema("ignifx/Model", Model.schema, { description: "One instance of a loaded glTF, cloned under the entity's node." }),
34836
- "ignifx/Environment": describeSchema("ignifx/Environment", Environment.schema, { description: "The world's image-based lighting, skybox, fog, image processing, and clear colour." }),
34837
- "ignifx/PostProcessStack": describeSchema("ignifx/PostProcessStack", PostProcessStack.schema, { description: "Bloom, SMAA, image processing, and custom .post.wgsl effects, inserted into the scene's frame graph." }),
35175
+ "ignifx/Camera": describeSchema("ignifx/Camera", Camera.schema, { description: Camera.description }),
35176
+ "ignifx/Light": describeSchema("ignifx/Light", Light.schema, { description: Light.description }),
35177
+ "ignifx/MeshRenderer": describeSchema("ignifx/MeshRenderer", MeshRenderer.schema, { description: MeshRenderer.description }),
35178
+ "ignifx/InstancedMeshRenderer": describeSchema("ignifx/InstancedMeshRenderer", InstancedMeshRenderer.schema, { description: InstancedMeshRenderer.description }),
35179
+ "ignifx/Model": describeSchema("ignifx/Model", Model.schema, { description: Model.description }),
35180
+ "ignifx/Environment": describeSchema("ignifx/Environment", Environment.schema, { description: Environment.description }),
35181
+ "ignifx/PostProcessStack": describeSchema("ignifx/PostProcessStack", PostProcessStack.schema, { description: PostProcessStack.description }),
34838
35182
  "ignifx/scene-file": describeSceneFileFormat(),
34839
35183
  "ignifx/material-file": describeMaterialFileFormat(),
34840
35184
  "ignifx/environment-file": describeEnvironmentFileFormat(),
@@ -35143,6 +35487,332 @@ function describeMeshFileFormat() {
35143
35487
  };
35144
35488
  }
35145
35489
  //#endregion
35490
+ //#region src/serialization/prefab-overrides.ts
35491
+ /**
35492
+ * Writes an instance's overrides into the prefab file it instances, so every instance of the prefab
35493
+ * gets them — Unity's "Apply to prefab" (ADR-0005).
35494
+ *
35495
+ * @remarks
35496
+ * A pure function over the two files: nothing is loaded, and the same input always gives
35497
+ * byte-identical output through {@link stringifySceneFile}. The rules:
35498
+ *
35499
+ * - Property, `enabled`, transform, and entity-field overrides change the prefab's record. An `add`
35500
+ * appends the component, keeping its uid; a `remove` deletes the component.
35501
+ * - On a prefab with exactly one root, the instance root's own `name`, `transform`, and other entity
35502
+ * fields are its placement, not prefab content, so overrides of the root's entity fields and
35503
+ * transform are skipped.
35504
+ * - Overrides reach only the prefab's own entities. Content of a scene the prefab itself instances
35505
+ * is not addressable by an override path, so a nested prefab is never edited: an override that
35506
+ * names something the prefab file does not hold is skipped.
35507
+ * - An override is skipped when an earlier override that stays on the instance overlaps its path, so
35508
+ * the instance keeps the value it had.
35509
+ * - A skipped override stays on the returned instance. The instance's own `components` are not
35510
+ * overrides and are not touched.
35511
+ * - Other instances of the prefab keep their overrides, which still win over the new prefab values
35512
+ * at the same path. Record {@link PrefabApplyResult.hash} on them, or loading them logs `IGX-0604`.
35513
+ * - References inside added components (`$entity`, `$component`) are copied unchanged.
35514
+ *
35515
+ * @param instance - The instance entry whose overrides to apply; its `scene` should name `asset`.
35516
+ * @param asset - The prefab file the entry instances.
35517
+ * @param selection - Which overrides to apply; all of them by default.
35518
+ * @returns The new prefab file and its hash, the instance entry without the applied overrides, and
35519
+ * what was applied or skipped.
35520
+ * @throws IgnifxError with code `IGX-0609` when a selected override path is outside the grammar.
35521
+ *
35522
+ * @example
35523
+ * ```ts
35524
+ * const result = await applyOverridesToAsset(spawn.instance, prefabFile);
35525
+ * await app.storage.write("prefabs/enemy.prefab.json", stringifySceneFile(result.asset));
35526
+ * ```
35527
+ *
35528
+ * @public
35529
+ */
35530
+ async function applyOverridesToAsset(instance, asset, selection) {
35531
+ const overrides = instance.overrides ?? [];
35532
+ const records = /* @__PURE__ */ new Map();
35533
+ const lookup = /* @__PURE__ */ new Map();
35534
+ const uids = /* @__PURE__ */ new Set();
35535
+ for (const entity of asset.entities) {
35536
+ const data = mutableEntity(entity);
35537
+ records.set(entity.uid, data);
35538
+ lookup.set(entity.uid, {
35539
+ data,
35540
+ components: /* @__PURE__ */ new Map()
35541
+ });
35542
+ uids.add(entity.uid);
35543
+ for (const component of entity.components ?? []) uids.add(component.uid);
35544
+ }
35545
+ const singleRootUid = singleRootOf(asset);
35546
+ const touched = /* @__PURE__ */ new Set();
35547
+ const applied = [];
35548
+ const skipped = [];
35549
+ const remaining = [];
35550
+ for (const override of overrides) {
35551
+ if (!isSelected(override, selection)) {
35552
+ remaining.push(override);
35553
+ continue;
35554
+ }
35555
+ const parsed = parseOverridePath(override.path);
35556
+ let reason = precheck(override, parsed, singleRootUid, uids) ?? shadowedBy(override, remaining);
35557
+ if (reason === null) applyOverrides([override], lookup, (message) => {
35558
+ reason ??= message;
35559
+ });
35560
+ if (reason !== null) {
35561
+ skipped.push({
35562
+ override,
35563
+ reason
35564
+ });
35565
+ remaining.push(override);
35566
+ continue;
35567
+ }
35568
+ touched.add(parsed.entity);
35569
+ const added = addedComponentUid(override);
35570
+ if (added !== null) uids.add(added);
35571
+ applied.push(override);
35572
+ }
35573
+ const next = applied.length === 0 ? asset : {
35574
+ ...asset,
35575
+ entities: asset.entities.map((entity) => {
35576
+ const data = records.get(entity.uid);
35577
+ return data === void 0 || !touched.has(entity.uid) ? entity : canonicalEntity(data);
35578
+ })
35579
+ };
35580
+ const hash = await computeSceneHash(next);
35581
+ return {
35582
+ asset: next,
35583
+ hash,
35584
+ instance: withOverrides(instance, remaining, hash),
35585
+ applied,
35586
+ skipped
35587
+ };
35588
+ }
35589
+ /**
35590
+ * Drops an instance's overrides so it follows its prefab again — Unity's "Revert".
35591
+ *
35592
+ * @remarks
35593
+ * A pure function: the entry's `scene` and `hash` are kept, and `overrides` is omitted when none
35594
+ * remain. Reverting an `add` also reverts the overrides below the added component when the
35595
+ * selection path covers them (`<entityUid>/components/<addedUid>` does).
35596
+ *
35597
+ * @param instance - The instance entry.
35598
+ * @param selection - Which overrides to drop; all of them by default.
35599
+ * @returns The entry without the selected overrides, or `instance` itself when none was selected.
35600
+ *
35601
+ * @example
35602
+ * ```ts
35603
+ * const reverted = revertOverrides(spawn.instance, { paths: [`${rootUid}/components/${aiUid}`] });
35604
+ * ```
35605
+ *
35606
+ * @public
35607
+ */
35608
+ function revertOverrides(instance, selection) {
35609
+ const overrides = instance.overrides ?? [];
35610
+ const remaining = overrides.filter((override) => !isSelected(override, selection));
35611
+ if (remaining.length === overrides.length) return instance;
35612
+ return withOverrides(instance, remaining, instance.hash);
35613
+ }
35614
+ /**
35615
+ * Whether a selection covers an override.
35616
+ *
35617
+ * @param override - The override.
35618
+ * @param selection - The selection; absent or without `paths`, everything.
35619
+ * @returns `true` when the override's target is a selected path or lies below one.
35620
+ */
35621
+ function isSelected(override, selection) {
35622
+ const paths = selection?.paths;
35623
+ if (paths === void 0) return true;
35624
+ const target = targetPath(override);
35625
+ return paths.some((path) => target === path || target.startsWith(`${path}/`));
35626
+ }
35627
+ /**
35628
+ * The path an override acts on: its own path, or for an `add` to a component list the path of the
35629
+ * component it adds, so a selection can name one added component.
35630
+ *
35631
+ * @param override - The override.
35632
+ * @returns The path.
35633
+ */
35634
+ function targetPath(override) {
35635
+ const added = addedComponentUid(override);
35636
+ return added === null ? override.path : `${override.path}/${added}`;
35637
+ }
35638
+ /**
35639
+ * The uid of the component an `add` override appends to a component list.
35640
+ *
35641
+ * @param override - The override.
35642
+ * @returns The uid, or `null` when the override is not such an `add` or names no uid.
35643
+ */
35644
+ function addedComponentUid(override) {
35645
+ if (overrideOp(override) !== "add") return null;
35646
+ const segments = override.path.split("/");
35647
+ if (segments.length !== 2 || segments[1] !== "components") return null;
35648
+ const uid = asJsonObject(override.value)?.["uid"];
35649
+ return typeof uid === "string" ? uid : null;
35650
+ }
35651
+ /**
35652
+ * Checks what the override patcher itself accepts silently but a prefab file must not take.
35653
+ *
35654
+ * @param override - The override.
35655
+ * @param parsed - Its parsed path.
35656
+ * @param singleRootUid - The prefab's only root, or `null`.
35657
+ * @param uids - Every uid the prefab file already uses.
35658
+ * @returns Why the override cannot be applied, or `null`.
35659
+ */
35660
+ function precheck(override, parsed, singleRootUid, uids) {
35661
+ if (parsed.entity === singleRootUid && (parsed.kind === "entityField" || parsed.kind === "transform")) return `"${override.path}" sets the instance root's own ${parsed.kind === "transform" ? "transform" : parsed.field}, which is its placement, not prefab content.`;
35662
+ if (parsed.kind === "transform") {
35663
+ const numbers = asJsonArray(override.value);
35664
+ const length = parsed.channel === "rotation" ? 4 : 3;
35665
+ if (numbers === null || numbers.length !== length || !numbers.every((entry) => typeof entry === "number" && Number.isFinite(entry))) return `"${override.path}" needs ${String(length)} finite numbers.`;
35666
+ }
35667
+ const added = addedComponentUid(override);
35668
+ if (added !== null && uids.has(added)) return `"${override.path}" adds component ${added}, a uid the prefab file already uses.`;
35669
+ return null;
35670
+ }
35671
+ /**
35672
+ * Why an override must stay on the instance: an earlier override that stays there overlaps it, and
35673
+ * once baked into the prefab the applied one would run first and lose to it.
35674
+ *
35675
+ * @param override - The selected override.
35676
+ * @param remaining - The earlier overrides that stay on the instance.
35677
+ * @returns Why the override cannot be applied, or `null`.
35678
+ */
35679
+ function shadowedBy(override, remaining) {
35680
+ const key = overlapKey(override);
35681
+ const earlier = remaining.find((candidate) => {
35682
+ const other = overlapKey(candidate);
35683
+ return addedComponentUid(candidate) === null && (key === other || key.startsWith(`${other}/`) || other.startsWith(`${key}/`));
35684
+ });
35685
+ return earlier === void 0 ? null : `"${override.path}" follows "${earlier.path}", which stays on the instance and overlaps it.`;
35686
+ }
35687
+ /**
35688
+ * The part of an override's path that decides overlap: cut at the prop field, so array index shifts
35689
+ * inside one field count.
35690
+ *
35691
+ * @param override - The override.
35692
+ * @returns The key.
35693
+ */
35694
+ function overlapKey(override) {
35695
+ return override.path.split("/").slice(0, 5).join("/");
35696
+ }
35697
+ /**
35698
+ * The uid of a scene file's only root.
35699
+ *
35700
+ * @param file - The file.
35701
+ * @returns The uid, or `null` when the file has no root or several.
35702
+ */
35703
+ function singleRootOf(file) {
35704
+ const roots = file.entities.filter((entity) => entity.parent === null);
35705
+ return roots.length === 1 ? roots[0]?.uid ?? null : null;
35706
+ }
35707
+ /**
35708
+ * Copies a file record into the mutable shape the override patcher edits.
35709
+ *
35710
+ * @param entity - The record.
35711
+ * @returns A copy that shares nothing the patcher mutates.
35712
+ */
35713
+ function mutableEntity(entity) {
35714
+ return {
35715
+ uid: entity.uid,
35716
+ name: entity.name,
35717
+ parent: entity.parent,
35718
+ ...entity.active === void 0 ? {} : { active: entity.active },
35719
+ ...entity.static === void 0 ? {} : { static: entity.static },
35720
+ ...entity.layer === void 0 ? {} : { layer: entity.layer },
35721
+ ...entity.tags === void 0 ? {} : { tags: [...entity.tags] },
35722
+ transform: {
35723
+ position: [...entity.transform.position],
35724
+ rotation: [...entity.transform.rotation],
35725
+ scale: [...entity.transform.scale]
35726
+ },
35727
+ ...entity.instance === void 0 ? {} : { instance: entity.instance },
35728
+ components: [...entity.components ?? []]
35729
+ };
35730
+ }
35731
+ /**
35732
+ * Writes a patched record back in the serializer's canonical form: its key order, defaults omitted,
35733
+ * tags sorted and unique, numbers canonicalized.
35734
+ *
35735
+ * @param data - The patched record.
35736
+ * @returns The file record.
35737
+ */
35738
+ function canonicalEntity(data) {
35739
+ const tags = [...new Set(data.tags ?? [])].toSorted();
35740
+ return {
35741
+ uid: data.uid,
35742
+ name: data.name,
35743
+ parent: data.parent,
35744
+ ...data.active === false ? { active: false } : {},
35745
+ ...data.static === true ? { static: true } : {},
35746
+ ...data.layer === void 0 || data.layer === "Default" ? {} : { layer: data.layer },
35747
+ ...tags.length === 0 ? {} : { tags },
35748
+ transform: {
35749
+ position: triple(data.transform.position),
35750
+ rotation: [
35751
+ canonicalNumberAt(data.transform.rotation, 0),
35752
+ canonicalNumberAt(data.transform.rotation, 1),
35753
+ canonicalNumberAt(data.transform.rotation, 2),
35754
+ canonicalNumberAt(data.transform.rotation, 3)
35755
+ ],
35756
+ scale: triple(data.transform.scale)
35757
+ },
35758
+ ...data.instance === void 0 ? {} : { instance: data.instance },
35759
+ ...data.components.length === 0 ? {} : { components: data.components.map(canonicalComponent) }
35760
+ };
35761
+ }
35762
+ /**
35763
+ * Writes a component record in the serializer's key order, `enabled` omitted when `true`.
35764
+ *
35765
+ * @param component - The record.
35766
+ * @returns The canonical record.
35767
+ */
35768
+ function canonicalComponent(component) {
35769
+ return {
35770
+ uid: component.uid,
35771
+ type: component.type,
35772
+ ...component.enabled === false ? { enabled: false } : {},
35773
+ ...component.schemaVersion === void 0 ? {} : { schemaVersion: component.schemaVersion },
35774
+ ...component.props === void 0 ? {} : { props: component.props }
35775
+ };
35776
+ }
35777
+ /**
35778
+ * Reads a three-number transform channel.
35779
+ *
35780
+ * @param values - The channel.
35781
+ * @returns The canonical triple.
35782
+ */
35783
+ function triple(values) {
35784
+ return [
35785
+ canonicalNumberAt(values, 0),
35786
+ canonicalNumberAt(values, 1),
35787
+ canonicalNumberAt(values, 2)
35788
+ ];
35789
+ }
35790
+ /**
35791
+ * Reads one canonical number from a transform channel.
35792
+ *
35793
+ * @param values - The channel.
35794
+ * @param index - Which entry.
35795
+ * @returns The canonical number; `0` when the entry is missing.
35796
+ */
35797
+ function canonicalNumberAt(values, index) {
35798
+ return canonicalizeNumber(values[index] ?? 0);
35799
+ }
35800
+ /**
35801
+ * Rebuilds an instance entry with a new override list and hash.
35802
+ *
35803
+ * @param instance - The entry.
35804
+ * @param overrides - The overrides to keep.
35805
+ * @param hash - The hash to record, or `undefined` for none.
35806
+ * @returns The entry, in the serializer's key order, `overrides` omitted when empty.
35807
+ */
35808
+ function withOverrides(instance, overrides, hash) {
35809
+ return {
35810
+ scene: instance.scene,
35811
+ ...hash === void 0 ? {} : { hash },
35812
+ ...overrides.length === 0 ? {} : { overrides }
35813
+ };
35814
+ }
35815
+ //#endregion
35146
35816
  //#region src/serialization/serialize.ts
35147
35817
  /**
35148
35818
  * Writes a scene instance, or a set of entities, as a scene file object
@@ -35819,9 +36489,14 @@ function componentPackage(registry, typeId) {
35819
36489
  * and marked `builtIn`, because every entity carries exactly one and a scene file stores it as the
35820
36490
  * entity's `transform` block rather than in its `components`.
35821
36491
  *
36492
+ * A component's `title` and `description` come from `curated` when it has an entry, else from the
36493
+ * class's own `static title` and `static description`, which is how an extension's components
36494
+ * reach an inspector with their curated names without the inspector importing the extension.
36495
+ *
35822
36496
  * @param registry - The registry to walk, usually `app.world.registry`.
35823
36497
  * @param curated - Titles, formats and summaries by type id, for example a package's own
35824
- * `describeSchemas()`; a component without an entry is titled from its type id.
36498
+ * `describeSchemas()`; an entry wins over the class's own `static title` and `static description`, and a component
36499
+ * with neither is titled from its type id.
35825
36500
  * @returns The descriptions, keyed by type id, in registration order.
35826
36501
  *
35827
36502
  * @example
@@ -35840,10 +36515,12 @@ function describeRegisteredSchemas(registry, curated) {
35840
36515
  const info = registry.describe(type);
35841
36516
  const meta = curated?.[typeId];
35842
36517
  const builtIn = type === Transform;
36518
+ const title = meta?.title ?? info.title;
36519
+ const description = meta?.description ?? info.description;
35843
36520
  described[typeId] = describeSchema(typeId, builtIn ? transformSchema() : info.schema ?? {}, {
35844
- ...meta?.title === void 0 ? {} : { title: meta.title },
36521
+ ...title === null ? {} : { title },
35845
36522
  ...meta?.format === void 0 ? {} : { format: meta.format },
35846
- ...meta?.description === void 0 ? {} : { description: meta.description },
36523
+ ...description === null ? {} : { description },
35847
36524
  allowMultiple: info.allowMultiple,
35848
36525
  package: componentPackage(registry, typeId),
35849
36526
  ...builtIn ? { builtIn } : {},
@@ -36395,6 +37072,6 @@ function settingsJsonSchema(app) {
36395
37072
  };
36396
37073
  }
36397
37074
  //#endregion
36398
- export { ASSET_DIAGNOSTICS_COUNTERS, ASSET_DIAGNOSTICS_GROUP, ASSET_MANIFEST_FORMAT, ASSET_MANIFEST_VERSION, AssetLoadError, CANVAS_ALPHA_MODES, CORE_ERROR_MESSAGES, Camera, Color, Component, ComponentRegistry, CoreErrorCode, DEFAULT_ASSET_CONCURRENCY, DEFAULT_ASSET_ROOT, DEFAULT_BRDF_LUT_ADDRESS, DEFAULT_LAYER, DEFAULT_MEMORY_SINK_LIMIT, DEFAULT_STORAGE_NAMESPACE, DEG_TO_RAD, Diagnostics, EASINGS, EASING_NAMES, EMPTY_ASSET_MANIFEST, ENVIRONMENT_ASSET_TYPE, ENVIRONMENT_FILE_EXTENSION, ENVIRONMENT_FILE_EXTENSIONS, ENVIRONMENT_FILE_FORMAT, ENVIRONMENT_FORMAT_VERSION, EPSILON, Entity, Environment, EnvironmentAsset, ErrorRange, FOG_MODE_NAMES, FONT_ASSET_TYPE, FONT_FILE_EXTENSIONS, FRAME_HISTORY_LENGTH, FieldKind, FontAsset, IGNIFX_UNIFORM_NAMES, INVALID_HANDLE, IgnifxError, IndexedDbStorageBackend, InstancedMeshRenderer, LIGHT_TYPES, LITE_MATERIAL_PLUGIN_POINTS, LITE_SYSTEM_UNIFORM_NAMES, LOG_LEVEL_SEVERITY, LayerMask, LayerTable, Light, LogLevel, MAT4_IDENTITY, MATERIAL_ALPHA_MODES, MATERIAL_ASSET_TYPE, MATERIAL_FILE_EXTENSION, MATERIAL_FILE_FORMAT, MATERIAL_FORMAT_VERSION, MATERIAL_KINDS, MATERIAL_PLUGIN_DEFAULT_PRIORITY, MATERIAL_PLUGIN_RESERVED_NAMES, MATERIAL_PLUGIN_SAMPLER_BUDGET, MAX_LAYERS, MAX_ULID_TIME_MS, MESH_ASSET_TYPE, MESH_FILE_EXTENSION, MESH_FILE_FORMAT, MESH_FORMAT_VERSION, MESH_PRIMITIVES, MESH_PRIMITIVE_OPTIONS, MODEL_ASSET_TYPE, MODEL_FILE_EXTENSIONS, Mat4, MaterialAsset, MemoryStorageBackend, MeshAsset, MeshRenderer, Model, ModelAsset, NAMESPACE_SEGMENT_MAX_LENGTH, PBR_TEXTURE_SLOTS, PHASES, PHASE_COUNT, PHASE_NAMES, POST_EFFECT_BUILTIN_UNIFORMS, POST_EFFECT_FUNCTION, PROJECTIONS, Phase, PhysicsCallbackName, PostProcessStack, QUAT_IDENTITY, Quat, RAD_TO_DEG, RENDERING_SETTINGS_SECTION, RENDER_DIAGNOSTICS_COUNTERS, RENDER_DIAGNOSTICS_GROUP, RESERVED_LAYER_NAMES, SCENE_ASSET_TYPE, SCENE_FILE_EXTENSIONS, SCENE_FILE_FORMAT, SCENE_FORMAT_VERSION, SETTINGS_DESCRIPTION_FORMAT, SHADER_ASSET_TYPE, SHADER_ATTRIBUTE_NAMES, SHADER_BLEND_MODES, SHADER_CULL_MODES, SHADER_FILE_EXTENSIONS, SHADER_INSTANCING_MODES, SHADER_KINDS, SHADER_TEXTURE_FALLBACKS, SHADER_UNIFORM_TYPES, SHADOW_TECHNIQUES, STANDARD_TEXTURE_SLOTS, STORAGE_BUFFER_ASSET_TYPE, STORAGE_KEY_MAX_LENGTH, SURFACE_HOOK_NAMES, SURFACE_UNIFORM_BLOCK, SceneAssetToken, SceneInstance, SchemaIssueCode, Script, ScriptCallbackKind, ShaderAsset, Signal, StorageBufferAsset, TEXTURE_ASSET_TYPE, THIRD_PARTY_ERROR_PREFIX, TONE_MAPPING_NAMES, TWEEN_LOOP_FOREVER, TWEEN_SYSTEM_ORDER, TWEEN_VALUE_KINDS, TagSet, TextureAsset, Transform, Tween, UidRemap, VEC2_ONE, VEC2_ZERO, VEC3_BACKWARD, VEC3_DOWN, VEC3_FORWARD, VEC3_LEFT, VEC3_ONE, VEC3_RIGHT, VEC3_UP, VEC3_ZERO, VERSION, Vec2, Vec3, Vec4, World, addComponentFromRecord, applyInit, approximately, array, assertNever, assertSceneDependenciesLoaded, asset, assetRef, binaryAssetLoader, bool, canonicalizeNumber, clamp, clamp01, color, componentRef, computeSceneHash, coreExtension, createApp, createAssetManifest, createConsoleSink, createCryptoRandom, createDefaults, createDiagnosticsGroup, createEnvironmentLoader, createErrorCodeRegistry, createFileStorageBackend, createFontLoader, createFrameSample, createLayerTable, createLogger, createManualClock, createMaterialAsset, createMaterialLoader, createMemorySink, createMeshLoader, createModelLoader, createPerformanceClock, createRay, createSceneAsset, createSceneLoader, createSeededRandom, createServiceKey, createShaderLoader, createStorageBufferAsset, createTextureLoader, createUlidFactory, curve, custom, customEffect, decodeProps, decodeValue, defaultRenderingSettings, defineExtension, defineMaterialPlugin, defineSchema, degToRad, deltaAngleDegrees, describeEnvironmentFileFormat, describeMaterialFileFormat, describeMeshFileFormat, describeRegisteredSchemas, describeSceneFileFormat, describeSchema, describeSchemas, describeSettings, encodeProps, encodeValue, entityRef, enumOf, environmentDefinition, f32, f64, forceRendererDeviceLossForTesting, formatErrorMessage, generateUlid, i32, instantiateScene, inverseLerp, isAssetRef, isIgnifxError, isLiteMaterialPluginPoint, isSceneFileHeader, isUlid, isValidErrorCode, isWebGpuAvailable, jsonAssetLoader, layerMask, lerp, lerpAngleDegrees, loadSceneDependencies, map, meshFileJsonSchema, moveTowards, optional, parseOverridePath, pbrMaterialDefinition, pingPong, platformInternals, quat, radToDeg, record, repeat, resetFrameSample, resolveEase, sceneFileJsonSchema, serializeComponent, serializeEntity, serializeScene, settingsJsonSchema, shaderMaterialDefinition, sign, smoothStep, standardMaterialDefinition, storageInternals, str, stringifySceneFile, textAssetLoader, toJsonSchema, transformSchema, u32, validateProps, validateSceneFile, validateValue, vec2, vec3, vec4, waitFixedUpdate, waitSeconds, waitSecondsRealtime, waitUntil, waitWhile, wrapAngleDegrees };
37075
+ export { ASSET_DIAGNOSTICS_COUNTERS, ASSET_DIAGNOSTICS_GROUP, ASSET_MANIFEST_FORMAT, ASSET_MANIFEST_VERSION, AssetLoadError, CANVAS_ALPHA_MODES, CORE_ERROR_MESSAGES, Camera, Color, Component, ComponentRegistry, CoreErrorCode, DEFAULT_ASSET_CONCURRENCY, DEFAULT_ASSET_ROOT, DEFAULT_BRDF_LUT_ADDRESS, DEFAULT_LAYER, DEFAULT_MEMORY_SINK_LIMIT, DEFAULT_STORAGE_NAMESPACE, DEG_TO_RAD, Diagnostics, EASINGS, EASING_NAMES, EMPTY_ASSET_MANIFEST, ENVIRONMENT_ASSET_TYPE, ENVIRONMENT_FILE_EXTENSION, ENVIRONMENT_FILE_EXTENSIONS, ENVIRONMENT_FILE_FORMAT, ENVIRONMENT_FORMAT_VERSION, EPSILON, Entity, Environment, EnvironmentAsset, ErrorRange, FOG_MODE_NAMES, FONT_ASSET_TYPE, FONT_FILE_EXTENSIONS, FRAME_HISTORY_LENGTH, FieldKind, FontAsset, IGNIFX_UNIFORM_NAMES, INVALID_HANDLE, IgnifxError, IndexedDbStorageBackend, InstancedMeshRenderer, LIGHT_TYPES, LITE_MATERIAL_PLUGIN_POINTS, LITE_SYSTEM_UNIFORM_NAMES, LOG_LEVEL_SEVERITY, LayerMask, LayerTable, Light, LogLevel, MAT4_IDENTITY, MATERIAL_ALPHA_MODES, MATERIAL_ASSET_TYPE, MATERIAL_FILE_EXTENSION, MATERIAL_FILE_FORMAT, MATERIAL_FORMAT_VERSION, MATERIAL_KINDS, MATERIAL_PLUGIN_DEFAULT_PRIORITY, MATERIAL_PLUGIN_RESERVED_NAMES, MATERIAL_PLUGIN_SAMPLER_BUDGET, MAX_LAYERS, MAX_ULID_TIME_MS, MESH_ASSET_TYPE, MESH_FILE_EXTENSION, MESH_FILE_FORMAT, MESH_FORMAT_VERSION, MESH_PRIMITIVES, MESH_PRIMITIVE_OPTIONS, MODEL_ASSET_TYPE, MODEL_FILE_EXTENSIONS, Mat4, MaterialAsset, MemoryStorageBackend, MeshAsset, MeshRenderer, Model, ModelAsset, NAMESPACE_SEGMENT_MAX_LENGTH, PBR_TEXTURE_SLOTS, PHASES, PHASE_COUNT, PHASE_NAMES, POST_EFFECT_BUILTIN_UNIFORMS, POST_EFFECT_FUNCTION, PROJECTIONS, Phase, PhysicsCallbackName, PostProcessStack, QUAT_IDENTITY, Quat, RAD_TO_DEG, RENDERING_SETTINGS_SECTION, RENDER_DIAGNOSTICS_COUNTERS, RENDER_DIAGNOSTICS_GROUP, RENDER_TEXTURE_MAX_SIZE, RESERVED_LAYER_NAMES, SCENE_ASSET_TYPE, SCENE_FILE_EXTENSIONS, SCENE_FILE_FORMAT, SCENE_FORMAT_VERSION, SETTINGS_DESCRIPTION_FORMAT, SHADER_ASSET_TYPE, SHADER_ATTRIBUTE_NAMES, SHADER_BLEND_MODES, SHADER_CULL_MODES, SHADER_FILE_EXTENSIONS, SHADER_INSTANCING_MODES, SHADER_KINDS, SHADER_TEXTURE_FALLBACKS, SHADER_UNIFORM_TYPES, SHADOW_TECHNIQUES, STANDARD_TEXTURE_SLOTS, STORAGE_BUFFER_ASSET_TYPE, STORAGE_KEY_MAX_LENGTH, SURFACE_HOOK_NAMES, SURFACE_UNIFORM_BLOCK, SceneAssetToken, SceneInstance, SchemaIssueCode, Script, ScriptCallbackKind, ShaderAsset, Signal, StorageBufferAsset, TEXTURE_ASSET_TYPE, THIRD_PARTY_ERROR_PREFIX, TONE_MAPPING_NAMES, TWEEN_LOOP_FOREVER, TWEEN_SYSTEM_ORDER, TWEEN_VALUE_KINDS, TagSet, TextureAsset, Transform, Tween, UidRemap, VEC2_ONE, VEC2_ZERO, VEC3_BACKWARD, VEC3_DOWN, VEC3_FORWARD, VEC3_LEFT, VEC3_ONE, VEC3_RIGHT, VEC3_UP, VEC3_ZERO, VERSION, Vec2, Vec3, Vec4, World, addComponentFromRecord, applyInit, applyOverridesToAsset, approximately, array, assertNever, assertSceneDependenciesLoaded, asset, assetRef, binaryAssetLoader, bool, canonicalizeNumber, clamp, clamp01, color, componentRef, computeSceneHash, coreExtension, createApp, createAssetManifest, createConsoleSink, createCryptoRandom, createDefaults, createDiagnosticsGroup, createEnvironmentLoader, createErrorCodeRegistry, createFileStorageBackend, createFontLoader, createFrameSample, createLayerTable, createLogger, createManualClock, createMaterialAsset, createMaterialLoader, createMemorySink, createMeshLoader, createModelLoader, createPerformanceClock, createRay, createSceneAsset, createSceneLoader, createSeededRandom, createServiceKey, createShaderLoader, createStorageBufferAsset, createTextureLoader, createUlidFactory, curve, custom, customEffect, decodeProps, decodeValue, defaultRenderingSettings, defineExtension, defineMaterialPlugin, defineSchema, degToRad, deltaAngleDegrees, describeEnvironmentFileFormat, describeMaterialFileFormat, describeMeshFileFormat, describeRegisteredSchemas, describeSceneFileFormat, describeSchema, describeSchemas, describeSettings, encodeProps, encodeValue, entityRef, enumOf, environmentDefinition, f32, f64, forceRendererDeviceLossForTesting, formatErrorMessage, generateUlid, i32, instantiateScene, inverseLerp, isAssetRef, isIgnifxError, isLiteMaterialPluginPoint, isSceneFileHeader, isUlid, isValidErrorCode, isWebGpuAvailable, jsonAssetLoader, layerMask, lerp, lerpAngleDegrees, loadSceneDependencies, map, meshFileJsonSchema, moveTowards, optional, parseOverridePath, pbrMaterialDefinition, pingPong, platformInternals, quat, radToDeg, record, repeat, resetFrameSample, resolveEase, revertOverrides, sceneFileJsonSchema, serializeComponent, serializeEntity, serializeScene, settingsJsonSchema, shaderMaterialDefinition, sign, smoothStep, standardMaterialDefinition, storageInternals, str, stringifySceneFile, textAssetLoader, toJsonSchema, transformSchema, u32, validateProps, validateSceneFile, validateValue, vec2, vec3, vec4, waitFixedUpdate, waitSeconds, waitSecondsRealtime, waitUntil, waitWhile, wrapAngleDegrees };
36399
37076
 
36400
37077
  //# sourceMappingURL=index.js.map