@ignifx/core 0.11.0 → 0.13.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 +142 -18
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js +409 -89
  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,8 +3525,10 @@ 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,
3530
+ title: ownString(type, "title"),
3531
+ description: ownString(type, "description"),
3484
3532
  ancestors,
3485
3533
  trackedFields: schema === null ? EMPTY_NAMES : collectTrackedFields(schema),
3486
3534
  isScript,
@@ -3489,6 +3537,55 @@ var ComponentRegistry = class {
3489
3537
  };
3490
3538
  }
3491
3539
  };
3540
+ /**
3541
+ * Refuses a class whose `static schema` names a field after an `Object.prototype` member.
3542
+ * `Component.define` and `Script.define` check this already; a hand-written `static schema` skips
3543
+ * them, so the registry checks every class it describes.
3544
+ *
3545
+ * @param type - The class being described.
3546
+ * @throws IgnifxError with code `IGX-0607` when a field is named `constructor`, `__proto__`, or
3547
+ * another inherited member.
3548
+ */
3549
+ function assertSchemaFieldNames(type) {
3550
+ const schema = readStatics$1(type).schema;
3551
+ if (schema !== void 0) assertNoInheritedFieldNames(schema, "schema");
3552
+ }
3553
+ /**
3554
+ * Refuses a class whose `static requires` graph contains a cycle — through the class itself or
3555
+ * through any class it reaches. `addComponent` adds each missing
3556
+ * required class before the requiring one, so a cycle — a self-require, or A requiring B requiring
3557
+ * A — would otherwise recurse until the stack overflows on the first `addComponent`.
3558
+ *
3559
+ * @param type - The class being described.
3560
+ * @throws IgnifxError with code `IGX-0209` when a cycle is reachable from the class.
3561
+ */
3562
+ function assertNoRequiresCycle(type) {
3563
+ const finished = /* @__PURE__ */ new Set();
3564
+ const path = [];
3565
+ const visit = (current) => {
3566
+ const at = path.indexOf(current);
3567
+ if (at >= 0) {
3568
+ const cycle = [...path.slice(at), current].map((entry) => entry.prototype.constructor.name).join(" -> ");
3569
+ throw new IgnifxError(CoreErrorCode.requiresCycle, `${type.prototype.constructor.name} has a static requires cycle: ${cycle}.`, {
3570
+ context: {
3571
+ component: type.prototype.constructor.name,
3572
+ cycle
3573
+ },
3574
+ hint: "Remove a class from one of the `static requires` lists so the chain never loops back; shared requirements are fine."
3575
+ });
3576
+ }
3577
+ if (finished.has(current)) return;
3578
+ const requires = readStatics$1(current).requires ?? EMPTY_TYPES;
3579
+ path.push(current);
3580
+ for (let index = 0; index < requires.length; index += 1) {
3581
+ const required = requires[index];
3582
+ if (required !== void 0) visit(required);
3583
+ }
3584
+ path.pop();
3585
+ finished.add(current);
3586
+ };
3587
+ visit(type);
3588
+ }
3492
3589
  /** Shared empty lists so the common case allocates nothing. */
3493
3590
  const EMPTY_TYPES = Object.freeze([]);
3494
3591
  /** Shared empty name list. */
@@ -3558,6 +3655,19 @@ function readStatics$1(type) {
3558
3655
  return type;
3559
3656
  }
3560
3657
  /**
3658
+ * Reads a string static the class declares itself. A subclass inherits its parent's statics in
3659
+ * JavaScript, and a parent's title would misname the subclass in an inspector.
3660
+ *
3661
+ * @param type - The component class.
3662
+ * @param name - The static's name.
3663
+ * @returns The class's own value, or `null` when it declares none or it is not a string.
3664
+ */
3665
+ function ownString(type, name) {
3666
+ if (!Object.hasOwn(type, name)) return null;
3667
+ const value = readStatics$1(type)[name];
3668
+ return typeof value === "string" ? value : null;
3669
+ }
3670
+ /**
3561
3671
  * Reports whether a class implements a callback, from its cached bit mask.
3562
3672
  *
3563
3673
  * @param info - The class info, or `null` for a plain component.
@@ -4704,7 +4814,7 @@ function createServiceKey(name) {
4704
4814
  *
4705
4815
  * @public
4706
4816
  */
4707
- const VERSION = "0.11.0";
4817
+ const VERSION = "0.13.0";
4708
4818
  //#endregion
4709
4819
  //#region src/assets/delivery-system.ts
4710
4820
  /**
@@ -5860,6 +5970,8 @@ function array(item, defaultValue = [], options) {
5860
5970
  * @param fields - The sub-fields.
5861
5971
  * @param options - Inspector and serializer metadata.
5862
5972
  * @returns The field definition.
5973
+ * @throws IgnifxError with code `IGX-0607` when a sub-field name is an `Object.prototype` member
5974
+ * such as `__proto__`, `constructor`, or `toString`.
5863
5975
  *
5864
5976
  * @example
5865
5977
  * ```ts
@@ -5869,6 +5981,7 @@ function array(item, defaultValue = [], options) {
5869
5981
  * @public
5870
5982
  */
5871
5983
  function record(fields, options) {
5984
+ assertNoInheritedFieldNames(fields, "record");
5872
5985
  return field({
5873
5986
  kind: FieldKind.record,
5874
5987
  fields
@@ -6084,6 +6197,8 @@ function createRay() {
6084
6197
  var Camera = class Camera extends Component {
6085
6198
  /** The namespaced registration id. */
6086
6199
  static typeId = "ignifx/Camera";
6200
+ /** What the component does, in one line, for an inspector. */
6201
+ static description = "The camera an entity renders the world through; the entity's transform is the view.";
6087
6202
  /** At most one camera per entity: two views from one transform would be the same view. */
6088
6203
  static allowMultiple = false;
6089
6204
  /** The serialized field declarations (ADR-0004). */
@@ -6721,6 +6836,8 @@ const SKYBOX_SIZE_DEFAULT = 20;
6721
6836
  var Environment = class Environment extends Component {
6722
6837
  /** The namespaced registration id. */
6723
6838
  static typeId = "ignifx/Environment";
6839
+ /** What the component does, in one line, for an inspector. */
6840
+ static description = "The world's image-based lighting, skybox, fog, image processing, and clear colour.";
6724
6841
  /** One per entity, and effectively one per world: the fields are all scene state. */
6725
6842
  static allowMultiple = false;
6726
6843
  /** The serialized field declarations (ADR-0004). */
@@ -7066,7 +7183,7 @@ let surfaceLayer = null;
7066
7183
  * @internal
7067
7184
  */
7068
7185
  async function loadShaderSupport() {
7069
- const loaded = shaderLayer ?? await import("./shader-material-C4VjLTfV.js").then((n) => n.n);
7186
+ const loaded = shaderLayer ?? await import("./shader-material-DRZmqA_S.js").then((n) => n.n);
7070
7187
  shaderLayer = loaded;
7071
7188
  await loaded.loadShaderMaterialAdapter();
7072
7189
  return loaded;
@@ -7089,7 +7206,7 @@ function shaderSupport() {
7089
7206
  * @internal
7090
7207
  */
7091
7208
  async function loadSurfaceShaderSupport() {
7092
- const loaded = surfaceLayer ?? await import("./surface-shader-BaR7Kg-F.js");
7209
+ const loaded = surfaceLayer ?? await import("./surface-shader-BgZchRBe.js");
7093
7210
  surfaceLayer = loaded;
7094
7211
  return loaded;
7095
7212
  }
@@ -7609,7 +7726,7 @@ function resolveSurfaceShaders(app, references) {
7609
7726
  const textures = {};
7610
7727
  for (const name of Object.keys(reference.textures)) {
7611
7728
  const handle = app.assets.get(reference.textures[name] ?? "");
7612
- if (handle !== null && handle.state === "loaded") textures[name] = handle;
7729
+ if (handle !== null && handle.state === "loaded") setOwnJsonProperty(textures, name, handle);
7613
7730
  }
7614
7731
  inits.push({
7615
7732
  shader,
@@ -11542,6 +11659,8 @@ function noMatrices() {
11542
11659
  var InstancedMeshRenderer = class InstancedMeshRenderer extends Component {
11543
11660
  /** The namespaced registration id. */
11544
11661
  static typeId = "ignifx/InstancedMeshRenderer";
11662
+ /** What the component does, in one line, for an inspector. */
11663
+ static description = "Draws one mesh many times from a caller-owned matrix slab, in a single draw call, with optional GPU culling and a coarser mesh for far instances.";
11545
11664
  /** Several instanced renderers on one entity draw several clouds from one transform. */
11546
11665
  static allowMultiple = true;
11547
11666
  /** The serialized field declarations (ADR-0004). */
@@ -12608,6 +12727,8 @@ const TRANSLATION_COLUMN = 12;
12608
12727
  var Light = class Light extends Component {
12609
12728
  /** The namespaced registration id. */
12610
12729
  static typeId = "ignifx/Light";
12730
+ /** What the component does, in one line, for an inspector. */
12731
+ static description = "A directional, point, spot, or hemispheric light, with optional shadow casting.";
12611
12732
  /** At most one light per entity: two lights from one transform want two entities. */
12612
12733
  static allowMultiple = false;
12613
12734
  /** The serialized field declarations (ADR-0004). */
@@ -13334,7 +13455,7 @@ function shaderMaterialDefinition(input) {
13334
13455
  const declared = input.textures ?? {};
13335
13456
  for (const name of Object.keys(declared)) {
13336
13457
  const bound = declared[name];
13337
- if (bound !== void 0) textures[name] = typeof bound === "string" ? bound : bound.address;
13458
+ if (bound !== void 0) setOwnJsonProperty(textures, name, typeof bound === "string" ? bound : bound.address);
13338
13459
  }
13339
13460
  return {
13340
13461
  kind: "shader",
@@ -13699,7 +13820,7 @@ async function loadSurfaceShaders(ctx, references) {
13699
13820
  for (let index = 0; index < names.length; index += 1) {
13700
13821
  const handle = resolved.handles[index];
13701
13822
  const name = names[index];
13702
- if (handle !== void 0 && name !== void 0) textures[name] = handle;
13823
+ if (handle !== void 0 && name !== void 0) setOwnJsonProperty(textures, name, handle);
13703
13824
  }
13704
13825
  return {
13705
13826
  shader,
@@ -13835,12 +13956,12 @@ function readTextureRecord(file) {
13835
13956
  for (const name of Object.keys(entries)) {
13836
13957
  const value = entries[name];
13837
13958
  if (typeof value === "string" && value !== "") {
13838
- record[name] = value;
13959
+ setOwnJsonProperty(record, name, value);
13839
13960
  continue;
13840
13961
  }
13841
13962
  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
13842
13963
  const address = value["$asset"];
13843
- if (typeof address === "string" && address !== "") record[name] = address;
13964
+ if (typeof address === "string" && address !== "") setOwnJsonProperty(record, name, address);
13844
13965
  }
13845
13966
  }
13846
13967
  return record;
@@ -13872,7 +13993,7 @@ async function loadNamedTextures(ctx, requested) {
13872
13993
  const name = names[index];
13873
13994
  const address = name === void 0 ? void 0 : requested[name];
13874
13995
  if (handle === null || handle === void 0 || name === void 0 || address === void 0) continue;
13875
- addresses[name] = address;
13996
+ setOwnJsonProperty(addresses, name, address);
13876
13997
  handles.push(handle);
13877
13998
  }
13878
13999
  return {
@@ -13895,13 +14016,13 @@ function readValues(file) {
13895
14016
  for (const name of Object.keys(entries)) {
13896
14017
  const value = entries[name];
13897
14018
  if (typeof value === "number" && Number.isFinite(value)) {
13898
- values[name] = value;
14019
+ setOwnJsonProperty(values, name, value);
13899
14020
  continue;
13900
14021
  }
13901
14022
  if (Array.isArray(value)) {
13902
14023
  const numbers = [];
13903
14024
  for (const element of value) numbers.push(typeof element === "number" && Number.isFinite(element) ? element : 0);
13904
- values[name] = numbers;
14025
+ setOwnJsonProperty(values, name, numbers);
13905
14026
  }
13906
14027
  }
13907
14028
  return values;
@@ -13919,7 +14040,7 @@ function readDefines(file) {
13919
14040
  const entries = declared;
13920
14041
  for (const name of Object.keys(entries)) {
13921
14042
  const value = entries[name];
13922
- if (typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) defines[name] = value;
14043
+ if (typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) setOwnJsonProperty(defines, name, value);
13923
14044
  }
13924
14045
  return defines;
13925
14046
  }
@@ -14712,7 +14833,7 @@ let effectLayer = null;
14712
14833
  * @internal
14713
14834
  */
14714
14835
  async function loadPostEffectSupport() {
14715
- const [compiler, effects] = await Promise.all([compilerLayer ?? import("./post-effect-compiler-pOvXae-i.js"), effectLayer ?? import("./effect-task-CMbuO6Kb.js")]);
14836
+ const [compiler, effects] = await Promise.all([compilerLayer ?? import("./post-effect-compiler-Dw6zW2cG.js"), effectLayer ?? import("./effect-task-CMbuO6Kb.js")]);
14716
14837
  compilerLayer = compiler;
14717
14838
  effectLayer = effects;
14718
14839
  }
@@ -14850,7 +14971,7 @@ function createShaderLoader() {
14850
14971
  type: SHADER_ASSET_TYPE,
14851
14972
  extensions: SHADER_FILE_EXTENSIONS,
14852
14973
  async load(ctx) {
14853
- const [source, pragma] = await Promise.all([ctx.fetchText(), import("./shader-pragma-qO9_6sTd.js")]);
14974
+ const [source, pragma] = await Promise.all([ctx.fetchText(), import("./shader-pragma-DrFm5f5m.js")]);
14854
14975
  const declaration = pragma.parseShaderDeclaration(source, ctx.address);
14855
14976
  await loadShaderSupport();
14856
14977
  if (declaration.kind === "surface") await loadSurfaceShaderSupport();
@@ -15800,6 +15921,11 @@ function asMesh(node) {
15800
15921
  * flag flips. That is `07-rendering.md` §2.3's rule, and the browser test asserts both halves: the
15801
15922
  * pixel returns to the clear colour, and the mesh is still in the scene.
15802
15923
  *
15924
+ * `displayHidden` hides the same way, and makes the clone unpickable too, but is not a field: scene
15925
+ * files do not save it, so a system
15926
+ * that chooses what is drawn without changing the document (a `LodGroup` in an edit-mode app,
15927
+ * ADR-0028) switches it instead of `enabled`.
15928
+ *
15803
15929
  * ## Decisions the documents left open
15804
15930
  *
15805
15931
  * - **The clone's Lite `id` is the entity's uid.** Lite's light include/exclude lists match on
@@ -15831,6 +15957,8 @@ function asMesh(node) {
15831
15957
  var MeshRenderer = class MeshRenderer extends Component {
15832
15958
  /** The namespaced registration id. */
15833
15959
  static typeId = "ignifx/MeshRenderer";
15960
+ /** What the component does, in one line, for an inspector. */
15961
+ static description = "Draws one clone of a mesh asset with a material.";
15834
15962
  /** Several renderers on one entity draw several meshes from one transform, which is useful. */
15835
15963
  static allowMultiple = true;
15836
15964
  /** The serialized field declarations (ADR-0004). */
@@ -15843,6 +15971,7 @@ var MeshRenderer = class MeshRenderer extends Component {
15843
15971
  #instance = null;
15844
15972
  #appliedMesh = null;
15845
15973
  #appliedCastShadows = true;
15974
+ #displayHidden = false;
15846
15975
  /**
15847
15976
  * The Babylon Lite mesh this renderer draws. Unstable escape hatch
15848
15977
  * (`docs/architecture/00-overview.md` §3).
@@ -15853,8 +15982,45 @@ var MeshRenderer = class MeshRenderer extends Component {
15853
15982
  return { mesh: this.#instance?.clone ?? null };
15854
15983
  }
15855
15984
  /**
15985
+ * A display-only hide: while `true` the mesh is neither drawn nor picked, whatever `enabled` and
15986
+ * `pickable` say.
15987
+ *
15988
+ * @remarks
15989
+ * It is not a schema field, so scene files do not save it, a serializer never reads it, and
15990
+ * `enabled` keeps its authored value. That makes it the switch for a system that chooses what is
15991
+ * drawn without changing the document: `@ignifx/3d`'s `LodGroup` uses it in place of `enabled` in
15992
+ * an edit-mode app (ADR-0028). It starts `false` and takes effect at the next render sync;
15993
+ * {@link MeshRenderer.isVisible} reports the outcome. Lite's pickers ignore visibility, so the
15994
+ * clone is also made unpickable while hidden: `app.renderer.pickAsync` and `world.raycastRender`
15995
+ * neither return it nor let it occlude, as with `pickable: false`.
15996
+ *
15997
+ * It is one flag with one owner, not a count. In an edit-mode app the `LodGroup` that lists the
15998
+ * renderer as a level owns it: the group sets and clears it whenever it switches, so a value
15999
+ * written by anything else lasts only until then. A renderer belongs to at most one `LodGroup`; a
16000
+ * second group that lists it leaves it alone and warns with `IGX-1217`.
16001
+ *
16002
+ * @returns `true` while the mesh is hidden for display.
16003
+ *
16004
+ * @example
16005
+ * ```ts
16006
+ * renderer.displayHidden = true; // not drawn, and `renderer.enabled` is still `true`
16007
+ * ```
16008
+ */
16009
+ get displayHidden() {
16010
+ return this.#displayHidden;
16011
+ }
16012
+ /**
16013
+ * Hides the mesh for display, or shows it again; `enabled` is not touched.
16014
+ *
16015
+ * @param value - `true` to hide it.
16016
+ */
16017
+ set displayHidden(value) {
16018
+ this.#displayHidden = value;
16019
+ }
16020
+ /**
15856
16021
  * Whether the mesh is currently drawn: its own `enabled` flag and its entity's
15857
- * `activeInHierarchy`, materialised onto Lite's `visible`.
16022
+ * `activeInHierarchy`, less {@link MeshRenderer.displayHidden}, materialised onto Lite's
16023
+ * `visible`.
15858
16024
  *
15859
16025
  * @returns `true` when the clone is visible.
15860
16026
  */
@@ -15885,8 +16051,8 @@ var MeshRenderer = class MeshRenderer extends Component {
15885
16051
  if (instance === null) return changed;
15886
16052
  instance.applyMaterial(this.#material(renderer));
15887
16053
  instance.applyDisplacement(this.#displacement(), this.entity.transform);
15888
- instance.applyFlags(this.receiveShadows, this.renderOrder, this.pickable);
15889
- instance.applyVisible(this.isEnabledInHierarchy);
16054
+ instance.applyFlags(this.receiveShadows, this.renderOrder, this.pickable && !this.#displayHidden);
16055
+ instance.applyVisible(this.isEnabledInHierarchy && !this.#displayHidden);
15890
16056
  return changed;
15891
16057
  }
15892
16058
  /**
@@ -16217,6 +16383,8 @@ const NO_SKELETONS = Object.freeze([]);
16217
16383
  var Model = class Model extends Component {
16218
16384
  /** The namespaced registration id. */
16219
16385
  static typeId = "ignifx/Model";
16386
+ /** What the component does, in one line, for an inspector. */
16387
+ static description = "One instance of a loaded glTF, cloned under the entity's node.";
16220
16388
  /** One model per entity: a second instance under the same transform wants its own entity. */
16221
16389
  static allowMultiple = false;
16222
16390
  /** The serialized field declarations (ADR-0004). */
@@ -17110,6 +17278,8 @@ function nextLink(engine, links, source) {
17110
17278
  var PostProcessStack = class PostProcessStack extends Component {
17111
17279
  /** The namespaced registration id. */
17112
17280
  static typeId = "ignifx/PostProcessStack";
17281
+ /** What the component does, in one line, for an inspector. */
17282
+ static description = "Bloom, SMAA, image processing, and custom .post.wgsl effects, inserted into the scene's frame graph.";
17113
17283
  /** One chain per camera entity; a second would fight the first for the swapchain. */
17114
17284
  static allowMultiple = false;
17115
17285
  /** The serialized field declarations (ADR-0004). */
@@ -18574,7 +18744,7 @@ function encodeInto(field, value, references, path, issues) {
18574
18744
  case "map": {
18575
18745
  if (!isPlainObject(value)) return unrepresentable(issues, path, `expected an object, received ${typeof value}.`);
18576
18746
  const encoded = {};
18577
- for (const key of Object.keys(value).toSorted()) encoded[key] = encodeInto(spec.value, value[key], references, indexPath(path, key), issues);
18747
+ for (const key of Object.keys(value).toSorted()) setOwnJsonProperty(encoded, key, encodeInto(spec.value, value[key], references, indexPath(path, key), issues));
18578
18748
  return encoded;
18579
18749
  }
18580
18750
  case "optional": return value === null ? null : encodeInto(spec.inner, value, references, path, issues);
@@ -18733,7 +18903,7 @@ function decodeInto(field, json, references, path, issues) {
18733
18903
  case "map": {
18734
18904
  if (!isPlainObject(json)) return rejected(field, issues, path, `expected an object.`);
18735
18905
  const decoded = {};
18736
- for (const key of Object.keys(json).toSorted()) decoded[key] = decodeInto(spec.value, json[key] ?? null, references, indexPath(path, key), issues);
18906
+ for (const key of Object.keys(json).toSorted()) setOwnJsonProperty(decoded, key, decodeInto(spec.value, json[key] ?? null, references, indexPath(path, key), issues));
18737
18907
  return decoded;
18738
18908
  }
18739
18909
  case "optional": return json === null ? null : decodeInto(spec.inner, json, references, path, issues);
@@ -19102,7 +19272,7 @@ function schemaJsonSchema(schema) {
19102
19272
  * @param typeId - The component's namespaced registration id, for example `mygame/Mover`.
19103
19273
  * @param schema - The component's declared fields.
19104
19274
  * @param meta - Overrides for the title, format grouping, and summary, and the component's
19105
- * `allowMultiple`, `package` and `builtIn` when the caller knows them.
19275
+ * `allowMultiple`, `package`, `builtIn` and `requires` when the caller knows them.
19106
19276
  * @returns The description entry.
19107
19277
  *
19108
19278
  * @example
@@ -19123,7 +19293,8 @@ function describeSchema(typeId, schema, meta) {
19123
19293
  fields: describeFields(schema, noReferences()),
19124
19294
  ...meta?.allowMultiple === void 0 ? {} : { allowMultiple: meta.allowMultiple },
19125
19295
  ...meta?.package === void 0 ? {} : { package: meta.package },
19126
- ...meta?.builtIn === void 0 ? {} : { builtIn: meta.builtIn }
19296
+ ...meta?.builtIn === void 0 ? {} : { builtIn: meta.builtIn },
19297
+ ...meta?.requires === void 0 ? {} : { requires: meta.requires }
19127
19298
  };
19128
19299
  }
19129
19300
  /**
@@ -19688,6 +19859,10 @@ function toHex(bytes) {
19688
19859
  * (`CONSTITUTION.md` §2.3). The generated document remains the artefact the Vite plugin and editors
19689
19860
  * validate against; this is the same rule set, executable at load time.
19690
19861
  *
19862
+ * Two checks go beyond what JSON Schema can say: uids are unique within the file, and no two
19863
+ * overrides of one instance share an identity (path, `op`, and an added component's uid), both
19864
+ * reported as issues like any other.
19865
+ *
19691
19866
  * Component `props` are *not* checked here: `decodeProps` already reports every field problem with
19692
19867
  * a schema issue code, per field, which is more precise than a document-level match.
19693
19868
  *
@@ -19871,6 +20046,7 @@ function validateInstance(value, path, issues) {
19871
20046
  });
19872
20047
  return;
19873
20048
  }
20049
+ const identities = /* @__PURE__ */ new Map();
19874
20050
  for (let index = 0; index < overrides.length; index += 1) {
19875
20051
  const at = `${path}/overrides/${String(index)}`;
19876
20052
  const override = asRecord(overrides[index]);
@@ -19882,11 +20058,64 @@ function validateInstance(value, path, issues) {
19882
20058
  continue;
19883
20059
  }
19884
20060
  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
- });
20061
+ if (op !== void 0 && op !== "replace" && op !== "remove" && op !== "add") {
20062
+ issues.push({
20063
+ path: `${at}/op`,
20064
+ message: "expected \"replace\", \"remove\", or \"add\"."
20065
+ });
20066
+ continue;
20067
+ }
20068
+ checkOverrideIdentity(override["path"], op ?? "replace", override["value"], index, at, identities, issues);
20069
+ }
20070
+ }
20071
+ /**
20072
+ * Appends an issue when an override has the identity of an earlier override of the same instance.
20073
+ *
20074
+ * @remarks
20075
+ * An override's identity is its `path`, its `op` (`"replace"` when absent), and for an `add` to a
20076
+ * component list (`<uid>/components`) the uid of the component it adds — what the editor's ops
20077
+ * address an override by. The loader applies overrides in order, so of two with one identity the
20078
+ * first has no effect, and an editor that edits or removes "the" override at that identity reaches
20079
+ * only one of them. The engine's serializer never writes two; a hand edit or a merge conflict does.
20080
+ * Like a uid used twice, it is a file defect, refused rather than resolved.
20081
+ *
20082
+ * @param overridePath - The override's path.
20083
+ * @param op - Its op, defaulted.
20084
+ * @param value - Its value.
20085
+ * @param index - Its index in the list.
20086
+ * @param at - Its path in the file, for the issue.
20087
+ * @param identities - The identities already seen in the list, with the index of each.
20088
+ * @param issues - Where problems are appended.
20089
+ */
20090
+ function checkOverrideIdentity(overridePath, op, value, index, at, identities, issues) {
20091
+ const uid = asRecord(value)?.["uid"];
20092
+ const added = op === "add" && isComponentListPath(overridePath) && typeof uid === "string" ? uid : null;
20093
+ const identity = JSON.stringify([
20094
+ overridePath,
20095
+ op,
20096
+ added
20097
+ ]);
20098
+ const first = identities.get(identity);
20099
+ if (first === void 0) {
20100
+ identities.set(identity, index);
20101
+ return;
19889
20102
  }
20103
+ const what = added === null ? `"${op}" of "${overridePath}"` : `"add" of component ${added} to "${overridePath}"`;
20104
+ issues.push({
20105
+ path: at,
20106
+ 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.`
20107
+ });
20108
+ }
20109
+ /**
20110
+ * Whether an override path addresses an entity's component list (`<uid>/components`), the one kind
20111
+ * whose `add` overrides are told apart by the uid they add.
20112
+ *
20113
+ * @param overridePath - The path.
20114
+ * @returns True for `<uid>/components`.
20115
+ */
20116
+ function isComponentListPath(overridePath) {
20117
+ const segments = overridePath.split("/");
20118
+ return segments.length === 2 && segments[0] !== "" && segments[1] === "components";
19890
20119
  }
19891
20120
  /**
19892
20121
  * Validates a `transform` entry.
@@ -21371,6 +21600,8 @@ function transformIsNotRemovable() {
21371
21600
  var Transform = class extends Component {
21372
21601
  /** The registration id of the one component every entity carries. */
21373
21602
  static typeId = "ignifx/Transform";
21603
+ /** What the component does, in one line, for an inspector. */
21604
+ static description = "The entity's local position, rotation, and scale; every entity has exactly one, stored as its transform block.";
21374
21605
  /** An entity has exactly one transform. */
21375
21606
  static allowMultiple = false;
21376
21607
  /** Creates an unbound transform. The entity constructor binds it to a Lite node immediately. */
@@ -23202,7 +23433,8 @@ var ExtensionContextImpl = class {
23202
23433
  * @param schema - The schema the section is validated against.
23203
23434
  * @param defaults - The values used when the project omits the section.
23204
23435
  * @throws IgnifxError with code `IGX-0408` in development when the project's values do not
23205
- * validate against the schema.
23436
+ * validate against the schema, and with code `IGX-0607` when a field is named after an
23437
+ * `Object.prototype` member such as `constructor`.
23206
23438
  */
23207
23439
  registerSettings(section, schema, defaults) {
23208
23440
  this.#settings.register(section, schema, defaults, this.#extension.name);
@@ -24246,7 +24478,14 @@ var HotReloadHostImpl = class {
24246
24478
  for (let index = 0; index < plans.length; index += 1) {
24247
24479
  const plan = plans[index];
24248
24480
  if (plan === void 0) continue;
24249
- const info = world.registry.replace(plan.next).info;
24481
+ let info;
24482
+ try {
24483
+ info = world.registry.replace(plan.next).info;
24484
+ } catch (error) {
24485
+ errors.push(error);
24486
+ this.#report(error);
24487
+ continue;
24488
+ }
24250
24489
  instances += plan.policy === "patch" ? patchInstances(world, plan.previousInfo, info, plan.instances) : recreateInstances(world, plan.previousInfo, plan.next, info, plan.instances, (message) => {
24251
24490
  this.#log.warn(`hot reload: ${message}`);
24252
24491
  });
@@ -26614,9 +26853,10 @@ var SettingsStore = class {
26614
26853
  * @param defaults - The values used for everything the project omits, as a bag of named props.
26615
26854
  * @param owner - The extension registering the section, named in diagnostics.
26616
26855
  * @throws IgnifxError with code `IGX-0408` in development when the project's values do not
26617
- * validate.
26856
+ * validate, and with code `IGX-0607` when a field is named after an `Object.prototype` member.
26618
26857
  */
26619
26858
  register(name, schema, defaults, owner) {
26859
+ assertNoInheritedFieldNames(schema, "settings");
26620
26860
  const base = isPropertyBag(defaults) ? defaults : createDefaults(schema);
26621
26861
  const value = this.#resolve(name, schema, base);
26622
26862
  this.#sections.set(name, {
@@ -29175,7 +29415,8 @@ var Entity = class {
29175
29415
  * @returns The attached component.
29176
29416
  * @throws IgnifxError with code `IGX-0202` when the class does not allow multiple instances and
29177
29417
  * 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.
29418
+ * schema, `IGX-0209` when the class's `static requires` graph contains a cycle, and `IGX-0101`
29419
+ * when the entity has been destroyed.
29179
29420
  */
29180
29421
  addComponent(type, init) {
29181
29422
  const internals = this.#mutable("addComponent");
@@ -30892,7 +31133,8 @@ const TRANSFORM_CHANNELS = Object.freeze([
30892
31133
  *
30893
31134
  * @param path - The `path` string from the file.
30894
31135
  * @returns The parsed path.
30895
- * @throws IgnifxError with code `IGX-0609` when the path does not match the grammar.
31136
+ * @throws IgnifxError with code `IGX-0609` when the path does not match the grammar, or when a
31137
+ * property step is `__proto__`.
30896
31138
  *
30897
31139
  * @example
30898
31140
  * ```ts
@@ -30948,11 +31190,13 @@ function parseOverridePath(path) {
30948
31190
  component
30949
31191
  };
30950
31192
  if (fourth !== "props" || segments.length < 5) throw invalidPath(path, "a property override is <uid>/components/<uid>/props/<field>.");
31193
+ const steps = segments.slice(4);
31194
+ if (steps.includes("__proto__")) throw invalidPath(path, "\"__proto__\" is not a property name an override may address.");
30951
31195
  return {
30952
31196
  kind: "prop",
30953
31197
  entity,
30954
31198
  component,
30955
- steps: segments.slice(4)
31199
+ steps
30956
31200
  };
30957
31201
  }
30958
31202
  /**
@@ -31129,18 +31373,18 @@ function writeStep(container, steps, at, op, value, path, report) {
31129
31373
  const { [key]: _removed, ...rest } = copy;
31130
31374
  return rest;
31131
31375
  }
31132
- copy[key] = value;
31376
+ setOwnJsonProperty(copy, key, value);
31133
31377
  return copy;
31134
31378
  }
31135
- const next = copy[key];
31379
+ const next = Object.hasOwn(copy, key) ? copy[key] : void 0;
31136
31380
  const nextArray = asJsonArray(next);
31137
31381
  if (nextArray !== null) {
31138
- copy[key] = writeArrayStep(nextArray, steps, at + 1, op, value, path, report);
31382
+ setOwnJsonProperty(copy, key, writeArrayStep(nextArray, steps, at + 1, op, value, path, report));
31139
31383
  return copy;
31140
31384
  }
31141
31385
  const nextObject = asJsonObject(next);
31142
31386
  if (nextObject !== null) {
31143
- copy[key] = writeStep(nextObject, steps, at + 1, op, value, path, report);
31387
+ setOwnJsonProperty(copy, key, writeStep(nextObject, steps, at + 1, op, value, path, report));
31144
31388
  return copy;
31145
31389
  }
31146
31390
  report(`"${path}" descends into ${key}, which is not an object or an array.`);
@@ -31595,7 +31839,7 @@ function remapValue(value, keys) {
31595
31839
  rewritten[key] = keys.get(entry) ?? entry;
31596
31840
  continue;
31597
31841
  }
31598
- rewritten[key] = remapValue(entry, keys);
31842
+ setOwnJsonProperty(rewritten, key, remapValue(entry, keys));
31599
31843
  }
31600
31844
  return rewritten;
31601
31845
  }
@@ -31710,14 +31954,15 @@ function noAssets() {
31710
31954
  * @param remap - The table filled while the scene was being constructed.
31711
31955
  * @param assets - How an asset address becomes a handle; defaults to resolving nothing, which makes
31712
31956
  * every `asset()` field `null` with an `IGX-0602` issue.
31957
+ * @param outside - How a uid the remap does not hold resolves; omitted, it resolves to `null`.
31713
31958
  * @returns The decoder to hand `decodeProps`.
31714
31959
  *
31715
31960
  * @internal
31716
31961
  */
31717
- function remapDecoder(remap, assets = noAssets) {
31962
+ function remapDecoder(remap, assets = noAssets, outside) {
31718
31963
  return {
31719
- entity: (uid) => remap.entity(uid),
31720
- component: (uid) => remap.component(uid),
31964
+ entity: (uid) => remap.entity(uid) ?? outside?.entity(uid) ?? null,
31965
+ component: (uid) => remap.component(uid) ?? outside?.component(uid) ?? null,
31721
31966
  asset: (address, type) => assets(address, type)
31722
31967
  };
31723
31968
  }
@@ -31824,7 +32069,7 @@ function instantiateScene(world, asset, options) {
31824
32069
  createEntities(context, expanded.entities, parent);
31825
32070
  attachComponents(context);
31826
32071
  linkInstances(context, options?.assetHandle ?? null, options?.rootEntity ?? null);
31827
- decodeAllProps(context, sceneAssetResolver(world, asset));
32072
+ decodeAllProps(context, sceneAssetResolver(world, asset), options?.outsideReferences);
31828
32073
  activate(context);
31829
32074
  return {
31830
32075
  roots: context.roots,
@@ -31883,6 +32128,12 @@ function createEntities(context, entities, parent) {
31883
32128
  * Pass 2: attaches every component with its schema defaults, so the reference table is complete
31884
32129
  * before any prop is decoded.
31885
32130
  *
32131
+ * @remarks
32132
+ * A file may list a component before one its class `requires` (an editor reorder does that).
32133
+ * `addComponent` would then add a second, fresh instance of the required class, or throw `IGX-0202`
32134
+ * when the file's own record comes. So a record that a class requires is attached first, and the
32135
+ * entity's components are put back in file order afterwards.
32136
+ *
31886
32137
  * @param context - The build state.
31887
32138
  * @throws IgnifxError with code `IGX-0307` when the file names an unregistered component type: the
31888
32139
  * file cannot be honoured with a component missing, so this one is not recoverable.
@@ -31890,25 +32141,83 @@ function createEntities(context, entities, parent) {
31890
32141
  function attachComponents(context) {
31891
32142
  for (let index = 0; index < context.built.length; index += 1) {
31892
32143
  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
- }
32144
+ if (built !== void 0) attachEntityComponents(context, built);
32145
+ }
32146
+ }
32147
+ /**
32148
+ * Attaches one entity's component records, each record's required records first.
32149
+ *
32150
+ * @param context - The build state.
32151
+ * @param built - The entity and its file record.
32152
+ */
32153
+ function attachEntityComponents(context, built) {
32154
+ const registry = context.world.registry;
32155
+ const records = built.source.data.components;
32156
+ const types = records.map((record) => registeredType(context, record, built.source.data.uid));
32157
+ const attached = [];
32158
+ const started = /* @__PURE__ */ new Set();
32159
+ const order = [];
32160
+ const attach = (at) => {
32161
+ const record = records[at];
32162
+ const type = types[at];
32163
+ if (record === void 0 || type === void 0 || started.has(at)) return;
32164
+ started.add(at);
32165
+ const requires = registry.describe(type).requires;
32166
+ for (let inner = 0; inner < requires.length; inner += 1) {
32167
+ const required = requires[inner];
32168
+ if (required === void 0 || built.entity.getComponent(required) !== null) continue;
32169
+ const supplier = types.findIndex((candidate, other) => !started.has(other) && registry.describe(candidate).ancestors.includes(required));
32170
+ if (supplier >= 0) attach(supplier);
32171
+ }
32172
+ const component = built.entity.addComponent(type);
32173
+ componentInternals(component).uid = record.uid;
32174
+ if (record.enabled === false) component.enabled = false;
32175
+ context.remap.addComponent(record.uid, component);
32176
+ attached[at] = component;
32177
+ order.push(at);
32178
+ };
32179
+ for (let at = 0; at < records.length; at += 1) attach(at);
32180
+ for (let at = 0; at < attached.length; at += 1) {
32181
+ const component = attached[at];
32182
+ if (component !== void 0) built.components.push(component);
32183
+ }
32184
+ if (order.some((at, position) => at !== position)) restoreFileOrder(built.entity, built.components);
32185
+ }
32186
+ /**
32187
+ * Looks up a record's component class.
32188
+ *
32189
+ * @param context - The build state.
32190
+ * @param record - The component record.
32191
+ * @param entityUid - The owning entity's file uid, for the error.
32192
+ * @returns The registered class.
32193
+ * @throws IgnifxError with code `IGX-0307` when the type is not registered.
32194
+ */
32195
+ function registeredType(context, record, entityUid) {
32196
+ const type = context.world.registry.get(record.type);
32197
+ if (type === null) throw new IgnifxError(CoreErrorCode.unknownComponentTypeId, `${record.type} is not a registered component type.`, {
32198
+ context: {
32199
+ typeId: record.type,
32200
+ entity: entityUid
32201
+ },
32202
+ hint: "Register the class with app.registerComponents before loading a scene that uses it."
32203
+ });
32204
+ return type;
32205
+ }
32206
+ /**
32207
+ * Puts the file's components back in file order within the slots they occupy on the entity, so
32208
+ * `getComponent`, `awake` and a later save see the order the file wrote. Other components (the
32209
+ * transform, any auto-added one) keep their places.
32210
+ *
32211
+ * @param entity - The entity.
32212
+ * @param inFileOrder - The components the file listed, in file order.
32213
+ */
32214
+ function restoreFileOrder(entity, inFileOrder) {
32215
+ const list = entityInternals(entity).components;
32216
+ const slots = inFileOrder.map((component) => list.indexOf(component)).toSorted((a, b) => a - b);
32217
+ for (let at = 0; at < slots.length; at += 1) {
32218
+ const slot = slots[at];
32219
+ const component = inFileOrder[at];
32220
+ if (slot !== void 0 && component !== void 0) list[slot] = component;
31912
32221
  }
31913
32222
  }
31914
32223
  /**
@@ -32018,9 +32327,10 @@ function instancedRoot(context, instance, source) {
32018
32327
  *
32019
32328
  * @param context - The build state.
32020
32329
  * @param assets - How an `asset()` field's address becomes the handle the scene already retains.
32330
+ * @param outside - How a uid the build made nothing with resolves, if at all.
32021
32331
  */
32022
- function decodeAllProps(context, assets) {
32023
- const decoder = remapDecoder(context.remap, assets);
32332
+ function decodeAllProps(context, assets, outside) {
32333
+ const decoder = remapDecoder(context.remap, assets, outside);
32024
32334
  for (let index = 0; index < context.built.length; index += 1) {
32025
32335
  const built = context.built[index];
32026
32336
  if (built === void 0) continue;
@@ -34544,18 +34854,18 @@ function transformSchema() {
34544
34854
  function describeSchemas() {
34545
34855
  return {
34546
34856
  "ignifx/Transform": describeSchema("ignifx/Transform", transformSchema(), {
34547
- description: "The entity's local position, rotation, and scale; every entity has exactly one, stored as its transform block.",
34857
+ description: Transform.description,
34548
34858
  allowMultiple: false,
34549
34859
  package: "@ignifx/core",
34550
34860
  builtIn: true
34551
34861
  }),
34552
- "ignifx/Camera": describeSchema("ignifx/Camera", Camera.schema, { description: "The camera an entity renders the world through; the entity's transform is the view." }),
34553
- "ignifx/Light": describeSchema("ignifx/Light", Light.schema, { description: "A directional, point, spot, or hemispheric light, with optional shadow casting." }),
34554
- "ignifx/MeshRenderer": describeSchema("ignifx/MeshRenderer", MeshRenderer.schema, { description: "Draws one clone of a mesh asset with a material." }),
34555
- "ignifx/InstancedMeshRenderer": describeSchema("ignifx/InstancedMeshRenderer", InstancedMeshRenderer.schema, { description: "Draws one mesh many times from a caller-owned matrix slab, in a single draw call, with optional GPU culling and a coarser mesh for far instances." }),
34556
- "ignifx/Model": describeSchema("ignifx/Model", Model.schema, { description: "One instance of a loaded glTF, cloned under the entity's node." }),
34557
- "ignifx/Environment": describeSchema("ignifx/Environment", Environment.schema, { description: "The world's image-based lighting, skybox, fog, image processing, and clear colour." }),
34558
- "ignifx/PostProcessStack": describeSchema("ignifx/PostProcessStack", PostProcessStack.schema, { description: "Bloom, SMAA, image processing, and custom .post.wgsl effects, inserted into the scene's frame graph." }),
34862
+ "ignifx/Camera": describeSchema("ignifx/Camera", Camera.schema, { description: Camera.description }),
34863
+ "ignifx/Light": describeSchema("ignifx/Light", Light.schema, { description: Light.description }),
34864
+ "ignifx/MeshRenderer": describeSchema("ignifx/MeshRenderer", MeshRenderer.schema, { description: MeshRenderer.description }),
34865
+ "ignifx/InstancedMeshRenderer": describeSchema("ignifx/InstancedMeshRenderer", InstancedMeshRenderer.schema, { description: InstancedMeshRenderer.description }),
34866
+ "ignifx/Model": describeSchema("ignifx/Model", Model.schema, { description: Model.description }),
34867
+ "ignifx/Environment": describeSchema("ignifx/Environment", Environment.schema, { description: Environment.description }),
34868
+ "ignifx/PostProcessStack": describeSchema("ignifx/PostProcessStack", PostProcessStack.schema, { description: PostProcessStack.description }),
34559
34869
  "ignifx/scene-file": describeSceneFileFormat(),
34560
34870
  "ignifx/material-file": describeMaterialFileFormat(),
34561
34871
  "ignifx/environment-file": describeEnvironmentFileFormat(),
@@ -35526,7 +35836,8 @@ function componentPackage(registry, typeId) {
35526
35836
  /**
35527
35837
  * Describes every component an app has registered, the engine's, its extensions' and the game's,
35528
35838
  * 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`).
35839
+ * entity may hold more than one (`allowMultiple`), which package registered it (`package`), and
35840
+ * which components it adds when they are missing (`requires`, its classes' type ids).
35530
35841
  * This is what an external inspector, such as the ignifx editor, is generated from.
35531
35842
  *
35532
35843
  * @remarks
@@ -35539,9 +35850,14 @@ function componentPackage(registry, typeId) {
35539
35850
  * and marked `builtIn`, because every entity carries exactly one and a scene file stores it as the
35540
35851
  * entity's `transform` block rather than in its `components`.
35541
35852
  *
35853
+ * A component's `title` and `description` come from `curated` when it has an entry, else from the
35854
+ * class's own `static title` and `static description`, which is how an extension's components
35855
+ * reach an inspector with their curated names without the inspector importing the extension.
35856
+ *
35542
35857
  * @param registry - The registry to walk, usually `app.world.registry`.
35543
35858
  * @param curated - Titles, formats and summaries by type id, for example a package's own
35544
- * `describeSchemas()`; a component without an entry is titled from its type id.
35859
+ * `describeSchemas()`; an entry wins over the class's own `static title` and `static description`, and a component
35860
+ * with neither is titled from its type id.
35545
35861
  * @returns The descriptions, keyed by type id, in registration order.
35546
35862
  *
35547
35863
  * @example
@@ -35549,6 +35865,7 @@ function componentPackage(registry, typeId) {
35549
35865
  * const schemas = describeRegisteredSchemas(app.world.registry, describeSchemas());
35550
35866
  * schemas["ignifx/Camera"]?.package; // "@ignifx/core"
35551
35867
  * schemas["ignifx/Camera"]?.allowMultiple; // false
35868
+ * schemas["ignifx/ThirdPersonController"]?.requires; // ["ignifx/CharacterController"] once @ignifx/3d is registered
35552
35869
  * ```
35553
35870
  *
35554
35871
  * @public
@@ -35559,13 +35876,16 @@ function describeRegisteredSchemas(registry, curated) {
35559
35876
  const info = registry.describe(type);
35560
35877
  const meta = curated?.[typeId];
35561
35878
  const builtIn = type === Transform;
35879
+ const title = meta?.title ?? info.title;
35880
+ const description = meta?.description ?? info.description;
35562
35881
  described[typeId] = describeSchema(typeId, builtIn ? transformSchema() : info.schema ?? {}, {
35563
- ...meta?.title === void 0 ? {} : { title: meta.title },
35882
+ ...title === null ? {} : { title },
35564
35883
  ...meta?.format === void 0 ? {} : { format: meta.format },
35565
- ...meta?.description === void 0 ? {} : { description: meta.description },
35884
+ ...description === null ? {} : { description },
35566
35885
  allowMultiple: info.allowMultiple,
35567
35886
  package: componentPackage(registry, typeId),
35568
- ...builtIn ? { builtIn } : {}
35887
+ ...builtIn ? { builtIn } : {},
35888
+ ...info.requires.length === 0 ? {} : { requires: info.requires.map((required) => required.typeId ?? null) }
35569
35889
  });
35570
35890
  }
35571
35891
  return described;
@@ -35714,7 +36034,7 @@ function entriesToJson(entries, convert) {
35714
36034
  const object = {};
35715
36035
  for (const [name, value] of entries) {
35716
36036
  const converted = convert(value, name);
35717
- if (converted !== void 0) object[name] = converted;
36037
+ if (converted !== void 0) setOwnJsonProperty(object, name, converted);
35718
36038
  }
35719
36039
  return object;
35720
36040
  }