@ignifx/core 0.11.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 (28) hide show
  1. package/dist/{environment-BCjfp1jB.js → environment-C9AjYJgV.js} +2 -2
  2. package/dist/{environment-BCjfp1jB.js.map → environment-C9AjYJgV.js.map} +1 -1
  3. package/dist/{ignifx-error-RpK-lWwE.js → ignifx-error-Dq2qJMkZ.js} +10 -3
  4. package/dist/ignifx-error-Dq2qJMkZ.js.map +1 -0
  5. package/dist/index.d.ts +105 -17
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js +360 -78
  8. package/dist/index.js.map +1 -1
  9. package/dist/json-CzZZ6K4x.js +24 -0
  10. package/dist/json-CzZZ6K4x.js.map +1 -0
  11. package/dist/{material-plugin-CWtV7DkH.js → material-plugin-BOCB7Stt.js} +2 -2
  12. package/dist/{material-plugin-CWtV7DkH.js.map → material-plugin-BOCB7Stt.js.map} +1 -1
  13. package/dist/{post-effect-C42XJFmo.js → post-effect-BHl7U56q.js} +5 -4
  14. package/dist/post-effect-BHl7U56q.js.map +1 -0
  15. package/dist/{post-effect-compiler-pOvXae-i.js → post-effect-compiler-Dw6zW2cG.js} +3 -3
  16. package/dist/{post-effect-compiler-pOvXae-i.js.map → post-effect-compiler-Dw6zW2cG.js.map} +1 -1
  17. package/dist/{shader-material-B6wwFCKB.js → shader-material-BxQn9FT4.js} +2 -2
  18. package/dist/{shader-material-B6wwFCKB.js.map → shader-material-BxQn9FT4.js.map} +1 -1
  19. package/dist/{shader-material-C4VjLTfV.js → shader-material-DRZmqA_S.js} +10 -6
  20. package/dist/shader-material-DRZmqA_S.js.map +1 -0
  21. package/dist/{shader-pragma-qO9_6sTd.js → shader-pragma-DrFm5f5m.js} +2 -2
  22. package/dist/{shader-pragma-qO9_6sTd.js.map → shader-pragma-DrFm5f5m.js.map} +1 -1
  23. package/dist/{surface-shader-BaR7Kg-F.js → surface-shader-BgZchRBe.js} +4 -4
  24. package/dist/{surface-shader-BaR7Kg-F.js.map → surface-shader-BgZchRBe.js.map} +1 -1
  25. package/package.json +1 -1
  26. package/dist/ignifx-error-RpK-lWwE.js.map +0 -1
  27. package/dist/post-effect-C42XJFmo.js.map +0 -1
  28. 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.11.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,
@@ -13334,7 +13432,7 @@ function shaderMaterialDefinition(input) {
13334
13432
  const declared = input.textures ?? {};
13335
13433
  for (const name of Object.keys(declared)) {
13336
13434
  const bound = declared[name];
13337
- 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);
13338
13436
  }
13339
13437
  return {
13340
13438
  kind: "shader",
@@ -13699,7 +13797,7 @@ async function loadSurfaceShaders(ctx, references) {
13699
13797
  for (let index = 0; index < names.length; index += 1) {
13700
13798
  const handle = resolved.handles[index];
13701
13799
  const name = names[index];
13702
- if (handle !== void 0 && name !== void 0) textures[name] = handle;
13800
+ if (handle !== void 0 && name !== void 0) setOwnJsonProperty(textures, name, handle);
13703
13801
  }
13704
13802
  return {
13705
13803
  shader,
@@ -13835,12 +13933,12 @@ function readTextureRecord(file) {
13835
13933
  for (const name of Object.keys(entries)) {
13836
13934
  const value = entries[name];
13837
13935
  if (typeof value === "string" && value !== "") {
13838
- record[name] = value;
13936
+ setOwnJsonProperty(record, name, value);
13839
13937
  continue;
13840
13938
  }
13841
13939
  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
13842
13940
  const address = value["$asset"];
13843
- if (typeof address === "string" && address !== "") record[name] = address;
13941
+ if (typeof address === "string" && address !== "") setOwnJsonProperty(record, name, address);
13844
13942
  }
13845
13943
  }
13846
13944
  return record;
@@ -13872,7 +13970,7 @@ async function loadNamedTextures(ctx, requested) {
13872
13970
  const name = names[index];
13873
13971
  const address = name === void 0 ? void 0 : requested[name];
13874
13972
  if (handle === null || handle === void 0 || name === void 0 || address === void 0) continue;
13875
- addresses[name] = address;
13973
+ setOwnJsonProperty(addresses, name, address);
13876
13974
  handles.push(handle);
13877
13975
  }
13878
13976
  return {
@@ -13895,13 +13993,13 @@ function readValues(file) {
13895
13993
  for (const name of Object.keys(entries)) {
13896
13994
  const value = entries[name];
13897
13995
  if (typeof value === "number" && Number.isFinite(value)) {
13898
- values[name] = value;
13996
+ setOwnJsonProperty(values, name, value);
13899
13997
  continue;
13900
13998
  }
13901
13999
  if (Array.isArray(value)) {
13902
14000
  const numbers = [];
13903
14001
  for (const element of value) numbers.push(typeof element === "number" && Number.isFinite(element) ? element : 0);
13904
- values[name] = numbers;
14002
+ setOwnJsonProperty(values, name, numbers);
13905
14003
  }
13906
14004
  }
13907
14005
  return values;
@@ -13919,7 +14017,7 @@ function readDefines(file) {
13919
14017
  const entries = declared;
13920
14018
  for (const name of Object.keys(entries)) {
13921
14019
  const value = entries[name];
13922
- 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);
13923
14021
  }
13924
14022
  return defines;
13925
14023
  }
@@ -14712,7 +14810,7 @@ let effectLayer = null;
14712
14810
  * @internal
14713
14811
  */
14714
14812
  async function loadPostEffectSupport() {
14715
- 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")]);
14716
14814
  compilerLayer = compiler;
14717
14815
  effectLayer = effects;
14718
14816
  }
@@ -14850,7 +14948,7 @@ function createShaderLoader() {
14850
14948
  type: SHADER_ASSET_TYPE,
14851
14949
  extensions: SHADER_FILE_EXTENSIONS,
14852
14950
  async load(ctx) {
14853
- 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")]);
14854
14952
  const declaration = pragma.parseShaderDeclaration(source, ctx.address);
14855
14953
  await loadShaderSupport();
14856
14954
  if (declaration.kind === "surface") await loadSurfaceShaderSupport();
@@ -15800,6 +15898,11 @@ function asMesh(node) {
15800
15898
  * flag flips. That is `07-rendering.md` §2.3's rule, and the browser test asserts both halves: the
15801
15899
  * pixel returns to the clear colour, and the mesh is still in the scene.
15802
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
+ *
15803
15906
  * ## Decisions the documents left open
15804
15907
  *
15805
15908
  * - **The clone's Lite `id` is the entity's uid.** Lite's light include/exclude lists match on
@@ -15843,6 +15946,7 @@ var MeshRenderer = class MeshRenderer extends Component {
15843
15946
  #instance = null;
15844
15947
  #appliedMesh = null;
15845
15948
  #appliedCastShadows = true;
15949
+ #displayHidden = false;
15846
15950
  /**
15847
15951
  * The Babylon Lite mesh this renderer draws. Unstable escape hatch
15848
15952
  * (`docs/architecture/00-overview.md` §3).
@@ -15853,8 +15957,45 @@ var MeshRenderer = class MeshRenderer extends Component {
15853
15957
  return { mesh: this.#instance?.clone ?? null };
15854
15958
  }
15855
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
+ /**
15856
15996
  * Whether the mesh is currently drawn: its own `enabled` flag and its entity's
15857
- * `activeInHierarchy`, materialised onto Lite's `visible`.
15997
+ * `activeInHierarchy`, less {@link MeshRenderer.displayHidden}, materialised onto Lite's
15998
+ * `visible`.
15858
15999
  *
15859
16000
  * @returns `true` when the clone is visible.
15860
16001
  */
@@ -15885,8 +16026,8 @@ var MeshRenderer = class MeshRenderer extends Component {
15885
16026
  if (instance === null) return changed;
15886
16027
  instance.applyMaterial(this.#material(renderer));
15887
16028
  instance.applyDisplacement(this.#displacement(), this.entity.transform);
15888
- instance.applyFlags(this.receiveShadows, this.renderOrder, this.pickable);
15889
- instance.applyVisible(this.isEnabledInHierarchy);
16029
+ instance.applyFlags(this.receiveShadows, this.renderOrder, this.pickable && !this.#displayHidden);
16030
+ instance.applyVisible(this.isEnabledInHierarchy && !this.#displayHidden);
15890
16031
  return changed;
15891
16032
  }
15892
16033
  /**
@@ -18574,7 +18715,7 @@ function encodeInto(field, value, references, path, issues) {
18574
18715
  case "map": {
18575
18716
  if (!isPlainObject(value)) return unrepresentable(issues, path, `expected an object, received ${typeof value}.`);
18576
18717
  const encoded = {};
18577
- 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));
18578
18719
  return encoded;
18579
18720
  }
18580
18721
  case "optional": return value === null ? null : encodeInto(spec.inner, value, references, path, issues);
@@ -18733,7 +18874,7 @@ function decodeInto(field, json, references, path, issues) {
18733
18874
  case "map": {
18734
18875
  if (!isPlainObject(json)) return rejected(field, issues, path, `expected an object.`);
18735
18876
  const decoded = {};
18736
- 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));
18737
18878
  return decoded;
18738
18879
  }
18739
18880
  case "optional": return json === null ? null : decodeInto(spec.inner, json, references, path, issues);
@@ -19102,7 +19243,7 @@ function schemaJsonSchema(schema) {
19102
19243
  * @param typeId - The component's namespaced registration id, for example `mygame/Mover`.
19103
19244
  * @param schema - The component's declared fields.
19104
19245
  * @param meta - Overrides for the title, format grouping, and summary, and the component's
19105
- * `allowMultiple`, `package` and `builtIn` when the caller knows them.
19246
+ * `allowMultiple`, `package`, `builtIn` and `requires` when the caller knows them.
19106
19247
  * @returns The description entry.
19107
19248
  *
19108
19249
  * @example
@@ -19123,7 +19264,8 @@ function describeSchema(typeId, schema, meta) {
19123
19264
  fields: describeFields(schema, noReferences()),
19124
19265
  ...meta?.allowMultiple === void 0 ? {} : { allowMultiple: meta.allowMultiple },
19125
19266
  ...meta?.package === void 0 ? {} : { package: meta.package },
19126
- ...meta?.builtIn === void 0 ? {} : { builtIn: meta.builtIn }
19267
+ ...meta?.builtIn === void 0 ? {} : { builtIn: meta.builtIn },
19268
+ ...meta?.requires === void 0 ? {} : { requires: meta.requires }
19127
19269
  };
19128
19270
  }
19129
19271
  /**
@@ -19688,6 +19830,10 @@ function toHex(bytes) {
19688
19830
  * (`CONSTITUTION.md` §2.3). The generated document remains the artefact the Vite plugin and editors
19689
19831
  * validate against; this is the same rule set, executable at load time.
19690
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
+ *
19691
19837
  * Component `props` are *not* checked here: `decodeProps` already reports every field problem with
19692
19838
  * a schema issue code, per field, which is more precise than a document-level match.
19693
19839
  *
@@ -19871,6 +20017,7 @@ function validateInstance(value, path, issues) {
19871
20017
  });
19872
20018
  return;
19873
20019
  }
20020
+ const identities = /* @__PURE__ */ new Map();
19874
20021
  for (let index = 0; index < overrides.length; index += 1) {
19875
20022
  const at = `${path}/overrides/${String(index)}`;
19876
20023
  const override = asRecord(overrides[index]);
@@ -19882,11 +20029,64 @@ function validateInstance(value, path, issues) {
19882
20029
  continue;
19883
20030
  }
19884
20031
  const op = override["op"];
19885
- if (op !== void 0 && op !== "replace" && op !== "remove" && op !== "add") issues.push({
19886
- path: `${at}/op`,
19887
- message: "expected \"replace\", \"remove\", or \"add\"."
19888
- });
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);
20040
+ }
20041
+ }
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;
19889
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";
19890
20090
  }
19891
20091
  /**
19892
20092
  * Validates a `transform` entry.
@@ -23202,7 +23402,8 @@ var ExtensionContextImpl = class {
23202
23402
  * @param schema - The schema the section is validated against.
23203
23403
  * @param defaults - The values used when the project omits the section.
23204
23404
  * @throws IgnifxError with code `IGX-0408` in development when the project's values do not
23205
- * 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`.
23206
23407
  */
23207
23408
  registerSettings(section, schema, defaults) {
23208
23409
  this.#settings.register(section, schema, defaults, this.#extension.name);
@@ -24246,7 +24447,14 @@ var HotReloadHostImpl = class {
24246
24447
  for (let index = 0; index < plans.length; index += 1) {
24247
24448
  const plan = plans[index];
24248
24449
  if (plan === void 0) continue;
24249
- 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
+ }
24250
24458
  instances += plan.policy === "patch" ? patchInstances(world, plan.previousInfo, info, plan.instances) : recreateInstances(world, plan.previousInfo, plan.next, info, plan.instances, (message) => {
24251
24459
  this.#log.warn(`hot reload: ${message}`);
24252
24460
  });
@@ -26614,9 +26822,10 @@ var SettingsStore = class {
26614
26822
  * @param defaults - The values used for everything the project omits, as a bag of named props.
26615
26823
  * @param owner - The extension registering the section, named in diagnostics.
26616
26824
  * @throws IgnifxError with code `IGX-0408` in development when the project's values do not
26617
- * validate.
26825
+ * validate, and with code `IGX-0607` when a field is named after an `Object.prototype` member.
26618
26826
  */
26619
26827
  register(name, schema, defaults, owner) {
26828
+ assertNoInheritedFieldNames(schema, "settings");
26620
26829
  const base = isPropertyBag(defaults) ? defaults : createDefaults(schema);
26621
26830
  const value = this.#resolve(name, schema, base);
26622
26831
  this.#sections.set(name, {
@@ -29175,7 +29384,8 @@ var Entity = class {
29175
29384
  * @returns The attached component.
29176
29385
  * @throws IgnifxError with code `IGX-0202` when the class does not allow multiple instances and
29177
29386
  * the entity already has one, `IGX-0605`/`IGX-0606`/`IGX-0607` when `init` does not match the
29178
- * 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.
29179
29389
  */
29180
29390
  addComponent(type, init) {
29181
29391
  const internals = this.#mutable("addComponent");
@@ -30892,7 +31102,8 @@ const TRANSFORM_CHANNELS = Object.freeze([
30892
31102
  *
30893
31103
  * @param path - The `path` string from the file.
30894
31104
  * @returns The parsed path.
30895
- * @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__`.
30896
31107
  *
30897
31108
  * @example
30898
31109
  * ```ts
@@ -30948,11 +31159,13 @@ function parseOverridePath(path) {
30948
31159
  component
30949
31160
  };
30950
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.");
30951
31164
  return {
30952
31165
  kind: "prop",
30953
31166
  entity,
30954
31167
  component,
30955
- steps: segments.slice(4)
31168
+ steps
30956
31169
  };
30957
31170
  }
30958
31171
  /**
@@ -31129,18 +31342,18 @@ function writeStep(container, steps, at, op, value, path, report) {
31129
31342
  const { [key]: _removed, ...rest } = copy;
31130
31343
  return rest;
31131
31344
  }
31132
- copy[key] = value;
31345
+ setOwnJsonProperty(copy, key, value);
31133
31346
  return copy;
31134
31347
  }
31135
- const next = copy[key];
31348
+ const next = Object.hasOwn(copy, key) ? copy[key] : void 0;
31136
31349
  const nextArray = asJsonArray(next);
31137
31350
  if (nextArray !== null) {
31138
- copy[key] = writeArrayStep(nextArray, steps, at + 1, op, value, path, report);
31351
+ setOwnJsonProperty(copy, key, writeArrayStep(nextArray, steps, at + 1, op, value, path, report));
31139
31352
  return copy;
31140
31353
  }
31141
31354
  const nextObject = asJsonObject(next);
31142
31355
  if (nextObject !== null) {
31143
- copy[key] = writeStep(nextObject, steps, at + 1, op, value, path, report);
31356
+ setOwnJsonProperty(copy, key, writeStep(nextObject, steps, at + 1, op, value, path, report));
31144
31357
  return copy;
31145
31358
  }
31146
31359
  report(`"${path}" descends into ${key}, which is not an object or an array.`);
@@ -31595,7 +31808,7 @@ function remapValue(value, keys) {
31595
31808
  rewritten[key] = keys.get(entry) ?? entry;
31596
31809
  continue;
31597
31810
  }
31598
- rewritten[key] = remapValue(entry, keys);
31811
+ setOwnJsonProperty(rewritten, key, remapValue(entry, keys));
31599
31812
  }
31600
31813
  return rewritten;
31601
31814
  }
@@ -31710,14 +31923,15 @@ function noAssets() {
31710
31923
  * @param remap - The table filled while the scene was being constructed.
31711
31924
  * @param assets - How an asset address becomes a handle; defaults to resolving nothing, which makes
31712
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`.
31713
31927
  * @returns The decoder to hand `decodeProps`.
31714
31928
  *
31715
31929
  * @internal
31716
31930
  */
31717
- function remapDecoder(remap, assets = noAssets) {
31931
+ function remapDecoder(remap, assets = noAssets, outside) {
31718
31932
  return {
31719
- entity: (uid) => remap.entity(uid),
31720
- 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,
31721
31935
  asset: (address, type) => assets(address, type)
31722
31936
  };
31723
31937
  }
@@ -31824,7 +32038,7 @@ function instantiateScene(world, asset, options) {
31824
32038
  createEntities(context, expanded.entities, parent);
31825
32039
  attachComponents(context);
31826
32040
  linkInstances(context, options?.assetHandle ?? null, options?.rootEntity ?? null);
31827
- decodeAllProps(context, sceneAssetResolver(world, asset));
32041
+ decodeAllProps(context, sceneAssetResolver(world, asset), options?.outsideReferences);
31828
32042
  activate(context);
31829
32043
  return {
31830
32044
  roots: context.roots,
@@ -31883,6 +32097,12 @@ function createEntities(context, entities, parent) {
31883
32097
  * Pass 2: attaches every component with its schema defaults, so the reference table is complete
31884
32098
  * before any prop is decoded.
31885
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
+ *
31886
32106
  * @param context - The build state.
31887
32107
  * @throws IgnifxError with code `IGX-0307` when the file names an unregistered component type: the
31888
32108
  * file cannot be honoured with a component missing, so this one is not recoverable.
@@ -31890,25 +32110,83 @@ function createEntities(context, entities, parent) {
31890
32110
  function attachComponents(context) {
31891
32111
  for (let index = 0; index < context.built.length; index += 1) {
31892
32112
  const built = context.built[index];
31893
- if (built === void 0) continue;
31894
- const records = built.source.data.components;
31895
- for (let inner = 0; inner < records.length; inner += 1) {
31896
- const record = records[inner];
31897
- if (record === void 0) continue;
31898
- const type = context.world.registry.get(record.type);
31899
- if (type === null) throw new IgnifxError(CoreErrorCode.unknownComponentTypeId, `${record.type} is not a registered component type.`, {
31900
- context: {
31901
- typeId: record.type,
31902
- entity: built.source.data.uid
31903
- },
31904
- hint: "Register the class with app.registerComponents before loading a scene that uses it."
31905
- });
31906
- const component = built.entity.addComponent(type);
31907
- componentInternals(component).uid = record.uid;
31908
- if (record.enabled === false) component.enabled = false;
31909
- context.remap.addComponent(record.uid, component);
31910
- built.components.push(component);
31911
- }
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;
31912
32190
  }
31913
32191
  }
31914
32192
  /**
@@ -32018,9 +32296,10 @@ function instancedRoot(context, instance, source) {
32018
32296
  *
32019
32297
  * @param context - The build state.
32020
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.
32021
32300
  */
32022
- function decodeAllProps(context, assets) {
32023
- const decoder = remapDecoder(context.remap, assets);
32301
+ function decodeAllProps(context, assets, outside) {
32302
+ const decoder = remapDecoder(context.remap, assets, outside);
32024
32303
  for (let index = 0; index < context.built.length; index += 1) {
32025
32304
  const built = context.built[index];
32026
32305
  if (built === void 0) continue;
@@ -35526,7 +35805,8 @@ function componentPackage(registry, typeId) {
35526
35805
  /**
35527
35806
  * Describes every component an app has registered, the engine's, its extensions' and the game's,
35528
35807
  * the way {@link describeSchema} describes one, plus what only the registry knows: whether an
35529
- * 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).
35530
35810
  * This is what an external inspector, such as the ignifx editor, is generated from.
35531
35811
  *
35532
35812
  * @remarks
@@ -35549,6 +35829,7 @@ function componentPackage(registry, typeId) {
35549
35829
  * const schemas = describeRegisteredSchemas(app.world.registry, describeSchemas());
35550
35830
  * schemas["ignifx/Camera"]?.package; // "@ignifx/core"
35551
35831
  * schemas["ignifx/Camera"]?.allowMultiple; // false
35832
+ * schemas["ignifx/ThirdPersonController"]?.requires; // ["ignifx/CharacterController"] once @ignifx/3d is registered
35552
35833
  * ```
35553
35834
  *
35554
35835
  * @public
@@ -35565,7 +35846,8 @@ function describeRegisteredSchemas(registry, curated) {
35565
35846
  ...meta?.description === void 0 ? {} : { description: meta.description },
35566
35847
  allowMultiple: info.allowMultiple,
35567
35848
  package: componentPackage(registry, typeId),
35568
- ...builtIn ? { builtIn } : {}
35849
+ ...builtIn ? { builtIn } : {},
35850
+ ...info.requires.length === 0 ? {} : { requires: info.requires.map((required) => required.typeId ?? null) }
35569
35851
  });
35570
35852
  }
35571
35853
  return described;
@@ -35714,7 +35996,7 @@ function entriesToJson(entries, convert) {
35714
35996
  const object = {};
35715
35997
  for (const [name, value] of entries) {
35716
35998
  const converted = convert(value, name);
35717
- if (converted !== void 0) object[name] = converted;
35999
+ if (converted !== void 0) setOwnJsonProperty(object, name, converted);
35718
36000
  }
35719
36001
  return object;
35720
36002
  }