@ignifx/core 0.8.0 → 0.10.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 (29) hide show
  1. package/dist/{environment-mr5wp69e.js → environment-BCjfp1jB.js} +2 -2
  2. package/dist/{environment-mr5wp69e.js.map → environment-BCjfp1jB.js.map} +1 -1
  3. package/dist/{ignifx-error-CRh89KUJ.js → ignifx-error-RpK-lWwE.js} +13 -2
  4. package/dist/ignifx-error-RpK-lWwE.js.map +1 -0
  5. package/dist/index.d.ts +1758 -807
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js +2695 -467
  8. package/dist/index.js.map +1 -1
  9. package/dist/{instanced-mesh-instance-gguMoIeZ.js → instanced-mesh-instance-DYwH0vLi.js} +2 -2
  10. package/dist/{instanced-mesh-instance-gguMoIeZ.js.map → instanced-mesh-instance-DYwH0vLi.js.map} +1 -1
  11. package/dist/{material-plugin-Cfw_h_Mg.js → material-plugin-CWtV7DkH.js} +3 -3
  12. package/dist/material-plugin-CWtV7DkH.js.map +1 -0
  13. package/dist/overlay-CjVgsfrm.js +239 -0
  14. package/dist/overlay-CjVgsfrm.js.map +1 -0
  15. package/dist/{post-effect-compiler-Rce26Eue.js → post-effect-compiler-pOvXae-i.js} +2 -2
  16. package/dist/{post-effect-compiler-Rce26Eue.js.map → post-effect-compiler-pOvXae-i.js.map} +1 -1
  17. package/dist/{shader-material-U6BKZ8D1.js → shader-material-B6wwFCKB.js} +2 -2
  18. package/dist/{shader-material-U6BKZ8D1.js.map → shader-material-B6wwFCKB.js.map} +1 -1
  19. package/dist/{shader-material-BIG3UDyu.js → shader-material-C4VjLTfV.js} +3 -3
  20. package/dist/{shader-material-BIG3UDyu.js.map → shader-material-C4VjLTfV.js.map} +1 -1
  21. package/dist/{shader-pragma-tw6AKaQD.js → shader-pragma-qO9_6sTd.js} +2 -2
  22. package/dist/{shader-pragma-tw6AKaQD.js.map → shader-pragma-qO9_6sTd.js.map} +1 -1
  23. package/dist/{surface-shader-DAWIDdaa.js → surface-shader-BaR7Kg-F.js} +4 -4
  24. package/dist/{surface-shader-DAWIDdaa.js.map → surface-shader-BaR7Kg-F.js.map} +1 -1
  25. package/dist/{vec3-B31o_KF_.js → vec3-T2PasQZv.js} +2 -2
  26. package/dist/{vec3-B31o_KF_.js.map → vec3-T2PasQZv.js.map} +1 -1
  27. package/package.json +2 -2
  28. package/dist/ignifx-error-CRh89KUJ.js.map +0 -1
  29. package/dist/material-plugin-Cfw_h_Mg.js.map +0 -1
package/dist/index.js CHANGED
@@ -1,9 +1,9 @@
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-CRh89KUJ.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-RpK-lWwE.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
- 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-B31o_KF_.js";
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-mr5wp69e.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-Cfw_h_Mg.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-BCjfp1jB.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-CWtV7DkH.js";
7
7
  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-C42XJFmo.js";
8
8
  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";
9
9
  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";
@@ -445,6 +445,11 @@ var AssetHandleImpl = class {
445
445
  interested = 0;
446
446
  /** `true` while the loader is running. */
447
447
  isRunning = false;
448
+ /**
449
+ * How many reloads were asked for. A running reload compares it with the count it last served,
450
+ * so one asked for meanwhile runs once more when the current pass finishes.
451
+ */
452
+ reloadRequests = 0;
448
453
  /** Bytes received so far. */
449
454
  bytesLoaded = 0;
450
455
  /** Bytes expected, from the manifest entry or the response's `Content-Length`; `0` when unknown. */
@@ -1680,14 +1685,19 @@ var AssetsImpl = class {
1680
1685
  * own: it is re-derived from the base's new value when that base is delivered, which is the only
1681
1686
  * order that cannot show a fragment of the old file next to a fragment of the new one.
1682
1687
  *
1688
+ * A call that finds a reload of the handle already running queues one more pass instead of being
1689
+ * dropped, so a second save inside the first reload's window still lands.
1690
+ *
1683
1691
  * @param address - The address that changed on disk, with or without a fragment.
1684
1692
  */
1685
1693
  reload(address) {
1686
1694
  const path = splitFragment(address).path;
1687
1695
  for (const handle of this.#entries.values()) {
1688
1696
  if (handle.address !== address && handle.path !== path) continue;
1689
- if (handle.state !== "loaded" || handle.isRunning) continue;
1697
+ if (handle.state !== "loaded") continue;
1690
1698
  if (handle.fragment !== null && handle.loader.parseFragment !== void 0) continue;
1699
+ handle.reloadRequests += 1;
1700
+ if (handle.isRunning) continue;
1691
1701
  this.#runReload(handle);
1692
1702
  }
1693
1703
  }
@@ -1930,30 +1940,66 @@ var AssetsImpl = class {
1930
1940
  }
1931
1941
  }
1932
1942
  /**
1933
- * Runs one hot-reload attempt.
1943
+ * Runs a hot reload, and again for each reload asked for while it ran, then delivers the newest
1944
+ * value once. Each pass starts from the value the previous pass produced, so the default reload
1945
+ * releases every intermediate value exactly once.
1934
1946
  *
1935
1947
  * @param handle - The loaded handle to refresh.
1936
1948
  */
1937
1949
  async #runReload(handle) {
1938
1950
  const controller = new AbortController();
1939
- const previous = handle.value;
1951
+ let current = handle.value;
1952
+ let isReplaced = false;
1953
+ let served = -1;
1940
1954
  handle.isRunning = true;
1941
1955
  try {
1942
- const value = await this.#invokeLoader(handle, controller.signal, true, previous);
1943
- if (this.#isDisposed) return;
1944
- if (handle.loader.reload === void 0) this.#runUnload(handle, previous);
1945
- this.#enqueueDelivery({
1956
+ while (served !== handle.reloadRequests && handle.state === "loaded") {
1957
+ served = handle.reloadRequests;
1958
+ try {
1959
+ const value = await this.#invokeLoader(handle, controller.signal, true, current);
1960
+ if (this.#isDisposed) return;
1961
+ if (handle.loader.reload === void 0) this.#runUnload(handle, current);
1962
+ current = value;
1963
+ isReplaced = true;
1964
+ } catch (error) {
1965
+ this.#report(this.#reloadError(handle, error, isReplaced));
1966
+ }
1967
+ }
1968
+ if (isReplaced) this.#enqueueDelivery({
1946
1969
  kind: "replaced",
1947
1970
  handle,
1948
- value
1971
+ value: current
1949
1972
  });
1950
- } catch (error) {
1951
- this.#report(error);
1952
1973
  } finally {
1953
1974
  handle.isRunning = false;
1954
1975
  }
1955
1976
  }
1956
1977
  /**
1978
+ * Builds the failure a hot reload reports through `app.onError`.
1979
+ *
1980
+ * @param handle - The handle whose reload failed.
1981
+ * @param error - What the loader threw.
1982
+ * @param isReplaced - Whether an earlier pass of the same reload produced a value, which the
1983
+ * handle keeps instead of the one it held before.
1984
+ * @returns The `IGX-0505` failure, with the loader's error as `cause`.
1985
+ */
1986
+ #reloadError(handle, error, isReplaced) {
1987
+ const kept = isReplaced ? "the last version that loaded" : "its previous value";
1988
+ return new AssetLoadError(CoreErrorCode.assetLoadFailed, `Reloading ${handle.address} from ${handle.url} failed; the asset keeps ${kept}.`, {
1989
+ address: handle.address,
1990
+ url: handle.url,
1991
+ cause: error,
1992
+ context: {
1993
+ asset: handle.address,
1994
+ url: handle.url,
1995
+ attempts: 1,
1996
+ reload: true,
1997
+ kept: isReplaced ? "earlier reload" : "previous"
1998
+ },
1999
+ hint: "Fix the file and save it again; the next save reloads it."
2000
+ });
2001
+ }
2002
+ /**
1957
2003
  * Calls the loader, resolving a `#fragment` address through the base address first.
1958
2004
  *
1959
2005
  * @param handle - The handle being loaded.
@@ -3104,12 +3150,13 @@ function notAttached(component) {
3104
3150
  * costs a call per frame and not defining it costs nothing.
3105
3151
  *
3106
3152
  * **The statics work the same way.** `typeId`, `schema`, `requires`, `allowMultiple`,
3107
- * `executionOrder`, and `updateWhenPaused` are not members of `Component` or `Script` either: a
3108
- * static declared on the base class is an override too, so `static typeId = "mygame/Mover"` would
3109
- * have needed an `override` modifier. Their shape lives on {@link ComponentStatics} and
3110
- * {@link ScriptStatics}, which the class-token types intersect, so a plain `static` on a subclass
3111
- * satisfies them structurally; `ComponentRegistry` reads each one once per class and applies the
3112
- * defaults (`executionOrder` `0`, `updateWhenPaused` `false`).
3153
+ * `executionOrder`, `updateWhenPaused`, and `runInEditMode` are not members of `Component` or
3154
+ * `Script` either: a static declared on the base class is an override too, so
3155
+ * `static typeId = "mygame/Mover"` would have needed an `override` modifier. Their shape lives on
3156
+ * {@link ComponentStatics} and {@link ScriptStatics}, which the class-token types intersect, so a
3157
+ * plain `static` on a subclass satisfies them structurally; `ComponentRegistry` reads each one once
3158
+ * per class and applies the defaults (`executionOrder` `0`, `updateWhenPaused` `false`,
3159
+ * `runInEditMode` `false`).
3113
3160
  *
3114
3161
  * @example
3115
3162
  * ```ts
@@ -3161,6 +3208,8 @@ var Script = class extends Component {
3161
3208
  *
3162
3209
  * @param routine - The generator to drive. Call the generator function: `this.spawnLoop()`.
3163
3210
  * @returns A handle for stopping it or waiting on it.
3211
+ * @throws IgnifxError with code `IGX-0111` in an edit-mode app when the class does not set
3212
+ * `static runInEditMode = true` (ADR-0028).
3164
3213
  *
3165
3214
  * @example
3166
3215
  * ```ts
@@ -3217,6 +3266,7 @@ const TYPE_ID_PATTERN = /^[a-z0-9][a-z0-9\-.@/]*\/[A-Za-z][A-Za-z0-9]*$/u;
3217
3266
  */
3218
3267
  var ComponentRegistry = class {
3219
3268
  #byTypeId = /* @__PURE__ */ new Map();
3269
+ #registrars = /* @__PURE__ */ new Map();
3220
3270
  #info = /* @__PURE__ */ new Map();
3221
3271
  #nextClassIndex = 0;
3222
3272
  /**
@@ -3232,11 +3282,13 @@ var ComponentRegistry = class {
3232
3282
  *
3233
3283
  * @param type - The component class.
3234
3284
  * @param typeId - An explicit id, when the class does not declare one.
3285
+ * @param registrar - Who registers it, for example the extension's `name`; the first registrar of
3286
+ * an id is kept, and {@link ComponentRegistry.registrarOf} reports it.
3235
3287
  * @returns What the registry worked out about the class.
3236
3288
  * @throws IgnifxError with code `IGX-0203` when the id is already registered by another class, or
3237
3289
  * when the id is not `<namespace>/<Name>`.
3238
3290
  */
3239
- register(type, typeId) {
3291
+ register(type, typeId, registrar) {
3240
3292
  const id = typeId ?? readStatics$1(type).typeId ?? null;
3241
3293
  if (id !== null) {
3242
3294
  if (!TYPE_ID_PATTERN.test(id)) throw new IgnifxError(CoreErrorCode.duplicateComponentTypeId, `The component type id ${id} is malformed.`, {
@@ -3252,6 +3304,7 @@ var ComponentRegistry = class {
3252
3304
  owner: existing.prototype.constructor.name
3253
3305
  } });
3254
3306
  this.#byTypeId.set(id, type);
3307
+ if (registrar !== void 0 && !this.#registrars.has(id)) this.#registrars.set(id, registrar);
3255
3308
  }
3256
3309
  return this.describe(type);
3257
3310
  }
@@ -3259,14 +3312,32 @@ var ComponentRegistry = class {
3259
3312
  * Registers several component classes.
3260
3313
  *
3261
3314
  * @param types - The component classes.
3315
+ * @param registrar - Who registers them, as for {@link ComponentRegistry.register}.
3262
3316
  */
3263
- registerAll(types) {
3317
+ registerAll(types, registrar) {
3264
3318
  for (let index = 0; index < types.length; index += 1) {
3265
3319
  const type = types[index];
3266
- if (type !== void 0) this.register(type);
3320
+ if (type !== void 0) this.register(type, void 0, registrar);
3267
3321
  }
3268
3322
  }
3269
3323
  /**
3324
+ * Who registered a type id: the extension `name` an `ExtensionContext` registers under, or
3325
+ * whatever a direct caller of {@link ComponentRegistry.register} passed. A hot-reload
3326
+ * {@link ComponentRegistry.replace} keeps it.
3327
+ *
3328
+ * @param typeId - The namespaced id.
3329
+ * @returns The registrar, or `null` when the id was registered without one (as
3330
+ * `app.registerComponents` does) or is not registered.
3331
+ *
3332
+ * @example
3333
+ * ```ts
3334
+ * app.world.registry.registrarOf("ignifx/Camera"); // "@ignifx/core"
3335
+ * ```
3336
+ */
3337
+ registrarOf(typeId) {
3338
+ return this.#registrars.get(typeId) ?? null;
3339
+ }
3340
+ /**
3270
3341
  * Swaps the class registered under a `typeId` for a replacement, for script hot reload
3271
3342
  * (`docs/architecture/15-devtools-and-diagnostics.md` §5). The previous class's cached info is
3272
3343
  * dropped and the replacement inherits its `classIndex`, so per-class bookkeeping indexed by that
@@ -3470,6 +3541,7 @@ function buildScriptInfo(type) {
3470
3541
  return {
3471
3542
  executionOrder: statics.executionOrder ?? 0,
3472
3543
  updateWhenPaused: statics.updateWhenPaused ?? false,
3544
+ runInEditMode: statics.runInEditMode ?? false,
3473
3545
  callbacks
3474
3546
  };
3475
3547
  }
@@ -3600,6 +3672,7 @@ var CoroutineRecord = class {
3600
3672
  */
3601
3673
  var CoroutineHostImpl = class {
3602
3674
  #frameState;
3675
+ #isEditMode;
3603
3676
  #report;
3604
3677
  #records = [];
3605
3678
  #byOwner = /* @__PURE__ */ new Map();
@@ -3612,6 +3685,7 @@ var CoroutineHostImpl = class {
3612
3685
  */
3613
3686
  constructor(options) {
3614
3687
  this.#frameState = options.frameState;
3688
+ this.#isEditMode = options.editMode;
3615
3689
  this.#report = (error, owner) => {
3616
3690
  options.report(error, owner);
3617
3691
  };
@@ -3631,8 +3705,17 @@ var CoroutineHostImpl = class {
3631
3705
  * @param owner - The script whose enabled state gates the coroutine.
3632
3706
  * @param routine - The generator to drive.
3633
3707
  * @returns A handle for stopping it or waiting on it.
3708
+ * @throws IgnifxError with code `IGX-0111` in edit mode when the owner's class does not set
3709
+ * `static runInEditMode = true`.
3634
3710
  */
3635
3711
  start(owner, routine) {
3712
+ if (this.#isEditMode && componentInternals(owner).info?.script?.runInEditMode !== true) {
3713
+ const script = owner.constructor.name;
3714
+ throw new IgnifxError(CoreErrorCode.coroutineInEditMode, `${script} cannot start a coroutine in edit mode because its class does not run in edit mode.`, {
3715
+ context: { script },
3716
+ hint: "Add `static runInEditMode = true` if the script is meant to run in an editor. Otherwise start the coroutine from a callback such as `start`, which only a game calls."
3717
+ });
3718
+ }
3636
3719
  const record = new CoroutineRecord(owner, routine);
3637
3720
  this.#records.push(record);
3638
3721
  let owned = this.#byOwner.get(owner);
@@ -4614,15 +4697,14 @@ function createServiceKey(name) {
4614
4697
  * `version` (`docs/architecture/04-extensions.md` §1).
4615
4698
  *
4616
4699
  * @remarks
4617
- * The literal is `"0.0.0"` in the repository and is stamped by the release pipeline: Changesets
4618
- * writes the real number into `package.json`, and the build replaces this constant with it
4619
- * (coding standards §12, `release.yml`). Reading the version from `package.json` at run time is not
4620
- * an option — that would be an import-time side effect and a bundler hazard
4700
+ * The build stamps it from `package.json`, where Changesets writes each release's number; code run
4701
+ * from source, such as this repository's tests, sees `"0.0.0"`. Reading `package.json` at run time
4702
+ * is not an option: that would be an import-time side effect and a bundler hazard
4621
4703
  * (`CONSTITUTION.md` §3.5).
4622
4704
  *
4623
4705
  * @public
4624
4706
  */
4625
- const VERSION = "0.0.0";
4707
+ const VERSION = "0.10.0";
4626
4708
  //#endregion
4627
4709
  //#region src/assets/delivery-system.ts
4628
4710
  /**
@@ -5188,37 +5270,89 @@ function raycastScene(scene, ray, options) {
5188
5270
  return pickWithRay(scene, ray, options);
5189
5271
  }
5190
5272
  /**
5191
- * Casts a ray against a scene's renderable meshes, considering only the meshes whose ignifx tag a
5192
- * predicate accepts.
5273
+ * The ignifx tag that owns a node: its own, or the nearest tagged ancestor's.
5193
5274
  *
5194
5275
  * @remarks
5195
- * The predicate is stated over the *tag* rather than over Lite's `Mesh` so the component layer can
5196
- * filter by entity without naming a Lite type (`CONSTITUTION.md` §3.4). Lite's own
5276
+ * A `MeshRenderer` tags the mesh it clones, but a `Model` tags only the cloned glTF root, and the
5277
+ * meshes Lite draws are that root's descendants (`render/gpu/model-instance.ts`). Walking up to the
5278
+ * nearest tag resolves both, and any other renderable that parents several Lite nodes under one
5279
+ * tagged node, to the entity and component that created them (editor spike S0.2 §6.1). The walk
5280
+ * stops at the first tag, so an entity parented under a model's bone still owns its own meshes.
5281
+ *
5282
+ * @param node - The picked node, usually a mesh.
5283
+ * @returns The nearest tag, or `null` when no node on the way to the root carries one.
5284
+ *
5285
+ * @internal
5286
+ */
5287
+ function readOwnerTag(node) {
5288
+ for (let current = node; current !== null; current = parentNode(current)) {
5289
+ const tag = readNodeTag(current);
5290
+ if (tag !== null) return tag;
5291
+ }
5292
+ return null;
5293
+ }
5294
+ /**
5295
+ * Casts a ray against a scene's renderable meshes, considering only the meshes a predicate accepts.
5296
+ *
5297
+ * @remarks
5298
+ * The predicate is stated over the owning *tag* rather than over Lite's `Mesh` so the component
5299
+ * layer can filter by entity without naming a Lite type (`CONSTITUTION.md` §3.4). Lite's own
5197
5300
  * `pickable === false` exclusion still runs first.
5198
5301
  *
5199
5302
  * @param scene - The render scene.
5200
5303
  * @param ray - The ray to cast.
5201
- * @param accept - Decides whether a mesh may be picked, from the ignifx tag its node carries.
5304
+ * @param accept - Decides whether a mesh may be picked, from the ignifx tag that owns it.
5202
5305
  * @returns Lite's picking info.
5203
5306
  *
5204
5307
  * @internal
5205
5308
  */
5206
5309
  function raycastSceneWhere(scene, ray, accept) {
5207
- return pickWithRay(scene, ray, { predicate: (mesh) => accept(readNodeTag(mesh)) });
5310
+ return pickWithRay(scene, ray, { predicate: (mesh) => accept(readOwnerTag(mesh), mesh) });
5208
5311
  }
5209
5312
  /**
5210
5313
  * Resolves a hit back to the ignifx entity and component that own the mesh.
5211
5314
  *
5212
5315
  * @param info - A result from {@link raycastScene}, {@link raycastMeshes}, or the GPU picker.
5213
- * @returns The owning entity's tag, or `null` when the ray missed or the mesh is not one ignifx
5214
- * created (a glTF child node inside a `Model`, for instance, whose tag lives on the model's root).
5316
+ * @returns The owning tag — the picked mesh's own or its nearest tagged ancestor's, so a glTF mesh
5317
+ * inside a `Model` resolves to the model — or `null` when the ray missed or no node on the way to
5318
+ * the root is one ignifx created.
5215
5319
  *
5216
5320
  * @internal
5217
5321
  */
5218
5322
  function readPickedTag(info) {
5219
5323
  const mesh = info.pickedMesh;
5220
5324
  if (mesh === null) return null;
5221
- return readNodeTag(mesh);
5325
+ return readOwnerTag(mesh);
5326
+ }
5327
+ /**
5328
+ * The name of the mesh a hit landed on.
5329
+ *
5330
+ * @param info - A hit.
5331
+ * @returns The Lite mesh's name — for a glTF model, the name the file gives the node or primitive —
5332
+ * or `""` for a miss or an unnamed mesh.
5333
+ *
5334
+ * @internal
5335
+ */
5336
+ function readPickedMeshName(info) {
5337
+ const name = info.pickedMesh?.name;
5338
+ return typeof name === "string" ? name : "";
5339
+ }
5340
+ /**
5341
+ * Reads the identity of a hit, for a later pick to ignore.
5342
+ *
5343
+ * @param info - A hit.
5344
+ * @returns The mesh and thin instance, or `null` for a miss or a hit on something other than a
5345
+ * regular Lite mesh (a Gaussian-splatting mesh, which Lite's `ignore` cannot name).
5346
+ *
5347
+ * @internal
5348
+ */
5349
+ function readPickedIdentity(info) {
5350
+ const mesh = info.pickedMesh;
5351
+ if (mesh === null || !("material" in mesh)) return null;
5352
+ return {
5353
+ mesh,
5354
+ thinInstanceIndex: info.thinInstanceIndex
5355
+ };
5222
5356
  }
5223
5357
  //#endregion
5224
5358
  //#region src/schema/types.ts
@@ -5910,7 +6044,9 @@ const HEADLESS_TARGET_SIZE = 1;
5910
6044
  * @example
5911
6045
  * ```ts
5912
6046
  * const ray = createRay();
5913
- * camera.screenToRay(event.offsetX, event.offsetY, ray);
6047
+ * // A DOM event is in CSS pixels; the camera speaks the canvas's backing-store pixels.
6048
+ * const scale = canvas.width / canvas.clientWidth;
6049
+ * camera.screenToRay(event.offsetX * scale, event.offsetY * scale, ray);
5914
6050
  * ```
5915
6051
  *
5916
6052
  * @public
@@ -6008,7 +6144,9 @@ var Camera = class Camera extends Component {
6008
6144
  * @remarks
6009
6145
  * Coordinates are backing-store pixels — the canvas's `width`/`height`, the space
6010
6146
  * {@link Camera.worldToScreen} answers in and `@ignifx/input` reports `<Pointer>/position` in — not
6011
- * CSS pixels; multiply a DOM event's `offsetX`/`offsetY` by `devicePixelRatio` first.
6147
+ * CSS pixels; multiply a DOM event's `offsetX`/`offsetY` by `canvas.width / canvas.clientWidth`
6148
+ * first (`devicePixelRatio` is that ratio only while `renderer.pixelRatio` and
6149
+ * `renderer.resolutionScale` leave it alone).
6012
6150
  *
6013
6151
  * @param x - The backing-store pixel x, from the canvas's left edge.
6014
6152
  * @param y - The backing-store pixel y, from the canvas's top edge.
@@ -6900,7 +7038,7 @@ let layer = null;
6900
7038
  * @internal
6901
7039
  */
6902
7040
  async function loadInstancedMeshSupport() {
6903
- const loaded = layer ?? await import("./instanced-mesh-instance-gguMoIeZ.js");
7041
+ const loaded = layer ?? await import("./instanced-mesh-instance-DYwH0vLi.js");
6904
7042
  layer = loaded;
6905
7043
  return loaded;
6906
7044
  }
@@ -6928,7 +7066,7 @@ let surfaceLayer = null;
6928
7066
  * @internal
6929
7067
  */
6930
7068
  async function loadShaderSupport() {
6931
- const loaded = shaderLayer ?? await import("./shader-material-BIG3UDyu.js").then((n) => n.n);
7069
+ const loaded = shaderLayer ?? await import("./shader-material-C4VjLTfV.js").then((n) => n.n);
6932
7070
  shaderLayer = loaded;
6933
7071
  await loaded.loadShaderMaterialAdapter();
6934
7072
  return loaded;
@@ -6951,7 +7089,7 @@ function shaderSupport() {
6951
7089
  * @internal
6952
7090
  */
6953
7091
  async function loadSurfaceShaderSupport() {
6954
- const loaded = surfaceLayer ?? await import("./surface-shader-DAWIDdaa.js");
7092
+ const loaded = surfaceLayer ?? await import("./surface-shader-BaR7Kg-F.js");
6955
7093
  surfaceLayer = loaded;
6956
7094
  return loaded;
6957
7095
  }
@@ -7986,6 +8124,42 @@ function buildMeshTemplate(isHeadless, scene, engine, build) {
7986
8124
  engine
7987
8125
  };
7988
8126
  }
8127
+ /**
8128
+ * Copies the ignifx ground options onto Lite's, which types `uvScale` as a mutable tuple.
8129
+ *
8130
+ * @param options - The declared options.
8131
+ * @returns Lite's options.
8132
+ */
8133
+ function toGroundOptions(options) {
8134
+ const result = {};
8135
+ if (options.width !== void 0) result.width = options.width;
8136
+ if (options.height !== void 0) result.height = options.height;
8137
+ if (options.subdivisions !== void 0) result.subdivisions = options.subdivisions;
8138
+ const uvScale = options.uvScale;
8139
+ if (uvScale !== void 0) result.uvScale = [uvScale[0], uvScale[1]];
8140
+ return result;
8141
+ }
8142
+ /**
8143
+ * Builds a primitive's Lite mesh.
8144
+ *
8145
+ * @param engine - The engine that owns the buffers.
8146
+ * @param definition - The primitive and its options.
8147
+ * @returns The template.
8148
+ *
8149
+ * @internal
8150
+ */
8151
+ function buildPrimitiveTemplate(engine, definition) {
8152
+ switch (definition.primitive) {
8153
+ case "box": return buildBoxTemplate(engine, definition.options);
8154
+ case "sphere": return buildSphereTemplate(engine, definition.options);
8155
+ case "plane": return buildPlaneTemplate(engine, definition.options);
8156
+ case "ground": return buildGroundTemplate(engine, toGroundOptions(definition.options));
8157
+ case "cylinder": return buildCylinderTemplate(engine, definition.options);
8158
+ case "capsule": return buildCapsuleTemplate(engine, definition.options);
8159
+ case "torus": return buildTorusTemplate(engine, definition.options);
8160
+ default: return assertNever(definition, "mesh primitive");
8161
+ }
8162
+ }
7989
8163
  //#endregion
7990
8164
  //#region src/render/mesh-asset.ts
7991
8165
  /**
@@ -8009,12 +8183,28 @@ const FLOATS_PER_UV = 2;
8009
8183
  /** Floats per vertex in the colour attribute — Lite's colour attribute is `vec4`. */
8010
8184
  const FLOATS_PER_COLOR$1 = 4;
8011
8185
  /**
8186
+ * The primitive shapes a `MeshAsset` factory and a `.mesh.json` file can build.
8187
+ *
8188
+ * @public
8189
+ */
8190
+ const MESH_PRIMITIVES = [
8191
+ "box",
8192
+ "sphere",
8193
+ "plane",
8194
+ "ground",
8195
+ "cylinder",
8196
+ "capsule",
8197
+ "torus"
8198
+ ];
8199
+ /**
8012
8200
  * A geometry template a `MeshRenderer` draws (`docs/architecture/07-rendering.md` §2.3).
8013
8201
  *
8014
8202
  * @remarks
8015
8203
  * Build one with a primitive factory or {@link MeshAsset.fromData}; each returns the handle the
8016
- * `MeshRenderer.mesh` field takes. A mesh that came from a file arrives as part of a `ModelAsset`
8017
- * instead — a glTF is a tree of meshes, materials, and animations, not one buffer.
8204
+ * `MeshRenderer.mesh` field takes. A `.mesh.json` file loads the same primitives by address
8205
+ * (`app.assets.load("meshes/crate.mesh.json")`), so a scene file can name one. A glTF mesh
8206
+ * arrives as part of a `ModelAsset` instead — a glTF is a tree of meshes, materials, and
8207
+ * animations, not one buffer.
8018
8208
  *
8019
8209
  * @example
8020
8210
  * ```ts
@@ -8270,7 +8460,10 @@ var MeshAsset = class {
8270
8460
  * ```
8271
8461
  */
8272
8462
  static box(app, options) {
8273
- return publish(app, "box", (engine) => buildBoxTemplate(engine, options));
8463
+ return publishPrimitive(app, {
8464
+ primitive: "box",
8465
+ options: options ?? {}
8466
+ });
8274
8467
  }
8275
8468
  /**
8276
8469
  * Creates a sphere template and publishes it.
@@ -8280,7 +8473,10 @@ var MeshAsset = class {
8280
8473
  * @returns The handle, with one holder.
8281
8474
  */
8282
8475
  static sphere(app, options) {
8283
- return publish(app, "sphere", (engine) => buildSphereTemplate(engine, options));
8476
+ return publishPrimitive(app, {
8477
+ primitive: "sphere",
8478
+ options: options ?? {}
8479
+ });
8284
8480
  }
8285
8481
  /**
8286
8482
  * Creates a quad template in the XY plane and publishes it.
@@ -8290,7 +8486,10 @@ var MeshAsset = class {
8290
8486
  * @returns The handle, with one holder.
8291
8487
  */
8292
8488
  static plane(app, options) {
8293
- return publish(app, "plane", (engine) => buildPlaneTemplate(engine, options));
8489
+ return publishPrimitive(app, {
8490
+ primitive: "plane",
8491
+ options: options ?? {}
8492
+ });
8294
8493
  }
8295
8494
  /**
8296
8495
  * Creates a subdivided grid in the XZ plane and publishes it.
@@ -8300,8 +8499,10 @@ var MeshAsset = class {
8300
8499
  * @returns The handle, with one holder.
8301
8500
  */
8302
8501
  static ground(app, options) {
8303
- const lite = toGroundOptions(options);
8304
- return publish(app, "ground", (engine) => buildGroundTemplate(engine, lite));
8502
+ return publishPrimitive(app, {
8503
+ primitive: "ground",
8504
+ options: options ?? {}
8505
+ });
8305
8506
  }
8306
8507
  /**
8307
8508
  * Creates a cylinder template standing along Y and publishes it.
@@ -8311,7 +8512,10 @@ var MeshAsset = class {
8311
8512
  * @returns The handle, with one holder.
8312
8513
  */
8313
8514
  static cylinder(app, options) {
8314
- return publish(app, "cylinder", (engine) => buildCylinderTemplate(engine, options));
8515
+ return publishPrimitive(app, {
8516
+ primitive: "cylinder",
8517
+ options: options ?? {}
8518
+ });
8315
8519
  }
8316
8520
  /**
8317
8521
  * Creates a capsule template standing along Y and publishes it.
@@ -8321,7 +8525,10 @@ var MeshAsset = class {
8321
8525
  * @returns The handle, with one holder.
8322
8526
  */
8323
8527
  static capsule(app, options) {
8324
- return publish(app, "capsule", (engine) => buildCapsuleTemplate(engine, options));
8528
+ return publishPrimitive(app, {
8529
+ primitive: "capsule",
8530
+ options: options ?? {}
8531
+ });
8325
8532
  }
8326
8533
  /**
8327
8534
  * Creates a torus template in the XZ plane and publishes it.
@@ -8331,7 +8538,10 @@ var MeshAsset = class {
8331
8538
  * @returns The handle, with one holder.
8332
8539
  */
8333
8540
  static torus(app, options) {
8334
- return publish(app, "torus", (engine) => buildTorusTemplate(engine, options));
8541
+ return publishPrimitive(app, {
8542
+ primitive: "torus",
8543
+ options: options ?? {}
8544
+ });
8335
8545
  }
8336
8546
  /**
8337
8547
  * Creates a template from raw vertex data and publishes it.
@@ -8381,20 +8591,30 @@ function copyRange(source, target, components, vertexOffset, count) {
8381
8591
  target.set(source.subarray(0, floats), base);
8382
8592
  }
8383
8593
  /**
8384
- * Copies the ignifx ground options onto Lite's, which types `uvScale` as a mutable tuple.
8594
+ * Builds a primitive mesh asset without publishing it. The factories and the `.mesh.json` loader
8595
+ * both go through here, so a primitive is the same whether code or a file asked for it.
8385
8596
  *
8386
- * @param options - The declared options.
8387
- * @returns Lite's options, or `undefined` when the caller declared none.
8597
+ * @param app - The app whose engine uploads the geometry; a headless app uploads nothing.
8598
+ * @param name - A human-readable name.
8599
+ * @param definition - The primitive and its options.
8600
+ * @returns The asset, owned by the caller.
8601
+ *
8602
+ * @internal
8388
8603
  */
8389
- function toGroundOptions(options) {
8390
- if (options === void 0) return;
8391
- const result = {};
8392
- if (options.width !== void 0) result.width = options.width;
8393
- if (options.height !== void 0) result.height = options.height;
8394
- if (options.subdivisions !== void 0) result.subdivisions = options.subdivisions;
8395
- const uvScale = options.uvScale;
8396
- if (uvScale !== void 0) result.uvScale = [uvScale[0], uvScale[1]];
8397
- return result;
8604
+ function createPrimitiveMeshAsset(app, name, definition) {
8605
+ const handles = buildMeshTemplate(app.isHeadless, app.lite.scene, app.lite.engine, (engine) => buildPrimitiveTemplate(engine, definition));
8606
+ return new MeshAsset(name, handles.mesh, handles.scene, null, handles.engine);
8607
+ }
8608
+ /**
8609
+ * Builds a primitive and registers it as an in-memory asset named after the primitive.
8610
+ *
8611
+ * @param app - The app that owns the engine and the asset service.
8612
+ * @param definition - The primitive and its options.
8613
+ * @returns The handle, with one holder.
8614
+ */
8615
+ function publishPrimitive(app, definition) {
8616
+ const asset = createPrimitiveMeshAsset(app, definition.primitive, definition);
8617
+ return app.assets.register(asset, { type: MESH_ASSET_TYPE });
8398
8618
  }
8399
8619
  /**
8400
8620
  * Builds a template — skipping the upload under a headless app — and registers it as an in-memory
@@ -8487,7 +8707,7 @@ function forceDeviceLossForTesting(engine) {
8487
8707
  * @example
8488
8708
  * ```ts
8489
8709
  * const picker = createScenePicker(scene);
8490
- * const hit = await pickScenePixel(picker, event.offsetX, event.offsetY);
8710
+ * const hit = await pickScenePixel(picker, scene, 120, 80, null, []);
8491
8711
  * ```
8492
8712
  *
8493
8713
  * @internal
@@ -8496,44 +8716,116 @@ function createScenePicker(scene) {
8496
8716
  return createGpuPicker(scene);
8497
8717
  }
8498
8718
  /**
8499
- * Picks the object under one CSS pixel of the canvas.
8719
+ * The ratio Lite's picker multiplies a CSS pixel by, on one axis.
8720
+ *
8721
+ * @param backing - The canvas's backing-store size on that axis.
8722
+ * @param client - Its CSS layout size, or `0` when it has none.
8723
+ * @returns `backing / (client || backing)`, exactly as Lite computes it, or `1` for an empty canvas.
8724
+ */
8725
+ function liteScale(backing, client) {
8726
+ const css = client || backing;
8727
+ return css > 0 && backing > 0 ? backing / css : 1;
8728
+ }
8729
+ /**
8730
+ * Converts a backing-store coordinate to the CSS coordinate Lite's picker multiplies back.
8500
8731
  *
8501
8732
  * @remarks
8502
- * Coordinates are in CSS pixels relative to the canvas; Lite scales them by the backing-store ratio
8503
- * itself. The returned info carries `pickedPoint` and `pickedNormal` only when detailed picking is
8504
- * on ({@link enableScenePickerDetail}); without it, `pickedMesh` and `distance` are what a pick
8505
- * yields.
8733
+ * Lite renders its 1×1 target at the exact sub-pixel point it computes (`computePickVP`,
8734
+ * `lib/picking/gpu-picker.js` ~96 and ~224 in 1.34.0), so a whole-number coordinate samples a
8735
+ * pixel **corner**, not a centre; add 0.5 for the centre. The floored value only feeds the viewport
8736
+ * bounds check, the clamp and the discard rule's `fragmentCoord`. `x / scale * scale` can land one
8737
+ * unit in the last place below `x`, which would put a point on the viewport's edge outside it, or
8738
+ * floor to the pixel before; the result is nudged up until Lite's product is not below `x`.
8506
8739
  *
8507
- * @param picker - The picker.
8508
- * @param x - The CSS pixel x, from the canvas's left edge.
8509
- * @param y - The CSS pixel y, from the canvas's top edge.
8510
- * @param options - A mesh filter, identities to ignore, or a WGSL discard rule.
8511
- * @returns The hit. Calls on one picker run one at a time.
8740
+ * @param value - The backing-store coordinate.
8741
+ * @param scale - Lite's ratio on that axis.
8742
+ * @returns The CSS coordinate.
8512
8743
  *
8513
8744
  * @internal
8514
8745
  */
8515
- function pickScenePixel(picker, x, y, options) {
8516
- return pickAsync(picker, x, y, options);
8746
+ function toLitePickCoordinate(value, scale) {
8747
+ if (scale === 1) return value;
8748
+ let css = value / scale;
8749
+ for (let attempt = 0; attempt < 4 && css * scale < value; attempt += 1) css += Math.max(Math.abs(css) * Number.EPSILON, Number.MIN_VALUE);
8750
+ return css;
8517
8751
  }
8518
8752
  /**
8519
- * Picks the object under one CSS pixel, considering only the meshes whose ignifx tag a predicate
8520
- * accepts.
8753
+ * Picks the object under one backing-store pixel of the scene's canvas.
8521
8754
  *
8522
8755
  * @remarks
8523
- * The predicate is stated over the *tag* rather than over Lite's `Mesh` so that the component layer
8524
- * can filter by entity without naming a Lite type (`CONSTITUTION.md` §3.4). A rejected mesh is
8525
- * excluded from the candidate list entirely, so it neither occludes nor returns.
8756
+ * Coordinates are backing-store pixels — `canvas.width`/`height`, the space `Camera.worldToScreen`
8757
+ * and `<Pointer>/position` use. They are converted to the CSS pixels Lite's picker takes (see the
8758
+ * module notes). Meshes `accept` rejects, and the identities in `ignore`, neither occlude nor return.
8526
8759
  *
8527
8760
  * @param picker - The picker.
8528
- * @param x - The CSS pixel x, from the canvas's left edge.
8529
- * @param y - The CSS pixel y, from the canvas's top edge.
8530
- * @param accept - Decides whether a mesh may be picked, from the ignifx tag its node carries.
8531
- * @returns The hit.
8761
+ * @param scene - The scene the picker was created for; its surface's canvas sets the ratio.
8762
+ * @param x - The backing-store pixel x, from the canvas's left edge.
8763
+ * @param y - The backing-store pixel y, from the canvas's top edge.
8764
+ * @param accept - Decides whether a mesh may be picked, from the ignifx tag that owns it, or `null`
8765
+ * to consider every mesh.
8766
+ * @param ignore - Earlier hits to look through; a thin-instance hit skips only that instance.
8767
+ * @returns The hit. Calls on one picker run one at a time.
8768
+ *
8769
+ * @example
8770
+ * ```ts
8771
+ * const picker = createScenePicker(scene);
8772
+ * const hit = await pickScenePixel(picker, scene, 120, 80, null, []);
8773
+ * ```
8532
8774
  *
8533
8775
  * @internal
8534
8776
  */
8535
- function pickScenePixelWhere(picker, x, y, accept) {
8536
- return pickAsync(picker, x, y, { filter: (mesh) => accept(readNodeTag(mesh)) });
8777
+ function pickScenePixel(picker, scene, x, y, accept, ignore) {
8778
+ const canvas = scene.surface.canvas;
8779
+ const clientWidth = "clientWidth" in canvas ? canvas.clientWidth : 0;
8780
+ const clientHeight = "clientHeight" in canvas ? canvas.clientHeight : 0;
8781
+ const cssX = toLitePickCoordinate(x, liteScale(canvas.width, clientWidth));
8782
+ const cssY = toLitePickCoordinate(y, liteScale(canvas.height, clientHeight));
8783
+ const options = {};
8784
+ if (accept !== null) options.filter = (mesh) => accept(readOwnerTag(mesh), mesh);
8785
+ if (ignore.length > 0) options.ignore = toLiteIgnore(ignore);
8786
+ return pickAsync(picker, cssX, cssY, options);
8787
+ }
8788
+ /**
8789
+ * Folds earlier hits into Lite's ignore list, one entry per mesh.
8790
+ *
8791
+ * @remarks
8792
+ * Lite reads only the **first** entry it finds for a mesh (`lib/picking/picking-ignore.js`,
8793
+ * `forMesh`), so several hits on one mesh are merged here: a whole-mesh hit wins, thin instances
8794
+ * that form one contiguous run become a range, and otherwise the lowest index is kept — a Lite
8795
+ * 1.34 limit, which a caller cycling through instances of one renderer can meet.
8796
+ *
8797
+ * @param ignore - The hits to look through.
8798
+ * @returns Lite's entries.
8799
+ */
8800
+ function toLiteIgnore(ignore) {
8801
+ const byMesh = /* @__PURE__ */ new Map();
8802
+ for (const identity of ignore) {
8803
+ const indices = byMesh.get(identity.mesh);
8804
+ if (identity.thinInstanceIndex < 0 || indices === null) byMesh.set(identity.mesh, null);
8805
+ else if (indices === void 0) byMesh.set(identity.mesh, [identity.thinInstanceIndex]);
8806
+ else indices.push(identity.thinInstanceIndex);
8807
+ }
8808
+ const entries = [];
8809
+ for (const [mesh, indices] of byMesh) {
8810
+ if (indices === null) {
8811
+ entries.push({ mesh });
8812
+ continue;
8813
+ }
8814
+ const sorted = [...new Set(indices)].toSorted((a, b) => a - b);
8815
+ const first = sorted[0] ?? 0;
8816
+ const last = sorted.at(-1) ?? first;
8817
+ entries.push(sorted.length === 1 || last - first + 1 !== sorted.length ? {
8818
+ mesh,
8819
+ thinInstanceIndex: first
8820
+ } : {
8821
+ mesh,
8822
+ thinInstanceRange: {
8823
+ start: first,
8824
+ count: sorted.length
8825
+ }
8826
+ });
8827
+ }
8828
+ return entries;
8537
8829
  }
8538
8830
  /**
8539
8831
  * Releases a picker's GPU resources.
@@ -8883,25 +9175,26 @@ function canWarmUp(material) {
8883
9175
  *
8884
9176
  * Everything here is `@internal`.
8885
9177
  *
8886
- * ## Why the render layer has to know (verified against `@babylonjs/lite@1.27.0`)
9178
+ * ## Why the render layer has to know (verified against `@babylonjs/lite@1.34.0`)
8887
9179
  *
8888
9180
  * Lite registers the PBR skinning and morph-target shader fragments only inside a full build of
8889
9181
  * the PBR group, and only when that build contains a skinned or morphed mesh (`buildPbrRenderables`,
8890
- * `lib/material/pbr/pbr-renderable.js` 114-117). A mesh added after `registerScene` to a PBR group
9182
+ * `lib/material/pbr/pbr-renderable.js` 112). A mesh added after `registerScene` to a PBR group
8891
9183
  * that already exists is built at once by the group's `rebuildSingle` instead
8892
- * (`processMaterialSwaps`, `lib/scene/scene-material-swap.js` 22-45), and that never registers
9184
+ * (`processMaterialSwaps`, `lib/scene/scene-material-swap.js` 4-45), and that never registers
8893
9185
  * them. ignifx's warm-up builds the PBR group at start whenever the scene has a light (ADR-0014).
8894
9186
  *
8895
9187
  * So the first skinned model a page adds after `app.start()` is composed without its skinning
8896
9188
  * fragment, and Lite caches that bind-group layout under a key that does not say which fragments
8897
- * were registered (`getOrCreatePbrBindings`, `lib/material/pbr/pbr-pipeline.js` 33-36). The next
9189
+ * were registered (`getOrCreatePbrBindings`, `lib/material/pbr/pbr-pipeline.js` 59-63). The next
8898
9190
  * renderable rebuild registers the fragment, reuses the cached layout, and builds a bind group with
8899
9191
  * one more entry than it: WebGPU rejects every frame from then on ("Binding entry sampler not set",
8900
9192
  * group 1, entries[3]) and the canvas stays black. The fragments are registered process-wide, so
8901
9193
  * every later app in the page was fine.
8902
9194
  *
8903
9195
  * The render sync system compares what this reports with what a full build has already composed,
8904
- * and clears Lite's layout caches before the rebuild that first sees a new kind. Until that
9196
+ * and clears Lite's layout caches (`forgetMaterialBindingLayouts`, `./shadow.ts`) before the
9197
+ * rebuild that first sees a new kind. Until that
8905
9198
  * rebuild, one frame after the mesh arrives, a skinned mesh draws in its bind pose; a morphed one
8906
9199
  * gets a shader that does not compile, so WebGPU rejects that frame or two.
8907
9200
  */
@@ -9293,6 +9586,411 @@ function disposeSceneOnly(scene) {
9293
9586
  disposeScene(scene);
9294
9587
  }
9295
9588
  //#endregion
9589
+ //#region src/lite/shadow.ts
9590
+ /**
9591
+ * The shadow techniques Lite offers, in the order `docs/architecture/07-rendering.md` §2.2 lists them.
9592
+ *
9593
+ * @public
9594
+ */
9595
+ const SHADOW_TECHNIQUES = [
9596
+ "esm",
9597
+ "pcf",
9598
+ "csm"
9599
+ ];
9600
+ /**
9601
+ * Refuses to build a shadow generator for a light kind Lite cannot shadow.
9602
+ *
9603
+ * @remarks
9604
+ * Lite has no point-light (cube) shadow generator and no area lights
9605
+ * (`docs/architecture/07-rendering.md` §8). Hemispheric lights have no position or frustum at all.
9606
+ *
9607
+ * @param lightType - The Lite `lightType` discriminant of the light.
9608
+ * @throws IgnifxError with code `IGX-0703` for any light kind other than `directional` or `spot`.
9609
+ *
9610
+ * @example
9611
+ * ```ts
9612
+ * assertShadowsSupported(light.lightType); // throws IGX-0703 for "point"
9613
+ * ```
9614
+ *
9615
+ * @internal
9616
+ */
9617
+ function assertShadowsSupported(lightType) {
9618
+ if (lightType === "directional" || lightType === "spot") return;
9619
+ throw new IgnifxError(CoreErrorCode.shadowsUnsupportedForLight, `Babylon Lite has no shadow generator for a ${lightType} light.`, {
9620
+ context: { lightType },
9621
+ hint: "Cast shadows from a directional or spot light instead."
9622
+ });
9623
+ }
9624
+ /**
9625
+ * Turns shadows on for a light by attaching its generator.
9626
+ *
9627
+ * @param light - The light that should cast shadows.
9628
+ * @param generator - A generator built for that light by `./gpu/shadow-generator.ts`.
9629
+ *
9630
+ * @internal
9631
+ */
9632
+ function attachShadowGenerator(light, generator) {
9633
+ light.shadowGenerator = generator;
9634
+ }
9635
+ /**
9636
+ * Turns shadows off for a light.
9637
+ *
9638
+ * @remarks
9639
+ * This only breaks the link. The generator's GPU resources are released when the scene disposes it
9640
+ * through {@link disposeShadowGenerator}.
9641
+ *
9642
+ * @param light - The light that should stop casting shadows.
9643
+ *
9644
+ * @internal
9645
+ */
9646
+ function detachShadowGenerator(light) {
9647
+ delete light.shadowGenerator;
9648
+ }
9649
+ /**
9650
+ * Replaces the list of meshes a generator renders into its shadow map.
9651
+ *
9652
+ * @remarks
9653
+ * Lite keys the list by array identity and re-preloads the shadow pipeline every time a **new**
9654
+ * array arrives, skipping the generator until that finishes. Callers therefore build the list once
9655
+ * per change, never per frame.
9656
+ *
9657
+ * @param generator - The shadow generator.
9658
+ * @param casters - The meshes that cast into it.
9659
+ *
9660
+ * @internal
9661
+ */
9662
+ function setShadowCasters(generator, casters) {
9663
+ setShadowTaskCasterMeshes(generator, casters);
9664
+ }
9665
+ /**
9666
+ * Creates an empty record of a scene's material cache resets.
9667
+ *
9668
+ * @returns The record; install it with {@link trackMaterialCacheResets}.
9669
+ *
9670
+ * @internal
9671
+ */
9672
+ function createMaterialCacheResets() {
9673
+ return {
9674
+ found: /* @__PURE__ */ new Set(),
9675
+ seen: /* @__PURE__ */ new WeakSet(),
9676
+ unconfirmed: false,
9677
+ retries: 0
9678
+ };
9679
+ }
9680
+ /**
9681
+ * Starts recording what the scene's disposer list is handed, for the scene's lifetime.
9682
+ *
9683
+ * @remarks
9684
+ * Call it before the scene is registered, so the builds `registerScene` runs are seen too. It is
9685
+ * idempotent. An own `push` shadows `Array.prototype.push` on that one array; Lite only ever appends
9686
+ * to it with `push`.
9687
+ *
9688
+ * @param scene - The scene.
9689
+ * @param resets - Where to record.
9690
+ *
9691
+ * @internal
9692
+ */
9693
+ function trackMaterialCacheResets(scene, resets) {
9694
+ const disposables = scene._disposables;
9695
+ if (disposables === void 0 || Object.hasOwn(disposables, "push")) return;
9696
+ Object.defineProperty(disposables, "push", {
9697
+ configurable: true,
9698
+ writable: true,
9699
+ value: (...items) => {
9700
+ for (const item of items) if (disposables.includes(item)) resets.found.add(item);
9701
+ else if (!resets.seen.has(item)) {
9702
+ resets.seen.add(item);
9703
+ resets.unconfirmed = true;
9704
+ }
9705
+ return Array.prototype.push.apply(disposables, items);
9706
+ }
9707
+ });
9708
+ }
9709
+ /**
9710
+ * Rebuilds every material group of a registered scene so renderables pick up the current light and
9711
+ * shadow topology.
9712
+ *
9713
+ * @remarks
9714
+ * Renderables bake the per-mesh light index list, the single- versus multi-light shader
9715
+ * permutation, and each generator's shadow bind group at build time; none of that follows a light
9716
+ * being added, removed, or given a generator (`rebuildSceneRenderables`, `index.d.ts` 11165). The
9717
+ * call is a no-op before the scene's first build, and it is expensive, so the component layer
9718
+ * coalesces every topology change in a frame into one call.
9719
+ *
9720
+ * With `resets`, a rebuild that built a material family for the first time rebuilds once more
9721
+ * straight away, so the family's cache reset is known before anything needs it; see
9722
+ * {@link MaterialCacheResets}.
9723
+ *
9724
+ * The engine frees nothing the rebuild retires until the rebuild has finished; see
9725
+ * `holdGpuRetirements`.
9726
+ *
9727
+ * @param scene - The scene to rebuild.
9728
+ * @param resets - The scene's record of cache resets.
9729
+ * @returns A promise that resolves when the rebuild has finished.
9730
+ *
9731
+ * @internal
9732
+ */
9733
+ async function rebuildRenderables(scene, resets) {
9734
+ const release = holdGpuRetirements(scene.surface.engine);
9735
+ try {
9736
+ if (resets === void 0) {
9737
+ await rebuildAcrossMaterialSwaps(scene);
9738
+ return;
9739
+ }
9740
+ trackMaterialCacheResets(scene, resets);
9741
+ takeUnconfirmed(resets);
9742
+ await rebuildAcrossMaterialSwaps(scene, resets);
9743
+ if (takeUnconfirmed(resets)) await rebuildAcrossMaterialSwaps(scene, resets);
9744
+ } finally {
9745
+ release();
9746
+ }
9747
+ }
9748
+ /** How many times {@link rebuildAcrossMaterialSwaps} starts over after a swap broke a rebuild. */
9749
+ const MAX_SWAP_RETRIES = 2;
9750
+ /**
9751
+ * Runs `rebuildSceneRenderables`, and runs it again when a material swap landed during it and made
9752
+ * it throw.
9753
+ *
9754
+ * @remarks
9755
+ * A group builder awaits its shader modules (`import()`) before it reads each mesh's material, and
9756
+ * on a loaded machine that await spans frames. A mesh given a material of another family meanwhile
9757
+ * reaches the old family's builder: the Standard one reads `diffuseColor[0]` off a PBR material and
9758
+ * throws `Cannot read properties of undefined (reading '0')` (`buildStandardMeshRenderables`,
9759
+ * `writeStdMaterialData`, `lib/material/standard/standard-pipeline.js` 278). Lite expects swaps to
9760
+ * land mid-build — it puts the group's old renderables back on a throw, and a rebuild that does not
9761
+ * throw re-sorts the groups and goes round again (`membershipDrifted`, `lib/scene/scene-rebuild.js`)
9762
+ * — but it rethrows, so the rest of the rebuild is skipped. Starting over sorts the groups from the
9763
+ * current materials. A throw with every material unchanged is not this race, and is rethrown.
9764
+ *
9765
+ * @param scene - The scene to rebuild.
9766
+ * @param resets - The scene's record, which counts the restarts.
9767
+ * @param retries - How many more times to start over.
9768
+ * @returns A promise that resolves when a rebuild has finished.
9769
+ */
9770
+ async function rebuildAcrossMaterialSwaps(scene, resets, retries = MAX_SWAP_RETRIES) {
9771
+ const meshes = scene.meshes;
9772
+ const materials = meshes.map((mesh) => mesh.material);
9773
+ try {
9774
+ await rebuildSceneRenderables(scene);
9775
+ } catch (error) {
9776
+ if (!(scene.meshes !== meshes || meshes.some((mesh, index) => mesh.material !== materials[index])) || retries <= 0) throw error;
9777
+ if (resets !== void 0) resets.retries += 1;
9778
+ await rebuildAcrossMaterialSwaps(scene, resets, retries - 1);
9779
+ }
9780
+ }
9781
+ /**
9782
+ * Keeps an engine from freeing retired GPU resources until the returned function is called.
9783
+ *
9784
+ * @remarks
9785
+ * `rebuildSceneRenderables` rebuilds one material group at a time and retires each group's old
9786
+ * uniform buffers and bind groups as soon as that group is done, but it only bumps
9787
+ * `_renderableVersion` and re-records the frame graph after the **last** group
9788
+ * (`rebuildSceneGroups`, `lib/scene/scene-rebuild.js`). Until then every frame still draws the old
9789
+ * renderables. Lite frees a retired resource once the next submitted frame has finished
9790
+ * (`flushGpuResourceRetirements`, `lib/engine/gpu-resource-retirement.js`), so when a later group
9791
+ * takes two frames or more to build — a slow machine, or a pipeline to compile — the following
9792
+ * frames submit buffers that are already destroyed, and WebGPU rejects them ("[Buffer] used in
9793
+ * submit while destroyed"). Holding the releases until the whole rebuild has finished means they
9794
+ * are fenced behind the first frame that draws the new renderables.
9795
+ *
9796
+ * While a hold is active, `_flushGpuRetirements` reads as absent, so `renderFrame` skips it and
9797
+ * the retired resources wait in the engine's list. Lite installs the flush with `??=`, so an
9798
+ * assignment it makes meanwhile is kept only when it had none before. Holds nest.
9799
+ *
9800
+ * @param engine - The engine that renders the scene being rebuilt.
9801
+ * @returns A function that ends this hold. Call it once.
9802
+ */
9803
+ function holdGpuRetirements(engine) {
9804
+ const target = engine;
9805
+ let hold = target._igxRetirementHold;
9806
+ if (hold === void 0) {
9807
+ const state = {
9808
+ count: 0,
9809
+ flush: target._flushGpuRetirements
9810
+ };
9811
+ Object.defineProperty(target, "_flushGpuRetirements", {
9812
+ configurable: true,
9813
+ enumerable: true,
9814
+ get: () => state.count > 0 ? void 0 : state.flush,
9815
+ set: (flush) => {
9816
+ state.flush ??= flush;
9817
+ }
9818
+ });
9819
+ Object.defineProperty(target, "_igxRetirementHold", {
9820
+ configurable: true,
9821
+ value: state
9822
+ });
9823
+ hold = state;
9824
+ }
9825
+ const held = hold;
9826
+ held.count += 1;
9827
+ return () => {
9828
+ held.count -= 1;
9829
+ if (held.count === 0) {
9830
+ Object.defineProperty(target, "_flushGpuRetirements", {
9831
+ configurable: true,
9832
+ enumerable: true,
9833
+ writable: true,
9834
+ value: held.flush
9835
+ });
9836
+ delete target._igxRetirementHold;
9837
+ }
9838
+ };
9839
+ }
9840
+ /**
9841
+ * Reads and clears {@link MaterialCacheResets.unconfirmed}.
9842
+ *
9843
+ * @param resets - The record.
9844
+ * @returns Whether a never-seen function was pushed since the flag was last cleared.
9845
+ */
9846
+ function takeUnconfirmed(resets) {
9847
+ const unconfirmed = resets.unconfirmed;
9848
+ resets.unconfirmed = false;
9849
+ return unconfirmed;
9850
+ }
9851
+ /**
9852
+ * Rebuilds a freshly registered scene once when its registration built anything, so Lite pushes
9853
+ * its cache resets again and {@link forgetMaterialBindingLayouts} can call them from the first
9854
+ * frame on.
9855
+ *
9856
+ * @remarks
9857
+ * Nothing has changed since registration, so every pipeline and layout comes from Lite's caches and
9858
+ * the rebuild only re-creates uniform buffers and bind groups.
9859
+ *
9860
+ * @param scene - The registered scene.
9861
+ * @param resets - The scene's record, installed with {@link trackMaterialCacheResets} before
9862
+ * registration.
9863
+ * @returns A promise that resolves when the rebuild has finished.
9864
+ *
9865
+ * @internal
9866
+ */
9867
+ async function learnMaterialCacheResets(scene, resets) {
9868
+ if (resets.unconfirmed) await rebuildRenderables(scene, resets);
9869
+ }
9870
+ /**
9871
+ * How many times the scene's materials have been rebuilt.
9872
+ *
9873
+ * @remarks
9874
+ * An ESM generator keeps the caster views it built for a caster array until it is handed a
9875
+ * different array, whatever happens to the materials (`ensureEsmShadowTaskState`,
9876
+ * `lib/shadow/esm-directional-shadow-generator.js` 121-126; PCF and CSM compare each material's
9877
+ * `_csmGen` instead). So a surface shader switched on or off went on drawing the old shape into an
9878
+ * ESM map. The render sync system re-supplies the caster lists whenever this moves.
9879
+ *
9880
+ * @param scene - The scene.
9881
+ * @returns The counter; `0` before anything was built.
9882
+ *
9883
+ * @internal
9884
+ */
9885
+ function readMaterialEpoch(scene) {
9886
+ return scene._materialEpoch ?? 0;
9887
+ }
9888
+ /**
9889
+ * Makes the next renderable rebuild create fresh bind-group layouts for every material.
9890
+ *
9891
+ * @remarks
9892
+ * Call it before {@link rebuildRenderables} whenever a light gained or lost a shadow generator,
9893
+ * and when the scene gained its first skinned or morphed PBR mesh (`./pbr-deformers.ts`).
9894
+ * Lite caches a PBR material's bindings, shadow bind-group layout included, under a key that does
9895
+ * not name the shadow maps (`getOrCreatePbrBindings`, `lib/material/pbr/pbr-pipeline.js` 59-63).
9896
+ * So after the number of shadow-casting lights changes, a rebuild reuses a layout sized for the old
9897
+ * number and builds a bind group for the new one, and WebGPU rejects every frame ("Number of
9898
+ * entries (3) did not match the expected number of entries (6)"). Clearing the caches costs one
9899
+ * pipeline rebuild per material, only on a frame whose shadow casters changed.
9900
+ *
9901
+ * @param resets - The resets the scene's rebuilds identified; see {@link MaterialCacheResets}.
9902
+ *
9903
+ * @internal
9904
+ */
9905
+ function forgetMaterialBindingLayouts(resets) {
9906
+ for (const reset of resets.found) reset();
9907
+ }
9908
+ /**
9909
+ * Releases a shadow generator's GPU resources and unlinks it from its light.
9910
+ *
9911
+ * @remarks
9912
+ * `removeFromScene` recognises a shadow generator by its private `_shadowType`/`_light` fields
9913
+ * (`lib/scene/scene-remove.js`), clears `light.shadowGenerator`, marks the scene's light topology
9914
+ * dirty, and queues the generator's task for disposal after the GPU has drained.
9915
+ *
9916
+ * @param scene - The scene the generator was rendering into.
9917
+ * @param generator - The generator to release.
9918
+ *
9919
+ * @internal
9920
+ */
9921
+ function disposeShadowGenerator(scene, generator) {
9922
+ removeFromScene(scene, generator);
9923
+ }
9924
+ /**
9925
+ * Maps the shared settings onto an exponential shadow map's configuration.
9926
+ *
9927
+ * @param settings - The declared settings.
9928
+ * @returns Lite's configuration, with every field the caller left out omitted.
9929
+ *
9930
+ * @internal
9931
+ */
9932
+ function toEsmConfig(settings) {
9933
+ const config = {};
9934
+ if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
9935
+ if (settings.bias !== void 0) config.bias = settings.bias;
9936
+ if (settings.darkness !== void 0) config.darkness = settings.darkness;
9937
+ return config;
9938
+ }
9939
+ /**
9940
+ * Maps the shared settings onto a percentage-closer-filtered directional shadow map's configuration.
9941
+ *
9942
+ * @param settings - The declared settings.
9943
+ * @returns Lite's configuration.
9944
+ *
9945
+ * @internal
9946
+ */
9947
+ function toPcfConfig(settings) {
9948
+ const config = {};
9949
+ if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
9950
+ if (settings.bias !== void 0) config.bias = settings.bias;
9951
+ if (settings.normalBias !== void 0) config.normalBias = settings.normalBias;
9952
+ if (settings.darkness !== void 0) config.darkness = settings.darkness;
9953
+ return config;
9954
+ }
9955
+ /**
9956
+ * Maps the shared settings onto a cascaded shadow map's configuration.
9957
+ *
9958
+ * @remarks
9959
+ * `cascades` becomes `numCascades` and `maxDistance` becomes `shadowMaxZ`; Lite clamps the cascade
9960
+ * count to four (`index.d.ts` 3515).
9961
+ *
9962
+ * @param settings - The declared settings.
9963
+ * @returns Lite's configuration.
9964
+ *
9965
+ * @internal
9966
+ */
9967
+ function toCsmConfig(settings) {
9968
+ const config = {};
9969
+ if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
9970
+ if (settings.bias !== void 0) config.bias = settings.bias;
9971
+ if (settings.darkness !== void 0) config.darkness = settings.darkness;
9972
+ if (settings.cascades !== void 0) config.numCascades = settings.cascades;
9973
+ if (settings.maxDistance !== void 0) config.shadowMaxZ = settings.maxDistance;
9974
+ return config;
9975
+ }
9976
+ /**
9977
+ * Maps the shared settings onto a spot light's shadow configuration.
9978
+ *
9979
+ * @param settings - The declared settings.
9980
+ * @returns Lite's configuration.
9981
+ *
9982
+ * @internal
9983
+ */
9984
+ function toSpotConfig(settings) {
9985
+ const config = {};
9986
+ if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
9987
+ if (settings.bias !== void 0) config.bias = settings.bias;
9988
+ if (settings.normalBias !== void 0) config.normalBias = settings.normalBias;
9989
+ if (settings.darkness !== void 0) config.darkness = settings.darkness;
9990
+ if (settings.maxDistance !== void 0) config.far = settings.maxDistance;
9991
+ return config;
9992
+ }
9993
+ //#endregion
9296
9994
  //#region src/render/gpu/renderer-gpu.ts
9297
9995
  /**
9298
9996
  * The device-only half of `app.renderer` (`docs/architecture/07-rendering.md` §1, §3, §5).
@@ -9315,18 +10013,35 @@ function createPicker(scene) {
9315
10013
  return createScenePicker(scene);
9316
10014
  }
9317
10015
  /**
9318
- * Picks the object under one CSS pixel, optionally restricted to the meshes a predicate accepts.
10016
+ * Loads the overlay module (`docs/architecture/07-rendering.md` §2.10).
10017
+ *
10018
+ * @remarks
10019
+ * It is loaded on first use, so a game that never opens an overlay ships none of it
10020
+ * (`CONSTITUTION.md` §2.5).
10021
+ *
10022
+ * @returns The function that opens an overlay scene.
10023
+ *
10024
+ * @internal
10025
+ */
10026
+ async function loadOverlayOpener() {
10027
+ return (await import("./overlay-CjVgsfrm.js")).openOverlayScene;
10028
+ }
10029
+ /**
10030
+ * Picks the object under one backing-store pixel, optionally restricted to the meshes a predicate
10031
+ * accepts and looking through earlier hits.
9319
10032
  *
9320
10033
  * @param picker - The app's picker.
9321
- * @param x - The CSS pixel x, from the canvas's left edge.
9322
- * @param y - The CSS pixel y, from the canvas's top edge.
10034
+ * @param scene - The scene the picker belongs to.
10035
+ * @param x - The backing-store pixel x, from the canvas's left edge.
10036
+ * @param y - The backing-store pixel y, from the canvas's top edge.
9323
10037
  * @param accept - The tag predicate, or `null` to consider every mesh.
10038
+ * @param ignore - Earlier hits to look through.
9324
10039
  * @returns Lite's picking info.
9325
10040
  *
9326
10041
  * @internal
9327
10042
  */
9328
- function pickPixel(picker, x, y, accept) {
9329
- return accept === null ? pickScenePixel(picker, x, y) : pickScenePixelWhere(picker, x, y, accept);
10043
+ function pickPixel(picker, scene, x, y, accept, ignore) {
10044
+ return pickScenePixel(picker, scene, x, y, accept, ignore);
9330
10045
  }
9331
10046
  /**
9332
10047
  * Installs one hidden probe per material so their families are compiled at `registerScene`
@@ -9849,10 +10564,19 @@ var RendererImpl = class {
9849
10564
  /** `true` once a light gained or lost a shadow generator, so the next rebuild needs fresh layouts. */
9850
10565
  needsShadowLayoutReset = false;
9851
10566
  /**
10567
+ * `true` from the moment the render sync system queues a renderable rebuild until the last one it
10568
+ * owes has finished. A light waits for it to be `false` before it gains or loses a shadow generator.
10569
+ */
10570
+ isRebuildInFlight = false;
10571
+ /** Scene changes held back until the rebuild in flight has finished; see {@link RendererImpl.afterRebuild}. */
10572
+ #afterRebuild = [];
10573
+ /**
9852
10574
  * The PBR deformation kinds (`PBR_DEFORMER` bits) a full renderable build has already composed on
9853
10575
  * this engine. A kind missing from it gets fresh layouts on its first rebuild (`../lite/pbr-deformers.ts`).
9854
10576
  */
9855
10577
  builtPbrDeformers = 0;
10578
+ /** Lite's material cache resets, as this scene's rebuilds identified them (`../lite/shadow.ts`). */
10579
+ materialCacheResets = createMaterialCacheResets();
9856
10580
  /** `true` once a camera was added, removed, enabled, disabled, or re-prioritised. */
9857
10581
  needsCameraSelect = true;
9858
10582
  /** `true` once the world has been told it has no enabled camera, so `IGX-0706` is logged once. */
@@ -9871,6 +10595,10 @@ var RendererImpl = class {
9871
10595
  #countersMeshes;
9872
10596
  #countersRebuilds;
9873
10597
  #picker = null;
10598
+ /** The mesh behind each hit this renderer returned, so a later pick can be told to ignore it. */
10599
+ #pickIdentities = /* @__PURE__ */ new WeakMap();
10600
+ /** The open overlays, by their Lite scene. */
10601
+ #overlays = /* @__PURE__ */ new Map();
9874
10602
  #warmUp = null;
9875
10603
  #syncSystem = null;
9876
10604
  /** Adapter chunks a component asked for; `app.start()` waits for them before it reconciles. */
@@ -9883,6 +10611,7 @@ var RendererImpl = class {
9883
10611
  #profileTasks = false;
9884
10612
  #isSceneRegistered = false;
9885
10613
  #isLoopRunning = false;
10614
+ #isDisposed = false;
9886
10615
  /** The clear colour as authored, in sRGB, before image processing. */
9887
10616
  #authoredClear = {
9888
10617
  r: 0,
@@ -10127,14 +10856,14 @@ var RendererImpl = class {
10127
10856
  *
10128
10857
  * @param x - The backing-store pixel x, from the canvas's left edge.
10129
10858
  * @param y - The backing-store pixel y, from the canvas's top edge.
10130
- * @param options - An entity filter.
10859
+ * @param options - An entity filter, and what to look through.
10131
10860
  * @returns What was hit, or `null` for a miss.
10132
10861
  */
10133
10862
  async pickAsync(x, y, options) {
10134
10863
  if (this.isHeadless) return null;
10135
10864
  const picker = this.#picker ??= createPicker(this.scene);
10136
- const filter = options?.filter;
10137
- const info = await pickPixel(picker, x, y, filter === void 0 ? null : (tag) => acceptsEntityTag(this.#app.world, tag, filter));
10865
+ const plan = this.planPick(options);
10866
+ const info = await pickPixel(picker, this.scene, x, y, plan.accept, plan.hits);
10138
10867
  return this.resolvePick(info);
10139
10868
  }
10140
10869
  /**
@@ -10172,6 +10901,61 @@ var RendererImpl = class {
10172
10901
  this.#features[feature] = true;
10173
10902
  }
10174
10903
  /**
10904
+ * Opens an overlay drawn over the finished frame.
10905
+ *
10906
+ * @returns The overlay.
10907
+ * @throws IgnifxError with code `IGX-0728` on a headless app or before the render scene is
10908
+ * registered, and `IGX-0106` when the app is disposed, also while the overlay was opening.
10909
+ */
10910
+ async openOverlay() {
10911
+ this.#assertOverlayAllowed();
10912
+ const open = await loadOverlayOpener();
10913
+ this.#assertOverlayAllowed();
10914
+ const overlays = this.#overlays;
10915
+ let overlay;
10916
+ try {
10917
+ overlay = await open(this.engine, this.scene, {
10918
+ isPeer: (context) => overlays.has(context),
10919
+ onDispose: (scene) => {
10920
+ overlays.delete(scene);
10921
+ },
10922
+ onError: (error) => {
10923
+ this.#app.onError.emit({
10924
+ error,
10925
+ source: "system",
10926
+ phase: null,
10927
+ entity: null,
10928
+ component: null
10929
+ });
10930
+ }
10931
+ });
10932
+ } catch (error) {
10933
+ if (this.#isDisposed) throw overlayAfterDisposeError();
10934
+ throw error;
10935
+ }
10936
+ if (this.#isDisposed) {
10937
+ overlay.dispose();
10938
+ throw overlayAfterDisposeError();
10939
+ }
10940
+ overlays.set(overlay.lite.scene, overlay);
10941
+ return overlay;
10942
+ }
10943
+ /**
10944
+ * Refuses an overlay on a disposed or headless app, or before the render scene is registered.
10945
+ *
10946
+ * @throws IgnifxError with code `IGX-0106` once the app is disposed, `IGX-0728` otherwise.
10947
+ */
10948
+ #assertOverlayAllowed() {
10949
+ if (this.#isDisposed) throw overlayAfterDisposeError();
10950
+ if (this.isHeadless || !this.#isSceneRegistered) throw new IgnifxError(CoreErrorCode.overlayNeedsRenderScene, "openOverlay() needs a canvas-backed app whose render scene is registered.", {
10951
+ context: {
10952
+ member: "app.renderer.openOverlay()",
10953
+ headless: this.isHeadless
10954
+ },
10955
+ hint: this.isHeadless ? "A headless app draws nothing, so it has no overlay. Create the app with a canvas." : "Call it after app.start() has resolved."
10956
+ });
10957
+ }
10958
+ /**
10175
10959
  * Registers a probe that answers whether another rendering context has a camera of its own.
10176
10960
  *
10177
10961
  * @param probe - Answers `true` while the caller has an active camera for the world.
@@ -10240,10 +11024,52 @@ var RendererImpl = class {
10240
11024
  readTargetSizePx(this.engine, out);
10241
11025
  }
10242
11026
  /**
11027
+ * Turns a pick's options into the mesh predicate and the earlier hits Lite looks through.
11028
+ *
11029
+ * @param options - The caller's options.
11030
+ * @returns The predicate — `null` when every mesh may be picked — and the hits to ignore.
11031
+ *
11032
+ * @internal
11033
+ */
11034
+ planPick(options) {
11035
+ const filter = options?.filter;
11036
+ const ignore = options?.ignore;
11037
+ if (ignore === void 0 || ignore.length === 0) {
11038
+ const world = this.#app.world;
11039
+ return {
11040
+ accept: filter === void 0 ? null : (tag) => acceptsEntityTag(world, tag, filter),
11041
+ hits: []
11042
+ };
11043
+ }
11044
+ const world = this.#app.world;
11045
+ const entities = /* @__PURE__ */ new Set();
11046
+ const components = /* @__PURE__ */ new Set();
11047
+ const hits = [];
11048
+ for (const item of ignore) {
11049
+ const identity = this.#pickIdentities.get(item);
11050
+ if (identity !== void 0) hits.push(identity);
11051
+ else if ("children" in item) {
11052
+ if (!item.isDestroyed && world.getEntityByHandle(item.handle) === item) entities.add(item.handle);
11053
+ } else if ("isDestroyed" in item && !item.isDestroyed && world.getComponentByHandle(item.handle) === item) components.add(item.handle);
11054
+ }
11055
+ if (filter === void 0 && entities.size === 0 && components.size === 0) return {
11056
+ accept: null,
11057
+ hits
11058
+ };
11059
+ return {
11060
+ accept: (tag) => {
11061
+ if (tag === null) return filter === void 0;
11062
+ if (entities.has(tag.entity) || tag.component !== void 0 && components.has(tag.component)) return false;
11063
+ return filter === void 0 || acceptsEntityTag(world, tag, filter);
11064
+ },
11065
+ hits
11066
+ };
11067
+ }
11068
+ /**
10243
11069
  * Resolves a Lite pick result back to the entity and component that own the mesh.
10244
11070
  *
10245
11071
  * @param info - Lite's picking info, from the GPU picker or a CPU ray cast.
10246
- * @returns What was hit, or `null` for a miss or a mesh ignifx did not create.
11072
+ * @returns What was hit, or `null` for a miss or a mesh no entity owns.
10247
11073
  *
10248
11074
  * @internal
10249
11075
  */
@@ -10255,13 +11081,19 @@ var RendererImpl = class {
10255
11081
  const entity = world.getEntityByHandle(toEntityHandle(tag.entity));
10256
11082
  if (entity === null) return null;
10257
11083
  const component = tag.component;
10258
- return {
11084
+ const thinInstanceIndex = info.thinInstanceIndex >= 0 ? info.thinInstanceIndex : null;
11085
+ const pick = {
10259
11086
  entity,
10260
11087
  component: component === void 0 ? null : world.getComponentByHandle(toComponentHandle(component)),
10261
11088
  point: info.pickedPoint,
10262
11089
  normal: info.pickedNormalWorld ?? info.pickedNormal,
10263
- distance: info.distance
11090
+ distance: info.distance,
11091
+ meshName: readPickedMeshName(info),
11092
+ thinInstanceIndex
10264
11093
  };
11094
+ const identity = readPickedIdentity(info);
11095
+ if (identity !== null) this.#pickIdentities.set(pick, identity);
11096
+ return pick;
10265
11097
  }
10266
11098
  /**
10267
11099
  * Records the Lite objects the app owns, so the service keeps working while the app is being
@@ -10455,11 +11287,47 @@ var RendererImpl = class {
10455
11287
  counters.set(this.#countersRebuilds, this.renderableRebuilds);
10456
11288
  }
10457
11289
  /**
10458
- * Releases the picker and the warm-up probes. The core extension registers it as a disposer.
11290
+ * Runs a scene change now, or holds it until the render sync system's rebuild has finished when
11291
+ * one is in flight.
11292
+ *
11293
+ * @remarks
11294
+ * For a change a rebuild must not see half-way: one that changes how many shadow generators the
11295
+ * scene has. A rebuild reads them group by group against layouts cached without that number, so
11296
+ * a group built after the change gets a bind group the layout does not match.
11297
+ *
11298
+ * @param change - The change.
11299
+ *
11300
+ * @internal
11301
+ */
11302
+ afterRebuild(change) {
11303
+ if (this.isRebuildInFlight) {
11304
+ this.#afterRebuild.push(change);
11305
+ return;
11306
+ }
11307
+ change();
11308
+ }
11309
+ /**
11310
+ * Takes the changes {@link RendererImpl.afterRebuild} held back. The render sync system runs them
11311
+ * once its rebuild has finished. A disposed renderer hands back none: its scene is gone.
11312
+ *
11313
+ * @returns The changes, oldest first.
11314
+ *
11315
+ * @internal
11316
+ */
11317
+ takeHeldChanges() {
11318
+ const held = this.#afterRebuild.splice(0);
11319
+ return this.#isDisposed ? [] : held;
11320
+ }
11321
+ /**
11322
+ * Releases the open overlays, the picker and the warm-up probes. The core extension registers it
11323
+ * as a disposer.
10459
11324
  *
10460
11325
  * @internal
10461
11326
  */
10462
11327
  dispose() {
11328
+ this.#isDisposed = true;
11329
+ this.#afterRebuild.length = 0;
11330
+ for (const overlay of this.#overlays.values()) overlay.dispose();
10463
11331
  const picker = this.#picker;
10464
11332
  this.#picker = null;
10465
11333
  if (picker !== null) disposeScenePicker(picker);
@@ -10541,6 +11409,14 @@ function rendererInternals(renderer) {
10541
11409
  function forceRendererDeviceLossForTesting(renderer) {
10542
11410
  rendererInternals(renderer).forceDeviceLossForTesting();
10543
11411
  }
11412
+ /**
11413
+ * The error an overlay request gets once the app is disposed.
11414
+ *
11415
+ * @returns `IGX-0106`.
11416
+ */
11417
+ function overlayAfterDisposeError() {
11418
+ return new IgnifxError(CoreErrorCode.appDisposed, "The app has been disposed; app.renderer.openOverlay() is no longer available.", { context: { member: "app.renderer.openOverlay()" } });
11419
+ }
10544
11420
  //#endregion
10545
11421
  //#region src/render/instanced-mesh-renderer.ts
10546
11422
  /**
@@ -10558,9 +11434,9 @@ function forceRendererDeviceLossForTesting(renderer) {
10558
11434
  * abort every other renderable's reconciliation. The LOD pairing's `distance` and `band` are not in
10559
11435
  * that set and are reconciled every frame.
10560
11436
  *
10561
- * `pickable` defaults to `false`, the opposite of `MeshRenderer`: Lite's picker reports
10562
- * `thinInstanceIndex` (`index.d.ts` 8720) but `RenderPick` does not carry it, so a hit would name
10563
- * the entity without saying which instance. Headless, the component keeps its slab, count, colours
11437
+ * `pickable` defaults to `false`, the opposite of `MeshRenderer`: a scatter of thousands of
11438
+ * instances is rarely what a click means. Set it to `true` and `RenderPick.thinInstanceIndex` says
11439
+ * which instance was hit. Headless, the component keeps its slab, count, colours
10564
11440
  * and flags and touches no scene (`docs/architecture/07-rendering.md` §6).
10565
11441
  */
10566
11442
  /** How many floats one instance matrix occupies. */
@@ -10998,7 +11874,7 @@ function instancedMeshRendererSchema() {
10998
11874
  castShadows: bool(true, { tooltip: "Whether the instances are rendered into shadow maps." }),
10999
11875
  receiveShadows: bool(true, { tooltip: "Whether shadow maps darken the instances." }),
11000
11876
  renderOrder: i32(0, { tooltip: "Sort key within the opaque or transparent phase; lower draws first." }),
11001
- pickable: bool(false, { tooltip: "Whether picking considers the instances; a hit names no instance index." }),
11877
+ pickable: bool(false, { tooltip: "Whether picking considers the instances; a hit names the instance it hit." }),
11002
11878
  lod: optional(record({
11003
11879
  mesh: asset(MeshAsset, { tooltip: "The coarse mesh drawn beyond the switch distance." }),
11004
11880
  distance: f32(40, {
@@ -11096,10 +11972,10 @@ function createHemisphericLightInWorld(intensity) {
11096
11972
  * from, in the one place every consumer reads them.
11097
11973
  *
11098
11974
  * @remarks
11099
- * The light's world matrix is its local matrix (there is no parent), so `worldMatrix[8..10]` — what
11100
- * the shader reads as the direction — is exactly what was written to `direction`,
11101
- * `worldMatrix[12..14]` — what a spot light reports as its position — is exactly `position`, and
11102
- * `computeDirectionalLightMatrix` fits the shadow frustum from the same two vectors.
11975
+ * The light has no parent and an identity rotation, so its world matrix is a pure translation:
11976
+ * the world direction Lite derives from `direction` is `direction` itself, and `worldMatrix[12..14]`
11977
+ * — where a point or spot light shines from, and where the shadow frustum is fitted from — is
11978
+ * exactly `position`.
11103
11979
  *
11104
11980
  * Each kind is written only what it uses, and each kind reads a different axis of the entity:
11105
11981
  *
@@ -11109,8 +11985,8 @@ function createHemisphericLightInWorld(intensity) {
11109
11985
  * | `point` | — | yes |
11110
11986
  * | `hemispheric` | the entity's world **up**: it is a sky direction, not a beam | — |
11111
11987
  *
11112
- * Both writes fire `ObservableVec3`'s dirty hook, so the lights uniform buffer re-uploads without a
11113
- * separate {@link markLightTransformDirty}.
11988
+ * Both writes bump the light's `_lightVersion`, so the lights uniform buffer re-uploads and a
11989
+ * shadow refits without a separate {@link markLightTransformDirty}.
11114
11990
  *
11115
11991
  * @param light - The light to pose.
11116
11992
  * @param forwardX - The entity's world-space forward x.
@@ -11251,7 +12127,7 @@ function setSpotExponent(light, exponent) {
11251
12127
  *
11252
12128
  * @remarks
11253
12129
  * Lite matches on `Mesh.id`, a string a loader or the adapter assigns; the include list wins over
11254
- * the exclude list when both are present (`lib/render/lights-ubo.js`, `affectsMesh`).
12130
+ * the exclude list when both are present (`lib/render/mesh-light-selection.js`, `affectsMesh`).
11255
12131
  *
11256
12132
  * @param light - The light to restrict.
11257
12133
  * @param meshIds - The mesh ids that may be lit, or `null` to light everything.
@@ -11324,227 +12200,6 @@ function markLightDirty(light) {
11324
12200
  }
11325
12201
  }
11326
12202
  //#endregion
11327
- //#region src/lite/shadow.ts
11328
- /**
11329
- * The shadow techniques Lite offers, in the order `docs/architecture/07-rendering.md` §2.2 lists them.
11330
- *
11331
- * @public
11332
- */
11333
- const SHADOW_TECHNIQUES = [
11334
- "esm",
11335
- "pcf",
11336
- "csm"
11337
- ];
11338
- /**
11339
- * Refuses to build a shadow generator for a light kind Lite cannot shadow.
11340
- *
11341
- * @remarks
11342
- * Lite has no point-light (cube) shadow generator and no area lights
11343
- * (`docs/architecture/07-rendering.md` §8). Hemispheric lights have no position or frustum at all.
11344
- *
11345
- * @param lightType - The Lite `lightType` discriminant of the light.
11346
- * @throws IgnifxError with code `IGX-0703` for any light kind other than `directional` or `spot`.
11347
- *
11348
- * @example
11349
- * ```ts
11350
- * assertShadowsSupported(light.lightType); // throws IGX-0703 for "point"
11351
- * ```
11352
- *
11353
- * @internal
11354
- */
11355
- function assertShadowsSupported(lightType) {
11356
- if (lightType === "directional" || lightType === "spot") return;
11357
- throw new IgnifxError(CoreErrorCode.shadowsUnsupportedForLight, `Babylon Lite has no shadow generator for a ${lightType} light.`, {
11358
- context: { lightType },
11359
- hint: "Cast shadows from a directional or spot light instead."
11360
- });
11361
- }
11362
- /**
11363
- * Turns shadows on for a light by attaching its generator.
11364
- *
11365
- * @param light - The light that should cast shadows.
11366
- * @param generator - A generator built for that light by `./gpu/shadow-generator.ts`.
11367
- *
11368
- * @internal
11369
- */
11370
- function attachShadowGenerator(light, generator) {
11371
- light.shadowGenerator = generator;
11372
- }
11373
- /**
11374
- * Turns shadows off for a light.
11375
- *
11376
- * @remarks
11377
- * This only breaks the link. The generator's GPU resources are released when the scene disposes it
11378
- * through {@link disposeShadowGenerator}.
11379
- *
11380
- * @param light - The light that should stop casting shadows.
11381
- *
11382
- * @internal
11383
- */
11384
- function detachShadowGenerator(light) {
11385
- delete light.shadowGenerator;
11386
- }
11387
- /**
11388
- * Replaces the list of meshes a generator renders into its shadow map.
11389
- *
11390
- * @remarks
11391
- * Lite keys the list by array identity and re-preloads the shadow pipeline every time a **new**
11392
- * array arrives, skipping the generator until that finishes. Callers therefore build the list once
11393
- * per change, never per frame.
11394
- *
11395
- * @param generator - The shadow generator.
11396
- * @param casters - The meshes that cast into it.
11397
- *
11398
- * @internal
11399
- */
11400
- function setShadowCasters(generator, casters) {
11401
- setShadowTaskCasterMeshes(generator, casters);
11402
- }
11403
- /**
11404
- * Rebuilds every material group of a registered scene so renderables pick up the current light and
11405
- * shadow topology.
11406
- *
11407
- * @remarks
11408
- * Renderables bake the per-mesh light index list, the single- versus multi-light shader
11409
- * permutation, and each generator's shadow bind group at build time; none of that follows a light
11410
- * being added, removed, or given a generator (`index.d.ts` 9465). The call is a no-op before the
11411
- * scene's first build, and it is expensive, so the component layer coalesces every topology change
11412
- * in a frame into one call.
11413
- *
11414
- * @param scene - The scene to rebuild.
11415
- * @returns A promise that resolves when the rebuild has finished.
11416
- *
11417
- * @internal
11418
- */
11419
- function rebuildRenderables(scene) {
11420
- return rebuildSceneRenderables(scene);
11421
- }
11422
- /**
11423
- * How many times the scene's materials have been rebuilt.
11424
- *
11425
- * @remarks
11426
- * An ESM generator keeps the caster views it built for a caster array until it is handed a
11427
- * different array, whatever happens to the materials (`ensureEsmShadowTaskState`,
11428
- * `lib/shadow/esm-directional-shadow-generator.js` 121-126; PCF and CSM compare each material's
11429
- * `_csmGen` instead). So a surface shader switched on or off went on drawing the old shape into an
11430
- * ESM map. The render sync system re-supplies the caster lists whenever this moves.
11431
- *
11432
- * @param scene - The scene.
11433
- * @returns The counter; `0` before anything was built.
11434
- *
11435
- * @internal
11436
- */
11437
- function readMaterialEpoch(scene) {
11438
- return scene._materialEpoch ?? 0;
11439
- }
11440
- /**
11441
- * Makes the next renderable rebuild create fresh bind-group layouts for every material.
11442
- *
11443
- * @remarks
11444
- * Call it before {@link rebuildRenderables} whenever a light gained or lost a shadow generator,
11445
- * and when the scene gained its first skinned or morphed PBR mesh (`./pbr-deformers.ts`).
11446
- * Lite caches a material's bindings, shadow bind-group layout included, under a key that does not
11447
- * name the shadow maps (`getOrCreatePbrBindings`, `lib/material/pbr/pbr-pipeline.js` 36). So after
11448
- * the number of shadow-casting lights changes, a rebuild reuses a layout sized for the old number
11449
- * and builds a bind group for the new one, and WebGPU rejects every frame ("Number of entries (3)
11450
- * did not match the expected number of entries (6)"). Clearing the cache costs one pipeline
11451
- * rebuild per material, only on a frame whose shadow casters changed.
11452
- *
11453
- * @param engine - The engine whose caches to clear.
11454
- *
11455
- * @internal
11456
- */
11457
- function forgetMaterialBindingLayouts(engine) {
11458
- const resets = engine;
11459
- resets._pbrCleanup?.();
11460
- resets._standardCleanup?.();
11461
- }
11462
- /**
11463
- * Releases a shadow generator's GPU resources and unlinks it from its light.
11464
- *
11465
- * @remarks
11466
- * `removeFromScene` recognises a shadow generator by its private `_shadowType`/`_light` fields
11467
- * (`lib/scene/scene-remove.js`), clears `light.shadowGenerator`, marks the scene's light topology
11468
- * dirty, and queues the generator's task for disposal after the GPU has drained.
11469
- *
11470
- * @param scene - The scene the generator was rendering into.
11471
- * @param generator - The generator to release.
11472
- *
11473
- * @internal
11474
- */
11475
- function disposeShadowGenerator(scene, generator) {
11476
- removeFromScene(scene, generator);
11477
- }
11478
- /**
11479
- * Maps the shared settings onto an exponential shadow map's configuration.
11480
- *
11481
- * @param settings - The declared settings.
11482
- * @returns Lite's configuration, with every field the caller left out omitted.
11483
- *
11484
- * @internal
11485
- */
11486
- function toEsmConfig(settings) {
11487
- const config = {};
11488
- if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
11489
- if (settings.bias !== void 0) config.bias = settings.bias;
11490
- if (settings.darkness !== void 0) config.darkness = settings.darkness;
11491
- return config;
11492
- }
11493
- /**
11494
- * Maps the shared settings onto a percentage-closer-filtered directional shadow map's configuration.
11495
- *
11496
- * @param settings - The declared settings.
11497
- * @returns Lite's configuration.
11498
- *
11499
- * @internal
11500
- */
11501
- function toPcfConfig(settings) {
11502
- const config = {};
11503
- if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
11504
- if (settings.bias !== void 0) config.bias = settings.bias;
11505
- if (settings.normalBias !== void 0) config.normalBias = settings.normalBias;
11506
- if (settings.darkness !== void 0) config.darkness = settings.darkness;
11507
- return config;
11508
- }
11509
- /**
11510
- * Maps the shared settings onto a cascaded shadow map's configuration.
11511
- *
11512
- * @remarks
11513
- * `cascades` becomes `numCascades` and `maxDistance` becomes `shadowMaxZ`; Lite clamps the cascade
11514
- * count to four (`index.d.ts` 3515).
11515
- *
11516
- * @param settings - The declared settings.
11517
- * @returns Lite's configuration.
11518
- *
11519
- * @internal
11520
- */
11521
- function toCsmConfig(settings) {
11522
- const config = {};
11523
- if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
11524
- if (settings.bias !== void 0) config.bias = settings.bias;
11525
- if (settings.darkness !== void 0) config.darkness = settings.darkness;
11526
- if (settings.cascades !== void 0) config.numCascades = settings.cascades;
11527
- if (settings.maxDistance !== void 0) config.shadowMaxZ = settings.maxDistance;
11528
- return config;
11529
- }
11530
- /**
11531
- * Maps the shared settings onto a spot light's shadow configuration.
11532
- *
11533
- * @param settings - The declared settings.
11534
- * @returns Lite's configuration.
11535
- *
11536
- * @internal
11537
- */
11538
- function toSpotConfig(settings) {
11539
- const config = {};
11540
- if (settings.mapSize !== void 0) config.mapSize = settings.mapSize;
11541
- if (settings.bias !== void 0) config.bias = settings.bias;
11542
- if (settings.normalBias !== void 0) config.normalBias = settings.normalBias;
11543
- if (settings.darkness !== void 0) config.darkness = settings.darkness;
11544
- if (settings.maxDistance !== void 0) config.far = settings.maxDistance;
11545
- return config;
11546
- }
11547
- //#endregion
11548
12203
  //#region src/lite/shadow-caster-shapes.ts
11549
12204
  /**
11550
12205
  * Tracks the bone poses and shader uniforms of one shadow generator's casters.
@@ -12101,6 +12756,7 @@ var Light = class Light extends Component {
12101
12756
  this.#warnAboutShadows(renderer);
12102
12757
  return false;
12103
12758
  }
12759
+ if (renderer.isRebuildInFlight) return false;
12104
12760
  this.#appliedShadows = wanted;
12105
12761
  if (!wanted) {
12106
12762
  this.#releaseGenerator(renderer);
@@ -12159,12 +12815,21 @@ var Light = class Light extends Component {
12159
12815
  * @param renderer - The rendering service, for the scene.
12160
12816
  */
12161
12817
  #teardown(renderer) {
12162
- this.#releaseGenerator(renderer);
12818
+ const generator = this.#generator;
12163
12819
  const light = this.#light;
12820
+ this.#generator = null;
12164
12821
  this.#light = null;
12165
12822
  this.#appliedType = null;
12166
12823
  this.#appliedShadows = false;
12167
- if (light !== null) removeLightFromScene(renderer.scene, light);
12824
+ const remove = () => {
12825
+ if (generator !== null) {
12826
+ detachShadows(renderer.scene, light, generator);
12827
+ renderer.needsShadowLayoutReset = true;
12828
+ }
12829
+ if (light !== null) removeLightFromScene(renderer.scene, light);
12830
+ };
12831
+ if (generator === null) remove();
12832
+ else renderer.afterRebuild(remove);
12168
12833
  }
12169
12834
  };
12170
12835
  /**
@@ -13203,6 +13868,312 @@ function readDefines(file) {
13203
13868
  return defines;
13204
13869
  }
13205
13870
  //#endregion
13871
+ //#region src/render/mesh-file.ts
13872
+ /**
13873
+ * The `.mesh.json` file format (ADR-0029): one primitive and the options its `MeshAsset` factory
13874
+ * takes, so a scene file can name a primitive by address.
13875
+ *
13876
+ * ```json
13877
+ * { "format": "ignifx.mesh", "formatVersion": 1, "primitive": "box", "options": { "size": 1 } }
13878
+ * ```
13879
+ *
13880
+ * One table, {@link MESH_PRIMITIVE_OPTIONS}, drives the runtime check and the JSON Schema, so the
13881
+ * two cannot drift apart.
13882
+ */
13883
+ /**
13884
+ * The `format` header a `.mesh.json` carries.
13885
+ *
13886
+ * @public
13887
+ */
13888
+ const MESH_FILE_FORMAT = "ignifx.mesh";
13889
+ /**
13890
+ * The only `.mesh.json` `formatVersion` this build reads.
13891
+ *
13892
+ * @public
13893
+ */
13894
+ const MESH_FORMAT_VERSION = 1;
13895
+ /**
13896
+ * The address suffix that selects the mesh loader.
13897
+ *
13898
+ * @public
13899
+ */
13900
+ const MESH_FILE_EXTENSION = ".mesh.json";
13901
+ /**
13902
+ * Every option each primitive takes, and what it holds. The keys are exactly the fields of the
13903
+ * factory's options type (`BoxMeshOptions`, …); the compiler checks that.
13904
+ *
13905
+ * @public
13906
+ */
13907
+ const MESH_PRIMITIVE_OPTIONS = {
13908
+ box: {
13909
+ size: "length",
13910
+ width: "length",
13911
+ height: "length",
13912
+ depth: "length"
13913
+ },
13914
+ sphere: {
13915
+ diameter: "length",
13916
+ segments: "count"
13917
+ },
13918
+ plane: {
13919
+ size: "length",
13920
+ width: "length",
13921
+ height: "length"
13922
+ },
13923
+ ground: {
13924
+ width: "length",
13925
+ height: "length",
13926
+ subdivisions: "count",
13927
+ uvScale: "pair"
13928
+ },
13929
+ cylinder: {
13930
+ height: "length",
13931
+ diameter: "length",
13932
+ diameterTop: "length",
13933
+ diameterBottom: "length",
13934
+ tessellation: "count"
13935
+ },
13936
+ capsule: {
13937
+ height: "length",
13938
+ radius: "length",
13939
+ tessellation: "count"
13940
+ },
13941
+ torus: {
13942
+ diameter: "length",
13943
+ thickness: "length",
13944
+ tessellation: "count"
13945
+ }
13946
+ };
13947
+ /** The top-level fields a mesh file may carry. */
13948
+ const MESH_FILE_FIELDS = Object.freeze({
13949
+ format: true,
13950
+ formatVersion: true,
13951
+ name: true,
13952
+ primitive: true,
13953
+ options: true
13954
+ });
13955
+ /**
13956
+ * Reads and checks a parsed `.mesh.json`.
13957
+ *
13958
+ * @param parsed - The parsed JSON.
13959
+ * @param address - The file's address, for error messages.
13960
+ * @returns The file.
13961
+ * @throws IgnifxError with code `IGX-0709` when the file has no `ignifx.mesh` header, `IGX-0603`
13962
+ * when its format version is not 1, or `IGX-0507` when it names an unknown primitive, an option the
13963
+ * primitive does not take, or a value the option cannot hold.
13964
+ *
13965
+ * @internal
13966
+ */
13967
+ function readMeshFile(parsed, address) {
13968
+ const file = asObject(parsed);
13969
+ if (file === null || file["format"] !== "ignifx.mesh") throw new IgnifxError(CoreErrorCode.invalidAssetFile, `${address} is not an ${MESH_FILE_FORMAT} file.`, {
13970
+ context: {
13971
+ file: address,
13972
+ format: MESH_FILE_FORMAT
13973
+ },
13974
+ hint: `A mesh file starts with { "format": "${MESH_FILE_FORMAT}", "formatVersion": ${String(1)} }.`
13975
+ });
13976
+ const version = file["formatVersion"];
13977
+ if (version !== 1) throw new IgnifxError(CoreErrorCode.unsupportedFormatVersion, `${address} declares format version ${JSON.stringify(version ?? null)}, which this build cannot read.`, {
13978
+ context: {
13979
+ file: address,
13980
+ version: JSON.stringify(version ?? null)
13981
+ },
13982
+ hint: `This build reads ${MESH_FILE_FORMAT} version ${String(1)}.`
13983
+ });
13984
+ for (const key of Object.keys(file)) if (!Object.hasOwn(MESH_FILE_FIELDS, key)) throw invalidMesh(address, `"${key}" is not a mesh file field`);
13985
+ const name = file["name"];
13986
+ if (name !== void 0 && typeof name !== "string") throw invalidMesh(address, "\"name\" must be a string");
13987
+ const primitive = readPrimitive(file["primitive"], address);
13988
+ const definition = {
13989
+ primitive,
13990
+ options: readOptions(file["options"], primitive, address)
13991
+ };
13992
+ return {
13993
+ name: name ?? null,
13994
+ definition
13995
+ };
13996
+ }
13997
+ /**
13998
+ * The JSON Schema `@ignifx/vite-plugin` validates `.mesh.json` files against, built from
13999
+ * {@link MESH_PRIMITIVE_OPTIONS}.
14000
+ *
14001
+ * @returns The schema document.
14002
+ *
14003
+ * @example
14004
+ * ```ts
14005
+ * // vite.config.ts
14006
+ * ignifx({ schemas: { formats: { [MESH_FILE_FORMAT]: meshFileJsonSchema() } } });
14007
+ * ```
14008
+ *
14009
+ * @public
14010
+ */
14011
+ function meshFileJsonSchema() {
14012
+ const branches = [];
14013
+ for (const primitive of MESH_PRIMITIVES) {
14014
+ const properties = {};
14015
+ for (const [option, kind] of Object.entries(MESH_PRIMITIVE_OPTIONS[primitive])) properties[option] = { $ref: `#/$defs/${kind}` };
14016
+ branches.push({ properties: {
14017
+ primitive: { const: primitive },
14018
+ options: {
14019
+ type: "object",
14020
+ additionalProperties: false,
14021
+ properties
14022
+ }
14023
+ } });
14024
+ }
14025
+ return {
14026
+ $schema: "https://json-schema.org/draft/2020-12/schema",
14027
+ $id: `https://ignifx.com/schemas/${MESH_FILE_FORMAT}.v${String(1)}.json`,
14028
+ title: "ignifx mesh file",
14029
+ type: "object",
14030
+ required: [
14031
+ "format",
14032
+ "formatVersion",
14033
+ "primitive"
14034
+ ],
14035
+ additionalProperties: false,
14036
+ properties: {
14037
+ format: { const: MESH_FILE_FORMAT },
14038
+ formatVersion: { const: 1 },
14039
+ name: { type: "string" },
14040
+ primitive: { enum: [...MESH_PRIMITIVES] },
14041
+ options: { type: "object" }
14042
+ },
14043
+ oneOf: branches,
14044
+ $defs: {
14045
+ length: {
14046
+ type: "number",
14047
+ minimum: 0
14048
+ },
14049
+ count: {
14050
+ type: "integer",
14051
+ minimum: 1
14052
+ },
14053
+ pair: {
14054
+ type: "array",
14055
+ items: { type: "number" },
14056
+ minItems: 2,
14057
+ maxItems: 2
14058
+ }
14059
+ }
14060
+ };
14061
+ }
14062
+ /**
14063
+ * Narrows a JSON value to an object.
14064
+ *
14065
+ * @param value - The value.
14066
+ * @returns The object, or `null` when it is not one.
14067
+ */
14068
+ function asObject(value) {
14069
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
14070
+ return value;
14071
+ }
14072
+ /**
14073
+ * Reads the `primitive` field.
14074
+ *
14075
+ * @param value - The field's value.
14076
+ * @param address - The file's address.
14077
+ * @returns The primitive.
14078
+ * @throws IgnifxError with code `IGX-0507` when it is not one of {@link MESH_PRIMITIVES}.
14079
+ */
14080
+ function readPrimitive(value, address) {
14081
+ for (const primitive of MESH_PRIMITIVES) if (value === primitive) return primitive;
14082
+ throw invalidMesh(address, `"primitive" is ${JSON.stringify(value ?? null)}; expected one of ${MESH_PRIMITIVES.join(", ")}`);
14083
+ }
14084
+ /**
14085
+ * Reads and checks the `options` field against one primitive's row of the table.
14086
+ *
14087
+ * @param value - The field's value; missing means every option takes its default.
14088
+ * @param primitive - The primitive the options are for.
14089
+ * @param address - The file's address.
14090
+ * @returns A copy of the options.
14091
+ * @throws IgnifxError with code `IGX-0507` when an option is unknown or holds the wrong value.
14092
+ */
14093
+ function readOptions(value, primitive, address) {
14094
+ if (value === void 0) return {};
14095
+ const options = asObject(value);
14096
+ if (options === null) throw invalidMesh(address, "\"options\" must be an object");
14097
+ const kinds = MESH_PRIMITIVE_OPTIONS[primitive];
14098
+ const result = {};
14099
+ for (const [option, optionValue] of Object.entries(options)) {
14100
+ const kind = Object.hasOwn(kinds, option) ? kinds[option] : void 0;
14101
+ if (kind === void 0) throw invalidMesh(address, `a ${primitive} has no option "${option}"; it takes ${Object.keys(kinds).join(", ")}`);
14102
+ if (!isOptionValue(optionValue, kind)) throw invalidMesh(address, `options.${option} must be ${OPTION_KIND_TEXT[kind]}; got ${JSON.stringify(optionValue)}`);
14103
+ result[option] = optionValue;
14104
+ }
14105
+ return result;
14106
+ }
14107
+ /** How an error message describes each option kind. */
14108
+ const OPTION_KIND_TEXT = {
14109
+ length: "a number of metres, zero or more",
14110
+ count: "a whole number, one or more",
14111
+ pair: "an array of two numbers"
14112
+ };
14113
+ /**
14114
+ * Checks one option value against its kind.
14115
+ *
14116
+ * @param value - The value.
14117
+ * @param kind - What the option holds.
14118
+ * @returns `true` when the value fits.
14119
+ */
14120
+ function isOptionValue(value, kind) {
14121
+ if (kind === "length") return typeof value === "number" && Number.isFinite(value) && value >= 0;
14122
+ if (kind === "count") return typeof value === "number" && Number.isInteger(value) && value >= 1;
14123
+ return Array.isArray(value) && value.length === 2 && value.every((item) => typeof item === "number" && Number.isFinite(item));
14124
+ }
14125
+ /**
14126
+ * Builds the `IGX-0507` failure.
14127
+ *
14128
+ * @param address - The file's address.
14129
+ * @param problem - What is wrong, without a trailing period.
14130
+ * @returns The error to throw.
14131
+ */
14132
+ function invalidMesh(address, problem) {
14133
+ return new IgnifxError(CoreErrorCode.invalidMeshFile, `${address} is not a valid mesh file: ${problem}.`, {
14134
+ context: {
14135
+ file: address,
14136
+ problem
14137
+ },
14138
+ hint: "See MESH_PRIMITIVE_OPTIONS for the options each primitive takes."
14139
+ });
14140
+ }
14141
+ //#endregion
14142
+ //#region src/render/loaders/mesh-loader.ts
14143
+ /**
14144
+ * Builds the `mesh` loader: `.mesh.json` to `MeshAsset` (ADR-0029).
14145
+ *
14146
+ * @remarks
14147
+ * The file names a primitive and its options, and the loader builds it exactly as the matching
14148
+ * `MeshAsset` factory would. The mesh is named after the file's `name`, or its address. A headless
14149
+ * app builds no GPU geometry. A file that is not a mesh file fails the load with `IGX-0709`, a
14150
+ * format version other than 1 with `IGX-0603`, and an unknown primitive or a bad option with
14151
+ * `IGX-0507`. The same `mesh` type still holds the in-memory meshes the factories publish; the
14152
+ * loader's `unload` frees both kinds.
14153
+ *
14154
+ * @returns The loader to register with `ctx.registerAssetLoader`.
14155
+ *
14156
+ * @example
14157
+ * ```ts
14158
+ * ctx.registerAssetLoader(createMeshLoader());
14159
+ * ```
14160
+ *
14161
+ * @public
14162
+ */
14163
+ function createMeshLoader() {
14164
+ return {
14165
+ type: MESH_ASSET_TYPE,
14166
+ extensions: [MESH_FILE_EXTENSION],
14167
+ async load(ctx) {
14168
+ const file = readMeshFile(await ctx.fetchJson(), ctx.address);
14169
+ return createPrimitiveMeshAsset(ctx.app, file.name ?? ctx.address, file.definition);
14170
+ },
14171
+ unload(value) {
14172
+ value.dispose();
14173
+ }
14174
+ };
14175
+ }
14176
+ //#endregion
13206
14177
  //#region src/lite/gpu/gltf.ts
13207
14178
  /** The suffix `cloneTransformNode` appends to every cloned node's name. */
13208
14179
  const CLONE_SUFFIX = "_clone";
@@ -13555,7 +14526,7 @@ let effectLayer = null;
13555
14526
  * @internal
13556
14527
  */
13557
14528
  async function loadPostEffectSupport() {
13558
- const [compiler, effects] = await Promise.all([compilerLayer ?? import("./post-effect-compiler-Rce26Eue.js"), effectLayer ?? import("./effect-task-CMbuO6Kb.js")]);
14529
+ const [compiler, effects] = await Promise.all([compilerLayer ?? import("./post-effect-compiler-pOvXae-i.js"), effectLayer ?? import("./effect-task-CMbuO6Kb.js")]);
13559
14530
  compilerLayer = compiler;
13560
14531
  effectLayer = effects;
13561
14532
  }
@@ -13693,7 +14664,7 @@ function createShaderLoader() {
13693
14664
  type: SHADER_ASSET_TYPE,
13694
14665
  extensions: SHADER_FILE_EXTENSIONS,
13695
14666
  async load(ctx) {
13696
- const [source, pragma] = await Promise.all([ctx.fetchText(), import("./shader-pragma-tw6AKaQD.js")]);
14667
+ const [source, pragma] = await Promise.all([ctx.fetchText(), import("./shader-pragma-qO9_6sTd.js")]);
13697
14668
  const declaration = pragma.parseShaderDeclaration(source, ctx.address);
13698
14669
  await loadShaderSupport();
13699
14670
  if (declaration.kind === "surface") await loadSurfaceShaderSupport();
@@ -16244,7 +17215,6 @@ var RenderSyncSystem = class {
16244
17215
  /** Each world's winning `Environment` last frame, so a change of winner is seen. */
16245
17216
  #lastEnvironment = /* @__PURE__ */ new WeakMap();
16246
17217
  #isRebuildDue = false;
16247
- #isRebuildInFlight = false;
16248
17218
  /** A rebuild asked for while one was already running; it is run once the in-flight one lands. */
16249
17219
  #isRebuildPending = false;
16250
17220
  #areCastersDirty = false;
@@ -16323,12 +17293,13 @@ var RenderSyncSystem = class {
16323
17293
  renderer.refreshClearColor();
16324
17294
  this.#applyStacks(world);
16325
17295
  this.#areCastersDirty = this.#areCastersDirty || castersChanged;
17296
+ if (renderer.materialCacheResets.unconfirmed && !this.#isRebuildDue && !renderer.isRebuildInFlight) this.#rebuildRenderables();
16326
17297
  if (this.#isRebuildDue && !topologyChanged) {
16327
17298
  this.#isRebuildDue = false;
16328
17299
  this.#rebuildRenderables();
16329
17300
  }
16330
17301
  this.#isRebuildDue = this.#isRebuildDue || topologyChanged;
16331
- if (this.#areCastersDirty && !this.#isRebuildDue && !this.#isRebuildInFlight) {
17302
+ if (this.#areCastersDirty && !this.#isRebuildDue && !renderer.isRebuildInFlight) {
16332
17303
  this.#areCastersDirty = false;
16333
17304
  this.#rebuildCasters(meshes, models, instanced, lights);
16334
17305
  }
@@ -16527,11 +17498,11 @@ var RenderSyncSystem = class {
16527
17498
  renderer.renderableRebuilds += 1;
16528
17499
  renderer.needsCasterRebuild = true;
16529
17500
  if (renderer.isHeadless || !renderer.isSceneRegistered) return;
16530
- if (this.#isRebuildInFlight) {
17501
+ if (renderer.isRebuildInFlight) {
16531
17502
  this.#isRebuildPending = true;
16532
17503
  return;
16533
17504
  }
16534
- this.#isRebuildInFlight = true;
17505
+ renderer.isRebuildInFlight = true;
16535
17506
  queueMicrotask(() => {
16536
17507
  this.#drainRebuilds();
16537
17508
  });
@@ -16575,9 +17546,9 @@ var RenderSyncSystem = class {
16575
17546
  const deformers = readPbrDeformers(renderer.scene);
16576
17547
  if (renderer.needsShadowLayoutReset || (deformers & ~renderer.builtPbrDeformers) !== 0) {
16577
17548
  renderer.needsShadowLayoutReset = false;
16578
- forgetMaterialBindingLayouts(renderer.engine);
17549
+ forgetMaterialBindingLayouts(renderer.materialCacheResets);
16579
17550
  }
16580
- await rebuildRenderables(renderer.scene);
17551
+ await rebuildRenderables(renderer.scene, renderer.materialCacheResets);
16581
17552
  renderer.builtPbrDeformers |= deformers;
16582
17553
  } catch (error) {
16583
17554
  renderer.app.onError.emit({
@@ -16590,8 +17561,25 @@ var RenderSyncSystem = class {
16590
17561
  }
16591
17562
  } while (this.#takePendingRebuild());
16592
17563
  } finally {
16593
- this.#isRebuildInFlight = false;
17564
+ renderer.isRebuildInFlight = false;
16594
17565
  this.#isRebuildPending = false;
17566
+ this.#runHeldChanges();
17567
+ }
17568
+ }
17569
+ /** Runs the scene changes `RendererImpl.afterRebuild` held back while the rebuild ran. */
17570
+ #runHeldChanges() {
17571
+ const renderer = this.#renderer;
17572
+ const held = renderer.takeHeldChanges();
17573
+ for (let index = 0; index < held.length; index += 1) try {
17574
+ held[index]?.();
17575
+ } catch (error) {
17576
+ renderer.app.onError.emit({
17577
+ error,
17578
+ source: "system",
17579
+ phase: null,
17580
+ entity: null,
17581
+ component: null
17582
+ });
16595
17583
  }
16596
17584
  }
16597
17585
  /**
@@ -16622,7 +17610,8 @@ var RenderSyncSystem = class {
16622
17610
  * The clock is accumulated here rather than read from `app.time.time` because a system keeps running
16623
17611
  * with a non-zero `dt` while the app is paused and has to check `time.paused` itself
16624
17612
  * (`docs/architecture/01-lifecycle-and-time.md` §7); that is what freezes `time` under
16625
- * `app.pause()` and resumes it without a jump.
17613
+ * `app.pause()` and resumes it without a jump. A held clock (`ctx.isClockHeld`, edit mode) freezes
17614
+ * it the same way.
16626
17615
  */
16627
17616
  /**
16628
17617
  * Where the shader uniform writer sits inside `PreRender`: just before the render sync
@@ -16676,7 +17665,7 @@ var ShaderUniformSystem = class {
16676
17665
  */
16677
17666
  update(ctx) {
16678
17667
  const time = ctx.time;
16679
- const isPaused = time.paused;
17668
+ const isPaused = time.paused || ctx.isClockHeld;
16680
17669
  if (!isPaused) {
16681
17670
  this.#time += time.deltaTime;
16682
17671
  this.#unscaledTime += time.unscaledDeltaTime;
@@ -17631,14 +18620,37 @@ function noReferences() {
17631
18620
  };
17632
18621
  }
17633
18622
  /**
17634
- * Builds the JSON Schema fragment for one field.
18623
+ * Builds the JSON Schema fragment for one field, at any depth: its encoded form plus an
18624
+ * `x-ignifx-*` keyword for each inspector option it declares. JSON Schema validators ignore
18625
+ * keywords they do not know, and the `x-` prefix keeps these clear of any future standard one.
17635
18626
  *
17636
18627
  * @param field - The field to describe.
17637
- * @returns The fragment describing the field's encoded form.
18628
+ * @returns The fragment.
17638
18629
  *
17639
18630
  * @internal
17640
18631
  */
17641
18632
  function fieldJsonSchema(field) {
18633
+ const fragment = { ...kindJsonSchema(field) };
18634
+ const { step, hidden, readonly, group, transient } = field.options;
18635
+ if (step !== void 0) fragment["x-ignifx-step"] = step;
18636
+ if (hidden !== void 0) fragment["x-ignifx-hidden"] = hidden;
18637
+ if (readonly !== void 0) {
18638
+ fragment["x-ignifx-readonly"] = readonly;
18639
+ if (readonly) fragment["readOnly"] = true;
18640
+ }
18641
+ if (group !== void 0) fragment["x-ignifx-group"] = group;
18642
+ if (transient !== void 0) fragment["x-ignifx-transient"] = transient;
18643
+ return fragment;
18644
+ }
18645
+ /**
18646
+ * Builds the JSON Schema fragment for one field's encoded form.
18647
+ *
18648
+ * @param field - The field to describe.
18649
+ * @returns The fragment describing the field's encoded form.
18650
+ *
18651
+ * @internal
18652
+ */
18653
+ function kindJsonSchema(field) {
17642
18654
  const { spec } = field;
17643
18655
  switch (spec.kind) {
17644
18656
  case "f32":
@@ -17679,16 +18691,25 @@ function fieldJsonSchema(field) {
17679
18691
  enum: [...spec.values]
17680
18692
  };
17681
18693
  case "entityRef": return taggedReferenceSchema("$entity");
17682
- case "componentRef": return taggedReferenceSchema("$component");
17683
- case "asset": return { oneOf: [{
17684
- type: "object",
17685
- properties: {
17686
- $asset: { type: "string" },
17687
- type: { type: "string" }
17688
- },
17689
- required: ["$asset"],
17690
- additionalProperties: false
17691
- }, { type: "null" }] };
18694
+ case "componentRef": {
18695
+ const typeId = spec.componentType.typeId;
18696
+ return {
18697
+ ...taggedReferenceSchema("$component"),
18698
+ ...typeId === void 0 ? {} : { "x-ignifx-component-type": typeId }
18699
+ };
18700
+ }
18701
+ case "asset": return {
18702
+ oneOf: [{
18703
+ type: "object",
18704
+ properties: {
18705
+ $asset: { type: "string" },
18706
+ type: { type: "string" }
18707
+ },
18708
+ required: ["$asset"],
18709
+ additionalProperties: false
18710
+ }, { type: "null" }],
18711
+ ...spec.typeName === null ? {} : { "x-ignifx-asset-type": spec.typeName }
18712
+ };
17692
18713
  case "array": return {
17693
18714
  type: "array",
17694
18715
  items: fieldJsonSchema(spec.item)
@@ -17772,14 +18793,18 @@ function schemaJsonSchema(schema) {
17772
18793
  };
17773
18794
  }
17774
18795
  /**
17775
- * Describes a component schema in the shape the documentation harness consumes. A package exports
17776
- * a record of these keyed by `typeId`; `pnpm docs:schemas` reads it from the built entry point and
17777
- * regenerates the format pages and `ignifx.schemas.json` from it
17778
- * (`scripts/README.md`, `docs/architecture/16-docs-harness-and-skill.md` §3).
18796
+ * Describes a component schema in the shape the documentation harness and an external inspector
18797
+ * consume. A package exports a record of these keyed by `typeId`; `pnpm docs:schemas` reads it from
18798
+ * the built entry point and regenerates the format pages and `ignifx.schemas.json` from it
18799
+ * (`scripts/README.md`, `docs/architecture/16-docs-harness-and-skill.md` §3). Each field carries
18800
+ * its inspector options and what its kind declares ({@link SchemaFieldDescription}); to describe
18801
+ * an app's registered components with `allowMultiple` and `package` filled in, use
18802
+ * {@link describeRegisteredSchemas}.
17779
18803
  *
17780
18804
  * @param typeId - The component's namespaced registration id, for example `mygame/Mover`.
17781
18805
  * @param schema - The component's declared fields.
17782
- * @param meta - Overrides for the title, format grouping, and summary.
18806
+ * @param meta - Overrides for the title, format grouping, and summary, and the component's
18807
+ * `allowMultiple`, `package` and `builtIn` when the caller knows them.
17783
18808
  * @returns The description entry.
17784
18809
  *
17785
18810
  * @example
@@ -17792,25 +18817,109 @@ function schemaJsonSchema(schema) {
17792
18817
  * @public
17793
18818
  */
17794
18819
  function describeSchema(typeId, schema, meta) {
17795
- const references = noReferences();
17796
- const fields = {};
17797
- for (const [name, field] of Object.entries(schema)) {
17798
- const { tooltip } = field.options;
17799
- fields[name] = {
17800
- kind: field.kind,
17801
- default: encodeValue(field, field.createDefault(), references),
17802
- ...tooltip === void 0 ? {} : { description: tooltip }
17803
- };
17804
- }
17805
18820
  const derivedTitle = typeId.slice(typeId.lastIndexOf("/") + 1);
17806
18821
  return {
17807
18822
  title: meta?.title ?? derivedTitle,
17808
18823
  format: meta?.format ?? "components",
17809
18824
  ...meta?.description === void 0 ? {} : { description: meta.description },
17810
- fields
18825
+ fields: describeFields(schema, noReferences()),
18826
+ ...meta?.allowMultiple === void 0 ? {} : { allowMultiple: meta.allowMultiple },
18827
+ ...meta?.package === void 0 ? {} : { package: meta.package },
18828
+ ...meta?.builtIn === void 0 ? {} : { builtIn: meta.builtIn }
18829
+ };
18830
+ }
18831
+ /**
18832
+ * Describes every field of a schema, in declaration order.
18833
+ *
18834
+ * @param schema - The fields.
18835
+ * @param references - The encoder for the defaults.
18836
+ * @returns The descriptions, keyed by field name.
18837
+ *
18838
+ * @internal
18839
+ */
18840
+ function describeFields(schema, references) {
18841
+ const fields = {};
18842
+ for (const [name, field] of Object.entries(schema)) fields[name] = describeField(field, references);
18843
+ return fields;
18844
+ }
18845
+ /**
18846
+ * Describes one field: its kind, default and tooltip, its inspector options, and what its kind
18847
+ * declares, recursing into nested fields.
18848
+ *
18849
+ * @param field - The field.
18850
+ * @param references - The encoder for the default.
18851
+ * @returns The description.
18852
+ *
18853
+ * @internal
18854
+ */
18855
+ function describeField(field, references) {
18856
+ const { tooltip } = field.options;
18857
+ return {
18858
+ kind: field.kind,
18859
+ default: encodeValue(field, field.createDefault(), references),
18860
+ ...tooltip === void 0 ? {} : { description: tooltip },
18861
+ ...describeOptions(field.options),
18862
+ ...describeKind(field, references)
18863
+ };
18864
+ }
18865
+ /**
18866
+ * Copies the inspector options a field declares.
18867
+ *
18868
+ * @param options - The field's options.
18869
+ * @returns Only the declared options.
18870
+ *
18871
+ * @internal
18872
+ */
18873
+ function describeOptions(options) {
18874
+ const { min, max, step, hidden, readonly, group, transient } = options;
18875
+ return {
18876
+ ...min === void 0 ? {} : { min },
18877
+ ...max === void 0 ? {} : { max },
18878
+ ...step === void 0 ? {} : { step },
18879
+ ...hidden === void 0 ? {} : { hidden },
18880
+ ...readonly === void 0 ? {} : { readonly },
18881
+ ...group === void 0 ? {} : { group },
18882
+ ...transient === void 0 ? {} : { transient }
17811
18883
  };
17812
18884
  }
17813
18885
  /**
18886
+ * Describes what a field's kind declares beyond the kind itself.
18887
+ *
18888
+ * @param field - The field.
18889
+ * @param references - The encoder for nested defaults.
18890
+ * @returns The kind's members; empty for a kind that declares nothing more.
18891
+ *
18892
+ * @internal
18893
+ */
18894
+ function describeKind(field, references) {
18895
+ const { spec } = field;
18896
+ switch (spec.kind) {
18897
+ case "enum": return { values: [...spec.values] };
18898
+ case "asset": return spec.typeName === null ? {} : { assetType: spec.typeName };
18899
+ case "componentRef": return { componentType: spec.componentType.typeId ?? null };
18900
+ case "array": return { item: describeField(spec.item, references) };
18901
+ case "record": return { fields: describeFields(spec.fields, references) };
18902
+ case "map": return { value: describeField(spec.value, references) };
18903
+ case "optional": return { inner: describeField(spec.inner, references) };
18904
+ case "f32":
18905
+ case "f64":
18906
+ case "i32":
18907
+ case "u32":
18908
+ case "bool":
18909
+ case "str":
18910
+ case "vec2":
18911
+ case "vec3":
18912
+ case "vec4":
18913
+ case "quat":
18914
+ case "color":
18915
+ case "entityRef":
18916
+ case "layerMask":
18917
+ case "curve":
18918
+ case "custom": return {};
18919
+ default: return assertNever(spec, "schema field kind");
18920
+ }
18921
+ }
18922
+ /**
17814
18923
  * Generates the JSON Schema (draft 2020-12) for a component's `props` object. The harness and the
17815
18924
  * Vite plugin assemble these into `ignifx.schemas.json`, which drives build-time validation and
17816
18925
  * editor autocompletion (`docs/architecture/06-serialization-and-scene-format.md` §8).
@@ -18674,15 +19783,14 @@ function readSceneFile(parsed, address, validate) {
18674
19783
  return asSceneFile(parsed);
18675
19784
  }
18676
19785
  /**
18677
- * Loads every asset the file references, in a stable order: `settings` first, then each entity's
19786
+ * Lists every asset the file references, in a stable order: `settings` first, then each entity's
18678
19787
  * `instance.scene`, then each component's `props`
18679
19788
  * (`docs/architecture/06-serialization-and-scene-format.md` §4 step 2).
18680
19789
  *
18681
19790
  * @param file - The parsed file.
18682
- * @param ctx - The loader context.
18683
- * @returns The loaded handles, deduplicated by address, in discovery order.
19791
+ * @returns The references, deduplicated by address, in discovery order.
18684
19792
  */
18685
- async function loadDependencies(file, ctx) {
19793
+ function dependencyRequests(file) {
18686
19794
  const requests = [];
18687
19795
  const seen = /* @__PURE__ */ new Set();
18688
19796
  const add = (address, type) => {
@@ -18699,7 +19807,59 @@ async function loadDependencies(file, ctx) {
18699
19807
  const entity = file.entities[index];
18700
19808
  if (entity !== void 0) collectEntityRefs(entity, add);
18701
19809
  }
18702
- return Promise.all(requests.map(async (request) => ctx.loadDependency(request.address, request.type === null ? void 0 : { type: request.type })));
19810
+ return requests;
19811
+ }
19812
+ /**
19813
+ * Loads every asset the file references through the loader context, which retains each one for
19814
+ * the scene asset being loaded.
19815
+ *
19816
+ * @param file - The parsed file.
19817
+ * @param ctx - The loader context.
19818
+ * @returns The loaded handles, deduplicated by address, in discovery order.
19819
+ */
19820
+ async function loadDependencies(file, ctx) {
19821
+ return Promise.all(dependencyRequests(file).map(async (request) => ctx.loadDependency(request.address, request.type === null ? void 0 : { type: request.type })));
19822
+ }
19823
+ /**
19824
+ * Loads every asset a scene file references — in `settings`, in every component's `props`, and in
19825
+ * every `instance.scene`, recursively through the scenes those pull in — the walk the scene loader
19826
+ * runs before it builds anything (`docs/architecture/06-serialization-and-scene-format.md` §4
19827
+ * step 2).
19828
+ *
19829
+ * @remarks
19830
+ * It is the half of the scene loader a file that is already in memory needs: pass the result to
19831
+ * `createSceneAsset` and the asset can be built synchronously with `instantiateScene`. Each handle
19832
+ * is returned with one holder, which the caller owns: release them all when the scene they serve
19833
+ * is gone. `world.loadSceneFile` does that for a whole scene.
19834
+ *
19835
+ * @param assets - The asset service to load through, normally `app.assets`.
19836
+ * @param file - The scene file.
19837
+ * @param options - Cancellation.
19838
+ * @returns The loaded handles, deduplicated by address, in the loader's order.
19839
+ * @throws Whatever the asset service rejects a load with (an `AssetLoadError`); every handle
19840
+ * loaded by then is released first.
19841
+ *
19842
+ * @example
19843
+ * ```ts
19844
+ * const dependencies = await loadSceneDependencies(app.assets, file);
19845
+ * const asset = await createSceneAsset("memory:scene/draft", file, dependencies);
19846
+ * ```
19847
+ *
19848
+ * @public
19849
+ */
19850
+ async function loadSceneDependencies(assets, file, options) {
19851
+ const signal = options?.signal;
19852
+ const handles = dependencyRequests(file).map((request) => assets.load(request.address, {
19853
+ ...request.type === null ? {} : { type: request.type },
19854
+ ...signal === void 0 ? {} : { signal }
19855
+ }));
19856
+ try {
19857
+ await Promise.all(handles.map(async (handle) => handle.promise));
19858
+ } catch (error) {
19859
+ for (let index = 0; index < handles.length; index += 1) handles[index]?.release();
19860
+ throw error;
19861
+ }
19862
+ return handles;
18703
19863
  }
18704
19864
  /**
18705
19865
  * Collects the asset references of one entity: its `instance.scene` first, so a nested scene is
@@ -21457,17 +22617,11 @@ function registerRendering(ctx) {
21457
22617
  if (value instanceof StorageBufferAsset) value.dispose();
21458
22618
  }
21459
22619
  });
21460
- ctx.registerAssetLoader({
21461
- type: MESH_ASSET_TYPE,
21462
- extensions: [],
21463
- load: () => Promise.reject(noMeshFileFormat()),
21464
- unload: (value) => {
21465
- if (value instanceof MeshAsset) value.dispose();
21466
- }
21467
- });
22620
+ ctx.registerAssetLoader(createMeshLoader());
21468
22621
  ctx.registerSystem(new ShaderUniformSystem(ctx.app), {
21469
22622
  phase: Phase.PreRender,
21470
- order: SHADER_UNIFORM_ORDER
22623
+ order: SHADER_UNIFORM_ORDER,
22624
+ editMode: "hold"
21471
22625
  });
21472
22626
  const sync = new RenderSyncSystem(renderer);
21473
22627
  renderer.attachSyncSystem(sync);
@@ -21480,18 +22634,6 @@ function registerRendering(ctx) {
21480
22634
  });
21481
22635
  }
21482
22636
  /**
21483
- * Builds the failure a `mesh` **address** produces: there is no mesh file format, because geometry
21484
- * arrives either as a primitive built in code or inside a `ModelAsset`.
21485
- *
21486
- * @returns The error to reject with.
21487
- */
21488
- function noMeshFileFormat() {
21489
- return new IgnifxError(CoreErrorCode.assetNoLoader, "There is no mesh file format; build one in code.", {
21490
- context: { type: MESH_ASSET_TYPE },
21491
- hint: "Use MeshAsset.box/sphere/plane/ground/... for primitives, or load a .glb as a model."
21492
- });
21493
- }
21494
- /**
21495
22637
  * Builds the failure a `storagebuffer` **address** produces: there is no storage buffer file
21496
22638
  * format, because the bytes are always written by the game.
21497
22639
  *
@@ -21686,7 +22828,7 @@ var ExtensionContextImpl = class {
21686
22828
  * @param options - An explicit `typeId`, when the class does not declare one.
21687
22829
  */
21688
22830
  registerComponent(type, options) {
21689
- this.#registry.register(type, options?.typeId);
22831
+ this.#registry.register(type, options?.typeId, this.#extension.name);
21690
22832
  }
21691
22833
  /**
21692
22834
  * Registers several component classes.
@@ -21694,7 +22836,7 @@ var ExtensionContextImpl = class {
21694
22836
  * @param types - The component classes.
21695
22837
  */
21696
22838
  registerComponents(types) {
21697
- this.#registry.registerAll(types);
22839
+ this.#registry.registerAll(types, this.#extension.name);
21698
22840
  }
21699
22841
  /**
21700
22842
  * Registers a system in a phase.
@@ -22696,6 +23838,17 @@ function readStatics(type) {
22696
23838
  return type;
22697
23839
  }
22698
23840
  /**
23841
+ * Whether a replacement class declares `static runInEditMode = true`.
23842
+ *
23843
+ * @param type - The component class.
23844
+ * @returns `true` only when the class declares it.
23845
+ *
23846
+ * @internal
23847
+ */
23848
+ function declaresRunInEditMode(type) {
23849
+ return readStatics(type).runInEditMode === true;
23850
+ }
23851
+ /**
22699
23852
  * The policy a class declares, defaulting to `"patch"`.
22700
23853
  *
22701
23854
  * @param type - The component class.
@@ -22904,6 +24057,8 @@ var HotReloadHostImpl = class {
22904
24057
  policy = "recreate";
22905
24058
  this.#log.warn(`${CoreErrorCode.hotReloadSchemaChanged} ${typeId} changed its schema shape under the "patch" policy; its instances were re-created. Declare static hotReload = "recreate" to say so.`);
22906
24059
  }
24060
+ const wasRunInEditMode = previousInfo.script?.runInEditMode ?? false;
24061
+ if (policy === "patch" && this.#app.isEditMode && wasRunInEditMode !== declaresRunInEditMode(next)) policy = "recreate";
22907
24062
  return {
22908
24063
  typeId,
22909
24064
  previous: current,
@@ -24403,6 +25558,9 @@ function updatesWhilePaused(script) {
24403
25558
  * not run" while paused, and a physics system that kept stepping with no `fixedUpdate` in front
24404
25559
  * of it would be worse than either reading alone. Systems of every other phase keep running:
24405
25560
  * rendering, audio, and UI must still work on a pause screen.
25561
+ * - **Edit mode costs a game one comparison per system.** An entry's edit-mode behaviour is
25562
+ * resolved at registration, so in an app that is not in edit mode every entry is `"run"` and the
25563
+ * frame takes the same path it always did (ADR-0028).
24406
25564
  * - **`FrameSample.destroyed` counts entities.** The destroy flush reports no total, and the only
24407
25565
  * world-level signal for a release is `onEntityDestroyed`; a component destroyed on a surviving
24408
25566
  * entity is therefore not counted yet.
@@ -24425,17 +25583,21 @@ var SystemEntry = class {
24425
25583
  order;
24426
25584
  /** Registration serial, the tie-breaker. */
24427
25585
  serial;
25586
+ /** What the system does this app's frames: always `"run"` outside edit mode. */
25587
+ editMode;
24428
25588
  /**
24429
25589
  * Creates an entry.
24430
25590
  *
24431
25591
  * @param system - The system.
24432
25592
  * @param order - Its order within the phase.
24433
25593
  * @param serial - Its registration serial.
25594
+ * @param editMode - What it does in this app's frames.
24434
25595
  */
24435
- constructor(system, order, serial) {
25596
+ constructor(system, order, serial, editMode) {
24436
25597
  this.system = system;
24437
25598
  this.order = order;
24438
25599
  this.serial = serial;
25600
+ this.editMode = editMode;
24439
25601
  }
24440
25602
  };
24441
25603
  /**
@@ -24452,6 +25614,8 @@ var SystemContextImpl = class {
24452
25614
  phase = Phase.EndOfFrame;
24453
25615
  /** Seconds elapsed. */
24454
25616
  dt = 0;
25617
+ /** Whether the running system's clock is held. */
25618
+ isClockHeld = false;
24455
25619
  /**
24456
25620
  * Creates the shared context.
24457
25621
  *
@@ -24476,6 +25640,7 @@ var Scheduler = class {
24476
25640
  #deferred;
24477
25641
  #clock;
24478
25642
  #development;
25643
+ #isEditMode;
24479
25644
  #report;
24480
25645
  /** One system list per phase, kept sorted by `(order, registration serial)`. */
24481
25646
  #systems = [];
@@ -24533,6 +25698,7 @@ var Scheduler = class {
24533
25698
  this.#deferred = options.deferred;
24534
25699
  this.#clock = options.clock;
24535
25700
  this.#development = options.development;
25701
+ this.#isEditMode = options.editMode;
24536
25702
  this.#report = (error, system, phase) => {
24537
25703
  options.report(error, system, phase);
24538
25704
  };
@@ -24561,14 +25727,16 @@ var Scheduler = class {
24561
25727
  * Registers a system in a phase (`docs/architecture/03-scripting-and-components.md` §6).
24562
25728
  *
24563
25729
  * @param system - The system.
24564
- * @param options - The phase and the ascending order within it; `order` defaults to `0`.
25730
+ * @param options - The phase, the ascending order within it (`order` defaults to `0`), and what
25731
+ * it does in edit mode (`editMode` defaults to `"run"`).
24565
25732
  */
24566
25733
  registerSystem(system, options) {
24567
25734
  const phase = options.phase;
24568
25735
  const list = this.#systems[phase];
24569
25736
  if (list === void 0) return;
24570
25737
  this.#serial += 1;
24571
- const entry = new SystemEntry(system, options.order ?? 0, this.#serial);
25738
+ const editMode = this.#isEditMode ? options.editMode ?? "run" : "run";
25739
+ const entry = new SystemEntry(system, options.order ?? 0, this.#serial, editMode);
24572
25740
  let index = list.length;
24573
25741
  while (index > 0) {
24574
25742
  const previous = list[index - 1];
@@ -24660,7 +25828,7 @@ var Scheduler = class {
24660
25828
  const start = this.#now();
24661
25829
  this.#phase = Phase.FixedUpdate;
24662
25830
  this.#internals?.setPhase(Phase.FixedUpdate);
24663
- if (!time.paused) {
25831
+ if (!time.paused && !this.#isEditMode) {
24664
25832
  this.#accumulator = snap(this.#accumulator + time.deltaTime, time.fixedDeltaTime);
24665
25833
  const step = time.fixedDeltaTime;
24666
25834
  this.#stepDt = step;
@@ -24729,18 +25897,35 @@ var Scheduler = class {
24729
25897
  this.#phase = phase;
24730
25898
  this.#internals?.setPhase(phase);
24731
25899
  for (let index = from; index < end; index += 1) {
24732
- const system = list[index]?.system;
24733
- if (system === void 0) continue;
24734
- try {
24735
- system.update?.(context);
24736
- } catch (error) {
24737
- this.#report(error, system, phase);
25900
+ const entry = list[index];
25901
+ if (entry === void 0) continue;
25902
+ if (entry.editMode === "run") this.#runSystem(entry.system, context, phase);
25903
+ else if (entry.editMode === "hold") {
25904
+ context.dt = 0;
25905
+ context.isClockHeld = true;
25906
+ this.#runSystem(entry.system, context, phase);
25907
+ context.dt = dt;
25908
+ context.isClockHeld = false;
24738
25909
  }
24739
25910
  }
24740
25911
  this.#internals?.setPhase(previousPhase);
24741
25912
  this.#phase = previousPhase;
24742
25913
  }
24743
25914
  /**
25915
+ * Runs one system, guarded.
25916
+ *
25917
+ * @param system - The system.
25918
+ * @param context - The shared context, already set for this phase.
25919
+ * @param phase - The phase, for the error report.
25920
+ */
25921
+ #runSystem(system, context, phase) {
25922
+ try {
25923
+ system.update?.(context);
25924
+ } catch (error) {
25925
+ this.#report(error, system, phase);
25926
+ }
25927
+ }
25928
+ /**
24744
25929
  * Walks one callback's sorted dispatch list.
24745
25930
  *
24746
25931
  * @param kind - Which callback.
@@ -25140,10 +26325,19 @@ var SettingsStore = class {
25140
26325
  this.#sections.set(name, {
25141
26326
  schema,
25142
26327
  owner,
26328
+ defaults: base,
25143
26329
  value: Object.freeze(value)
25144
26330
  });
25145
26331
  }
25146
26332
  /**
26333
+ * Every registered section, in registration order, for `describeSettings`.
26334
+ *
26335
+ * @returns The sections, keyed by name.
26336
+ */
26337
+ registrations() {
26338
+ return this.#sections;
26339
+ }
26340
+ /**
25147
26341
  * Reports whether a section has been registered.
25148
26342
  *
25149
26343
  * @param name - The section name.
@@ -27392,6 +28586,11 @@ var Entity = class {
27392
28586
  * The immovability hint: `true` promises that the transform will not change after `awake`, which
27393
28587
  * lets the 2D batcher, physics, and navmesh treat the entity as static.
27394
28588
  *
28589
+ * @remarks
28590
+ * It can be changed only in files or before `awake`; afterwards the setter throws `IGX-0101`. In an
28591
+ * edit-mode app it stays writable, because an editor's inspector edits it on loaded entities
28592
+ * (ADR-0028).
28593
+ *
27395
28594
  * @returns `true` when the entity is marked static.
27396
28595
  */
27397
28596
  get isStatic() {
@@ -27399,7 +28598,7 @@ var Entity = class {
27399
28598
  }
27400
28599
  set isStatic(value) {
27401
28600
  const internals = this.#mutable("isStatic");
27402
- if (internals.hasAwoken) throw new IgnifxError(CoreErrorCode.mutationAfterDestroy, "isStatic is set in files or before awake, and cannot change afterwards.", { context: {
28601
+ if (internals.hasAwoken && !internals.host.app.isEditMode) throw new IgnifxError(CoreErrorCode.mutationAfterDestroy, "isStatic is set in files or before awake, and cannot change afterwards.", { context: {
27403
28602
  entity: internals.uid,
27404
28603
  operation: "isStatic"
27405
28604
  } });
@@ -27576,6 +28775,36 @@ var Entity = class {
27576
28775
  internals.onParentChanged?.emit(parent);
27577
28776
  }
27578
28777
  /**
28778
+ * Moves the entity among its siblings: its parent's children, or its scene's roots when it has no
28779
+ * parent. Sibling order is the order a scene file lists entities in and the order `children`
28780
+ * reports.
28781
+ *
28782
+ * @param index - The entity's new index among its siblings. A value past either end is clamped
28783
+ * to that end, and a fraction is truncated.
28784
+ * @throws IgnifxError with code `IGX-0101` when the entity has been destroyed.
28785
+ *
28786
+ * @example
28787
+ * ```ts
28788
+ * weapon.setSiblingIndex(0); // first child of its parent
28789
+ * ```
28790
+ */
28791
+ setSiblingIndex(index) {
28792
+ const internals = this.#mutable("setSiblingIndex");
28793
+ const parent = internals.parent;
28794
+ const siblings = parent === null ? internals.scene.roots : entityInternals(parent).children;
28795
+ const at = Math.min(Math.max(Math.trunc(Number.isNaN(index) ? 0 : index), 0), siblings.length - 1);
28796
+ if (parent === null) {
28797
+ internals.scene.moveRoot(this, at);
28798
+ return;
28799
+ }
28800
+ const children = entityInternals(parent).children;
28801
+ const from = children.indexOf(this);
28802
+ if (from >= 0 && from !== at) {
28803
+ children.splice(from, 1);
28804
+ children.splice(at, 0, this);
28805
+ }
28806
+ }
28807
+ /**
27579
28808
  * Resolves a path relative to this entity — `"Body/Arm.L"`, `"../Sibling"`, `"/Root/Child"`.
27580
28809
  *
27581
28810
  * @remarks
@@ -28562,6 +29791,8 @@ function compare(item, order, serial) {
28562
29791
  * `awake` waits until the component is effectively enabled. Outside callbacks, enables are queued
28563
29792
  * and disables are immediate; nested changes run synchronously.
28564
29793
  * Destroy children before parents and release each entity's components in attachment order.
29794
+ * In edit mode the one call site is also the gate: a script whose class does not run in edit mode
29795
+ * gets no callback at all, from any path (ADR-0028).
28565
29796
  */
28566
29797
  /** How many callbacks get a sorted dispatch list. */
28567
29798
  const DISPATCH_LIST_COUNT = 15 - FIRST_DISPATCHED_CALLBACK;
@@ -28583,6 +29814,8 @@ var LifecycleQueue = class {
28583
29814
  #doomedComponents = [];
28584
29815
  /** The phase the scheduler says is running, recorded in error reports. */
28585
29816
  #phase = null;
29817
+ /** Whether the app is in edit mode, read once: it is fixed for the app's life. */
29818
+ #isEditMode;
28586
29819
  /**
28587
29820
  * Creates the queue.
28588
29821
  *
@@ -28590,6 +29823,7 @@ var LifecycleQueue = class {
28590
29823
  */
28591
29824
  constructor(host) {
28592
29825
  this.#host = host;
29826
+ this.#isEditMode = host.app.isEditMode;
28593
29827
  for (let index = 0; index < DISPATCH_LIST_COUNT; index += 1) this.#lists.push(new ScriptList());
28594
29828
  }
28595
29829
  /**
@@ -28728,6 +29962,7 @@ var LifecycleQueue = class {
28728
29962
  const state = componentInternals(component);
28729
29963
  const info = state.info;
28730
29964
  if (info === null || !implementsCallback(info.script, kind)) return;
29965
+ if (this.#isEditMode && info.script?.runInEditMode !== true) return;
28731
29966
  const name = SCRIPT_CALLBACK_NAMES[kind];
28732
29967
  if (name === void 0) return;
28733
29968
  const callback = readCallback(component, name);
@@ -28902,7 +30137,7 @@ var LifecycleQueue = class {
28902
30137
  * @param info - Its class's callback mask and ordering, or `null` when it has none.
28903
30138
  */
28904
30139
  #addToDispatch(script, info) {
28905
- if (info === null) return;
30140
+ if (info === null || this.#isEditMode && !info.runInEditMode) return;
28906
30141
  for (let kind = FIRST_DISPATCHED_CALLBACK; kind < 15; kind += 1) if ((info.callbacks & 1 << kind) !== 0) this.#lists[kind - FIRST_DISPATCHED_CALLBACK]?.insert(script, info);
28907
30142
  }
28908
30143
  /**
@@ -28912,7 +30147,7 @@ var LifecycleQueue = class {
28912
30147
  * @param info - Its class's callback mask, or `null` when it has none.
28913
30148
  */
28914
30149
  #removeFromDispatch(script, info) {
28915
- if (info === null) return;
30150
+ if (info === null || this.#isEditMode && !info.runInEditMode) return;
28916
30151
  for (let kind = FIRST_DISPATCHED_CALLBACK; kind < 15; kind += 1) if ((info.callbacks & 1 << kind) !== 0) this.#lists[kind - FIRST_DISPATCHED_CALLBACK]?.remove(script);
28917
30152
  }
28918
30153
  /**
@@ -29135,7 +30370,7 @@ let scratch = null;
29135
30370
  * @param world - The world being picked in, for the handle tables.
29136
30371
  * @param scene - The Lite render scene.
29137
30372
  * @param ray - The ray to cast.
29138
- * @param options - An entity filter.
30373
+ * @param options - An entity filter, and what to look through.
29139
30374
  * @returns What was hit, or `null` for a miss.
29140
30375
  *
29141
30376
  * @internal
@@ -29144,8 +30379,11 @@ function raycastRenderScene(world, scene, ray, options) {
29144
30379
  const renderer = rendererInternals(world.app.renderer);
29145
30380
  const pickRay = scratch ??= createPickRay();
29146
30381
  setPickRay(pickRay, ray.origin.x, ray.origin.y, ray.origin.z, ray.direction.x, ray.direction.y, ray.direction.z, ray.length);
29147
- const filter = options?.filter;
29148
- const info = filter === void 0 ? raycastScene(scene, pickRay) : raycastSceneWhere(scene, pickRay, (tag) => acceptsEntityTag(world, tag, filter));
30382
+ const plan = renderer.planPick(options);
30383
+ const accept = plan.accept;
30384
+ const hits = plan.hits;
30385
+ if (accept === null && hits.length === 0) return renderer.resolvePick(raycastScene(scene, pickRay));
30386
+ const info = raycastSceneWhere(scene, pickRay, (tag, mesh) => (accept === null || accept(tag, mesh)) && !hits.some((hit) => hit.mesh === mesh));
29149
30387
  return renderer.resolvePick(info);
29150
30388
  }
29151
30389
  //#endregion
@@ -29310,6 +30548,21 @@ var SceneInstance = class {
29310
30548
  if (!this.#roots.includes(entity)) this.#roots.push(entity);
29311
30549
  }
29312
30550
  /**
30551
+ * Moves a root to another place in the root list.
30552
+ *
30553
+ * @param entity - A root of this instance.
30554
+ * @param index - Its new index, already clamped to the list.
30555
+ *
30556
+ * @internal
30557
+ */
30558
+ moveRoot(entity, index) {
30559
+ const from = this.#roots.indexOf(entity);
30560
+ if (from >= 0) {
30561
+ this.#roots.splice(from, 1);
30562
+ this.#roots.splice(index, 0, entity);
30563
+ }
30564
+ }
30565
+ /**
29313
30566
  * Removes an entity from the root list.
29314
30567
  *
29315
30568
  * @param entity - The entity that gained a parent or was destroyed.
@@ -29750,9 +31003,11 @@ function invalidPath(path, reason) {
29750
31003
  function expandScene(asset, options) {
29751
31004
  const entities = [];
29752
31005
  const instances = [];
31006
+ const merged = /* @__PURE__ */ new Map();
29753
31007
  const state = {
29754
31008
  entities,
29755
31009
  instances,
31010
+ merged,
29756
31011
  options,
29757
31012
  counter: 0
29758
31013
  };
@@ -29763,18 +31018,21 @@ function expandScene(asset, options) {
29763
31018
  address: asset.address,
29764
31019
  asset: null,
29765
31020
  scene: asset,
29766
- rootUid: null
31021
+ rootUid: null,
31022
+ root: null
29767
31023
  });
29768
- expandFile(asset, null, key, true, [asset.address], state);
31024
+ expandFile(asset, null, key, true, [asset.address], state, null);
29769
31025
  return {
29770
31026
  entities,
29771
- instances
31027
+ instances,
31028
+ merged
29772
31029
  };
29773
31030
  }
29774
- expandFile(asset, null, null, false, [asset.address], state);
31031
+ expandFile(asset, null, null, false, [asset.address], state, null);
29775
31032
  return {
29776
31033
  entities,
29777
- instances
31034
+ instances,
31035
+ merged
29778
31036
  };
29779
31037
  }
29780
31038
  /**
@@ -29786,16 +31044,17 @@ function expandScene(asset, options) {
29786
31044
  * @param freshUids - `true` mints a new uid per entity and component; `false` keeps the file's own.
29787
31045
  * @param chain - The addresses of the scenes currently being expanded, for the cycle check.
29788
31046
  * @param state - The accumulating output.
31047
+ * @param merge - Where the file's single root merges, or `null` to create every entity.
29789
31048
  * @returns The override targets produced, keyed by the uid each entity carries in `asset`'s own
29790
31049
  * file.
29791
31050
  */
29792
- function expandFile(asset, parentUid, instanceKey, freshUids, chain, state) {
31051
+ function expandFile(asset, parentUid, instanceKey, freshUids, chain, state, merge) {
29793
31052
  const source = asset.file.entities;
29794
31053
  const keys = /* @__PURE__ */ new Map();
29795
31054
  if (freshUids) for (let index = 0; index < source.length; index += 1) {
29796
31055
  const entity = source[index];
29797
31056
  if (entity === void 0) continue;
29798
- keys.set(entity.uid, state.options.nextUid());
31057
+ keys.set(entity.uid, merge !== null && entity.parent === null ? merge.into.uid : state.options.nextUid());
29799
31058
  const components = entity.components ?? [];
29800
31059
  for (let inner = 0; inner < components.length; inner += 1) {
29801
31060
  const component = components[inner];
@@ -29806,6 +31065,11 @@ function expandFile(asset, parentUid, instanceKey, freshUids, chain, state) {
29806
31065
  for (let index = 0; index < source.length; index += 1) {
29807
31066
  const entity = source[index];
29808
31067
  if (entity === void 0) continue;
31068
+ if (merge !== null && entity.parent === null) {
31069
+ produced.set(entity.uid, mergeRoot(entity, merge, keys, state));
31070
+ if (entity.instance !== void 0) expandInstance(asset, entity.instance, merge.into, chain, state);
31071
+ continue;
31072
+ }
29809
31073
  const uid = keys.get(entity.uid) ?? entity.uid;
29810
31074
  const componentSourceUids = /* @__PURE__ */ new Map();
29811
31075
  const data = {
@@ -29834,20 +31098,52 @@ function expandFile(asset, parentUid, instanceKey, freshUids, chain, state) {
29834
31098
  componentSourceUids
29835
31099
  });
29836
31100
  const nested = entity.instance;
29837
- if (nested !== void 0) expandInstance(asset, nested, uid, chain, state);
31101
+ if (nested !== void 0) expandInstance(asset, nested, data, chain, state);
29838
31102
  }
29839
31103
  return produced;
29840
31104
  }
29841
31105
  /**
29842
- * Expands one `instance` entry under the entity that carries it.
31106
+ * Merges an instanced scene's single root into the entity carrying the `instance` entry: the
31107
+ * root's components come first, then the carrier's own. The carrier keeps its own uid, name,
31108
+ * transform, and other entity fields, as `world.instantiate` keeps the placement it is given.
31109
+ *
31110
+ * @param entity - The instanced root's record.
31111
+ * @param merge - The carrier and the component uid table to fill.
31112
+ * @param keys - Source uid to expanded uid for the instanced file.
31113
+ * @param state - The accumulating output.
31114
+ * @returns The override target for the root, which is the carrier.
31115
+ */
31116
+ function mergeRoot(entity, merge, keys, state) {
31117
+ const into = merge.into;
31118
+ const components = cloneComponents(entity, keys, merge.componentSourceUids);
31119
+ into.components = [...components, ...into.components];
31120
+ let merged = state.merged.get(into.uid);
31121
+ if (merged === void 0) {
31122
+ merged = /* @__PURE__ */ new Set();
31123
+ state.merged.set(into.uid, merged);
31124
+ }
31125
+ for (let index = 0; index < components.length; index += 1) {
31126
+ const component = components[index];
31127
+ if (component !== void 0) merged.add(component.uid);
31128
+ }
31129
+ return {
31130
+ data: into,
31131
+ components: reverse(merge.componentSourceUids)
31132
+ };
31133
+ }
31134
+ /**
31135
+ * Expands one `instance` entry on the entity that carries it. A scene with exactly one root merges
31136
+ * that root into the carrier, as `world.instantiate` answers with that root; any other scene's
31137
+ * roots become the carrier's children.
29843
31138
  *
29844
31139
  * @param asset - The scene the entry was declared in, whose dependencies resolve the reference.
29845
31140
  * @param instance - The entry.
29846
- * @param rootUid - The expanded uid of the entity carrying it.
31141
+ * @param carrier - The expanded record of the entity carrying it.
29847
31142
  * @param chain - The addresses currently being expanded.
29848
31143
  * @param state - The accumulating output.
29849
31144
  */
29850
- function expandInstance(asset, instance, rootUid, chain, state) {
31145
+ function expandInstance(asset, instance, carrier, chain, state) {
31146
+ const rootUid = carrier.uid;
29851
31147
  const address = instance.scene.$asset;
29852
31148
  if (chain.includes(address)) throw new IgnifxError(CoreErrorCode.sceneInstanceCycle, `Instantiating ${address} would nest the scene inside itself.`, {
29853
31149
  context: {
@@ -29865,14 +31161,28 @@ function expandInstance(asset, instance, rootUid, chain, state) {
29865
31161
  const recorded = instance.hash;
29866
31162
  if (recorded !== void 0 && recorded !== resolved.value.hash) reportHashMismatch(address, recorded, resolved.value.hash, state.options);
29867
31163
  const key = nextInstanceKey(state);
31164
+ const single = singleRoot(resolved.value);
31165
+ let merge = null;
31166
+ let root = null;
31167
+ if (single !== null) {
31168
+ merge = {
31169
+ into: carrier,
31170
+ componentSourceUids: /* @__PURE__ */ new Map()
31171
+ };
31172
+ root = {
31173
+ sourceUid: single.uid,
31174
+ componentSourceUids: merge.componentSourceUids
31175
+ };
31176
+ }
29868
31177
  state.instances.push({
29869
31178
  key,
29870
31179
  address,
29871
31180
  asset: resolved.handle,
29872
31181
  scene: resolved.value,
29873
- rootUid
31182
+ rootUid,
31183
+ root
29874
31184
  });
29875
- const produced = expandFile(resolved.value, rootUid, key, true, [...chain, address], state);
31185
+ const produced = expandFile(resolved.value, rootUid, key, true, [...chain, address], state, merge);
29876
31186
  const overrides = instance.overrides;
29877
31187
  if (overrides !== void 0 && overrides.length > 0) applyOverrides(overrides, produced, (message) => {
29878
31188
  state.options.report(CoreErrorCode.instanceHashMismatch, `${asset.address}: ${message}`);
@@ -29899,6 +31209,25 @@ function reportHashMismatch(address, recorded, actual, options) {
29899
31209
  options.report(CoreErrorCode.instanceHashMismatch, message);
29900
31210
  }
29901
31211
  /**
31212
+ * The record of a scene's only root.
31213
+ *
31214
+ * @param asset - The scene.
31215
+ * @returns The root's record, or `null` when the scene declares no root or several.
31216
+ *
31217
+ * @internal
31218
+ */
31219
+ function singleRoot(asset) {
31220
+ let found = null;
31221
+ const entities = asset.file.entities;
31222
+ for (let index = 0; index < entities.length; index += 1) {
31223
+ const entity = entities[index];
31224
+ if (entity === void 0 || entity.parent !== null) continue;
31225
+ if (found !== null) return null;
31226
+ found = entity;
31227
+ }
31228
+ return found;
31229
+ }
31230
+ /**
29902
31231
  * Mints the next instance key.
29903
31232
  *
29904
31233
  * @param state - The expansion state.
@@ -30191,6 +31520,7 @@ function instantiateScene(world, asset, options) {
30191
31520
  remap: new UidRemap(),
30192
31521
  report,
30193
31522
  instances: indexInstances(expanded.instances),
31523
+ merged: expanded.merged,
30194
31524
  roots: [],
30195
31525
  built: []
30196
31526
  };
@@ -30293,16 +31623,17 @@ function attachComponents(context) {
30293
31623
  * @param rootEntity - The entity that stands for the outermost instance, when the caller made one.
30294
31624
  */
30295
31625
  function linkInstances(context, handle, rootEntity) {
30296
- const rootOfInstance = /* @__PURE__ */ new Map();
31626
+ const firstMember = /* @__PURE__ */ new Map();
30297
31627
  for (let index = 0; index < context.built.length; index += 1) {
30298
31628
  const built = context.built[index];
30299
31629
  const key = built?.source.instanceKey ?? null;
30300
- if (built === void 0 || key === null || rootOfInstance.has(key)) continue;
30301
- const instance = context.instances.get(key);
30302
- if (instance === void 0) continue;
31630
+ if (built !== void 0 && key !== null && !firstMember.has(key)) firstMember.set(key, built.entity);
31631
+ }
31632
+ const rootOfInstance = /* @__PURE__ */ new Map();
31633
+ for (const instance of context.instances.values()) {
30303
31634
  const declared = instance.rootUid;
30304
- const resolved = declared === null ? rootEntity ?? built.entity : context.remap.entity(declared);
30305
- rootOfInstance.set(key, resolved ?? built.entity);
31635
+ const resolved = declared === null ? rootEntity ?? firstMember.get(instance.key) ?? null : context.remap.entity(declared);
31636
+ if (resolved !== null) rootOfInstance.set(instance.key, resolved);
30306
31637
  }
30307
31638
  const insideOf = /* @__PURE__ */ new Map();
30308
31639
  for (let index = 0; index < context.built.length; index += 1) {
@@ -30313,7 +31644,7 @@ function linkInstances(context, handle, rootEntity) {
30313
31644
  if (root !== void 0 && root !== built.entity) insideOf.set(built.entity, root);
30314
31645
  }
30315
31646
  if (rootEntity !== null) {
30316
- const own = ownedInstance(context, rootEntity, rootOfInstance, handle);
31647
+ const own = ownedInstance(context, rootEntity, null, rootOfInstance, handle);
30317
31648
  if (own !== null) entityInternals(rootEntity).origin = {
30318
31649
  sourceUid: "",
30319
31650
  instanceRoot: null,
@@ -30324,7 +31655,7 @@ function linkInstances(context, handle, rootEntity) {
30324
31655
  for (let index = 0; index < context.built.length; index += 1) {
30325
31656
  const built = context.built[index];
30326
31657
  if (built === void 0) continue;
30327
- const own = ownedInstance(context, built.entity, rootOfInstance, handle);
31658
+ const own = ownedInstance(context, built.entity, built.source, rootOfInstance, handle);
30328
31659
  const inside = insideOf.get(built.entity) ?? null;
30329
31660
  if (own === null && inside === null) continue;
30330
31661
  const origin = {
@@ -30341,11 +31672,12 @@ function linkInstances(context, handle, rootEntity) {
30341
31672
  *
30342
31673
  * @param context - The build state.
30343
31674
  * @param entity - The candidate root.
31675
+ * @param source - The expanded record that produced it, or `null` for a caller's container.
30344
31676
  * @param rootOfInstance - Instance key to its root entity.
30345
31677
  * @param handle - The handle the whole file was loaded through, for `asInstance` builds.
30346
31678
  * @returns The link, or `null` when the entity roots no instance.
30347
31679
  */
30348
- function ownedInstance(context, entity, rootOfInstance, handle) {
31680
+ function ownedInstance(context, entity, source, rootOfInstance, handle) {
30349
31681
  for (const [key, root] of rootOfInstance) {
30350
31682
  if (root !== entity) continue;
30351
31683
  const instance = context.instances.get(key);
@@ -30353,12 +31685,37 @@ function ownedInstance(context, entity, rootOfInstance, handle) {
30353
31685
  return {
30354
31686
  address: instance.address,
30355
31687
  asset: instance.rootUid === null ? handle : instance.asset,
30356
- scene: instance.scene
31688
+ scene: instance.scene,
31689
+ root: instancedRoot(context, instance, source)
30357
31690
  };
30358
31691
  }
30359
31692
  return null;
30360
31693
  }
30361
31694
  /**
31695
+ * What an instance root took from its scene's single root, when it stands for that root rather
31696
+ * than for a container (`docs/architecture/06-serialization-and-scene-format.md` §2).
31697
+ *
31698
+ * @param context - The build state.
31699
+ * @param instance - The instance the entity roots.
31700
+ * @param source - The expanded record that produced the entity, or `null` for a caller's container.
31701
+ * @returns The root's record uid and the components it brought, or `null` for a container.
31702
+ */
31703
+ function instancedRoot(context, instance, source) {
31704
+ if (source === null) return null;
31705
+ const merged = context.merged.get(source.data.uid) ?? /* @__PURE__ */ new Set();
31706
+ if (instance.root !== null) return {
31707
+ sourceUid: instance.root.sourceUid,
31708
+ componentSourceUids: instance.root.componentSourceUids,
31709
+ components: merged
31710
+ };
31711
+ if (instance.rootUid !== null || singleRoot(instance.scene)?.uid !== source.sourceUid) return null;
31712
+ return {
31713
+ sourceUid: source.sourceUid,
31714
+ componentSourceUids: source.componentSourceUids,
31715
+ components: /* @__PURE__ */ new Set([...source.componentSourceUids.keys(), ...merged])
31716
+ };
31717
+ }
31718
+ /**
30362
31719
  * Pass 4: decodes every component's props, resolving `entityRef`/`componentRef` through the now
30363
31720
  * complete uid table (`docs/architecture/06-serialization-and-scene-format.md` §4 step 5).
30364
31721
  *
@@ -30486,6 +31843,90 @@ function sceneAssetResolver(world, asset) {
30486
31843
  return cached !== null && cached.state === "loaded" ? cached : null;
30487
31844
  };
30488
31845
  }
31846
+ /** A decoder that resolves nothing, for a record built without one. */
31847
+ const NO_REFERENCES = Object.freeze({
31848
+ entity: () => null,
31849
+ component: () => null,
31850
+ asset: () => null
31851
+ });
31852
+ /**
31853
+ * Attaches one component to a live entity from its scene file record, the way the scene loader
31854
+ * builds it: the record's registered type, its uid, its `enabled` flag, and its `props` decoded
31855
+ * against the schema (`docs/architecture/06-serialization-and-scene-format.md` §4).
31856
+ *
31857
+ * @remarks
31858
+ * This is the per-component step of {@link instantiateScene} for a world that already exists, which
31859
+ * is what an editor mirroring a document into a live world needs. The component is attached with
31860
+ * `entity.addComponent`, so `awake` follows that method's rules. The record's uid is adopted as is;
31861
+ * keeping it unique within the scene is the caller's job. Decoding never throws: a value that does
31862
+ * not match its field takes the field's default and is reported in `issues`.
31863
+ *
31864
+ * @param entity - The entity to attach to.
31865
+ * @param record - The component record, as a scene file writes it.
31866
+ * @param options - Where it goes among the entity's components, and how references resolve.
31867
+ * @returns The component and the decoding problems.
31868
+ * @throws IgnifxError with code `IGX-0307` when the record's type is not registered, and whatever
31869
+ * `entity.addComponent` throws (`IGX-0202` for a second instance of a single-instance class,
31870
+ * `IGX-0101` for a destroyed entity).
31871
+ *
31872
+ * @example
31873
+ * ```ts
31874
+ * const { component } = addComponentFromRecord(player, { uid: "01J9Z6M7E5S3A0V2Q4R8T1Y6WY", type: "game/Health", props: { max: 120 } });
31875
+ * ```
31876
+ *
31877
+ * @public
31878
+ */
31879
+ function addComponentFromRecord(entity, record, options) {
31880
+ const registry = entity.world.registry;
31881
+ const type = registry.get(record.type);
31882
+ if (type === null) throw new IgnifxError(CoreErrorCode.unknownComponentTypeId, `The component type "${record.type}" is not registered; register it with app.registerComponents or check its typeId.`, { context: {
31883
+ typeId: record.type,
31884
+ entity: entity.uid
31885
+ } });
31886
+ const component = entity.addComponent(type);
31887
+ componentInternals(component).uid = record.uid;
31888
+ if (record.enabled === false) component.enabled = false;
31889
+ if (options?.index !== void 0) moveToFileIndex(entity, component, options.index);
31890
+ const issues = [];
31891
+ const schema = registry.describe(component.constructor).schema;
31892
+ if (schema !== null) applyProps({ report: (code, message) => {
31893
+ issues.push({
31894
+ code,
31895
+ message
31896
+ });
31897
+ } }, options?.references ?? NO_REFERENCES, component, schema, record.props ?? {}, record.uid);
31898
+ return {
31899
+ component,
31900
+ issues
31901
+ };
31902
+ }
31903
+ /**
31904
+ * Moves a component to an index of the entity's component list as a scene file counts it: the
31905
+ * transform, destroyed components, and the components an instanced scene merged in do not count.
31906
+ *
31907
+ * @param entity - The owner.
31908
+ * @param component - One of its components.
31909
+ * @param index - The index in file order; past the end means the end.
31910
+ */
31911
+ function moveToFileIndex(entity, component, index) {
31912
+ const internals = entityInternals(entity);
31913
+ const list = internals.components;
31914
+ const from = list.indexOf(component);
31915
+ if (from < 0) return;
31916
+ list.splice(from, 1);
31917
+ const merged = internals.origin?.instanced?.root?.components ?? null;
31918
+ let counted = 0;
31919
+ for (let at = 0; at < list.length; at += 1) {
31920
+ const other = list[at];
31921
+ if (other === void 0 || other === internals.transform || other.isDestroyed || merged?.has(other.uid) === true) continue;
31922
+ if (counted >= index) {
31923
+ list.splice(at, 0, component);
31924
+ return;
31925
+ }
31926
+ counted += 1;
31927
+ }
31928
+ list.push(component);
31929
+ }
30489
31930
  /**
30490
31931
  * Checks that every scene a file instances — at any depth — is among the loaded dependencies, which
30491
31932
  * is what makes `world.instantiate` safe to be synchronous
@@ -30859,7 +32300,7 @@ var World = class {
30859
32300
  * answer.
30860
32301
  *
30861
32302
  * @param ray - The ray to cast.
30862
- * @param options - An entity filter.
32303
+ * @param options - An entity filter, and what to look through.
30863
32304
  * @returns What was hit, or `null` for a miss.
30864
32305
  *
30865
32306
  * @example
@@ -31003,6 +32444,110 @@ var World = class {
31003
32444
  return instance;
31004
32445
  }
31005
32446
  /**
32447
+ * Builds a scene from a file that is already in memory, the way {@link World.loadScene} builds one
32448
+ * from an address (`docs/architecture/02-scene-graph.md` §2).
32449
+ *
32450
+ * @remarks
32451
+ * Nothing is fetched for the file itself: it is validated, every asset it references is loaded
32452
+ * through `app.assets` (the scene loader's own walk), and it is published there at
32453
+ * `options.address` as a scene asset, so the instance's `asset` and everything that reads it
32454
+ * behave as for a loaded file. Entity and component uids are the file's. The instance holds the
32455
+ * asset and its dependencies and releases them when it is unloaded. The rest is
32456
+ * {@link World.loadScene}'s: the same modes, the same synchronous build, `awake` before the
32457
+ * promise settles, and `onSceneLoaded`.
32458
+ *
32459
+ * This is how a tool builds a scene it holds as an object, such as an editor's open document with
32460
+ * unsaved edits.
32461
+ *
32462
+ * @param file - The scene file object, as `serializeScene` or `JSON.parse` produces it.
32463
+ * @param options - The address to publish it at, the mode, cancellation, and an issue collector.
32464
+ * @returns The instance, once every entity exists, every reference is resolved, and `awake` has
32465
+ * run.
32466
+ * @throws IgnifxError with code `IGX-0308` when the object is not a scene file, `IGX-0603` for a
32467
+ * format version this build cannot read, and `IGX-0608` when it does not match the scene format;
32468
+ * nothing is unloaded then. `IGX-0502` when `options.signal` aborts, `IGX-0307` when the file
32469
+ * names an unregistered component type (the half-built instance is unloaded first), and
32470
+ * whatever the asset system throws for a dependency.
32471
+ *
32472
+ * @example
32473
+ * ```ts
32474
+ * const level = await world.loadSceneFile(file, { address: "levels/level01.scene.json" });
32475
+ * ```
32476
+ */
32477
+ async loadSceneFile(file, options) {
32478
+ const { address, signal } = options;
32479
+ const checked = readSceneFile(file, address, true);
32480
+ const mode = options.mode ?? "single";
32481
+ if (mode === "single") await this.#unloadNonPersistent();
32482
+ const dependencies = await loadSceneDependencies(this.#assets(), checked, signal === void 0 ? void 0 : { signal });
32483
+ const release = () => {
32484
+ for (let index = 0; index < dependencies.length; index += 1) dependencies[index]?.release();
32485
+ };
32486
+ if (signal?.aborted === true) {
32487
+ release();
32488
+ throw new IgnifxError(CoreErrorCode.assetLoadAborted, `Loading ${address} was aborted.`, { context: { asset: address } });
32489
+ }
32490
+ const asset = await createSceneAsset(address, checked, dependencies);
32491
+ const handle = this.#assets().register(asset, {
32492
+ type: SCENE_ASSET_TYPE,
32493
+ address
32494
+ });
32495
+ const instance = new SceneInstance(this.#nextUid(), options.name ?? checked.name, false);
32496
+ instance.setAsset(handle);
32497
+ instance.onUnloading.connect(release, { once: true });
32498
+ instance.setLoaded(false);
32499
+ this.#scenes.push(instance);
32500
+ let built;
32501
+ try {
32502
+ built = instantiateScene(this, asset, {
32503
+ scene: instance,
32504
+ ...options.strictInstanceHashes === void 0 ? {} : { strictInstanceHashes: options.strictInstanceHashes }
32505
+ });
32506
+ } catch (error) {
32507
+ await this.unloadScene(instance);
32508
+ throw error;
32509
+ }
32510
+ instance.setRemap(built.remap);
32511
+ instance.setSettings(checked.settings ?? null);
32512
+ instance.setLoaded(true);
32513
+ this.#reportSceneIssues(address, built.issues);
32514
+ const onIssue = options.onIssue;
32515
+ if (onIssue !== void 0) for (let index = 0; index < built.issues.length; index += 1) {
32516
+ const issue = built.issues[index];
32517
+ if (issue !== void 0) onIssue(issue);
32518
+ }
32519
+ if (options.setActive ?? mode === "single") this.#activeScene = instance;
32520
+ this.#lifecycle.flushAwakeAndEnable();
32521
+ this.#onSceneLoaded.emit(instance);
32522
+ return instance;
32523
+ }
32524
+ /**
32525
+ * Creates an empty scene instance that is built in code rather than loaded from a file
32526
+ * (`docs/architecture/02-scene-graph.md` §3).
32527
+ *
32528
+ * @remarks
32529
+ * Entities join it through `createEntity(name, { scene })` or `moveEntityToScene`. A persistent
32530
+ * instance survives every `"single"` load, so it is where a tool keeps objects that must outlive
32531
+ * the levels it loads: an editor's cameras, grid and gizmo roots. Like any instance other than the
32532
+ * implicit `"default"` one, it can be unloaded with `unloadScene`. Creating it raises no
32533
+ * `onSceneLoaded`, because nothing was loaded; `serializeScene` writes it only when it is passed.
32534
+ *
32535
+ * @param name - The instance's name.
32536
+ * @param options - Whether it is persistent.
32537
+ * @returns The new, empty instance, appended to `scenes`.
32538
+ *
32539
+ * @example
32540
+ * ```ts
32541
+ * const tools = world.createScene("editor", { persistent: true });
32542
+ * const camera = world.createEntity("Editor Camera", { scene: tools });
32543
+ * ```
32544
+ */
32545
+ createScene(name, options) {
32546
+ const instance = new SceneInstance(this.#nextUid(), name, options?.persistent ?? false);
32547
+ this.#scenes.push(instance);
32548
+ return instance;
32549
+ }
32550
+ /**
31006
32551
  * Unloads a scene instance: `onUnloading` fires while its entities are still valid, its roots are
31007
32552
  * destroyed through the normal destroy path (children before parents, `onDisable` then
31008
32553
  * `onDestroy`), and the assets it held are released
@@ -31544,6 +33089,8 @@ var AppImpl = class {
31544
33089
  hotReload;
31545
33090
  /** `true` when the app runs on Lite's null engine with no render surface. */
31546
33091
  isHeadless;
33092
+ /** `true` when the app was created for an editor's scene view. */
33093
+ isEditMode;
31547
33094
  /** The `@ignifx/core` version this app was built from. */
31548
33095
  version = VERSION;
31549
33096
  /** Where the app is running. */
@@ -31597,6 +33144,7 @@ var AppImpl = class {
31597
33144
  this.#clock = options.clock;
31598
33145
  this.#mode = options.mode;
31599
33146
  this.isHeadless = options.canvas === null;
33147
+ this.isEditMode = options.editMode;
31600
33148
  this.platform = options.platform;
31601
33149
  this.storage = new StorageImpl(options.storage);
31602
33150
  const development = options.mode === "development";
@@ -31642,6 +33190,7 @@ var AppImpl = class {
31642
33190
  });
31643
33191
  this.coroutines = new CoroutineHostImpl({
31644
33192
  frameState: this.#frameState,
33193
+ editMode: options.editMode,
31645
33194
  report: (error, owner) => {
31646
33195
  this.#report({
31647
33196
  error,
@@ -31660,6 +33209,7 @@ var AppImpl = class {
31660
33209
  deferred: this.#deferred,
31661
33210
  clock: options.clock,
31662
33211
  development,
33212
+ editMode: options.editMode,
31663
33213
  report: (error, system, phase) => {
31664
33214
  this.log.error(`The system ${system.name} threw in ${PHASE_NAMES[phase] ?? "no phase"}.`, error);
31665
33215
  this.#report({
@@ -31937,7 +33487,10 @@ var AppImpl = class {
31937
33487
  const world = this.#world;
31938
33488
  if (world !== null) renderer.syncBeforeRegister(world);
31939
33489
  renderer.warmUpAtStart();
33490
+ trackMaterialCacheResets(handles.scene, renderer.materialCacheResets);
31940
33491
  await registerRenderScene(handles.scene, { shadows: features.shadows });
33492
+ await learnMaterialCacheResets(handles.scene, renderer.materialCacheResets);
33493
+ renderer.needsCasterRebuild = true;
31941
33494
  renderer.markSceneRegistered();
31942
33495
  }
31943
33496
  /** Stops the Lite loop, detaches the browser listeners, and runs `onStop` in reverse order. */
@@ -32103,7 +33656,8 @@ async function createApp(options = {}) {
32103
33656
  mode: options.mode ?? "development",
32104
33657
  logSink: options.logSink ?? createConsoleSink(),
32105
33658
  logLevel: options.logLevel ?? "info",
32106
- reloadScenes: options.hotReload?.reloadScenes ?? false
33659
+ reloadScenes: options.hotReload?.reloadScenes ?? false,
33660
+ editMode: options.editMode ?? false
32107
33661
  });
32108
33662
  await app.initialize(options.extensions ?? []);
32109
33663
  return app;
@@ -32589,6 +34143,64 @@ var Vec4 = class Vec4 {
32589
34143
  }
32590
34144
  };
32591
34145
  //#endregion
34146
+ //#region src/transform/transform-schema.ts
34147
+ /**
34148
+ * The entity transform as a schema: the fields of a scene file's `transform` block, so an
34149
+ * inspector and its ops can treat the transform like any component
34150
+ * (`docs/architecture/06-serialization-and-scene-format.md` §2).
34151
+ *
34152
+ * @remarks
34153
+ * The schema **describes** the transform; {@link (Transform:class)} does not declare it. The class keeps
34154
+ * no schema because its `position` and `rotation` are world-space getters, while the file, this
34155
+ * schema, and the editor's `setTransform` op all carry **local** values. Every entity has exactly
34156
+ * one transform, which is never in a file's `components` list, so `describeSchemas()` and
34157
+ * `describeRegisteredSchemas()` mark `ignifx/Transform` as `builtIn`: it cannot be added or
34158
+ * removed, and its values are edited as the whole block, not with a per-prop op.
34159
+ *
34160
+ * `rotation` is a `quat` field: files and ops store a unit quaternion, and an inspector shows
34161
+ * intrinsic XYZ Euler angles in degrees (ADR-0011), so its `step` is in degrees.
34162
+ *
34163
+ * @returns A new schema: `position` (`vec3`, origin, step 0.01), `rotation` (`quat`, identity,
34164
+ * step 0.5 degrees), `scale` (`vec3`, one, step 0.01).
34165
+ *
34166
+ * @example
34167
+ * ```ts
34168
+ * const fields = describeSchema("ignifx/Transform", transformSchema()).fields;
34169
+ * fields["rotation"]?.default; // [0, 0, 0, 1]
34170
+ * ```
34171
+ *
34172
+ * @public
34173
+ */
34174
+ function transformSchema() {
34175
+ return defineSchema({
34176
+ position: vec3({
34177
+ x: 0,
34178
+ y: 0,
34179
+ z: 0
34180
+ }, {
34181
+ tooltip: "Local position relative to the parent, in metres.",
34182
+ step: .01
34183
+ }),
34184
+ rotation: quat({
34185
+ x: 0,
34186
+ y: 0,
34187
+ z: 0,
34188
+ w: 1
34189
+ }, {
34190
+ tooltip: "Local rotation relative to the parent: a unit quaternion [x, y, z, w], shown as intrinsic XYZ Euler angles in degrees.",
34191
+ step: .5
34192
+ }),
34193
+ scale: vec3({
34194
+ x: 1,
34195
+ y: 1,
34196
+ z: 1
34197
+ }, {
34198
+ tooltip: "Local scale relative to the parent.",
34199
+ step: .01
34200
+ })
34201
+ });
34202
+ }
34203
+ //#endregion
32592
34204
  //#region src/render/schemas.ts
32593
34205
  /**
32594
34206
  * The documentation harness's view of everything `@ignifx/core` declares
@@ -32605,11 +34217,19 @@ var Vec4 = class Vec4 {
32605
34217
  *
32606
34218
  * The harness requires every key to be a namespaced `<package>/<Name>` type id
32607
34219
  * (`scripts/lib/schema-source.ts` rejects a key with no `/`), and it groups entries onto a page by
32608
- * their `format`. A *file* format is not a component and has no type id, so the three file formats
32609
- * below are keyed `ignifx/scene-file`, `ignifx/material-file`, and `ignifx/environment-file` while
32610
- * declaring `format: "ignifx.scene"`, `"ignifx.material"`, and `"ignifx.environment"`. The wave-1
34220
+ * their `format`. A *file* format is not a component and has no type id, so the file formats
34221
+ * below are keyed `ignifx/scene-file`, `ignifx/material-file`, `ignifx/environment-file`, and
34222
+ * `ignifx/mesh-file` while declaring `format: "ignifx.scene"`, `"ignifx.material"`,
34223
+ * `"ignifx.environment"`, and `"ignifx.mesh"`. The wave-1
32611
34224
  * hand-off asked for the key `"ignifx.scene"`; that key fails the namespacing check, and the
32612
34225
  * grouping — which is what actually decides the page — comes from `format` either way.
34226
+ *
34227
+ * ## The transform
34228
+ *
34229
+ * `ignifx/Transform` is described like a component, from `transformSchema()`, though its class
34230
+ * declares no schema: it is the scene file's per-entity `transform` block. Its entry is the only one
34231
+ * that sets `builtIn` (with `allowMultiple: false` and `package: "@ignifx/core"`), so an editor
34232
+ * shows it with the components but never offers to add or remove it.
32613
34233
  */
32614
34234
  /**
32615
34235
  * Describes every component and file format this package declares, for the documentation harness.
@@ -32626,6 +34246,12 @@ var Vec4 = class Vec4 {
32626
34246
  */
32627
34247
  function describeSchemas() {
32628
34248
  return {
34249
+ "ignifx/Transform": describeSchema("ignifx/Transform", transformSchema(), {
34250
+ description: "The entity's local position, rotation, and scale; every entity has exactly one, stored as its transform block.",
34251
+ allowMultiple: false,
34252
+ package: "@ignifx/core",
34253
+ builtIn: true
34254
+ }),
32629
34255
  "ignifx/Camera": describeSchema("ignifx/Camera", Camera.schema, { description: "The camera an entity renders the world through; the entity's transform is the view." }),
32630
34256
  "ignifx/Light": describeSchema("ignifx/Light", Light.schema, { description: "A directional, point, spot, or hemispheric light, with optional shadow casting." }),
32631
34257
  "ignifx/MeshRenderer": describeSchema("ignifx/MeshRenderer", MeshRenderer.schema, { description: "Draws one clone of a mesh asset with a material." }),
@@ -32635,7 +34261,8 @@ function describeSchemas() {
32635
34261
  "ignifx/PostProcessStack": describeSchema("ignifx/PostProcessStack", PostProcessStack.schema, { description: "Bloom, SMAA, image processing, and custom .post.wgsl effects, inserted into the scene's frame graph." }),
32636
34262
  "ignifx/scene-file": describeSceneFileFormat(),
32637
34263
  "ignifx/material-file": describeMaterialFileFormat(),
32638
- "ignifx/environment-file": describeEnvironmentFileFormat()
34264
+ "ignifx/environment-file": describeEnvironmentFileFormat(),
34265
+ "ignifx/mesh-file": describeMeshFileFormat()
32639
34266
  };
32640
34267
  }
32641
34268
  /**
@@ -32897,6 +34524,48 @@ function describeEnvironmentFileFormat() {
32897
34524
  }
32898
34525
  };
32899
34526
  }
34527
+ /**
34528
+ * Describes the `ignifx.mesh` file format (ADR-0029).
34529
+ *
34530
+ * @returns The description of the top-level file fields.
34531
+ *
34532
+ * @public
34533
+ */
34534
+ function describeMeshFileFormat() {
34535
+ const optionsByPrimitive = MESH_PRIMITIVES.map((primitive) => `${primitive}: ${Object.keys(MESH_PRIMITIVE_OPTIONS[primitive]).join(", ")}`).join("; ");
34536
+ return {
34537
+ title: "Mesh file",
34538
+ format: MESH_FILE_FORMAT,
34539
+ description: "One primitive mesh and the options its MeshAsset factory takes, so a scene file can name it by address. glTF meshes load as models instead.",
34540
+ fields: {
34541
+ format: {
34542
+ kind: "str",
34543
+ default: MESH_FILE_FORMAT,
34544
+ description: `Always "${MESH_FILE_FORMAT}".`
34545
+ },
34546
+ formatVersion: {
34547
+ kind: "u32",
34548
+ default: 1,
34549
+ description: "The file format version; 1 before ignifx 1.0."
34550
+ },
34551
+ name: {
34552
+ kind: "str",
34553
+ default: "",
34554
+ description: "A name for diagnostics; empty uses the file's address."
34555
+ },
34556
+ primitive: {
34557
+ kind: "enum",
34558
+ default: "box",
34559
+ description: `The shape: ${MESH_PRIMITIVES.join(", ")}. Required; an unknown value is rejected with IGX-0507.`
34560
+ },
34561
+ options: {
34562
+ kind: "record",
34563
+ default: {},
34564
+ description: `The factory's options; omitted ones take its defaults. Lengths are metres, zero or more; counts are whole numbers, one or more; uvScale is two numbers. An unknown option or a bad value is IGX-0507. By primitive: ${optionsByPrimitive}.`
34565
+ }
34566
+ }
34567
+ };
34568
+ }
32900
34569
  //#endregion
32901
34570
  //#region src/serialization/serialize.ts
32902
34571
  /**
@@ -33104,7 +34773,7 @@ function writeEntity(planned, references, report) {
33104
34773
  const layerName = entity.world.layers.nameOf(entity.layer);
33105
34774
  const origin = planned.origin;
33106
34775
  const instance = origin === null ? null : writeInstance(entity, origin, references, report);
33107
- const components = writeComponents(entity, references, report);
34776
+ const components = writeComponents(entity, references, report, origin?.instanced?.root?.components ?? null);
33108
34777
  return {
33109
34778
  uid: entity.uid,
33110
34779
  name: entity.name,
@@ -33124,14 +34793,15 @@ function writeEntity(planned, references, report) {
33124
34793
  * @param entity - The entity.
33125
34794
  * @param references - How references resolve.
33126
34795
  * @param report - Receives problems.
34796
+ * @param skip - The uids of components an instanced scene put on the entity, which are not written.
33127
34797
  * @returns The records, in attach order.
33128
34798
  */
33129
- function writeComponents(entity, references, report) {
34799
+ function writeComponents(entity, references, report, skip) {
33130
34800
  const records = [];
33131
34801
  const components = entity.components;
33132
34802
  for (let index = 0; index < components.length; index += 1) {
33133
34803
  const component = components[index];
33134
- if (component === void 0 || component === entity.transform || component.isDestroyed) continue;
34804
+ if (component === void 0 || component === entity.transform || component.isDestroyed || skip?.has(component.uid) === true) continue;
33135
34805
  if (component.world.registry.describe(component.constructor).typeId === null) {
33136
34806
  report(CoreErrorCode.componentTypeIdMissing, `${component.constructor.name} on ${entity.name} has no typeId and cannot be written.`);
33137
34807
  continue;
@@ -33185,7 +34855,7 @@ function writeTransform(transform) {
33185
34855
  function writeInstance(root, origin, references, report) {
33186
34856
  const link = origin.instanced;
33187
34857
  if (link === null) return null;
33188
- const overrides = computeOverrides(root, link.scene, references, report);
34858
+ const overrides = computeOverrides(root, link, references, report);
33189
34859
  return {
33190
34860
  scene: { $asset: link.address },
33191
34861
  hash: link.scene.hash,
@@ -33201,23 +34871,37 @@ function writeInstance(root, origin, references, report) {
33201
34871
  * a third file — so deep edits inside a nested prefab are not written back; `flatten: true` is the
33202
34872
  * escape hatch.
33203
34873
  *
34874
+ * An instance root that stands for its scene's single root is diffed against that root's record
34875
+ * too, but only for the components the scene put on it: its name, transform, and other entity
34876
+ * fields, and the components it gained, are the entry's own.
34877
+ *
33204
34878
  * @param root - The instance root.
33205
- * @param scene - The instanced scene.
34879
+ * @param link - Its link to the instanced scene.
33206
34880
  * @param references - How references resolve.
33207
34881
  * @param report - Receives problems.
33208
34882
  * @returns The overrides, in a stable order: entity records in file order, then per entity its
33209
34883
  * plain properties, then its components.
33210
34884
  */
33211
- function computeOverrides(root, scene, references, report) {
34885
+ function computeOverrides(root, link, references, report) {
33212
34886
  const current = /* @__PURE__ */ new Map();
34887
+ const single = link.root;
34888
+ if (single !== null) current.set(single.sourceUid, root);
33213
34889
  collectDirectMembers(root, root, current);
33214
34890
  const overrides = [];
33215
- const source = scene.file.entities;
34891
+ const source = link.scene.file.entities;
33216
34892
  for (let index = 0; index < source.length; index += 1) {
33217
34893
  const record = source[index];
33218
34894
  if (record === void 0) continue;
33219
34895
  const entity = current.get(record.uid);
33220
34896
  if (entity === void 0) continue;
34897
+ if (entity === root && single !== null) {
34898
+ diffComponents(entity, record, {
34899
+ sourceUids: single.componentSourceUids,
34900
+ from: single.components,
34901
+ inside: true
34902
+ }, overrides, references, report);
34903
+ continue;
34904
+ }
33221
34905
  diffEntity(entity, record, overrides, references, report);
33222
34906
  }
33223
34907
  return overrides;
@@ -33274,7 +34958,13 @@ function diffEntity(entity, record, overrides, references, report) {
33274
34958
  value: tags
33275
34959
  });
33276
34960
  diffTransform(entity, record, uid, overrides);
33277
- diffComponents(entity, record, uid, overrides, references, report);
34961
+ const origin = entityInternals(entity).origin;
34962
+ const nested = origin?.instanced?.root?.components ?? /* @__PURE__ */ new Set();
34963
+ diffComponents(entity, record, {
34964
+ sourceUids: origin?.componentSourceUids ?? /* @__PURE__ */ new Map(),
34965
+ from: nested,
34966
+ inside: false
34967
+ }, overrides, references, report);
33278
34968
  }
33279
34969
  /**
33280
34970
  * Diffs an instanced entity's transform against its file record.
@@ -33305,21 +34995,24 @@ function diffTransform(entity, record, uid, overrides) {
33305
34995
  *
33306
34996
  * @param entity - The runtime entity.
33307
34997
  * @param record - Its file record.
33308
- * @param uid - The record's uid, for paths.
34998
+ * @param diff - Which components to diff, and their record uids.
33309
34999
  * @param overrides - Where patches are appended.
33310
35000
  * @param references - How references resolve.
33311
35001
  * @param report - Receives problems.
33312
35002
  */
33313
- function diffComponents(entity, record, uid, overrides, references, report) {
33314
- const sourceUids = entityInternals(entity).origin?.componentSourceUids ?? /* @__PURE__ */ new Map();
35003
+ function diffComponents(entity, record, diff, overrides, references, report) {
35004
+ const uid = record.uid;
35005
+ const sourceUids = diff.sourceUids;
33315
35006
  const declared = record.components ?? [];
33316
35007
  const seen = /* @__PURE__ */ new Set();
33317
35008
  const components = entity.components;
33318
35009
  for (let index = 0; index < components.length; index += 1) {
33319
35010
  const component = components[index];
33320
35011
  if (component === void 0 || component === entity.transform || component.isDestroyed) continue;
35012
+ if (diff.from.has(component.uid) !== diff.inside) continue;
33321
35013
  if (component.world.registry.describe(component.constructor).typeId === null) continue;
33322
35014
  const sourceUid = sourceUids.get(component.uid);
35015
+ if (sourceUid === void 0 && diff.inside) continue;
33323
35016
  const written = serializeComponent(component, references, (issue) => {
33324
35017
  report(issue.code, issue.message);
33325
35018
  });
@@ -33472,15 +35165,113 @@ function sameNumbers(left, right) {
33472
35165
  return true;
33473
35166
  }
33474
35167
  /**
33475
- * Compares two JSON values structurally. Both sides come out of the same canonical encoder, so
33476
- * comparing their canonical text is exact and cheap.
35168
+ * Compares two JSON values structurally, counting both spellings of one asset reference as equal.
35169
+ *
35170
+ * @remarks
35171
+ * One side is what the instanced file says, written by hand or by any tool; the other comes out of
35172
+ * the encoder. A file may leave out an asset reference's `type`, which the loader then infers from
35173
+ * the address, but the encoder always writes the type of the handle it holds. So
35174
+ * `{ "$asset": a }` and `{ "$asset": a, "type": t }` name the same asset; comparing them as text
35175
+ * would save every terse reference in an instanced prefab as an override.
33477
35176
  *
33478
35177
  * @param left - The first.
33479
35178
  * @param right - The second.
33480
- * @returns `true` when they encode identically.
35179
+ * @returns `true` when they hold the same data.
33481
35180
  */
33482
35181
  function sameJson(left, right) {
33483
- return JSON.stringify(left) === JSON.stringify(right);
35182
+ if (left === right) return true;
35183
+ const leftArray = asJsonArray(left);
35184
+ const rightArray = asJsonArray(right);
35185
+ if (leftArray !== null || rightArray !== null) {
35186
+ if (leftArray === null || rightArray === null || leftArray.length !== rightArray.length) return false;
35187
+ for (let index = 0; index < leftArray.length; index += 1) if (!sameJson(leftArray[index] ?? null, rightArray[index] ?? null)) return false;
35188
+ return true;
35189
+ }
35190
+ const leftObject = asJsonObject(left);
35191
+ const rightObject = asJsonObject(right);
35192
+ if (leftObject === null || rightObject === null) return false;
35193
+ if (typeof leftObject["$asset"] === "string" && typeof rightObject["$asset"] === "string") return sameAssetReference(leftObject, rightObject);
35194
+ const keys = Object.keys(leftObject);
35195
+ if (keys.length !== Object.keys(rightObject).length) return false;
35196
+ for (const key of keys) if (!Object.hasOwn(rightObject, key) || !sameJson(leftObject[key] ?? null, rightObject[key] ?? null)) return false;
35197
+ return true;
35198
+ }
35199
+ /**
35200
+ * Compares two `{ "$asset": … }` references: the same address, and the same type unless one side
35201
+ * leaves the type for the loader to infer.
35202
+ *
35203
+ * @param left - The first reference.
35204
+ * @param right - The second reference.
35205
+ * @returns `true` when they name the same asset.
35206
+ */
35207
+ function sameAssetReference(left, right) {
35208
+ if (left["$asset"] !== right["$asset"]) return false;
35209
+ const leftType = left["type"];
35210
+ const rightType = right["type"];
35211
+ return leftType === void 0 || rightType === void 0 || leftType === rightType;
35212
+ }
35213
+ //#endregion
35214
+ //#region src/schema/describe-registry.ts
35215
+ /**
35216
+ * The package a registered component belongs to: the extension that registered it, or else the
35217
+ * namespace of its type id.
35218
+ *
35219
+ * @param registry - The registry the component is registered in.
35220
+ * @param typeId - The component's type id.
35221
+ * @returns The extension's `name` (`@ignifx/3d`), or everything before the type id's last `/`
35222
+ * (`mygame` for `mygame/Mover`) when no extension registered it.
35223
+ *
35224
+ * @internal
35225
+ */
35226
+ function componentPackage(registry, typeId) {
35227
+ return registry.registrarOf(typeId) ?? typeId.slice(0, Math.max(0, typeId.lastIndexOf("/")));
35228
+ }
35229
+ /**
35230
+ * Describes every component an app has registered, the engine's, its extensions' and the game's,
35231
+ * the way {@link describeSchema} describes one, plus what only the registry knows: whether an
35232
+ * entity may hold more than one (`allowMultiple`) and which package registered it (`package`).
35233
+ * This is what an external inspector, such as the ignifx editor, is generated from.
35234
+ *
35235
+ * @remarks
35236
+ * `package` is the `name` of the extension whose `register(ctx)` registered the class, which is the
35237
+ * npm package name for a published extension (`@ignifx/core`, `@ignifx/3d`). A class the game
35238
+ * registered itself with `app.registerComponents` has no extension, so its `package` is its type
35239
+ * id's namespace: everything before the last `/` (`third-person` for `third-person/Beacon`).
35240
+ *
35241
+ * `ignifx/Transform` declares no schema on its class; it is described with {@link transformSchema}
35242
+ * and marked `builtIn`, because every entity carries exactly one and a scene file stores it as the
35243
+ * entity's `transform` block rather than in its `components`.
35244
+ *
35245
+ * @param registry - The registry to walk, usually `app.world.registry`.
35246
+ * @param curated - Titles, formats and summaries by type id, for example a package's own
35247
+ * `describeSchemas()`; a component without an entry is titled from its type id.
35248
+ * @returns The descriptions, keyed by type id, in registration order.
35249
+ *
35250
+ * @example
35251
+ * ```ts
35252
+ * const schemas = describeRegisteredSchemas(app.world.registry, describeSchemas());
35253
+ * schemas["ignifx/Camera"]?.package; // "@ignifx/core"
35254
+ * schemas["ignifx/Camera"]?.allowMultiple; // false
35255
+ * ```
35256
+ *
35257
+ * @public
35258
+ */
35259
+ function describeRegisteredSchemas(registry, curated) {
35260
+ const described = {};
35261
+ for (const [typeId, type] of registry.registrations()) {
35262
+ const info = registry.describe(type);
35263
+ const meta = curated?.[typeId];
35264
+ const builtIn = type === Transform;
35265
+ described[typeId] = describeSchema(typeId, builtIn ? transformSchema() : info.schema ?? {}, {
35266
+ ...meta?.title === void 0 ? {} : { title: meta.title },
35267
+ ...meta?.format === void 0 ? {} : { format: meta.format },
35268
+ ...meta?.description === void 0 ? {} : { description: meta.description },
35269
+ allowMultiple: info.allowMultiple,
35270
+ package: componentPackage(registry, typeId),
35271
+ ...builtIn ? { builtIn } : {}
35272
+ });
35273
+ }
35274
+ return described;
33484
35275
  }
33485
35276
  //#endregion
33486
35277
  //#region src/script/wait.ts
@@ -33588,6 +35379,443 @@ function waitWhile(predicate) {
33588
35379
  });
33589
35380
  }
33590
35381
  //#endregion
33591
- 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, 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, 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, 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, createModelLoader, createPerformanceClock, createRay, createSceneAsset, createSceneLoader, createSeededRandom, createServiceKey, createShaderLoader, createStorageBufferAsset, createTextureLoader, createUlidFactory, curve, custom, customEffect, decodeProps, decodeValue, defaultRenderingSettings, defineExtension, defineMaterialPlugin, defineSchema, degToRad, deltaAngleDegrees, describeEnvironmentFileFormat, describeMaterialFileFormat, describeSceneFileFormat, describeSchema, describeSchemas, encodeProps, encodeValue, entityRef, enumOf, environmentDefinition, f32, f64, forceRendererDeviceLossForTesting, formatErrorMessage, generateUlid, i32, instantiateScene, inverseLerp, isAssetRef, isIgnifxError, isLiteMaterialPluginPoint, isSceneFileHeader, isUlid, isValidErrorCode, isWebGpuAvailable, jsonAssetLoader, layerMask, lerp, lerpAngleDegrees, map, moveTowards, optional, parseOverridePath, pbrMaterialDefinition, pingPong, platformInternals, quat, radToDeg, record, repeat, resetFrameSample, resolveEase, sceneFileJsonSchema, serializeComponent, serializeEntity, serializeScene, shaderMaterialDefinition, sign, smoothStep, standardMaterialDefinition, storageInternals, str, stringifySceneFile, textAssetLoader, toJsonSchema, u32, validateProps, validateSceneFile, validateValue, vec2, vec3, vec4, waitFixedUpdate, waitSeconds, waitSecondsRealtime, waitUntil, waitWhile, wrapAngleDegrees };
35382
+ //#region src/settings/settings-json.ts
35383
+ /**
35384
+ * The JSON form of project settings. Settings are read as written: `createApp` hands the project's
35385
+ * values to `validateProps` unencoded, so a `vec3` is `{ x, y, z }` and a `color` is
35386
+ * `{ r, g, b, a }`, not the scene file's arrays. Everything here describes that runtime form.
35387
+ */
35388
+ /**
35389
+ * Reports whether a value is a plain bag of named values.
35390
+ *
35391
+ * @param value - The candidate.
35392
+ * @returns `true` for a non-null, non-array object.
35393
+ */
35394
+ function isBag(value) {
35395
+ return typeof value === "object" && value !== null && !Array.isArray(value);
35396
+ }
35397
+ /**
35398
+ * Copies a value made of JSON data, dropping what JSON cannot carry.
35399
+ *
35400
+ * @param value - The value.
35401
+ * @returns The JSON copy, or `undefined` for a function, `undefined`, or a non-finite number.
35402
+ */
35403
+ function plainJson(value) {
35404
+ if (value === null || typeof value === "string" || typeof value === "boolean") return value;
35405
+ if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
35406
+ if (Array.isArray(value)) return value.map((item) => plainJson(item) ?? null);
35407
+ if (isBag(value)) return entriesToJson(Object.entries(value), plainJson);
35408
+ }
35409
+ /**
35410
+ * Builds a JSON object from entries, leaving out the ones that convert to nothing.
35411
+ *
35412
+ * @param entries - The name and value pairs.
35413
+ * @param convert - How one value converts.
35414
+ * @returns The object.
35415
+ */
35416
+ function entriesToJson(entries, convert) {
35417
+ const object = {};
35418
+ for (const [name, value] of entries) {
35419
+ const converted = convert(value, name);
35420
+ if (converted !== void 0) object[name] = converted;
35421
+ }
35422
+ return object;
35423
+ }
35424
+ /**
35425
+ * Converts a runtime settings value into the JSON a settings file holds for it.
35426
+ *
35427
+ * @param field - The field the value belongs to.
35428
+ * @param value - The runtime value, such as a registered default.
35429
+ * @returns The JSON form, or `undefined` when the value does not fit the field.
35430
+ *
35431
+ * @internal
35432
+ */
35433
+ function settingsValueToJson(field, value) {
35434
+ const { spec } = field;
35435
+ switch (spec.kind) {
35436
+ case "vec2":
35437
+ case "vec3":
35438
+ case "vec4":
35439
+ case "quat": return isBag(value) ? entriesToJson(channelEntries(VECTOR_COMPONENTS.slice(0, spec.components), value), plainJson) : void 0;
35440
+ case "color": return isBag(value) ? entriesToJson(channelEntries(COLOR_CHANNELS, value), plainJson) : void 0;
35441
+ case "array": return Array.isArray(value) ? value.map((item) => settingsValueToJson(spec.item, item) ?? null) : void 0;
35442
+ case "record": {
35443
+ if (!isBag(value)) return;
35444
+ const object = {};
35445
+ for (const [name, sub] of Object.entries(spec.fields)) {
35446
+ const converted = settingsValueToJson(sub, value[name]);
35447
+ if (converted !== void 0) object[name] = converted;
35448
+ }
35449
+ return object;
35450
+ }
35451
+ case "map": return isBag(value) ? entriesToJson(Object.entries(value), (entry) => settingsValueToJson(spec.value, entry)) : void 0;
35452
+ case "optional": return value === null ? null : settingsValueToJson(spec.inner, value);
35453
+ case "entityRef":
35454
+ case "componentRef": return value === null ? null : void 0;
35455
+ case "asset":
35456
+ if (isBag(value) && typeof value["address"] === "string") return typeof value["type"] === "string" ? {
35457
+ address: value["address"],
35458
+ type: value["type"]
35459
+ } : { address: value["address"] };
35460
+ return value === null ? null : void 0;
35461
+ case "f32":
35462
+ case "f64":
35463
+ case "i32":
35464
+ case "u32":
35465
+ case "bool":
35466
+ case "str":
35467
+ case "enum":
35468
+ case "layerMask":
35469
+ case "curve":
35470
+ case "custom": return plainJson(value);
35471
+ default: return assertNever(spec, "schema field kind");
35472
+ }
35473
+ }
35474
+ /**
35475
+ * Pairs each channel name with the value's channel.
35476
+ *
35477
+ * @param names - The channel names.
35478
+ * @param value - The vector or colour.
35479
+ * @returns The pairs, in channel order.
35480
+ */
35481
+ function channelEntries(names, value) {
35482
+ return names.map((name) => [name, value[name]]);
35483
+ }
35484
+ /**
35485
+ * The object schema of channel values, every channel required.
35486
+ *
35487
+ * @param names - The channel names.
35488
+ * @param channel - The schema of one channel.
35489
+ * @returns The fragment.
35490
+ */
35491
+ function channelsSchema(names, channel) {
35492
+ return {
35493
+ type: "object",
35494
+ properties: Object.fromEntries(names.map((name) => [name, channel])),
35495
+ required: [...names]
35496
+ };
35497
+ }
35498
+ /**
35499
+ * Builds the JSON Schema of one settings field in the form `createApp` reads, with its default, its
35500
+ * tooltip, its bounds and the `x-ignifx-*` inspector keywords.
35501
+ *
35502
+ * @param field - The field.
35503
+ * @param defaultValue - The runtime default to annotate it with, or `undefined` for none.
35504
+ * @returns The fragment.
35505
+ *
35506
+ * @internal
35507
+ */
35508
+ function settingsFieldJsonSchema(field, defaultValue) {
35509
+ const fragment = { ...settingsKindJsonSchema(field) };
35510
+ const { tooltip, min, max, step, hidden, readonly, group } = field.options;
35511
+ const annotations = {
35512
+ description: tooltip,
35513
+ minimum: min,
35514
+ maximum: max,
35515
+ "x-ignifx-step": step,
35516
+ "x-ignifx-hidden": hidden,
35517
+ "x-ignifx-readonly": readonly,
35518
+ "x-ignifx-group": group,
35519
+ default: defaultValue === void 0 ? void 0 : settingsValueToJson(field, defaultValue)
35520
+ };
35521
+ for (const [keyword, value] of Object.entries(annotations)) if (value !== void 0) fragment[keyword] = value;
35522
+ return fragment;
35523
+ }
35524
+ /**
35525
+ * Builds the object schema of a group of settings fields: every field optional, no other key.
35526
+ *
35527
+ * @param fields - The fields.
35528
+ * @param defaults - The runtime defaults by field name; a field without one carries no `default`.
35529
+ * @returns The fragment.
35530
+ *
35531
+ * @internal
35532
+ */
35533
+ function settingsObjectJsonSchema(fields, defaults) {
35534
+ const properties = {};
35535
+ for (const [name, field] of Object.entries(fields)) properties[name] = settingsFieldJsonSchema(field, defaults[name]);
35536
+ return {
35537
+ type: "object",
35538
+ properties,
35539
+ additionalProperties: false
35540
+ };
35541
+ }
35542
+ /**
35543
+ * Builds the fragment that constrains a field's runtime form, mirroring `validateProps`.
35544
+ *
35545
+ * @param field - The field.
35546
+ * @returns The fragment, without annotations.
35547
+ */
35548
+ function settingsKindJsonSchema(field) {
35549
+ const { spec } = field;
35550
+ switch (spec.kind) {
35551
+ case "f32":
35552
+ case "f64": return { type: "number" };
35553
+ case "i32": return {
35554
+ type: "integer",
35555
+ minimum: -2147483648,
35556
+ maximum: 2147483647
35557
+ };
35558
+ case "u32": return {
35559
+ type: "integer",
35560
+ minimum: 0,
35561
+ maximum: 4294967295
35562
+ };
35563
+ case "bool": return { type: "boolean" };
35564
+ case "str": return { type: "string" };
35565
+ case "enum": return {
35566
+ type: "string",
35567
+ enum: [...spec.values]
35568
+ };
35569
+ case "vec2":
35570
+ case "vec3":
35571
+ case "vec4":
35572
+ case "quat": return channelsSchema(VECTOR_COMPONENTS.slice(0, spec.components), { type: "number" });
35573
+ case "color": return channelsSchema(COLOR_CHANNELS, {
35574
+ type: "number",
35575
+ minimum: 0,
35576
+ maximum: 1
35577
+ });
35578
+ case "entityRef":
35579
+ case "componentRef": return { oneOf: [{ type: "object" }, { type: "null" }] };
35580
+ case "asset": return { oneOf: [{
35581
+ type: "object",
35582
+ properties: { address: { type: "string" } },
35583
+ required: ["address"]
35584
+ }, { type: "null" }] };
35585
+ case "array": return {
35586
+ type: "array",
35587
+ items: settingsFieldJsonSchema(spec.item, void 0)
35588
+ };
35589
+ case "record": return settingsObjectJsonSchema(spec.fields, {});
35590
+ case "map": return {
35591
+ type: "object",
35592
+ additionalProperties: settingsFieldJsonSchema(spec.value, void 0)
35593
+ };
35594
+ case "optional": return { anyOf: [settingsFieldJsonSchema(spec.inner, void 0), { type: "null" }] };
35595
+ case "layerMask": return {
35596
+ type: "array",
35597
+ items: { type: "string" }
35598
+ };
35599
+ case "curve": return {
35600
+ type: "object",
35601
+ properties: { keys: {
35602
+ type: "array",
35603
+ items: {
35604
+ type: "array",
35605
+ items: { type: "number" },
35606
+ minItems: 4,
35607
+ maxItems: 4
35608
+ }
35609
+ } },
35610
+ required: ["keys"]
35611
+ };
35612
+ case "custom": return {};
35613
+ default: return assertNever(spec, "schema field kind");
35614
+ }
35615
+ }
35616
+ //#endregion
35617
+ //#region src/settings/describe-settings.ts
35618
+ /**
35619
+ * The `format` every settings section description carries, so a consumer that merges settings and
35620
+ * component descriptions can tell them apart.
35621
+ *
35622
+ * @public
35623
+ */
35624
+ const SETTINGS_DESCRIPTION_FORMAT = "settings";
35625
+ /**
35626
+ * Whether a single field of each kind may stand for its whole section: a one-field section may be
35627
+ * written as the field's value (`layers: ["Default"]`) only when that value cannot be mistaken for
35628
+ * the section's object form, so a kind whose runtime form may be an object (a vector or colour is
35629
+ * `{ x, y, z }` or `{ r, g, b, a }` in settings) never qualifies.
35630
+ */
35631
+ const ALLOWS_SHORTHAND = {
35632
+ f32: true,
35633
+ f64: true,
35634
+ i32: true,
35635
+ u32: true,
35636
+ bool: true,
35637
+ str: true,
35638
+ vec2: false,
35639
+ vec3: false,
35640
+ vec4: false,
35641
+ quat: false,
35642
+ color: false,
35643
+ enum: true,
35644
+ array: true,
35645
+ layerMask: true,
35646
+ entityRef: false,
35647
+ componentRef: false,
35648
+ asset: false,
35649
+ record: false,
35650
+ map: false,
35651
+ optional: false,
35652
+ curve: false,
35653
+ custom: false
35654
+ };
35655
+ /**
35656
+ * Reaches the settings table behind `app.settings`.
35657
+ *
35658
+ * @param app - The app.
35659
+ * @returns The table.
35660
+ * @throws IgnifxError with code `IGX-0702` when the app was not created by this copy of core.
35661
+ */
35662
+ function settingsStoreOf(app) {
35663
+ const { settings } = app;
35664
+ if (settings instanceof SettingsStore) return settings;
35665
+ throw new IgnifxError(CoreErrorCode.invalidRuntime, "app.settings was not created by this copy of @ignifx/core.", {
35666
+ context: { member: "app.settings" },
35667
+ hint: "Describe the settings of an app createApp returned."
35668
+ });
35669
+ }
35670
+ /**
35671
+ * Describes one section, with the defaults its owner registered rather than the schema's own field
35672
+ * defaults, because the registered bag is what the project gets for a value it omits.
35673
+ *
35674
+ * @param name - The section name.
35675
+ * @param section - The registered section.
35676
+ * @returns The description.
35677
+ */
35678
+ function describeSection(name, section) {
35679
+ const described = describeSchema(name, section.schema, {
35680
+ title: name,
35681
+ format: SETTINGS_DESCRIPTION_FORMAT,
35682
+ package: section.owner
35683
+ });
35684
+ const fields = {};
35685
+ for (const [fieldName, field] of Object.entries(section.schema)) {
35686
+ const description = described.fields[fieldName];
35687
+ if (description !== void 0) fields[fieldName] = settingsFieldDescription(field, description, section.defaults[fieldName]);
35688
+ }
35689
+ return {
35690
+ ...described,
35691
+ fields
35692
+ };
35693
+ }
35694
+ /**
35695
+ * Rewrites a field description's defaults, at every depth, into the runtime form settings are
35696
+ * written in: `{ x, y, z }` rather than the scene file's `[x, y, z]`.
35697
+ *
35698
+ * @param field - The field.
35699
+ * @param description - Its description, with defaults in the scene-file form.
35700
+ * @param value - The runtime default, or `undefined` to leave `default` off.
35701
+ * @returns The description in the settings form.
35702
+ */
35703
+ function settingsFieldDescription(field, description, value) {
35704
+ const { default: _encoded, item, fields, value: entry, inner, ...rest } = description;
35705
+ const { spec } = field;
35706
+ const converted = value === void 0 ? void 0 : settingsValueToJson(field, value);
35707
+ const nested = {};
35708
+ if (spec.kind === "array" && item !== void 0) nested.item = settingsFieldDescription(spec.item, item, spec.item.createDefault());
35709
+ else if (spec.kind === "map" && entry !== void 0) nested.value = settingsFieldDescription(spec.value, entry, spec.value.createDefault());
35710
+ else if (spec.kind === "optional" && inner !== void 0) nested.inner = settingsFieldDescription(spec.inner, inner, spec.inner.createDefault());
35711
+ else if (spec.kind === "record" && fields !== void 0) {
35712
+ nested.fields = {};
35713
+ for (const [name, sub] of Object.entries(spec.fields)) {
35714
+ const subDescription = fields[name];
35715
+ if (subDescription !== void 0) nested.fields[name] = settingsFieldDescription(sub, subDescription, sub.createDefault());
35716
+ }
35717
+ }
35718
+ return {
35719
+ ...rest,
35720
+ ...converted === void 0 ? {} : { default: converted },
35721
+ ...nested
35722
+ };
35723
+ }
35724
+ /**
35725
+ * Describes every project settings section an app has registered (core's own `layers`,
35726
+ * `sortingLayers`, `time`, `assets` and `rendering`, and every section an extension declared with
35727
+ * `ctx.registerSettings`) in the same shape {@link describeRegisteredSchemas} describes components.
35728
+ * This is what an external settings panel, such as the ignifx editor's, is generated from.
35729
+ *
35730
+ * @remarks
35731
+ * Each entry is keyed and titled by its section name, has `format: "settings"`
35732
+ * ({@link SETTINGS_DESCRIPTION_FORMAT}), and names the extension that registered it as `package`
35733
+ * (`@ignifx/core`, `@ignifx/physics`). A field's `default` is the value the owner registered for it,
35734
+ * which is what the project gets when it omits the field; a field the owner's defaults leave out has
35735
+ * no `default`, because the resolved section has no value for it either.
35736
+ *
35737
+ * Defaults are in the **settings form**, the form `createApp` reads, which differs from the scene
35738
+ * file's for vectors and colours: a `vec3` default is `{ "x": 0, "y": -9.81, "z": 0 }` and a `color`
35739
+ * default is `{ "r": 0, "g": 0, "b": 0, "a": 1 }`, not an array. A tool writes values back in this
35740
+ * form.
35741
+ *
35742
+ * The registration seam is `ctx.registerSettings(section, schema, defaults)`: an extension that
35743
+ * declares a section there is described here with no further work. A section is written in project
35744
+ * settings (`ignifx.settings.json` or `ignifx.config.ts`) as an object of these fields; a section
35745
+ * with exactly one field of a non-object kind (a number, string, enum or array, not a vector or
35746
+ * colour) may also be written as that field's value.
35747
+ *
35748
+ * @param app - The app whose sections to describe; its extensions have all registered by the time
35749
+ * `createApp` resolves.
35750
+ * @returns The descriptions, keyed by section name, in registration order.
35751
+ * @throws IgnifxError with code `IGX-0702` when `app` was not created by this copy of
35752
+ * `@ignifx/core`.
35753
+ *
35754
+ * @example
35755
+ * ```ts
35756
+ * const sections = describeSettings(app);
35757
+ * sections["time"]?.package; // "@ignifx/core"
35758
+ * sections["time"]?.fields["fixedDeltaTime"]?.default; // 0.016666666666666666
35759
+ * ```
35760
+ *
35761
+ * @public
35762
+ */
35763
+ function describeSettings(app) {
35764
+ const described = {};
35765
+ for (const [name, section] of settingsStoreOf(app).registrations()) described[name] = describeSection(name, section);
35766
+ return described;
35767
+ }
35768
+ /**
35769
+ * The JSON Schema of one section as project settings may write it: the object form, or, for a
35770
+ * single field of a non-object kind, also that field's value on its own.
35771
+ *
35772
+ * @param section - The registered section.
35773
+ * @returns The fragment.
35774
+ */
35775
+ function sectionJsonSchema(section) {
35776
+ const { schema, defaults } = section;
35777
+ const objectForm = settingsObjectJsonSchema(schema, defaults);
35778
+ const entries = Object.entries(schema);
35779
+ const [only] = entries;
35780
+ if (entries.length !== 1 || only === void 0 || !ALLOWS_SHORTHAND[only[1].kind]) return objectForm;
35781
+ return { oneOf: [objectForm, settingsFieldJsonSchema(only[1], defaults[only[0]])] };
35782
+ }
35783
+ /**
35784
+ * Generates the JSON Schema (draft 2020-12) of a project's settings object, the content of
35785
+ * `ignifx.settings.json`, from every section the app registered. Pass it to the Vite plugin as
35786
+ * `ignifx({ schemas: { settings } })` to validate the project settings at build time, or associate
35787
+ * it with `ignifx.settings.json` in a text editor.
35788
+ *
35789
+ * @remarks
35790
+ * The schema describes the settings form `createApp` reads (vectors as `{ x, y, z }`, colours as
35791
+ * `{ r, g, b, a }` with every channel required), so a document it accepts also passes `createApp`'s
35792
+ * own validation (`IGX-0408`). Every section is optional and a section omitted takes its defaults.
35793
+ * An unknown key inside a section is a violation. The top level stays open: a section this app did
35794
+ * not register, perhaps one of an extension it lacks, is left to `createApp`, which reports it
35795
+ * (`IGX-0407`), and to the Vite plugin, which warns about it.
35796
+ *
35797
+ * @param app - The app whose sections to describe.
35798
+ * @returns The object schema, one property per section.
35799
+ * @throws IgnifxError with code `IGX-0702` when `app` was not created by this copy of
35800
+ * `@ignifx/core`.
35801
+ *
35802
+ * @example
35803
+ * ```ts
35804
+ * const schema = settingsJsonSchema(app);
35805
+ * Object.keys(schema["properties"] ?? {}); // ["layers", "sortingLayers", "time", "assets", "rendering"]
35806
+ * ```
35807
+ *
35808
+ * @public
35809
+ */
35810
+ function settingsJsonSchema(app) {
35811
+ const properties = {};
35812
+ for (const [name, section] of settingsStoreOf(app).registrations()) properties[name] = sectionJsonSchema(section);
35813
+ return {
35814
+ type: "object",
35815
+ properties
35816
+ };
35817
+ }
35818
+ //#endregion
35819
+ 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 };
33592
35820
 
33593
35821
  //# sourceMappingURL=index.js.map