@ignifx/core 0.10.0 → 0.12.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 (47) hide show
  1. package/decoders/babylon.ktx2Decoder.js +1 -0
  2. package/decoders/babylonjs-ktx2decoder.LICENSE.md +71 -0
  3. package/decoders/meshopt_decoder.js +199 -0
  4. package/decoders/meshoptimizer.LICENSE.md +21 -0
  5. package/decoders/msc_basis_transcoder.js +22 -0
  6. package/decoders/msc_basis_transcoder.wasm +0 -0
  7. package/decoders/scoped-babylonjs-ktx2decoder.LICENSE.md +396 -0
  8. package/decoders/scoped-babylonjs-ktx2decoder.NOTICE.md +15 -0
  9. package/decoders/uastc_astc.wasm +0 -0
  10. package/decoders/uastc_bc7.wasm +0 -0
  11. package/decoders/uastc_r8_unorm.wasm +0 -0
  12. package/decoders/uastc_rg8_unorm.wasm +0 -0
  13. package/decoders/uastc_rgba8_srgb_v2.wasm +0 -0
  14. package/decoders/uastc_rgba8_unorm_v2.wasm +0 -0
  15. package/decoders/vendored.json +96 -0
  16. package/decoders/zstddec.wasm +0 -0
  17. package/dist/decoders-CHJ7vduE.js +82 -0
  18. package/dist/decoders-CHJ7vduE.js.map +1 -0
  19. package/dist/{environment-BCjfp1jB.js → environment-C9AjYJgV.js} +2 -2
  20. package/dist/{environment-BCjfp1jB.js.map → environment-C9AjYJgV.js.map} +1 -1
  21. package/dist/{ignifx-error-RpK-lWwE.js → ignifx-error-Dq2qJMkZ.js} +10 -3
  22. package/dist/ignifx-error-Dq2qJMkZ.js.map +1 -0
  23. package/dist/index.d.ts +191 -17
  24. package/dist/index.d.ts.map +1 -1
  25. package/dist/index.js +665 -86
  26. package/dist/index.js.map +1 -1
  27. package/dist/json-CzZZ6K4x.js +24 -0
  28. package/dist/json-CzZZ6K4x.js.map +1 -0
  29. package/dist/{material-plugin-CWtV7DkH.js → material-plugin-BOCB7Stt.js} +2 -2
  30. package/dist/{material-plugin-CWtV7DkH.js.map → material-plugin-BOCB7Stt.js.map} +1 -1
  31. package/dist/{post-effect-C42XJFmo.js → post-effect-BHl7U56q.js} +5 -4
  32. package/dist/post-effect-BHl7U56q.js.map +1 -0
  33. package/dist/{post-effect-compiler-pOvXae-i.js → post-effect-compiler-Dw6zW2cG.js} +3 -3
  34. package/dist/{post-effect-compiler-pOvXae-i.js.map → post-effect-compiler-Dw6zW2cG.js.map} +1 -1
  35. package/dist/{shader-material-B6wwFCKB.js → shader-material-BxQn9FT4.js} +2 -2
  36. package/dist/{shader-material-B6wwFCKB.js.map → shader-material-BxQn9FT4.js.map} +1 -1
  37. package/dist/{shader-material-C4VjLTfV.js → shader-material-DRZmqA_S.js} +10 -6
  38. package/dist/shader-material-DRZmqA_S.js.map +1 -0
  39. package/dist/{shader-pragma-qO9_6sTd.js → shader-pragma-DrFm5f5m.js} +2 -2
  40. package/dist/{shader-pragma-qO9_6sTd.js.map → shader-pragma-DrFm5f5m.js.map} +1 -1
  41. package/dist/{surface-shader-BaR7Kg-F.js → surface-shader-BgZchRBe.js} +4 -4
  42. package/dist/{surface-shader-BaR7Kg-F.js.map → surface-shader-BgZchRBe.js.map} +1 -1
  43. package/package.json +20 -2
  44. package/LICENSE +0 -201
  45. package/dist/ignifx-error-RpK-lWwE.js.map +0 -1
  46. package/dist/post-effect-C42XJFmo.js.map +0 -1
  47. package/dist/shader-material-C4VjLTfV.js.map +0 -1
package/dist/index.js CHANGED
@@ -1,10 +1,11 @@
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";
1
+ import { a as CORE_ERROR_MESSAGES, c as THIRD_PARTY_ERROR_PREFIX, i as isIgnifxError, l as isValidErrorCode, n as assertNever, o as CoreErrorCode, r as formatErrorMessage, s as ErrorRange, t as IgnifxError } from "./ignifx-error-Dq2qJMkZ.js";
2
2
  import { _ as smoothStep, a as clamp, c as deltaAngleDegrees, d as lerpAngleDegrees, f as moveTowards, g as sign, h as repeat, i as approximately, l as inverseLerp, m as radToDeg, n as EPSILON, o as clamp01, p as pingPong, r as RAD_TO_DEG, s as degToRad, t as DEG_TO_RAD, u as lerp, v as wrapAngleDegrees } from "./math-utils-BcDnL-gi.js";
3
3
  import { $ as basisToQuatToRef, A as setMeshReceiveShadows, B as localPosition, C as overrideSubtreeMaterials, D as setMeshId, E as setMeshBounds, F as updateMeshPositions$1, G as readWorldMatrix, H as localScale, I as updateMeshUvs$1, J as setNodeSelfVisible, K as reparentKeepingWorld, L as createNode, M as setMeshSubtreeVisible, N as updateMeshColors$1, O as setMeshMaterial, P as updateMeshNormals$1, Q as Mat4, R as disposeNode, S as disposeMeshTemplate, T as removeMeshFromScene, U as parentNode, V as localRotation, W as readNodeTag, X as worldMatrixVersion, Y as tagNode, Z as MAT4_IDENTITY, _ as createMeshFromGeometry, a as VEC3_ONE, b as createTorusMesh, c as VEC3_ZERO, d as cloneMeshUnderNode, f as collectSubtreeMeshes, g as createGroundMesh, h as createCylinderMesh, i as VEC3_LEFT, j as setMeshRenderOrder, k as setMeshPickable, l as Vec3, m as createCapsuleMesh, n as VEC3_DOWN, o as VEC3_RIGHT, p as createBoxMesh, q as setNodeName, r as VEC3_FORWARD, s as VEC3_UP, t as VEC3_BACKWARD, u as addMeshToScene, v as createPlaneMesh, w as recomputeMeshBounds, x as detachMeshBounds, y as createSphereMesh, z as linkParent } from "./vec3-T2PasQZv.js";
4
4
  import { t as Color } from "./color-DrR6GFTd.js";
5
- import { a as readSceneImageProcessing, c as setSceneEnvironmentRotation, l as setSceneFog, n as installSceneEnvironment, o as setSceneClearColor, r as loadSceneEnvironment, s as setSceneEnvironmentBlur, t as TONE_MAPPING_NAMES, u as setSceneImageProcessingOptions } from "./environment-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
- 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";
5
+ import { a as readSceneImageProcessing, c as setSceneEnvironmentRotation, l as setSceneFog, n as installSceneEnvironment, o as setSceneClearColor, r as loadSceneEnvironment, s as setSceneEnvironmentBlur, t as TONE_MAPPING_NAMES, u as setSceneImageProcessingOptions } from "./environment-C9AjYJgV.js";
6
+ import { a as defineMaterialPlugin, c as MATERIAL_ALPHA_MODES, d as createStandardMaterialFromProps, f as markMaterialDirty, g as setPbrMetallicRoughness, h as setPbrBaseColor, i as MATERIAL_PLUGIN_SAMPLER_BUDGET, l as createDefaultMaterial, m as setMaterialAlpha, n as MATERIAL_PLUGIN_DEFAULT_PRIORITY, o as isLiteMaterialPluginPoint, r as MATERIAL_PLUGIN_RESERVED_NAMES, t as LITE_MATERIAL_PLUGIN_POINTS, u as createPbrMaterialFromProps } from "./material-plugin-BOCB7Stt.js";
7
+ import { t as setOwnJsonProperty } from "./json-CzZZ6K4x.js";
8
+ import { a as postEffectValuesCodec, i as declaredTextureBinding, n as POST_EFFECT_FUNCTION, o as asJsonArray, r as customEffect, s as asJsonObject, t as POST_EFFECT_BUILTIN_UNIFORMS } from "./post-effect-BHl7U56q.js";
8
9
  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
10
  import { acquireTexture, addTask, addToScene, buildFrameGraphTask, captureScreenshot, cloneTransformNode, createBloomPostProcessTask, createCopyToTextureTask, createCsmDirectionalShadowGenerator, createDirectionalLight, createEngine, createEsmDirectionalShadowGenerator, createFontFromBuffer, createFreeCamera, createGpuPicker, createHemisphericLight, createImageProcessingTask, createMeshFromData, createNullEngine, createPcfDirectionalShadowGenerator, createPcfSpotlightShadowGenerator, createPointLight, createRenderTarget, createRenderTask, createSceneContext, createSmaaPostProcessTask, createSpotLight, createStorageBuffer, createTexture2DFromPixels, disableOrthographicCamera, disposeEngine, disposePicker, disposeScene, disposeStorageBuffer, enableBoneControl, enableDeviceLostSceneRecovery, enableMaterialPlugins, enableMaterialStencil, enableOrthographicCamera, enablePbrLightmap, enableSkeletonShadows, enableStandardSkeleton, forceWebGpuDeviceLossForTesting, getEffectiveAspectRatio, getFrameGraph, getProjectionMatrix, getRenderTaskGpuTimings, getViewMatrix, getViewProjectionMatrix, isPbrMaterial, isShaderMaterial, loadTexture2D, onBeforeRender, pickAsync, pickWithRay, rebuildSceneRenderables, registerScene, registerSceneWithShadowSupport, releaseTexture, removeFromScene, resizeEngine, resolveCameraViewport, setGpuTimingEnabled, setShadowTaskCasterMeshes, setSubtreeVisible, setSurfaceSize, startEngine, stopEngine, updateStorageBuffer, updateTexture2DFromPixels } from "@babylonjs/lite";
10
11
  //#region src/signal/signal.ts
@@ -2630,7 +2631,11 @@ const SchemaIssueCode = {
2630
2631
  typeMismatch: "IGX-0605",
2631
2632
  /** A value had the right type but fell outside the field's declared value domain. */
2632
2633
  outOfRange: "IGX-0606",
2633
- /** A property was supplied that the schema does not declare. */
2634
+ /**
2635
+ * A property was supplied that the schema does not declare, or a schema declaration named a field
2636
+ * it may not use: not identifier-like, a `Component`/`Script` member, or an `Object.prototype`
2637
+ * member such as `constructor` or `__proto__`.
2638
+ */
2634
2639
  unknownField: "IGX-0607"
2635
2640
  };
2636
2641
  /**
@@ -2708,6 +2713,31 @@ const RESERVED_FIELD_NAMES = [
2708
2713
  */
2709
2714
  const FIELD_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9]*$/u;
2710
2715
  /**
2716
+ * Refuses a field name that every plain object already has through `Object.prototype`:
2717
+ * `constructor`, `toString`, `valueOf`, `hasOwnProperty`, `__proto__` and the rest. Encoders,
2718
+ * decoders, and the inspector walk a schema and read each field as `values[name]`, so a value that
2719
+ * omits such a field yields the inherited member instead of `undefined`; and they write it as
2720
+ * `out[name] = …`, which for `__proto__` replaces the object's prototype instead of adding a key.
2721
+ * Refusing the name once, where the schema is declared, keeps every one of those sites correct.
2722
+ * `prototype` is not inherited by plain objects, so it stays a legal name.
2723
+ *
2724
+ * A literal `{ __proto__: f32(1) }` (not computed) never makes a key at all: it sets the object's
2725
+ * prototype, so the field would vanish without a word. The fields object must therefore be a plain
2726
+ * object (its prototype `Object.prototype`, or `null`).
2727
+ *
2728
+ * @param fields - The field definitions being declared.
2729
+ * @param where - What declares them, for the message: `"schema"` or `"record"`.
2730
+ * @throws IgnifxError with code `IGX-0607` when a name is an `Object.prototype` member, or the
2731
+ * fields object is not a plain object.
2732
+ *
2733
+ * @internal
2734
+ */
2735
+ function assertNoInheritedFieldNames(fields, where) {
2736
+ const prototype = Object.getPrototypeOf(fields);
2737
+ if (prototype !== Object.prototype && prototype !== null) throwSchemaError(SchemaIssueCode.unknownField, `${where} fields are not a plain object, so a field is hidden in its prototype; a literal "__proto__: …" key sets the prototype instead of declaring a field. Rename the field.`);
2738
+ for (const name of Object.keys(fields)) if (Object.hasOwn(Object.prototype, name)) throwSchemaError(SchemaIssueCode.unknownField, `${where} field "${name}" names a member every object inherits (Object.prototype.${name}); rename the field.`);
2739
+ }
2740
+ /**
2711
2741
  * Rewrites a JavaScript value into a mutable string-keyed view. Schema-shaped objects are always
2712
2742
  * plain records built by this module, so the assertion holds by construction; it exists because a
2713
2743
  * mapped type such as `FieldsOf<S>` cannot be indexed generically (coding standards §5.2 permits
@@ -2742,8 +2772,10 @@ function fieldsView(value) {
2742
2772
  *
2743
2773
  * @param fields - The field definitions, keyed by the property name they become.
2744
2774
  * @returns The same object, with its precise type preserved.
2745
- * @throws A `TypeError` when a field name is not identifier-like, starts with `_`, or collides with
2746
- * a `Component`/`Script` member such as `enabled` or `update`.
2775
+ * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like, starts with
2776
+ * `_`, collides with a `Component`/`Script` member such as `enabled` or `update`, or names an
2777
+ * `Object.prototype` member such as `constructor` or `toString`, or when `fields` is not a plain
2778
+ * object (a literal `__proto__: …` key sets its prototype rather than declaring a field).
2747
2779
  *
2748
2780
  * @example
2749
2781
  * ```ts
@@ -2756,6 +2788,7 @@ function fieldsView(value) {
2756
2788
  * @public
2757
2789
  */
2758
2790
  function defineSchema(fields) {
2791
+ assertNoInheritedFieldNames(fields, "schema");
2759
2792
  for (const name of Object.keys(fields)) {
2760
2793
  if (!FIELD_NAME_PATTERN.test(name)) throwSchemaError(SchemaIssueCode.unknownField, `schema field "${name}" is not a valid field name: use a letter followed by letters or digits, and do not start with "_".`);
2761
2794
  if (RESERVED_FIELD_NAMES.includes(name)) throwSchemaError(SchemaIssueCode.unknownField, `schema field "${name}" collides with a Component or Script member; rename the field.`);
@@ -2946,8 +2979,8 @@ var Component = class {
2946
2979
  * @typeParam S - The schema being declared.
2947
2980
  * @param schema - The field definitions, keyed by the property name they become.
2948
2981
  * @returns An abstract class to extend.
2949
- * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like or collides
2950
- * with a `Component`/`Script` member.
2982
+ * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like, collides
2983
+ * with a `Component`/`Script` member, or names an `Object.prototype` member such as `constructor`.
2951
2984
  *
2952
2985
  * @example
2953
2986
  * ```ts
@@ -3180,8 +3213,8 @@ var Script = class extends Component {
3180
3213
  * @typeParam S - The schema being declared.
3181
3214
  * @param schema - The field definitions, keyed by the property name they become.
3182
3215
  * @returns An abstract class to extend.
3183
- * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like or collides
3184
- * with a `Component`/`Script` member.
3216
+ * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like, collides
3217
+ * with a `Component`/`Script` member, or names an `Object.prototype` member such as `constructor`.
3185
3218
  *
3186
3219
  * @example
3187
3220
  * ```ts
@@ -3286,7 +3319,9 @@ var ComponentRegistry = class {
3286
3319
  * an id is kept, and {@link ComponentRegistry.registrarOf} reports it.
3287
3320
  * @returns What the registry worked out about the class.
3288
3321
  * @throws IgnifxError with code `IGX-0203` when the id is already registered by another class, or
3289
- * when the id is not `<namespace>/<Name>`.
3322
+ * when the id is not `<namespace>/<Name>`, `IGX-0209` when the class's `static requires`
3323
+ * graph contains a cycle, and `IGX-0607` when its `static schema` names a field after an
3324
+ * `Object.prototype` member.
3290
3325
  */
3291
3326
  register(type, typeId, registrar) {
3292
3327
  const id = typeId ?? readStatics$1(type).typeId ?? null;
@@ -3303,8 +3338,10 @@ var ComponentRegistry = class {
3303
3338
  typeId: id,
3304
3339
  owner: existing.prototype.constructor.name
3305
3340
  } });
3341
+ const info = this.describe(type);
3306
3342
  this.#byTypeId.set(id, type);
3307
3343
  if (registrar !== void 0 && !this.#registrars.has(id)) this.#registrars.set(id, registrar);
3344
+ return info;
3308
3345
  }
3309
3346
  return this.describe(type);
3310
3347
  }
@@ -3349,7 +3386,10 @@ var ComponentRegistry = class {
3349
3386
  *
3350
3387
  * @param type - The replacement class. It must declare the `typeId` it replaces.
3351
3388
  * @returns The freshly built info for the replacement, and the class it replaced.
3352
- * @throws IgnifxError with code `IGX-0204` when the replacement declares no `typeId`.
3389
+ * @throws IgnifxError with code `IGX-0204` when the replacement declares no `typeId`,
3390
+ * `IGX-0209` when its `static requires` graph contains a cycle, and `IGX-0607` when its
3391
+ * `static schema` names a field after an `Object.prototype` member; in every case the registry is
3392
+ * left unchanged.
3353
3393
  *
3354
3394
  * @example
3355
3395
  * ```ts
@@ -3363,6 +3403,8 @@ var ComponentRegistry = class {
3363
3403
  previous,
3364
3404
  info: this.describe(type)
3365
3405
  };
3406
+ assertNoRequiresCycle(type);
3407
+ assertSchemaFieldNames(type);
3366
3408
  const inherited = previous === null ? null : this.#info.get(previous)?.classIndex ?? null;
3367
3409
  if (previous !== null) this.#info.delete(previous);
3368
3410
  this.#byTypeId.set(id, type);
@@ -3381,10 +3423,14 @@ var ComponentRegistry = class {
3381
3423
  *
3382
3424
  * @param type - The component class.
3383
3425
  * @returns The cached class info.
3426
+ * @throws IgnifxError with code `IGX-0209` when the class's `static requires` graph contains a
3427
+ * cycle, and `IGX-0607` when its `static schema` names a field after an `Object.prototype` member.
3384
3428
  */
3385
3429
  describe(type) {
3386
3430
  const cached = this.#info.get(type);
3387
3431
  if (cached !== void 0) return cached;
3432
+ assertNoRequiresCycle(type);
3433
+ assertSchemaFieldNames(type);
3388
3434
  const info = this.#build(type);
3389
3435
  this.#info.set(type, info);
3390
3436
  return info;
@@ -3479,7 +3525,7 @@ var ComponentRegistry = class {
3479
3525
  type,
3480
3526
  typeId: statics.typeId ?? null,
3481
3527
  schema,
3482
- requires: statics.requires ?? EMPTY_TYPES,
3528
+ requires: statics.requires === void 0 ? EMPTY_TYPES : Object.freeze([...statics.requires]),
3483
3529
  allowMultiple: statics.allowMultiple ?? true,
3484
3530
  ancestors,
3485
3531
  trackedFields: schema === null ? EMPTY_NAMES : collectTrackedFields(schema),
@@ -3489,6 +3535,55 @@ var ComponentRegistry = class {
3489
3535
  };
3490
3536
  }
3491
3537
  };
3538
+ /**
3539
+ * Refuses a class whose `static schema` names a field after an `Object.prototype` member.
3540
+ * `Component.define` and `Script.define` check this already; a hand-written `static schema` skips
3541
+ * them, so the registry checks every class it describes.
3542
+ *
3543
+ * @param type - The class being described.
3544
+ * @throws IgnifxError with code `IGX-0607` when a field is named `constructor`, `__proto__`, or
3545
+ * another inherited member.
3546
+ */
3547
+ function assertSchemaFieldNames(type) {
3548
+ const schema = readStatics$1(type).schema;
3549
+ if (schema !== void 0) assertNoInheritedFieldNames(schema, "schema");
3550
+ }
3551
+ /**
3552
+ * Refuses a class whose `static requires` graph contains a cycle — through the class itself or
3553
+ * through any class it reaches. `addComponent` adds each missing
3554
+ * required class before the requiring one, so a cycle — a self-require, or A requiring B requiring
3555
+ * A — would otherwise recurse until the stack overflows on the first `addComponent`.
3556
+ *
3557
+ * @param type - The class being described.
3558
+ * @throws IgnifxError with code `IGX-0209` when a cycle is reachable from the class.
3559
+ */
3560
+ function assertNoRequiresCycle(type) {
3561
+ const finished = /* @__PURE__ */ new Set();
3562
+ const path = [];
3563
+ const visit = (current) => {
3564
+ const at = path.indexOf(current);
3565
+ if (at >= 0) {
3566
+ const cycle = [...path.slice(at), current].map((entry) => entry.prototype.constructor.name).join(" -> ");
3567
+ throw new IgnifxError(CoreErrorCode.requiresCycle, `${type.prototype.constructor.name} has a static requires cycle: ${cycle}.`, {
3568
+ context: {
3569
+ component: type.prototype.constructor.name,
3570
+ cycle
3571
+ },
3572
+ hint: "Remove a class from one of the `static requires` lists so the chain never loops back; shared requirements are fine."
3573
+ });
3574
+ }
3575
+ if (finished.has(current)) return;
3576
+ const requires = readStatics$1(current).requires ?? EMPTY_TYPES;
3577
+ path.push(current);
3578
+ for (let index = 0; index < requires.length; index += 1) {
3579
+ const required = requires[index];
3580
+ if (required !== void 0) visit(required);
3581
+ }
3582
+ path.pop();
3583
+ finished.add(current);
3584
+ };
3585
+ visit(type);
3586
+ }
3492
3587
  /** Shared empty lists so the common case allocates nothing. */
3493
3588
  const EMPTY_TYPES = Object.freeze([]);
3494
3589
  /** Shared empty name list. */
@@ -4704,7 +4799,7 @@ function createServiceKey(name) {
4704
4799
  *
4705
4800
  * @public
4706
4801
  */
4707
- const VERSION = "0.10.0";
4802
+ const VERSION = "0.12.0";
4708
4803
  //#endregion
4709
4804
  //#region src/assets/delivery-system.ts
4710
4805
  /**
@@ -5860,6 +5955,8 @@ function array(item, defaultValue = [], options) {
5860
5955
  * @param fields - The sub-fields.
5861
5956
  * @param options - Inspector and serializer metadata.
5862
5957
  * @returns The field definition.
5958
+ * @throws IgnifxError with code `IGX-0607` when a sub-field name is an `Object.prototype` member
5959
+ * such as `__proto__`, `constructor`, or `toString`.
5863
5960
  *
5864
5961
  * @example
5865
5962
  * ```ts
@@ -5869,6 +5966,7 @@ function array(item, defaultValue = [], options) {
5869
5966
  * @public
5870
5967
  */
5871
5968
  function record(fields, options) {
5969
+ assertNoInheritedFieldNames(fields, "record");
5872
5970
  return field({
5873
5971
  kind: FieldKind.record,
5874
5972
  fields
@@ -7066,7 +7164,7 @@ let surfaceLayer = null;
7066
7164
  * @internal
7067
7165
  */
7068
7166
  async function loadShaderSupport() {
7069
- const loaded = shaderLayer ?? await import("./shader-material-C4VjLTfV.js").then((n) => n.n);
7167
+ const loaded = shaderLayer ?? await import("./shader-material-DRZmqA_S.js").then((n) => n.n);
7070
7168
  shaderLayer = loaded;
7071
7169
  await loaded.loadShaderMaterialAdapter();
7072
7170
  return loaded;
@@ -7089,7 +7187,7 @@ function shaderSupport() {
7089
7187
  * @internal
7090
7188
  */
7091
7189
  async function loadSurfaceShaderSupport() {
7092
- const loaded = surfaceLayer ?? await import("./surface-shader-BaR7Kg-F.js");
7190
+ const loaded = surfaceLayer ?? await import("./surface-shader-BgZchRBe.js");
7093
7191
  surfaceLayer = loaded;
7094
7192
  return loaded;
7095
7193
  }
@@ -7609,7 +7707,7 @@ function resolveSurfaceShaders(app, references) {
7609
7707
  const textures = {};
7610
7708
  for (const name of Object.keys(reference.textures)) {
7611
7709
  const handle = app.assets.get(reference.textures[name] ?? "");
7612
- if (handle !== null && handle.state === "loaded") textures[name] = handle;
7710
+ if (handle !== null && handle.state === "loaded") setOwnJsonProperty(textures, name, handle);
7613
7711
  }
7614
7712
  inits.push({
7615
7713
  shader,
@@ -10609,6 +10707,13 @@ var RendererImpl = class {
10609
10707
  #resolutionScale = 1;
10610
10708
  #pixelRatio;
10611
10709
  #profileTasks = false;
10710
+ #animateMaterialsInEditMode = true;
10711
+ /** The shader clock `ShaderUniformSystem` accumulates, which edit mode's post effects read too. */
10712
+ #shaderClock = {
10713
+ time: 0,
10714
+ unscaledTime: 0,
10715
+ deltaTime: 0
10716
+ };
10612
10717
  #isSceneRegistered = false;
10613
10718
  #isLoopRunning = false;
10614
10719
  #isDisposed = false;
@@ -10787,6 +10892,55 @@ var RendererImpl = class {
10787
10892
  else disableGpuTiming(this.engine);
10788
10893
  }
10789
10894
  /**
10895
+ * Whether the shader clock runs in an edit-mode app.
10896
+ *
10897
+ * @returns `true` unless an editor turned material animation off.
10898
+ */
10899
+ get animateMaterialsInEditMode() {
10900
+ return this.#animateMaterialsInEditMode;
10901
+ }
10902
+ set animateMaterialsInEditMode(value) {
10903
+ this.#animateMaterialsInEditMode = value;
10904
+ }
10905
+ /**
10906
+ * Records this frame's shader clock, as `ShaderUniformSystem` accumulated it: the one clock both
10907
+ * shader materials and, in edit mode, custom post effects read.
10908
+ *
10909
+ * @param time - Scaled seconds the clock has run.
10910
+ * @param unscaledTime - Unscaled seconds the clock has run.
10911
+ * @param deltaTime - This frame's step; `0` while the clock is held.
10912
+ *
10913
+ * @internal
10914
+ */
10915
+ setShaderClock(time, unscaledTime, deltaTime) {
10916
+ this.#shaderClock.time = time;
10917
+ this.#shaderClock.unscaledTime = unscaledTime;
10918
+ this.#shaderClock.deltaTime = deltaTime;
10919
+ }
10920
+ /**
10921
+ * Whether the shader clock stands still this frame because an edit-mode app turned material
10922
+ * animation off. `app.pause()` is checked separately, by each reader.
10923
+ *
10924
+ * @returns `true` while the editor's toggle holds the clock.
10925
+ *
10926
+ * @internal
10927
+ */
10928
+ get isShaderClockHeld() {
10929
+ return this.#app.isEditMode && !this.#animateMaterialsInEditMode;
10930
+ }
10931
+ /**
10932
+ * The clock custom post effects upload. In an edit-mode app it is the shader clock materials read
10933
+ * (`setShaderClock`), so the two never drift apart when the editor holds and resumes it
10934
+ * (ADR-0028, amendment of 2026-10-20). A game keeps the app's own clock.
10935
+ *
10936
+ * @returns The clock.
10937
+ *
10938
+ * @internal
10939
+ */
10940
+ get effectClock() {
10941
+ return this.#app.isEditMode ? this.#shaderClock : this.#app.time;
10942
+ }
10943
+ /**
10790
10944
  * GPU draw calls in the last rendered frame.
10791
10945
  *
10792
10946
  * @returns The count; `0` under a headless app.
@@ -13278,7 +13432,7 @@ function shaderMaterialDefinition(input) {
13278
13432
  const declared = input.textures ?? {};
13279
13433
  for (const name of Object.keys(declared)) {
13280
13434
  const bound = declared[name];
13281
- if (bound !== void 0) textures[name] = typeof bound === "string" ? bound : bound.address;
13435
+ if (bound !== void 0) setOwnJsonProperty(textures, name, typeof bound === "string" ? bound : bound.address);
13282
13436
  }
13283
13437
  return {
13284
13438
  kind: "shader",
@@ -13643,7 +13797,7 @@ async function loadSurfaceShaders(ctx, references) {
13643
13797
  for (let index = 0; index < names.length; index += 1) {
13644
13798
  const handle = resolved.handles[index];
13645
13799
  const name = names[index];
13646
- if (handle !== void 0 && name !== void 0) textures[name] = handle;
13800
+ if (handle !== void 0 && name !== void 0) setOwnJsonProperty(textures, name, handle);
13647
13801
  }
13648
13802
  return {
13649
13803
  shader,
@@ -13779,12 +13933,12 @@ function readTextureRecord(file) {
13779
13933
  for (const name of Object.keys(entries)) {
13780
13934
  const value = entries[name];
13781
13935
  if (typeof value === "string" && value !== "") {
13782
- record[name] = value;
13936
+ setOwnJsonProperty(record, name, value);
13783
13937
  continue;
13784
13938
  }
13785
13939
  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
13786
13940
  const address = value["$asset"];
13787
- if (typeof address === "string" && address !== "") record[name] = address;
13941
+ if (typeof address === "string" && address !== "") setOwnJsonProperty(record, name, address);
13788
13942
  }
13789
13943
  }
13790
13944
  return record;
@@ -13816,7 +13970,7 @@ async function loadNamedTextures(ctx, requested) {
13816
13970
  const name = names[index];
13817
13971
  const address = name === void 0 ? void 0 : requested[name];
13818
13972
  if (handle === null || handle === void 0 || name === void 0 || address === void 0) continue;
13819
- addresses[name] = address;
13973
+ setOwnJsonProperty(addresses, name, address);
13820
13974
  handles.push(handle);
13821
13975
  }
13822
13976
  return {
@@ -13839,13 +13993,13 @@ function readValues(file) {
13839
13993
  for (const name of Object.keys(entries)) {
13840
13994
  const value = entries[name];
13841
13995
  if (typeof value === "number" && Number.isFinite(value)) {
13842
- values[name] = value;
13996
+ setOwnJsonProperty(values, name, value);
13843
13997
  continue;
13844
13998
  }
13845
13999
  if (Array.isArray(value)) {
13846
14000
  const numbers = [];
13847
14001
  for (const element of value) numbers.push(typeof element === "number" && Number.isFinite(element) ? element : 0);
13848
- values[name] = numbers;
14002
+ setOwnJsonProperty(values, name, numbers);
13849
14003
  }
13850
14004
  }
13851
14005
  return values;
@@ -13863,7 +14017,7 @@ function readDefines(file) {
13863
14017
  const entries = declared;
13864
14018
  for (const name of Object.keys(entries)) {
13865
14019
  const value = entries[name];
13866
- if (typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) defines[name] = value;
14020
+ if (typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) setOwnJsonProperty(defines, name, value);
13867
14021
  }
13868
14022
  return defines;
13869
14023
  }
@@ -14280,6 +14434,128 @@ function collectNames(node, out) {
14280
14434
  if (child !== void 0) collectNames(child, out);
14281
14435
  }
14282
14436
  }
14437
+ /**
14438
+ * The file name of the meshopt decoder script Lite injects.
14439
+ *
14440
+ * @internal
14441
+ */
14442
+ const MESHOPT_DECODER_FILE = "meshopt_decoder.js";
14443
+ /**
14444
+ * The transcoder modules `babylon.ktx2Decoder.js` fetches, as `[class, static property, file]`:
14445
+ * the class in the decoder's `KTX2DECODER` namespace whose property holds the URL, and the file
14446
+ * name it is served under. These are the defaults in `@babylonjs/ktx2decoder`'s
14447
+ * `Transcoders/*.js` and `zstddec.js`.
14448
+ *
14449
+ * @internal
14450
+ */
14451
+ const KTX2_TRANSCODER_FILES = [
14452
+ [
14453
+ "MSCTranscoder",
14454
+ "JSModuleURL",
14455
+ "msc_basis_transcoder.js"
14456
+ ],
14457
+ [
14458
+ "MSCTranscoder",
14459
+ "WasmModuleURL",
14460
+ "msc_basis_transcoder.wasm"
14461
+ ],
14462
+ [
14463
+ "ZSTDDecoder",
14464
+ "WasmModuleURL",
14465
+ "zstddec.wasm"
14466
+ ],
14467
+ [
14468
+ "LiteTranscoder_UASTC_ASTC",
14469
+ "WasmModuleURL",
14470
+ "uastc_astc.wasm"
14471
+ ],
14472
+ [
14473
+ "LiteTranscoder_UASTC_BC7",
14474
+ "WasmModuleURL",
14475
+ "uastc_bc7.wasm"
14476
+ ],
14477
+ [
14478
+ "LiteTranscoder_UASTC_R8_UNORM",
14479
+ "WasmModuleURL",
14480
+ "uastc_r8_unorm.wasm"
14481
+ ],
14482
+ [
14483
+ "LiteTranscoder_UASTC_RG8_UNORM",
14484
+ "WasmModuleURL",
14485
+ "uastc_rg8_unorm.wasm"
14486
+ ],
14487
+ [
14488
+ "LiteTranscoder_UASTC_RGBA_SRGB",
14489
+ "WasmModuleURL",
14490
+ "uastc_rgba8_srgb_v2.wasm"
14491
+ ],
14492
+ [
14493
+ "LiteTranscoder_UASTC_RGBA_UNORM",
14494
+ "WasmModuleURL",
14495
+ "uastc_rgba8_unorm_v2.wasm"
14496
+ ]
14497
+ ];
14498
+ /**
14499
+ * Reads the decoder locations a manifest records.
14500
+ *
14501
+ * @remarks
14502
+ * The transcoders are only worth overriding together with the decoder script that reads them, so
14503
+ * they are ignored when the manifest has no `babylon.ktx2Decoder.js`. Lite takes the meshopt
14504
+ * decoder's **directory**, so its entry is used only when its URL ends in the file name.
14505
+ *
14506
+ * @param manifest - The asset manifest.
14507
+ * @returns The locations; a `null` field means the manifest does not list that decoder.
14508
+ *
14509
+ * @example
14510
+ * ```ts
14511
+ * decoderUrlsFromManifest(app.assets.manifest).ktx2Decoder; // "/assets/babylon.ktx2Decoder.js"
14512
+ * ```
14513
+ *
14514
+ * @internal
14515
+ */
14516
+ function decoderUrlsFromManifest(manifest) {
14517
+ const urls = /* @__PURE__ */ new Map();
14518
+ for (const entry of manifest.entries) urls.set(entry.address, entry.url);
14519
+ const ktx2Decoder = urls.get("babylon.ktx2Decoder.js") ?? null;
14520
+ const ktx2Transcoders = {};
14521
+ if (ktx2Decoder !== null) for (const [name, property, file] of KTX2_TRANSCODER_FILES) {
14522
+ const url = urls.get(file);
14523
+ if (url !== void 0) ktx2Transcoders[name] = {
14524
+ ...ktx2Transcoders[name],
14525
+ [property]: url
14526
+ };
14527
+ }
14528
+ const meshoptUrl = urls.get(MESHOPT_DECODER_FILE);
14529
+ return {
14530
+ ktx2Decoder,
14531
+ ktx2Transcoders,
14532
+ meshoptBaseUrl: meshoptUrl?.endsWith("meshopt_decoder.js") === true ? meshoptUrl.slice(0, meshoptUrl.length - 18) : null
14533
+ };
14534
+ }
14535
+ /** What {@link configureDecoders} last handed Lite, so an unchanged manifest costs one comparison. */
14536
+ let appliedKey = null;
14537
+ /**
14538
+ * Points Lite at the decoders the app's manifest lists, before a load that may need one.
14539
+ *
14540
+ * @remarks
14541
+ * Lite's decoder locations are process-wide, so two apps on one page with different manifests share
14542
+ * the last one applied. Lite loads the KTX2 decoder once and keeps it, so this has to run before the
14543
+ * first KTX2 texture — the texture and model loaders call it at the start of every load, and a call
14544
+ * whose manifest has not changed does nothing.
14545
+ *
14546
+ * @param app - The app whose manifest to read.
14547
+ * @returns Once Lite has been told; immediately when the manifest lists no decoder.
14548
+ *
14549
+ * @internal
14550
+ */
14551
+ async function configureDecoders(app) {
14552
+ const urls = decoderUrlsFromManifest(app.assets.manifest);
14553
+ if (urls.ktx2Decoder === null && urls.meshoptBaseUrl === null) return;
14554
+ const key = JSON.stringify(urls);
14555
+ if (key === appliedKey) return;
14556
+ (await import("./decoders-CHJ7vduE.js")).applyLiteDecoderUrls(urls);
14557
+ appliedKey = key;
14558
+ }
14283
14559
  //#endregion
14284
14560
  //#region src/render/model-asset.ts
14285
14561
  /**
@@ -14477,6 +14753,13 @@ function createModelAsset(address, container, scene) {
14477
14753
  * asset pipeline produces, and the fix — passing the URL through for that one shape — is a
14478
14754
  * three-line change whenever a project needs it.
14479
14755
  *
14756
+ * ## Decoders
14757
+ *
14758
+ * A glTF may need one of Lite's run-time decoders: `KHR_texture_basisu` images go through the KTX2
14759
+ * decoder and `EXT_meshopt_compression` buffers through the meshopt decoder. Both load from
14760
+ * `cdn.babylonjs.com` unless told otherwise, so the loader calls `configureDecoders` first, which
14761
+ * points Lite at the copies `@ignifx/vite-plugin` serves (`../decoder-urls.ts`).
14762
+ *
14480
14763
  * ## Headless
14481
14764
  *
14482
14765
  * `loadGltf` throws a `TypeError` under the null engine: it uploads while parsing and reaches for
@@ -14504,6 +14787,7 @@ function createModelLoader() {
14504
14787
  async load(ctx) {
14505
14788
  const bytes = await ctx.fetchBytes();
14506
14789
  if (ctx.app.isHeadless) return createModelAsset(ctx.address, null, null);
14790
+ await configureDecoders(ctx.app);
14507
14791
  const container = await loadGltfFromBytes(ctx.lite.engine, bytes);
14508
14792
  return createModelAsset(ctx.address, container, ctx.app.lite.scene);
14509
14793
  },
@@ -14526,7 +14810,7 @@ let effectLayer = null;
14526
14810
  * @internal
14527
14811
  */
14528
14812
  async function loadPostEffectSupport() {
14529
- const [compiler, effects] = await Promise.all([compilerLayer ?? import("./post-effect-compiler-pOvXae-i.js"), effectLayer ?? import("./effect-task-CMbuO6Kb.js")]);
14813
+ const [compiler, effects] = await Promise.all([compilerLayer ?? import("./post-effect-compiler-Dw6zW2cG.js"), effectLayer ?? import("./effect-task-CMbuO6Kb.js")]);
14530
14814
  compilerLayer = compiler;
14531
14815
  effectLayer = effects;
14532
14816
  }
@@ -14664,7 +14948,7 @@ function createShaderLoader() {
14664
14948
  type: SHADER_ASSET_TYPE,
14665
14949
  extensions: SHADER_FILE_EXTENSIONS,
14666
14950
  async load(ctx) {
14667
- const [source, pragma] = await Promise.all([ctx.fetchText(), import("./shader-pragma-qO9_6sTd.js")]);
14951
+ const [source, pragma] = await Promise.all([ctx.fetchText(), import("./shader-pragma-DrFm5f5m.js")]);
14668
14952
  const declaration = pragma.parseShaderDeclaration(source, ctx.address);
14669
14953
  await loadShaderSupport();
14670
14954
  if (declaration.kind === "surface") await loadSurfaceShaderSupport();
@@ -14694,6 +14978,50 @@ function loadTexture(engine, url, options) {
14694
14978
  return loadTexture2D(engine, url, options);
14695
14979
  }
14696
14980
  /**
14981
+ * Loads a KTX2 (Basis Universal) texture from a URL, transcoded to the device's best compressed
14982
+ * format.
14983
+ *
14984
+ * @remarks
14985
+ * Lite's KTX2 glue is imported on first use (`./decoders.ts`), so a game that never loads a `.ktx2`
14986
+ * does not carry it. The decoder script and its transcoders load from wherever
14987
+ * `applyLiteDecoderUrls` last pointed Lite, or from `cdn.babylonjs.com` when nothing did. Sampler and
14988
+ * sRGB options apply; `mipMaps`, `invertY` and `premultiplyAlpha` do not — the file's rows and mips
14989
+ * are uploaded as stored (`./decoders.ts` explains the orientation).
14990
+ *
14991
+ * @param engine - The engine that owns the GPU texture.
14992
+ * @param url - Where to fetch it from.
14993
+ * @param options - Colour space and sampler.
14994
+ * @returns The texture. Its reference count starts at an implicit one.
14995
+ *
14996
+ * @example
14997
+ * ```ts
14998
+ * const albedo = await loadKtx2Texture(engine, "textures/hero-albedo.ktx2", { srgb: true });
14999
+ * ```
15000
+ *
15001
+ * @internal
15002
+ */
15003
+ async function loadKtx2Texture(engine, url, options = {}) {
15004
+ return (await import("./decoders-CHJ7vduE.js")).loadKtx2TextureWithOptions(engine, url, options);
15005
+ }
15006
+ /**
15007
+ * Loads a Basis Universal (`.basis`) texture from a URL.
15008
+ *
15009
+ * @remarks
15010
+ * Babylon Lite 1.34 always fetches the Basis transcoder from `cdn.babylonjs.com` and offers no
15011
+ * setter for it, so this works only where the page may load scripts from that origin. Prefer
15012
+ * `.ktx2`, which carries the same Basis payloads and whose decoder is served locally.
15013
+ *
15014
+ * @param engine - The engine that owns the GPU texture.
15015
+ * @param url - Where to fetch it from.
15016
+ * @param options - Colour space and sampler.
15017
+ * @returns The texture.
15018
+ *
15019
+ * @internal
15020
+ */
15021
+ async function loadBasisTexture(engine, url, options = {}) {
15022
+ return (await import("./decoders-CHJ7vduE.js")).loadBasisTextureWithOptions(engine, url, options);
15023
+ }
15024
+ /**
14697
15025
  * Creates a 2D texture from tightly packed RGBA8 bytes.
14698
15026
  *
14699
15027
  * @param engine - The engine that owns the GPU texture.
@@ -15241,6 +15569,17 @@ function readString$1(block, key, fallback) {
15241
15569
  * one place §5's "the three `fetch*` methods are the only network paths" does not hold; the
15242
15570
  * alternative is worse.
15243
15571
  *
15572
+ * ## The container picks the decoder
15573
+ *
15574
+ * `.png`, `.jpg`, `.jpeg` and `.webp` go to `loadTexture2D` and the browser's image decoder.
15575
+ * `.ktx2` goes to Lite's KTX2 loader and `.basis` to its Basis loader, which transcode to the
15576
+ * device's best compressed format (`src/lite/gpu/decoders.ts` lists the targets); handing either
15577
+ * to `createImageBitmap` fails with "The source image could not be decoded". The asset type stays
15578
+ * `texture` for all six, so the choice is made here, from the address's extension — the one name a
15579
+ * manifest entry, a hashed build URL and a hand-written `{ type: "texture" }` load all keep. Before
15580
+ * a KTX2 or Basis load, {@link configureDecoders} points Lite at the decoders the manifest lists,
15581
+ * which is how a built game avoids `cdn.babylonjs.com`.
15582
+ *
15244
15583
  * ## Options come from the sidecar
15245
15584
  *
15246
15585
  * `.meta.json` sidecars carry per-asset import options (§7), the build copies them into the
@@ -15274,7 +15613,9 @@ function createTextureLoader() {
15274
15613
  const options = readTextureImportOptions(ctx.meta);
15275
15614
  if (ctx.app.isHeadless) return new TextureAsset(ctx.address, null, options);
15276
15615
  ctx.reportProgress(0);
15277
- const texture = await loadTexture(ctx.lite.engine, ctx.url, toLiteTextureOptions(options));
15616
+ const container = textureContainerOf(ctx.address, ctx.url);
15617
+ if (container !== "image") await configureDecoders(ctx.app);
15618
+ const texture = await loadByContainer(container, ctx.lite.engine, ctx.url, toLiteTextureOptions(options));
15278
15619
  ctx.reportProgress(1);
15279
15620
  return new TextureAsset(ctx.address, texture, options);
15280
15621
  },
@@ -15283,6 +15624,57 @@ function createTextureLoader() {
15283
15624
  }
15284
15625
  };
15285
15626
  }
15627
+ /**
15628
+ * The lowercase extension of a path or URL, without its query or fragment.
15629
+ *
15630
+ * @param reference - An address or URL.
15631
+ * @returns The extension with its dot, or `""`.
15632
+ */
15633
+ function extensionOf(reference) {
15634
+ const path = reference.split(/[?#]/u, 1)[0] ?? "";
15635
+ const name = path.slice(path.lastIndexOf("/") + 1);
15636
+ const dot = name.lastIndexOf(".");
15637
+ return dot <= 0 ? "" : name.slice(dot).toLowerCase();
15638
+ }
15639
+ /**
15640
+ * Decides which Lite loader a texture needs.
15641
+ *
15642
+ * @remarks
15643
+ * The address decides; the URL is consulted only when the address has no extension, which happens
15644
+ * when a load passes `{ type: "texture" }` for an address the manifest maps to a file. Anything that
15645
+ * is neither `.ktx2` nor `.basis` is an image for the browser to decode.
15646
+ *
15647
+ * @param address - The asset address.
15648
+ * @param url - The URL it resolved to.
15649
+ * @returns The container.
15650
+ *
15651
+ * @example
15652
+ * ```ts
15653
+ * textureContainerOf("textures/rock.ktx2", "/assets/textures/rock.3f2a1b9c.ktx2"); // "ktx2"
15654
+ * ```
15655
+ *
15656
+ * @internal
15657
+ */
15658
+ function textureContainerOf(address, url) {
15659
+ const extension = extensionOf(address) || extensionOf(url);
15660
+ if (extension === ".ktx2") return "ktx2";
15661
+ if (extension === ".basis") return "basis";
15662
+ return "image";
15663
+ }
15664
+ /**
15665
+ * Loads a texture with the Lite loader its container needs.
15666
+ *
15667
+ * @param container - What the file is.
15668
+ * @param engine - The engine that owns the GPU texture.
15669
+ * @param url - Where to fetch it from.
15670
+ * @param options - Lite's texture options, from the sidecar.
15671
+ * @returns The texture.
15672
+ */
15673
+ function loadByContainer(container, engine, url, options) {
15674
+ if (container === "ktx2") return loadKtx2Texture(engine, url, options);
15675
+ if (container === "basis") return loadBasisTexture(engine, url, options);
15676
+ return loadTexture(engine, url, options);
15677
+ }
15286
15678
  //#endregion
15287
15679
  //#region src/render/gpu/mesh-instance.ts
15288
15680
  /**
@@ -15506,6 +15898,11 @@ function asMesh(node) {
15506
15898
  * flag flips. That is `07-rendering.md` §2.3's rule, and the browser test asserts both halves: the
15507
15899
  * pixel returns to the clear colour, and the mesh is still in the scene.
15508
15900
  *
15901
+ * `displayHidden` hides the same way, and makes the clone unpickable too, but is not a field: scene
15902
+ * files do not save it, so a system
15903
+ * that chooses what is drawn without changing the document (a `LodGroup` in an edit-mode app,
15904
+ * ADR-0028) switches it instead of `enabled`.
15905
+ *
15509
15906
  * ## Decisions the documents left open
15510
15907
  *
15511
15908
  * - **The clone's Lite `id` is the entity's uid.** Lite's light include/exclude lists match on
@@ -15549,6 +15946,7 @@ var MeshRenderer = class MeshRenderer extends Component {
15549
15946
  #instance = null;
15550
15947
  #appliedMesh = null;
15551
15948
  #appliedCastShadows = true;
15949
+ #displayHidden = false;
15552
15950
  /**
15553
15951
  * The Babylon Lite mesh this renderer draws. Unstable escape hatch
15554
15952
  * (`docs/architecture/00-overview.md` §3).
@@ -15559,8 +15957,45 @@ var MeshRenderer = class MeshRenderer extends Component {
15559
15957
  return { mesh: this.#instance?.clone ?? null };
15560
15958
  }
15561
15959
  /**
15960
+ * A display-only hide: while `true` the mesh is neither drawn nor picked, whatever `enabled` and
15961
+ * `pickable` say.
15962
+ *
15963
+ * @remarks
15964
+ * It is not a schema field, so scene files do not save it, a serializer never reads it, and
15965
+ * `enabled` keeps its authored value. That makes it the switch for a system that chooses what is
15966
+ * drawn without changing the document: `@ignifx/3d`'s `LodGroup` uses it in place of `enabled` in
15967
+ * an edit-mode app (ADR-0028). It starts `false` and takes effect at the next render sync;
15968
+ * {@link MeshRenderer.isVisible} reports the outcome. Lite's pickers ignore visibility, so the
15969
+ * clone is also made unpickable while hidden: `app.renderer.pickAsync` and `world.raycastRender`
15970
+ * neither return it nor let it occlude, as with `pickable: false`.
15971
+ *
15972
+ * It is one flag with one owner, not a count. In an edit-mode app the `LodGroup` that lists the
15973
+ * renderer as a level owns it: the group sets and clears it whenever it switches, so a value
15974
+ * written by anything else lasts only until then. A renderer belongs to at most one `LodGroup`; a
15975
+ * second group that lists it leaves it alone and warns with `IGX-1217`.
15976
+ *
15977
+ * @returns `true` while the mesh is hidden for display.
15978
+ *
15979
+ * @example
15980
+ * ```ts
15981
+ * renderer.displayHidden = true; // not drawn, and `renderer.enabled` is still `true`
15982
+ * ```
15983
+ */
15984
+ get displayHidden() {
15985
+ return this.#displayHidden;
15986
+ }
15987
+ /**
15988
+ * Hides the mesh for display, or shows it again; `enabled` is not touched.
15989
+ *
15990
+ * @param value - `true` to hide it.
15991
+ */
15992
+ set displayHidden(value) {
15993
+ this.#displayHidden = value;
15994
+ }
15995
+ /**
15562
15996
  * Whether the mesh is currently drawn: its own `enabled` flag and its entity's
15563
- * `activeInHierarchy`, materialised onto Lite's `visible`.
15997
+ * `activeInHierarchy`, less {@link MeshRenderer.displayHidden}, materialised onto Lite's
15998
+ * `visible`.
15564
15999
  *
15565
16000
  * @returns `true` when the clone is visible.
15566
16001
  */
@@ -15591,8 +16026,8 @@ var MeshRenderer = class MeshRenderer extends Component {
15591
16026
  if (instance === null) return changed;
15592
16027
  instance.applyMaterial(this.#material(renderer));
15593
16028
  instance.applyDisplacement(this.#displacement(), this.entity.transform);
15594
- instance.applyFlags(this.receiveShadows, this.renderOrder, this.pickable);
15595
- instance.applyVisible(this.isEnabledInHierarchy);
16029
+ instance.applyFlags(this.receiveShadows, this.renderOrder, this.pickable && !this.#displayHidden);
16030
+ instance.applyVisible(this.isEnabledInHierarchy && !this.#displayHidden);
15596
16031
  return changed;
15597
16032
  }
15598
16033
  /**
@@ -16894,7 +17329,7 @@ var PostProcessStack = class PostProcessStack extends Component {
16894
17329
  }
16895
17330
  if (!this.#hasWarnedAboutFeature && !renderer.features.postProcessing) this.#warnAboutFeature(renderer, this.plannedChain().length);
16896
17331
  const surface = renderer.surface;
16897
- applyPostProcessSettings(this.#chain, this.isEnabledInHierarchy, this.bloom, this.smaa, renderer.app.time, surface?.width ?? 0, surface?.height ?? 0, renderer.isSceneRegistered);
17332
+ applyPostProcessSettings(this.#chain, this.isEnabledInHierarchy, this.bloom, this.smaa, renderer.effectClock, surface?.width ?? 0, surface?.height ?? 0, renderer.isSceneRegistered);
16898
17333
  }
16899
17334
  /**
16900
17335
  * Replaces the chain with one that holds the effects the fields currently ask for.
@@ -17610,8 +18045,10 @@ var RenderSyncSystem = class {
17610
18045
  * The clock is accumulated here rather than read from `app.time.time` because a system keeps running
17611
18046
  * with a non-zero `dt` while the app is paused and has to check `time.paused` itself
17612
18047
  * (`docs/architecture/01-lifecycle-and-time.md` §7); that is what freezes `time` under
17613
- * `app.pause()` and resumes it without a jump. A held clock (`ctx.isClockHeld`, edit mode) freezes
17614
- * it the same way.
18048
+ * `app.pause()` and resumes it without a jump. In an edit-mode app the system runs, so materials
18049
+ * animate as an editor previews them, and `app.renderer.animateMaterialsInEditMode = false` freezes
18050
+ * the clock the same way (ADR-0028, amendment of 2026-10-20). A held clock (`ctx.isClockHeld`, for a
18051
+ * registration that asks for `"hold"`) would too.
17615
18052
  */
17616
18053
  /**
17617
18054
  * Where the shader uniform writer sits inside `PreRender`: just before the render sync
@@ -17665,18 +18102,20 @@ var ShaderUniformSystem = class {
17665
18102
  */
17666
18103
  update(ctx) {
17667
18104
  const time = ctx.time;
17668
- const isPaused = time.paused || ctx.isClockHeld;
18105
+ const renderer = rendererInternals(this.#app.renderer);
18106
+ const isPaused = time.paused || ctx.isClockHeld || renderer.isShaderClockHeld;
17669
18107
  if (!isPaused) {
17670
18108
  this.#time += time.deltaTime;
17671
18109
  this.#unscaledTime += time.unscaledDeltaTime;
17672
18110
  }
18111
+ const delta = isPaused ? 0 : time.deltaTime;
18112
+ renderer.setShaderClock(this.#time, this.#unscaledTime, delta);
17673
18113
  const support = shaderSupport();
17674
18114
  if (support === null) return;
17675
18115
  const materials = support.shaderMaterialsOf(this.#app).animated;
17676
18116
  if (materials.length === 0) return;
17677
18117
  const hasLight = this.#readMainLight(ctx.world);
17678
18118
  this.#readAmbient();
17679
- const delta = isPaused ? 0 : time.deltaTime;
17680
18119
  for (let index = 0; index < materials.length; index += 1) materials[index]?.writeFrameUniforms(this.#time, this.#unscaledTime, delta, this.#frame, hasLight);
17681
18120
  }
17682
18121
  /**
@@ -18276,7 +18715,7 @@ function encodeInto(field, value, references, path, issues) {
18276
18715
  case "map": {
18277
18716
  if (!isPlainObject(value)) return unrepresentable(issues, path, `expected an object, received ${typeof value}.`);
18278
18717
  const encoded = {};
18279
- for (const key of Object.keys(value).toSorted()) encoded[key] = encodeInto(spec.value, value[key], references, indexPath(path, key), issues);
18718
+ for (const key of Object.keys(value).toSorted()) setOwnJsonProperty(encoded, key, encodeInto(spec.value, value[key], references, indexPath(path, key), issues));
18280
18719
  return encoded;
18281
18720
  }
18282
18721
  case "optional": return value === null ? null : encodeInto(spec.inner, value, references, path, issues);
@@ -18435,7 +18874,7 @@ function decodeInto(field, json, references, path, issues) {
18435
18874
  case "map": {
18436
18875
  if (!isPlainObject(json)) return rejected(field, issues, path, `expected an object.`);
18437
18876
  const decoded = {};
18438
- for (const key of Object.keys(json).toSorted()) decoded[key] = decodeInto(spec.value, json[key] ?? null, references, indexPath(path, key), issues);
18877
+ for (const key of Object.keys(json).toSorted()) setOwnJsonProperty(decoded, key, decodeInto(spec.value, json[key] ?? null, references, indexPath(path, key), issues));
18439
18878
  return decoded;
18440
18879
  }
18441
18880
  case "optional": return json === null ? null : decodeInto(spec.inner, json, references, path, issues);
@@ -18804,7 +19243,7 @@ function schemaJsonSchema(schema) {
18804
19243
  * @param typeId - The component's namespaced registration id, for example `mygame/Mover`.
18805
19244
  * @param schema - The component's declared fields.
18806
19245
  * @param meta - Overrides for the title, format grouping, and summary, and the component's
18807
- * `allowMultiple`, `package` and `builtIn` when the caller knows them.
19246
+ * `allowMultiple`, `package`, `builtIn` and `requires` when the caller knows them.
18808
19247
  * @returns The description entry.
18809
19248
  *
18810
19249
  * @example
@@ -18825,7 +19264,8 @@ function describeSchema(typeId, schema, meta) {
18825
19264
  fields: describeFields(schema, noReferences()),
18826
19265
  ...meta?.allowMultiple === void 0 ? {} : { allowMultiple: meta.allowMultiple },
18827
19266
  ...meta?.package === void 0 ? {} : { package: meta.package },
18828
- ...meta?.builtIn === void 0 ? {} : { builtIn: meta.builtIn }
19267
+ ...meta?.builtIn === void 0 ? {} : { builtIn: meta.builtIn },
19268
+ ...meta?.requires === void 0 ? {} : { requires: meta.requires }
18829
19269
  };
18830
19270
  }
18831
19271
  /**
@@ -19390,6 +19830,10 @@ function toHex(bytes) {
19390
19830
  * (`CONSTITUTION.md` §2.3). The generated document remains the artefact the Vite plugin and editors
19391
19831
  * validate against; this is the same rule set, executable at load time.
19392
19832
  *
19833
+ * Two checks go beyond what JSON Schema can say: uids are unique within the file, and no two
19834
+ * overrides of one instance share an identity (path, `op`, and an added component's uid), both
19835
+ * reported as issues like any other.
19836
+ *
19393
19837
  * Component `props` are *not* checked here: `decodeProps` already reports every field problem with
19394
19838
  * a schema issue code, per field, which is more precise than a document-level match.
19395
19839
  *
@@ -19573,6 +20017,7 @@ function validateInstance(value, path, issues) {
19573
20017
  });
19574
20018
  return;
19575
20019
  }
20020
+ const identities = /* @__PURE__ */ new Map();
19576
20021
  for (let index = 0; index < overrides.length; index += 1) {
19577
20022
  const at = `${path}/overrides/${String(index)}`;
19578
20023
  const override = asRecord(overrides[index]);
@@ -19584,13 +20029,66 @@ function validateInstance(value, path, issues) {
19584
20029
  continue;
19585
20030
  }
19586
20031
  const op = override["op"];
19587
- if (op !== void 0 && op !== "replace" && op !== "remove" && op !== "add") issues.push({
19588
- path: `${at}/op`,
19589
- message: "expected \"replace\", \"remove\", or \"add\"."
19590
- });
20032
+ if (op !== void 0 && op !== "replace" && op !== "remove" && op !== "add") {
20033
+ issues.push({
20034
+ path: `${at}/op`,
20035
+ message: "expected \"replace\", \"remove\", or \"add\"."
20036
+ });
20037
+ continue;
20038
+ }
20039
+ checkOverrideIdentity(override["path"], op ?? "replace", override["value"], index, at, identities, issues);
19591
20040
  }
19592
20041
  }
19593
20042
  /**
20043
+ * Appends an issue when an override has the identity of an earlier override of the same instance.
20044
+ *
20045
+ * @remarks
20046
+ * An override's identity is its `path`, its `op` (`"replace"` when absent), and for an `add` to a
20047
+ * component list (`<uid>/components`) the uid of the component it adds — what the editor's ops
20048
+ * address an override by. The loader applies overrides in order, so of two with one identity the
20049
+ * first has no effect, and an editor that edits or removes "the" override at that identity reaches
20050
+ * only one of them. The engine's serializer never writes two; a hand edit or a merge conflict does.
20051
+ * Like a uid used twice, it is a file defect, refused rather than resolved.
20052
+ *
20053
+ * @param overridePath - The override's path.
20054
+ * @param op - Its op, defaulted.
20055
+ * @param value - Its value.
20056
+ * @param index - Its index in the list.
20057
+ * @param at - Its path in the file, for the issue.
20058
+ * @param identities - The identities already seen in the list, with the index of each.
20059
+ * @param issues - Where problems are appended.
20060
+ */
20061
+ function checkOverrideIdentity(overridePath, op, value, index, at, identities, issues) {
20062
+ const uid = asRecord(value)?.["uid"];
20063
+ const added = op === "add" && isComponentListPath(overridePath) && typeof uid === "string" ? uid : null;
20064
+ const identity = JSON.stringify([
20065
+ overridePath,
20066
+ op,
20067
+ added
20068
+ ]);
20069
+ const first = identities.get(identity);
20070
+ if (first === void 0) {
20071
+ identities.set(identity, index);
20072
+ return;
20073
+ }
20074
+ const what = added === null ? `"${op}" of "${overridePath}"` : `"add" of component ${added} to "${overridePath}"`;
20075
+ issues.push({
20076
+ path: at,
20077
+ message: `duplicates overrides/${String(first)}: both are the ${what}. An instance holds one override per path and op (a merge conflict can leave two); keep one.`
20078
+ });
20079
+ }
20080
+ /**
20081
+ * Whether an override path addresses an entity's component list (`<uid>/components`), the one kind
20082
+ * whose `add` overrides are told apart by the uid they add.
20083
+ *
20084
+ * @param overridePath - The path.
20085
+ * @returns True for `<uid>/components`.
20086
+ */
20087
+ function isComponentListPath(overridePath) {
20088
+ const segments = overridePath.split("/");
20089
+ return segments.length === 2 && segments[0] !== "" && segments[1] === "components";
20090
+ }
20091
+ /**
19594
20092
  * Validates a `transform` entry.
19595
20093
  *
19596
20094
  * @param value - The entry.
@@ -22620,8 +23118,7 @@ function registerRendering(ctx) {
22620
23118
  ctx.registerAssetLoader(createMeshLoader());
22621
23119
  ctx.registerSystem(new ShaderUniformSystem(ctx.app), {
22622
23120
  phase: Phase.PreRender,
22623
- order: SHADER_UNIFORM_ORDER,
22624
- editMode: "hold"
23121
+ order: SHADER_UNIFORM_ORDER
22625
23122
  });
22626
23123
  const sync = new RenderSyncSystem(renderer);
22627
23124
  renderer.attachSyncSystem(sync);
@@ -22905,7 +23402,8 @@ var ExtensionContextImpl = class {
22905
23402
  * @param schema - The schema the section is validated against.
22906
23403
  * @param defaults - The values used when the project omits the section.
22907
23404
  * @throws IgnifxError with code `IGX-0408` in development when the project's values do not
22908
- * validate against the schema.
23405
+ * validate against the schema, and with code `IGX-0607` when a field is named after an
23406
+ * `Object.prototype` member such as `constructor`.
22909
23407
  */
22910
23408
  registerSettings(section, schema, defaults) {
22911
23409
  this.#settings.register(section, schema, defaults, this.#extension.name);
@@ -23949,7 +24447,14 @@ var HotReloadHostImpl = class {
23949
24447
  for (let index = 0; index < plans.length; index += 1) {
23950
24448
  const plan = plans[index];
23951
24449
  if (plan === void 0) continue;
23952
- const info = world.registry.replace(plan.next).info;
24450
+ let info;
24451
+ try {
24452
+ info = world.registry.replace(plan.next).info;
24453
+ } catch (error) {
24454
+ errors.push(error);
24455
+ this.#report(error);
24456
+ continue;
24457
+ }
23953
24458
  instances += plan.policy === "patch" ? patchInstances(world, plan.previousInfo, info, plan.instances) : recreateInstances(world, plan.previousInfo, plan.next, info, plan.instances, (message) => {
23954
24459
  this.#log.warn(`hot reload: ${message}`);
23955
24460
  });
@@ -26317,9 +26822,10 @@ var SettingsStore = class {
26317
26822
  * @param defaults - The values used for everything the project omits, as a bag of named props.
26318
26823
  * @param owner - The extension registering the section, named in diagnostics.
26319
26824
  * @throws IgnifxError with code `IGX-0408` in development when the project's values do not
26320
- * validate.
26825
+ * validate, and with code `IGX-0607` when a field is named after an `Object.prototype` member.
26321
26826
  */
26322
26827
  register(name, schema, defaults, owner) {
26828
+ assertNoInheritedFieldNames(schema, "settings");
26323
26829
  const base = isPropertyBag(defaults) ? defaults : createDefaults(schema);
26324
26830
  const value = this.#resolve(name, schema, base);
26325
26831
  this.#sections.set(name, {
@@ -28878,7 +29384,8 @@ var Entity = class {
28878
29384
  * @returns The attached component.
28879
29385
  * @throws IgnifxError with code `IGX-0202` when the class does not allow multiple instances and
28880
29386
  * the entity already has one, `IGX-0605`/`IGX-0606`/`IGX-0607` when `init` does not match the
28881
- * schema, and `IGX-0101` when the entity has been destroyed.
29387
+ * schema, `IGX-0209` when the class's `static requires` graph contains a cycle, and `IGX-0101`
29388
+ * when the entity has been destroyed.
28882
29389
  */
28883
29390
  addComponent(type, init) {
28884
29391
  const internals = this.#mutable("addComponent");
@@ -30595,7 +31102,8 @@ const TRANSFORM_CHANNELS = Object.freeze([
30595
31102
  *
30596
31103
  * @param path - The `path` string from the file.
30597
31104
  * @returns The parsed path.
30598
- * @throws IgnifxError with code `IGX-0609` when the path does not match the grammar.
31105
+ * @throws IgnifxError with code `IGX-0609` when the path does not match the grammar, or when a
31106
+ * property step is `__proto__`.
30599
31107
  *
30600
31108
  * @example
30601
31109
  * ```ts
@@ -30651,11 +31159,13 @@ function parseOverridePath(path) {
30651
31159
  component
30652
31160
  };
30653
31161
  if (fourth !== "props" || segments.length < 5) throw invalidPath(path, "a property override is <uid>/components/<uid>/props/<field>.");
31162
+ const steps = segments.slice(4);
31163
+ if (steps.includes("__proto__")) throw invalidPath(path, "\"__proto__\" is not a property name an override may address.");
30654
31164
  return {
30655
31165
  kind: "prop",
30656
31166
  entity,
30657
31167
  component,
30658
- steps: segments.slice(4)
31168
+ steps
30659
31169
  };
30660
31170
  }
30661
31171
  /**
@@ -30832,18 +31342,18 @@ function writeStep(container, steps, at, op, value, path, report) {
30832
31342
  const { [key]: _removed, ...rest } = copy;
30833
31343
  return rest;
30834
31344
  }
30835
- copy[key] = value;
31345
+ setOwnJsonProperty(copy, key, value);
30836
31346
  return copy;
30837
31347
  }
30838
- const next = copy[key];
31348
+ const next = Object.hasOwn(copy, key) ? copy[key] : void 0;
30839
31349
  const nextArray = asJsonArray(next);
30840
31350
  if (nextArray !== null) {
30841
- copy[key] = writeArrayStep(nextArray, steps, at + 1, op, value, path, report);
31351
+ setOwnJsonProperty(copy, key, writeArrayStep(nextArray, steps, at + 1, op, value, path, report));
30842
31352
  return copy;
30843
31353
  }
30844
31354
  const nextObject = asJsonObject(next);
30845
31355
  if (nextObject !== null) {
30846
- copy[key] = writeStep(nextObject, steps, at + 1, op, value, path, report);
31356
+ setOwnJsonProperty(copy, key, writeStep(nextObject, steps, at + 1, op, value, path, report));
30847
31357
  return copy;
30848
31358
  }
30849
31359
  report(`"${path}" descends into ${key}, which is not an object or an array.`);
@@ -31298,7 +31808,7 @@ function remapValue(value, keys) {
31298
31808
  rewritten[key] = keys.get(entry) ?? entry;
31299
31809
  continue;
31300
31810
  }
31301
- rewritten[key] = remapValue(entry, keys);
31811
+ setOwnJsonProperty(rewritten, key, remapValue(entry, keys));
31302
31812
  }
31303
31813
  return rewritten;
31304
31814
  }
@@ -31413,14 +31923,15 @@ function noAssets() {
31413
31923
  * @param remap - The table filled while the scene was being constructed.
31414
31924
  * @param assets - How an asset address becomes a handle; defaults to resolving nothing, which makes
31415
31925
  * every `asset()` field `null` with an `IGX-0602` issue.
31926
+ * @param outside - How a uid the remap does not hold resolves; omitted, it resolves to `null`.
31416
31927
  * @returns The decoder to hand `decodeProps`.
31417
31928
  *
31418
31929
  * @internal
31419
31930
  */
31420
- function remapDecoder(remap, assets = noAssets) {
31931
+ function remapDecoder(remap, assets = noAssets, outside) {
31421
31932
  return {
31422
- entity: (uid) => remap.entity(uid),
31423
- component: (uid) => remap.component(uid),
31933
+ entity: (uid) => remap.entity(uid) ?? outside?.entity(uid) ?? null,
31934
+ component: (uid) => remap.component(uid) ?? outside?.component(uid) ?? null,
31424
31935
  asset: (address, type) => assets(address, type)
31425
31936
  };
31426
31937
  }
@@ -31527,7 +32038,7 @@ function instantiateScene(world, asset, options) {
31527
32038
  createEntities(context, expanded.entities, parent);
31528
32039
  attachComponents(context);
31529
32040
  linkInstances(context, options?.assetHandle ?? null, options?.rootEntity ?? null);
31530
- decodeAllProps(context, sceneAssetResolver(world, asset));
32041
+ decodeAllProps(context, sceneAssetResolver(world, asset), options?.outsideReferences);
31531
32042
  activate(context);
31532
32043
  return {
31533
32044
  roots: context.roots,
@@ -31586,6 +32097,12 @@ function createEntities(context, entities, parent) {
31586
32097
  * Pass 2: attaches every component with its schema defaults, so the reference table is complete
31587
32098
  * before any prop is decoded.
31588
32099
  *
32100
+ * @remarks
32101
+ * A file may list a component before one its class `requires` (an editor reorder does that).
32102
+ * `addComponent` would then add a second, fresh instance of the required class, or throw `IGX-0202`
32103
+ * when the file's own record comes. So a record that a class requires is attached first, and the
32104
+ * entity's components are put back in file order afterwards.
32105
+ *
31589
32106
  * @param context - The build state.
31590
32107
  * @throws IgnifxError with code `IGX-0307` when the file names an unregistered component type: the
31591
32108
  * file cannot be honoured with a component missing, so this one is not recoverable.
@@ -31593,25 +32110,83 @@ function createEntities(context, entities, parent) {
31593
32110
  function attachComponents(context) {
31594
32111
  for (let index = 0; index < context.built.length; index += 1) {
31595
32112
  const built = context.built[index];
31596
- if (built === void 0) continue;
31597
- const records = built.source.data.components;
31598
- for (let inner = 0; inner < records.length; inner += 1) {
31599
- const record = records[inner];
31600
- if (record === void 0) continue;
31601
- const type = context.world.registry.get(record.type);
31602
- if (type === null) throw new IgnifxError(CoreErrorCode.unknownComponentTypeId, `${record.type} is not a registered component type.`, {
31603
- context: {
31604
- typeId: record.type,
31605
- entity: built.source.data.uid
31606
- },
31607
- hint: "Register the class with app.registerComponents before loading a scene that uses it."
31608
- });
31609
- const component = built.entity.addComponent(type);
31610
- componentInternals(component).uid = record.uid;
31611
- if (record.enabled === false) component.enabled = false;
31612
- context.remap.addComponent(record.uid, component);
31613
- built.components.push(component);
31614
- }
32113
+ if (built !== void 0) attachEntityComponents(context, built);
32114
+ }
32115
+ }
32116
+ /**
32117
+ * Attaches one entity's component records, each record's required records first.
32118
+ *
32119
+ * @param context - The build state.
32120
+ * @param built - The entity and its file record.
32121
+ */
32122
+ function attachEntityComponents(context, built) {
32123
+ const registry = context.world.registry;
32124
+ const records = built.source.data.components;
32125
+ const types = records.map((record) => registeredType(context, record, built.source.data.uid));
32126
+ const attached = [];
32127
+ const started = /* @__PURE__ */ new Set();
32128
+ const order = [];
32129
+ const attach = (at) => {
32130
+ const record = records[at];
32131
+ const type = types[at];
32132
+ if (record === void 0 || type === void 0 || started.has(at)) return;
32133
+ started.add(at);
32134
+ const requires = registry.describe(type).requires;
32135
+ for (let inner = 0; inner < requires.length; inner += 1) {
32136
+ const required = requires[inner];
32137
+ if (required === void 0 || built.entity.getComponent(required) !== null) continue;
32138
+ const supplier = types.findIndex((candidate, other) => !started.has(other) && registry.describe(candidate).ancestors.includes(required));
32139
+ if (supplier >= 0) attach(supplier);
32140
+ }
32141
+ const component = built.entity.addComponent(type);
32142
+ componentInternals(component).uid = record.uid;
32143
+ if (record.enabled === false) component.enabled = false;
32144
+ context.remap.addComponent(record.uid, component);
32145
+ attached[at] = component;
32146
+ order.push(at);
32147
+ };
32148
+ for (let at = 0; at < records.length; at += 1) attach(at);
32149
+ for (let at = 0; at < attached.length; at += 1) {
32150
+ const component = attached[at];
32151
+ if (component !== void 0) built.components.push(component);
32152
+ }
32153
+ if (order.some((at, position) => at !== position)) restoreFileOrder(built.entity, built.components);
32154
+ }
32155
+ /**
32156
+ * Looks up a record's component class.
32157
+ *
32158
+ * @param context - The build state.
32159
+ * @param record - The component record.
32160
+ * @param entityUid - The owning entity's file uid, for the error.
32161
+ * @returns The registered class.
32162
+ * @throws IgnifxError with code `IGX-0307` when the type is not registered.
32163
+ */
32164
+ function registeredType(context, record, entityUid) {
32165
+ const type = context.world.registry.get(record.type);
32166
+ if (type === null) throw new IgnifxError(CoreErrorCode.unknownComponentTypeId, `${record.type} is not a registered component type.`, {
32167
+ context: {
32168
+ typeId: record.type,
32169
+ entity: entityUid
32170
+ },
32171
+ hint: "Register the class with app.registerComponents before loading a scene that uses it."
32172
+ });
32173
+ return type;
32174
+ }
32175
+ /**
32176
+ * Puts the file's components back in file order within the slots they occupy on the entity, so
32177
+ * `getComponent`, `awake` and a later save see the order the file wrote. Other components (the
32178
+ * transform, any auto-added one) keep their places.
32179
+ *
32180
+ * @param entity - The entity.
32181
+ * @param inFileOrder - The components the file listed, in file order.
32182
+ */
32183
+ function restoreFileOrder(entity, inFileOrder) {
32184
+ const list = entityInternals(entity).components;
32185
+ const slots = inFileOrder.map((component) => list.indexOf(component)).toSorted((a, b) => a - b);
32186
+ for (let at = 0; at < slots.length; at += 1) {
32187
+ const slot = slots[at];
32188
+ const component = inFileOrder[at];
32189
+ if (slot !== void 0 && component !== void 0) list[slot] = component;
31615
32190
  }
31616
32191
  }
31617
32192
  /**
@@ -31721,9 +32296,10 @@ function instancedRoot(context, instance, source) {
31721
32296
  *
31722
32297
  * @param context - The build state.
31723
32298
  * @param assets - How an `asset()` field's address becomes the handle the scene already retains.
32299
+ * @param outside - How a uid the build made nothing with resolves, if at all.
31724
32300
  */
31725
- function decodeAllProps(context, assets) {
31726
- const decoder = remapDecoder(context.remap, assets);
32301
+ function decodeAllProps(context, assets, outside) {
32302
+ const decoder = remapDecoder(context.remap, assets, outside);
31727
32303
  for (let index = 0; index < context.built.length; index += 1) {
31728
32304
  const built = context.built[index];
31729
32305
  if (built === void 0) continue;
@@ -35229,7 +35805,8 @@ function componentPackage(registry, typeId) {
35229
35805
  /**
35230
35806
  * Describes every component an app has registered, the engine's, its extensions' and the game's,
35231
35807
  * 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`).
35808
+ * entity may hold more than one (`allowMultiple`), which package registered it (`package`), and
35809
+ * which components it adds when they are missing (`requires`, its classes' type ids).
35233
35810
  * This is what an external inspector, such as the ignifx editor, is generated from.
35234
35811
  *
35235
35812
  * @remarks
@@ -35252,6 +35829,7 @@ function componentPackage(registry, typeId) {
35252
35829
  * const schemas = describeRegisteredSchemas(app.world.registry, describeSchemas());
35253
35830
  * schemas["ignifx/Camera"]?.package; // "@ignifx/core"
35254
35831
  * schemas["ignifx/Camera"]?.allowMultiple; // false
35832
+ * schemas["ignifx/ThirdPersonController"]?.requires; // ["ignifx/CharacterController"] once @ignifx/3d is registered
35255
35833
  * ```
35256
35834
  *
35257
35835
  * @public
@@ -35268,7 +35846,8 @@ function describeRegisteredSchemas(registry, curated) {
35268
35846
  ...meta?.description === void 0 ? {} : { description: meta.description },
35269
35847
  allowMultiple: info.allowMultiple,
35270
35848
  package: componentPackage(registry, typeId),
35271
- ...builtIn ? { builtIn } : {}
35849
+ ...builtIn ? { builtIn } : {},
35850
+ ...info.requires.length === 0 ? {} : { requires: info.requires.map((required) => required.typeId ?? null) }
35272
35851
  });
35273
35852
  }
35274
35853
  return described;
@@ -35417,7 +35996,7 @@ function entriesToJson(entries, convert) {
35417
35996
  const object = {};
35418
35997
  for (const [name, value] of entries) {
35419
35998
  const converted = convert(value, name);
35420
- if (converted !== void 0) object[name] = converted;
35999
+ if (converted !== void 0) setOwnJsonProperty(object, name, converted);
35421
36000
  }
35422
36001
  return object;
35423
36002
  }