@ignifx/core 0.8.0 → 0.10.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 (29) hide show
  1. package/dist/{environment-mr5wp69e.js → environment-BCjfp1jB.js} +2 -2
  2. package/dist/{environment-mr5wp69e.js.map → environment-BCjfp1jB.js.map} +1 -1
  3. package/dist/{ignifx-error-CRh89KUJ.js → ignifx-error-RpK-lWwE.js} +13 -2
  4. package/dist/ignifx-error-RpK-lWwE.js.map +1 -0
  5. package/dist/index.d.ts +1758 -807
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js +2695 -467
  8. package/dist/index.js.map +1 -1
  9. package/dist/{instanced-mesh-instance-gguMoIeZ.js → instanced-mesh-instance-DYwH0vLi.js} +2 -2
  10. package/dist/{instanced-mesh-instance-gguMoIeZ.js.map → instanced-mesh-instance-DYwH0vLi.js.map} +1 -1
  11. package/dist/{material-plugin-Cfw_h_Mg.js → material-plugin-CWtV7DkH.js} +3 -3
  12. package/dist/material-plugin-CWtV7DkH.js.map +1 -0
  13. package/dist/overlay-CjVgsfrm.js +239 -0
  14. package/dist/overlay-CjVgsfrm.js.map +1 -0
  15. package/dist/{post-effect-compiler-Rce26Eue.js → post-effect-compiler-pOvXae-i.js} +2 -2
  16. package/dist/{post-effect-compiler-Rce26Eue.js.map → post-effect-compiler-pOvXae-i.js.map} +1 -1
  17. package/dist/{shader-material-U6BKZ8D1.js → shader-material-B6wwFCKB.js} +2 -2
  18. package/dist/{shader-material-U6BKZ8D1.js.map → shader-material-B6wwFCKB.js.map} +1 -1
  19. package/dist/{shader-material-BIG3UDyu.js → shader-material-C4VjLTfV.js} +3 -3
  20. package/dist/{shader-material-BIG3UDyu.js.map → shader-material-C4VjLTfV.js.map} +1 -1
  21. package/dist/{shader-pragma-tw6AKaQD.js → shader-pragma-qO9_6sTd.js} +2 -2
  22. package/dist/{shader-pragma-tw6AKaQD.js.map → shader-pragma-qO9_6sTd.js.map} +1 -1
  23. package/dist/{surface-shader-DAWIDdaa.js → surface-shader-BaR7Kg-F.js} +4 -4
  24. package/dist/{surface-shader-DAWIDdaa.js.map → surface-shader-BaR7Kg-F.js.map} +1 -1
  25. package/dist/{vec3-B31o_KF_.js → vec3-T2PasQZv.js} +2 -2
  26. package/dist/{vec3-B31o_KF_.js.map → vec3-T2PasQZv.js.map} +1 -1
  27. package/package.json +2 -2
  28. package/dist/ignifx-error-CRh89KUJ.js.map +0 -1
  29. package/dist/material-plugin-Cfw_h_Mg.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,118 @@ 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
+ }
7862
+ //#endregion
7863
+ //#region src/lite/shadow.d.ts
7864
+ /**
7865
+ * Shadow half of the Babylon Lite adapter (`docs/architecture/07-rendering.md` §2.2): everything
7866
+ * about shadow generators that does **not** need a GPU device. Creating a generator allocates a
7867
+ * depth texture and a sampler, so the four factories live in `./gpu/shadow-generator.ts`.
7868
+ *
7869
+ * Everything here is `@internal`.
7870
+ *
7871
+ * ## How Lite renders shadows (verified against `@babylonjs/lite@1.34.0`)
7872
+ *
7873
+ * - A scene grows a shadow pass only through `registerSceneWithShadowSupport`
7874
+ * (`index.d.ts` 11275), which unshifts a task named `"shadow"` at the front of the frame graph
7875
+ * (`lib/scene/scene-core.js`, `ensureShadowTask`). `registerScene` never adds one, and there is
7876
+ * no public call that adds it later — so the decision is made once, at start, from whether any
7877
+ * shadow-casting light exists (`docs/architecture/07-rendering.md` §1).
7878
+ * - The shadow task finds its work by walking `scene.lights` and reading `light.shadowGenerator`
7879
+ * (`lib/frame-graph/shadow-task.js`). Assigning that property is what turns shadows on for a
7880
+ * light; Lite never adds to `scene.shadowGenerators` — it only reads it during device-loss
7881
+ * recovery and splices from it on removal — so the adapter does not maintain it either.
7882
+ * - The caster list is a side table keyed by generator (`setShadowTaskCasterMeshes`,
7883
+ * `index.d.ts` 12986, `lib/frame-graph/shadow-inputs.js`). Passing a new array parks the
7884
+ * generator until an async preload of the shadow pipeline finishes, so the list is replaced as
7885
+ * rarely as possible: once per frame in which the caster set actually changed.
7886
+ * - A pass redraws its map only when something it tracks moved: the sum of every caster's
7887
+ * `worldMatrixVersion` plus its thin-instance version (`casterVersionSum`,
7888
+ * `lib/shadow/shadow-base.js` 186), the light's `_lightVersion` (see `./light.ts`), and the
7889
+ * floating-origin camera (CSM: the camera and its aspect). Otherwise the previous map is reused
7890
+ * (`lib/shadow/pcf-shadow-task-hooks.js` 120, `_chunks/esm-directional-shadow-generator-*.js`
7891
+ * 173, `lib/shadow/csm-shadow-task-hooks.js` 303). A caster that changes shape in place — a
7892
+ * skinned mesh, a shader material moving vertices by a uniform — moves none of those, so
7893
+ * `./gpu/shadow-generator.ts` adds Lite's skeleton layer and a shape check of its own to every
7894
+ * generator.
7895
+ * - `computeDirectionalLightMatrix` (`lib/shadow/shadow-base.js` 76-79) fits the shadow frustum
7896
+ * from the light's `direction` rotated by its world matrix and from the world matrix's
7897
+ * translation, the same pose the lights uniform buffer is written from. `./light.ts` keeps every
7898
+ * light unparented and unrotated and writes the world pose into its own vectors, so a posed light
7899
+ * casts where it shades and nothing extra is needed here.
7900
+ */
7901
+ /**
7902
+ * The Babylon Lite shadow generator a `Light` owns, re-exported under an ignifx name
7903
+ * (`CONSTITUTION.md` §3.4, coding standards §4).
7904
+ *
7905
+ * @remarks
7906
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
7907
+ *
7908
+ * @public
7909
+ */
7910
+ type LiteShadowGenerator = ShadowGenerator;
7911
+ /**
7912
+ * The shadow techniques Lite offers, in the order `docs/architecture/07-rendering.md` §2.2 lists them.
7913
+ *
7914
+ * @public
7915
+ */
7916
+ export declare const SHADOW_TECHNIQUES: readonly ["esm", "pcf", "csm"];
7917
+ /**
7918
+ * Lite's process-wide pipeline-cache resets that one scene has been seen to register, so the
7919
+ * adapter can call them before a rebuild that needs fresh bind-group layouts.
7920
+ *
7921
+ * @remarks
7922
+ * Babylon Lite 1.31 removed the per-engine cache resets (`engine._pbrCleanup`,
7923
+ * `engine._standardCleanup`) that 1.27 parked on the engine. The only remaining handle on the PBR
7924
+ * and Standard bindings caches is the reset each material-group builder pushes onto
7925
+ * `scene._disposables` at the end of every build (`buildPbrRenderables`,
7926
+ * `lib/material/pbr/pbr-renderable.js` 306; `buildStandardMeshRenderables`,
7927
+ * `lib/material/standard/standard-renderable.js` 178). A reset is a module-level function, so a
7928
+ * group rebuild pushes the **same** function again, and Lite drops the duplicate
7929
+ * (`dedupeGroupCleanup`, `lib/scene/scene-rebuild.js`). That re-push is how the adapter tells a
7930
+ * cache reset from a scene's own disposers without relying on function names, which an app's
7931
+ * minifier rewrites.
7932
+ *
7933
+ * {@link trackMaterialCacheResets} watches every push: a function already in the list is a reset
7934
+ * and goes into `found`, and a function never seen before raises `unconfirmed`. A rebuild that
7935
+ * raised it rebuilds once more at once, and a family Lite built on its own (a runtime build of the
7936
+ * first mesh of a family, after start) is confirmed by the next rebuild the render sync system
7937
+ * schedules for it. Each function raises `unconfirmed` once, so a scene's one-off disposers cost
7938
+ * one extra rebuild in total, never a loop.
7939
+ *
7940
+ * @internal
7941
+ */
7942
+ interface MaterialCacheResets {
7943
+ /** The resets identified so far. */
7944
+ readonly found: Set<() => void>;
7945
+ /** Every function seen pushed, so each one asks for at most one confirming rebuild. */
7946
+ readonly seen: WeakSet<() => void>;
7947
+ /** `true` when a function nobody had seen was pushed since the last rebuild started. */
7948
+ unconfirmed: boolean;
7949
+ /** How many rebuilds started over because a material swap landed in them; for diagnostics. */
7950
+ retries: number;
7951
+ }
7702
7952
  //#endregion
7703
7953
  //#region src/platform/webgpu.d.ts
7704
7954
  /**
@@ -7762,6 +8012,18 @@ export declare const RENDER_DIAGNOSTICS_GROUP = "render";
7762
8012
  * @public
7763
8013
  */
7764
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
+ }
7765
8027
  /**
7766
8028
  * A rendering feature a project or an extension asks for
7767
8029
  * (`docs/architecture/07-rendering.md` §1.1).
@@ -7770,7 +8032,11 @@ export declare const RENDER_DIAGNOSTICS_COUNTERS: readonly string[];
7770
8032
  */
7771
8033
  type RenderingFeature = keyof RenderingFeatureSettings;
7772
8034
  /**
7773
- * 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.
7774
8040
  *
7775
8041
  * @public
7776
8042
  */
@@ -7779,15 +8045,36 @@ interface RenderPick {
7779
8045
  readonly entity: Entity;
7780
8046
  /** The component that created the mesh, when it was not the entity's own transform. */
7781
8047
  readonly component: Component | null;
7782
- /** 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
+ */
7783
8052
  readonly point: readonly [number, number, number] | null;
7784
- /** 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. */
7785
8054
  readonly normal: readonly [number, number, number] | null;
7786
- /** 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. */
7787
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;
7788
8068
  }
7789
8069
  /**
7790
- * 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).
7791
8078
  *
7792
8079
  * @public
7793
8080
  */
@@ -7800,6 +8087,22 @@ interface RenderPickOptions {
7800
8087
  * @returns `true` to consider the entity.
7801
8088
  */
7802
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[];
7803
8106
  }
7804
8107
  /**
7805
8108
  * A captured frame (`docs/architecture/07-rendering.md` §5).
@@ -7846,6 +8149,40 @@ interface RenderTaskTimings {
7846
8149
  /** The tasks, in frame execution order. Empty unless `status` is `"ok"`. */
7847
8150
  readonly tasks: readonly RenderTaskTiming[];
7848
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
+ }
7849
8186
  /**
7850
8187
  * The rendering service, reached as `app.renderer`
7851
8188
  * (`docs/architecture/07-rendering.md` §1, §3, §5).
@@ -7853,7 +8190,9 @@ interface RenderTaskTimings {
7853
8190
  * @example
7854
8191
  * ```ts
7855
8192
  * app.renderer.resolutionScale = 0.75;
7856
- * 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);
7857
8196
  * hit?.entity.name;
7858
8197
  * ```
7859
8198
  *
@@ -7916,14 +8255,20 @@ interface Renderer {
7916
8255
  *
7917
8256
  * @remarks
7918
8257
  * Coordinates are **backing-store pixels** — the canvas's `width`/`height`, the space
7919
- * `Camera.worldToScreen` answers in — not CSS pixels; multiply a DOM event's `offsetX`/`offsetY`
7920
- * by `devicePixelRatio` first. Picks are serialised per app: Lite's picker owns one set of staging
7921
- * buffers and chains each call onto the previous one's promise. A headless app has no picker and
7922
- * always misses.
8258
+ * `Camera.worldToScreen` answers in and `<Pointer>/position` reports — not CSS pixels. Multiply a
8259
+ * DOM event's `offsetX`/`offsetY` by `canvas.width / canvas.clientWidth` first. The renderer
8260
+ * converts to the CSS pixels Lite's picker takes, so the same call hits at every device pixel
8261
+ * ratio and resolution scale. The point is sampled exactly: whole numbers are pixel corners, so
8262
+ * add 0.5 for a pixel's centre.
8263
+ *
8264
+ * A hit on any mesh of a glTF `Model`, or of any renderable built from several Lite nodes,
8265
+ * resolves through the nearest node an entity owns. Picks are serialised per app: Lite's picker
8266
+ * owns one set of staging buffers and chains each call onto the previous one's promise. A
8267
+ * headless app has no picker and always misses.
7923
8268
  *
7924
8269
  * @param x - The backing-store pixel x, from the canvas's left edge.
7925
8270
  * @param y - The backing-store pixel y, from the canvas's top edge.
7926
- * @param options - An entity filter.
8271
+ * @param options - An entity filter, and what to look through.
7927
8272
  * @returns What was hit, or `null` for a miss.
7928
8273
  */
7929
8274
  pickAsync(x: number, y: number, options?: RenderPickOptions): Promise<RenderPick | null>;
@@ -7950,6 +8295,31 @@ interface Renderer {
7950
8295
  * which point Lite has compiled what it is going to compile.
7951
8296
  */
7952
8297
  requireFeature(feature: RenderingFeature): void;
8298
+ /**
8299
+ * Opens an overlay: a Babylon Lite scene drawn over the finished frame, for an editor's gizmos
8300
+ * and selection outlines (`docs/architecture/07-rendering.md` §2.10).
8301
+ *
8302
+ * @remarks
8303
+ * Add Lite meshes, or Lite's gizmos, to `overlay.lite.scene`. The overlay follows the render
8304
+ * scene's camera, draws over every other rendering context, and works at every MSAA setting and
8305
+ * on both render paths. Dispose it when it is no longer needed; `app.dispose()` disposes any that
8306
+ * are still open.
8307
+ *
8308
+ * @returns The overlay, drawing from the next frame.
8309
+ * @throws IgnifxError with code `IGX-0728` on a headless app or before `app.start()` has
8310
+ * registered the render scene, and `IGX-0106` when the app is disposed, also while the overlay
8311
+ * was opening.
8312
+ *
8313
+ * @example
8314
+ * ```ts
8315
+ * const overlay = await app.renderer.openOverlay();
8316
+ * // Lite code under src/lite/ adds gizmos to overlay.lite.scene.
8317
+ * overlay.dispose();
8318
+ * ```
8319
+ *
8320
+ * @beta
8321
+ */
8322
+ openOverlay(): Promise<RenderOverlay>;
7953
8323
  /**
7954
8324
  * Registers a probe that answers whether a rendering context **other than the render scene** is
7955
8325
  * drawing a world through a camera of its own.
@@ -7985,11 +8355,18 @@ declare class RendererImpl implements Renderer {
7985
8355
  needsCasterRebuild: boolean;
7986
8356
  /** `true` once a light gained or lost a shadow generator, so the next rebuild needs fresh layouts. */
7987
8357
  needsShadowLayoutReset: boolean;
8358
+ /**
8359
+ * `true` from the moment the render sync system queues a renderable rebuild until the last one it
8360
+ * owes has finished. A light waits for it to be `false` before it gains or loses a shadow generator.
8361
+ */
8362
+ isRebuildInFlight: boolean;
7988
8363
  /**
7989
8364
  * The PBR deformation kinds (`PBR_DEFORMER` bits) a full renderable build has already composed on
7990
8365
  * this engine. A kind missing from it gets fresh layouts on its first rebuild (`../lite/pbr-deformers.ts`).
7991
8366
  */
7992
8367
  builtPbrDeformers: number;
8368
+ /** Lite's material cache resets, as this scene's rebuilds identified them (`../lite/shadow.ts`). */
8369
+ readonly materialCacheResets: MaterialCacheResets;
7993
8370
  /** `true` once a camera was added, removed, enabled, disabled, or re-prioritised. */
7994
8371
  needsCameraSelect: boolean;
7995
8372
  /** `true` once the world has been told it has no enabled camera, so `IGX-0706` is logged once. */
@@ -8146,7 +8523,7 @@ declare class RendererImpl implements Renderer {
8146
8523
  *
8147
8524
  * @param x - The backing-store pixel x, from the canvas's left edge.
8148
8525
  * @param y - The backing-store pixel y, from the canvas's top edge.
8149
- * @param options - An entity filter.
8526
+ * @param options - An entity filter, and what to look through.
8150
8527
  * @returns What was hit, or `null` for a miss.
8151
8528
  */
8152
8529
  pickAsync(x: number, y: number, options?: RenderPickOptions): Promise<RenderPick | null>;
@@ -8170,6 +8547,14 @@ declare class RendererImpl implements Renderer {
8170
8547
  * @throws IgnifxError with code `IGX-0704` after the render scene has been registered.
8171
8548
  */
8172
8549
  requireFeature(feature: RenderingFeature): void;
8550
+ /**
8551
+ * Opens an overlay drawn over the finished frame.
8552
+ *
8553
+ * @returns The overlay.
8554
+ * @throws IgnifxError with code `IGX-0728` on a headless app or before the render scene is
8555
+ * registered, and `IGX-0106` when the app is disposed, also while the overlay was opening.
8556
+ */
8557
+ openOverlay(): Promise<RenderOverlay>;
8173
8558
  /**
8174
8559
  * Registers a probe that answers whether another rendering context has a camera of its own.
8175
8560
  *
@@ -8222,11 +8607,20 @@ declare class RendererImpl implements Renderer {
8222
8607
  width: number;
8223
8608
  height: number;
8224
8609
  }): void;
8610
+ /**
8611
+ * Turns a pick's options into the mesh predicate and the earlier hits Lite looks through.
8612
+ *
8613
+ * @param options - The caller's options.
8614
+ * @returns The predicate — `null` when every mesh may be picked — and the hits to ignore.
8615
+ *
8616
+ * @internal
8617
+ */
8618
+ planPick(options: RenderPickOptions | undefined): PickPlan;
8225
8619
  /**
8226
8620
  * Resolves a Lite pick result back to the entity and component that own the mesh.
8227
8621
  *
8228
8622
  * @param info - Lite's picking info, from the GPU picker or a CPU ray cast.
8229
- * @returns What was hit, or `null` for a miss or a mesh ignifx did not create.
8623
+ * @returns What was hit, or `null` for a miss or a mesh no entity owns.
8230
8624
  *
8231
8625
  * @internal
8232
8626
  */
@@ -8365,7 +8759,31 @@ declare class RendererImpl implements Renderer {
8365
8759
  */
8366
8760
  publishCounters(cameras: number, lights: number, meshes: number): void;
8367
8761
  /**
8368
- * Releases the picker and the warm-up probes. The core extension registers it as a disposer.
8762
+ * Runs a scene change now, or holds it until the render sync system's rebuild has finished when
8763
+ * one is in flight.
8764
+ *
8765
+ * @remarks
8766
+ * For a change a rebuild must not see half-way: one that changes how many shadow generators the
8767
+ * scene has. A rebuild reads them group by group against layouts cached without that number, so
8768
+ * a group built after the change gets a bind group the layout does not match.
8769
+ *
8770
+ * @param change - The change.
8771
+ *
8772
+ * @internal
8773
+ */
8774
+ afterRebuild(change: () => void): void;
8775
+ /**
8776
+ * Takes the changes {@link RendererImpl.afterRebuild} held back. The render sync system runs them
8777
+ * once its rebuild has finished. A disposed renderer hands back none: its scene is gone.
8778
+ *
8779
+ * @returns The changes, oldest first.
8780
+ *
8781
+ * @internal
8782
+ */
8783
+ takeHeldChanges(): (() => void)[];
8784
+ /**
8785
+ * Releases the open overlays, the picker and the warm-up probes. The core extension registers it
8786
+ * as a disposer.
8369
8787
  *
8370
8788
  * @internal
8371
8789
  */
@@ -8926,7 +9344,9 @@ interface RayVector {
8926
9344
  * @example
8927
9345
  * ```ts
8928
9346
  * const ray = createRay();
8929
- * camera.screenToRay(event.offsetX, event.offsetY, ray);
9347
+ * // A DOM event is in CSS pixels; the camera speaks the canvas's backing-store pixels.
9348
+ * const scale = canvas.width / canvas.clientWidth;
9349
+ * camera.screenToRay(event.offsetX * scale, event.offsetY * scale, ray);
8930
9350
  * ```
8931
9351
  *
8932
9352
  * @public
@@ -8997,7 +9417,9 @@ export declare class Camera extends Component implements ComponentHooks {
8997
9417
  * @remarks
8998
9418
  * Coordinates are backing-store pixels — the canvas's `width`/`height`, the space
8999
9419
  * {@link Camera.worldToScreen} answers in and `@ignifx/input` reports `<Pointer>/position` in — not
9000
- * CSS pixels; multiply a DOM event's `offsetX`/`offsetY` by `devicePixelRatio` first.
9420
+ * CSS pixels; multiply a DOM event's `offsetX`/`offsetY` by `canvas.width / canvas.clientWidth`
9421
+ * first (`devicePixelRatio` is that ratio only while `renderer.pixelRatio` and
9422
+ * `renderer.resolutionScale` leave it alone).
9001
9423
  *
9002
9424
  * @param x - The backing-store pixel x, from the canvas's left edge.
9003
9425
  * @param y - The backing-store pixel y, from the canvas's top edge.
@@ -9069,65 +9491,222 @@ export declare class Camera extends Component implements ComponentHooks {
9069
9491
  sync(renderer: RendererImpl): void;
9070
9492
  }
9071
9493
  //#endregion
9072
- //#region src/world/world.d.ts
9494
+ //#region src/serialization/load.d.ts
9073
9495
  /**
9074
- * The running simulation: the entity registry, the scene instances, and the lifecycle queues
9075
- * (`docs/architecture/02-scene-graph.md` §2). One world per app in the MVP.
9076
- *
9077
- * @remarks
9078
- * The world owns entity creation, queries, the implicit `"default"` scene, and the lifecycle, plus
9079
- * the scene operations that need the asset service — `loadScene`, `unloadScene`, `instantiate`,
9080
- * `instantiateAsync`, `moveEntityToScene` — and the `onSceneLoaded`/`onSceneUnloaded` signals they
9081
- * raise.
9496
+ * One recoverable problem found while a scene was being built. Nothing here stops the load: a file
9497
+ * degrades one field, one reference, or one layer rather than failing whole
9498
+ * (`docs/architecture/06-serialization-and-scene-format.md` §4).
9082
9499
  *
9083
- * @example
9084
- * ```ts
9085
- * const player = app.world.createEntity("Player");
9086
- * for (const script of app.world.components(Script)) {
9087
- * script.enabled = false;
9088
- * }
9089
- * ```
9500
+ * @public
9501
+ */
9502
+ interface SceneLoadIssue {
9503
+ /** The diagnostic code, for example `IGX-0602` or `IGX-0303`. */
9504
+ readonly code: string;
9505
+ /** The actionable sentence. */
9506
+ readonly message: string;
9507
+ }
9508
+ /**
9509
+ * Options accepted by {@link instantiateScene}.
9090
9510
  *
9091
9511
  * @public
9092
9512
  */
9093
- export declare class World implements WorldHost {
9094
- #private;
9095
- /**
9096
- * Builds a world. Call `createWorld` instead; the runtime owns this.
9097
- *
9098
- * @param options - The app, the Lite scene, the frame state, and the resolved settings.
9099
- *
9100
- * @internal
9101
- */
9102
- constructor(options: CreateWorldOptions);
9103
- /**
9104
- * The app that owns the world.
9105
- *
9106
- * @returns The app.
9107
- */
9108
- get app(): App;
9109
- /**
9110
- * The world itself; `WorldHost` names it so entities can reach it.
9111
- *
9112
- * @returns This world.
9113
- */
9114
- get world(): World;
9513
+ interface InstantiateSceneOptions {
9514
+ /** The entity the scene's roots attach to; `null` or omitted makes them roots of `scene`. */
9515
+ readonly parent?: Entity | null;
9516
+ /** The instance that owns the new entities; defaults to the parent's, else `world.activeScene`. */
9517
+ readonly scene?: SceneInstance;
9115
9518
  /**
9116
- * The project's resolved layer names. `world.layers.mask("Player", "Enemy")` builds a mask.
9117
- *
9118
- * @returns The layer table.
9519
+ * `true` treats the whole file as one instance: every entity gets a fresh uid and an
9520
+ * `Entity.prefab` link. This is what `world.instantiate` does; `world.loadScene` leaves it off so
9521
+ * that the scene's own entities keep the uids the file gave them
9522
+ * (`docs/architecture/02-scene-graph.md` §10).
9119
9523
  */
9120
- get layers(): LayerTable;
9524
+ readonly asInstance?: boolean;
9525
+ /** The handle the scene was loaded through, recorded on `Entity.prefab` when `asInstance`. */
9526
+ readonly assetHandle?: AssetHandle<SceneAsset> | null;
9121
9527
  /**
9122
- * The component-class table.
9123
- *
9124
- * @returns The registry.
9528
+ * The entity that stands for the instance when `asInstance` is set and the file has more or fewer
9529
+ * than one root. `world.instantiate` creates it and passes it as both `parent` and `rootEntity`,
9530
+ * so that the call still answers with one entity.
9125
9531
  */
9126
- get registry(): ComponentRegistry;
9127
- /**
9128
- * The live per-type component index.
9129
- *
9130
- * @returns The store.
9532
+ readonly rootEntity?: Entity | null;
9533
+ /** `true` turns an `IGX-0604` hash mismatch from a diagnostic into a throw. */
9534
+ readonly strictInstanceHashes?: boolean;
9535
+ }
9536
+ /**
9537
+ * What {@link instantiateScene} produced.
9538
+ *
9539
+ * @public
9540
+ */
9541
+ interface SceneBuildResult {
9542
+ /** The entities that ended up parentless within the built subtree, in file order. */
9543
+ readonly roots: readonly Entity[];
9544
+ /** The file-local uid to runtime object table (`docs/architecture/02-scene-graph.md` §10). */
9545
+ readonly remap: UidRemap;
9546
+ /** Every recoverable problem, in discovery order. */
9547
+ readonly issues: readonly SceneLoadIssue[];
9548
+ }
9549
+ /**
9550
+ * Builds the entities of a scene asset into a world — steps 3 to 6 of the loading algorithm
9551
+ * (`docs/architecture/06-serialization-and-scene-format.md` §4). It is synchronous and does no I/O:
9552
+ * every asset the file references is already loaded, which is what a `SceneAsset` guarantees.
9553
+ *
9554
+ * @remarks
9555
+ * The mechanism that keeps `awake` honest is worth stating, because §4 step 6 and
9556
+ * `01-lifecycle-and-time.md` §4 state only the outcome. Entities are created with `active: false`,
9557
+ * so the enable transition computes "not effectively enabled" and queues nothing. Components are
9558
+ * attached with their schema defaults, then every component's props are decoded — that is where
9559
+ * `entityRef` and `componentRef` resolve, through a table that by then holds the whole scene. Only
9560
+ * then does a last pass write each entity's file `active` value in tree order, which is what queues
9561
+ * `awake` and `onEnable`, parents before children. Nothing observes the half-built scene, because
9562
+ * all of this runs in one synchronous block.
9563
+ *
9564
+ * @param world - The world to build into.
9565
+ * @param asset - The scene to build.
9566
+ * @param options - Where to attach the result, and how to treat instance hashes.
9567
+ * @returns The roots, the uid table, and every recoverable problem.
9568
+ * @throws IgnifxError with code `IGX-0302` on an instance cycle, `IGX-0307` when the file names an
9569
+ * unregistered component type, and `IGX-0604` when `strictInstanceHashes` is set and a recorded
9570
+ * instance hash does not match.
9571
+ *
9572
+ * @example
9573
+ * ```ts
9574
+ * const built = instantiateScene(world, sceneAsset, { scene: world.activeScene });
9575
+ * const player = built.remap.entity("01J9Z6M7E5S3A0V2Q4R8T1Y6WX");
9576
+ * ```
9577
+ *
9578
+ * @public
9579
+ */
9580
+ export declare function instantiateScene(world: World, asset: SceneAsset, options?: InstantiateSceneOptions): SceneBuildResult;
9581
+ /**
9582
+ * Options accepted by {@link addComponentFromRecord}.
9583
+ *
9584
+ * @public
9585
+ */
9586
+ interface AddComponentFromRecordOptions {
9587
+ /**
9588
+ * The component's index among the entity's components as a scene file lists them (the transform
9589
+ * and the components an instanced scene put on the entity do not count). Defaults to the end; a
9590
+ * value past the end is clamped to it.
9591
+ */
9592
+ readonly index?: number;
9593
+ /**
9594
+ * How `$entity`, `$component` and `$asset` values in the record's `props` resolve. Without one
9595
+ * every reference decodes as `null` and is reported (`IGX-0602`). An asset must already be loaded:
9596
+ * decoding never starts a load.
9597
+ */
9598
+ readonly references?: ReferenceDecoder;
9599
+ }
9600
+ /**
9601
+ * What {@link addComponentFromRecord} built.
9602
+ *
9603
+ * @public
9604
+ */
9605
+ interface ComponentBuildResult {
9606
+ /** The attached component, carrying the record's uid. */
9607
+ readonly component: Component;
9608
+ /** Every recoverable problem found while decoding `props`, in discovery order. */
9609
+ readonly issues: readonly SceneLoadIssue[];
9610
+ }
9611
+ /**
9612
+ * Attaches one component to a live entity from its scene file record, the way the scene loader
9613
+ * builds it: the record's registered type, its uid, its `enabled` flag, and its `props` decoded
9614
+ * against the schema (`docs/architecture/06-serialization-and-scene-format.md` §4).
9615
+ *
9616
+ * @remarks
9617
+ * This is the per-component step of {@link instantiateScene} for a world that already exists, which
9618
+ * is what an editor mirroring a document into a live world needs. The component is attached with
9619
+ * `entity.addComponent`, so `awake` follows that method's rules. The record's uid is adopted as is;
9620
+ * keeping it unique within the scene is the caller's job. Decoding never throws: a value that does
9621
+ * not match its field takes the field's default and is reported in `issues`.
9622
+ *
9623
+ * @param entity - The entity to attach to.
9624
+ * @param record - The component record, as a scene file writes it.
9625
+ * @param options - Where it goes among the entity's components, and how references resolve.
9626
+ * @returns The component and the decoding problems.
9627
+ * @throws IgnifxError with code `IGX-0307` when the record's type is not registered, and whatever
9628
+ * `entity.addComponent` throws (`IGX-0202` for a second instance of a single-instance class,
9629
+ * `IGX-0101` for a destroyed entity).
9630
+ *
9631
+ * @example
9632
+ * ```ts
9633
+ * const { component } = addComponentFromRecord(player, { uid: "01J9Z6M7E5S3A0V2Q4R8T1Y6WY", type: "game/Health", props: { max: 120 } });
9634
+ * ```
9635
+ *
9636
+ * @public
9637
+ */
9638
+ export declare function addComponentFromRecord(entity: Entity, record: SceneFileComponent, options?: AddComponentFromRecordOptions): ComponentBuildResult;
9639
+ /**
9640
+ * Checks that every scene a file instances — at any depth — is among the loaded dependencies, which
9641
+ * is what makes `world.instantiate` safe to be synchronous
9642
+ * (`docs/architecture/02-scene-graph.md` §2).
9643
+ *
9644
+ * @param asset - The scene to check.
9645
+ * @throws IgnifxError with code `IGX-0301` naming the first instanced scene that is not loaded.
9646
+ *
9647
+ * @public
9648
+ */
9649
+ export declare function assertSceneDependenciesLoaded(asset: SceneAsset): void;
9650
+ //#endregion
9651
+ //#region src/world/world.d.ts
9652
+ /**
9653
+ * The running simulation: the entity registry, the scene instances, and the lifecycle queues
9654
+ * (`docs/architecture/02-scene-graph.md` §2). One world per app in the MVP.
9655
+ *
9656
+ * @remarks
9657
+ * The world owns entity creation, queries, the implicit `"default"` scene, and the lifecycle, plus
9658
+ * the scene operations that need the asset service — `loadScene`, `unloadScene`, `instantiate`,
9659
+ * `instantiateAsync`, `moveEntityToScene` — and the `onSceneLoaded`/`onSceneUnloaded` signals they
9660
+ * raise.
9661
+ *
9662
+ * @example
9663
+ * ```ts
9664
+ * const player = app.world.createEntity("Player");
9665
+ * for (const script of app.world.components(Script)) {
9666
+ * script.enabled = false;
9667
+ * }
9668
+ * ```
9669
+ *
9670
+ * @public
9671
+ */
9672
+ export declare class World implements WorldHost {
9673
+ #private;
9674
+ /**
9675
+ * Builds a world. Call `createWorld` instead; the runtime owns this.
9676
+ *
9677
+ * @param options - The app, the Lite scene, the frame state, and the resolved settings.
9678
+ *
9679
+ * @internal
9680
+ */
9681
+ constructor(options: CreateWorldOptions);
9682
+ /**
9683
+ * The app that owns the world.
9684
+ *
9685
+ * @returns The app.
9686
+ */
9687
+ get app(): App;
9688
+ /**
9689
+ * The world itself; `WorldHost` names it so entities can reach it.
9690
+ *
9691
+ * @returns This world.
9692
+ */
9693
+ get world(): World;
9694
+ /**
9695
+ * The project's resolved layer names. `world.layers.mask("Player", "Enemy")` builds a mask.
9696
+ *
9697
+ * @returns The layer table.
9698
+ */
9699
+ get layers(): LayerTable;
9700
+ /**
9701
+ * The component-class table.
9702
+ *
9703
+ * @returns The registry.
9704
+ */
9705
+ get registry(): ComponentRegistry;
9706
+ /**
9707
+ * The live per-type component index.
9708
+ *
9709
+ * @returns The store.
9131
9710
  *
9132
9711
  * @internal
9133
9712
  */
@@ -9292,7 +9871,7 @@ export declare class World implements WorldHost {
9292
9871
  * answer.
9293
9872
  *
9294
9873
  * @param ray - The ray to cast.
9295
- * @param options - An entity filter.
9874
+ * @param options - An entity filter, and what to look through.
9296
9875
  * @returns What was hit, or `null` for a miss.
9297
9876
  *
9298
9877
  * @example
@@ -9372,6 +9951,60 @@ export declare class World implements WorldHost {
9372
9951
  * ```
9373
9952
  */
9374
9953
  loadScene(scene: AssetRef<SceneAsset> | string, options?: LoadSceneOptions): Promise<SceneInstance>;
9954
+ /**
9955
+ * Builds a scene from a file that is already in memory, the way {@link World.loadScene} builds one
9956
+ * from an address (`docs/architecture/02-scene-graph.md` §2).
9957
+ *
9958
+ * @remarks
9959
+ * Nothing is fetched for the file itself: it is validated, every asset it references is loaded
9960
+ * through `app.assets` (the scene loader's own walk), and it is published there at
9961
+ * `options.address` as a scene asset, so the instance's `asset` and everything that reads it
9962
+ * behave as for a loaded file. Entity and component uids are the file's. The instance holds the
9963
+ * asset and its dependencies and releases them when it is unloaded. The rest is
9964
+ * {@link World.loadScene}'s: the same modes, the same synchronous build, `awake` before the
9965
+ * promise settles, and `onSceneLoaded`.
9966
+ *
9967
+ * This is how a tool builds a scene it holds as an object, such as an editor's open document with
9968
+ * unsaved edits.
9969
+ *
9970
+ * @param file - The scene file object, as `serializeScene` or `JSON.parse` produces it.
9971
+ * @param options - The address to publish it at, the mode, cancellation, and an issue collector.
9972
+ * @returns The instance, once every entity exists, every reference is resolved, and `awake` has
9973
+ * run.
9974
+ * @throws IgnifxError with code `IGX-0308` when the object is not a scene file, `IGX-0603` for a
9975
+ * format version this build cannot read, and `IGX-0608` when it does not match the scene format;
9976
+ * nothing is unloaded then. `IGX-0502` when `options.signal` aborts, `IGX-0307` when the file
9977
+ * names an unregistered component type (the half-built instance is unloaded first), and
9978
+ * whatever the asset system throws for a dependency.
9979
+ *
9980
+ * @example
9981
+ * ```ts
9982
+ * const level = await world.loadSceneFile(file, { address: "levels/level01.scene.json" });
9983
+ * ```
9984
+ */
9985
+ loadSceneFile(file: SceneFile, options: LoadSceneFileOptions): Promise<SceneInstance>;
9986
+ /**
9987
+ * Creates an empty scene instance that is built in code rather than loaded from a file
9988
+ * (`docs/architecture/02-scene-graph.md` §3).
9989
+ *
9990
+ * @remarks
9991
+ * Entities join it through `createEntity(name, { scene })` or `moveEntityToScene`. A persistent
9992
+ * instance survives every `"single"` load, so it is where a tool keeps objects that must outlive
9993
+ * the levels it loads: an editor's cameras, grid and gizmo roots. Like any instance other than the
9994
+ * implicit `"default"` one, it can be unloaded with `unloadScene`. Creating it raises no
9995
+ * `onSceneLoaded`, because nothing was loaded; `serializeScene` writes it only when it is passed.
9996
+ *
9997
+ * @param name - The instance's name.
9998
+ * @param options - Whether it is persistent.
9999
+ * @returns The new, empty instance, appended to `scenes`.
10000
+ *
10001
+ * @example
10002
+ * ```ts
10003
+ * const tools = world.createScene("editor", { persistent: true });
10004
+ * const camera = world.createEntity("Editor Camera", { scene: tools });
10005
+ * ```
10006
+ */
10007
+ createScene(name: string, options?: CreateSceneOptions): SceneInstance;
9375
10008
  /**
9376
10009
  * Unloads a scene instance: `onUnloading` fires while its entities are still valid, its roots are
9377
10010
  * destroyed through the normal destroy path (children before parents, `onDisable` then
@@ -9625,6 +10258,46 @@ interface LoadSceneOptions {
9625
10258
  /** `true` turns an `IGX-0604` instance hash mismatch from a logged warning into a throw. */
9626
10259
  readonly strictInstanceHashes?: boolean;
9627
10260
  }
10261
+ /**
10262
+ * Options accepted by {@link World.loadSceneFile}.
10263
+ *
10264
+ * @public
10265
+ */
10266
+ interface LoadSceneFileOptions {
10267
+ /**
10268
+ * The address the scene is published at in `app.assets`, for example
10269
+ * `"levels/level01.scene.json"`, or a `memory:` address for a file that was never saved. It
10270
+ * replaces whatever the cache held there. The file is never fetched from it.
10271
+ */
10272
+ readonly address: string;
10273
+ /** The instance's name; defaults to the file's `name`. */
10274
+ readonly name?: string;
10275
+ /**
10276
+ * `"single"` (the default) unloads every instance that is not `persistent` first; `"additive"`
10277
+ * keeps them.
10278
+ */
10279
+ readonly mode?: "single" | "additive";
10280
+ /** Cancels the dependency loads; an abort rejects with `IGX-0502`. */
10281
+ readonly signal?: AbortSignal;
10282
+ /** Makes the instance `world.activeScene`. Defaults to `true` for `"single"`, `false` for `"additive"`. */
10283
+ readonly setActive?: boolean;
10284
+ /** `true` turns an `IGX-0604` instance hash mismatch from a logged warning into a throw. */
10285
+ readonly strictInstanceHashes?: boolean;
10286
+ /**
10287
+ * Receives every recoverable problem the build found (`SceneBuildResult.issues`), in order. They
10288
+ * are also written to the app log as warnings, as for `loadScene`.
10289
+ */
10290
+ readonly onIssue?: (issue: SceneLoadIssue) => void;
10291
+ }
10292
+ /**
10293
+ * Options accepted by {@link World.createScene}.
10294
+ *
10295
+ * @public
10296
+ */
10297
+ interface CreateSceneOptions {
10298
+ /** Whether the instance survives a `"single"` scene load. Defaults to `false`. */
10299
+ readonly persistent?: boolean;
10300
+ }
9628
10301
  /**
9629
10302
  * Options accepted by {@link World.instantiate} and {@link World.instantiateAsync}
9630
10303
  * (`docs/architecture/02-scene-graph.md` §2).
@@ -9818,6 +10491,27 @@ interface EntityInstanceLink {
9818
10491
  readonly asset: AssetHandle<SceneAsset> | null;
9819
10492
  /** The scene value, so the serializer can diff current state against it. */
9820
10493
  readonly scene: SceneAsset;
10494
+ /**
10495
+ * Set when the instance root *is* the instanced scene's single root, rather than a container
10496
+ * holding the scene's roots (`06-serialization-and-scene-format.md` §2).
10497
+ */
10498
+ readonly root: InstancedRoot | null;
10499
+ }
10500
+ /**
10501
+ * What an instance root that stands for its scene's single root took from that root.
10502
+ *
10503
+ * @internal
10504
+ */
10505
+ interface InstancedRoot {
10506
+ /** The uid of the root's record in the instanced file, which overrides address. */
10507
+ readonly sourceUid: string;
10508
+ /** Expanded component uid to the uid the instanced root's record gives that component. */
10509
+ readonly componentSourceUids: ReadonlyMap<string, string>;
10510
+ /**
10511
+ * Every component the instancing put on the entity, including those a variant's own instance
10512
+ * merged in; the serializer writes the others as the entry's own `components`.
10513
+ */
10514
+ readonly components: ReadonlySet<string>;
9821
10515
  }
9822
10516
  /**
9823
10517
  * The engine-owned state of one entity.
@@ -10017,6 +10711,11 @@ export declare class Entity {
10017
10711
  * The immovability hint: `true` promises that the transform will not change after `awake`, which
10018
10712
  * lets the 2D batcher, physics, and navmesh treat the entity as static.
10019
10713
  *
10714
+ * @remarks
10715
+ * It can be changed only in files or before `awake`; afterwards the setter throws `IGX-0101`. In an
10716
+ * edit-mode app it stays writable, because an editor's inspector edits it on loaded entities
10717
+ * (ADR-0028).
10718
+ *
10020
10719
  * @returns `true` when the entity is marked static.
10021
10720
  */
10022
10721
  get isStatic(): boolean;
@@ -10116,6 +10815,21 @@ export declare class Entity {
10116
10815
  * ```
10117
10816
  */
10118
10817
  setParent(parent: Entity | null, options?: SetParentOptions): void;
10818
+ /**
10819
+ * Moves the entity among its siblings: its parent's children, or its scene's roots when it has no
10820
+ * parent. Sibling order is the order a scene file lists entities in and the order `children`
10821
+ * reports.
10822
+ *
10823
+ * @param index - The entity's new index among its siblings. A value past either end is clamped
10824
+ * to that end, and a fraction is truncated.
10825
+ * @throws IgnifxError with code `IGX-0101` when the entity has been destroyed.
10826
+ *
10827
+ * @example
10828
+ * ```ts
10829
+ * weapon.setSiblingIndex(0); // first child of its parent
10830
+ * ```
10831
+ */
10832
+ setSiblingIndex(index: number): void;
10119
10833
  /**
10120
10834
  * Resolves a path relative to this entity — `"Body/Arm.L"`, `"../Sibling"`, `"/Root/Child"`.
10121
10835
  *
@@ -10607,8 +11321,8 @@ interface ComponentStatics {
10607
11321
  }
10608
11322
  /**
10609
11323
  * The static members a script class may declare: everything {@link ComponentStatics} allows plus
10610
- * the two scheduling flags (`docs/architecture/01-lifecycle-and-time.md` §3). Structural and
10611
- * optional for the reason given on {@link ComponentStatics}.
11324
+ * the scheduling flags (`docs/architecture/01-lifecycle-and-time.md` §3). Structural and optional
11325
+ * for the reason given on {@link ComponentStatics}.
10612
11326
  *
10613
11327
  * @public
10614
11328
  */
@@ -10623,6 +11337,22 @@ interface ScriptStatics extends ComponentStatics {
10623
11337
  * Defaults to `false`.
10624
11338
  */
10625
11339
  readonly updateWhenPaused?: boolean;
11340
+ /**
11341
+ * When `true`, the script receives its callbacks in an edit-mode app
11342
+ * (`createApp({ editMode: true })`, ADR-0028), as an editor camera or a tool script needs.
11343
+ * Defaults to `false`: in edit mode a script gets no `awake`, `update`, or any other callback.
11344
+ *
11345
+ * @example
11346
+ * ```ts
11347
+ * class EditorCamera extends Script {
11348
+ * static runInEditMode = true;
11349
+ * update(dt: number): void {
11350
+ * this.transform.translate({ x: 0, y: 0, z: dt });
11351
+ * }
11352
+ * }
11353
+ * ```
11354
+ */
11355
+ readonly runInEditMode?: boolean;
10626
11356
  }
10627
11357
  /**
10628
11358
  * A component class used as a **query token** — `entity.getComponent(Type)`,
@@ -12328,6 +13058,12 @@ interface SystemContext {
12328
13058
  * `updateWhenPaused` — so a system that animates checks `time.paused` itself.
12329
13059
  */
12330
13060
  readonly dt: number;
13061
+ /**
13062
+ * `true` when the scheduler is holding this system's clock: in an edit-mode app, for a system
13063
+ * registered with `editMode: "hold"` (ADR-0028). `dt` is `0` then, and a system that reads
13064
+ * `time` directly treats the frame as paused.
13065
+ */
13066
+ readonly isClockHeld: boolean;
12331
13067
  }
12332
13068
  /**
12333
13069
  * Engine-level logic that runs once per phase over many components, registered by an extension
@@ -12591,6 +13327,8 @@ interface CoroutineHost {
12591
13327
  * @param owner - The script whose enabled state gates the coroutine.
12592
13328
  * @param routine - The generator to drive.
12593
13329
  * @returns A handle for stopping it or waiting on it.
13330
+ * @throws IgnifxError with code `IGX-0111` in an edit-mode app when the owner's class does not
13331
+ * set `static runInEditMode = true`.
12594
13332
  */
12595
13333
  start(owner: Script, routine: Coroutine): CoroutineHandle;
12596
13334
  /**
@@ -12721,6 +13459,12 @@ interface App {
12721
13459
  readonly onError: Signal<ErrorReport>;
12722
13460
  /** `true` when the app runs on Lite's null engine with no render surface. */
12723
13461
  readonly isHeadless: boolean;
13462
+ /**
13463
+ * `true` when the app was created with `createApp({ editMode: true })`: an editor's scene view
13464
+ * (ADR-0028). Scripts get no callbacks unless their class sets `static runInEditMode = true`,
13465
+ * the fixed loop and physics do not run, and coroutines cannot start. Fixed for the app's life.
13466
+ */
13467
+ readonly isEditMode: boolean;
12724
13468
  /** `true` between `start()` and `stop()`/`dispose()`. */
12725
13469
  readonly isRunning: boolean;
12726
13470
  /** The `@ignifx/core` version this app was built from. */
@@ -12814,7 +13558,33 @@ interface RegisterSystemOptions {
12814
13558
  readonly phase: Phase;
12815
13559
  /** Ascending order within the phase; core uses `[-1000, 1000]`, extensions `[1001, 9999]`. */
12816
13560
  readonly order?: number;
13561
+ /**
13562
+ * What the system does in an edit-mode app (ADR-0028). Defaults to `"run"`. Ignored when the app
13563
+ * is not in edit mode.
13564
+ */
13565
+ readonly editMode?: SystemEditMode;
12817
13566
  }
13567
+ /**
13568
+ * What a system does in an edit-mode app (`createApp({ editMode: true })`, ADR-0028).
13569
+ *
13570
+ * - `"run"`: runs as it does in a game. Right for systems that turn component data into what is
13571
+ * drawn, heard, or laid out.
13572
+ * - `"hold"`: runs with `ctx.dt` set to `0` and `ctx.isClockHeld` set to `true`, so it shows its
13573
+ * current state without moving it forward.
13574
+ * - `"skip"`: does not run. Right for simulation, and for systems that would overwrite authored
13575
+ * data such as a transform.
13576
+ *
13577
+ * A `FixedUpdate` system never runs in edit mode, whatever it declares, because the fixed loop does
13578
+ * not run.
13579
+ *
13580
+ * @example
13581
+ * ```ts
13582
+ * ctx.registerSystem(new WindSystem(), { phase: Phase.Update, editMode: "skip" });
13583
+ * ```
13584
+ *
13585
+ * @public
13586
+ */
13587
+ type SystemEditMode = "run" | "hold" | "skip";
12818
13588
  /**
12819
13589
  * An extension's registration surface (`docs/architecture/04-extensions.md` §1). Everything an
12820
13590
  * extension contributes is declared here; nothing happens at module import time
@@ -13281,6 +14051,17 @@ interface CreateAppOptions {
13281
14051
  * rebuilds the live instances built from it.
13282
14052
  */
13283
14053
  readonly hotReload?: HotReloadOptions;
14054
+ /**
14055
+ * Builds the app for an editor's scene view (ADR-0028,
14056
+ * `docs/architecture/03-scripting-and-components.md` §10). Scripts get no lifecycle or frame
14057
+ * callbacks unless their class sets `static runInEditMode = true`; the fixed loop, physics, and
14058
+ * other simulation systems do not run; `startCoroutine` throws `IGX-0111` for a script that does
14059
+ * not run in edit mode. Systems that turn component data into what is drawn keep running. Fixed
14060
+ * for the app's life; `app.isEditMode` reports it.
14061
+ *
14062
+ * @defaultValue `false`
14063
+ */
14064
+ readonly editMode?: boolean;
13284
14065
  }
13285
14066
  /**
13286
14067
  * Creates a game (`docs/architecture/00-overview.md` §1, `04-extensions.md` §2).
@@ -13316,15 +14097,14 @@ export declare function createApp(options?: CreateAppOptions): Promise<App>;
13316
14097
  * `version` (`docs/architecture/04-extensions.md` §1).
13317
14098
  *
13318
14099
  * @remarks
13319
- * The literal is `"0.0.0"` in the repository and is stamped by the release pipeline: Changesets
13320
- * writes the real number into `package.json`, and the build replaces this constant with it
13321
- * (coding standards §12, `release.yml`). Reading the version from `package.json` at run time is not
13322
- * an option — that would be an import-time side effect and a bundler hazard
14100
+ * The build stamps it from `package.json`, where Changesets writes each release's number; code run
14101
+ * from source, such as this repository's tests, sees `"0.0.0"`. Reading `package.json` at run time
14102
+ * is not an option: that would be an import-time side effect and a bundler hazard
13323
14103
  * (`CONSTITUTION.md` §3.5).
13324
14104
  *
13325
14105
  * @public
13326
14106
  */
13327
- export declare const VERSION = "0.0.0";
14107
+ export declare const VERSION: string;
13328
14108
  //#endregion
13329
14109
  //#region src/assets/asset-ref.d.ts
13330
14110
  /**
@@ -13742,44 +14522,44 @@ export declare const MAX_ULID_TIME_MS: number;
13742
14522
  *
13743
14523
  * ## Why an ignifx light is never parented in Lite
13744
14524
  *
13745
- * A Lite light is an `IParentable` with a world matrix (`LightBase`, `index.d.ts` 6589), so
13746
- * parenting it under the entity's node looks like the obvious mirror of what `Camera` and
13747
- * `MeshRenderer` do. It is wrong, and the visual suite caught it:
13748
- *
13749
- * - Lite composes a light's world matrix as `parentWorld × localMatrixFromDirection(direction,
13750
- * position)` (`lib/light/directional-light.js` 8-10, `lib/light/light-matrix.js`), and the shader
13751
- * reads the **third column of that world matrix** as the light direction
13752
- * (`lib/light/directional-light.js` 20-22 copies `w[8]`, `w[9]`, `w[10]`; the spot light also
13753
- * takes its position from `w[12..14]`, `lib/light/spot-light.js` 28-30). Writing the entity's
13754
- * **world** forward into `direction` while the light is **also** parented applies the entity's
13755
- * rotation twice, so the light shades from a direction that is neither the local nor the world
13756
- * one.
13757
- * - The shadow frustum does not go through the world matrix at all:
13758
- * `computeDirectionalLightMatrix` fits it from `light.direction` and `light.position` directly
13759
- * (`lib/shadow/shadow-base.js` 54-55). A parented light therefore shades from one direction and
13760
- * casts along another.
13761
- *
13762
- * One pose, written once, is the only arrangement in which shading, the lights UBO, and the shadow
13763
- * frustum agree: the adapter creates every light with `parent = null` and the component writes the
13764
- * entity's **world** direction and position into the light's own observables with
13765
- * {@link syncLightWorldPose} in each frame the entity moved. With no parent, `worldMatrix` is the
13766
- * local matrix, whose third column is exactly the direction that was written.
13767
- *
13768
- * ## The lights uniform buffer only follows the light's own observables
13769
- *
13770
- * It is re-uploaded when the summed `_lightVersion` of the scene's lights changes
13771
- * (`lib/render/lights-ubo.js`, `refreshSceneLightsUBO`), and that counter is bumped by writes to the
13772
- * light's **own** observable vectors (`lib/light/light-base.js`, `onDirty`). `ObservableVec3.set`
13773
- * fires its dirty hook unconditionally (`lib/math/observable-vec3.js`), so {@link syncLightWorldPose}
13774
- * re-marks the light as a side effect of posing it, and {@link markLightTransformDirty} is the
13775
- * allocation-free nudge for a caller that has nothing new to write.
14525
+ * Since Lite 1.30 a light is a full scene node (`LightBase extends SceneNode`, `index.d.ts` 7620):
14526
+ * `createLightBase` builds it with `initSceneNodeTransform` (`lib/light/light-base.js`), so it has
14527
+ * `position`, `rotationQuaternion`, `scaling`, `parent` and a composed `worldMatrix`. Its
14528
+ * `direction` is **local**: the lights UBO writer and the shadow fit both rotate it by the world
14529
+ * matrix (`writeWorldLightDirection`, `lib/light/light-base.js`; `computeDirectionalLightMatrix`,
14530
+ * `lib/shadow/shadow-base.js` 76-79), and a point or spot light's world position is
14531
+ * `worldMatrix[12..14]` (`lib/light/point-light.js`, `lib/light/spot-light.js`).
14532
+ *
14533
+ * Parenting the light under the entity's node and driving its rotation would also work, but it
14534
+ * needs a quaternion that turns `+Z` into the light's axis — which differs per kind (a hemispheric
14535
+ * light follows the entity's **up**) — and it ties the light's lifetime to the entity's node. The
14536
+ * adapter keeps the simpler arrangement it already had: every light is created with
14537
+ * `parent = null` and an identity rotation and scale, and {@link syncLightWorldPose} writes the
14538
+ * entity's **world** direction into `direction` and its **world** position into `position` in each
14539
+ * frame the entity moved. The world matrix is then a pure translation, so Lite's rotation of
14540
+ * `direction` changes nothing and shading, the lights UBO and the shadow frustum all see the pose
14541
+ * that was written. Nothing here writes `rotationQuaternion` or `scaling`; doing so would rotate
14542
+ * the written direction a second time.
14543
+ *
14544
+ * ## The lights uniform buffer and the shadow refit follow `_lightVersion`
14545
+ *
14546
+ * The lights UBO is re-uploaded when the summed `_lightVersion` of the scene's lights changes
14547
+ * (`computeLightsVersion`, `lib/render/scene-lights-ubo.js`), and a shadow pass refits its frustum
14548
+ * when its light's `_lightVersion` changes (`renderPcfShadowMap`, `lib/shadow/pcf-shadow-task-hooks.js`
14549
+ * 114; the ESM and CSM hooks do the same). That counter is `lvs._lightVersion + worldMatrixVersion`
14550
+ * (`applyLightBase`, `lib/light/light-base.js`): writing `direction` bumps the first term, writing
14551
+ * `position` bumps the second through the scene-node transform. `ObservableVec3.set` fires its
14552
+ * dirty hook unconditionally (`lib/math/observable-vec3.js`), so {@link syncLightWorldPose} re-marks
14553
+ * the light as a side effect of posing it, and {@link markLightTransformDirty} is the
14554
+ * allocation-free nudge for a change Lite cannot see (a colour, a range, an exponent written as a
14555
+ * plain field).
13776
14556
  *
13777
14557
  * ## Two more things Lite spells its own way
13778
14558
  *
13779
14559
  * - Include/exclude lists are sets of `Mesh.id` **strings**, not mesh references
13780
- * (`lib/render/lights-ubo.js`, `affectsMesh`), and a mesh with no `id` is never excluded.
14560
+ * (`lib/render/mesh-light-selection.js`, `affectsMesh`), and a mesh with no `id` is never excluded.
13781
14561
  * - Hemispheric lights spell their colours `diffuseColor`/`specularColor`, not `diffuse`/`specular`
13782
- * (`index.d.ts` 6286) — `docs/architecture/07-rendering.md` §2.2 says "`diffuse`/`specular`" for
14562
+ * (`index.d.ts` 7283) — `docs/architecture/07-rendering.md` §2.2 says "`diffuse`/`specular`" for
13783
14563
  * every type, which is wrong for this one.
13784
14564
  */
13785
14565
  /**
@@ -13794,65 +14574,10 @@ export declare const MAX_ULID_TIME_MS: number;
13794
14574
  */
13795
14575
  type AdapterLight = DirectionalLight | PointLight | SpotLight | HemisphericLight;
13796
14576
  //#endregion
13797
- //#region src/lite/shadow.d.ts
14577
+ //#region src/log/console-sink.d.ts
13798
14578
  /**
13799
- * Shadow half of the Babylon Lite adapter (`docs/architecture/07-rendering.md` §2.2): everything
13800
- * about shadow generators that does **not** need a GPU device. Creating a generator allocates a
13801
- * depth texture and a sampler, so the four factories live in `./gpu/shadow-generator.ts`.
13802
- *
13803
- * Everything here is `@internal`.
13804
- *
13805
- * ## How Lite renders shadows (verified against `@babylonjs/lite@1.27.0`)
13806
- *
13807
- * - A scene grows a shadow pass only through `registerSceneWithShadowSupport`
13808
- * (`index.d.ts` 9542), which unshifts a task named `"shadow"` at the front of the frame graph
13809
- * (`lib/scene/scene-core.js`, `ensureShadowTask`). `registerScene` never adds one, and there is
13810
- * no public call that adds it later — so the decision is made once, at start, from whether any
13811
- * shadow-casting light exists (`docs/architecture/07-rendering.md` §1).
13812
- * - The shadow task finds its work by walking `scene.lights` and reading `light.shadowGenerator`
13813
- * (`lib/frame-graph/shadow-task.js`). Assigning that property is what turns shadows on for a
13814
- * light; `scene.shadowGenerators` is **never written** by Lite in 1.27.0 — only read by
13815
- * device-loss recovery — so the adapter does not maintain it either.
13816
- * - The caster list is a side table keyed by generator (`setShadowTaskCasterMeshes`,
13817
- * `index.d.ts` 10981, `lib/frame-graph/shadow-inputs.js`). Passing a new array parks the
13818
- * generator until an async preload of the shadow pipeline finishes, so the list is replaced as
13819
- * rarely as possible: once per frame in which the caster set actually changed.
13820
- * - A pass redraws its map only when something it tracks moved: the sum of every caster's
13821
- * `worldMatrixVersion` plus its thin-instance version (`casterVersionSum`,
13822
- * `lib/shadow/shadow-base.js` 138), the light's `worldMatrixVersion`, and the floating-origin
13823
- * camera (CSM: the camera and its aspect). Otherwise the previous map is reused
13824
- * (`lib/shadow/pcf-shadow-task-hooks.js` 135, `esm-directional-shadow-generator.js` 179,
13825
- * `csm-shadow-task-hooks.js` 180). A caster that changes shape in place — a skinned mesh, a shader
13826
- * material moving vertices by a uniform — moves none of those, so `./gpu/shadow-generator.ts`
13827
- * adds Lite's skeleton layer and a shape check of its own to every generator.
13828
- * - `computeDirectionalLightMatrix` (`lib/shadow/shadow-base.js` 54-55) fits the shadow frustum
13829
- * from the light's **own** `direction` and `position`, not from its world matrix, while the
13830
- * shader reads the world matrix. The two only agree when the light has no parent and its own
13831
- * vectors hold the world pose, which is what `syncLightWorldPose` in `./light.ts` writes and why
13832
- * this adapter parents no light. Nothing extra is needed here: a posed light casts where it
13833
- * shades.
13834
- */
13835
- /**
13836
- * The Babylon Lite shadow generator a `Light` owns, re-exported under an ignifx name
13837
- * (`CONSTITUTION.md` §3.4, coding standards §4).
13838
- *
13839
- * @remarks
13840
- * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
13841
- *
13842
- * @public
13843
- */
13844
- type LiteShadowGenerator = ShadowGenerator;
13845
- /**
13846
- * The shadow techniques Lite offers, in the order `docs/architecture/07-rendering.md` §2.2 lists them.
13847
- *
13848
- * @public
13849
- */
13850
- export declare const SHADOW_TECHNIQUES: readonly ["esm", "pcf", "csm"];
13851
- //#endregion
13852
- //#region src/log/console-sink.d.ts
13853
- /**
13854
- * The part of the host `console` a {@link LogSink} needs. Declaring it keeps the sink testable and
13855
- * keeps ignifx off the DOM `Console` type, which Node's console does not implement in full.
14579
+ * The part of the host `console` a {@link LogSink} needs. Declaring it keeps the sink testable and
14580
+ * keeps ignifx off the DOM `Console` type, which Node's console does not implement in full.
13856
14581
  *
13857
14582
  * @public
13858
14583
  */
@@ -15697,696 +16422,828 @@ export declare function createFontLoader(): AssetLoader<FontAsset>;
15697
16422
  */
15698
16423
  export declare function createMaterialLoader(): AssetLoader<MaterialAsset>;
15699
16424
  //#endregion
15700
- //#region src/lite/gpu/gltf.d.ts
16425
+ //#region src/render/mesh-asset.d.ts
15701
16426
  /**
15702
- * glTF half of the Babylon Lite adapter (`docs/architecture/07-rendering.md` §2.4): loading a
15703
- * `.glb` into an asset container, and instantiating that container under an entity node.
15704
- *
15705
- * Everything here is `@internal`. `loadGltf` uploads vertex buffers and textures, so the module is
15706
- * GPU-only.
15707
- *
15708
- * ## What a container holds (verified against `@babylonjs/lite@1.27.0`)
15709
- *
15710
- * `loadGltf(engine, source)` (`index.d.ts` 6821) — reached through the dynamically imported
15711
- * `./gltf-source.ts`, so that a game which loads no model carries no glTF parser — takes a URL, an
15712
- * `ArrayBuffer`, or a `Blob` and
15713
- * resolves to an `AssetContainer` (`index.d.ts` 653) whose `entities` is `[rootTransformNode]` for
15714
- * glTF. The ignifx asset layer fetches the bytes itself — that is where progress reporting and
15715
- * `AbortSignal` support live (`docs/architecture/05-assets-and-loading.md`) — and hands Lite an
15716
- * `ArrayBuffer`, so this adapter never fetches.
15717
- *
15718
- * ## Animation groups are stripped, not ticked
15719
- *
15720
- * `addToScene` pushes a container's `animationGroups` onto the scene and installs a before-render
15721
- * hook that calls `tickAnimation` for each one (`lib/scene/scene-core.js`). ADR-0003 says ignifx
15722
- * owns time, so {@link takeAnimationGroups} removes them from the container *before* it is added:
15723
- * Lite then registers no hook, and ignifx's animation system advances the clips itself.
15724
- *
15725
- * ## Instancing
15726
- *
15727
- * `cloneTransformNode` on the container root deep-clones the transform hierarchy while every mesh
15728
- * in it shares the original's `_gpu` wrapper and bumps its reference count
15729
- * (`lib/scene/transform-node.js`) — so N instances of a model upload one copy of the geometry. Lights
15730
- * inside the subtree are shallow-copied as plain objects rather than cloned; glTF cameras are only
15731
- * present at all when `enableGltfCameras()` ran before the load.
16427
+ * Mesh templates share geometry with renderer clones (ADR-0002).
16428
+ * Factories register a loaded handle with one caller-owned hold; release it when no longer needed.
16429
+ * Existing clones survive collection, but a disposed template cannot make new clones.
16430
+ * Headless mesh assets keep component state without GPU geometry.
15732
16431
  */
15733
16432
  /**
15734
- * The Babylon Lite asset container a `ModelAsset` holds, re-exported under an ignifx name
15735
- * (`CONSTITUTION.md` §3.4, coding standards §4).
15736
- *
15737
- * @remarks
15738
- * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
16433
+ * The asset type primitives are registered under.
15739
16434
  *
15740
16435
  * @public
15741
16436
  */
15742
- type LiteAssetContainer = AssetContainer;
16437
+ export declare const MESH_ASSET_TYPE = "mesh";
15743
16438
  /**
15744
- * A Babylon Lite animation clip, re-exported under an ignifx name. `Model.animations` hands these
15745
- * to `@ignifx/3d`'s animator, which owns advancement (ADR-0003).
15746
- *
15747
- * @remarks
15748
- * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
16439
+ * How {@link MeshAsset.box} sizes its box, in metres. Give `size` for a cube, or the three
16440
+ * dimensions.
15749
16441
  *
15750
- * @beta
16442
+ * @public
15751
16443
  */
15752
- type LiteAnimationGroup = AnimationGroup;
16444
+ interface BoxMeshOptions {
16445
+ /** Edge length on every axis. */
16446
+ readonly size?: number;
16447
+ /** Size along X, overriding `size`. */
16448
+ readonly width?: number;
16449
+ /** Size along Y, overriding `size`. */
16450
+ readonly height?: number;
16451
+ /** Size along Z, overriding `size`. */
16452
+ readonly depth?: number;
16453
+ }
15753
16454
  /**
15754
- * A Babylon Lite skeleton, re-exported under an ignifx name. Present on a container only when
15755
- * `enableBoneControl()` ran before the load (`index.d.ts` 653).
15756
- *
15757
- * @remarks
15758
- * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
16455
+ * How {@link MeshAsset.sphere} tessellates its sphere.
15759
16456
  *
15760
- * @beta
16457
+ * @public
15761
16458
  */
15762
- type LiteSkeleton = Skeleton;
15763
- //#endregion
15764
- //#region src/render/model-asset.d.ts
16459
+ interface SphereMeshOptions {
16460
+ /** Diameter on every axis, in metres. Lite defaults to 1. */
16461
+ readonly diameter?: number;
16462
+ /** Ring count; higher is smoother. Lite defaults to 32. */
16463
+ readonly segments?: number;
16464
+ }
15765
16465
  /**
15766
- * `ModelAsset` (`docs/architecture/05-assets-and-loading.md` §5 and §6,
15767
- * `07-rendering.md` §2.4): the loaded glTF container a `Model` component instantiates.
15768
- *
15769
- * ## The container is a template, not a scene member
15770
- *
15771
- * `loadGltf` resolves to an `AssetContainer` whose `entities` is `[rootTransformNode]`
15772
- * (`index.d.ts` 653). ignifx never adds that container to a scene. Each `Model` clones it instead
15773
- * (`cloneTransformNode`), which deep-copies the transform hierarchy while every mesh shares the
15774
- * original's GPU buffers under a reference count — so ten instances of a model upload one copy of
15775
- * the geometry (`src/lite/gpu/gltf.ts`). Keeping the container out of the scene is also what makes
15776
- * the first instance cost the same as the tenth, and what lets the asset outlive any one of them.
15777
- *
15778
- * ## Animation groups are taken, not ticked
16466
+ * How {@link MeshAsset.plane} sizes its quad, which lies in the XY plane facing `-Z`.
15779
16467
  *
15780
- * `addToScene` would register a container's `animationGroups` with Lite's own animation manager and
15781
- * install a before-render hook for them. ADR-0003 says ignifx owns every clock, so the loader
15782
- * removes them from the container the moment it is loaded and the asset keeps them
15783
- * ({@link ModelAsset.animations}). Core exposes them and advances nothing; `@ignifx/3d`'s
15784
- * `Animator` is what plays them.
16468
+ * @public
16469
+ */
16470
+ interface PlaneMeshOptions {
16471
+ /** Edge length on both axes, in metres. */
16472
+ readonly size?: number;
16473
+ /** Width, overriding `size`. */
16474
+ readonly width?: number;
16475
+ /** Height, overriding `size`. */
16476
+ readonly height?: number;
16477
+ }
16478
+ /**
16479
+ * How {@link MeshAsset.ground} sizes and subdivides its grid, which lies in the XZ plane facing
16480
+ * `+Y`.
15785
16481
  *
15786
- * ## Instance counting
16482
+ * @public
16483
+ */
16484
+ interface GroundMeshOptions {
16485
+ /** Size along X, in metres. */
16486
+ readonly width?: number;
16487
+ /** Size along Z, in metres. */
16488
+ readonly height?: number;
16489
+ /** Quads per side. */
16490
+ readonly subdivisions?: number;
16491
+ /** UV multiplier, for tiling a texture across the grid. */
16492
+ readonly uvScale?: readonly [number, number];
16493
+ }
16494
+ /**
16495
+ * How {@link MeshAsset.cylinder} sizes its cylinder, which stands along Y.
15787
16496
  *
15788
- * Instances are counted so the template's GPU resources live until the last instance and the asset
15789
- * handle are gone (`05-assets-and-loading.md` §6). {@link ModelAsset.retainInstance} and
15790
- * {@link ModelAsset.releaseInstance} are that counter; `Model` calls them, and
15791
- * {@link ModelAsset.instanceCount} is what a test asserts on.
16497
+ * @public
16498
+ */
16499
+ interface CylinderMeshOptions {
16500
+ /** Height along Y, in metres. */
16501
+ readonly height?: number;
16502
+ /** Diameter of both ends. */
16503
+ readonly diameter?: number;
16504
+ /** Diameter of the top cap, overriding `diameter` — a cone is `diameterTop: 0`. */
16505
+ readonly diameterTop?: number;
16506
+ /** Diameter of the bottom cap, overriding `diameter`. */
16507
+ readonly diameterBottom?: number;
16508
+ /** Radial segment count. */
16509
+ readonly tessellation?: number;
16510
+ }
16511
+ /**
16512
+ * How {@link MeshAsset.capsule} sizes its capsule, which stands along Y.
15792
16513
  *
15793
- * ## Headless
16514
+ * @remarks
16515
+ * `height` is the **total** height including both caps, the same convention `@ignifx/physics` uses
16516
+ * for a capsule collider, so one pair of numbers describes both.
15794
16517
  *
15795
- * `loadGltf` throws a `TypeError` under the null engine — it reaches for `engine._device` while
15796
- * uploading (ADR-0002 Validation) — so a headless load skips it entirely and produces an asset with
15797
- * `lite.container === null`. A `Model` that holds one keeps its fields, reports an empty `nodes`
15798
- * map, and touches no scene (`07-rendering.md` §6).
16518
+ * @public
15799
16519
  */
16520
+ interface CapsuleMeshOptions {
16521
+ /** Total height including both caps, in metres. */
16522
+ readonly height?: number;
16523
+ /** Radius of the body and the caps. */
16524
+ readonly radius?: number;
16525
+ /** Radial segment count. */
16526
+ readonly tessellation?: number;
16527
+ }
15800
16528
  /**
15801
- * The asset type models are registered under.
16529
+ * How {@link MeshAsset.torus} sizes its ring, which lies in the XZ plane.
15802
16530
  *
15803
16531
  * @public
15804
16532
  */
15805
- export declare const MODEL_ASSET_TYPE = "model";
16533
+ interface TorusMeshOptions {
16534
+ /** Outer diameter, in metres. */
16535
+ readonly diameter?: number;
16536
+ /** Tube thickness, in metres. */
16537
+ readonly thickness?: number;
16538
+ /** Segment count around the ring. */
16539
+ readonly tessellation?: number;
16540
+ }
15806
16541
  /**
15807
- * The address suffixes that select the model loader.
16542
+ * The primitive shapes a `MeshAsset` factory and a `.mesh.json` file can build.
15808
16543
  *
15809
16544
  * @public
15810
16545
  */
15811
- export declare const MODEL_FILE_EXTENSIONS: readonly string[];
16546
+ export declare const MESH_PRIMITIVES: readonly ["box", "sphere", "plane", "ground", "cylinder", "capsule", "torus"];
15812
16547
  /**
15813
- * The Babylon Lite objects a {@link ModelAsset} owns. Unstable escape hatch
15814
- * (`docs/architecture/00-overview.md` §3).
16548
+ * One of {@link MESH_PRIMITIVES}.
15815
16549
  *
15816
16550
  * @public
15817
16551
  */
15818
- interface ModelAssetLiteHandles {
15819
- /** The template container, or `null` under a headless app. */
15820
- readonly container: LiteAssetContainer | null;
15821
- }
16552
+ type MeshPrimitive = (typeof MESH_PRIMITIVES)[number];
15822
16553
  /**
15823
- * One instantiated copy of a model, as a `Model` component holds it.
16554
+ * A primitive and the options its factory takes: what a `.mesh.json` file declares.
15824
16555
  *
15825
16556
  * @public
15826
16557
  */
15827
- interface ModelInstantiation {
15828
- /** The cloned container root, parented under the entity's node. */
15829
- readonly root: LiteSceneNode;
15830
- /** Every named node in the clone, keyed by its glTF node name. */
15831
- readonly nodes: ReadonlyMap<string, LiteSceneNode>;
15832
- }
16558
+ type MeshPrimitiveDefinition = {
16559
+ readonly primitive: "box";
16560
+ readonly options: BoxMeshOptions;
16561
+ } | {
16562
+ readonly primitive: "sphere";
16563
+ readonly options: SphereMeshOptions;
16564
+ } | {
16565
+ readonly primitive: "plane";
16566
+ readonly options: PlaneMeshOptions;
16567
+ } | {
16568
+ readonly primitive: "ground";
16569
+ readonly options: GroundMeshOptions;
16570
+ } | {
16571
+ readonly primitive: "cylinder";
16572
+ readonly options: CylinderMeshOptions;
16573
+ } | {
16574
+ readonly primitive: "capsule";
16575
+ readonly options: CapsuleMeshOptions;
16576
+ } | {
16577
+ readonly primitive: "torus";
16578
+ readonly options: TorusMeshOptions;
16579
+ };
15833
16580
  /**
15834
- * A loaded glTF or GLB file (`docs/architecture/05-assets-and-loading.md` §5).
16581
+ * Raw vertex data for {@link MeshAsset.fromData}.
15835
16582
  *
15836
- * @example
15837
- * ```ts
15838
- * const hero = await app.assets.loadAsync<ModelAsset>("models/hero.glb");
15839
- * hero.value.animations.map((clip) => clip.name);
15840
- * ```
16583
+ * @remarks
16584
+ * Lite keeps references to these arrays rather than copying them — they are what its CPU ray pick
16585
+ * and its bounds read (`lib/mesh/mesh-factories.js`). Mutating one behind Lite's back changes what
16586
+ * a pick reports without changing what the GPU draws; the sanctioned way to change geometry after
16587
+ * the fact is {@link MeshAsset.updatePositions} and its three siblings, which re-upload, keep this
16588
+ * copy in step, and re-fit the bounds.
15841
16589
  *
15842
16590
  * @public
15843
16591
  */
15844
- export declare class ModelAsset {
15845
- #private;
15846
- /** The type name the asset service registers models under. */
15847
- static assetType: string;
15848
- /** The address the model was loaded from. */
15849
- readonly address: string;
16592
+ interface MeshGeometryData {
16593
+ /** Three floats per vertex. */
16594
+ readonly positions: Float32Array;
16595
+ /** Three floats per vertex, one normal each. */
16596
+ readonly normals: Float32Array;
16597
+ /** Three indices per triangle. */
16598
+ readonly indices: Uint32Array;
16599
+ /** Two floats per vertex, or omitted for a mesh with no texture coordinates. */
16600
+ readonly uvs?: Float32Array;
15850
16601
  /**
15851
- * The clips the file declared, stripped from the container so Lite never ticks them.
15852
- *
15853
- * @remarks
15854
- * Unstable: these are Lite's own animation groups, handed on to `@ignifx/3d`'s `Animator`, and
15855
- * they are excluded from the stability guarantees of `CONSTITUTION.md` Article IV. To core they
15856
- * are read-only metadata: nothing here advances or re-binds them.
16602
+ * Two floats per vertex for the second UV set (`uv2` in a shader), or omitted. Lightmaps, baked
16603
+ * ambient occlusion, and the parent-LOD height a terrain morph reads all ride here.
16604
+ */
16605
+ readonly uvs2?: Float32Array;
16606
+ /** Four floats per vertex — `xyz` plus a handedness `w` — or omitted. A normal map needs them. */
16607
+ readonly tangents?: Float32Array;
16608
+ /**
16609
+ * Four floats per vertex, linear RGBA, or omitted. A material has to be one that reads the colour
16610
+ * attribute; set `hasVertexAlpha` on the Lite mesh if the alpha is meant to blend.
16611
+ */
16612
+ readonly colors?: Float32Array;
16613
+ }
16614
+ /**
16615
+ * The Babylon Lite objects a {@link MeshAsset} owns. Unstable escape hatch
16616
+ * (`docs/architecture/00-overview.md` §3).
16617
+ *
16618
+ * @public
16619
+ */
16620
+ interface MeshAssetLiteHandles {
16621
+ /** The template mesh, or `null` under a headless app, which uploads no geometry. */
16622
+ readonly mesh: LiteMesh | null;
16623
+ }
16624
+ /**
16625
+ * A geometry template a `MeshRenderer` draws (`docs/architecture/07-rendering.md` §2.3).
16626
+ *
16627
+ * @remarks
16628
+ * Build one with a primitive factory or {@link MeshAsset.fromData}; each returns the handle the
16629
+ * `MeshRenderer.mesh` field takes. A `.mesh.json` file loads the same primitives by address
16630
+ * (`app.assets.load("meshes/crate.mesh.json")`), so a scene file can name one. A glTF mesh
16631
+ * arrives as part of a `ModelAsset` instead — a glTF is a tree of meshes, materials, and
16632
+ * animations, not one buffer.
16633
+ *
16634
+ * @example
16635
+ * ```ts
16636
+ * const box = MeshAsset.box(app, { size: 2 }); // one reference, owned by this code
16637
+ * const cube = app.world.createEntity("Cube");
16638
+ * cube.addComponent(MeshRenderer, { mesh: box }); // the field takes no reference
16639
+ * // Once nothing draws the box any more:
16640
+ * box.release();
16641
+ * ```
16642
+ *
16643
+ * @public
16644
+ */
16645
+ export declare class MeshAsset {
16646
+ #private;
16647
+ /** The type name the asset service registers meshes under. */
16648
+ static assetType: string;
16649
+ /** A human-readable name, used in diagnostics and as the Lite mesh's name. */
16650
+ readonly name: string;
16651
+ /**
16652
+ * Wraps a template mesh. Use the static factories; the engine constructs assets.
15857
16653
  *
15858
- * @beta
16654
+ * @param name - A human-readable name.
16655
+ * @param mesh - The template, or `null` when the app is headless.
16656
+ * @param scene - The scene the template is released through, or `null` when there is nothing to
16657
+ * release.
16658
+ * @param geometry - The vertex arrays the asset was built from, when it came from
16659
+ * {@link MeshAsset.fromData}; `null` for a primitive, whose arrays Lite generated and never
16660
+ * handed back. It is what makes the `update*` methods legal.
16661
+ * @param engine - The engine an update writes through, or `null` under a headless app.
16662
+ *
16663
+ * @internal
15859
16664
  */
15860
- readonly animations: readonly LiteAnimationGroup[];
16665
+ constructor(name: string, mesh: LiteMesh | null, scene: LiteScene | null, geometry?: MeshGeometryData | null, engine?: LiteEngine | null);
15861
16666
  /**
15862
- * The skeletons the file declared. Empty unless the `boneControl` rendering feature was on before
15863
- * the load, because Lite builds them only then (`index.d.ts` 653).
16667
+ * The Babylon Lite objects the asset owns. Unstable escape hatch
16668
+ * (`docs/architecture/00-overview.md` §3).
15864
16669
  *
15865
- * @beta
16670
+ * @returns The template mesh, or `null` under a headless app.
15866
16671
  */
15867
- readonly skeletons: readonly LiteSkeleton[];
16672
+ get lite(): MeshAssetLiteHandles;
15868
16673
  /**
15869
- * Wraps a loaded container. The `model` loader constructs these.
16674
+ * Whether the template's GPU buffers have been released.
15870
16675
  *
15871
- * @param address - The address it was loaded from.
15872
- * @param container - The template container, or `null` when the app is headless.
15873
- * @param animations - The clips taken off the container.
15874
- * @param skeletons - The skeletons the loader found.
15875
- * @param scene - The scene the container is released through, or `null` when headless.
16676
+ * @returns `true` once {@link MeshAsset.dispose} has run.
16677
+ */
16678
+ get isDisposed(): boolean;
16679
+ /**
16680
+ * How many vertices the geometry has.
15876
16681
  *
15877
- * @internal
16682
+ * @remarks
16683
+ * Known for a mesh built with {@link MeshAsset.fromData} — headless included — and `0` for a
16684
+ * primitive: Lite generates a primitive's arrays internally and 1.27.0's `Mesh` exposes no vertex
16685
+ * count, only the opaque `MeshGPU` handle it says a user never touches (`index.d.ts` 7230).
16686
+ *
16687
+ * @returns The vertex count, or `0`.
15878
16688
  */
15879
- constructor(address: string, container: LiteAssetContainer | null, animations: readonly LiteAnimationGroup[], skeletons: readonly LiteSkeleton[], scene: LiteScene | null);
16689
+ get vertexCount(): number;
15880
16690
  /**
15881
- * The Babylon Lite objects the asset owns. Unstable escape hatch.
16691
+ * How many indices the geometry has — three per triangle.
15882
16692
  *
15883
- * @returns The template container, or `null` under a headless app.
16693
+ * @returns The index count, or `0`; see {@link MeshAsset.vertexCount}.
15884
16694
  */
15885
- get lite(): ModelAssetLiteHandles;
16695
+ get indexCount(): number;
15886
16696
  /**
15887
- * How many `Model` components currently hold a copy of this template.
16697
+ * Re-uploads vertex positions and re-fits the bounds.
15888
16698
  *
15889
- * @returns The live instance count.
16699
+ * @remarks
16700
+ * Only a mesh from {@link MeshAsset.fromData} can be updated, and only while nothing has cloned it:
16701
+ * Lite refuses to write a vertex buffer with more than one owner, and a `MeshRenderer` clone is a
16702
+ * second owner.
16703
+ *
16704
+ * Lite's `updateMeshPositions` writes the GPU buffer and stops there, so this also copies the range
16705
+ * into the asset's own position array — the one Lite retained and CPU picking reads — and rewrites
16706
+ * the bounds from the whole of it, `O(vertexCount)` per call. Passing the asset's own array skips
16707
+ * the copy.
16708
+ *
16709
+ * @param data - Three floats per vertex, read from index 0.
16710
+ * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16711
+ * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16712
+ * @throws IgnifxError with code `IGX-0702` when the mesh did not come from
16713
+ * {@link MeshAsset.fromData}, or has been disposed.
16714
+ * @throws IgnifxError with code `IGX-0725` when the range falls outside the mesh or `data` is too
16715
+ * short for it.
16716
+ *
16717
+ * @example
16718
+ * ```ts
16719
+ * const grid = MeshAsset.fromData(app, "grid", { positions, normals, indices });
16720
+ * positions[1] += 0.5;
16721
+ * grid.value.updatePositions(positions);
16722
+ * ```
15890
16723
  */
15891
- get instanceCount(): number;
16724
+ updatePositions(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
15892
16725
  /**
15893
- * Clones the template under an entity's node.
16726
+ * Re-uploads vertex normals.
15894
16727
  *
15895
- * @param parent - The entity's transform node, or `null` for world space.
15896
- * @returns The cloned root and its named nodes, or `null` when there is nothing to clone — a
15897
- * headless app, or a file that declared only lights.
16728
+ * @remarks
16729
+ * The same rules as {@link MeshAsset.updatePositions}, minus the bounds: a normal cannot move a
16730
+ * bounding box. The range is copied into the asset's own normal array so that a later
16731
+ * `updatePositions` sees a consistent mesh.
16732
+ *
16733
+ * @param data - Three floats per vertex.
16734
+ * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16735
+ * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16736
+ * @throws IgnifxError with code `IGX-0702` or `IGX-0725`; see
16737
+ * {@link MeshAsset.updatePositions}.
15898
16738
  */
15899
- instantiate(parent: LiteSceneNode | null): ModelInstantiation | null;
15900
- /** Records that one more `Model` holds a copy. */
15901
- retainInstance(): void;
15902
- /** Records that one fewer `Model` holds a copy. Releasing below zero is a no-op. */
15903
- releaseInstance(): void;
16739
+ updateNormals(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
15904
16740
  /**
15905
- * Releases the template's GPU resources.
16741
+ * Re-uploads texture coordinates.
15906
16742
  *
15907
16743
  * @remarks
15908
- * The container was never added to a scene, so the round trip `removeFromScene` needs is the same
15909
- * one `MeshAsset.dispose` performs: this hands it to the scene and takes it straight back out,
15910
- * which drops its share of every buffer. Clones still in a scene keep theirs. Calling it twice is
15911
- * a no-op, and it is a no-op under a headless app.
16744
+ * Lite makes the upload a **no-op** when the mesh was created without UVs, rather than an error,
16745
+ * so a mesh whose `MeshGeometryData` named none silently ignores this. The range check still runs.
16746
+ *
16747
+ * @param data - Two floats per vertex.
16748
+ * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16749
+ * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16750
+ * @throws IgnifxError with code `IGX-0702` or `IGX-0725`; see
16751
+ * {@link MeshAsset.updatePositions}.
16752
+ */
16753
+ updateUvs(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
16754
+ /**
16755
+ * Re-uploads vertex colours.
16756
+ *
16757
+ * @remarks
16758
+ * Four floats per vertex, linear RGBA. A no-op on the GPU when the mesh was created without
16759
+ * colours, exactly as {@link MeshAsset.updateUvs} is.
16760
+ *
16761
+ * @param data - Four floats per vertex.
16762
+ * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16763
+ * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16764
+ * @throws IgnifxError with code `IGX-0702` or `IGX-0725`; see
16765
+ * {@link MeshAsset.updatePositions}.
16766
+ */
16767
+ updateColors(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
16768
+ /**
16769
+ * Releases the template's GPU buffers.
16770
+ *
16771
+ * @remarks
16772
+ * Lite exports no mesh disposer: a mesh's buffers are freed when it leaves its last scene, so the
16773
+ * adapter adds the template to a scene and takes it straight out again
16774
+ * (`src/lite/gpu/mesh.ts`). Clones still in a scene keep the shared buffers alive; what the
16775
+ * template loses is the ability to be cloned again. Calling it twice is a no-op, and it is a
16776
+ * no-op under a headless app, which has no buffers.
15912
16777
  */
15913
16778
  dispose(): void;
15914
16779
  /** Releases the template when the asset leaves a `using` block. */
15915
16780
  [Symbol.dispose](): void;
16781
+ /**
16782
+ * Creates a box template and publishes it.
16783
+ *
16784
+ * @param app - The app whose engine uploads the geometry and whose asset service holds the handle.
16785
+ * @param options - A uniform `size`, or per-axis dimensions.
16786
+ * @returns The handle, with one holder — the caller.
16787
+ *
16788
+ * @example
16789
+ * ```ts
16790
+ * const box = MeshAsset.box(app, { width: 2, height: 1, depth: 3 });
16791
+ * ```
16792
+ */
16793
+ static box(app: App, options?: BoxMeshOptions): AssetHandle<MeshAsset>;
16794
+ /**
16795
+ * Creates a sphere template and publishes it.
16796
+ *
16797
+ * @param app - The app that owns the engine and the asset service.
16798
+ * @param options - Diameter and ring count.
16799
+ * @returns The handle, with one holder.
16800
+ */
16801
+ static sphere(app: App, options?: SphereMeshOptions): AssetHandle<MeshAsset>;
16802
+ /**
16803
+ * Creates a quad template in the XY plane and publishes it.
16804
+ *
16805
+ * @param app - The app that owns the engine and the asset service.
16806
+ * @param options - A uniform `size`, or width and height.
16807
+ * @returns The handle, with one holder.
16808
+ */
16809
+ static plane(app: App, options?: PlaneMeshOptions): AssetHandle<MeshAsset>;
16810
+ /**
16811
+ * Creates a subdivided grid in the XZ plane and publishes it.
16812
+ *
16813
+ * @param app - The app that owns the engine and the asset service.
16814
+ * @param options - Width, depth, subdivisions, and UV scale.
16815
+ * @returns The handle, with one holder.
16816
+ */
16817
+ static ground(app: App, options?: GroundMeshOptions): AssetHandle<MeshAsset>;
16818
+ /**
16819
+ * Creates a cylinder template standing along Y and publishes it.
16820
+ *
16821
+ * @param app - The app that owns the engine and the asset service.
16822
+ * @param options - Height, diameters, and tessellation.
16823
+ * @returns The handle, with one holder.
16824
+ */
16825
+ static cylinder(app: App, options?: CylinderMeshOptions): AssetHandle<MeshAsset>;
16826
+ /**
16827
+ * Creates a capsule template standing along Y and publishes it.
16828
+ *
16829
+ * @param app - The app that owns the engine and the asset service.
16830
+ * @param options - Total height, radius, and tessellation.
16831
+ * @returns The handle, with one holder.
16832
+ */
16833
+ static capsule(app: App, options?: CapsuleMeshOptions): AssetHandle<MeshAsset>;
16834
+ /**
16835
+ * Creates a torus template in the XZ plane and publishes it.
16836
+ *
16837
+ * @param app - The app that owns the engine and the asset service.
16838
+ * @param options - Diameter, thickness, and tessellation.
16839
+ * @returns The handle, with one holder.
16840
+ */
16841
+ static torus(app: App, options?: TorusMeshOptions): AssetHandle<MeshAsset>;
16842
+ /**
16843
+ * Creates a template from raw vertex data and publishes it.
16844
+ *
16845
+ * @param app - The app that owns the engine and the asset service.
16846
+ * @param name - A human-readable name.
16847
+ * @param data - Positions, normals, indices, and any of the four optional attributes. Lite keeps
16848
+ * references to the arrays; a caller that means to edit them afterwards does so through the
16849
+ * `update*` methods, which keep Lite's own copy and its bounds in step.
16850
+ * @returns The handle, with one holder.
16851
+ *
16852
+ * @example
16853
+ * ```ts
16854
+ * const triangle = MeshAsset.fromData(app, "triangle", {
16855
+ * positions: Float32Array.from([0, 0, 0, 1, 0, 0, 0, 1, 0]),
16856
+ * normals: Float32Array.from([0, 0, -1, 0, 0, -1, 0, 0, -1]),
16857
+ * indices: Uint32Array.from([0, 1, 2]),
16858
+ * });
16859
+ * ```
16860
+ */
16861
+ static fromData(app: App, name: string, data: MeshGeometryData): AssetHandle<MeshAsset>;
15916
16862
  }
15917
16863
  //#endregion
15918
- //#region src/render/loaders/model-loader.d.ts
16864
+ //#region src/render/loaders/mesh-loader.d.ts
15919
16865
  /**
15920
- * The `model` asset loader (`docs/architecture/05-assets-and-loading.md` §5).
15921
- *
15922
- * ## Bytes, not a URL
15923
- *
15924
- * `loadGltf` accepts a URL, an `ArrayBuffer`, or a `Blob`. ignifx hands it an `ArrayBuffer` fetched
15925
- * through `ctx.fetchBytes`, because that is where progress reporting, `AbortSignal` support, the
15926
- * priority queue, and the retry policy live (§5). A `.glb` is one file, so this is lossless.
15927
- *
15928
- * A `.gltf` with **external** buffers and images is the one case where it is not: Lite would have to
15929
- * resolve those relative URLs itself, which it can only do when it did the fetching. This loader
15930
- * loads the container from bytes either way and therefore supports self-contained `.gltf` files and
15931
- * `.glb`; a `.gltf` with siblings fails inside Lite and surfaces as `IGX-0505`. `.glb` is what the
15932
- * asset pipeline produces, and the fix — passing the URL through for that one shape — is a
15933
- * three-line change whenever a project needs it.
15934
- *
15935
- * ## Headless
16866
+ * Builds the `mesh` loader: `.mesh.json` to `MeshAsset` (ADR-0029).
15936
16867
  *
15937
- * `loadGltf` throws a `TypeError` under the null engine: it uploads while parsing and reaches for
15938
- * `engine._device` (ADR-0002 Validation). So a headless load skips it entirely and produces an
15939
- * asset with no container — the `gpu: null` shape §5 requires — rather than failing. The bytes are
15940
- * still fetched, so a headless test still exercises the address, the manifest, and the byte
15941
- * counters.
15942
- */
15943
- /**
15944
- * Builds the loader for `.glb` and `.gltf` addresses.
16868
+ * @remarks
16869
+ * The file names a primitive and its options, and the loader builds it exactly as the matching
16870
+ * `MeshAsset` factory would. The mesh is named after the file's `name`, or its address. A headless
16871
+ * app builds no GPU geometry. A file that is not a mesh file fails the load with `IGX-0709`, a
16872
+ * format version other than 1 with `IGX-0603`, and an unknown primitive or a bad option with
16873
+ * `IGX-0507`. The same `mesh` type still holds the in-memory meshes the factories publish; the
16874
+ * loader's `unload` frees both kinds.
15945
16875
  *
15946
16876
  * @returns The loader to register with `ctx.registerAssetLoader`.
15947
16877
  *
15948
16878
  * @example
15949
16879
  * ```ts
15950
- * ctx.registerAssetLoader(createModelLoader());
16880
+ * ctx.registerAssetLoader(createMeshLoader());
15951
16881
  * ```
15952
16882
  *
15953
16883
  * @public
15954
16884
  */
15955
- export declare function createModelLoader(): AssetLoader<ModelAsset>;
16885
+ export declare function createMeshLoader(): AssetLoader<MeshAsset>;
15956
16886
  //#endregion
15957
- //#region src/render/loaders/texture-loader.d.ts
16887
+ //#region src/lite/gpu/gltf.d.ts
15958
16888
  /**
15959
- * The `texture` asset loader (`docs/architecture/05-assets-and-loading.md` §5).
16889
+ * glTF half of the Babylon Lite adapter (`docs/architecture/07-rendering.md` §2.4): loading a
16890
+ * `.glb` into an asset container, and instantiating that container under an entity node.
15960
16891
  *
15961
- * ## Lite fetches the bytes, not ignifx
16892
+ * Everything here is `@internal`. `loadGltf` uploads vertex buffers and textures, so the module is
16893
+ * GPU-only.
15962
16894
  *
15963
- * Every other GPU loader here reads through `ctx.fetchBytes`, which is what gives it progress,
15964
- * cancellation, and retries. A texture cannot: `loadTexture2D` takes a **URL** and decodes it with
15965
- * `createImageBitmap`, which is the browser's own hardware-accelerated decode path
15966
- * (`src/lite/gpu/texture.ts`). Handing it bytes would mean decoding a PNG in JavaScript. So the
15967
- * loader hands Lite `ctx.url` and reports its own coarse progress instead, and a texture's
15968
- * `AbortSignal` stops the *request* rather than the fetch. The trade is deliberate and it is the
15969
- * one place §5's "the three `fetch*` methods are the only network paths" does not hold; the
15970
- * alternative is worse.
16895
+ * ## What a container holds (verified against `@babylonjs/lite@1.27.0`)
15971
16896
  *
15972
- * ## Options come from the sidecar
16897
+ * `loadGltf(engine, source)` (`index.d.ts` 6821) — reached through the dynamically imported
16898
+ * `./gltf-source.ts`, so that a game which loads no model carries no glTF parser — takes a URL, an
16899
+ * `ArrayBuffer`, or a `Blob` and
16900
+ * resolves to an `AssetContainer` (`index.d.ts` 653) whose `entities` is `[rootTransformNode]` for
16901
+ * glTF. The ignifx asset layer fetches the bytes itself — that is where progress reporting and
16902
+ * `AbortSignal` support live (`docs/architecture/05-assets-and-loading.md`) — and hands Lite an
16903
+ * `ArrayBuffer`, so this adapter never fetches.
15973
16904
  *
15974
- * `.meta.json` sidecars carry per-asset import options (§7), the build copies them into the
15975
- * manifest entry, and `ctx.meta` is how a loader reads its own block. sRGB is the one that matters:
15976
- * a base-colour or emissive texture wants it, and a normal, ORM, or data map must not have it.
15977
- */
15978
- /**
15979
- * Builds the loader for `.png`, `.jpg`, `.jpeg`, `.webp`, `.ktx2`, and `.basis` addresses.
16905
+ * ## Animation groups are stripped, not ticked
15980
16906
  *
15981
- * @returns The loader to register with `ctx.registerAssetLoader`.
16907
+ * `addToScene` pushes a container's `animationGroups` onto the scene and installs a before-render
16908
+ * hook that calls `tickAnimation` for each one (`lib/scene/scene-core.js`). ADR-0003 says ignifx
16909
+ * owns time, so {@link takeAnimationGroups} removes them from the container *before* it is added:
16910
+ * Lite then registers no hook, and ignifx's animation system advances the clips itself.
15982
16911
  *
15983
- * @example
15984
- * ```ts
15985
- * ctx.registerAssetLoader(createTextureLoader());
15986
- * ```
16912
+ * ## Instancing
15987
16913
  *
15988
- * @public
15989
- */
15990
- export declare function createTextureLoader(): AssetLoader<TextureAsset>;
15991
- //#endregion
15992
- //#region src/render/mesh-asset.d.ts
15993
- /**
15994
- * Mesh templates share geometry with renderer clones (ADR-0002).
15995
- * Factories register a loaded handle with one caller-owned hold; release it when no longer needed.
15996
- * Existing clones survive collection, but a disposed template cannot make new clones.
15997
- * Headless mesh assets keep component state without GPU geometry.
16914
+ * `cloneTransformNode` on the container root deep-clones the transform hierarchy while every mesh
16915
+ * in it shares the original's `_gpu` wrapper and bumps its reference count
16916
+ * (`lib/scene/transform-node.js`) — so N instances of a model upload one copy of the geometry. Lights
16917
+ * inside the subtree are shallow-copied as plain objects rather than cloned; glTF cameras are only
16918
+ * present at all when `enableGltfCameras()` ran before the load.
15998
16919
  */
15999
16920
  /**
16000
- * The asset type primitives are registered under.
16921
+ * The Babylon Lite asset container a `ModelAsset` holds, re-exported under an ignifx name
16922
+ * (`CONSTITUTION.md` §3.4, coding standards §4).
16001
16923
  *
16002
- * @public
16003
- */
16004
- export declare const MESH_ASSET_TYPE = "mesh";
16005
- /**
16006
- * How {@link MeshAsset.box} sizes its box, in metres. Give `size` for a cube, or the three
16007
- * dimensions.
16924
+ * @remarks
16925
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
16008
16926
  *
16009
16927
  * @public
16010
16928
  */
16011
- interface BoxMeshOptions {
16012
- /** Edge length on every axis. */
16013
- readonly size?: number;
16014
- /** Size along X, overriding `size`. */
16015
- readonly width?: number;
16016
- /** Size along Y, overriding `size`. */
16017
- readonly height?: number;
16018
- /** Size along Z, overriding `size`. */
16019
- readonly depth?: number;
16020
- }
16929
+ type LiteAssetContainer = AssetContainer;
16021
16930
  /**
16022
- * How {@link MeshAsset.sphere} tessellates its sphere.
16931
+ * A Babylon Lite animation clip, re-exported under an ignifx name. `Model.animations` hands these
16932
+ * to `@ignifx/3d`'s animator, which owns advancement (ADR-0003).
16023
16933
  *
16024
- * @public
16025
- */
16026
- interface SphereMeshOptions {
16027
- /** Diameter on every axis, in metres. Lite defaults to 1. */
16028
- readonly diameter?: number;
16029
- /** Ring count; higher is smoother. Lite defaults to 32. */
16030
- readonly segments?: number;
16031
- }
16032
- /**
16033
- * How {@link MeshAsset.plane} sizes its quad, which lies in the XY plane facing `-Z`.
16934
+ * @remarks
16935
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
16034
16936
  *
16035
- * @public
16937
+ * @beta
16036
16938
  */
16037
- interface PlaneMeshOptions {
16038
- /** Edge length on both axes, in metres. */
16039
- readonly size?: number;
16040
- /** Width, overriding `size`. */
16041
- readonly width?: number;
16042
- /** Height, overriding `size`. */
16043
- readonly height?: number;
16044
- }
16939
+ type LiteAnimationGroup = AnimationGroup;
16045
16940
  /**
16046
- * How {@link MeshAsset.ground} sizes and subdivides its grid, which lies in the XZ plane facing
16047
- * `+Y`.
16941
+ * A Babylon Lite skeleton, re-exported under an ignifx name. Present on a container only when
16942
+ * `enableBoneControl()` ran before the load (`index.d.ts` 653).
16048
16943
  *
16049
- * @public
16944
+ * @remarks
16945
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
16946
+ *
16947
+ * @beta
16050
16948
  */
16051
- interface GroundMeshOptions {
16052
- /** Size along X, in metres. */
16053
- readonly width?: number;
16054
- /** Size along Z, in metres. */
16055
- readonly height?: number;
16056
- /** Quads per side. */
16057
- readonly subdivisions?: number;
16058
- /** UV multiplier, for tiling a texture across the grid. */
16059
- readonly uvScale?: readonly [number, number];
16060
- }
16949
+ type LiteSkeleton = Skeleton;
16950
+ //#endregion
16951
+ //#region src/render/model-asset.d.ts
16061
16952
  /**
16062
- * How {@link MeshAsset.cylinder} sizes its cylinder, which stands along Y.
16953
+ * `ModelAsset` (`docs/architecture/05-assets-and-loading.md` §5 and §6,
16954
+ * `07-rendering.md` §2.4): the loaded glTF container a `Model` component instantiates.
16063
16955
  *
16064
- * @public
16956
+ * ## The container is a template, not a scene member
16957
+ *
16958
+ * `loadGltf` resolves to an `AssetContainer` whose `entities` is `[rootTransformNode]`
16959
+ * (`index.d.ts` 653). ignifx never adds that container to a scene. Each `Model` clones it instead
16960
+ * (`cloneTransformNode`), which deep-copies the transform hierarchy while every mesh shares the
16961
+ * original's GPU buffers under a reference count — so ten instances of a model upload one copy of
16962
+ * the geometry (`src/lite/gpu/gltf.ts`). Keeping the container out of the scene is also what makes
16963
+ * the first instance cost the same as the tenth, and what lets the asset outlive any one of them.
16964
+ *
16965
+ * ## Animation groups are taken, not ticked
16966
+ *
16967
+ * `addToScene` would register a container's `animationGroups` with Lite's own animation manager and
16968
+ * install a before-render hook for them. ADR-0003 says ignifx owns every clock, so the loader
16969
+ * removes them from the container the moment it is loaded and the asset keeps them
16970
+ * ({@link ModelAsset.animations}). Core exposes them and advances nothing; `@ignifx/3d`'s
16971
+ * `Animator` is what plays them.
16972
+ *
16973
+ * ## Instance counting
16974
+ *
16975
+ * Instances are counted so the template's GPU resources live until the last instance and the asset
16976
+ * handle are gone (`05-assets-and-loading.md` §6). {@link ModelAsset.retainInstance} and
16977
+ * {@link ModelAsset.releaseInstance} are that counter; `Model` calls them, and
16978
+ * {@link ModelAsset.instanceCount} is what a test asserts on.
16979
+ *
16980
+ * ## Headless
16981
+ *
16982
+ * `loadGltf` throws a `TypeError` under the null engine — it reaches for `engine._device` while
16983
+ * uploading (ADR-0002 Validation) — so a headless load skips it entirely and produces an asset with
16984
+ * `lite.container === null`. A `Model` that holds one keeps its fields, reports an empty `nodes`
16985
+ * map, and touches no scene (`07-rendering.md` §6).
16065
16986
  */
16066
- interface CylinderMeshOptions {
16067
- /** Height along Y, in metres. */
16068
- readonly height?: number;
16069
- /** Diameter of both ends. */
16070
- readonly diameter?: number;
16071
- /** Diameter of the top cap, overriding `diameter` — a cone is `diameterTop: 0`. */
16072
- readonly diameterTop?: number;
16073
- /** Diameter of the bottom cap, overriding `diameter`. */
16074
- readonly diameterBottom?: number;
16075
- /** Radial segment count. */
16076
- readonly tessellation?: number;
16077
- }
16078
16987
  /**
16079
- * How {@link MeshAsset.capsule} sizes its capsule, which stands along Y.
16080
- *
16081
- * @remarks
16082
- * `height` is the **total** height including both caps, the same convention `@ignifx/physics` uses
16083
- * for a capsule collider, so one pair of numbers describes both.
16988
+ * The asset type models are registered under.
16084
16989
  *
16085
16990
  * @public
16086
16991
  */
16087
- interface CapsuleMeshOptions {
16088
- /** Total height including both caps, in metres. */
16089
- readonly height?: number;
16090
- /** Radius of the body and the caps. */
16091
- readonly radius?: number;
16092
- /** Radial segment count. */
16093
- readonly tessellation?: number;
16094
- }
16992
+ export declare const MODEL_ASSET_TYPE = "model";
16095
16993
  /**
16096
- * How {@link MeshAsset.torus} sizes its ring, which lies in the XZ plane.
16994
+ * The address suffixes that select the model loader.
16097
16995
  *
16098
16996
  * @public
16099
16997
  */
16100
- interface TorusMeshOptions {
16101
- /** Outer diameter, in metres. */
16102
- readonly diameter?: number;
16103
- /** Tube thickness, in metres. */
16104
- readonly thickness?: number;
16105
- /** Segment count around the ring. */
16106
- readonly tessellation?: number;
16107
- }
16998
+ export declare const MODEL_FILE_EXTENSIONS: readonly string[];
16108
16999
  /**
16109
- * Raw vertex data for {@link MeshAsset.fromData}.
16110
- *
16111
- * @remarks
16112
- * Lite keeps references to these arrays rather than copying them — they are what its CPU ray pick
16113
- * and its bounds read (`lib/mesh/mesh-factories.js`). Mutating one behind Lite's back changes what
16114
- * a pick reports without changing what the GPU draws; the sanctioned way to change geometry after
16115
- * the fact is {@link MeshAsset.updatePositions} and its three siblings, which re-upload, keep this
16116
- * copy in step, and re-fit the bounds.
17000
+ * The Babylon Lite objects a {@link ModelAsset} owns. Unstable escape hatch
17001
+ * (`docs/architecture/00-overview.md` §3).
16117
17002
  *
16118
17003
  * @public
16119
17004
  */
16120
- interface MeshGeometryData {
16121
- /** Three floats per vertex. */
16122
- readonly positions: Float32Array;
16123
- /** Three floats per vertex, one normal each. */
16124
- readonly normals: Float32Array;
16125
- /** Three indices per triangle. */
16126
- readonly indices: Uint32Array;
16127
- /** Two floats per vertex, or omitted for a mesh with no texture coordinates. */
16128
- readonly uvs?: Float32Array;
16129
- /**
16130
- * Two floats per vertex for the second UV set (`uv2` in a shader), or omitted. Lightmaps, baked
16131
- * ambient occlusion, and the parent-LOD height a terrain morph reads all ride here.
16132
- */
16133
- readonly uvs2?: Float32Array;
16134
- /** Four floats per vertex — `xyz` plus a handedness `w` — or omitted. A normal map needs them. */
16135
- readonly tangents?: Float32Array;
16136
- /**
16137
- * Four floats per vertex, linear RGBA, or omitted. A material has to be one that reads the colour
16138
- * attribute; set `hasVertexAlpha` on the Lite mesh if the alpha is meant to blend.
16139
- */
16140
- readonly colors?: Float32Array;
17005
+ interface ModelAssetLiteHandles {
17006
+ /** The template container, or `null` under a headless app. */
17007
+ readonly container: LiteAssetContainer | null;
16141
17008
  }
16142
17009
  /**
16143
- * The Babylon Lite objects a {@link MeshAsset} owns. Unstable escape hatch
16144
- * (`docs/architecture/00-overview.md` §3).
17010
+ * One instantiated copy of a model, as a `Model` component holds it.
16145
17011
  *
16146
17012
  * @public
16147
17013
  */
16148
- interface MeshAssetLiteHandles {
16149
- /** The template mesh, or `null` under a headless app, which uploads no geometry. */
16150
- readonly mesh: LiteMesh | null;
17014
+ interface ModelInstantiation {
17015
+ /** The cloned container root, parented under the entity's node. */
17016
+ readonly root: LiteSceneNode;
17017
+ /** Every named node in the clone, keyed by its glTF node name. */
17018
+ readonly nodes: ReadonlyMap<string, LiteSceneNode>;
16151
17019
  }
16152
17020
  /**
16153
- * A geometry template a `MeshRenderer` draws (`docs/architecture/07-rendering.md` §2.3).
16154
- *
16155
- * @remarks
16156
- * Build one with a primitive factory or {@link MeshAsset.fromData}; each returns the handle the
16157
- * `MeshRenderer.mesh` field takes. A mesh that came from a file arrives as part of a `ModelAsset`
16158
- * instead — a glTF is a tree of meshes, materials, and animations, not one buffer.
17021
+ * A loaded glTF or GLB file (`docs/architecture/05-assets-and-loading.md` §5).
16159
17022
  *
16160
17023
  * @example
16161
17024
  * ```ts
16162
- * const box = MeshAsset.box(app, { size: 2 }); // one reference, owned by this code
16163
- * const cube = app.world.createEntity("Cube");
16164
- * cube.addComponent(MeshRenderer, { mesh: box }); // the field takes no reference
16165
- * // Once nothing draws the box any more:
16166
- * box.release();
17025
+ * const hero = await app.assets.loadAsync<ModelAsset>("models/hero.glb");
17026
+ * hero.value.animations.map((clip) => clip.name);
16167
17027
  * ```
16168
17028
  *
16169
17029
  * @public
16170
17030
  */
16171
- export declare class MeshAsset {
17031
+ export declare class ModelAsset {
16172
17032
  #private;
16173
- /** The type name the asset service registers meshes under. */
17033
+ /** The type name the asset service registers models under. */
16174
17034
  static assetType: string;
16175
- /** A human-readable name, used in diagnostics and as the Lite mesh's name. */
16176
- readonly name: string;
16177
- /**
16178
- * Wraps a template mesh. Use the static factories; the engine constructs assets.
16179
- *
16180
- * @param name - A human-readable name.
16181
- * @param mesh - The template, or `null` when the app is headless.
16182
- * @param scene - The scene the template is released through, or `null` when there is nothing to
16183
- * release.
16184
- * @param geometry - The vertex arrays the asset was built from, when it came from
16185
- * {@link MeshAsset.fromData}; `null` for a primitive, whose arrays Lite generated and never
16186
- * handed back. It is what makes the `update*` methods legal.
16187
- * @param engine - The engine an update writes through, or `null` under a headless app.
16188
- *
16189
- * @internal
16190
- */
16191
- constructor(name: string, mesh: LiteMesh | null, scene: LiteScene | null, geometry?: MeshGeometryData | null, engine?: LiteEngine | null);
16192
- /**
16193
- * The Babylon Lite objects the asset owns. Unstable escape hatch
16194
- * (`docs/architecture/00-overview.md` §3).
16195
- *
16196
- * @returns The template mesh, or `null` under a headless app.
16197
- */
16198
- get lite(): MeshAssetLiteHandles;
16199
- /**
16200
- * Whether the template's GPU buffers have been released.
16201
- *
16202
- * @returns `true` once {@link MeshAsset.dispose} has run.
16203
- */
16204
- get isDisposed(): boolean;
17035
+ /** The address the model was loaded from. */
17036
+ readonly address: string;
16205
17037
  /**
16206
- * How many vertices the geometry has.
17038
+ * The clips the file declared, stripped from the container so Lite never ticks them.
16207
17039
  *
16208
17040
  * @remarks
16209
- * Known for a mesh built with {@link MeshAsset.fromData} — headless included — and `0` for a
16210
- * primitive: Lite generates a primitive's arrays internally and 1.27.0's `Mesh` exposes no vertex
16211
- * count, only the opaque `MeshGPU` handle it says a user never touches (`index.d.ts` 7230).
17041
+ * Unstable: these are Lite's own animation groups, handed on to `@ignifx/3d`'s `Animator`, and
17042
+ * they are excluded from the stability guarantees of `CONSTITUTION.md` Article IV. To core they
17043
+ * are read-only metadata: nothing here advances or re-binds them.
16212
17044
  *
16213
- * @returns The vertex count, or `0`.
17045
+ * @beta
16214
17046
  */
16215
- get vertexCount(): number;
17047
+ readonly animations: readonly LiteAnimationGroup[];
16216
17048
  /**
16217
- * How many indices the geometry has — three per triangle.
17049
+ * The skeletons the file declared. Empty unless the `boneControl` rendering feature was on before
17050
+ * the load, because Lite builds them only then (`index.d.ts` 653).
16218
17051
  *
16219
- * @returns The index count, or `0`; see {@link MeshAsset.vertexCount}.
17052
+ * @beta
16220
17053
  */
16221
- get indexCount(): number;
17054
+ readonly skeletons: readonly LiteSkeleton[];
16222
17055
  /**
16223
- * Re-uploads vertex positions and re-fits the bounds.
16224
- *
16225
- * @remarks
16226
- * Only a mesh from {@link MeshAsset.fromData} can be updated, and only while nothing has cloned it:
16227
- * Lite refuses to write a vertex buffer with more than one owner, and a `MeshRenderer` clone is a
16228
- * second owner.
16229
- *
16230
- * Lite's `updateMeshPositions` writes the GPU buffer and stops there, so this also copies the range
16231
- * into the asset's own position array — the one Lite retained and CPU picking reads — and rewrites
16232
- * the bounds from the whole of it, `O(vertexCount)` per call. Passing the asset's own array skips
16233
- * the copy.
17056
+ * Wraps a loaded container. The `model` loader constructs these.
16234
17057
  *
16235
- * @param data - Three floats per vertex, read from index 0.
16236
- * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16237
- * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16238
- * @throws IgnifxError with code `IGX-0702` when the mesh did not come from
16239
- * {@link MeshAsset.fromData}, or has been disposed.
16240
- * @throws IgnifxError with code `IGX-0725` when the range falls outside the mesh or `data` is too
16241
- * short for it.
17058
+ * @param address - The address it was loaded from.
17059
+ * @param container - The template container, or `null` when the app is headless.
17060
+ * @param animations - The clips taken off the container.
17061
+ * @param skeletons - The skeletons the loader found.
17062
+ * @param scene - The scene the container is released through, or `null` when headless.
16242
17063
  *
16243
- * @example
16244
- * ```ts
16245
- * const grid = MeshAsset.fromData(app, "grid", { positions, normals, indices });
16246
- * positions[1] += 0.5;
16247
- * grid.value.updatePositions(positions);
16248
- * ```
17064
+ * @internal
16249
17065
  */
16250
- updatePositions(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
17066
+ constructor(address: string, container: LiteAssetContainer | null, animations: readonly LiteAnimationGroup[], skeletons: readonly LiteSkeleton[], scene: LiteScene | null);
16251
17067
  /**
16252
- * Re-uploads vertex normals.
16253
- *
16254
- * @remarks
16255
- * The same rules as {@link MeshAsset.updatePositions}, minus the bounds: a normal cannot move a
16256
- * bounding box. The range is copied into the asset's own normal array so that a later
16257
- * `updatePositions` sees a consistent mesh.
17068
+ * The Babylon Lite objects the asset owns. Unstable escape hatch.
16258
17069
  *
16259
- * @param data - Three floats per vertex.
16260
- * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16261
- * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16262
- * @throws IgnifxError with code `IGX-0702` or `IGX-0725`; see
16263
- * {@link MeshAsset.updatePositions}.
17070
+ * @returns The template container, or `null` under a headless app.
16264
17071
  */
16265
- updateNormals(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
17072
+ get lite(): ModelAssetLiteHandles;
16266
17073
  /**
16267
- * Re-uploads texture coordinates.
16268
- *
16269
- * @remarks
16270
- * Lite makes the upload a **no-op** when the mesh was created without UVs, rather than an error,
16271
- * so a mesh whose `MeshGeometryData` named none silently ignores this. The range check still runs.
17074
+ * How many `Model` components currently hold a copy of this template.
16272
17075
  *
16273
- * @param data - Two floats per vertex.
16274
- * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16275
- * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16276
- * @throws IgnifxError with code `IGX-0702` or `IGX-0725`; see
16277
- * {@link MeshAsset.updatePositions}.
17076
+ * @returns The live instance count.
16278
17077
  */
16279
- updateUvs(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
17078
+ get instanceCount(): number;
16280
17079
  /**
16281
- * Re-uploads vertex colours.
16282
- *
16283
- * @remarks
16284
- * Four floats per vertex, linear RGBA. A no-op on the GPU when the mesh was created without
16285
- * colours, exactly as {@link MeshAsset.updateUvs} is.
17080
+ * Clones the template under an entity's node.
16286
17081
  *
16287
- * @param data - Four floats per vertex.
16288
- * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
16289
- * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
16290
- * @throws IgnifxError with code `IGX-0702` or `IGX-0725`; see
16291
- * {@link MeshAsset.updatePositions}.
17082
+ * @param parent - The entity's transform node, or `null` for world space.
17083
+ * @returns The cloned root and its named nodes, or `null` when there is nothing to clone — a
17084
+ * headless app, or a file that declared only lights.
16292
17085
  */
16293
- updateColors(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
17086
+ instantiate(parent: LiteSceneNode | null): ModelInstantiation | null;
17087
+ /** Records that one more `Model` holds a copy. */
17088
+ retainInstance(): void;
17089
+ /** Records that one fewer `Model` holds a copy. Releasing below zero is a no-op. */
17090
+ releaseInstance(): void;
16294
17091
  /**
16295
- * Releases the template's GPU buffers.
17092
+ * Releases the template's GPU resources.
16296
17093
  *
16297
17094
  * @remarks
16298
- * Lite exports no mesh disposer: a mesh's buffers are freed when it leaves its last scene, so the
16299
- * adapter adds the template to a scene and takes it straight out again
16300
- * (`src/lite/gpu/mesh.ts`). Clones still in a scene keep the shared buffers alive; what the
16301
- * template loses is the ability to be cloned again. Calling it twice is a no-op, and it is a
16302
- * no-op under a headless app, which has no buffers.
17095
+ * The container was never added to a scene, so the round trip `removeFromScene` needs is the same
17096
+ * one `MeshAsset.dispose` performs: this hands it to the scene and takes it straight back out,
17097
+ * which drops its share of every buffer. Clones still in a scene keep theirs. Calling it twice is
17098
+ * a no-op, and it is a no-op under a headless app.
16303
17099
  */
16304
17100
  dispose(): void;
16305
17101
  /** Releases the template when the asset leaves a `using` block. */
16306
17102
  [Symbol.dispose](): void;
16307
- /**
16308
- * Creates a box template and publishes it.
16309
- *
16310
- * @param app - The app whose engine uploads the geometry and whose asset service holds the handle.
16311
- * @param options - A uniform `size`, or per-axis dimensions.
16312
- * @returns The handle, with one holder — the caller.
16313
- *
16314
- * @example
16315
- * ```ts
16316
- * const box = MeshAsset.box(app, { width: 2, height: 1, depth: 3 });
16317
- * ```
16318
- */
16319
- static box(app: App, options?: BoxMeshOptions): AssetHandle<MeshAsset>;
16320
- /**
16321
- * Creates a sphere template and publishes it.
16322
- *
16323
- * @param app - The app that owns the engine and the asset service.
16324
- * @param options - Diameter and ring count.
16325
- * @returns The handle, with one holder.
16326
- */
16327
- static sphere(app: App, options?: SphereMeshOptions): AssetHandle<MeshAsset>;
16328
- /**
16329
- * Creates a quad template in the XY plane and publishes it.
16330
- *
16331
- * @param app - The app that owns the engine and the asset service.
16332
- * @param options - A uniform `size`, or width and height.
16333
- * @returns The handle, with one holder.
16334
- */
16335
- static plane(app: App, options?: PlaneMeshOptions): AssetHandle<MeshAsset>;
16336
- /**
16337
- * Creates a subdivided grid in the XZ plane and publishes it.
16338
- *
16339
- * @param app - The app that owns the engine and the asset service.
16340
- * @param options - Width, depth, subdivisions, and UV scale.
16341
- * @returns The handle, with one holder.
16342
- */
16343
- static ground(app: App, options?: GroundMeshOptions): AssetHandle<MeshAsset>;
16344
- /**
16345
- * Creates a cylinder template standing along Y and publishes it.
16346
- *
16347
- * @param app - The app that owns the engine and the asset service.
16348
- * @param options - Height, diameters, and tessellation.
16349
- * @returns The handle, with one holder.
16350
- */
16351
- static cylinder(app: App, options?: CylinderMeshOptions): AssetHandle<MeshAsset>;
16352
- /**
16353
- * Creates a capsule template standing along Y and publishes it.
16354
- *
16355
- * @param app - The app that owns the engine and the asset service.
16356
- * @param options - Total height, radius, and tessellation.
16357
- * @returns The handle, with one holder.
16358
- */
16359
- static capsule(app: App, options?: CapsuleMeshOptions): AssetHandle<MeshAsset>;
16360
- /**
16361
- * Creates a torus template in the XZ plane and publishes it.
16362
- *
16363
- * @param app - The app that owns the engine and the asset service.
16364
- * @param options - Diameter, thickness, and tessellation.
16365
- * @returns The handle, with one holder.
16366
- */
16367
- static torus(app: App, options?: TorusMeshOptions): AssetHandle<MeshAsset>;
16368
- /**
16369
- * Creates a template from raw vertex data and publishes it.
16370
- *
16371
- * @param app - The app that owns the engine and the asset service.
16372
- * @param name - A human-readable name.
16373
- * @param data - Positions, normals, indices, and any of the four optional attributes. Lite keeps
16374
- * references to the arrays; a caller that means to edit them afterwards does so through the
16375
- * `update*` methods, which keep Lite's own copy and its bounds in step.
16376
- * @returns The handle, with one holder.
16377
- *
16378
- * @example
16379
- * ```ts
16380
- * const triangle = MeshAsset.fromData(app, "triangle", {
16381
- * positions: Float32Array.from([0, 0, 0, 1, 0, 0, 0, 1, 0]),
16382
- * normals: Float32Array.from([0, 0, -1, 0, 0, -1, 0, 0, -1]),
16383
- * indices: Uint32Array.from([0, 1, 2]),
16384
- * });
16385
- * ```
16386
- */
16387
- static fromData(app: App, name: string, data: MeshGeometryData): AssetHandle<MeshAsset>;
16388
17103
  }
16389
17104
  //#endregion
17105
+ //#region src/render/loaders/model-loader.d.ts
17106
+ /**
17107
+ * The `model` asset loader (`docs/architecture/05-assets-and-loading.md` §5).
17108
+ *
17109
+ * ## Bytes, not a URL
17110
+ *
17111
+ * `loadGltf` accepts a URL, an `ArrayBuffer`, or a `Blob`. ignifx hands it an `ArrayBuffer` fetched
17112
+ * through `ctx.fetchBytes`, because that is where progress reporting, `AbortSignal` support, the
17113
+ * priority queue, and the retry policy live (§5). A `.glb` is one file, so this is lossless.
17114
+ *
17115
+ * A `.gltf` with **external** buffers and images is the one case where it is not: Lite would have to
17116
+ * resolve those relative URLs itself, which it can only do when it did the fetching. This loader
17117
+ * loads the container from bytes either way and therefore supports self-contained `.gltf` files and
17118
+ * `.glb`; a `.gltf` with siblings fails inside Lite and surfaces as `IGX-0505`. `.glb` is what the
17119
+ * asset pipeline produces, and the fix — passing the URL through for that one shape — is a
17120
+ * three-line change whenever a project needs it.
17121
+ *
17122
+ * ## Headless
17123
+ *
17124
+ * `loadGltf` throws a `TypeError` under the null engine: it uploads while parsing and reaches for
17125
+ * `engine._device` (ADR-0002 Validation). So a headless load skips it entirely and produces an
17126
+ * asset with no container — the `gpu: null` shape §5 requires — rather than failing. The bytes are
17127
+ * still fetched, so a headless test still exercises the address, the manifest, and the byte
17128
+ * counters.
17129
+ */
17130
+ /**
17131
+ * Builds the loader for `.glb` and `.gltf` addresses.
17132
+ *
17133
+ * @returns The loader to register with `ctx.registerAssetLoader`.
17134
+ *
17135
+ * @example
17136
+ * ```ts
17137
+ * ctx.registerAssetLoader(createModelLoader());
17138
+ * ```
17139
+ *
17140
+ * @public
17141
+ */
17142
+ export declare function createModelLoader(): AssetLoader<ModelAsset>;
17143
+ //#endregion
17144
+ //#region src/render/loaders/texture-loader.d.ts
17145
+ /**
17146
+ * The `texture` asset loader (`docs/architecture/05-assets-and-loading.md` §5).
17147
+ *
17148
+ * ## Lite fetches the bytes, not ignifx
17149
+ *
17150
+ * Every other GPU loader here reads through `ctx.fetchBytes`, which is what gives it progress,
17151
+ * cancellation, and retries. A texture cannot: `loadTexture2D` takes a **URL** and decodes it with
17152
+ * `createImageBitmap`, which is the browser's own hardware-accelerated decode path
17153
+ * (`src/lite/gpu/texture.ts`). Handing it bytes would mean decoding a PNG in JavaScript. So the
17154
+ * loader hands Lite `ctx.url` and reports its own coarse progress instead, and a texture's
17155
+ * `AbortSignal` stops the *request* rather than the fetch. The trade is deliberate and it is the
17156
+ * one place §5's "the three `fetch*` methods are the only network paths" does not hold; the
17157
+ * alternative is worse.
17158
+ *
17159
+ * ## Options come from the sidecar
17160
+ *
17161
+ * `.meta.json` sidecars carry per-asset import options (§7), the build copies them into the
17162
+ * manifest entry, and `ctx.meta` is how a loader reads its own block. sRGB is the one that matters:
17163
+ * a base-colour or emissive texture wants it, and a normal, ORM, or data map must not have it.
17164
+ */
17165
+ /**
17166
+ * Builds the loader for `.png`, `.jpg`, `.jpeg`, `.webp`, `.ktx2`, and `.basis` addresses.
17167
+ *
17168
+ * @returns The loader to register with `ctx.registerAssetLoader`.
17169
+ *
17170
+ * @example
17171
+ * ```ts
17172
+ * ctx.registerAssetLoader(createTextureLoader());
17173
+ * ```
17174
+ *
17175
+ * @public
17176
+ */
17177
+ export declare function createTextureLoader(): AssetLoader<TextureAsset>;
17178
+ //#endregion
17179
+ //#region src/render/mesh-file.d.ts
17180
+ /**
17181
+ * The `.mesh.json` file format (ADR-0029): one primitive and the options its `MeshAsset` factory
17182
+ * takes, so a scene file can name a primitive by address.
17183
+ *
17184
+ * ```json
17185
+ * { "format": "ignifx.mesh", "formatVersion": 1, "primitive": "box", "options": { "size": 1 } }
17186
+ * ```
17187
+ *
17188
+ * One table, {@link MESH_PRIMITIVE_OPTIONS}, drives the runtime check and the JSON Schema, so the
17189
+ * two cannot drift apart.
17190
+ */
17191
+ /**
17192
+ * The `format` header a `.mesh.json` carries.
17193
+ *
17194
+ * @public
17195
+ */
17196
+ export declare const MESH_FILE_FORMAT = "ignifx.mesh";
17197
+ /**
17198
+ * The only `.mesh.json` `formatVersion` this build reads.
17199
+ *
17200
+ * @public
17201
+ */
17202
+ export declare const MESH_FORMAT_VERSION = 1;
17203
+ /**
17204
+ * The address suffix that selects the mesh loader.
17205
+ *
17206
+ * @public
17207
+ */
17208
+ export declare const MESH_FILE_EXTENSION = ".mesh.json";
17209
+ /**
17210
+ * What a primitive option holds: a length in metres (finite, zero or more), a segment count
17211
+ * (a whole number, one or more), or a pair of finite numbers.
17212
+ *
17213
+ * @public
17214
+ */
17215
+ type MeshOptionKind = "length" | "count" | "pair";
17216
+ /**
17217
+ * For each primitive, every option its factory's options type declares, and what it holds.
17218
+ *
17219
+ * @public
17220
+ */
17221
+ type MeshPrimitiveOptionKinds = { readonly [P in MeshPrimitive]: { readonly [K in keyof Extract<MeshPrimitiveDefinition, {
17222
+ readonly primitive: P;
17223
+ }>["options"]]-?: MeshOptionKind; }; };
17224
+ /**
17225
+ * Every option each primitive takes, and what it holds. The keys are exactly the fields of the
17226
+ * factory's options type (`BoxMeshOptions`, …); the compiler checks that.
17227
+ *
17228
+ * @public
17229
+ */
17230
+ export declare const MESH_PRIMITIVE_OPTIONS: MeshPrimitiveOptionKinds;
17231
+ /**
17232
+ * The JSON Schema `@ignifx/vite-plugin` validates `.mesh.json` files against, built from
17233
+ * {@link MESH_PRIMITIVE_OPTIONS}.
17234
+ *
17235
+ * @returns The schema document.
17236
+ *
17237
+ * @example
17238
+ * ```ts
17239
+ * // vite.config.ts
17240
+ * ignifx({ schemas: { formats: { [MESH_FILE_FORMAT]: meshFileJsonSchema() } } });
17241
+ * ```
17242
+ *
17243
+ * @public
17244
+ */
17245
+ export declare function meshFileJsonSchema(): JsonSchemaObject;
17246
+ //#endregion
16390
17247
  //#region src/render/mesh-renderer.d.ts
16391
17248
  /**
16392
17249
  * The `MeshRenderer` component (`docs/architecture/07-rendering.md` §2.3): one clone of a
@@ -17385,11 +18242,19 @@ export declare class PostProcessStack extends Component implements ComponentHook
17385
18242
  *
17386
18243
  * The harness requires every key to be a namespaced `<package>/<Name>` type id
17387
18244
  * (`scripts/lib/schema-source.ts` rejects a key with no `/`), and it groups entries onto a page by
17388
- * their `format`. A *file* format is not a component and has no type id, so the three file formats
17389
- * below are keyed `ignifx/scene-file`, `ignifx/material-file`, and `ignifx/environment-file` while
17390
- * declaring `format: "ignifx.scene"`, `"ignifx.material"`, and `"ignifx.environment"`. The wave-1
18245
+ * their `format`. A *file* format is not a component and has no type id, so the file formats
18246
+ * below are keyed `ignifx/scene-file`, `ignifx/material-file`, `ignifx/environment-file`, and
18247
+ * `ignifx/mesh-file` while declaring `format: "ignifx.scene"`, `"ignifx.material"`,
18248
+ * `"ignifx.environment"`, and `"ignifx.mesh"`. The wave-1
17391
18249
  * hand-off asked for the key `"ignifx.scene"`; that key fails the namespacing check, and the
17392
18250
  * grouping — which is what actually decides the page — comes from `format` either way.
18251
+ *
18252
+ * ## The transform
18253
+ *
18254
+ * `ignifx/Transform` is described like a component, from `transformSchema()`, though its class
18255
+ * declares no schema: it is the scene file's per-entity `transform` block. Its entry is the only one
18256
+ * that sets `builtIn` (with `allowMultiple: false` and `package: "@ignifx/core"`), so an editor
18257
+ * shows it with the components but never offers to add or remove it.
17393
18258
  */
17394
18259
  /**
17395
18260
  * Describes every component and file format this package declares, for the documentation harness.
@@ -17423,105 +18288,14 @@ export declare function describeMaterialFileFormat(): SchemaDescription;
17423
18288
  * @public
17424
18289
  */
17425
18290
  export declare function describeEnvironmentFileFormat(): SchemaDescription;
17426
- //#endregion
17427
- //#region src/serialization/load.d.ts
17428
- /**
17429
- * One recoverable problem found while a scene was being built. Nothing here stops the load: a file
17430
- * degrades one field, one reference, or one layer rather than failing whole
17431
- * (`docs/architecture/06-serialization-and-scene-format.md` §4).
17432
- *
17433
- * @public
17434
- */
17435
- interface SceneLoadIssue {
17436
- /** The diagnostic code, for example `IGX-0602` or `IGX-0303`. */
17437
- readonly code: string;
17438
- /** The actionable sentence. */
17439
- readonly message: string;
17440
- }
17441
- /**
17442
- * Options accepted by {@link instantiateScene}.
17443
- *
17444
- * @public
17445
- */
17446
- interface InstantiateSceneOptions {
17447
- /** The entity the scene's roots attach to; `null` or omitted makes them roots of `scene`. */
17448
- readonly parent?: Entity | null;
17449
- /** The instance that owns the new entities; defaults to the parent's, else `world.activeScene`. */
17450
- readonly scene?: SceneInstance;
17451
- /**
17452
- * `true` treats the whole file as one instance: every entity gets a fresh uid and an
17453
- * `Entity.prefab` link. This is what `world.instantiate` does; `world.loadScene` leaves it off so
17454
- * that the scene's own entities keep the uids the file gave them
17455
- * (`docs/architecture/02-scene-graph.md` §10).
17456
- */
17457
- readonly asInstance?: boolean;
17458
- /** The handle the scene was loaded through, recorded on `Entity.prefab` when `asInstance`. */
17459
- readonly assetHandle?: AssetHandle<SceneAsset> | null;
17460
- /**
17461
- * The entity that stands for the instance when `asInstance` is set and the file has more or fewer
17462
- * than one root. `world.instantiate` creates it and passes it as both `parent` and `rootEntity`,
17463
- * so that the call still answers with one entity.
17464
- */
17465
- readonly rootEntity?: Entity | null;
17466
- /** `true` turns an `IGX-0604` hash mismatch from a diagnostic into a throw. */
17467
- readonly strictInstanceHashes?: boolean;
17468
- }
17469
- /**
17470
- * What {@link instantiateScene} produced.
17471
- *
17472
- * @public
17473
- */
17474
- interface SceneBuildResult {
17475
- /** The entities that ended up parentless within the built subtree, in file order. */
17476
- readonly roots: readonly Entity[];
17477
- /** The file-local uid to runtime object table (`docs/architecture/02-scene-graph.md` §10). */
17478
- readonly remap: UidRemap;
17479
- /** Every recoverable problem, in discovery order. */
17480
- readonly issues: readonly SceneLoadIssue[];
17481
- }
17482
- /**
17483
- * Builds the entities of a scene asset into a world — steps 3 to 6 of the loading algorithm
17484
- * (`docs/architecture/06-serialization-and-scene-format.md` §4). It is synchronous and does no I/O:
17485
- * every asset the file references is already loaded, which is what a `SceneAsset` guarantees.
17486
- *
17487
- * @remarks
17488
- * The mechanism that keeps `awake` honest is worth stating, because §4 step 6 and
17489
- * `01-lifecycle-and-time.md` §4 state only the outcome. Entities are created with `active: false`,
17490
- * so the enable transition computes "not effectively enabled" and queues nothing. Components are
17491
- * attached with their schema defaults, then every component's props are decoded — that is where
17492
- * `entityRef` and `componentRef` resolve, through a table that by then holds the whole scene. Only
17493
- * then does a last pass write each entity's file `active` value in tree order, which is what queues
17494
- * `awake` and `onEnable`, parents before children. Nothing observes the half-built scene, because
17495
- * all of this runs in one synchronous block.
17496
- *
17497
- * @param world - The world to build into.
17498
- * @param asset - The scene to build.
17499
- * @param options - Where to attach the result, and how to treat instance hashes.
17500
- * @returns The roots, the uid table, and every recoverable problem.
17501
- * @throws IgnifxError with code `IGX-0302` on an instance cycle, `IGX-0307` when the file names an
17502
- * unregistered component type, and `IGX-0604` when `strictInstanceHashes` is set and a recorded
17503
- * instance hash does not match.
17504
- *
17505
- * @example
17506
- * ```ts
17507
- * const built = instantiateScene(world, sceneAsset, { scene: world.activeScene });
17508
- * const player = built.remap.entity("01J9Z6M7E5S3A0V2Q4R8T1Y6WX");
17509
- * ```
17510
- *
17511
- * @public
17512
- */
17513
- export declare function instantiateScene(world: World, asset: SceneAsset, options?: InstantiateSceneOptions): SceneBuildResult;
17514
18291
  /**
17515
- * Checks that every scene a file instances — at any depth — is among the loaded dependencies, which
17516
- * is what makes `world.instantiate` safe to be synchronous
17517
- * (`docs/architecture/02-scene-graph.md` §2).
18292
+ * Describes the `ignifx.mesh` file format (ADR-0029).
17518
18293
  *
17519
- * @param asset - The scene to check.
17520
- * @throws IgnifxError with code `IGX-0301` naming the first instanced scene that is not loaded.
18294
+ * @returns The description of the top-level file fields.
17521
18295
  *
17522
18296
  * @public
17523
18297
  */
17524
- export declare function assertSceneDependenciesLoaded(asset: SceneAsset): void;
18298
+ export declare function describeMeshFileFormat(): SchemaDescription;
17525
18299
  //#endregion
17526
18300
  //#region src/serialization/overrides.d.ts
17527
18301
  /**
@@ -17635,6 +18409,43 @@ interface SceneLoaderOptions {
17635
18409
  * @public
17636
18410
  */
17637
18411
  export declare function createSceneLoader(options?: SceneLoaderOptions): AssetLoader<SceneAsset>;
18412
+ /**
18413
+ * Options accepted by {@link loadSceneDependencies}.
18414
+ *
18415
+ * @public
18416
+ */
18417
+ interface LoadSceneDependenciesOptions {
18418
+ /** Aborts every request; the handles already loaded are released before the promise rejects. */
18419
+ readonly signal?: AbortSignal;
18420
+ }
18421
+ /**
18422
+ * Loads every asset a scene file references — in `settings`, in every component's `props`, and in
18423
+ * every `instance.scene`, recursively through the scenes those pull in — the walk the scene loader
18424
+ * runs before it builds anything (`docs/architecture/06-serialization-and-scene-format.md` §4
18425
+ * step 2).
18426
+ *
18427
+ * @remarks
18428
+ * It is the half of the scene loader a file that is already in memory needs: pass the result to
18429
+ * `createSceneAsset` and the asset can be built synchronously with `instantiateScene`. Each handle
18430
+ * is returned with one holder, which the caller owns: release them all when the scene they serve
18431
+ * is gone. `world.loadSceneFile` does that for a whole scene.
18432
+ *
18433
+ * @param assets - The asset service to load through, normally `app.assets`.
18434
+ * @param file - The scene file.
18435
+ * @param options - Cancellation.
18436
+ * @returns The loaded handles, deduplicated by address, in the loader's order.
18437
+ * @throws Whatever the asset service rejects a load with (an `AssetLoadError`); every handle
18438
+ * loaded by then is released first.
18439
+ *
18440
+ * @example
18441
+ * ```ts
18442
+ * const dependencies = await loadSceneDependencies(app.assets, file);
18443
+ * const asset = await createSceneAsset("memory:scene/draft", file, dependencies);
18444
+ * ```
18445
+ *
18446
+ * @public
18447
+ */
18448
+ export declare function loadSceneDependencies(assets: Assets, file: SceneFile, options?: LoadSceneDependenciesOptions): Promise<readonly AssetHandle[]>;
17638
18449
  //#endregion
17639
18450
  //#region src/serialization/serialize.d.ts
17640
18451
  /**
@@ -17778,6 +18589,39 @@ interface SceneFileIssue {
17778
18589
  */
17779
18590
  export declare function validateSceneFile(value: unknown): readonly SceneFileIssue[];
17780
18591
  //#endregion
18592
+ //#region src/schema/describe-registry.d.ts
18593
+ /**
18594
+ * Describes every component an app has registered, the engine's, its extensions' and the game's,
18595
+ * the way {@link describeSchema} describes one, plus what only the registry knows: whether an
18596
+ * entity may hold more than one (`allowMultiple`) and which package registered it (`package`).
18597
+ * This is what an external inspector, such as the ignifx editor, is generated from.
18598
+ *
18599
+ * @remarks
18600
+ * `package` is the `name` of the extension whose `register(ctx)` registered the class, which is the
18601
+ * npm package name for a published extension (`@ignifx/core`, `@ignifx/3d`). A class the game
18602
+ * registered itself with `app.registerComponents` has no extension, so its `package` is its type
18603
+ * id's namespace: everything before the last `/` (`third-person` for `third-person/Beacon`).
18604
+ *
18605
+ * `ignifx/Transform` declares no schema on its class; it is described with {@link transformSchema}
18606
+ * and marked `builtIn`, because every entity carries exactly one and a scene file stores it as the
18607
+ * entity's `transform` block rather than in its `components`.
18608
+ *
18609
+ * @param registry - The registry to walk, usually `app.world.registry`.
18610
+ * @param curated - Titles, formats and summaries by type id, for example a package's own
18611
+ * `describeSchemas()`; a component without an entry is titled from its type id.
18612
+ * @returns The descriptions, keyed by type id, in registration order.
18613
+ *
18614
+ * @example
18615
+ * ```ts
18616
+ * const schemas = describeRegisteredSchemas(app.world.registry, describeSchemas());
18617
+ * schemas["ignifx/Camera"]?.package; // "@ignifx/core"
18618
+ * schemas["ignifx/Camera"]?.allowMultiple; // false
18619
+ * ```
18620
+ *
18621
+ * @public
18622
+ */
18623
+ export declare function describeRegisteredSchemas(registry: ComponentRegistry, curated?: Readonly<Record<string, SchemaDescriptionMeta>>): Readonly<Record<string, SchemaDescription>>;
18624
+ //#endregion
17781
18625
  //#region src/schema/field-kinds.d.ts
17782
18626
  /**
17783
18627
  * Declares a single-precision floating point field.
@@ -18317,6 +19161,83 @@ export declare function waitUntil(predicate: () => boolean): WaitInstruction;
18317
19161
  */
18318
19162
  export declare function waitWhile(predicate: () => boolean): WaitInstruction;
18319
19163
  //#endregion
19164
+ //#region src/settings/describe-settings.d.ts
19165
+ /**
19166
+ * The `format` every settings section description carries, so a consumer that merges settings and
19167
+ * component descriptions can tell them apart.
19168
+ *
19169
+ * @public
19170
+ */
19171
+ export declare const SETTINGS_DESCRIPTION_FORMAT = "settings";
19172
+ /**
19173
+ * Describes every project settings section an app has registered (core's own `layers`,
19174
+ * `sortingLayers`, `time`, `assets` and `rendering`, and every section an extension declared with
19175
+ * `ctx.registerSettings`) in the same shape {@link describeRegisteredSchemas} describes components.
19176
+ * This is what an external settings panel, such as the ignifx editor's, is generated from.
19177
+ *
19178
+ * @remarks
19179
+ * Each entry is keyed and titled by its section name, has `format: "settings"`
19180
+ * ({@link SETTINGS_DESCRIPTION_FORMAT}), and names the extension that registered it as `package`
19181
+ * (`@ignifx/core`, `@ignifx/physics`). A field's `default` is the value the owner registered for it,
19182
+ * which is what the project gets when it omits the field; a field the owner's defaults leave out has
19183
+ * no `default`, because the resolved section has no value for it either.
19184
+ *
19185
+ * Defaults are in the **settings form**, the form `createApp` reads, which differs from the scene
19186
+ * file's for vectors and colours: a `vec3` default is `{ "x": 0, "y": -9.81, "z": 0 }` and a `color`
19187
+ * default is `{ "r": 0, "g": 0, "b": 0, "a": 1 }`, not an array. A tool writes values back in this
19188
+ * form.
19189
+ *
19190
+ * The registration seam is `ctx.registerSettings(section, schema, defaults)`: an extension that
19191
+ * declares a section there is described here with no further work. A section is written in project
19192
+ * settings (`ignifx.settings.json` or `ignifx.config.ts`) as an object of these fields; a section
19193
+ * with exactly one field of a non-object kind (a number, string, enum or array, not a vector or
19194
+ * colour) may also be written as that field's value.
19195
+ *
19196
+ * @param app - The app whose sections to describe; its extensions have all registered by the time
19197
+ * `createApp` resolves.
19198
+ * @returns The descriptions, keyed by section name, in registration order.
19199
+ * @throws IgnifxError with code `IGX-0702` when `app` was not created by this copy of
19200
+ * `@ignifx/core`.
19201
+ *
19202
+ * @example
19203
+ * ```ts
19204
+ * const sections = describeSettings(app);
19205
+ * sections["time"]?.package; // "@ignifx/core"
19206
+ * sections["time"]?.fields["fixedDeltaTime"]?.default; // 0.016666666666666666
19207
+ * ```
19208
+ *
19209
+ * @public
19210
+ */
19211
+ export declare function describeSettings(app: App): Readonly<Record<string, SchemaDescription>>;
19212
+ /**
19213
+ * Generates the JSON Schema (draft 2020-12) of a project's settings object, the content of
19214
+ * `ignifx.settings.json`, from every section the app registered. Pass it to the Vite plugin as
19215
+ * `ignifx({ schemas: { settings } })` to validate the project settings at build time, or associate
19216
+ * it with `ignifx.settings.json` in a text editor.
19217
+ *
19218
+ * @remarks
19219
+ * The schema describes the settings form `createApp` reads (vectors as `{ x, y, z }`, colours as
19220
+ * `{ r, g, b, a }` with every channel required), so a document it accepts also passes `createApp`'s
19221
+ * own validation (`IGX-0408`). Every section is optional and a section omitted takes its defaults.
19222
+ * An unknown key inside a section is a violation. The top level stays open: a section this app did
19223
+ * not register, perhaps one of an extension it lacks, is left to `createApp`, which reports it
19224
+ * (`IGX-0407`), and to the Vite plugin, which warns about it.
19225
+ *
19226
+ * @param app - The app whose sections to describe.
19227
+ * @returns The object schema, one property per section.
19228
+ * @throws IgnifxError with code `IGX-0702` when `app` was not created by this copy of
19229
+ * `@ignifx/core`.
19230
+ *
19231
+ * @example
19232
+ * ```ts
19233
+ * const schema = settingsJsonSchema(app);
19234
+ * Object.keys(schema["properties"] ?? {}); // ["layers", "sortingLayers", "time", "assets", "rendering"]
19235
+ * ```
19236
+ *
19237
+ * @public
19238
+ */
19239
+ export declare function settingsJsonSchema(app: App): JsonSchemaObject;
19240
+ //#endregion
18320
19241
  //#region src/storage/memory-backend.d.ts
18321
19242
  /**
18322
19243
  * The in-memory storage backend: the default for a headless app, and the one every unit test in the
@@ -18488,6 +19409,36 @@ export declare class IndexedDbStorageBackend implements StorageBackend {
18488
19409
  dispose(): void;
18489
19410
  }
18490
19411
  //#endregion
19412
+ //#region src/transform/transform-schema.d.ts
19413
+ /**
19414
+ * The entity transform as a schema: the fields of a scene file's `transform` block, so an
19415
+ * inspector and its ops can treat the transform like any component
19416
+ * (`docs/architecture/06-serialization-and-scene-format.md` §2).
19417
+ *
19418
+ * @remarks
19419
+ * The schema **describes** the transform; {@link (Transform:class)} does not declare it. The class keeps
19420
+ * no schema because its `position` and `rotation` are world-space getters, while the file, this
19421
+ * schema, and the editor's `setTransform` op all carry **local** values. Every entity has exactly
19422
+ * one transform, which is never in a file's `components` list, so `describeSchemas()` and
19423
+ * `describeRegisteredSchemas()` mark `ignifx/Transform` as `builtIn`: it cannot be added or
19424
+ * removed, and its values are edited as the whole block, not with a per-prop op.
19425
+ *
19426
+ * `rotation` is a `quat` field: files and ops store a unit quaternion, and an inspector shows
19427
+ * intrinsic XYZ Euler angles in degrees (ADR-0011), so its `step` is in degrees.
19428
+ *
19429
+ * @returns A new schema: `position` (`vec3`, origin, step 0.01), `rotation` (`quat`, identity,
19430
+ * step 0.5 degrees), `scale` (`vec3`, one, step 0.01).
19431
+ *
19432
+ * @example
19433
+ * ```ts
19434
+ * const fields = describeSchema("ignifx/Transform", transformSchema()).fields;
19435
+ * fields["rotation"]?.default; // [0, 0, 0, 1]
19436
+ * ```
19437
+ *
19438
+ * @public
19439
+ */
19440
+ export declare function transformSchema(): Schema;
19441
+ //#endregion
18491
19442
  //#region src/tween/tween-system.d.ts
18492
19443
  /**
18493
19444
  * The `PostUpdate` system that advances `app.tweens` (`docs/architecture/01-lifecycle-and-time.md`
@@ -18508,5 +19459,5 @@ export declare class IndexedDbStorageBackend implements StorageBackend {
18508
19459
  */
18509
19460
  export declare const TWEEN_SYSTEM_ORDER = -100;
18510
19461
  //#endregion
18511
- 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 };
19462
+ 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 };
18512
19463
  //# sourceMappingURL=index.d.ts.map