@ignifx/core 0.10.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/decoders/babylon.ktx2Decoder.js +1 -0
  2. package/decoders/babylonjs-ktx2decoder.LICENSE.md +71 -0
  3. package/decoders/meshopt_decoder.js +199 -0
  4. package/decoders/meshoptimizer.LICENSE.md +21 -0
  5. package/decoders/msc_basis_transcoder.js +22 -0
  6. package/decoders/msc_basis_transcoder.wasm +0 -0
  7. package/decoders/scoped-babylonjs-ktx2decoder.LICENSE.md +396 -0
  8. package/decoders/scoped-babylonjs-ktx2decoder.NOTICE.md +15 -0
  9. package/decoders/uastc_astc.wasm +0 -0
  10. package/decoders/uastc_bc7.wasm +0 -0
  11. package/decoders/uastc_r8_unorm.wasm +0 -0
  12. package/decoders/uastc_rg8_unorm.wasm +0 -0
  13. package/decoders/uastc_rgba8_srgb_v2.wasm +0 -0
  14. package/decoders/uastc_rgba8_unorm_v2.wasm +0 -0
  15. package/decoders/vendored.json +96 -0
  16. package/decoders/zstddec.wasm +0 -0
  17. package/dist/decoders-CHJ7vduE.js +82 -0
  18. package/dist/decoders-CHJ7vduE.js.map +1 -0
  19. package/dist/{environment-BCjfp1jB.js → environment-C9AjYJgV.js} +2 -2
  20. package/dist/{environment-BCjfp1jB.js.map → environment-C9AjYJgV.js.map} +1 -1
  21. package/dist/{ignifx-error-RpK-lWwE.js → ignifx-error-Dq2qJMkZ.js} +10 -3
  22. package/dist/ignifx-error-Dq2qJMkZ.js.map +1 -0
  23. package/dist/index.d.ts +191 -17
  24. package/dist/index.d.ts.map +1 -1
  25. package/dist/index.js +665 -86
  26. package/dist/index.js.map +1 -1
  27. package/dist/json-CzZZ6K4x.js +24 -0
  28. package/dist/json-CzZZ6K4x.js.map +1 -0
  29. package/dist/{material-plugin-CWtV7DkH.js → material-plugin-BOCB7Stt.js} +2 -2
  30. package/dist/{material-plugin-CWtV7DkH.js.map → material-plugin-BOCB7Stt.js.map} +1 -1
  31. package/dist/{post-effect-C42XJFmo.js → post-effect-BHl7U56q.js} +5 -4
  32. package/dist/post-effect-BHl7U56q.js.map +1 -0
  33. package/dist/{post-effect-compiler-pOvXae-i.js → post-effect-compiler-Dw6zW2cG.js} +3 -3
  34. package/dist/{post-effect-compiler-pOvXae-i.js.map → post-effect-compiler-Dw6zW2cG.js.map} +1 -1
  35. package/dist/{shader-material-B6wwFCKB.js → shader-material-BxQn9FT4.js} +2 -2
  36. package/dist/{shader-material-B6wwFCKB.js.map → shader-material-BxQn9FT4.js.map} +1 -1
  37. package/dist/{shader-material-C4VjLTfV.js → shader-material-DRZmqA_S.js} +10 -6
  38. package/dist/shader-material-DRZmqA_S.js.map +1 -0
  39. package/dist/{shader-pragma-qO9_6sTd.js → shader-pragma-DrFm5f5m.js} +2 -2
  40. package/dist/{shader-pragma-qO9_6sTd.js.map → shader-pragma-DrFm5f5m.js.map} +1 -1
  41. package/dist/{surface-shader-BaR7Kg-F.js → surface-shader-BgZchRBe.js} +4 -4
  42. package/dist/{surface-shader-BaR7Kg-F.js.map → surface-shader-BgZchRBe.js.map} +1 -1
  43. package/package.json +20 -2
  44. package/LICENSE +0 -201
  45. package/dist/ignifx-error-RpK-lWwE.js.map +0 -1
  46. package/dist/post-effect-C42XJFmo.js.map +0 -1
  47. package/dist/shader-material-C4VjLTfV.js.map +0 -1
package/dist/index.d.ts CHANGED
@@ -147,6 +147,8 @@ export declare const CoreErrorCode: {
147
147
  readonly hotReloadSchemaChanged: "IGX-0207";
148
148
  /** `app.hotReload.apply()` was called from inside a lifecycle callback. */
149
149
  readonly hotReloadInsideCallback: "IGX-0208";
150
+ /** A component class's `static requires` chain loops, through the class itself or a class it requires. */
151
+ readonly requiresCycle: "IGX-0209";
150
152
  /** A scene was instantiated before it had finished loading. */
151
153
  readonly sceneNotLoaded: "IGX-0301";
152
154
  /** Instantiating a scene would place an instance inside itself. */
@@ -211,7 +213,11 @@ export declare const CoreErrorCode: {
211
213
  readonly schemaTypeMismatch: "IGX-0605";
212
214
  /** A value had the right type but fell outside its schema field's declared value domain. */
213
215
  readonly schemaOutOfRange: "IGX-0606";
214
- /** A schema declaration or a property bag named a field the schema does not declare. */
216
+ /**
217
+ * A property bag named a field the schema does not declare, or a schema declaration named a field
218
+ * it may not use: not identifier-like, a `Component`/`Script` member, or an `Object.prototype`
219
+ * member such as `constructor` or `__proto__`.
220
+ */
215
221
  readonly schemaUnknownField: "IGX-0607";
216
222
  /** A scene file failed structural validation against the generated scene-file JSON Schema. */
217
223
  readonly sceneFileInvalid: "IGX-0608";
@@ -1953,7 +1959,9 @@ export declare class ComponentRegistry {
1953
1959
  * an id is kept, and {@link ComponentRegistry.registrarOf} reports it.
1954
1960
  * @returns What the registry worked out about the class.
1955
1961
  * @throws IgnifxError with code `IGX-0203` when the id is already registered by another class, or
1956
- * when the id is not `<namespace>/<Name>`.
1962
+ * when the id is not `<namespace>/<Name>`, `IGX-0209` when the class's `static requires`
1963
+ * graph contains a cycle, and `IGX-0607` when its `static schema` names a field after an
1964
+ * `Object.prototype` member.
1957
1965
  */
1958
1966
  register(type: ConcreteComponentType, typeId?: string, registrar?: string): ComponentClassInfo;
1959
1967
  /**
@@ -1990,7 +1998,10 @@ export declare class ComponentRegistry {
1990
1998
  *
1991
1999
  * @param type - The replacement class. It must declare the `typeId` it replaces.
1992
2000
  * @returns The freshly built info for the replacement, and the class it replaced.
1993
- * @throws IgnifxError with code `IGX-0204` when the replacement declares no `typeId`.
2001
+ * @throws IgnifxError with code `IGX-0204` when the replacement declares no `typeId`,
2002
+ * `IGX-0209` when its `static requires` graph contains a cycle, and `IGX-0607` when its
2003
+ * `static schema` names a field after an `Object.prototype` member; in every case the registry is
2004
+ * left unchanged.
1994
2005
  *
1995
2006
  * @example
1996
2007
  * ```ts
@@ -2005,6 +2016,8 @@ export declare class ComponentRegistry {
2005
2016
  *
2006
2017
  * @param type - The component class.
2007
2018
  * @returns The cached class info.
2019
+ * @throws IgnifxError with code `IGX-0209` when the class's `static requires` graph contains a
2020
+ * cycle, and `IGX-0607` when its `static schema` names a field after an `Object.prototype` member.
2008
2021
  */
2009
2022
  describe(type: ComponentType): ComponentClassInfo;
2010
2023
  /**
@@ -4099,6 +4112,14 @@ interface SchemaDescription {
4099
4112
  * prop by prop. Absent on every other component and on file formats.
4100
4113
  */
4101
4114
  readonly builtIn?: boolean;
4115
+ /**
4116
+ * The components the class lists in `static requires`, as type ids (`null` for a class without a
4117
+ * `typeId`), in declaration order. `addComponent` adds each one that is missing, so an editor adds
4118
+ * them itself, and a scene file may list them in any order. A component on the entity whose class
4119
+ * extends a required class counts as present. Set by {@link describeRegisteredSchemas}, or by the
4120
+ * caller through {@link SchemaDescriptionMeta}; absent when the class requires nothing.
4121
+ */
4122
+ readonly requires?: readonly (string | null)[];
4102
4123
  }
4103
4124
  /**
4104
4125
  * Optional overrides for {@link describeSchema}.
@@ -4118,6 +4139,8 @@ interface SchemaDescriptionMeta {
4118
4139
  readonly package?: string;
4119
4140
  /** Whether the component is the entity's own built-in block, copied onto the description. */
4120
4141
  readonly builtIn?: boolean;
4142
+ /** The type ids of the components the class requires, copied onto the description. */
4143
+ readonly requires?: readonly (string | null)[];
4121
4144
  }
4122
4145
  /**
4123
4146
  * A JSON Schema fragment. Kept as a plain JSON object because the generated document is assembled
@@ -4139,7 +4162,7 @@ type JsonSchemaObject = JsonObject;
4139
4162
  * @param typeId - The component's namespaced registration id, for example `mygame/Mover`.
4140
4163
  * @param schema - The component's declared fields.
4141
4164
  * @param meta - Overrides for the title, format grouping, and summary, and the component's
4142
- * `allowMultiple`, `package` and `builtIn` when the caller knows them.
4165
+ * `allowMultiple`, `package`, `builtIn` and `requires` when the caller knows them.
4143
4166
  * @returns The description entry.
4144
4167
  *
4145
4168
  * @example
@@ -4489,7 +4512,11 @@ export declare const SchemaIssueCode: {
4489
4512
  readonly typeMismatch: "IGX-0605";
4490
4513
  /** A value had the right type but fell outside the field's declared value domain. */
4491
4514
  readonly outOfRange: "IGX-0606";
4492
- /** A property was supplied that the schema does not declare. */
4515
+ /**
4516
+ * A property was supplied that the schema does not declare, or a schema declaration named a field
4517
+ * it may not use: not identifier-like, a `Component`/`Script` member, or an `Object.prototype`
4518
+ * member such as `constructor` or `__proto__`.
4519
+ */
4493
4520
  readonly unknownField: "IGX-0607";
4494
4521
  };
4495
4522
  /**
@@ -4928,8 +4955,8 @@ export declare abstract class Script extends Component {
4928
4955
  * @typeParam S - The schema being declared.
4929
4956
  * @param schema - The field definitions, keyed by the property name they become.
4930
4957
  * @returns An abstract class to extend.
4931
- * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like or collides
4932
- * with a `Component`/`Script` member.
4958
+ * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like, collides
4959
+ * with a `Component`/`Script` member, or names an `Object.prototype` member such as `constructor`.
4933
4960
  *
4934
4961
  * @example
4935
4962
  * ```ts
@@ -8211,6 +8238,24 @@ interface Renderer {
8211
8238
  resolutionScale: number;
8212
8239
  /** Whether per-task GPU timings are collected. Off by default; it costs timestamp queries. */
8213
8240
  profileTasks: boolean;
8241
+ /**
8242
+ * Whether the shader clock runs in an edit-mode app (ADR-0028, amendment of 2026-10-20): an
8243
+ * editor's "animate materials" toggle. `true` by default.
8244
+ *
8245
+ * @remarks
8246
+ * The clock is the `time`, `unscaledTime` and `deltaTime` that shader materials and custom post
8247
+ * effects declare. While this is `false` in an edit-mode app the clock stands still, as it does
8248
+ * under `app.pause()`: `time` keeps its value, `deltaTime` is `0`, and setting it back to `true`
8249
+ * resumes from there without a jump. The main-light and ambient uniforms stay live either way.
8250
+ * Outside edit mode the value is ignored and the clock always runs.
8251
+ *
8252
+ * @example
8253
+ * ```ts
8254
+ * const app = await createApp({ canvas, editMode: true });
8255
+ * app.renderer.animateMaterialsInEditMode = false; // the editor's toggle is off
8256
+ * ```
8257
+ */
8258
+ animateMaterialsInEditMode: boolean;
8214
8259
  /** Which rendering features are on. Read-only once `app.start()` has registered the scene. */
8215
8260
  readonly features: Readonly<RenderingFeatureSettings>;
8216
8261
  /**
@@ -8471,6 +8516,47 @@ declare class RendererImpl implements Renderer {
8471
8516
  */
8472
8517
  get profileTasks(): boolean;
8473
8518
  set profileTasks(value: boolean);
8519
+ /**
8520
+ * Whether the shader clock runs in an edit-mode app.
8521
+ *
8522
+ * @returns `true` unless an editor turned material animation off.
8523
+ */
8524
+ get animateMaterialsInEditMode(): boolean;
8525
+ set animateMaterialsInEditMode(value: boolean);
8526
+ /**
8527
+ * Records this frame's shader clock, as `ShaderUniformSystem` accumulated it: the one clock both
8528
+ * shader materials and, in edit mode, custom post effects read.
8529
+ *
8530
+ * @param time - Scaled seconds the clock has run.
8531
+ * @param unscaledTime - Unscaled seconds the clock has run.
8532
+ * @param deltaTime - This frame's step; `0` while the clock is held.
8533
+ *
8534
+ * @internal
8535
+ */
8536
+ setShaderClock(time: number, unscaledTime: number, deltaTime: number): void;
8537
+ /**
8538
+ * Whether the shader clock stands still this frame because an edit-mode app turned material
8539
+ * animation off. `app.pause()` is checked separately, by each reader.
8540
+ *
8541
+ * @returns `true` while the editor's toggle holds the clock.
8542
+ *
8543
+ * @internal
8544
+ */
8545
+ get isShaderClockHeld(): boolean;
8546
+ /**
8547
+ * The clock custom post effects upload. In an edit-mode app it is the shader clock materials read
8548
+ * (`setShaderClock`), so the two never drift apart when the editor holds and resumes it
8549
+ * (ADR-0028, amendment of 2026-10-20). A game keeps the app's own clock.
8550
+ *
8551
+ * @returns The clock.
8552
+ *
8553
+ * @internal
8554
+ */
8555
+ get effectClock(): {
8556
+ readonly time: number;
8557
+ readonly unscaledTime: number;
8558
+ readonly deltaTime: number;
8559
+ };
8474
8560
  /**
8475
8561
  * GPU draw calls in the last rendered frame.
8476
8562
  *
@@ -9532,6 +9618,15 @@ interface InstantiateSceneOptions {
9532
9618
  readonly rootEntity?: Entity | null;
9533
9619
  /** `true` turns an `IGX-0604` hash mismatch from a diagnostic into a throw. */
9534
9620
  readonly strictInstanceHashes?: boolean;
9621
+ /**
9622
+ * How an `entityRef` or `componentRef` resolves when the build made nothing with its uid: a uid
9623
+ * the file does not declare, or one of a component an instance's `remove` override deleted. A
9624
+ * tool that builds part of a larger document, such as an editor rebuilding one prefab instance,
9625
+ * resolves the rest of the document here, so the part decodes as the whole file would; this
9626
+ * includes a reference an instance's overrides hold. The uids the build made come first, and
9627
+ * `asset()` fields never use it. Omitted, such a reference is `null` with an `IGX-0602` issue.
9628
+ */
9629
+ readonly outsideReferences?: Pick<ReferenceDecoder, "entity" | "component">;
9535
9630
  }
9536
9631
  /**
9537
9632
  * What {@link instantiateScene} produced.
@@ -10881,7 +10976,8 @@ export declare class Entity {
10881
10976
  * @returns The attached component.
10882
10977
  * @throws IgnifxError with code `IGX-0202` when the class does not allow multiple instances and
10883
10978
  * the entity already has one, `IGX-0605`/`IGX-0606`/`IGX-0607` when `init` does not match the
10884
- * schema, and `IGX-0101` when the entity has been destroyed.
10979
+ * schema, `IGX-0209` when the class's `static requires` graph contains a cycle, and `IGX-0101`
10980
+ * when the entity has been destroyed.
10885
10981
  */
10886
10982
  addComponent<T extends Component>(type: ConcreteComponentType<T>, init?: ComponentInit<T>): T;
10887
10983
  /**
@@ -11117,8 +11213,8 @@ export declare abstract class Component implements SignalOwner {
11117
11213
  * @typeParam S - The schema being declared.
11118
11214
  * @param schema - The field definitions, keyed by the property name they become.
11119
11215
  * @returns An abstract class to extend.
11120
- * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like or collides
11121
- * with a `Component`/`Script` member.
11216
+ * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like, collides
11217
+ * with a `Component`/`Script` member, or names an `Object.prototype` member such as `constructor`.
11122
11218
  *
11123
11219
  * @example
11124
11220
  * ```ts
@@ -11262,6 +11358,15 @@ interface ComponentHooks {
11262
11358
  onAttach?(): void;
11263
11359
  /** Runs just before the component is removed, after `onDestroy`. */
11264
11360
  onDetach?(): void;
11361
+ /**
11362
+ * Runs after a tool changed the component's serialized fields from outside it: an editor's
11363
+ * inspector or document op, or a hot reload that gave a field its new default. The engine's own
11364
+ * loads and a script's assignments do not call it. A component that builds something from its
11365
+ * fields (a physics shape, say) rebuilds it here. Not gated in edit mode (ADR-0028).
11366
+ *
11367
+ * @param fields - The names of the fields that changed.
11368
+ */
11369
+ onValidate?(fields: readonly string[]): void;
11265
11370
  }
11266
11371
  /**
11267
11372
  * The abstract base class `Component.define` returns: a `Component` that also carries every
@@ -11880,7 +11985,9 @@ interface HotReloadHost {
11880
11985
  * Applies replaced component classes to the running app.
11881
11986
  *
11882
11987
  * @param modules - The replaced modules and the classes they export.
11883
- * @returns What was reloaded.
11988
+ * @returns What was reloaded. A replacement the registry refuses — for example one whose
11989
+ * `static requires` loops (`IGX-0209`) — is collected in `errors`, and the class it would have
11990
+ * replaced stays registered.
11884
11991
  * @throws IgnifxError with code `IGX-0208` when called from inside a lifecycle callback, where a
11885
11992
  * half-swapped world would be observable.
11886
11993
  */
@@ -11891,7 +11998,7 @@ interface HotReloadHost {
11891
11998
  *
11892
11999
  * @param instance - The instance to rebuild. It is unloaded and a fresh one takes its place.
11893
12000
  * @returns The new instance.
11894
- * @throws IgnifxError with code `IGX-0209` when the instance was not built from a scene asset.
12001
+ * @throws IgnifxError with code `IGX-1506` when the instance was not built from a scene asset.
11895
12002
  */
11896
12003
  reloadScene(instance: SceneInstance): Promise<SceneInstance>;
11897
12004
  }
@@ -17119,6 +17226,13 @@ export declare class ModelAsset {
17119
17226
  * asset pipeline produces, and the fix — passing the URL through for that one shape — is a
17120
17227
  * three-line change whenever a project needs it.
17121
17228
  *
17229
+ * ## Decoders
17230
+ *
17231
+ * A glTF may need one of Lite's run-time decoders: `KHR_texture_basisu` images go through the KTX2
17232
+ * decoder and `EXT_meshopt_compression` buffers through the meshopt decoder. Both load from
17233
+ * `cdn.babylonjs.com` unless told otherwise, so the loader calls `configureDecoders` first, which
17234
+ * points Lite at the copies `@ignifx/vite-plugin` serves (`../decoder-urls.ts`).
17235
+ *
17122
17236
  * ## Headless
17123
17237
  *
17124
17238
  * `loadGltf` throws a `TypeError` under the null engine: it uploads while parsing and reaches for
@@ -17156,6 +17270,17 @@ export declare function createModelLoader(): AssetLoader<ModelAsset>;
17156
17270
  * one place §5's "the three `fetch*` methods are the only network paths" does not hold; the
17157
17271
  * alternative is worse.
17158
17272
  *
17273
+ * ## The container picks the decoder
17274
+ *
17275
+ * `.png`, `.jpg`, `.jpeg` and `.webp` go to `loadTexture2D` and the browser's image decoder.
17276
+ * `.ktx2` goes to Lite's KTX2 loader and `.basis` to its Basis loader, which transcode to the
17277
+ * device's best compressed format (`src/lite/gpu/decoders.ts` lists the targets); handing either
17278
+ * to `createImageBitmap` fails with "The source image could not be decoded". The asset type stays
17279
+ * `texture` for all six, so the choice is made here, from the address's extension — the one name a
17280
+ * manifest entry, a hashed build URL and a hand-written `{ type: "texture" }` load all keep. Before
17281
+ * a KTX2 or Basis load, {@link configureDecoders} points Lite at the decoders the manifest lists,
17282
+ * which is how a built game avoids `cdn.babylonjs.com`.
17283
+ *
17159
17284
  * ## Options come from the sidecar
17160
17285
  *
17161
17286
  * `.meta.json` sidecars carry per-asset import options (§7), the build copies them into the
@@ -17265,6 +17390,11 @@ export declare function meshFileJsonSchema(): JsonSchemaObject;
17265
17390
  * flag flips. That is `07-rendering.md` §2.3's rule, and the browser test asserts both halves: the
17266
17391
  * pixel returns to the clear colour, and the mesh is still in the scene.
17267
17392
  *
17393
+ * `displayHidden` hides the same way, and makes the clone unpickable too, but is not a field: scene
17394
+ * files do not save it, so a system
17395
+ * that chooses what is drawn without changing the document (a `LodGroup` in an edit-mode app,
17396
+ * ADR-0028) switches it instead of `enabled`.
17397
+ *
17268
17398
  * ## Decisions the documents left open
17269
17399
  *
17270
17400
  * - **The clone's Lite `id` is the entity's uid.** Lite's light include/exclude lists match on
@@ -17318,9 +17448,42 @@ export declare class MeshRenderer extends Component implements ComponentHooks {
17318
17448
  get lite(): {
17319
17449
  readonly mesh: LiteSceneNode | null;
17320
17450
  };
17451
+ /**
17452
+ * A display-only hide: while `true` the mesh is neither drawn nor picked, whatever `enabled` and
17453
+ * `pickable` say.
17454
+ *
17455
+ * @remarks
17456
+ * It is not a schema field, so scene files do not save it, a serializer never reads it, and
17457
+ * `enabled` keeps its authored value. That makes it the switch for a system that chooses what is
17458
+ * drawn without changing the document: `@ignifx/3d`'s `LodGroup` uses it in place of `enabled` in
17459
+ * an edit-mode app (ADR-0028). It starts `false` and takes effect at the next render sync;
17460
+ * {@link MeshRenderer.isVisible} reports the outcome. Lite's pickers ignore visibility, so the
17461
+ * clone is also made unpickable while hidden: `app.renderer.pickAsync` and `world.raycastRender`
17462
+ * neither return it nor let it occlude, as with `pickable: false`.
17463
+ *
17464
+ * It is one flag with one owner, not a count. In an edit-mode app the `LodGroup` that lists the
17465
+ * renderer as a level owns it: the group sets and clears it whenever it switches, so a value
17466
+ * written by anything else lasts only until then. A renderer belongs to at most one `LodGroup`; a
17467
+ * second group that lists it leaves it alone and warns with `IGX-1217`.
17468
+ *
17469
+ * @returns `true` while the mesh is hidden for display.
17470
+ *
17471
+ * @example
17472
+ * ```ts
17473
+ * renderer.displayHidden = true; // not drawn, and `renderer.enabled` is still `true`
17474
+ * ```
17475
+ */
17476
+ get displayHidden(): boolean;
17477
+ /**
17478
+ * Hides the mesh for display, or shows it again; `enabled` is not touched.
17479
+ *
17480
+ * @param value - `true` to hide it.
17481
+ */
17482
+ set displayHidden(value: boolean);
17321
17483
  /**
17322
17484
  * Whether the mesh is currently drawn: its own `enabled` flag and its entity's
17323
- * `activeInHierarchy`, materialised onto Lite's `visible`.
17485
+ * `activeInHierarchy`, less {@link MeshRenderer.displayHidden}, materialised onto Lite's
17486
+ * `visible`.
17324
17487
  *
17325
17488
  * @returns `true` when the clone is visible.
17326
17489
  */
@@ -18357,7 +18520,8 @@ type EntityOverrideField = "name" | "active" | "static" | "layer" | "tags";
18357
18520
  *
18358
18521
  * @param path - The `path` string from the file.
18359
18522
  * @returns The parsed path.
18360
- * @throws IgnifxError with code `IGX-0609` when the path does not match the grammar.
18523
+ * @throws IgnifxError with code `IGX-0609` when the path does not match the grammar, or when a
18524
+ * property step is `__proto__`.
18361
18525
  *
18362
18526
  * @example
18363
18527
  * ```ts
@@ -18571,6 +18735,10 @@ interface SceneFileIssue {
18571
18735
  * (`CONSTITUTION.md` §2.3). The generated document remains the artefact the Vite plugin and editors
18572
18736
  * validate against; this is the same rule set, executable at load time.
18573
18737
  *
18738
+ * Two checks go beyond what JSON Schema can say: uids are unique within the file, and no two
18739
+ * overrides of one instance share an identity (path, `op`, and an added component's uid), both
18740
+ * reported as issues like any other.
18741
+ *
18574
18742
  * Component `props` are *not* checked here: `decodeProps` already reports every field problem with
18575
18743
  * a schema issue code, per field, which is more precise than a document-level match.
18576
18744
  *
@@ -18593,7 +18761,8 @@ export declare function validateSceneFile(value: unknown): readonly SceneFileIss
18593
18761
  /**
18594
18762
  * Describes every component an app has registered, the engine's, its extensions' and the game's,
18595
18763
  * the way {@link describeSchema} describes one, plus what only the registry knows: whether an
18596
- * entity may hold more than one (`allowMultiple`) and which package registered it (`package`).
18764
+ * entity may hold more than one (`allowMultiple`), which package registered it (`package`), and
18765
+ * which components it adds when they are missing (`requires`, its classes' type ids).
18597
18766
  * This is what an external inspector, such as the ignifx editor, is generated from.
18598
18767
  *
18599
18768
  * @remarks
@@ -18616,6 +18785,7 @@ export declare function validateSceneFile(value: unknown): readonly SceneFileIss
18616
18785
  * const schemas = describeRegisteredSchemas(app.world.registry, describeSchemas());
18617
18786
  * schemas["ignifx/Camera"]?.package; // "@ignifx/core"
18618
18787
  * schemas["ignifx/Camera"]?.allowMultiple; // false
18788
+ * schemas["ignifx/ThirdPersonController"]?.requires; // ["ignifx/CharacterController"] once @ignifx/3d is registered
18619
18789
  * ```
18620
18790
  *
18621
18791
  * @public
@@ -18877,6 +19047,8 @@ export declare function array<T>(item: FieldDefinition<T>, defaultValue?: readon
18877
19047
  * @param fields - The sub-fields.
18878
19048
  * @param options - Inspector and serializer metadata.
18879
19049
  * @returns The field definition.
19050
+ * @throws IgnifxError with code `IGX-0607` when a sub-field name is an `Object.prototype` member
19051
+ * such as `__proto__`, `constructor`, or `toString`.
18880
19052
  *
18881
19053
  * @example
18882
19054
  * ```ts
@@ -18989,8 +19161,10 @@ export declare function custom<T>(codec: CustomFieldCodec<T>, options?: FieldOpt
18989
19161
  *
18990
19162
  * @param fields - The field definitions, keyed by the property name they become.
18991
19163
  * @returns The same object, with its precise type preserved.
18992
- * @throws A `TypeError` when a field name is not identifier-like, starts with `_`, or collides with
18993
- * a `Component`/`Script` member such as `enabled` or `update`.
19164
+ * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like, starts with
19165
+ * `_`, collides with a `Component`/`Script` member such as `enabled` or `update`, or names an
19166
+ * `Object.prototype` member such as `constructor` or `toString`, or when `fields` is not a plain
19167
+ * object (a literal `__proto__: …` key sets its prototype rather than declaring a field).
18994
19168
  *
18995
19169
  * @example
18996
19170
  * ```ts