@ignifx/core 0.9.0 → 0.11.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 (43) 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-mr5wp69e.js → environment-BCjfp1jB.js} +2 -2
  20. package/dist/{environment-mr5wp69e.js.map → environment-BCjfp1jB.js.map} +1 -1
  21. package/dist/{ignifx-error-CRh89KUJ.js → ignifx-error-RpK-lWwE.js} +13 -2
  22. package/dist/ignifx-error-RpK-lWwE.js.map +1 -0
  23. package/dist/index.d.ts +1682 -680
  24. package/dist/index.d.ts.map +1 -1
  25. package/dist/index.js +2675 -240
  26. package/dist/index.js.map +1 -1
  27. package/dist/{material-plugin-BRnhfw7K.js → material-plugin-CWtV7DkH.js} +2 -2
  28. package/dist/{material-plugin-BRnhfw7K.js.map → material-plugin-CWtV7DkH.js.map} +1 -1
  29. package/dist/overlay-CjVgsfrm.js +239 -0
  30. package/dist/overlay-CjVgsfrm.js.map +1 -0
  31. package/dist/{post-effect-compiler-Rce26Eue.js → post-effect-compiler-pOvXae-i.js} +2 -2
  32. package/dist/{post-effect-compiler-Rce26Eue.js.map → post-effect-compiler-pOvXae-i.js.map} +1 -1
  33. package/dist/{shader-material-U6BKZ8D1.js → shader-material-B6wwFCKB.js} +2 -2
  34. package/dist/{shader-material-U6BKZ8D1.js.map → shader-material-B6wwFCKB.js.map} +1 -1
  35. package/dist/{shader-material-BIG3UDyu.js → shader-material-C4VjLTfV.js} +3 -3
  36. package/dist/{shader-material-BIG3UDyu.js.map → shader-material-C4VjLTfV.js.map} +1 -1
  37. package/dist/{shader-pragma-tw6AKaQD.js → shader-pragma-qO9_6sTd.js} +2 -2
  38. package/dist/{shader-pragma-tw6AKaQD.js.map → shader-pragma-qO9_6sTd.js.map} +1 -1
  39. package/dist/{surface-shader-Br17yysO.js → surface-shader-BaR7Kg-F.js} +4 -4
  40. package/dist/{surface-shader-Br17yysO.js.map → surface-shader-BaR7Kg-F.js.map} +1 -1
  41. package/package.json +20 -2
  42. package/LICENSE +0 -201
  43. package/dist/ignifx-error-CRh89KUJ.js.map +0 -1
package/dist/index.d.ts CHANGED
@@ -55,6 +55,8 @@ export declare const ErrorRange: {
55
55
  readonly terrain: "16";
56
56
  /** Particle systems, 3D and 2D. */
57
57
  readonly particles: "17";
58
+ /** The editor host package and its Vite plugin. */
59
+ readonly editorHost: "18";
58
60
  };
59
61
  /**
60
62
  * The union of the two-digit subsystem prefixes declared by `ErrorRange`.
@@ -127,6 +129,8 @@ export declare const CoreErrorCode: {
127
129
  readonly invalidTweenOptions: "IGX-0109";
128
130
  /** A tweened field is not a number, `Vec2`, `Vec3`, or `Quat`, or is not writable. */
129
131
  readonly tweenFieldNotTweenable: "IGX-0110";
132
+ /** A coroutine was started in an edit-mode app by a script whose class does not run in edit mode. */
133
+ readonly coroutineInEditMode: "IGX-0111";
130
134
  /** A component declared through `requires` is missing from the entity. */
131
135
  readonly requiredComponentMissing: "IGX-0201";
132
136
  /** A second instance of a component type that does not allow multiples was added. */
@@ -193,6 +197,8 @@ export declare const CoreErrorCode: {
193
197
  readonly assetLoadFailed: "IGX-0505";
194
198
  /** Two loaders were registered for the same asset type. */
195
199
  readonly duplicateAssetLoader: "IGX-0506";
200
+ /** A `.mesh.json` file names an unknown primitive, or an option the primitive does not take or cannot use. */
201
+ readonly invalidMeshFile: "IGX-0507";
196
202
  /** A serialized number was `NaN` or infinite. */
197
203
  readonly nonFiniteNumber: "IGX-0601";
198
204
  /** A serialized `$entity`/`$component` reference could not be resolved. */
@@ -265,6 +271,8 @@ export declare const CoreErrorCode: {
265
271
  readonly surfaceSamplerBudgetExceeded: "IGX-0726";
266
272
  /** An `InstancedMeshRenderer` declares a LOD partner with `gpuCulling` off, so the partner never draws. */
267
273
  readonly instancingLodWithoutCulling: "IGX-0727";
274
+ /** `app.renderer.openOverlay()` was called on a headless app, or before `app.start()` registered the render scene. */
275
+ readonly overlayNeedsRenderScene: "IGX-0728";
268
276
  /** The host exposes no Web Crypto implementation. */
269
277
  readonly cryptoUnavailable: "IGX-1420";
270
278
  /** A storage namespace name is not a legal namespace segment. */
@@ -1155,6 +1163,12 @@ interface Assets {
1155
1163
  * development hot reload does (`docs/architecture/05-assets-and-loading.md` §7); a handle that is
1156
1164
  * not loaded is left alone. The Vite plugin's HMR channel and the devtools Assets panel call it.
1157
1165
  *
1166
+ * @remarks
1167
+ * A call made while a reload of the same handle is running reloads once more after it, however
1168
+ * many calls arrive meanwhile, and only the newest value is delivered. A failed reload keeps the
1169
+ * value the handle had and reports an `IGX-0505` {@link AssetLoadError} naming the address through
1170
+ * `app.onError`.
1171
+ *
1158
1172
  * @param address - The asset's address.
1159
1173
  */
1160
1174
  reload(address: string): void;
@@ -1485,7 +1499,10 @@ interface FieldOptions {
1485
1499
  readonly min?: number;
1486
1500
  /** Highest accepted value for numeric kinds; validation reports `IGX-0606` above it. */
1487
1501
  readonly max?: number;
1488
- /** Increment used by the inspector's drag and spinner controls. */
1502
+ /**
1503
+ * Increment used by the inspector's drag and spinner controls. A `quat` field is edited as
1504
+ * intrinsic XYZ Euler angles, so its step is in degrees.
1505
+ */
1489
1506
  readonly step?: number;
1490
1507
  /** Hides the field from the inspector while still serializing it. */
1491
1508
  readonly hidden?: boolean;
@@ -1854,6 +1871,8 @@ interface ScriptClassInfo {
1854
1871
  readonly executionOrder: number;
1855
1872
  /** `static updateWhenPaused`, resolved at registration. */
1856
1873
  readonly updateWhenPaused: boolean;
1874
+ /** `static runInEditMode`, resolved at registration. */
1875
+ readonly runInEditMode: boolean;
1857
1876
  /** One bit per `ScriptCallbackKind`: set when the class implements that callback. */
1858
1877
  readonly callbacks: number;
1859
1878
  }
@@ -1930,17 +1949,35 @@ export declare class ComponentRegistry {
1930
1949
  *
1931
1950
  * @param type - The component class.
1932
1951
  * @param typeId - An explicit id, when the class does not declare one.
1952
+ * @param registrar - Who registers it, for example the extension's `name`; the first registrar of
1953
+ * an id is kept, and {@link ComponentRegistry.registrarOf} reports it.
1933
1954
  * @returns What the registry worked out about the class.
1934
1955
  * @throws IgnifxError with code `IGX-0203` when the id is already registered by another class, or
1935
1956
  * when the id is not `<namespace>/<Name>`.
1936
1957
  */
1937
- register(type: ConcreteComponentType, typeId?: string): ComponentClassInfo;
1958
+ register(type: ConcreteComponentType, typeId?: string, registrar?: string): ComponentClassInfo;
1938
1959
  /**
1939
1960
  * Registers several component classes.
1940
1961
  *
1941
1962
  * @param types - The component classes.
1963
+ * @param registrar - Who registers them, as for {@link ComponentRegistry.register}.
1964
+ */
1965
+ registerAll(types: readonly ConcreteComponentType[], registrar?: string): void;
1966
+ /**
1967
+ * Who registered a type id: the extension `name` an `ExtensionContext` registers under, or
1968
+ * whatever a direct caller of {@link ComponentRegistry.register} passed. A hot-reload
1969
+ * {@link ComponentRegistry.replace} keeps it.
1970
+ *
1971
+ * @param typeId - The namespaced id.
1972
+ * @returns The registrar, or `null` when the id was registered without one (as
1973
+ * `app.registerComponents` does) or is not registered.
1974
+ *
1975
+ * @example
1976
+ * ```ts
1977
+ * app.world.registry.registrarOf("ignifx/Camera"); // "@ignifx/core"
1978
+ * ```
1942
1979
  */
1943
- registerAll(types: readonly ConcreteComponentType[]): void;
1980
+ registrarOf(typeId: string): string | null;
1944
1981
  /**
1945
1982
  * Swaps the class registered under a `typeId` for a replacement, for script hot reload
1946
1983
  * (`docs/architecture/15-devtools-and-diagnostics.md` §5). The previous class's cached info is
@@ -3589,6 +3626,19 @@ export declare const VEC3_FORWARD: Vec3Like;
3589
3626
  export declare const VEC3_BACKWARD: Vec3Like;
3590
3627
  //#endregion
3591
3628
  //#region src/lite/node.d.ts
3629
+ /**
3630
+ * The ignifx identity written into a Lite node's metadata bag so picking results and physics bodies
3631
+ * resolve back to the owning entity (`docs/architecture/00-overview.md` §5,
3632
+ * `docs/architecture/02-scene-graph.md` §10).
3633
+ *
3634
+ * @internal
3635
+ */
3636
+ interface NodeTag {
3637
+ /** The dense runtime handle of the entity that owns the node. */
3638
+ readonly entity: number;
3639
+ /** The component that created the node, when the node is not the entity's own transform. */
3640
+ readonly component?: number;
3641
+ }
3592
3642
  /**
3593
3643
  * The Babylon Lite node an ignifx `Transform` wraps, re-exported under an ignifx name so that
3594
3644
  * feature code can name the type without importing `@babylonjs/lite`
@@ -3960,8 +4010,12 @@ export interface Transform {
3960
4010
  //#endregion
3961
4011
  //#region src/schema/describe.d.ts
3962
4012
  /**
3963
- * One field as the documentation harness sees it (`scripts/README.md`, "Schema discovery
3964
- * convention").
4013
+ * One field as the documentation harness and an external inspector see it (`scripts/README.md`,
4014
+ * "Schema discovery convention"; `docs/architecture/03-scripting-and-components.md` §3).
4015
+ *
4016
+ * Every member past `kind` is present only when the declaration states it: a field with no
4017
+ * `step` has no `step` here. The inspector members mirror {@link FieldOptions}; the others carry
4018
+ * what the field's kind declares: an enum's values, an asset's type, a nested field's own description.
3965
4019
  *
3966
4020
  * @public
3967
4021
  */
@@ -3972,6 +4026,43 @@ interface SchemaFieldDescription {
3972
4026
  readonly default?: JsonValue;
3973
4027
  /** The field's tooltip, when it declares one. */
3974
4028
  readonly description?: string;
4029
+ /** `FieldOptions.min`: the lowest accepted value of a numeric field. */
4030
+ readonly min?: number;
4031
+ /** `FieldOptions.max`: the highest accepted value of a numeric field. */
4032
+ readonly max?: number;
4033
+ /**
4034
+ * `FieldOptions.step`: the increment of the inspector's drag and spinner controls; in degrees for
4035
+ * a `quat` field, which an inspector edits as Euler angles.
4036
+ */
4037
+ readonly step?: number;
4038
+ /** `FieldOptions.hidden`: the inspector leaves the field out; it is still saved. */
4039
+ readonly hidden?: boolean;
4040
+ /** `FieldOptions.readonly`: the inspector shows the field but does not let it be edited. */
4041
+ readonly readonly?: boolean;
4042
+ /** `FieldOptions.group`: the inspector group the field folds into. */
4043
+ readonly group?: string;
4044
+ /** `FieldOptions.transient`: the field is never saved and takes its default on load. */
4045
+ readonly transient?: boolean;
4046
+ /** An `enum` field's accepted values, in declaration order. */
4047
+ readonly values?: readonly string[];
4048
+ /**
4049
+ * An `asset` field's asset type name (`asset(TextureAsset)` → `"texture"`), the `type` an asset
4050
+ * reference to it carries. Absent when the asset token names no type.
4051
+ */
4052
+ readonly assetType?: string;
4053
+ /**
4054
+ * A `componentRef` field's accepted component, as its `typeId`, or `null` when the class it was
4055
+ * declared with carries no `typeId`. Present on every `componentRef` field.
4056
+ */
4057
+ readonly componentType?: string | null;
4058
+ /** An `array` field's element, described the same way. */
4059
+ readonly item?: SchemaFieldDescription;
4060
+ /** A `record` field's sub-fields, in declaration order, described the same way. */
4061
+ readonly fields?: Readonly<Record<string, SchemaFieldDescription>>;
4062
+ /** A `map` field's entry value, described the same way. */
4063
+ readonly value?: SchemaFieldDescription;
4064
+ /** An `optional` field's non-`null` value, described the same way. */
4065
+ readonly inner?: SchemaFieldDescription;
3975
4066
  }
3976
4067
  /**
3977
4068
  * One component schema as the documentation harness sees it. `pnpm docs:schemas` reads a record of
@@ -3989,6 +4080,25 @@ interface SchemaDescription {
3989
4080
  readonly description?: string;
3990
4081
  /** Every declared field, in declaration order. */
3991
4082
  readonly fields: Readonly<Record<string, SchemaFieldDescription>>;
4083
+ /**
4084
+ * Whether an entity may hold more than one of the component (`static allowMultiple`, `true` when
4085
+ * the class declares nothing). Set by {@link describeRegisteredSchemas}, or by the caller through
4086
+ * {@link SchemaDescriptionMeta}; absent on file formats.
4087
+ */
4088
+ readonly allowMultiple?: boolean;
4089
+ /**
4090
+ * Who registered the component: the extension's `name` (the npm package name, for example
4091
+ * `@ignifx/3d`), or, for a class the game registered itself, its type id's namespace (`mygame`).
4092
+ * Set by {@link describeRegisteredSchemas}, or by the caller through {@link SchemaDescriptionMeta}.
4093
+ */
4094
+ readonly package?: string;
4095
+ /**
4096
+ * `true` for the one component every entity carries itself, `ignifx/Transform`: it is never in a
4097
+ * scene file's `components` list, an editor cannot add or remove it, and its fields are the
4098
+ * entity record's `transform` block, edited whole (the editor protocol's `setTransform`), not
4099
+ * prop by prop. Absent on every other component and on file formats.
4100
+ */
4101
+ readonly builtIn?: boolean;
3992
4102
  }
3993
4103
  /**
3994
4104
  * Optional overrides for {@link describeSchema}.
@@ -4002,6 +4112,12 @@ interface SchemaDescriptionMeta {
4002
4112
  readonly format?: string;
4003
4113
  /** A one-line summary of what the component does. */
4004
4114
  readonly description?: string;
4115
+ /** Whether an entity may hold more than one of the component, copied onto the description. */
4116
+ readonly allowMultiple?: boolean;
4117
+ /** The package or extension that registered the component, copied onto the description. */
4118
+ readonly package?: string;
4119
+ /** Whether the component is the entity's own built-in block, copied onto the description. */
4120
+ readonly builtIn?: boolean;
4005
4121
  }
4006
4122
  /**
4007
4123
  * A JSON Schema fragment. Kept as a plain JSON object because the generated document is assembled
@@ -4012,14 +4128,18 @@ interface SchemaDescriptionMeta {
4012
4128
  */
4013
4129
  type JsonSchemaObject = JsonObject;
4014
4130
  /**
4015
- * Describes a component schema in the shape the documentation harness consumes. A package exports
4016
- * a record of these keyed by `typeId`; `pnpm docs:schemas` reads it from the built entry point and
4017
- * regenerates the format pages and `ignifx.schemas.json` from it
4018
- * (`scripts/README.md`, `docs/architecture/16-docs-harness-and-skill.md` §3).
4131
+ * Describes a component schema in the shape the documentation harness and an external inspector
4132
+ * consume. A package exports a record of these keyed by `typeId`; `pnpm docs:schemas` reads it from
4133
+ * the built entry point and regenerates the format pages and `ignifx.schemas.json` from it
4134
+ * (`scripts/README.md`, `docs/architecture/16-docs-harness-and-skill.md` §3). Each field carries
4135
+ * its inspector options and what its kind declares ({@link SchemaFieldDescription}); to describe
4136
+ * an app's registered components with `allowMultiple` and `package` filled in, use
4137
+ * {@link describeRegisteredSchemas}.
4019
4138
  *
4020
4139
  * @param typeId - The component's namespaced registration id, for example `mygame/Mover`.
4021
4140
  * @param schema - The component's declared fields.
4022
- * @param meta - Overrides for the title, format grouping, and summary.
4141
+ * @param meta - Overrides for the title, format grouping, and summary, and the component's
4142
+ * `allowMultiple`, `package` and `builtIn` when the caller knows them.
4023
4143
  * @returns The description entry.
4024
4144
  *
4025
4145
  * @example
@@ -4144,6 +4264,12 @@ interface SceneFileOverride {
4144
4264
  * The `instance` entry that turns an entity into the root of an instanced scene — what other
4145
4265
  * engines call a prefab instance (ADR-0005).
4146
4266
  *
4267
+ * @remarks
4268
+ * When the instanced scene has exactly one root, the entity carrying the entry _is_ that root, as
4269
+ * with `world.instantiate`: it gets the root's components, then its own, and keeps its own uid,
4270
+ * name, and transform. A scene with several roots is expanded under the entity instead
4271
+ * (`docs/architecture/06-serialization-and-scene-format.md` §2).
4272
+ *
4147
4273
  * @public
4148
4274
  */
4149
4275
  interface SceneFileInstance {
@@ -4737,6 +4863,15 @@ export declare class SceneInstance {
4737
4863
  * @internal
4738
4864
  */
4739
4865
  addRoot(entity: Entity): void;
4866
+ /**
4867
+ * Moves a root to another place in the root list.
4868
+ *
4869
+ * @param entity - A root of this instance.
4870
+ * @param index - Its new index, already clamped to the list.
4871
+ *
4872
+ * @internal
4873
+ */
4874
+ moveRoot(entity: Entity, index: number): void;
4740
4875
  /**
4741
4876
  * Removes an entity from the root list.
4742
4877
  *
@@ -4763,12 +4898,13 @@ export declare class SceneInstance {
4763
4898
  * costs a call per frame and not defining it costs nothing.
4764
4899
  *
4765
4900
  * **The statics work the same way.** `typeId`, `schema`, `requires`, `allowMultiple`,
4766
- * `executionOrder`, and `updateWhenPaused` are not members of `Component` or `Script` either: a
4767
- * static declared on the base class is an override too, so `static typeId = "mygame/Mover"` would
4768
- * have needed an `override` modifier. Their shape lives on {@link ComponentStatics} and
4769
- * {@link ScriptStatics}, which the class-token types intersect, so a plain `static` on a subclass
4770
- * satisfies them structurally; `ComponentRegistry` reads each one once per class and applies the
4771
- * defaults (`executionOrder` `0`, `updateWhenPaused` `false`).
4901
+ * `executionOrder`, `updateWhenPaused`, and `runInEditMode` are not members of `Component` or
4902
+ * `Script` either: a static declared on the base class is an override too, so
4903
+ * `static typeId = "mygame/Mover"` would have needed an `override` modifier. Their shape lives on
4904
+ * {@link ComponentStatics} and {@link ScriptStatics}, which the class-token types intersect, so a
4905
+ * plain `static` on a subclass satisfies them structurally; `ComponentRegistry` reads each one once
4906
+ * per class and applies the defaults (`executionOrder` `0`, `updateWhenPaused` `false`,
4907
+ * `runInEditMode` `false`).
4772
4908
  *
4773
4909
  * @example
4774
4910
  * ```ts
@@ -4810,6 +4946,8 @@ export declare abstract class Script extends Component {
4810
4946
  *
4811
4947
  * @param routine - The generator to drive. Call the generator function: `this.spawnLoop()`.
4812
4948
  * @returns A handle for stopping it or waiting on it.
4949
+ * @throws IgnifxError with code `IGX-0111` in an edit-mode app when the class does not set
4950
+ * `static runInEditMode = true` (ADR-0028).
4813
4951
  *
4814
4952
  * @example
4815
4953
  * ```ts
@@ -7699,6 +7837,28 @@ interface ScenePresenter {
7699
7837
  * @internal
7700
7838
  */
7701
7839
  type LitePickInfo = PickingInfo;
7840
+ /**
7841
+ * Decides whether a mesh may be picked, from the ignifx tag that owns it and the mesh itself.
7842
+ *
7843
+ * @remarks
7844
+ * The tag is the one {@link readOwnerTag} finds, so a glTF mesh inside a `Model` is judged by the
7845
+ * model's entity. The mesh is passed only so a caller can compare it by identity against an earlier
7846
+ * hit; nothing outside `src/lite/**` reads it.
7847
+ *
7848
+ * @internal
7849
+ */
7850
+ type PickAccept = (tag: NodeTag | null, mesh: Mesh) => boolean;
7851
+ /**
7852
+ * The identity of one earlier hit, which a pick can be told to look through.
7853
+ *
7854
+ * @internal
7855
+ */
7856
+ interface PickedIdentity {
7857
+ /** The mesh that was hit. */
7858
+ readonly mesh: Mesh;
7859
+ /** The thin instance that was hit, or `-1` when the mesh has none. */
7860
+ readonly thinInstanceIndex: number;
7861
+ }
7702
7862
  //#endregion
7703
7863
  //#region src/lite/shadow.d.ts
7704
7864
  /**
@@ -7786,6 +7946,8 @@ interface MaterialCacheResets {
7786
7946
  readonly seen: WeakSet<() => void>;
7787
7947
  /** `true` when a function nobody had seen was pushed since the last rebuild started. */
7788
7948
  unconfirmed: boolean;
7949
+ /** How many rebuilds started over because a material swap landed in them; for diagnostics. */
7950
+ retries: number;
7789
7951
  }
7790
7952
  //#endregion
7791
7953
  //#region src/platform/webgpu.d.ts
@@ -7850,6 +8012,18 @@ export declare const RENDER_DIAGNOSTICS_GROUP = "render";
7850
8012
  * @public
7851
8013
  */
7852
8014
  export declare const RENDER_DIAGNOSTICS_COUNTERS: readonly string[];
8015
+ /**
8016
+ * A pick's options as Lite consumes them: a mesh predicate over the owning tag, and the earlier hits
8017
+ * to look through.
8018
+ *
8019
+ * @internal
8020
+ */
8021
+ interface PickPlan {
8022
+ /** Decides whether a mesh may be picked; `null` considers every mesh. */
8023
+ readonly accept: PickAccept | null;
8024
+ /** The earlier hits to ignore. */
8025
+ readonly hits: readonly PickedIdentity[];
8026
+ }
7853
8027
  /**
7854
8028
  * A rendering feature a project or an extension asks for
7855
8029
  * (`docs/architecture/07-rendering.md` §1.1).
@@ -7858,7 +8032,11 @@ export declare const RENDER_DIAGNOSTICS_COUNTERS: readonly string[];
7858
8032
  */
7859
8033
  type RenderingFeature = keyof RenderingFeatureSettings;
7860
8034
  /**
7861
- * What a GPU pick found (`docs/architecture/07-rendering.md` §3).
8035
+ * What a GPU pick or a render raycast found (`docs/architecture/07-rendering.md` §3).
8036
+ *
8037
+ * @remarks
8038
+ * A hit on any mesh resolves to the nearest node on its way to the root that an entity owns, so a
8039
+ * click on any part of a glTF `Model` names the model's entity and the `Model` component.
7862
8040
  *
7863
8041
  * @public
7864
8042
  */
@@ -7867,15 +8045,36 @@ interface RenderPick {
7867
8045
  readonly entity: Entity;
7868
8046
  /** The component that created the mesh, when it was not the entity's own transform. */
7869
8047
  readonly component: Component | null;
7870
- /** The world-space hit point, or `null` unless detailed picking is on. */
8048
+ /**
8049
+ * The world-space hit point. A GPU pick reads it from the depth of the winning pixel, a render
8050
+ * raycast from the triangle it hit; `null` only when the camera's matrix cannot be inverted.
8051
+ */
7871
8052
  readonly point: readonly [number, number, number] | null;
7872
- /** The world-space surface normal, or `null` unless detailed picking is on. */
8053
+ /** The world-space surface normal, or `null` from a GPU pick, which does not compute one. */
7873
8054
  readonly normal: readonly [number, number, number] | null;
7874
- /** How far along the ray the hit is, in metres. */
8055
+ /** How far the hit is from the camera (GPU pick) or the ray's origin (raycast), in metres. */
7875
8056
  readonly distance: number;
8057
+ /**
8058
+ * The name of the mesh the ray hit: for a `Model`, the name the glTF file gives that node or
8059
+ * primitive; for a `MeshRenderer`, its mesh's. `""` when the mesh has none.
8060
+ */
8061
+ readonly meshName: string;
8062
+ /**
8063
+ * Which instance of an `InstancedMeshRenderer` was hit, or `null` when the mesh is not instanced.
8064
+ * Lite's sub-mesh index is not reported: a glTF primitive is a mesh of its own in Lite, so
8065
+ * {@link RenderPick.meshName} already tells the parts of a model apart.
8066
+ */
8067
+ readonly thinInstanceIndex: number | null;
7876
8068
  }
7877
8069
  /**
7878
- * How a GPU pick is restricted (`docs/architecture/07-rendering.md` §3).
8070
+ * Something a pick looks through: an entity (every mesh it owns), a component (every mesh it
8071
+ * created), or an earlier hit (that mesh, or that one instance of an instanced mesh).
8072
+ *
8073
+ * @public
8074
+ */
8075
+ type RenderPickIgnore = Entity | Component | RenderPick;
8076
+ /**
8077
+ * How a GPU pick or a render raycast is restricted (`docs/architecture/07-rendering.md` §3).
7879
8078
  *
7880
8079
  * @public
7881
8080
  */
@@ -7888,6 +8087,22 @@ interface RenderPickOptions {
7888
8087
  * @returns `true` to consider the entity.
7889
8088
  */
7890
8089
  readonly filter?: (entity: Entity) => boolean;
8090
+ /**
8091
+ * What to look through: each entity, component or earlier hit listed neither occludes nor
8092
+ * returns. Passing the previous hit each time walks through the objects under one pixel from
8093
+ * front to back — an editor's click-to-cycle.
8094
+ *
8095
+ * @remarks
8096
+ * Only a GPU pick can skip one instance of an instanced mesh; `world.raycastRender` skips the
8097
+ * whole mesh. A hit from another app is not recognised and is skipped.
8098
+ *
8099
+ * **Limit (Babylon Lite 1.34).** Lite keeps one ignore entry per mesh. Several hits on instances
8100
+ * of one `InstancedMeshRenderer` are merged into a range when their indices are contiguous;
8101
+ * otherwise only the lowest index is skipped, and the pick can return a hit already in the list.
8102
+ * A loop that walks through a pixel must stop when a hit repeats (the same `entity`, `meshName`
8103
+ * and `thinInstanceIndex`), or it never gets past such a renderer.
8104
+ */
8105
+ readonly ignore?: readonly RenderPickIgnore[];
7891
8106
  }
7892
8107
  /**
7893
8108
  * A captured frame (`docs/architecture/07-rendering.md` §5).
@@ -7934,6 +8149,40 @@ interface RenderTaskTimings {
7934
8149
  /** The tasks, in frame execution order. Empty unless `status` is `"ok"`. */
7935
8150
  readonly tasks: readonly RenderTaskTiming[];
7936
8151
  }
8152
+ /**
8153
+ * The Babylon Lite scenes behind a {@link RenderOverlay}: the escape hatch an editor hands to Lite's
8154
+ * gizmo constructors, which take this shape as a `UtilityLayer` (`CONSTITUTION.md` §3.4).
8155
+ *
8156
+ * @remarks
8157
+ * Unstable: these are Lite's own objects, excluded from the stability guarantees of
8158
+ * `CONSTITUTION.md` Article IV.
8159
+ *
8160
+ * @beta
8161
+ */
8162
+ interface RenderOverlayLiteHandles {
8163
+ /** The overlay's own scene. What is added to it draws over the frame. */
8164
+ readonly scene: LiteScene;
8165
+ /** The render scene. The overlay scene uses its camera. */
8166
+ readonly mainScene: LiteScene;
8167
+ }
8168
+ /**
8169
+ * A Babylon Lite scene drawn over the finished frame, for an editor's gizmos, selection outlines,
8170
+ * and grids (`docs/architecture/07-rendering.md` §2.10, ADR-0031).
8171
+ *
8172
+ * @remarks
8173
+ * The overlay draws after everything else on the canvas, the render scene, its post-processing,
8174
+ * sprites and text included, at every `rendering.msaaSamples` setting. It has a depth buffer of its
8175
+ * own, cleared every frame, so what it holds is never hidden by the scene; within the overlay,
8176
+ * depth testing works as usual. It is drawn without MSAA. Screenshots include it.
8177
+ *
8178
+ * @beta
8179
+ */
8180
+ interface RenderOverlay {
8181
+ /** The overlay's Lite scenes (unstable, `CONSTITUTION.md` §3.4). */
8182
+ readonly lite: RenderOverlayLiteHandles;
8183
+ /** Stops drawing the overlay and releases its scene and everything in it. Calling it again does nothing. */
8184
+ dispose(): void;
8185
+ }
7937
8186
  /**
7938
8187
  * The rendering service, reached as `app.renderer`
7939
8188
  * (`docs/architecture/07-rendering.md` §1, §3, §5).
@@ -7941,7 +8190,9 @@ interface RenderTaskTimings {
7941
8190
  * @example
7942
8191
  * ```ts
7943
8192
  * app.renderer.resolutionScale = 0.75;
7944
- * const hit = await app.renderer.pickAsync(event.offsetX, event.offsetY);
8193
+ * // A DOM event is in CSS pixels; the renderer speaks the canvas's backing-store pixels.
8194
+ * const scale = canvas.width / canvas.clientWidth;
8195
+ * const hit = await app.renderer.pickAsync(event.offsetX * scale, event.offsetY * scale);
7945
8196
  * hit?.entity.name;
7946
8197
  * ```
7947
8198
  *
@@ -7960,6 +8211,24 @@ interface Renderer {
7960
8211
  resolutionScale: number;
7961
8212
  /** Whether per-task GPU timings are collected. Off by default; it costs timestamp queries. */
7962
8213
  profileTasks: boolean;
8214
+ /**
8215
+ * Whether the shader clock runs in an edit-mode app (ADR-0028, amendment of 2026-10-20): an
8216
+ * editor's "animate materials" toggle. `true` by default.
8217
+ *
8218
+ * @remarks
8219
+ * The clock is the `time`, `unscaledTime` and `deltaTime` that shader materials and custom post
8220
+ * effects declare. While this is `false` in an edit-mode app the clock stands still, as it does
8221
+ * under `app.pause()`: `time` keeps its value, `deltaTime` is `0`, and setting it back to `true`
8222
+ * resumes from there without a jump. The main-light and ambient uniforms stay live either way.
8223
+ * Outside edit mode the value is ignored and the clock always runs.
8224
+ *
8225
+ * @example
8226
+ * ```ts
8227
+ * const app = await createApp({ canvas, editMode: true });
8228
+ * app.renderer.animateMaterialsInEditMode = false; // the editor's toggle is off
8229
+ * ```
8230
+ */
8231
+ animateMaterialsInEditMode: boolean;
7963
8232
  /** Which rendering features are on. Read-only once `app.start()` has registered the scene. */
7964
8233
  readonly features: Readonly<RenderingFeatureSettings>;
7965
8234
  /**
@@ -8004,14 +8273,20 @@ interface Renderer {
8004
8273
  *
8005
8274
  * @remarks
8006
8275
  * Coordinates are **backing-store pixels** — the canvas's `width`/`height`, the space
8007
- * `Camera.worldToScreen` answers in — not CSS pixels; multiply a DOM event's `offsetX`/`offsetY`
8008
- * by `devicePixelRatio` first. Picks are serialised per app: Lite's picker owns one set of staging
8009
- * buffers and chains each call onto the previous one's promise. A headless app has no picker and
8010
- * always misses.
8276
+ * `Camera.worldToScreen` answers in and `<Pointer>/position` reports — not CSS pixels. Multiply a
8277
+ * DOM event's `offsetX`/`offsetY` by `canvas.width / canvas.clientWidth` first. The renderer
8278
+ * converts to the CSS pixels Lite's picker takes, so the same call hits at every device pixel
8279
+ * ratio and resolution scale. The point is sampled exactly: whole numbers are pixel corners, so
8280
+ * add 0.5 for a pixel's centre.
8281
+ *
8282
+ * A hit on any mesh of a glTF `Model`, or of any renderable built from several Lite nodes,
8283
+ * resolves through the nearest node an entity owns. Picks are serialised per app: Lite's picker
8284
+ * owns one set of staging buffers and chains each call onto the previous one's promise. A
8285
+ * headless app has no picker and always misses.
8011
8286
  *
8012
8287
  * @param x - The backing-store pixel x, from the canvas's left edge.
8013
8288
  * @param y - The backing-store pixel y, from the canvas's top edge.
8014
- * @param options - An entity filter.
8289
+ * @param options - An entity filter, and what to look through.
8015
8290
  * @returns What was hit, or `null` for a miss.
8016
8291
  */
8017
8292
  pickAsync(x: number, y: number, options?: RenderPickOptions): Promise<RenderPick | null>;
@@ -8038,6 +8313,31 @@ interface Renderer {
8038
8313
  * which point Lite has compiled what it is going to compile.
8039
8314
  */
8040
8315
  requireFeature(feature: RenderingFeature): void;
8316
+ /**
8317
+ * Opens an overlay: a Babylon Lite scene drawn over the finished frame, for an editor's gizmos
8318
+ * and selection outlines (`docs/architecture/07-rendering.md` §2.10).
8319
+ *
8320
+ * @remarks
8321
+ * Add Lite meshes, or Lite's gizmos, to `overlay.lite.scene`. The overlay follows the render
8322
+ * scene's camera, draws over every other rendering context, and works at every MSAA setting and
8323
+ * on both render paths. Dispose it when it is no longer needed; `app.dispose()` disposes any that
8324
+ * are still open.
8325
+ *
8326
+ * @returns The overlay, drawing from the next frame.
8327
+ * @throws IgnifxError with code `IGX-0728` on a headless app or before `app.start()` has
8328
+ * registered the render scene, and `IGX-0106` when the app is disposed, also while the overlay
8329
+ * was opening.
8330
+ *
8331
+ * @example
8332
+ * ```ts
8333
+ * const overlay = await app.renderer.openOverlay();
8334
+ * // Lite code under src/lite/ adds gizmos to overlay.lite.scene.
8335
+ * overlay.dispose();
8336
+ * ```
8337
+ *
8338
+ * @beta
8339
+ */
8340
+ openOverlay(): Promise<RenderOverlay>;
8041
8341
  /**
8042
8342
  * Registers a probe that answers whether a rendering context **other than the render scene** is
8043
8343
  * drawing a world through a camera of its own.
@@ -8073,6 +8373,11 @@ declare class RendererImpl implements Renderer {
8073
8373
  needsCasterRebuild: boolean;
8074
8374
  /** `true` once a light gained or lost a shadow generator, so the next rebuild needs fresh layouts. */
8075
8375
  needsShadowLayoutReset: boolean;
8376
+ /**
8377
+ * `true` from the moment the render sync system queues a renderable rebuild until the last one it
8378
+ * owes has finished. A light waits for it to be `false` before it gains or loses a shadow generator.
8379
+ */
8380
+ isRebuildInFlight: boolean;
8076
8381
  /**
8077
8382
  * The PBR deformation kinds (`PBR_DEFORMER` bits) a full renderable build has already composed on
8078
8383
  * this engine. A kind missing from it gets fresh layouts on its first rebuild (`../lite/pbr-deformers.ts`).
@@ -8184,6 +8489,47 @@ declare class RendererImpl implements Renderer {
8184
8489
  */
8185
8490
  get profileTasks(): boolean;
8186
8491
  set profileTasks(value: boolean);
8492
+ /**
8493
+ * Whether the shader clock runs in an edit-mode app.
8494
+ *
8495
+ * @returns `true` unless an editor turned material animation off.
8496
+ */
8497
+ get animateMaterialsInEditMode(): boolean;
8498
+ set animateMaterialsInEditMode(value: boolean);
8499
+ /**
8500
+ * Records this frame's shader clock, as `ShaderUniformSystem` accumulated it: the one clock both
8501
+ * shader materials and, in edit mode, custom post effects read.
8502
+ *
8503
+ * @param time - Scaled seconds the clock has run.
8504
+ * @param unscaledTime - Unscaled seconds the clock has run.
8505
+ * @param deltaTime - This frame's step; `0` while the clock is held.
8506
+ *
8507
+ * @internal
8508
+ */
8509
+ setShaderClock(time: number, unscaledTime: number, deltaTime: number): void;
8510
+ /**
8511
+ * Whether the shader clock stands still this frame because an edit-mode app turned material
8512
+ * animation off. `app.pause()` is checked separately, by each reader.
8513
+ *
8514
+ * @returns `true` while the editor's toggle holds the clock.
8515
+ *
8516
+ * @internal
8517
+ */
8518
+ get isShaderClockHeld(): boolean;
8519
+ /**
8520
+ * The clock custom post effects upload. In an edit-mode app it is the shader clock materials read
8521
+ * (`setShaderClock`), so the two never drift apart when the editor holds and resumes it
8522
+ * (ADR-0028, amendment of 2026-10-20). A game keeps the app's own clock.
8523
+ *
8524
+ * @returns The clock.
8525
+ *
8526
+ * @internal
8527
+ */
8528
+ get effectClock(): {
8529
+ readonly time: number;
8530
+ readonly unscaledTime: number;
8531
+ readonly deltaTime: number;
8532
+ };
8187
8533
  /**
8188
8534
  * GPU draw calls in the last rendered frame.
8189
8535
  *
@@ -8236,7 +8582,7 @@ declare class RendererImpl implements Renderer {
8236
8582
  *
8237
8583
  * @param x - The backing-store pixel x, from the canvas's left edge.
8238
8584
  * @param y - The backing-store pixel y, from the canvas's top edge.
8239
- * @param options - An entity filter.
8585
+ * @param options - An entity filter, and what to look through.
8240
8586
  * @returns What was hit, or `null` for a miss.
8241
8587
  */
8242
8588
  pickAsync(x: number, y: number, options?: RenderPickOptions): Promise<RenderPick | null>;
@@ -8260,6 +8606,14 @@ declare class RendererImpl implements Renderer {
8260
8606
  * @throws IgnifxError with code `IGX-0704` after the render scene has been registered.
8261
8607
  */
8262
8608
  requireFeature(feature: RenderingFeature): void;
8609
+ /**
8610
+ * Opens an overlay drawn over the finished frame.
8611
+ *
8612
+ * @returns The overlay.
8613
+ * @throws IgnifxError with code `IGX-0728` on a headless app or before the render scene is
8614
+ * registered, and `IGX-0106` when the app is disposed, also while the overlay was opening.
8615
+ */
8616
+ openOverlay(): Promise<RenderOverlay>;
8263
8617
  /**
8264
8618
  * Registers a probe that answers whether another rendering context has a camera of its own.
8265
8619
  *
@@ -8312,11 +8666,20 @@ declare class RendererImpl implements Renderer {
8312
8666
  width: number;
8313
8667
  height: number;
8314
8668
  }): void;
8669
+ /**
8670
+ * Turns a pick's options into the mesh predicate and the earlier hits Lite looks through.
8671
+ *
8672
+ * @param options - The caller's options.
8673
+ * @returns The predicate — `null` when every mesh may be picked — and the hits to ignore.
8674
+ *
8675
+ * @internal
8676
+ */
8677
+ planPick(options: RenderPickOptions | undefined): PickPlan;
8315
8678
  /**
8316
8679
  * Resolves a Lite pick result back to the entity and component that own the mesh.
8317
8680
  *
8318
8681
  * @param info - Lite's picking info, from the GPU picker or a CPU ray cast.
8319
- * @returns What was hit, or `null` for a miss or a mesh ignifx did not create.
8682
+ * @returns What was hit, or `null` for a miss or a mesh no entity owns.
8320
8683
  *
8321
8684
  * @internal
8322
8685
  */
@@ -8455,7 +8818,31 @@ declare class RendererImpl implements Renderer {
8455
8818
  */
8456
8819
  publishCounters(cameras: number, lights: number, meshes: number): void;
8457
8820
  /**
8458
- * Releases the picker and the warm-up probes. The core extension registers it as a disposer.
8821
+ * Runs a scene change now, or holds it until the render sync system's rebuild has finished when
8822
+ * one is in flight.
8823
+ *
8824
+ * @remarks
8825
+ * For a change a rebuild must not see half-way: one that changes how many shadow generators the
8826
+ * scene has. A rebuild reads them group by group against layouts cached without that number, so
8827
+ * a group built after the change gets a bind group the layout does not match.
8828
+ *
8829
+ * @param change - The change.
8830
+ *
8831
+ * @internal
8832
+ */
8833
+ afterRebuild(change: () => void): void;
8834
+ /**
8835
+ * Takes the changes {@link RendererImpl.afterRebuild} held back. The render sync system runs them
8836
+ * once its rebuild has finished. A disposed renderer hands back none: its scene is gone.
8837
+ *
8838
+ * @returns The changes, oldest first.
8839
+ *
8840
+ * @internal
8841
+ */
8842
+ takeHeldChanges(): (() => void)[];
8843
+ /**
8844
+ * Releases the open overlays, the picker and the warm-up probes. The core extension registers it
8845
+ * as a disposer.
8459
8846
  *
8460
8847
  * @internal
8461
8848
  */
@@ -9016,7 +9403,9 @@ interface RayVector {
9016
9403
  * @example
9017
9404
  * ```ts
9018
9405
  * const ray = createRay();
9019
- * camera.screenToRay(event.offsetX, event.offsetY, ray);
9406
+ * // A DOM event is in CSS pixels; the camera speaks the canvas's backing-store pixels.
9407
+ * const scale = canvas.width / canvas.clientWidth;
9408
+ * camera.screenToRay(event.offsetX * scale, event.offsetY * scale, ray);
9020
9409
  * ```
9021
9410
  *
9022
9411
  * @public
@@ -9087,7 +9476,9 @@ export declare class Camera extends Component implements ComponentHooks {
9087
9476
  * @remarks
9088
9477
  * Coordinates are backing-store pixels — the canvas's `width`/`height`, the space
9089
9478
  * {@link Camera.worldToScreen} answers in and `@ignifx/input` reports `<Pointer>/position` in — not
9090
- * CSS pixels; multiply a DOM event's `offsetX`/`offsetY` by `devicePixelRatio` first.
9479
+ * CSS pixels; multiply a DOM event's `offsetX`/`offsetY` by `canvas.width / canvas.clientWidth`
9480
+ * first (`devicePixelRatio` is that ratio only while `renderer.pixelRatio` and
9481
+ * `renderer.resolutionScale` leave it alone).
9091
9482
  *
9092
9483
  * @param x - The backing-store pixel x, from the canvas's left edge.
9093
9484
  * @param y - The backing-store pixel y, from the canvas's top edge.
@@ -9159,33 +9550,190 @@ export declare class Camera extends Component implements ComponentHooks {
9159
9550
  sync(renderer: RendererImpl): void;
9160
9551
  }
9161
9552
  //#endregion
9162
- //#region src/world/world.d.ts
9553
+ //#region src/serialization/load.d.ts
9163
9554
  /**
9164
- * The running simulation: the entity registry, the scene instances, and the lifecycle queues
9165
- * (`docs/architecture/02-scene-graph.md` §2). One world per app in the MVP.
9555
+ * One recoverable problem found while a scene was being built. Nothing here stops the load: a file
9556
+ * degrades one field, one reference, or one layer rather than failing whole
9557
+ * (`docs/architecture/06-serialization-and-scene-format.md` §4).
9558
+ *
9559
+ * @public
9560
+ */
9561
+ interface SceneLoadIssue {
9562
+ /** The diagnostic code, for example `IGX-0602` or `IGX-0303`. */
9563
+ readonly code: string;
9564
+ /** The actionable sentence. */
9565
+ readonly message: string;
9566
+ }
9567
+ /**
9568
+ * Options accepted by {@link instantiateScene}.
9569
+ *
9570
+ * @public
9571
+ */
9572
+ interface InstantiateSceneOptions {
9573
+ /** The entity the scene's roots attach to; `null` or omitted makes them roots of `scene`. */
9574
+ readonly parent?: Entity | null;
9575
+ /** The instance that owns the new entities; defaults to the parent's, else `world.activeScene`. */
9576
+ readonly scene?: SceneInstance;
9577
+ /**
9578
+ * `true` treats the whole file as one instance: every entity gets a fresh uid and an
9579
+ * `Entity.prefab` link. This is what `world.instantiate` does; `world.loadScene` leaves it off so
9580
+ * that the scene's own entities keep the uids the file gave them
9581
+ * (`docs/architecture/02-scene-graph.md` §10).
9582
+ */
9583
+ readonly asInstance?: boolean;
9584
+ /** The handle the scene was loaded through, recorded on `Entity.prefab` when `asInstance`. */
9585
+ readonly assetHandle?: AssetHandle<SceneAsset> | null;
9586
+ /**
9587
+ * The entity that stands for the instance when `asInstance` is set and the file has more or fewer
9588
+ * than one root. `world.instantiate` creates it and passes it as both `parent` and `rootEntity`,
9589
+ * so that the call still answers with one entity.
9590
+ */
9591
+ readonly rootEntity?: Entity | null;
9592
+ /** `true` turns an `IGX-0604` hash mismatch from a diagnostic into a throw. */
9593
+ readonly strictInstanceHashes?: boolean;
9594
+ }
9595
+ /**
9596
+ * What {@link instantiateScene} produced.
9597
+ *
9598
+ * @public
9599
+ */
9600
+ interface SceneBuildResult {
9601
+ /** The entities that ended up parentless within the built subtree, in file order. */
9602
+ readonly roots: readonly Entity[];
9603
+ /** The file-local uid to runtime object table (`docs/architecture/02-scene-graph.md` §10). */
9604
+ readonly remap: UidRemap;
9605
+ /** Every recoverable problem, in discovery order. */
9606
+ readonly issues: readonly SceneLoadIssue[];
9607
+ }
9608
+ /**
9609
+ * Builds the entities of a scene asset into a world — steps 3 to 6 of the loading algorithm
9610
+ * (`docs/architecture/06-serialization-and-scene-format.md` §4). It is synchronous and does no I/O:
9611
+ * every asset the file references is already loaded, which is what a `SceneAsset` guarantees.
9166
9612
  *
9167
9613
  * @remarks
9168
- * The world owns entity creation, queries, the implicit `"default"` scene, and the lifecycle, plus
9169
- * the scene operations that need the asset service — `loadScene`, `unloadScene`, `instantiate`,
9170
- * `instantiateAsync`, `moveEntityToScene` — and the `onSceneLoaded`/`onSceneUnloaded` signals they
9171
- * raise.
9614
+ * The mechanism that keeps `awake` honest is worth stating, because §4 step 6 and
9615
+ * `01-lifecycle-and-time.md` §4 state only the outcome. Entities are created with `active: false`,
9616
+ * so the enable transition computes "not effectively enabled" and queues nothing. Components are
9617
+ * attached with their schema defaults, then every component's props are decoded — that is where
9618
+ * `entityRef` and `componentRef` resolve, through a table that by then holds the whole scene. Only
9619
+ * then does a last pass write each entity's file `active` value in tree order, which is what queues
9620
+ * `awake` and `onEnable`, parents before children. Nothing observes the half-built scene, because
9621
+ * all of this runs in one synchronous block.
9622
+ *
9623
+ * @param world - The world to build into.
9624
+ * @param asset - The scene to build.
9625
+ * @param options - Where to attach the result, and how to treat instance hashes.
9626
+ * @returns The roots, the uid table, and every recoverable problem.
9627
+ * @throws IgnifxError with code `IGX-0302` on an instance cycle, `IGX-0307` when the file names an
9628
+ * unregistered component type, and `IGX-0604` when `strictInstanceHashes` is set and a recorded
9629
+ * instance hash does not match.
9172
9630
  *
9173
9631
  * @example
9174
9632
  * ```ts
9175
- * const player = app.world.createEntity("Player");
9176
- * for (const script of app.world.components(Script)) {
9177
- * script.enabled = false;
9178
- * }
9633
+ * const built = instantiateScene(world, sceneAsset, { scene: world.activeScene });
9634
+ * const player = built.remap.entity("01J9Z6M7E5S3A0V2Q4R8T1Y6WX");
9179
9635
  * ```
9180
9636
  *
9181
9637
  * @public
9182
9638
  */
9183
- export declare class World implements WorldHost {
9184
- #private;
9639
+ export declare function instantiateScene(world: World, asset: SceneAsset, options?: InstantiateSceneOptions): SceneBuildResult;
9640
+ /**
9641
+ * Options accepted by {@link addComponentFromRecord}.
9642
+ *
9643
+ * @public
9644
+ */
9645
+ interface AddComponentFromRecordOptions {
9185
9646
  /**
9186
- * Builds a world. Call `createWorld` instead; the runtime owns this.
9187
- *
9188
- * @param options - The app, the Lite scene, the frame state, and the resolved settings.
9647
+ * The component's index among the entity's components as a scene file lists them (the transform
9648
+ * and the components an instanced scene put on the entity do not count). Defaults to the end; a
9649
+ * value past the end is clamped to it.
9650
+ */
9651
+ readonly index?: number;
9652
+ /**
9653
+ * How `$entity`, `$component` and `$asset` values in the record's `props` resolve. Without one
9654
+ * every reference decodes as `null` and is reported (`IGX-0602`). An asset must already be loaded:
9655
+ * decoding never starts a load.
9656
+ */
9657
+ readonly references?: ReferenceDecoder;
9658
+ }
9659
+ /**
9660
+ * What {@link addComponentFromRecord} built.
9661
+ *
9662
+ * @public
9663
+ */
9664
+ interface ComponentBuildResult {
9665
+ /** The attached component, carrying the record's uid. */
9666
+ readonly component: Component;
9667
+ /** Every recoverable problem found while decoding `props`, in discovery order. */
9668
+ readonly issues: readonly SceneLoadIssue[];
9669
+ }
9670
+ /**
9671
+ * Attaches one component to a live entity from its scene file record, the way the scene loader
9672
+ * builds it: the record's registered type, its uid, its `enabled` flag, and its `props` decoded
9673
+ * against the schema (`docs/architecture/06-serialization-and-scene-format.md` §4).
9674
+ *
9675
+ * @remarks
9676
+ * This is the per-component step of {@link instantiateScene} for a world that already exists, which
9677
+ * is what an editor mirroring a document into a live world needs. The component is attached with
9678
+ * `entity.addComponent`, so `awake` follows that method's rules. The record's uid is adopted as is;
9679
+ * keeping it unique within the scene is the caller's job. Decoding never throws: a value that does
9680
+ * not match its field takes the field's default and is reported in `issues`.
9681
+ *
9682
+ * @param entity - The entity to attach to.
9683
+ * @param record - The component record, as a scene file writes it.
9684
+ * @param options - Where it goes among the entity's components, and how references resolve.
9685
+ * @returns The component and the decoding problems.
9686
+ * @throws IgnifxError with code `IGX-0307` when the record's type is not registered, and whatever
9687
+ * `entity.addComponent` throws (`IGX-0202` for a second instance of a single-instance class,
9688
+ * `IGX-0101` for a destroyed entity).
9689
+ *
9690
+ * @example
9691
+ * ```ts
9692
+ * const { component } = addComponentFromRecord(player, { uid: "01J9Z6M7E5S3A0V2Q4R8T1Y6WY", type: "game/Health", props: { max: 120 } });
9693
+ * ```
9694
+ *
9695
+ * @public
9696
+ */
9697
+ export declare function addComponentFromRecord(entity: Entity, record: SceneFileComponent, options?: AddComponentFromRecordOptions): ComponentBuildResult;
9698
+ /**
9699
+ * Checks that every scene a file instances — at any depth — is among the loaded dependencies, which
9700
+ * is what makes `world.instantiate` safe to be synchronous
9701
+ * (`docs/architecture/02-scene-graph.md` §2).
9702
+ *
9703
+ * @param asset - The scene to check.
9704
+ * @throws IgnifxError with code `IGX-0301` naming the first instanced scene that is not loaded.
9705
+ *
9706
+ * @public
9707
+ */
9708
+ export declare function assertSceneDependenciesLoaded(asset: SceneAsset): void;
9709
+ //#endregion
9710
+ //#region src/world/world.d.ts
9711
+ /**
9712
+ * The running simulation: the entity registry, the scene instances, and the lifecycle queues
9713
+ * (`docs/architecture/02-scene-graph.md` §2). One world per app in the MVP.
9714
+ *
9715
+ * @remarks
9716
+ * The world owns entity creation, queries, the implicit `"default"` scene, and the lifecycle, plus
9717
+ * the scene operations that need the asset service — `loadScene`, `unloadScene`, `instantiate`,
9718
+ * `instantiateAsync`, `moveEntityToScene` — and the `onSceneLoaded`/`onSceneUnloaded` signals they
9719
+ * raise.
9720
+ *
9721
+ * @example
9722
+ * ```ts
9723
+ * const player = app.world.createEntity("Player");
9724
+ * for (const script of app.world.components(Script)) {
9725
+ * script.enabled = false;
9726
+ * }
9727
+ * ```
9728
+ *
9729
+ * @public
9730
+ */
9731
+ export declare class World implements WorldHost {
9732
+ #private;
9733
+ /**
9734
+ * Builds a world. Call `createWorld` instead; the runtime owns this.
9735
+ *
9736
+ * @param options - The app, the Lite scene, the frame state, and the resolved settings.
9189
9737
  *
9190
9738
  * @internal
9191
9739
  */
@@ -9382,7 +9930,7 @@ export declare class World implements WorldHost {
9382
9930
  * answer.
9383
9931
  *
9384
9932
  * @param ray - The ray to cast.
9385
- * @param options - An entity filter.
9933
+ * @param options - An entity filter, and what to look through.
9386
9934
  * @returns What was hit, or `null` for a miss.
9387
9935
  *
9388
9936
  * @example
@@ -9462,6 +10010,60 @@ export declare class World implements WorldHost {
9462
10010
  * ```
9463
10011
  */
9464
10012
  loadScene(scene: AssetRef<SceneAsset> | string, options?: LoadSceneOptions): Promise<SceneInstance>;
10013
+ /**
10014
+ * Builds a scene from a file that is already in memory, the way {@link World.loadScene} builds one
10015
+ * from an address (`docs/architecture/02-scene-graph.md` §2).
10016
+ *
10017
+ * @remarks
10018
+ * Nothing is fetched for the file itself: it is validated, every asset it references is loaded
10019
+ * through `app.assets` (the scene loader's own walk), and it is published there at
10020
+ * `options.address` as a scene asset, so the instance's `asset` and everything that reads it
10021
+ * behave as for a loaded file. Entity and component uids are the file's. The instance holds the
10022
+ * asset and its dependencies and releases them when it is unloaded. The rest is
10023
+ * {@link World.loadScene}'s: the same modes, the same synchronous build, `awake` before the
10024
+ * promise settles, and `onSceneLoaded`.
10025
+ *
10026
+ * This is how a tool builds a scene it holds as an object, such as an editor's open document with
10027
+ * unsaved edits.
10028
+ *
10029
+ * @param file - The scene file object, as `serializeScene` or `JSON.parse` produces it.
10030
+ * @param options - The address to publish it at, the mode, cancellation, and an issue collector.
10031
+ * @returns The instance, once every entity exists, every reference is resolved, and `awake` has
10032
+ * run.
10033
+ * @throws IgnifxError with code `IGX-0308` when the object is not a scene file, `IGX-0603` for a
10034
+ * format version this build cannot read, and `IGX-0608` when it does not match the scene format;
10035
+ * nothing is unloaded then. `IGX-0502` when `options.signal` aborts, `IGX-0307` when the file
10036
+ * names an unregistered component type (the half-built instance is unloaded first), and
10037
+ * whatever the asset system throws for a dependency.
10038
+ *
10039
+ * @example
10040
+ * ```ts
10041
+ * const level = await world.loadSceneFile(file, { address: "levels/level01.scene.json" });
10042
+ * ```
10043
+ */
10044
+ loadSceneFile(file: SceneFile, options: LoadSceneFileOptions): Promise<SceneInstance>;
10045
+ /**
10046
+ * Creates an empty scene instance that is built in code rather than loaded from a file
10047
+ * (`docs/architecture/02-scene-graph.md` §3).
10048
+ *
10049
+ * @remarks
10050
+ * Entities join it through `createEntity(name, { scene })` or `moveEntityToScene`. A persistent
10051
+ * instance survives every `"single"` load, so it is where a tool keeps objects that must outlive
10052
+ * the levels it loads: an editor's cameras, grid and gizmo roots. Like any instance other than the
10053
+ * implicit `"default"` one, it can be unloaded with `unloadScene`. Creating it raises no
10054
+ * `onSceneLoaded`, because nothing was loaded; `serializeScene` writes it only when it is passed.
10055
+ *
10056
+ * @param name - The instance's name.
10057
+ * @param options - Whether it is persistent.
10058
+ * @returns The new, empty instance, appended to `scenes`.
10059
+ *
10060
+ * @example
10061
+ * ```ts
10062
+ * const tools = world.createScene("editor", { persistent: true });
10063
+ * const camera = world.createEntity("Editor Camera", { scene: tools });
10064
+ * ```
10065
+ */
10066
+ createScene(name: string, options?: CreateSceneOptions): SceneInstance;
9465
10067
  /**
9466
10068
  * Unloads a scene instance: `onUnloading` fires while its entities are still valid, its roots are
9467
10069
  * destroyed through the normal destroy path (children before parents, `onDisable` then
@@ -9715,6 +10317,46 @@ interface LoadSceneOptions {
9715
10317
  /** `true` turns an `IGX-0604` instance hash mismatch from a logged warning into a throw. */
9716
10318
  readonly strictInstanceHashes?: boolean;
9717
10319
  }
10320
+ /**
10321
+ * Options accepted by {@link World.loadSceneFile}.
10322
+ *
10323
+ * @public
10324
+ */
10325
+ interface LoadSceneFileOptions {
10326
+ /**
10327
+ * The address the scene is published at in `app.assets`, for example
10328
+ * `"levels/level01.scene.json"`, or a `memory:` address for a file that was never saved. It
10329
+ * replaces whatever the cache held there. The file is never fetched from it.
10330
+ */
10331
+ readonly address: string;
10332
+ /** The instance's name; defaults to the file's `name`. */
10333
+ readonly name?: string;
10334
+ /**
10335
+ * `"single"` (the default) unloads every instance that is not `persistent` first; `"additive"`
10336
+ * keeps them.
10337
+ */
10338
+ readonly mode?: "single" | "additive";
10339
+ /** Cancels the dependency loads; an abort rejects with `IGX-0502`. */
10340
+ readonly signal?: AbortSignal;
10341
+ /** Makes the instance `world.activeScene`. Defaults to `true` for `"single"`, `false` for `"additive"`. */
10342
+ readonly setActive?: boolean;
10343
+ /** `true` turns an `IGX-0604` instance hash mismatch from a logged warning into a throw. */
10344
+ readonly strictInstanceHashes?: boolean;
10345
+ /**
10346
+ * Receives every recoverable problem the build found (`SceneBuildResult.issues`), in order. They
10347
+ * are also written to the app log as warnings, as for `loadScene`.
10348
+ */
10349
+ readonly onIssue?: (issue: SceneLoadIssue) => void;
10350
+ }
10351
+ /**
10352
+ * Options accepted by {@link World.createScene}.
10353
+ *
10354
+ * @public
10355
+ */
10356
+ interface CreateSceneOptions {
10357
+ /** Whether the instance survives a `"single"` scene load. Defaults to `false`. */
10358
+ readonly persistent?: boolean;
10359
+ }
9718
10360
  /**
9719
10361
  * Options accepted by {@link World.instantiate} and {@link World.instantiateAsync}
9720
10362
  * (`docs/architecture/02-scene-graph.md` §2).
@@ -9908,6 +10550,27 @@ interface EntityInstanceLink {
9908
10550
  readonly asset: AssetHandle<SceneAsset> | null;
9909
10551
  /** The scene value, so the serializer can diff current state against it. */
9910
10552
  readonly scene: SceneAsset;
10553
+ /**
10554
+ * Set when the instance root *is* the instanced scene's single root, rather than a container
10555
+ * holding the scene's roots (`06-serialization-and-scene-format.md` §2).
10556
+ */
10557
+ readonly root: InstancedRoot | null;
10558
+ }
10559
+ /**
10560
+ * What an instance root that stands for its scene's single root took from that root.
10561
+ *
10562
+ * @internal
10563
+ */
10564
+ interface InstancedRoot {
10565
+ /** The uid of the root's record in the instanced file, which overrides address. */
10566
+ readonly sourceUid: string;
10567
+ /** Expanded component uid to the uid the instanced root's record gives that component. */
10568
+ readonly componentSourceUids: ReadonlyMap<string, string>;
10569
+ /**
10570
+ * Every component the instancing put on the entity, including those a variant's own instance
10571
+ * merged in; the serializer writes the others as the entry's own `components`.
10572
+ */
10573
+ readonly components: ReadonlySet<string>;
9911
10574
  }
9912
10575
  /**
9913
10576
  * The engine-owned state of one entity.
@@ -10107,6 +10770,11 @@ export declare class Entity {
10107
10770
  * The immovability hint: `true` promises that the transform will not change after `awake`, which
10108
10771
  * lets the 2D batcher, physics, and navmesh treat the entity as static.
10109
10772
  *
10773
+ * @remarks
10774
+ * It can be changed only in files or before `awake`; afterwards the setter throws `IGX-0101`. In an
10775
+ * edit-mode app it stays writable, because an editor's inspector edits it on loaded entities
10776
+ * (ADR-0028).
10777
+ *
10110
10778
  * @returns `true` when the entity is marked static.
10111
10779
  */
10112
10780
  get isStatic(): boolean;
@@ -10206,6 +10874,21 @@ export declare class Entity {
10206
10874
  * ```
10207
10875
  */
10208
10876
  setParent(parent: Entity | null, options?: SetParentOptions): void;
10877
+ /**
10878
+ * Moves the entity among its siblings: its parent's children, or its scene's roots when it has no
10879
+ * parent. Sibling order is the order a scene file lists entities in and the order `children`
10880
+ * reports.
10881
+ *
10882
+ * @param index - The entity's new index among its siblings. A value past either end is clamped
10883
+ * to that end, and a fraction is truncated.
10884
+ * @throws IgnifxError with code `IGX-0101` when the entity has been destroyed.
10885
+ *
10886
+ * @example
10887
+ * ```ts
10888
+ * weapon.setSiblingIndex(0); // first child of its parent
10889
+ * ```
10890
+ */
10891
+ setSiblingIndex(index: number): void;
10209
10892
  /**
10210
10893
  * Resolves a path relative to this entity — `"Body/Arm.L"`, `"../Sibling"`, `"/Root/Child"`.
10211
10894
  *
@@ -10638,6 +11321,15 @@ interface ComponentHooks {
10638
11321
  onAttach?(): void;
10639
11322
  /** Runs just before the component is removed, after `onDestroy`. */
10640
11323
  onDetach?(): void;
11324
+ /**
11325
+ * Runs after a tool changed the component's serialized fields from outside it: an editor's
11326
+ * inspector or document op, or a hot reload that gave a field its new default. The engine's own
11327
+ * loads and a script's assignments do not call it. A component that builds something from its
11328
+ * fields (a physics shape, say) rebuilds it here. Not gated in edit mode (ADR-0028).
11329
+ *
11330
+ * @param fields - The names of the fields that changed.
11331
+ */
11332
+ onValidate?(fields: readonly string[]): void;
10641
11333
  }
10642
11334
  /**
10643
11335
  * The abstract base class `Component.define` returns: a `Component` that also carries every
@@ -10697,8 +11389,8 @@ interface ComponentStatics {
10697
11389
  }
10698
11390
  /**
10699
11391
  * The static members a script class may declare: everything {@link ComponentStatics} allows plus
10700
- * the two scheduling flags (`docs/architecture/01-lifecycle-and-time.md` §3). Structural and
10701
- * optional for the reason given on {@link ComponentStatics}.
11392
+ * the scheduling flags (`docs/architecture/01-lifecycle-and-time.md` §3). Structural and optional
11393
+ * for the reason given on {@link ComponentStatics}.
10702
11394
  *
10703
11395
  * @public
10704
11396
  */
@@ -10713,6 +11405,22 @@ interface ScriptStatics extends ComponentStatics {
10713
11405
  * Defaults to `false`.
10714
11406
  */
10715
11407
  readonly updateWhenPaused?: boolean;
11408
+ /**
11409
+ * When `true`, the script receives its callbacks in an edit-mode app
11410
+ * (`createApp({ editMode: true })`, ADR-0028), as an editor camera or a tool script needs.
11411
+ * Defaults to `false`: in edit mode a script gets no `awake`, `update`, or any other callback.
11412
+ *
11413
+ * @example
11414
+ * ```ts
11415
+ * class EditorCamera extends Script {
11416
+ * static runInEditMode = true;
11417
+ * update(dt: number): void {
11418
+ * this.transform.translate({ x: 0, y: 0, z: dt });
11419
+ * }
11420
+ * }
11421
+ * ```
11422
+ */
11423
+ readonly runInEditMode?: boolean;
10716
11424
  }
10717
11425
  /**
10718
11426
  * A component class used as a **query token** — `entity.getComponent(Type)`,
@@ -12418,6 +13126,12 @@ interface SystemContext {
12418
13126
  * `updateWhenPaused` — so a system that animates checks `time.paused` itself.
12419
13127
  */
12420
13128
  readonly dt: number;
13129
+ /**
13130
+ * `true` when the scheduler is holding this system's clock: in an edit-mode app, for a system
13131
+ * registered with `editMode: "hold"` (ADR-0028). `dt` is `0` then, and a system that reads
13132
+ * `time` directly treats the frame as paused.
13133
+ */
13134
+ readonly isClockHeld: boolean;
12421
13135
  }
12422
13136
  /**
12423
13137
  * Engine-level logic that runs once per phase over many components, registered by an extension
@@ -12681,6 +13395,8 @@ interface CoroutineHost {
12681
13395
  * @param owner - The script whose enabled state gates the coroutine.
12682
13396
  * @param routine - The generator to drive.
12683
13397
  * @returns A handle for stopping it or waiting on it.
13398
+ * @throws IgnifxError with code `IGX-0111` in an edit-mode app when the owner's class does not
13399
+ * set `static runInEditMode = true`.
12684
13400
  */
12685
13401
  start(owner: Script, routine: Coroutine): CoroutineHandle;
12686
13402
  /**
@@ -12811,6 +13527,12 @@ interface App {
12811
13527
  readonly onError: Signal<ErrorReport>;
12812
13528
  /** `true` when the app runs on Lite's null engine with no render surface. */
12813
13529
  readonly isHeadless: boolean;
13530
+ /**
13531
+ * `true` when the app was created with `createApp({ editMode: true })`: an editor's scene view
13532
+ * (ADR-0028). Scripts get no callbacks unless their class sets `static runInEditMode = true`,
13533
+ * the fixed loop and physics do not run, and coroutines cannot start. Fixed for the app's life.
13534
+ */
13535
+ readonly isEditMode: boolean;
12814
13536
  /** `true` between `start()` and `stop()`/`dispose()`. */
12815
13537
  readonly isRunning: boolean;
12816
13538
  /** The `@ignifx/core` version this app was built from. */
@@ -12904,7 +13626,33 @@ interface RegisterSystemOptions {
12904
13626
  readonly phase: Phase;
12905
13627
  /** Ascending order within the phase; core uses `[-1000, 1000]`, extensions `[1001, 9999]`. */
12906
13628
  readonly order?: number;
13629
+ /**
13630
+ * What the system does in an edit-mode app (ADR-0028). Defaults to `"run"`. Ignored when the app
13631
+ * is not in edit mode.
13632
+ */
13633
+ readonly editMode?: SystemEditMode;
12907
13634
  }
13635
+ /**
13636
+ * What a system does in an edit-mode app (`createApp({ editMode: true })`, ADR-0028).
13637
+ *
13638
+ * - `"run"`: runs as it does in a game. Right for systems that turn component data into what is
13639
+ * drawn, heard, or laid out.
13640
+ * - `"hold"`: runs with `ctx.dt` set to `0` and `ctx.isClockHeld` set to `true`, so it shows its
13641
+ * current state without moving it forward.
13642
+ * - `"skip"`: does not run. Right for simulation, and for systems that would overwrite authored
13643
+ * data such as a transform.
13644
+ *
13645
+ * A `FixedUpdate` system never runs in edit mode, whatever it declares, because the fixed loop does
13646
+ * not run.
13647
+ *
13648
+ * @example
13649
+ * ```ts
13650
+ * ctx.registerSystem(new WindSystem(), { phase: Phase.Update, editMode: "skip" });
13651
+ * ```
13652
+ *
13653
+ * @public
13654
+ */
13655
+ type SystemEditMode = "run" | "hold" | "skip";
12908
13656
  /**
12909
13657
  * An extension's registration surface (`docs/architecture/04-extensions.md` §1). Everything an
12910
13658
  * extension contributes is declared here; nothing happens at module import time
@@ -13371,6 +14119,17 @@ interface CreateAppOptions {
13371
14119
  * rebuilds the live instances built from it.
13372
14120
  */
13373
14121
  readonly hotReload?: HotReloadOptions;
14122
+ /**
14123
+ * Builds the app for an editor's scene view (ADR-0028,
14124
+ * `docs/architecture/03-scripting-and-components.md` §10). Scripts get no lifecycle or frame
14125
+ * callbacks unless their class sets `static runInEditMode = true`; the fixed loop, physics, and
14126
+ * other simulation systems do not run; `startCoroutine` throws `IGX-0111` for a script that does
14127
+ * not run in edit mode. Systems that turn component data into what is drawn keep running. Fixed
14128
+ * for the app's life; `app.isEditMode` reports it.
14129
+ *
14130
+ * @defaultValue `false`
14131
+ */
14132
+ readonly editMode?: boolean;
13374
14133
  }
13375
14134
  /**
13376
14135
  * Creates a game (`docs/architecture/00-overview.md` §1, `04-extensions.md` §2).
@@ -13406,15 +14165,14 @@ export declare function createApp(options?: CreateAppOptions): Promise<App>;
13406
14165
  * `version` (`docs/architecture/04-extensions.md` §1).
13407
14166
  *
13408
14167
  * @remarks
13409
- * The literal is `"0.0.0"` in the repository and is stamped by the release pipeline: Changesets
13410
- * writes the real number into `package.json`, and the build replaces this constant with it
13411
- * (coding standards §12, `release.yml`). Reading the version from `package.json` at run time is not
13412
- * an option — that would be an import-time side effect and a bundler hazard
14168
+ * The build stamps it from `package.json`, where Changesets writes each release's number; code run
14169
+ * from source, such as this repository's tests, sees `"0.0.0"`. Reading `package.json` at run time
14170
+ * is not an option: that would be an import-time side effect and a bundler hazard
13413
14171
  * (`CONSTITUTION.md` §3.5).
13414
14172
  *
13415
14173
  * @public
13416
14174
  */
13417
- export declare const VERSION = "0.0.0";
14175
+ export declare const VERSION: string;
13418
14176
  //#endregion
13419
14177
  //#region src/assets/asset-ref.d.ts
13420
14178
  /**
@@ -15732,696 +16490,846 @@ export declare function createFontLoader(): AssetLoader<FontAsset>;
15732
16490
  */
15733
16491
  export declare function createMaterialLoader(): AssetLoader<MaterialAsset>;
15734
16492
  //#endregion
15735
- //#region src/lite/gpu/gltf.d.ts
16493
+ //#region src/render/mesh-asset.d.ts
15736
16494
  /**
15737
- * glTF half of the Babylon Lite adapter (`docs/architecture/07-rendering.md` §2.4): loading a
15738
- * `.glb` into an asset container, and instantiating that container under an entity node.
15739
- *
15740
- * Everything here is `@internal`. `loadGltf` uploads vertex buffers and textures, so the module is
15741
- * GPU-only.
15742
- *
15743
- * ## What a container holds (verified against `@babylonjs/lite@1.27.0`)
15744
- *
15745
- * `loadGltf(engine, source)` (`index.d.ts` 6821) — reached through the dynamically imported
15746
- * `./gltf-source.ts`, so that a game which loads no model carries no glTF parser — takes a URL, an
15747
- * `ArrayBuffer`, or a `Blob` and
15748
- * resolves to an `AssetContainer` (`index.d.ts` 653) whose `entities` is `[rootTransformNode]` for
15749
- * glTF. The ignifx asset layer fetches the bytes itself — that is where progress reporting and
15750
- * `AbortSignal` support live (`docs/architecture/05-assets-and-loading.md`) — and hands Lite an
15751
- * `ArrayBuffer`, so this adapter never fetches.
15752
- *
15753
- * ## Animation groups are stripped, not ticked
15754
- *
15755
- * `addToScene` pushes a container's `animationGroups` onto the scene and installs a before-render
15756
- * hook that calls `tickAnimation` for each one (`lib/scene/scene-core.js`). ADR-0003 says ignifx
15757
- * owns time, so {@link takeAnimationGroups} removes them from the container *before* it is added:
15758
- * Lite then registers no hook, and ignifx's animation system advances the clips itself.
15759
- *
15760
- * ## Instancing
15761
- *
15762
- * `cloneTransformNode` on the container root deep-clones the transform hierarchy while every mesh
15763
- * in it shares the original's `_gpu` wrapper and bumps its reference count
15764
- * (`lib/scene/transform-node.js`) — so N instances of a model upload one copy of the geometry. Lights
15765
- * inside the subtree are shallow-copied as plain objects rather than cloned; glTF cameras are only
15766
- * present at all when `enableGltfCameras()` ran before the load.
16495
+ * Mesh templates share geometry with renderer clones (ADR-0002).
16496
+ * Factories register a loaded handle with one caller-owned hold; release it when no longer needed.
16497
+ * Existing clones survive collection, but a disposed template cannot make new clones.
16498
+ * Headless mesh assets keep component state without GPU geometry.
15767
16499
  */
15768
16500
  /**
15769
- * The Babylon Lite asset container a `ModelAsset` holds, re-exported under an ignifx name
15770
- * (`CONSTITUTION.md` §3.4, coding standards §4).
15771
- *
15772
- * @remarks
15773
- * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
16501
+ * The asset type primitives are registered under.
15774
16502
  *
15775
16503
  * @public
15776
16504
  */
15777
- type LiteAssetContainer = AssetContainer;
16505
+ export declare const MESH_ASSET_TYPE = "mesh";
15778
16506
  /**
15779
- * A Babylon Lite animation clip, re-exported under an ignifx name. `Model.animations` hands these
15780
- * to `@ignifx/3d`'s animator, which owns advancement (ADR-0003).
15781
- *
15782
- * @remarks
15783
- * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
16507
+ * How {@link MeshAsset.box} sizes its box, in metres. Give `size` for a cube, or the three
16508
+ * dimensions.
15784
16509
  *
15785
- * @beta
16510
+ * @public
15786
16511
  */
15787
- type LiteAnimationGroup = AnimationGroup;
16512
+ interface BoxMeshOptions {
16513
+ /** Edge length on every axis. */
16514
+ readonly size?: number;
16515
+ /** Size along X, overriding `size`. */
16516
+ readonly width?: number;
16517
+ /** Size along Y, overriding `size`. */
16518
+ readonly height?: number;
16519
+ /** Size along Z, overriding `size`. */
16520
+ readonly depth?: number;
16521
+ }
15788
16522
  /**
15789
- * A Babylon Lite skeleton, re-exported under an ignifx name. Present on a container only when
15790
- * `enableBoneControl()` ran before the load (`index.d.ts` 653).
15791
- *
15792
- * @remarks
15793
- * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
16523
+ * How {@link MeshAsset.sphere} tessellates its sphere.
15794
16524
  *
15795
- * @beta
16525
+ * @public
15796
16526
  */
15797
- type LiteSkeleton = Skeleton;
15798
- //#endregion
15799
- //#region src/render/model-asset.d.ts
16527
+ interface SphereMeshOptions {
16528
+ /** Diameter on every axis, in metres. Lite defaults to 1. */
16529
+ readonly diameter?: number;
16530
+ /** Ring count; higher is smoother. Lite defaults to 32. */
16531
+ readonly segments?: number;
16532
+ }
15800
16533
  /**
15801
- * `ModelAsset` (`docs/architecture/05-assets-and-loading.md` §5 and §6,
15802
- * `07-rendering.md` §2.4): the loaded glTF container a `Model` component instantiates.
16534
+ * How {@link MeshAsset.plane} sizes its quad, which lies in the XY plane facing `-Z`.
15803
16535
  *
15804
- * ## The container is a template, not a scene member
16536
+ * @public
16537
+ */
16538
+ interface PlaneMeshOptions {
16539
+ /** Edge length on both axes, in metres. */
16540
+ readonly size?: number;
16541
+ /** Width, overriding `size`. */
16542
+ readonly width?: number;
16543
+ /** Height, overriding `size`. */
16544
+ readonly height?: number;
16545
+ }
16546
+ /**
16547
+ * How {@link MeshAsset.ground} sizes and subdivides its grid, which lies in the XZ plane facing
16548
+ * `+Y`.
15805
16549
  *
15806
- * `loadGltf` resolves to an `AssetContainer` whose `entities` is `[rootTransformNode]`
15807
- * (`index.d.ts` 653). ignifx never adds that container to a scene. Each `Model` clones it instead
15808
- * (`cloneTransformNode`), which deep-copies the transform hierarchy while every mesh shares the
15809
- * original's GPU buffers under a reference count — so ten instances of a model upload one copy of
15810
- * the geometry (`src/lite/gpu/gltf.ts`). Keeping the container out of the scene is also what makes
15811
- * the first instance cost the same as the tenth, and what lets the asset outlive any one of them.
15812
- *
15813
- * ## Animation groups are taken, not ticked
16550
+ * @public
16551
+ */
16552
+ interface GroundMeshOptions {
16553
+ /** Size along X, in metres. */
16554
+ readonly width?: number;
16555
+ /** Size along Z, in metres. */
16556
+ readonly height?: number;
16557
+ /** Quads per side. */
16558
+ readonly subdivisions?: number;
16559
+ /** UV multiplier, for tiling a texture across the grid. */
16560
+ readonly uvScale?: readonly [number, number];
16561
+ }
16562
+ /**
16563
+ * How {@link MeshAsset.cylinder} sizes its cylinder, which stands along Y.
15814
16564
  *
15815
- * `addToScene` would register a container's `animationGroups` with Lite's own animation manager and
15816
- * install a before-render hook for them. ADR-0003 says ignifx owns every clock, so the loader
15817
- * removes them from the container the moment it is loaded and the asset keeps them
15818
- * ({@link ModelAsset.animations}). Core exposes them and advances nothing; `@ignifx/3d`'s
15819
- * `Animator` is what plays them.
16565
+ * @public
16566
+ */
16567
+ interface CylinderMeshOptions {
16568
+ /** Height along Y, in metres. */
16569
+ readonly height?: number;
16570
+ /** Diameter of both ends. */
16571
+ readonly diameter?: number;
16572
+ /** Diameter of the top cap, overriding `diameter` — a cone is `diameterTop: 0`. */
16573
+ readonly diameterTop?: number;
16574
+ /** Diameter of the bottom cap, overriding `diameter`. */
16575
+ readonly diameterBottom?: number;
16576
+ /** Radial segment count. */
16577
+ readonly tessellation?: number;
16578
+ }
16579
+ /**
16580
+ * How {@link MeshAsset.capsule} sizes its capsule, which stands along Y.
15820
16581
  *
15821
- * ## Instance counting
16582
+ * @remarks
16583
+ * `height` is the **total** height including both caps, the same convention `@ignifx/physics` uses
16584
+ * for a capsule collider, so one pair of numbers describes both.
15822
16585
  *
15823
- * Instances are counted so the template's GPU resources live until the last instance and the asset
15824
- * handle are gone (`05-assets-and-loading.md` §6). {@link ModelAsset.retainInstance} and
15825
- * {@link ModelAsset.releaseInstance} are that counter; `Model` calls them, and
15826
- * {@link ModelAsset.instanceCount} is what a test asserts on.
16586
+ * @public
16587
+ */
16588
+ interface CapsuleMeshOptions {
16589
+ /** Total height including both caps, in metres. */
16590
+ readonly height?: number;
16591
+ /** Radius of the body and the caps. */
16592
+ readonly radius?: number;
16593
+ /** Radial segment count. */
16594
+ readonly tessellation?: number;
16595
+ }
16596
+ /**
16597
+ * How {@link MeshAsset.torus} sizes its ring, which lies in the XZ plane.
15827
16598
  *
15828
- * ## Headless
16599
+ * @public
16600
+ */
16601
+ interface TorusMeshOptions {
16602
+ /** Outer diameter, in metres. */
16603
+ readonly diameter?: number;
16604
+ /** Tube thickness, in metres. */
16605
+ readonly thickness?: number;
16606
+ /** Segment count around the ring. */
16607
+ readonly tessellation?: number;
16608
+ }
16609
+ /**
16610
+ * The primitive shapes a `MeshAsset` factory and a `.mesh.json` file can build.
15829
16611
  *
15830
- * `loadGltf` throws a `TypeError` under the null engine — it reaches for `engine._device` while
15831
- * uploading (ADR-0002 Validation) — so a headless load skips it entirely and produces an asset with
15832
- * `lite.container === null`. A `Model` that holds one keeps its fields, reports an empty `nodes`
15833
- * map, and touches no scene (`07-rendering.md` §6).
16612
+ * @public
15834
16613
  */
16614
+ export declare const MESH_PRIMITIVES: readonly ["box", "sphere", "plane", "ground", "cylinder", "capsule", "torus"];
15835
16615
  /**
15836
- * The asset type models are registered under.
16616
+ * One of {@link MESH_PRIMITIVES}.
15837
16617
  *
15838
16618
  * @public
15839
16619
  */
15840
- export declare const MODEL_ASSET_TYPE = "model";
16620
+ type MeshPrimitive = (typeof MESH_PRIMITIVES)[number];
15841
16621
  /**
15842
- * The address suffixes that select the model loader.
16622
+ * A primitive and the options its factory takes: what a `.mesh.json` file declares.
15843
16623
  *
15844
16624
  * @public
15845
16625
  */
15846
- export declare const MODEL_FILE_EXTENSIONS: readonly string[];
16626
+ type MeshPrimitiveDefinition = {
16627
+ readonly primitive: "box";
16628
+ readonly options: BoxMeshOptions;
16629
+ } | {
16630
+ readonly primitive: "sphere";
16631
+ readonly options: SphereMeshOptions;
16632
+ } | {
16633
+ readonly primitive: "plane";
16634
+ readonly options: PlaneMeshOptions;
16635
+ } | {
16636
+ readonly primitive: "ground";
16637
+ readonly options: GroundMeshOptions;
16638
+ } | {
16639
+ readonly primitive: "cylinder";
16640
+ readonly options: CylinderMeshOptions;
16641
+ } | {
16642
+ readonly primitive: "capsule";
16643
+ readonly options: CapsuleMeshOptions;
16644
+ } | {
16645
+ readonly primitive: "torus";
16646
+ readonly options: TorusMeshOptions;
16647
+ };
15847
16648
  /**
15848
- * The Babylon Lite objects a {@link ModelAsset} owns. Unstable escape hatch
15849
- * (`docs/architecture/00-overview.md` §3).
16649
+ * Raw vertex data for {@link MeshAsset.fromData}.
16650
+ *
16651
+ * @remarks
16652
+ * Lite keeps references to these arrays rather than copying them — they are what its CPU ray pick
16653
+ * and its bounds read (`lib/mesh/mesh-factories.js`). Mutating one behind Lite's back changes what
16654
+ * a pick reports without changing what the GPU draws; the sanctioned way to change geometry after
16655
+ * the fact is {@link MeshAsset.updatePositions} and its three siblings, which re-upload, keep this
16656
+ * copy in step, and re-fit the bounds.
15850
16657
  *
15851
16658
  * @public
15852
16659
  */
15853
- interface ModelAssetLiteHandles {
15854
- /** The template container, or `null` under a headless app. */
15855
- readonly container: LiteAssetContainer | null;
16660
+ interface MeshGeometryData {
16661
+ /** Three floats per vertex. */
16662
+ readonly positions: Float32Array;
16663
+ /** Three floats per vertex, one normal each. */
16664
+ readonly normals: Float32Array;
16665
+ /** Three indices per triangle. */
16666
+ readonly indices: Uint32Array;
16667
+ /** Two floats per vertex, or omitted for a mesh with no texture coordinates. */
16668
+ readonly uvs?: Float32Array;
16669
+ /**
16670
+ * Two floats per vertex for the second UV set (`uv2` in a shader), or omitted. Lightmaps, baked
16671
+ * ambient occlusion, and the parent-LOD height a terrain morph reads all ride here.
16672
+ */
16673
+ readonly uvs2?: Float32Array;
16674
+ /** Four floats per vertex — `xyz` plus a handedness `w` — or omitted. A normal map needs them. */
16675
+ readonly tangents?: Float32Array;
16676
+ /**
16677
+ * Four floats per vertex, linear RGBA, or omitted. A material has to be one that reads the colour
16678
+ * attribute; set `hasVertexAlpha` on the Lite mesh if the alpha is meant to blend.
16679
+ */
16680
+ readonly colors?: Float32Array;
15856
16681
  }
15857
16682
  /**
15858
- * One instantiated copy of a model, as a `Model` component holds it.
16683
+ * The Babylon Lite objects a {@link MeshAsset} owns. Unstable escape hatch
16684
+ * (`docs/architecture/00-overview.md` §3).
15859
16685
  *
15860
16686
  * @public
15861
16687
  */
15862
- interface ModelInstantiation {
15863
- /** The cloned container root, parented under the entity's node. */
15864
- readonly root: LiteSceneNode;
15865
- /** Every named node in the clone, keyed by its glTF node name. */
15866
- readonly nodes: ReadonlyMap<string, LiteSceneNode>;
16688
+ interface MeshAssetLiteHandles {
16689
+ /** The template mesh, or `null` under a headless app, which uploads no geometry. */
16690
+ readonly mesh: LiteMesh | null;
15867
16691
  }
15868
16692
  /**
15869
- * A loaded glTF or GLB file (`docs/architecture/05-assets-and-loading.md` §5).
16693
+ * A geometry template a `MeshRenderer` draws (`docs/architecture/07-rendering.md` §2.3).
16694
+ *
16695
+ * @remarks
16696
+ * Build one with a primitive factory or {@link MeshAsset.fromData}; each returns the handle the
16697
+ * `MeshRenderer.mesh` field takes. A `.mesh.json` file loads the same primitives by address
16698
+ * (`app.assets.load("meshes/crate.mesh.json")`), so a scene file can name one. A glTF mesh
16699
+ * arrives as part of a `ModelAsset` instead — a glTF is a tree of meshes, materials, and
16700
+ * animations, not one buffer.
15870
16701
  *
15871
16702
  * @example
15872
16703
  * ```ts
15873
- * const hero = await app.assets.loadAsync<ModelAsset>("models/hero.glb");
15874
- * hero.value.animations.map((clip) => clip.name);
16704
+ * const box = MeshAsset.box(app, { size: 2 }); // one reference, owned by this code
16705
+ * const cube = app.world.createEntity("Cube");
16706
+ * cube.addComponent(MeshRenderer, { mesh: box }); // the field takes no reference
16707
+ * // Once nothing draws the box any more:
16708
+ * box.release();
15875
16709
  * ```
15876
16710
  *
15877
16711
  * @public
15878
16712
  */
15879
- export declare class ModelAsset {
16713
+ export declare class MeshAsset {
15880
16714
  #private;
15881
- /** The type name the asset service registers models under. */
16715
+ /** The type name the asset service registers meshes under. */
15882
16716
  static assetType: string;
15883
- /** The address the model was loaded from. */
15884
- readonly address: string;
16717
+ /** A human-readable name, used in diagnostics and as the Lite mesh's name. */
16718
+ readonly name: string;
15885
16719
  /**
15886
- * The clips the file declared, stripped from the container so Lite never ticks them.
16720
+ * Wraps a template mesh. Use the static factories; the engine constructs assets.
15887
16721
  *
15888
- * @remarks
15889
- * Unstable: these are Lite's own animation groups, handed on to `@ignifx/3d`'s `Animator`, and
15890
- * they are excluded from the stability guarantees of `CONSTITUTION.md` Article IV. To core they
15891
- * are read-only metadata: nothing here advances or re-binds them.
16722
+ * @param name - A human-readable name.
16723
+ * @param mesh - The template, or `null` when the app is headless.
16724
+ * @param scene - The scene the template is released through, or `null` when there is nothing to
16725
+ * release.
16726
+ * @param geometry - The vertex arrays the asset was built from, when it came from
16727
+ * {@link MeshAsset.fromData}; `null` for a primitive, whose arrays Lite generated and never
16728
+ * handed back. It is what makes the `update*` methods legal.
16729
+ * @param engine - The engine an update writes through, or `null` under a headless app.
15892
16730
  *
15893
- * @beta
16731
+ * @internal
15894
16732
  */
15895
- readonly animations: readonly LiteAnimationGroup[];
16733
+ constructor(name: string, mesh: LiteMesh | null, scene: LiteScene | null, geometry?: MeshGeometryData | null, engine?: LiteEngine | null);
15896
16734
  /**
15897
- * The skeletons the file declared. Empty unless the `boneControl` rendering feature was on before
15898
- * the load, because Lite builds them only then (`index.d.ts` 653).
16735
+ * The Babylon Lite objects the asset owns. Unstable escape hatch
16736
+ * (`docs/architecture/00-overview.md` §3).
15899
16737
  *
15900
- * @beta
16738
+ * @returns The template mesh, or `null` under a headless app.
15901
16739
  */
15902
- readonly skeletons: readonly LiteSkeleton[];
16740
+ get lite(): MeshAssetLiteHandles;
15903
16741
  /**
15904
- * Wraps a loaded container. The `model` loader constructs these.
15905
- *
15906
- * @param address - The address it was loaded from.
15907
- * @param container - The template container, or `null` when the app is headless.
15908
- * @param animations - The clips taken off the container.
15909
- * @param skeletons - The skeletons the loader found.
15910
- * @param scene - The scene the container is released through, or `null` when headless.
16742
+ * Whether the template's GPU buffers have been released.
15911
16743
  *
15912
- * @internal
16744
+ * @returns `true` once {@link MeshAsset.dispose} has run.
15913
16745
  */
15914
- constructor(address: string, container: LiteAssetContainer | null, animations: readonly LiteAnimationGroup[], skeletons: readonly LiteSkeleton[], scene: LiteScene | null);
16746
+ get isDisposed(): boolean;
15915
16747
  /**
15916
- * The Babylon Lite objects the asset owns. Unstable escape hatch.
16748
+ * How many vertices the geometry has.
15917
16749
  *
15918
- * @returns The template container, or `null` under a headless app.
16750
+ * @remarks
16751
+ * Known for a mesh built with {@link MeshAsset.fromData} — headless included — and `0` for a
16752
+ * primitive: Lite generates a primitive's arrays internally and 1.27.0's `Mesh` exposes no vertex
16753
+ * count, only the opaque `MeshGPU` handle it says a user never touches (`index.d.ts` 7230).
16754
+ *
16755
+ * @returns The vertex count, or `0`.
15919
16756
  */
15920
- get lite(): ModelAssetLiteHandles;
16757
+ get vertexCount(): number;
15921
16758
  /**
15922
- * How many `Model` components currently hold a copy of this template.
16759
+ * How many indices the geometry has — three per triangle.
15923
16760
  *
15924
- * @returns The live instance count.
16761
+ * @returns The index count, or `0`; see {@link MeshAsset.vertexCount}.
15925
16762
  */
15926
- get instanceCount(): number;
16763
+ get indexCount(): number;
15927
16764
  /**
15928
- * Clones the template under an entity's node.
16765
+ * Re-uploads vertex positions and re-fits the bounds.
15929
16766
  *
15930
- * @param parent - The entity's transform node, or `null` for world space.
15931
- * @returns The cloned root and its named nodes, or `null` when there is nothing to clone — a
15932
- * headless app, or a file that declared only lights.
16767
+ * @remarks
16768
+ * Only a mesh from {@link MeshAsset.fromData} can be updated, and only while nothing has cloned it:
16769
+ * Lite refuses to write a vertex buffer with more than one owner, and a `MeshRenderer` clone is a
16770
+ * second owner.
16771
+ *
16772
+ * Lite's `updateMeshPositions` writes the GPU buffer and stops there, so this also copies the range
16773
+ * into the asset's own position array — the one Lite retained and CPU picking reads — and rewrites
16774
+ * the bounds from the whole of it, `O(vertexCount)` per call. Passing the asset's own array skips
16775
+ * the copy.
16776
+ *
16777
+ * @param data - Three floats per vertex, read from index 0.
16778
+ * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16779
+ * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16780
+ * @throws IgnifxError with code `IGX-0702` when the mesh did not come from
16781
+ * {@link MeshAsset.fromData}, or has been disposed.
16782
+ * @throws IgnifxError with code `IGX-0725` when the range falls outside the mesh or `data` is too
16783
+ * short for it.
16784
+ *
16785
+ * @example
16786
+ * ```ts
16787
+ * const grid = MeshAsset.fromData(app, "grid", { positions, normals, indices });
16788
+ * positions[1] += 0.5;
16789
+ * grid.value.updatePositions(positions);
16790
+ * ```
15933
16791
  */
15934
- instantiate(parent: LiteSceneNode | null): ModelInstantiation | null;
15935
- /** Records that one more `Model` holds a copy. */
15936
- retainInstance(): void;
15937
- /** Records that one fewer `Model` holds a copy. Releasing below zero is a no-op. */
15938
- releaseInstance(): void;
16792
+ updatePositions(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
15939
16793
  /**
15940
- * Releases the template's GPU resources.
16794
+ * Re-uploads vertex normals.
15941
16795
  *
15942
16796
  * @remarks
15943
- * The container was never added to a scene, so the round trip `removeFromScene` needs is the same
15944
- * one `MeshAsset.dispose` performs: this hands it to the scene and takes it straight back out,
15945
- * which drops its share of every buffer. Clones still in a scene keep theirs. Calling it twice is
15946
- * a no-op, and it is a no-op under a headless app.
15947
- */
15948
- dispose(): void;
15949
- /** Releases the template when the asset leaves a `using` block. */
15950
- [Symbol.dispose](): void;
15951
- }
15952
- //#endregion
15953
- //#region src/render/loaders/model-loader.d.ts
15954
- /**
15955
- * The `model` asset loader (`docs/architecture/05-assets-and-loading.md` §5).
15956
- *
15957
- * ## Bytes, not a URL
15958
- *
15959
- * `loadGltf` accepts a URL, an `ArrayBuffer`, or a `Blob`. ignifx hands it an `ArrayBuffer` fetched
15960
- * through `ctx.fetchBytes`, because that is where progress reporting, `AbortSignal` support, the
15961
- * priority queue, and the retry policy live (§5). A `.glb` is one file, so this is lossless.
15962
- *
15963
- * A `.gltf` with **external** buffers and images is the one case where it is not: Lite would have to
15964
- * resolve those relative URLs itself, which it can only do when it did the fetching. This loader
15965
- * loads the container from bytes either way and therefore supports self-contained `.gltf` files and
15966
- * `.glb`; a `.gltf` with siblings fails inside Lite and surfaces as `IGX-0505`. `.glb` is what the
15967
- * asset pipeline produces, and the fix — passing the URL through for that one shape — is a
15968
- * three-line change whenever a project needs it.
15969
- *
15970
- * ## Headless
15971
- *
15972
- * `loadGltf` throws a `TypeError` under the null engine: it uploads while parsing and reaches for
15973
- * `engine._device` (ADR-0002 Validation). So a headless load skips it entirely and produces an
15974
- * asset with no container — the `gpu: null` shape §5 requires — rather than failing. The bytes are
15975
- * still fetched, so a headless test still exercises the address, the manifest, and the byte
15976
- * counters.
15977
- */
16797
+ * The same rules as {@link MeshAsset.updatePositions}, minus the bounds: a normal cannot move a
16798
+ * bounding box. The range is copied into the asset's own normal array so that a later
16799
+ * `updatePositions` sees a consistent mesh.
16800
+ *
16801
+ * @param data - Three floats per vertex.
16802
+ * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16803
+ * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16804
+ * @throws IgnifxError with code `IGX-0702` or `IGX-0725`; see
16805
+ * {@link MeshAsset.updatePositions}.
16806
+ */
16807
+ updateNormals(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
16808
+ /**
16809
+ * Re-uploads texture coordinates.
16810
+ *
16811
+ * @remarks
16812
+ * Lite makes the upload a **no-op** when the mesh was created without UVs, rather than an error,
16813
+ * so a mesh whose `MeshGeometryData` named none silently ignores this. The range check still runs.
16814
+ *
16815
+ * @param data - Two floats per vertex.
16816
+ * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16817
+ * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16818
+ * @throws IgnifxError with code `IGX-0702` or `IGX-0725`; see
16819
+ * {@link MeshAsset.updatePositions}.
16820
+ */
16821
+ updateUvs(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
16822
+ /**
16823
+ * Re-uploads vertex colours.
16824
+ *
16825
+ * @remarks
16826
+ * Four floats per vertex, linear RGBA. A no-op on the GPU when the mesh was created without
16827
+ * colours, exactly as {@link MeshAsset.updateUvs} is.
16828
+ *
16829
+ * @param data - Four floats per vertex.
16830
+ * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16831
+ * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16832
+ * @throws IgnifxError with code `IGX-0702` or `IGX-0725`; see
16833
+ * {@link MeshAsset.updatePositions}.
16834
+ */
16835
+ updateColors(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
16836
+ /**
16837
+ * Releases the template's GPU buffers.
16838
+ *
16839
+ * @remarks
16840
+ * Lite exports no mesh disposer: a mesh's buffers are freed when it leaves its last scene, so the
16841
+ * adapter adds the template to a scene and takes it straight out again
16842
+ * (`src/lite/gpu/mesh.ts`). Clones still in a scene keep the shared buffers alive; what the
16843
+ * template loses is the ability to be cloned again. Calling it twice is a no-op, and it is a
16844
+ * no-op under a headless app, which has no buffers.
16845
+ */
16846
+ dispose(): void;
16847
+ /** Releases the template when the asset leaves a `using` block. */
16848
+ [Symbol.dispose](): void;
16849
+ /**
16850
+ * Creates a box template and publishes it.
16851
+ *
16852
+ * @param app - The app whose engine uploads the geometry and whose asset service holds the handle.
16853
+ * @param options - A uniform `size`, or per-axis dimensions.
16854
+ * @returns The handle, with one holder — the caller.
16855
+ *
16856
+ * @example
16857
+ * ```ts
16858
+ * const box = MeshAsset.box(app, { width: 2, height: 1, depth: 3 });
16859
+ * ```
16860
+ */
16861
+ static box(app: App, options?: BoxMeshOptions): AssetHandle<MeshAsset>;
16862
+ /**
16863
+ * Creates a sphere template and publishes it.
16864
+ *
16865
+ * @param app - The app that owns the engine and the asset service.
16866
+ * @param options - Diameter and ring count.
16867
+ * @returns The handle, with one holder.
16868
+ */
16869
+ static sphere(app: App, options?: SphereMeshOptions): AssetHandle<MeshAsset>;
16870
+ /**
16871
+ * Creates a quad template in the XY plane and publishes it.
16872
+ *
16873
+ * @param app - The app that owns the engine and the asset service.
16874
+ * @param options - A uniform `size`, or width and height.
16875
+ * @returns The handle, with one holder.
16876
+ */
16877
+ static plane(app: App, options?: PlaneMeshOptions): AssetHandle<MeshAsset>;
16878
+ /**
16879
+ * Creates a subdivided grid in the XZ plane and publishes it.
16880
+ *
16881
+ * @param app - The app that owns the engine and the asset service.
16882
+ * @param options - Width, depth, subdivisions, and UV scale.
16883
+ * @returns The handle, with one holder.
16884
+ */
16885
+ static ground(app: App, options?: GroundMeshOptions): AssetHandle<MeshAsset>;
16886
+ /**
16887
+ * Creates a cylinder template standing along Y and publishes it.
16888
+ *
16889
+ * @param app - The app that owns the engine and the asset service.
16890
+ * @param options - Height, diameters, and tessellation.
16891
+ * @returns The handle, with one holder.
16892
+ */
16893
+ static cylinder(app: App, options?: CylinderMeshOptions): AssetHandle<MeshAsset>;
16894
+ /**
16895
+ * Creates a capsule template standing along Y and publishes it.
16896
+ *
16897
+ * @param app - The app that owns the engine and the asset service.
16898
+ * @param options - Total height, radius, and tessellation.
16899
+ * @returns The handle, with one holder.
16900
+ */
16901
+ static capsule(app: App, options?: CapsuleMeshOptions): AssetHandle<MeshAsset>;
16902
+ /**
16903
+ * Creates a torus template in the XZ plane and publishes it.
16904
+ *
16905
+ * @param app - The app that owns the engine and the asset service.
16906
+ * @param options - Diameter, thickness, and tessellation.
16907
+ * @returns The handle, with one holder.
16908
+ */
16909
+ static torus(app: App, options?: TorusMeshOptions): AssetHandle<MeshAsset>;
16910
+ /**
16911
+ * Creates a template from raw vertex data and publishes it.
16912
+ *
16913
+ * @param app - The app that owns the engine and the asset service.
16914
+ * @param name - A human-readable name.
16915
+ * @param data - Positions, normals, indices, and any of the four optional attributes. Lite keeps
16916
+ * references to the arrays; a caller that means to edit them afterwards does so through the
16917
+ * `update*` methods, which keep Lite's own copy and its bounds in step.
16918
+ * @returns The handle, with one holder.
16919
+ *
16920
+ * @example
16921
+ * ```ts
16922
+ * const triangle = MeshAsset.fromData(app, "triangle", {
16923
+ * positions: Float32Array.from([0, 0, 0, 1, 0, 0, 0, 1, 0]),
16924
+ * normals: Float32Array.from([0, 0, -1, 0, 0, -1, 0, 0, -1]),
16925
+ * indices: Uint32Array.from([0, 1, 2]),
16926
+ * });
16927
+ * ```
16928
+ */
16929
+ static fromData(app: App, name: string, data: MeshGeometryData): AssetHandle<MeshAsset>;
16930
+ }
16931
+ //#endregion
16932
+ //#region src/render/loaders/mesh-loader.d.ts
15978
16933
  /**
15979
- * Builds the loader for `.glb` and `.gltf` addresses.
16934
+ * Builds the `mesh` loader: `.mesh.json` to `MeshAsset` (ADR-0029).
16935
+ *
16936
+ * @remarks
16937
+ * The file names a primitive and its options, and the loader builds it exactly as the matching
16938
+ * `MeshAsset` factory would. The mesh is named after the file's `name`, or its address. A headless
16939
+ * app builds no GPU geometry. A file that is not a mesh file fails the load with `IGX-0709`, a
16940
+ * format version other than 1 with `IGX-0603`, and an unknown primitive or a bad option with
16941
+ * `IGX-0507`. The same `mesh` type still holds the in-memory meshes the factories publish; the
16942
+ * loader's `unload` frees both kinds.
15980
16943
  *
15981
16944
  * @returns The loader to register with `ctx.registerAssetLoader`.
15982
16945
  *
15983
16946
  * @example
15984
16947
  * ```ts
15985
- * ctx.registerAssetLoader(createModelLoader());
16948
+ * ctx.registerAssetLoader(createMeshLoader());
15986
16949
  * ```
15987
16950
  *
15988
16951
  * @public
15989
16952
  */
15990
- export declare function createModelLoader(): AssetLoader<ModelAsset>;
16953
+ export declare function createMeshLoader(): AssetLoader<MeshAsset>;
15991
16954
  //#endregion
15992
- //#region src/render/loaders/texture-loader.d.ts
16955
+ //#region src/lite/gpu/gltf.d.ts
15993
16956
  /**
15994
- * The `texture` asset loader (`docs/architecture/05-assets-and-loading.md` §5).
16957
+ * glTF half of the Babylon Lite adapter (`docs/architecture/07-rendering.md` §2.4): loading a
16958
+ * `.glb` into an asset container, and instantiating that container under an entity node.
15995
16959
  *
15996
- * ## Lite fetches the bytes, not ignifx
16960
+ * Everything here is `@internal`. `loadGltf` uploads vertex buffers and textures, so the module is
16961
+ * GPU-only.
15997
16962
  *
15998
- * Every other GPU loader here reads through `ctx.fetchBytes`, which is what gives it progress,
15999
- * cancellation, and retries. A texture cannot: `loadTexture2D` takes a **URL** and decodes it with
16000
- * `createImageBitmap`, which is the browser's own hardware-accelerated decode path
16001
- * (`src/lite/gpu/texture.ts`). Handing it bytes would mean decoding a PNG in JavaScript. So the
16002
- * loader hands Lite `ctx.url` and reports its own coarse progress instead, and a texture's
16003
- * `AbortSignal` stops the *request* rather than the fetch. The trade is deliberate and it is the
16004
- * one place §5's "the three `fetch*` methods are the only network paths" does not hold; the
16005
- * alternative is worse.
16963
+ * ## What a container holds (verified against `@babylonjs/lite@1.27.0`)
16006
16964
  *
16007
- * ## Options come from the sidecar
16965
+ * `loadGltf(engine, source)` (`index.d.ts` 6821) — reached through the dynamically imported
16966
+ * `./gltf-source.ts`, so that a game which loads no model carries no glTF parser — takes a URL, an
16967
+ * `ArrayBuffer`, or a `Blob` and
16968
+ * resolves to an `AssetContainer` (`index.d.ts` 653) whose `entities` is `[rootTransformNode]` for
16969
+ * glTF. The ignifx asset layer fetches the bytes itself — that is where progress reporting and
16970
+ * `AbortSignal` support live (`docs/architecture/05-assets-and-loading.md`) — and hands Lite an
16971
+ * `ArrayBuffer`, so this adapter never fetches.
16008
16972
  *
16009
- * `.meta.json` sidecars carry per-asset import options (§7), the build copies them into the
16010
- * manifest entry, and `ctx.meta` is how a loader reads its own block. sRGB is the one that matters:
16011
- * a base-colour or emissive texture wants it, and a normal, ORM, or data map must not have it.
16012
- */
16013
- /**
16014
- * Builds the loader for `.png`, `.jpg`, `.jpeg`, `.webp`, `.ktx2`, and `.basis` addresses.
16973
+ * ## Animation groups are stripped, not ticked
16015
16974
  *
16016
- * @returns The loader to register with `ctx.registerAssetLoader`.
16975
+ * `addToScene` pushes a container's `animationGroups` onto the scene and installs a before-render
16976
+ * hook that calls `tickAnimation` for each one (`lib/scene/scene-core.js`). ADR-0003 says ignifx
16977
+ * owns time, so {@link takeAnimationGroups} removes them from the container *before* it is added:
16978
+ * Lite then registers no hook, and ignifx's animation system advances the clips itself.
16017
16979
  *
16018
- * @example
16019
- * ```ts
16020
- * ctx.registerAssetLoader(createTextureLoader());
16021
- * ```
16980
+ * ## Instancing
16022
16981
  *
16023
- * @public
16024
- */
16025
- export declare function createTextureLoader(): AssetLoader<TextureAsset>;
16026
- //#endregion
16027
- //#region src/render/mesh-asset.d.ts
16028
- /**
16029
- * Mesh templates share geometry with renderer clones (ADR-0002).
16030
- * Factories register a loaded handle with one caller-owned hold; release it when no longer needed.
16031
- * Existing clones survive collection, but a disposed template cannot make new clones.
16032
- * Headless mesh assets keep component state without GPU geometry.
16982
+ * `cloneTransformNode` on the container root deep-clones the transform hierarchy while every mesh
16983
+ * in it shares the original's `_gpu` wrapper and bumps its reference count
16984
+ * (`lib/scene/transform-node.js`) — so N instances of a model upload one copy of the geometry. Lights
16985
+ * inside the subtree are shallow-copied as plain objects rather than cloned; glTF cameras are only
16986
+ * present at all when `enableGltfCameras()` ran before the load.
16033
16987
  */
16034
16988
  /**
16035
- * The asset type primitives are registered under.
16989
+ * The Babylon Lite asset container a `ModelAsset` holds, re-exported under an ignifx name
16990
+ * (`CONSTITUTION.md` §3.4, coding standards §4).
16036
16991
  *
16037
- * @public
16038
- */
16039
- export declare const MESH_ASSET_TYPE = "mesh";
16040
- /**
16041
- * How {@link MeshAsset.box} sizes its box, in metres. Give `size` for a cube, or the three
16042
- * dimensions.
16992
+ * @remarks
16993
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
16043
16994
  *
16044
16995
  * @public
16045
16996
  */
16046
- interface BoxMeshOptions {
16047
- /** Edge length on every axis. */
16048
- readonly size?: number;
16049
- /** Size along X, overriding `size`. */
16050
- readonly width?: number;
16051
- /** Size along Y, overriding `size`. */
16052
- readonly height?: number;
16053
- /** Size along Z, overriding `size`. */
16054
- readonly depth?: number;
16055
- }
16997
+ type LiteAssetContainer = AssetContainer;
16056
16998
  /**
16057
- * How {@link MeshAsset.sphere} tessellates its sphere.
16999
+ * A Babylon Lite animation clip, re-exported under an ignifx name. `Model.animations` hands these
17000
+ * to `@ignifx/3d`'s animator, which owns advancement (ADR-0003).
16058
17001
  *
16059
- * @public
16060
- */
16061
- interface SphereMeshOptions {
16062
- /** Diameter on every axis, in metres. Lite defaults to 1. */
16063
- readonly diameter?: number;
16064
- /** Ring count; higher is smoother. Lite defaults to 32. */
16065
- readonly segments?: number;
16066
- }
16067
- /**
16068
- * How {@link MeshAsset.plane} sizes its quad, which lies in the XY plane facing `-Z`.
17002
+ * @remarks
17003
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
16069
17004
  *
16070
- * @public
17005
+ * @beta
16071
17006
  */
16072
- interface PlaneMeshOptions {
16073
- /** Edge length on both axes, in metres. */
16074
- readonly size?: number;
16075
- /** Width, overriding `size`. */
16076
- readonly width?: number;
16077
- /** Height, overriding `size`. */
16078
- readonly height?: number;
16079
- }
17007
+ type LiteAnimationGroup = AnimationGroup;
16080
17008
  /**
16081
- * How {@link MeshAsset.ground} sizes and subdivides its grid, which lies in the XZ plane facing
16082
- * `+Y`.
17009
+ * A Babylon Lite skeleton, re-exported under an ignifx name. Present on a container only when
17010
+ * `enableBoneControl()` ran before the load (`index.d.ts` 653).
16083
17011
  *
16084
- * @public
17012
+ * @remarks
17013
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
17014
+ *
17015
+ * @beta
16085
17016
  */
16086
- interface GroundMeshOptions {
16087
- /** Size along X, in metres. */
16088
- readonly width?: number;
16089
- /** Size along Z, in metres. */
16090
- readonly height?: number;
16091
- /** Quads per side. */
16092
- readonly subdivisions?: number;
16093
- /** UV multiplier, for tiling a texture across the grid. */
16094
- readonly uvScale?: readonly [number, number];
16095
- }
17017
+ type LiteSkeleton = Skeleton;
17018
+ //#endregion
17019
+ //#region src/render/model-asset.d.ts
16096
17020
  /**
16097
- * How {@link MeshAsset.cylinder} sizes its cylinder, which stands along Y.
17021
+ * `ModelAsset` (`docs/architecture/05-assets-and-loading.md` §5 and §6,
17022
+ * `07-rendering.md` §2.4): the loaded glTF container a `Model` component instantiates.
16098
17023
  *
16099
- * @public
17024
+ * ## The container is a template, not a scene member
17025
+ *
17026
+ * `loadGltf` resolves to an `AssetContainer` whose `entities` is `[rootTransformNode]`
17027
+ * (`index.d.ts` 653). ignifx never adds that container to a scene. Each `Model` clones it instead
17028
+ * (`cloneTransformNode`), which deep-copies the transform hierarchy while every mesh shares the
17029
+ * original's GPU buffers under a reference count — so ten instances of a model upload one copy of
17030
+ * the geometry (`src/lite/gpu/gltf.ts`). Keeping the container out of the scene is also what makes
17031
+ * the first instance cost the same as the tenth, and what lets the asset outlive any one of them.
17032
+ *
17033
+ * ## Animation groups are taken, not ticked
17034
+ *
17035
+ * `addToScene` would register a container's `animationGroups` with Lite's own animation manager and
17036
+ * install a before-render hook for them. ADR-0003 says ignifx owns every clock, so the loader
17037
+ * removes them from the container the moment it is loaded and the asset keeps them
17038
+ * ({@link ModelAsset.animations}). Core exposes them and advances nothing; `@ignifx/3d`'s
17039
+ * `Animator` is what plays them.
17040
+ *
17041
+ * ## Instance counting
17042
+ *
17043
+ * Instances are counted so the template's GPU resources live until the last instance and the asset
17044
+ * handle are gone (`05-assets-and-loading.md` §6). {@link ModelAsset.retainInstance} and
17045
+ * {@link ModelAsset.releaseInstance} are that counter; `Model` calls them, and
17046
+ * {@link ModelAsset.instanceCount} is what a test asserts on.
17047
+ *
17048
+ * ## Headless
17049
+ *
17050
+ * `loadGltf` throws a `TypeError` under the null engine — it reaches for `engine._device` while
17051
+ * uploading (ADR-0002 Validation) — so a headless load skips it entirely and produces an asset with
17052
+ * `lite.container === null`. A `Model` that holds one keeps its fields, reports an empty `nodes`
17053
+ * map, and touches no scene (`07-rendering.md` §6).
16100
17054
  */
16101
- interface CylinderMeshOptions {
16102
- /** Height along Y, in metres. */
16103
- readonly height?: number;
16104
- /** Diameter of both ends. */
16105
- readonly diameter?: number;
16106
- /** Diameter of the top cap, overriding `diameter` — a cone is `diameterTop: 0`. */
16107
- readonly diameterTop?: number;
16108
- /** Diameter of the bottom cap, overriding `diameter`. */
16109
- readonly diameterBottom?: number;
16110
- /** Radial segment count. */
16111
- readonly tessellation?: number;
16112
- }
16113
17055
  /**
16114
- * How {@link MeshAsset.capsule} sizes its capsule, which stands along Y.
16115
- *
16116
- * @remarks
16117
- * `height` is the **total** height including both caps, the same convention `@ignifx/physics` uses
16118
- * for a capsule collider, so one pair of numbers describes both.
17056
+ * The asset type models are registered under.
16119
17057
  *
16120
17058
  * @public
16121
17059
  */
16122
- interface CapsuleMeshOptions {
16123
- /** Total height including both caps, in metres. */
16124
- readonly height?: number;
16125
- /** Radius of the body and the caps. */
16126
- readonly radius?: number;
16127
- /** Radial segment count. */
16128
- readonly tessellation?: number;
16129
- }
17060
+ export declare const MODEL_ASSET_TYPE = "model";
16130
17061
  /**
16131
- * How {@link MeshAsset.torus} sizes its ring, which lies in the XZ plane.
17062
+ * The address suffixes that select the model loader.
16132
17063
  *
16133
17064
  * @public
16134
17065
  */
16135
- interface TorusMeshOptions {
16136
- /** Outer diameter, in metres. */
16137
- readonly diameter?: number;
16138
- /** Tube thickness, in metres. */
16139
- readonly thickness?: number;
16140
- /** Segment count around the ring. */
16141
- readonly tessellation?: number;
16142
- }
17066
+ export declare const MODEL_FILE_EXTENSIONS: readonly string[];
16143
17067
  /**
16144
- * Raw vertex data for {@link MeshAsset.fromData}.
16145
- *
16146
- * @remarks
16147
- * Lite keeps references to these arrays rather than copying them — they are what its CPU ray pick
16148
- * and its bounds read (`lib/mesh/mesh-factories.js`). Mutating one behind Lite's back changes what
16149
- * a pick reports without changing what the GPU draws; the sanctioned way to change geometry after
16150
- * the fact is {@link MeshAsset.updatePositions} and its three siblings, which re-upload, keep this
16151
- * copy in step, and re-fit the bounds.
17068
+ * The Babylon Lite objects a {@link ModelAsset} owns. Unstable escape hatch
17069
+ * (`docs/architecture/00-overview.md` §3).
16152
17070
  *
16153
17071
  * @public
16154
17072
  */
16155
- interface MeshGeometryData {
16156
- /** Three floats per vertex. */
16157
- readonly positions: Float32Array;
16158
- /** Three floats per vertex, one normal each. */
16159
- readonly normals: Float32Array;
16160
- /** Three indices per triangle. */
16161
- readonly indices: Uint32Array;
16162
- /** Two floats per vertex, or omitted for a mesh with no texture coordinates. */
16163
- readonly uvs?: Float32Array;
16164
- /**
16165
- * Two floats per vertex for the second UV set (`uv2` in a shader), or omitted. Lightmaps, baked
16166
- * ambient occlusion, and the parent-LOD height a terrain morph reads all ride here.
16167
- */
16168
- readonly uvs2?: Float32Array;
16169
- /** Four floats per vertex — `xyz` plus a handedness `w` — or omitted. A normal map needs them. */
16170
- readonly tangents?: Float32Array;
16171
- /**
16172
- * Four floats per vertex, linear RGBA, or omitted. A material has to be one that reads the colour
16173
- * attribute; set `hasVertexAlpha` on the Lite mesh if the alpha is meant to blend.
16174
- */
16175
- readonly colors?: Float32Array;
17073
+ interface ModelAssetLiteHandles {
17074
+ /** The template container, or `null` under a headless app. */
17075
+ readonly container: LiteAssetContainer | null;
16176
17076
  }
16177
17077
  /**
16178
- * The Babylon Lite objects a {@link MeshAsset} owns. Unstable escape hatch
16179
- * (`docs/architecture/00-overview.md` §3).
17078
+ * One instantiated copy of a model, as a `Model` component holds it.
16180
17079
  *
16181
17080
  * @public
16182
17081
  */
16183
- interface MeshAssetLiteHandles {
16184
- /** The template mesh, or `null` under a headless app, which uploads no geometry. */
16185
- readonly mesh: LiteMesh | null;
17082
+ interface ModelInstantiation {
17083
+ /** The cloned container root, parented under the entity's node. */
17084
+ readonly root: LiteSceneNode;
17085
+ /** Every named node in the clone, keyed by its glTF node name. */
17086
+ readonly nodes: ReadonlyMap<string, LiteSceneNode>;
16186
17087
  }
16187
17088
  /**
16188
- * A geometry template a `MeshRenderer` draws (`docs/architecture/07-rendering.md` §2.3).
16189
- *
16190
- * @remarks
16191
- * Build one with a primitive factory or {@link MeshAsset.fromData}; each returns the handle the
16192
- * `MeshRenderer.mesh` field takes. A mesh that came from a file arrives as part of a `ModelAsset`
16193
- * instead — a glTF is a tree of meshes, materials, and animations, not one buffer.
17089
+ * A loaded glTF or GLB file (`docs/architecture/05-assets-and-loading.md` §5).
16194
17090
  *
16195
17091
  * @example
16196
17092
  * ```ts
16197
- * const box = MeshAsset.box(app, { size: 2 }); // one reference, owned by this code
16198
- * const cube = app.world.createEntity("Cube");
16199
- * cube.addComponent(MeshRenderer, { mesh: box }); // the field takes no reference
16200
- * // Once nothing draws the box any more:
16201
- * box.release();
17093
+ * const hero = await app.assets.loadAsync<ModelAsset>("models/hero.glb");
17094
+ * hero.value.animations.map((clip) => clip.name);
16202
17095
  * ```
16203
17096
  *
16204
17097
  * @public
16205
17098
  */
16206
- export declare class MeshAsset {
17099
+ export declare class ModelAsset {
16207
17100
  #private;
16208
- /** The type name the asset service registers meshes under. */
17101
+ /** The type name the asset service registers models under. */
16209
17102
  static assetType: string;
16210
- /** A human-readable name, used in diagnostics and as the Lite mesh's name. */
16211
- readonly name: string;
16212
- /**
16213
- * Wraps a template mesh. Use the static factories; the engine constructs assets.
16214
- *
16215
- * @param name - A human-readable name.
16216
- * @param mesh - The template, or `null` when the app is headless.
16217
- * @param scene - The scene the template is released through, or `null` when there is nothing to
16218
- * release.
16219
- * @param geometry - The vertex arrays the asset was built from, when it came from
16220
- * {@link MeshAsset.fromData}; `null` for a primitive, whose arrays Lite generated and never
16221
- * handed back. It is what makes the `update*` methods legal.
16222
- * @param engine - The engine an update writes through, or `null` under a headless app.
16223
- *
16224
- * @internal
16225
- */
16226
- constructor(name: string, mesh: LiteMesh | null, scene: LiteScene | null, geometry?: MeshGeometryData | null, engine?: LiteEngine | null);
16227
- /**
16228
- * The Babylon Lite objects the asset owns. Unstable escape hatch
16229
- * (`docs/architecture/00-overview.md` §3).
16230
- *
16231
- * @returns The template mesh, or `null` under a headless app.
16232
- */
16233
- get lite(): MeshAssetLiteHandles;
16234
- /**
16235
- * Whether the template's GPU buffers have been released.
16236
- *
16237
- * @returns `true` once {@link MeshAsset.dispose} has run.
16238
- */
16239
- get isDisposed(): boolean;
17103
+ /** The address the model was loaded from. */
17104
+ readonly address: string;
16240
17105
  /**
16241
- * How many vertices the geometry has.
17106
+ * The clips the file declared, stripped from the container so Lite never ticks them.
16242
17107
  *
16243
17108
  * @remarks
16244
- * Known for a mesh built with {@link MeshAsset.fromData} — headless included — and `0` for a
16245
- * primitive: Lite generates a primitive's arrays internally and 1.27.0's `Mesh` exposes no vertex
16246
- * count, only the opaque `MeshGPU` handle it says a user never touches (`index.d.ts` 7230).
17109
+ * Unstable: these are Lite's own animation groups, handed on to `@ignifx/3d`'s `Animator`, and
17110
+ * they are excluded from the stability guarantees of `CONSTITUTION.md` Article IV. To core they
17111
+ * are read-only metadata: nothing here advances or re-binds them.
16247
17112
  *
16248
- * @returns The vertex count, or `0`.
17113
+ * @beta
16249
17114
  */
16250
- get vertexCount(): number;
17115
+ readonly animations: readonly LiteAnimationGroup[];
16251
17116
  /**
16252
- * How many indices the geometry has — three per triangle.
17117
+ * The skeletons the file declared. Empty unless the `boneControl` rendering feature was on before
17118
+ * the load, because Lite builds them only then (`index.d.ts` 653).
16253
17119
  *
16254
- * @returns The index count, or `0`; see {@link MeshAsset.vertexCount}.
17120
+ * @beta
16255
17121
  */
16256
- get indexCount(): number;
17122
+ readonly skeletons: readonly LiteSkeleton[];
16257
17123
  /**
16258
- * Re-uploads vertex positions and re-fits the bounds.
16259
- *
16260
- * @remarks
16261
- * Only a mesh from {@link MeshAsset.fromData} can be updated, and only while nothing has cloned it:
16262
- * Lite refuses to write a vertex buffer with more than one owner, and a `MeshRenderer` clone is a
16263
- * second owner.
16264
- *
16265
- * Lite's `updateMeshPositions` writes the GPU buffer and stops there, so this also copies the range
16266
- * into the asset's own position array — the one Lite retained and CPU picking reads — and rewrites
16267
- * the bounds from the whole of it, `O(vertexCount)` per call. Passing the asset's own array skips
16268
- * the copy.
17124
+ * Wraps a loaded container. The `model` loader constructs these.
16269
17125
  *
16270
- * @param data - Three floats per vertex, read from index 0.
16271
- * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16272
- * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16273
- * @throws IgnifxError with code `IGX-0702` when the mesh did not come from
16274
- * {@link MeshAsset.fromData}, or has been disposed.
16275
- * @throws IgnifxError with code `IGX-0725` when the range falls outside the mesh or `data` is too
16276
- * short for it.
17126
+ * @param address - The address it was loaded from.
17127
+ * @param container - The template container, or `null` when the app is headless.
17128
+ * @param animations - The clips taken off the container.
17129
+ * @param skeletons - The skeletons the loader found.
17130
+ * @param scene - The scene the container is released through, or `null` when headless.
16277
17131
  *
16278
- * @example
16279
- * ```ts
16280
- * const grid = MeshAsset.fromData(app, "grid", { positions, normals, indices });
16281
- * positions[1] += 0.5;
16282
- * grid.value.updatePositions(positions);
16283
- * ```
17132
+ * @internal
16284
17133
  */
16285
- updatePositions(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
17134
+ constructor(address: string, container: LiteAssetContainer | null, animations: readonly LiteAnimationGroup[], skeletons: readonly LiteSkeleton[], scene: LiteScene | null);
16286
17135
  /**
16287
- * Re-uploads vertex normals.
16288
- *
16289
- * @remarks
16290
- * The same rules as {@link MeshAsset.updatePositions}, minus the bounds: a normal cannot move a
16291
- * bounding box. The range is copied into the asset's own normal array so that a later
16292
- * `updatePositions` sees a consistent mesh.
17136
+ * The Babylon Lite objects the asset owns. Unstable escape hatch.
16293
17137
  *
16294
- * @param data - Three floats per vertex.
16295
- * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16296
- * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16297
- * @throws IgnifxError with code `IGX-0702` or `IGX-0725`; see
16298
- * {@link MeshAsset.updatePositions}.
17138
+ * @returns The template container, or `null` under a headless app.
16299
17139
  */
16300
- updateNormals(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
17140
+ get lite(): ModelAssetLiteHandles;
16301
17141
  /**
16302
- * Re-uploads texture coordinates.
16303
- *
16304
- * @remarks
16305
- * Lite makes the upload a **no-op** when the mesh was created without UVs, rather than an error,
16306
- * so a mesh whose `MeshGeometryData` named none silently ignores this. The range check still runs.
17142
+ * How many `Model` components currently hold a copy of this template.
16307
17143
  *
16308
- * @param data - Two floats per vertex.
16309
- * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16310
- * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16311
- * @throws IgnifxError with code `IGX-0702` or `IGX-0725`; see
16312
- * {@link MeshAsset.updatePositions}.
17144
+ * @returns The live instance count.
16313
17145
  */
16314
- updateUvs(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
17146
+ get instanceCount(): number;
16315
17147
  /**
16316
- * Re-uploads vertex colours.
16317
- *
16318
- * @remarks
16319
- * Four floats per vertex, linear RGBA. A no-op on the GPU when the mesh was created without
16320
- * colours, exactly as {@link MeshAsset.updateUvs} is.
17148
+ * Clones the template under an entity's node.
16321
17149
  *
16322
- * @param data - Four floats per vertex.
16323
- * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16324
- * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16325
- * @throws IgnifxError with code `IGX-0702` or `IGX-0725`; see
16326
- * {@link MeshAsset.updatePositions}.
17150
+ * @param parent - The entity's transform node, or `null` for world space.
17151
+ * @returns The cloned root and its named nodes, or `null` when there is nothing to clone — a
17152
+ * headless app, or a file that declared only lights.
16327
17153
  */
16328
- updateColors(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
17154
+ instantiate(parent: LiteSceneNode | null): ModelInstantiation | null;
17155
+ /** Records that one more `Model` holds a copy. */
17156
+ retainInstance(): void;
17157
+ /** Records that one fewer `Model` holds a copy. Releasing below zero is a no-op. */
17158
+ releaseInstance(): void;
16329
17159
  /**
16330
- * Releases the template's GPU buffers.
17160
+ * Releases the template's GPU resources.
16331
17161
  *
16332
17162
  * @remarks
16333
- * Lite exports no mesh disposer: a mesh's buffers are freed when it leaves its last scene, so the
16334
- * adapter adds the template to a scene and takes it straight out again
16335
- * (`src/lite/gpu/mesh.ts`). Clones still in a scene keep the shared buffers alive; what the
16336
- * template loses is the ability to be cloned again. Calling it twice is a no-op, and it is a
16337
- * no-op under a headless app, which has no buffers.
17163
+ * The container was never added to a scene, so the round trip `removeFromScene` needs is the same
17164
+ * one `MeshAsset.dispose` performs: this hands it to the scene and takes it straight back out,
17165
+ * which drops its share of every buffer. Clones still in a scene keep theirs. Calling it twice is
17166
+ * a no-op, and it is a no-op under a headless app.
16338
17167
  */
16339
17168
  dispose(): void;
16340
17169
  /** Releases the template when the asset leaves a `using` block. */
16341
17170
  [Symbol.dispose](): void;
16342
- /**
16343
- * Creates a box template and publishes it.
16344
- *
16345
- * @param app - The app whose engine uploads the geometry and whose asset service holds the handle.
16346
- * @param options - A uniform `size`, or per-axis dimensions.
16347
- * @returns The handle, with one holder — the caller.
16348
- *
16349
- * @example
16350
- * ```ts
16351
- * const box = MeshAsset.box(app, { width: 2, height: 1, depth: 3 });
16352
- * ```
16353
- */
16354
- static box(app: App, options?: BoxMeshOptions): AssetHandle<MeshAsset>;
16355
- /**
16356
- * Creates a sphere template and publishes it.
16357
- *
16358
- * @param app - The app that owns the engine and the asset service.
16359
- * @param options - Diameter and ring count.
16360
- * @returns The handle, with one holder.
16361
- */
16362
- static sphere(app: App, options?: SphereMeshOptions): AssetHandle<MeshAsset>;
16363
- /**
16364
- * Creates a quad template in the XY plane and publishes it.
16365
- *
16366
- * @param app - The app that owns the engine and the asset service.
16367
- * @param options - A uniform `size`, or width and height.
16368
- * @returns The handle, with one holder.
16369
- */
16370
- static plane(app: App, options?: PlaneMeshOptions): AssetHandle<MeshAsset>;
16371
- /**
16372
- * Creates a subdivided grid in the XZ plane and publishes it.
16373
- *
16374
- * @param app - The app that owns the engine and the asset service.
16375
- * @param options - Width, depth, subdivisions, and UV scale.
16376
- * @returns The handle, with one holder.
16377
- */
16378
- static ground(app: App, options?: GroundMeshOptions): AssetHandle<MeshAsset>;
16379
- /**
16380
- * Creates a cylinder template standing along Y and publishes it.
16381
- *
16382
- * @param app - The app that owns the engine and the asset service.
16383
- * @param options - Height, diameters, and tessellation.
16384
- * @returns The handle, with one holder.
16385
- */
16386
- static cylinder(app: App, options?: CylinderMeshOptions): AssetHandle<MeshAsset>;
16387
- /**
16388
- * Creates a capsule template standing along Y and publishes it.
16389
- *
16390
- * @param app - The app that owns the engine and the asset service.
16391
- * @param options - Total height, radius, and tessellation.
16392
- * @returns The handle, with one holder.
16393
- */
16394
- static capsule(app: App, options?: CapsuleMeshOptions): AssetHandle<MeshAsset>;
16395
- /**
16396
- * Creates a torus template in the XZ plane and publishes it.
16397
- *
16398
- * @param app - The app that owns the engine and the asset service.
16399
- * @param options - Diameter, thickness, and tessellation.
16400
- * @returns The handle, with one holder.
16401
- */
16402
- static torus(app: App, options?: TorusMeshOptions): AssetHandle<MeshAsset>;
16403
- /**
16404
- * Creates a template from raw vertex data and publishes it.
16405
- *
16406
- * @param app - The app that owns the engine and the asset service.
16407
- * @param name - A human-readable name.
16408
- * @param data - Positions, normals, indices, and any of the four optional attributes. Lite keeps
16409
- * references to the arrays; a caller that means to edit them afterwards does so through the
16410
- * `update*` methods, which keep Lite's own copy and its bounds in step.
16411
- * @returns The handle, with one holder.
16412
- *
16413
- * @example
16414
- * ```ts
16415
- * const triangle = MeshAsset.fromData(app, "triangle", {
16416
- * positions: Float32Array.from([0, 0, 0, 1, 0, 0, 0, 1, 0]),
16417
- * normals: Float32Array.from([0, 0, -1, 0, 0, -1, 0, 0, -1]),
16418
- * indices: Uint32Array.from([0, 1, 2]),
16419
- * });
16420
- * ```
16421
- */
16422
- static fromData(app: App, name: string, data: MeshGeometryData): AssetHandle<MeshAsset>;
16423
17171
  }
16424
17172
  //#endregion
17173
+ //#region src/render/loaders/model-loader.d.ts
17174
+ /**
17175
+ * The `model` asset loader (`docs/architecture/05-assets-and-loading.md` §5).
17176
+ *
17177
+ * ## Bytes, not a URL
17178
+ *
17179
+ * `loadGltf` accepts a URL, an `ArrayBuffer`, or a `Blob`. ignifx hands it an `ArrayBuffer` fetched
17180
+ * through `ctx.fetchBytes`, because that is where progress reporting, `AbortSignal` support, the
17181
+ * priority queue, and the retry policy live (§5). A `.glb` is one file, so this is lossless.
17182
+ *
17183
+ * A `.gltf` with **external** buffers and images is the one case where it is not: Lite would have to
17184
+ * resolve those relative URLs itself, which it can only do when it did the fetching. This loader
17185
+ * loads the container from bytes either way and therefore supports self-contained `.gltf` files and
17186
+ * `.glb`; a `.gltf` with siblings fails inside Lite and surfaces as `IGX-0505`. `.glb` is what the
17187
+ * asset pipeline produces, and the fix — passing the URL through for that one shape — is a
17188
+ * three-line change whenever a project needs it.
17189
+ *
17190
+ * ## Decoders
17191
+ *
17192
+ * A glTF may need one of Lite's run-time decoders: `KHR_texture_basisu` images go through the KTX2
17193
+ * decoder and `EXT_meshopt_compression` buffers through the meshopt decoder. Both load from
17194
+ * `cdn.babylonjs.com` unless told otherwise, so the loader calls `configureDecoders` first, which
17195
+ * points Lite at the copies `@ignifx/vite-plugin` serves (`../decoder-urls.ts`).
17196
+ *
17197
+ * ## Headless
17198
+ *
17199
+ * `loadGltf` throws a `TypeError` under the null engine: it uploads while parsing and reaches for
17200
+ * `engine._device` (ADR-0002 Validation). So a headless load skips it entirely and produces an
17201
+ * asset with no container — the `gpu: null` shape §5 requires — rather than failing. The bytes are
17202
+ * still fetched, so a headless test still exercises the address, the manifest, and the byte
17203
+ * counters.
17204
+ */
17205
+ /**
17206
+ * Builds the loader for `.glb` and `.gltf` addresses.
17207
+ *
17208
+ * @returns The loader to register with `ctx.registerAssetLoader`.
17209
+ *
17210
+ * @example
17211
+ * ```ts
17212
+ * ctx.registerAssetLoader(createModelLoader());
17213
+ * ```
17214
+ *
17215
+ * @public
17216
+ */
17217
+ export declare function createModelLoader(): AssetLoader<ModelAsset>;
17218
+ //#endregion
17219
+ //#region src/render/loaders/texture-loader.d.ts
17220
+ /**
17221
+ * The `texture` asset loader (`docs/architecture/05-assets-and-loading.md` §5).
17222
+ *
17223
+ * ## Lite fetches the bytes, not ignifx
17224
+ *
17225
+ * Every other GPU loader here reads through `ctx.fetchBytes`, which is what gives it progress,
17226
+ * cancellation, and retries. A texture cannot: `loadTexture2D` takes a **URL** and decodes it with
17227
+ * `createImageBitmap`, which is the browser's own hardware-accelerated decode path
17228
+ * (`src/lite/gpu/texture.ts`). Handing it bytes would mean decoding a PNG in JavaScript. So the
17229
+ * loader hands Lite `ctx.url` and reports its own coarse progress instead, and a texture's
17230
+ * `AbortSignal` stops the *request* rather than the fetch. The trade is deliberate and it is the
17231
+ * one place §5's "the three `fetch*` methods are the only network paths" does not hold; the
17232
+ * alternative is worse.
17233
+ *
17234
+ * ## The container picks the decoder
17235
+ *
17236
+ * `.png`, `.jpg`, `.jpeg` and `.webp` go to `loadTexture2D` and the browser's image decoder.
17237
+ * `.ktx2` goes to Lite's KTX2 loader and `.basis` to its Basis loader, which transcode to the
17238
+ * device's best compressed format (`src/lite/gpu/decoders.ts` lists the targets); handing either
17239
+ * to `createImageBitmap` fails with "The source image could not be decoded". The asset type stays
17240
+ * `texture` for all six, so the choice is made here, from the address's extension — the one name a
17241
+ * manifest entry, a hashed build URL and a hand-written `{ type: "texture" }` load all keep. Before
17242
+ * a KTX2 or Basis load, {@link configureDecoders} points Lite at the decoders the manifest lists,
17243
+ * which is how a built game avoids `cdn.babylonjs.com`.
17244
+ *
17245
+ * ## Options come from the sidecar
17246
+ *
17247
+ * `.meta.json` sidecars carry per-asset import options (§7), the build copies them into the
17248
+ * manifest entry, and `ctx.meta` is how a loader reads its own block. sRGB is the one that matters:
17249
+ * a base-colour or emissive texture wants it, and a normal, ORM, or data map must not have it.
17250
+ */
17251
+ /**
17252
+ * Builds the loader for `.png`, `.jpg`, `.jpeg`, `.webp`, `.ktx2`, and `.basis` addresses.
17253
+ *
17254
+ * @returns The loader to register with `ctx.registerAssetLoader`.
17255
+ *
17256
+ * @example
17257
+ * ```ts
17258
+ * ctx.registerAssetLoader(createTextureLoader());
17259
+ * ```
17260
+ *
17261
+ * @public
17262
+ */
17263
+ export declare function createTextureLoader(): AssetLoader<TextureAsset>;
17264
+ //#endregion
17265
+ //#region src/render/mesh-file.d.ts
17266
+ /**
17267
+ * The `.mesh.json` file format (ADR-0029): one primitive and the options its `MeshAsset` factory
17268
+ * takes, so a scene file can name a primitive by address.
17269
+ *
17270
+ * ```json
17271
+ * { "format": "ignifx.mesh", "formatVersion": 1, "primitive": "box", "options": { "size": 1 } }
17272
+ * ```
17273
+ *
17274
+ * One table, {@link MESH_PRIMITIVE_OPTIONS}, drives the runtime check and the JSON Schema, so the
17275
+ * two cannot drift apart.
17276
+ */
17277
+ /**
17278
+ * The `format` header a `.mesh.json` carries.
17279
+ *
17280
+ * @public
17281
+ */
17282
+ export declare const MESH_FILE_FORMAT = "ignifx.mesh";
17283
+ /**
17284
+ * The only `.mesh.json` `formatVersion` this build reads.
17285
+ *
17286
+ * @public
17287
+ */
17288
+ export declare const MESH_FORMAT_VERSION = 1;
17289
+ /**
17290
+ * The address suffix that selects the mesh loader.
17291
+ *
17292
+ * @public
17293
+ */
17294
+ export declare const MESH_FILE_EXTENSION = ".mesh.json";
17295
+ /**
17296
+ * What a primitive option holds: a length in metres (finite, zero or more), a segment count
17297
+ * (a whole number, one or more), or a pair of finite numbers.
17298
+ *
17299
+ * @public
17300
+ */
17301
+ type MeshOptionKind = "length" | "count" | "pair";
17302
+ /**
17303
+ * For each primitive, every option its factory's options type declares, and what it holds.
17304
+ *
17305
+ * @public
17306
+ */
17307
+ type MeshPrimitiveOptionKinds = { readonly [P in MeshPrimitive]: { readonly [K in keyof Extract<MeshPrimitiveDefinition, {
17308
+ readonly primitive: P;
17309
+ }>["options"]]-?: MeshOptionKind; }; };
17310
+ /**
17311
+ * Every option each primitive takes, and what it holds. The keys are exactly the fields of the
17312
+ * factory's options type (`BoxMeshOptions`, …); the compiler checks that.
17313
+ *
17314
+ * @public
17315
+ */
17316
+ export declare const MESH_PRIMITIVE_OPTIONS: MeshPrimitiveOptionKinds;
17317
+ /**
17318
+ * The JSON Schema `@ignifx/vite-plugin` validates `.mesh.json` files against, built from
17319
+ * {@link MESH_PRIMITIVE_OPTIONS}.
17320
+ *
17321
+ * @returns The schema document.
17322
+ *
17323
+ * @example
17324
+ * ```ts
17325
+ * // vite.config.ts
17326
+ * ignifx({ schemas: { formats: { [MESH_FILE_FORMAT]: meshFileJsonSchema() } } });
17327
+ * ```
17328
+ *
17329
+ * @public
17330
+ */
17331
+ export declare function meshFileJsonSchema(): JsonSchemaObject;
17332
+ //#endregion
16425
17333
  //#region src/render/mesh-renderer.d.ts
16426
17334
  /**
16427
17335
  * The `MeshRenderer` component (`docs/architecture/07-rendering.md` §2.3): one clone of a
@@ -17420,11 +18328,19 @@ export declare class PostProcessStack extends Component implements ComponentHook
17420
18328
  *
17421
18329
  * The harness requires every key to be a namespaced `<package>/<Name>` type id
17422
18330
  * (`scripts/lib/schema-source.ts` rejects a key with no `/`), and it groups entries onto a page by
17423
- * their `format`. A *file* format is not a component and has no type id, so the three file formats
17424
- * below are keyed `ignifx/scene-file`, `ignifx/material-file`, and `ignifx/environment-file` while
17425
- * declaring `format: "ignifx.scene"`, `"ignifx.material"`, and `"ignifx.environment"`. The wave-1
18331
+ * their `format`. A *file* format is not a component and has no type id, so the file formats
18332
+ * below are keyed `ignifx/scene-file`, `ignifx/material-file`, `ignifx/environment-file`, and
18333
+ * `ignifx/mesh-file` while declaring `format: "ignifx.scene"`, `"ignifx.material"`,
18334
+ * `"ignifx.environment"`, and `"ignifx.mesh"`. The wave-1
17426
18335
  * hand-off asked for the key `"ignifx.scene"`; that key fails the namespacing check, and the
17427
18336
  * grouping — which is what actually decides the page — comes from `format` either way.
18337
+ *
18338
+ * ## The transform
18339
+ *
18340
+ * `ignifx/Transform` is described like a component, from `transformSchema()`, though its class
18341
+ * declares no schema: it is the scene file's per-entity `transform` block. Its entry is the only one
18342
+ * that sets `builtIn` (with `allowMultiple: false` and `package: "@ignifx/core"`), so an editor
18343
+ * shows it with the components but never offers to add or remove it.
17428
18344
  */
17429
18345
  /**
17430
18346
  * Describes every component and file format this package declares, for the documentation harness.
@@ -17458,105 +18374,14 @@ export declare function describeMaterialFileFormat(): SchemaDescription;
17458
18374
  * @public
17459
18375
  */
17460
18376
  export declare function describeEnvironmentFileFormat(): SchemaDescription;
17461
- //#endregion
17462
- //#region src/serialization/load.d.ts
17463
- /**
17464
- * One recoverable problem found while a scene was being built. Nothing here stops the load: a file
17465
- * degrades one field, one reference, or one layer rather than failing whole
17466
- * (`docs/architecture/06-serialization-and-scene-format.md` §4).
17467
- *
17468
- * @public
17469
- */
17470
- interface SceneLoadIssue {
17471
- /** The diagnostic code, for example `IGX-0602` or `IGX-0303`. */
17472
- readonly code: string;
17473
- /** The actionable sentence. */
17474
- readonly message: string;
17475
- }
17476
- /**
17477
- * Options accepted by {@link instantiateScene}.
17478
- *
17479
- * @public
17480
- */
17481
- interface InstantiateSceneOptions {
17482
- /** The entity the scene's roots attach to; `null` or omitted makes them roots of `scene`. */
17483
- readonly parent?: Entity | null;
17484
- /** The instance that owns the new entities; defaults to the parent's, else `world.activeScene`. */
17485
- readonly scene?: SceneInstance;
17486
- /**
17487
- * `true` treats the whole file as one instance: every entity gets a fresh uid and an
17488
- * `Entity.prefab` link. This is what `world.instantiate` does; `world.loadScene` leaves it off so
17489
- * that the scene's own entities keep the uids the file gave them
17490
- * (`docs/architecture/02-scene-graph.md` §10).
17491
- */
17492
- readonly asInstance?: boolean;
17493
- /** The handle the scene was loaded through, recorded on `Entity.prefab` when `asInstance`. */
17494
- readonly assetHandle?: AssetHandle<SceneAsset> | null;
17495
- /**
17496
- * The entity that stands for the instance when `asInstance` is set and the file has more or fewer
17497
- * than one root. `world.instantiate` creates it and passes it as both `parent` and `rootEntity`,
17498
- * so that the call still answers with one entity.
17499
- */
17500
- readonly rootEntity?: Entity | null;
17501
- /** `true` turns an `IGX-0604` hash mismatch from a diagnostic into a throw. */
17502
- readonly strictInstanceHashes?: boolean;
17503
- }
17504
- /**
17505
- * What {@link instantiateScene} produced.
17506
- *
17507
- * @public
17508
- */
17509
- interface SceneBuildResult {
17510
- /** The entities that ended up parentless within the built subtree, in file order. */
17511
- readonly roots: readonly Entity[];
17512
- /** The file-local uid to runtime object table (`docs/architecture/02-scene-graph.md` §10). */
17513
- readonly remap: UidRemap;
17514
- /** Every recoverable problem, in discovery order. */
17515
- readonly issues: readonly SceneLoadIssue[];
17516
- }
17517
- /**
17518
- * Builds the entities of a scene asset into a world — steps 3 to 6 of the loading algorithm
17519
- * (`docs/architecture/06-serialization-and-scene-format.md` §4). It is synchronous and does no I/O:
17520
- * every asset the file references is already loaded, which is what a `SceneAsset` guarantees.
17521
- *
17522
- * @remarks
17523
- * The mechanism that keeps `awake` honest is worth stating, because §4 step 6 and
17524
- * `01-lifecycle-and-time.md` §4 state only the outcome. Entities are created with `active: false`,
17525
- * so the enable transition computes "not effectively enabled" and queues nothing. Components are
17526
- * attached with their schema defaults, then every component's props are decoded — that is where
17527
- * `entityRef` and `componentRef` resolve, through a table that by then holds the whole scene. Only
17528
- * then does a last pass write each entity's file `active` value in tree order, which is what queues
17529
- * `awake` and `onEnable`, parents before children. Nothing observes the half-built scene, because
17530
- * all of this runs in one synchronous block.
17531
- *
17532
- * @param world - The world to build into.
17533
- * @param asset - The scene to build.
17534
- * @param options - Where to attach the result, and how to treat instance hashes.
17535
- * @returns The roots, the uid table, and every recoverable problem.
17536
- * @throws IgnifxError with code `IGX-0302` on an instance cycle, `IGX-0307` when the file names an
17537
- * unregistered component type, and `IGX-0604` when `strictInstanceHashes` is set and a recorded
17538
- * instance hash does not match.
17539
- *
17540
- * @example
17541
- * ```ts
17542
- * const built = instantiateScene(world, sceneAsset, { scene: world.activeScene });
17543
- * const player = built.remap.entity("01J9Z6M7E5S3A0V2Q4R8T1Y6WX");
17544
- * ```
17545
- *
17546
- * @public
17547
- */
17548
- export declare function instantiateScene(world: World, asset: SceneAsset, options?: InstantiateSceneOptions): SceneBuildResult;
17549
18377
  /**
17550
- * Checks that every scene a file instances — at any depth — is among the loaded dependencies, which
17551
- * is what makes `world.instantiate` safe to be synchronous
17552
- * (`docs/architecture/02-scene-graph.md` §2).
18378
+ * Describes the `ignifx.mesh` file format (ADR-0029).
17553
18379
  *
17554
- * @param asset - The scene to check.
17555
- * @throws IgnifxError with code `IGX-0301` naming the first instanced scene that is not loaded.
18380
+ * @returns The description of the top-level file fields.
17556
18381
  *
17557
18382
  * @public
17558
18383
  */
17559
- export declare function assertSceneDependenciesLoaded(asset: SceneAsset): void;
18384
+ export declare function describeMeshFileFormat(): SchemaDescription;
17560
18385
  //#endregion
17561
18386
  //#region src/serialization/overrides.d.ts
17562
18387
  /**
@@ -17670,6 +18495,43 @@ interface SceneLoaderOptions {
17670
18495
  * @public
17671
18496
  */
17672
18497
  export declare function createSceneLoader(options?: SceneLoaderOptions): AssetLoader<SceneAsset>;
18498
+ /**
18499
+ * Options accepted by {@link loadSceneDependencies}.
18500
+ *
18501
+ * @public
18502
+ */
18503
+ interface LoadSceneDependenciesOptions {
18504
+ /** Aborts every request; the handles already loaded are released before the promise rejects. */
18505
+ readonly signal?: AbortSignal;
18506
+ }
18507
+ /**
18508
+ * Loads every asset a scene file references — in `settings`, in every component's `props`, and in
18509
+ * every `instance.scene`, recursively through the scenes those pull in — the walk the scene loader
18510
+ * runs before it builds anything (`docs/architecture/06-serialization-and-scene-format.md` §4
18511
+ * step 2).
18512
+ *
18513
+ * @remarks
18514
+ * It is the half of the scene loader a file that is already in memory needs: pass the result to
18515
+ * `createSceneAsset` and the asset can be built synchronously with `instantiateScene`. Each handle
18516
+ * is returned with one holder, which the caller owns: release them all when the scene they serve
18517
+ * is gone. `world.loadSceneFile` does that for a whole scene.
18518
+ *
18519
+ * @param assets - The asset service to load through, normally `app.assets`.
18520
+ * @param file - The scene file.
18521
+ * @param options - Cancellation.
18522
+ * @returns The loaded handles, deduplicated by address, in the loader's order.
18523
+ * @throws Whatever the asset service rejects a load with (an `AssetLoadError`); every handle
18524
+ * loaded by then is released first.
18525
+ *
18526
+ * @example
18527
+ * ```ts
18528
+ * const dependencies = await loadSceneDependencies(app.assets, file);
18529
+ * const asset = await createSceneAsset("memory:scene/draft", file, dependencies);
18530
+ * ```
18531
+ *
18532
+ * @public
18533
+ */
18534
+ export declare function loadSceneDependencies(assets: Assets, file: SceneFile, options?: LoadSceneDependenciesOptions): Promise<readonly AssetHandle[]>;
17673
18535
  //#endregion
17674
18536
  //#region src/serialization/serialize.d.ts
17675
18537
  /**
@@ -17813,6 +18675,39 @@ interface SceneFileIssue {
17813
18675
  */
17814
18676
  export declare function validateSceneFile(value: unknown): readonly SceneFileIssue[];
17815
18677
  //#endregion
18678
+ //#region src/schema/describe-registry.d.ts
18679
+ /**
18680
+ * Describes every component an app has registered, the engine's, its extensions' and the game's,
18681
+ * the way {@link describeSchema} describes one, plus what only the registry knows: whether an
18682
+ * entity may hold more than one (`allowMultiple`) and which package registered it (`package`).
18683
+ * This is what an external inspector, such as the ignifx editor, is generated from.
18684
+ *
18685
+ * @remarks
18686
+ * `package` is the `name` of the extension whose `register(ctx)` registered the class, which is the
18687
+ * npm package name for a published extension (`@ignifx/core`, `@ignifx/3d`). A class the game
18688
+ * registered itself with `app.registerComponents` has no extension, so its `package` is its type
18689
+ * id's namespace: everything before the last `/` (`third-person` for `third-person/Beacon`).
18690
+ *
18691
+ * `ignifx/Transform` declares no schema on its class; it is described with {@link transformSchema}
18692
+ * and marked `builtIn`, because every entity carries exactly one and a scene file stores it as the
18693
+ * entity's `transform` block rather than in its `components`.
18694
+ *
18695
+ * @param registry - The registry to walk, usually `app.world.registry`.
18696
+ * @param curated - Titles, formats and summaries by type id, for example a package's own
18697
+ * `describeSchemas()`; a component without an entry is titled from its type id.
18698
+ * @returns The descriptions, keyed by type id, in registration order.
18699
+ *
18700
+ * @example
18701
+ * ```ts
18702
+ * const schemas = describeRegisteredSchemas(app.world.registry, describeSchemas());
18703
+ * schemas["ignifx/Camera"]?.package; // "@ignifx/core"
18704
+ * schemas["ignifx/Camera"]?.allowMultiple; // false
18705
+ * ```
18706
+ *
18707
+ * @public
18708
+ */
18709
+ export declare function describeRegisteredSchemas(registry: ComponentRegistry, curated?: Readonly<Record<string, SchemaDescriptionMeta>>): Readonly<Record<string, SchemaDescription>>;
18710
+ //#endregion
17816
18711
  //#region src/schema/field-kinds.d.ts
17817
18712
  /**
17818
18713
  * Declares a single-precision floating point field.
@@ -18352,6 +19247,83 @@ export declare function waitUntil(predicate: () => boolean): WaitInstruction;
18352
19247
  */
18353
19248
  export declare function waitWhile(predicate: () => boolean): WaitInstruction;
18354
19249
  //#endregion
19250
+ //#region src/settings/describe-settings.d.ts
19251
+ /**
19252
+ * The `format` every settings section description carries, so a consumer that merges settings and
19253
+ * component descriptions can tell them apart.
19254
+ *
19255
+ * @public
19256
+ */
19257
+ export declare const SETTINGS_DESCRIPTION_FORMAT = "settings";
19258
+ /**
19259
+ * Describes every project settings section an app has registered (core's own `layers`,
19260
+ * `sortingLayers`, `time`, `assets` and `rendering`, and every section an extension declared with
19261
+ * `ctx.registerSettings`) in the same shape {@link describeRegisteredSchemas} describes components.
19262
+ * This is what an external settings panel, such as the ignifx editor's, is generated from.
19263
+ *
19264
+ * @remarks
19265
+ * Each entry is keyed and titled by its section name, has `format: "settings"`
19266
+ * ({@link SETTINGS_DESCRIPTION_FORMAT}), and names the extension that registered it as `package`
19267
+ * (`@ignifx/core`, `@ignifx/physics`). A field's `default` is the value the owner registered for it,
19268
+ * which is what the project gets when it omits the field; a field the owner's defaults leave out has
19269
+ * no `default`, because the resolved section has no value for it either.
19270
+ *
19271
+ * Defaults are in the **settings form**, the form `createApp` reads, which differs from the scene
19272
+ * file's for vectors and colours: a `vec3` default is `{ "x": 0, "y": -9.81, "z": 0 }` and a `color`
19273
+ * default is `{ "r": 0, "g": 0, "b": 0, "a": 1 }`, not an array. A tool writes values back in this
19274
+ * form.
19275
+ *
19276
+ * The registration seam is `ctx.registerSettings(section, schema, defaults)`: an extension that
19277
+ * declares a section there is described here with no further work. A section is written in project
19278
+ * settings (`ignifx.settings.json` or `ignifx.config.ts`) as an object of these fields; a section
19279
+ * with exactly one field of a non-object kind (a number, string, enum or array, not a vector or
19280
+ * colour) may also be written as that field's value.
19281
+ *
19282
+ * @param app - The app whose sections to describe; its extensions have all registered by the time
19283
+ * `createApp` resolves.
19284
+ * @returns The descriptions, keyed by section name, in registration order.
19285
+ * @throws IgnifxError with code `IGX-0702` when `app` was not created by this copy of
19286
+ * `@ignifx/core`.
19287
+ *
19288
+ * @example
19289
+ * ```ts
19290
+ * const sections = describeSettings(app);
19291
+ * sections["time"]?.package; // "@ignifx/core"
19292
+ * sections["time"]?.fields["fixedDeltaTime"]?.default; // 0.016666666666666666
19293
+ * ```
19294
+ *
19295
+ * @public
19296
+ */
19297
+ export declare function describeSettings(app: App): Readonly<Record<string, SchemaDescription>>;
19298
+ /**
19299
+ * Generates the JSON Schema (draft 2020-12) of a project's settings object, the content of
19300
+ * `ignifx.settings.json`, from every section the app registered. Pass it to the Vite plugin as
19301
+ * `ignifx({ schemas: { settings } })` to validate the project settings at build time, or associate
19302
+ * it with `ignifx.settings.json` in a text editor.
19303
+ *
19304
+ * @remarks
19305
+ * The schema describes the settings form `createApp` reads (vectors as `{ x, y, z }`, colours as
19306
+ * `{ r, g, b, a }` with every channel required), so a document it accepts also passes `createApp`'s
19307
+ * own validation (`IGX-0408`). Every section is optional and a section omitted takes its defaults.
19308
+ * An unknown key inside a section is a violation. The top level stays open: a section this app did
19309
+ * not register, perhaps one of an extension it lacks, is left to `createApp`, which reports it
19310
+ * (`IGX-0407`), and to the Vite plugin, which warns about it.
19311
+ *
19312
+ * @param app - The app whose sections to describe.
19313
+ * @returns The object schema, one property per section.
19314
+ * @throws IgnifxError with code `IGX-0702` when `app` was not created by this copy of
19315
+ * `@ignifx/core`.
19316
+ *
19317
+ * @example
19318
+ * ```ts
19319
+ * const schema = settingsJsonSchema(app);
19320
+ * Object.keys(schema["properties"] ?? {}); // ["layers", "sortingLayers", "time", "assets", "rendering"]
19321
+ * ```
19322
+ *
19323
+ * @public
19324
+ */
19325
+ export declare function settingsJsonSchema(app: App): JsonSchemaObject;
19326
+ //#endregion
18355
19327
  //#region src/storage/memory-backend.d.ts
18356
19328
  /**
18357
19329
  * The in-memory storage backend: the default for a headless app, and the one every unit test in the
@@ -18523,6 +19495,36 @@ export declare class IndexedDbStorageBackend implements StorageBackend {
18523
19495
  dispose(): void;
18524
19496
  }
18525
19497
  //#endregion
19498
+ //#region src/transform/transform-schema.d.ts
19499
+ /**
19500
+ * The entity transform as a schema: the fields of a scene file's `transform` block, so an
19501
+ * inspector and its ops can treat the transform like any component
19502
+ * (`docs/architecture/06-serialization-and-scene-format.md` §2).
19503
+ *
19504
+ * @remarks
19505
+ * The schema **describes** the transform; {@link (Transform:class)} does not declare it. The class keeps
19506
+ * no schema because its `position` and `rotation` are world-space getters, while the file, this
19507
+ * schema, and the editor's `setTransform` op all carry **local** values. Every entity has exactly
19508
+ * one transform, which is never in a file's `components` list, so `describeSchemas()` and
19509
+ * `describeRegisteredSchemas()` mark `ignifx/Transform` as `builtIn`: it cannot be added or
19510
+ * removed, and its values are edited as the whole block, not with a per-prop op.
19511
+ *
19512
+ * `rotation` is a `quat` field: files and ops store a unit quaternion, and an inspector shows
19513
+ * intrinsic XYZ Euler angles in degrees (ADR-0011), so its `step` is in degrees.
19514
+ *
19515
+ * @returns A new schema: `position` (`vec3`, origin, step 0.01), `rotation` (`quat`, identity,
19516
+ * step 0.5 degrees), `scale` (`vec3`, one, step 0.01).
19517
+ *
19518
+ * @example
19519
+ * ```ts
19520
+ * const fields = describeSchema("ignifx/Transform", transformSchema()).fields;
19521
+ * fields["rotation"]?.default; // [0, 0, 0, 1]
19522
+ * ```
19523
+ *
19524
+ * @public
19525
+ */
19526
+ export declare function transformSchema(): Schema;
19527
+ //#endregion
18526
19528
  //#region src/tween/tween-system.d.ts
18527
19529
  /**
18528
19530
  * The `PostUpdate` system that advances `app.tweens` (`docs/architecture/01-lifecycle-and-time.md`
@@ -18543,5 +19545,5 @@ export declare class IndexedDbStorageBackend implements StorageBackend {
18543
19545
  */
18544
19546
  export declare const TWEEN_SYSTEM_ORDER = -100;
18545
19547
  //#endregion
18546
- export type { App, AppEvents, AppLiteHandles, AppSettings, ArrayFieldSpec, AssetFieldSpec, AssetHandle, AssetLoadErrorOptions, AssetLoader, AssetManifest, AssetManifestEntry, AssetProgress, AssetRef, AssetRefValue, AssetState, AssetTypeDefinition, AssetTypeToken, Assets, AssetsCreateOptions, AssetsSettings, BatchHandle, BloomEffectSettings, BoolFieldSpec, BoxMeshOptions, CameraProjection, CanvasAlphaMode, CapsuleMeshOptions, Clock, ColorFieldSpec, ColorLike, ComponentClassInfo, ComponentDefinition, ComponentHandle, ComponentHooks, ComponentInit, ComponentInitValue, ComponentRefFieldSpec, ComponentReplacement, ComponentStatics, ComponentType, ComponentTypeToken, ConcreteComponentType, ConnectOptions, ConsoleLike, ConsoleSinkOptions, Coroutine, CoroutineHandle, CoroutineHost, CoroutineYield, CreateAppOptions, CreateEntityOptions, CurveFieldSpec, CurveKey, CurveValue, CustomEffectInit, CustomEffectSettings, CustomFieldCodec, CustomFieldSpec, CylinderMeshOptions, DecodeResult, DeferredQueue, DeviceLostInfo, DiagnosticsGroup, DiagnosticsOptions, Disconnect, EasingFunction, EasingName, EntityHandle, EntityOverrideField, EntityPrefabLink, EntityRefFieldSpec, EnumFieldSpec, EnvironmentAssetLiteHandles, EnvironmentDefinition, EnvironmentFogMode, EnvironmentFogSettings, EnvironmentSkyboxSettings, ErrorCode, ErrorCodeDescription, ErrorCodeRegistry, ErrorContext, ErrorFormatMode, ErrorReport, Extension, ExtensionContext, FetchLike, FieldDefinition, FieldOptions, FieldSpec, FieldsOf, FileStorageOptions, FontAssetLiteHandles, FrameSample, FrameState, GpuAdapterInfo, GroundMeshOptions, HotReloadHost, HotReloadKind, HotReloadModule, HotReloadOptions, HotReloadPolicy, HotReloadReport, HotReloadStatics, IgnifxErrorOptions, IgnifxUniformName, ImageProcessingEffectSettings, ImageProcessingSettings, InstanceRange, InstancedMeshLod, InstancedMeshRendererLiteHandles, InstantiateOptions, InstantiateSceneOptions, JsonArray, JsonObject, JsonSchemaObject, JsonValue, LayerMaskFieldSpec, LayersSettings, LightShadowSettings, LightType, LiteAnimationGroup, LiteAssetContainer, LiteCamera, LiteEngine, LiteEnvironmentTextures, LiteFont, AdapterLight as LiteLight, LiteMaterial, LiteMaterialPluginPoint, LiteMesh, LitePbrMaterial, LiteScene, LiteSceneNode, LiteShaderMaterial, LiteShadowGenerator, LiteSkeleton, LiteStandardMaterial, LiteStorageBuffer, LiteSystemUniformName, LiteTexture2D, LoadOptions, LoadProgress, LoadSceneOptions, LoaderContext, LogRecord, LogSink, LogThreshold, Logger, LoggerOptions, ManualClock, MapFieldSpec, Mat4Elements, Mat4Like, MaterialAlphaMode, MaterialAssetLiteHandles, MaterialDefinition, MaterialKind, MaterialPluginDefinition, MaterialPluginDefinitionInit, MemorySink, MeshAssetLiteHandles, MeshGeometryData, ModelAssetLiteHandles, ModelInstantiation, MutableQuat, MutableVec2, MutableVec3, MutableVec4, NumberFieldSpec, OptionalFieldSpec, OverridePath, PartialFieldsOf, PbrMaterialDefinition, PhaseIndex, PixelTextureOptions, PlaneMeshOptions, PlatformInfo, PlatformKind, PlatformOs, ProfileScope, QuatLike, RandomSource, Ray, RayVector, RecordFieldSpec, ReferenceDecoder, ReferenceEncoder, RegisterAssetOptions, RegisterComponentOptions, RegisterSystemOptions, RenderCapture, RenderPick, RenderPickOptions, RenderSurface, RenderTaskTiming, RenderTaskTimings, Renderer, RenderingFeature, RenderingFeatureSettings, RenderingSettings, SceneAsset, SceneBuildResult, SceneFile, SceneFileAssetRef, SceneFileComponent, SceneFileEntity, SceneFileInstance, SceneFileIssue, SceneFileOverride, SceneFileTransform, SceneLoadIssue, SceneLoaderOptions, Schema, SchemaDescription, SchemaDescriptionMeta, SchemaFieldDescription, SchemaIssue, ScriptCallbacks, ScriptClassInfo, ScriptDefinition, ScriptStatics, SerializeIssue, SerializeSceneOptions, ServiceClassKey, ServiceKey, ServiceNameKey, ServiceRegistry, SetParentOptions, SettingsInput, ShaderAttributeName, ShaderBlendMode, ShaderCullMode, ShaderDeclaration, ShaderDefineDeclaration, ShaderInstancingMode, ShaderKind, ShaderMaterialDefinition, ShaderMaterialDefinitionInput, ShaderPipelineState, ShaderStorageDeclaration, ShaderTextureDeclaration, ShaderTextureFallback, ShaderUniformDeclaration, ShaderUniformType, ShadowTechniqueName, SignalHandler, SignalLike, SignalOptions, SignalOwner, SmaaEffectSettings, SortingLayersSettings, SphereMeshOptions, StandardMaterialDefinition, Storage, StorageBackend, StorageBufferAssetLiteHandles, StoredValue, StoredValueKind, StringFieldSpec, SurfaceHookName, SurfaceHostCapabilities, SurfaceHostFamily, SurfaceShaderBinding, SurfaceShaderInit, SurfaceShaderReference, System, SystemContext, TextureAssetLiteHandles, TextureImportOptions, Time, TimeSettings, ToneMappingCurve, TorusMeshOptions, TweenOptions, TweenProps, TweenTargetValue, TweenValueKind, TweenableValue, Tweens, UlidFactoryOptions, Vec2Like, Vec3Like, Vec4Like, VectorFieldSpec, WaitInstruction, WebGpuInfo, WorldLiteHandles };
19548
+ export type { AddComponentFromRecordOptions, App, AppEvents, AppLiteHandles, AppSettings, ArrayFieldSpec, AssetFieldSpec, AssetHandle, AssetLoadErrorOptions, AssetLoader, AssetManifest, AssetManifestEntry, AssetProgress, AssetRef, AssetRefValue, AssetState, AssetTypeDefinition, AssetTypeToken, Assets, AssetsCreateOptions, AssetsSettings, BatchHandle, BloomEffectSettings, BoolFieldSpec, BoxMeshOptions, CameraProjection, CanvasAlphaMode, CapsuleMeshOptions, Clock, ColorFieldSpec, ColorLike, ComponentBuildResult, ComponentClassInfo, ComponentDefinition, ComponentHandle, ComponentHooks, ComponentInit, ComponentInitValue, ComponentRefFieldSpec, ComponentReplacement, ComponentStatics, ComponentType, ComponentTypeToken, ConcreteComponentType, ConnectOptions, ConsoleLike, ConsoleSinkOptions, Coroutine, CoroutineHandle, CoroutineHost, CoroutineYield, CreateAppOptions, CreateEntityOptions, CreateSceneOptions, CurveFieldSpec, CurveKey, CurveValue, CustomEffectInit, CustomEffectSettings, CustomFieldCodec, CustomFieldSpec, CylinderMeshOptions, DecodeResult, DeferredQueue, DeviceLostInfo, DiagnosticsGroup, DiagnosticsOptions, Disconnect, EasingFunction, EasingName, EntityHandle, EntityOverrideField, EntityPrefabLink, EntityRefFieldSpec, EnumFieldSpec, EnvironmentAssetLiteHandles, EnvironmentDefinition, EnvironmentFogMode, EnvironmentFogSettings, EnvironmentSkyboxSettings, ErrorCode, ErrorCodeDescription, ErrorCodeRegistry, ErrorContext, ErrorFormatMode, ErrorReport, Extension, ExtensionContext, FetchLike, FieldDefinition, FieldOptions, FieldSpec, FieldsOf, FileStorageOptions, FontAssetLiteHandles, FrameSample, FrameState, GpuAdapterInfo, GroundMeshOptions, HotReloadHost, HotReloadKind, HotReloadModule, HotReloadOptions, HotReloadPolicy, HotReloadReport, HotReloadStatics, IgnifxErrorOptions, IgnifxUniformName, ImageProcessingEffectSettings, ImageProcessingSettings, InstanceRange, InstancedMeshLod, InstancedMeshRendererLiteHandles, InstantiateOptions, InstantiateSceneOptions, JsonArray, JsonObject, JsonSchemaObject, JsonValue, LayerMaskFieldSpec, LayersSettings, LightShadowSettings, LightType, LiteAnimationGroup, LiteAssetContainer, LiteCamera, LiteEngine, LiteEnvironmentTextures, LiteFont, AdapterLight as LiteLight, LiteMaterial, LiteMaterialPluginPoint, LiteMesh, LitePbrMaterial, LiteScene, LiteSceneNode, LiteShaderMaterial, LiteShadowGenerator, LiteSkeleton, LiteStandardMaterial, LiteStorageBuffer, LiteSystemUniformName, LiteTexture2D, LoadOptions, LoadProgress, LoadSceneDependenciesOptions, LoadSceneFileOptions, LoadSceneOptions, LoaderContext, LogRecord, LogSink, LogThreshold, Logger, LoggerOptions, ManualClock, MapFieldSpec, Mat4Elements, Mat4Like, MaterialAlphaMode, MaterialAssetLiteHandles, MaterialDefinition, MaterialKind, MaterialPluginDefinition, MaterialPluginDefinitionInit, MemorySink, MeshAssetLiteHandles, MeshGeometryData, MeshOptionKind, MeshPrimitive, MeshPrimitiveDefinition, MeshPrimitiveOptionKinds, ModelAssetLiteHandles, ModelInstantiation, MutableQuat, MutableVec2, MutableVec3, MutableVec4, NumberFieldSpec, OptionalFieldSpec, OverridePath, PartialFieldsOf, PbrMaterialDefinition, PhaseIndex, PixelTextureOptions, PlaneMeshOptions, PlatformInfo, PlatformKind, PlatformOs, ProfileScope, QuatLike, RandomSource, Ray, RayVector, RecordFieldSpec, ReferenceDecoder, ReferenceEncoder, RegisterAssetOptions, RegisterComponentOptions, RegisterSystemOptions, RenderCapture, RenderOverlay, RenderOverlayLiteHandles, RenderPick, RenderPickIgnore, RenderPickOptions, RenderSurface, RenderTaskTiming, RenderTaskTimings, Renderer, RenderingFeature, RenderingFeatureSettings, RenderingSettings, SceneAsset, SceneBuildResult, SceneFile, SceneFileAssetRef, SceneFileComponent, SceneFileEntity, SceneFileInstance, SceneFileIssue, SceneFileOverride, SceneFileTransform, SceneLoadIssue, SceneLoaderOptions, Schema, SchemaDescription, SchemaDescriptionMeta, SchemaFieldDescription, SchemaIssue, ScriptCallbacks, ScriptClassInfo, ScriptDefinition, ScriptStatics, SerializeIssue, SerializeSceneOptions, ServiceClassKey, ServiceKey, ServiceNameKey, ServiceRegistry, SetParentOptions, SettingsInput, ShaderAttributeName, ShaderBlendMode, ShaderCullMode, ShaderDeclaration, ShaderDefineDeclaration, ShaderInstancingMode, ShaderKind, ShaderMaterialDefinition, ShaderMaterialDefinitionInput, ShaderPipelineState, ShaderStorageDeclaration, ShaderTextureDeclaration, ShaderTextureFallback, ShaderUniformDeclaration, ShaderUniformType, ShadowTechniqueName, SignalHandler, SignalLike, SignalOptions, SignalOwner, SmaaEffectSettings, SortingLayersSettings, SphereMeshOptions, StandardMaterialDefinition, Storage, StorageBackend, StorageBufferAssetLiteHandles, StoredValue, StoredValueKind, StringFieldSpec, SurfaceHookName, SurfaceHostCapabilities, SurfaceHostFamily, SurfaceShaderBinding, SurfaceShaderInit, SurfaceShaderReference, System, SystemContext, SystemEditMode, TextureAssetLiteHandles, TextureImportOptions, Time, TimeSettings, ToneMappingCurve, TorusMeshOptions, TweenOptions, TweenProps, TweenTargetValue, TweenValueKind, TweenableValue, Tweens, UlidFactoryOptions, Vec2Like, Vec3Like, Vec4Like, VectorFieldSpec, WaitInstruction, WebGpuInfo, WorldLiteHandles };
18547
19549
  //# sourceMappingURL=index.d.ts.map