@ignifx/core 0.17.0 → 0.19.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 (50) hide show
  1. package/dist/{environment-CMpzGXTz.js → environment-Bf4aphSb.js} +2 -2
  2. package/dist/{environment-CMpzGXTz.js.map → environment-Bf4aphSb.js.map} +1 -1
  3. package/dist/{hdr-output-BrUvpAsE.js → hdr-output-Dbv0lhFl.js} +4 -3
  4. package/dist/{hdr-output-BrUvpAsE.js.map → hdr-output-Dbv0lhFl.js.map} +1 -1
  5. package/dist/{ignifx-error-Der0bpHK.js → ignifx-error-DwIZKxA2.js} +13 -1
  6. package/dist/ignifx-error-DwIZKxA2.js.map +1 -0
  7. package/dist/index.d.ts +144 -675
  8. package/dist/index.d.ts.map +1 -1
  9. package/dist/index.js +3242 -1949
  10. package/dist/index.js.map +1 -1
  11. package/dist/light-probe-asset-BqfSrJe9.js +331 -0
  12. package/dist/light-probe-asset-BqfSrJe9.js.map +1 -0
  13. package/dist/light-probes-DyLapYX9.js +284 -0
  14. package/dist/light-probes-DyLapYX9.js.map +1 -0
  15. package/dist/lightmaps-LO6Ygtwe.js +137 -0
  16. package/dist/lightmaps-LO6Ygtwe.js.map +1 -0
  17. package/dist/{material-plugin-B-hartHR.js → material-plugin-DapJNj04.js} +2 -2
  18. package/dist/{material-plugin-B-hartHR.js.map → material-plugin-DapJNj04.js.map} +1 -1
  19. package/dist/{post-effect-CuoYvrhb.js → post-effect-CaiqDlhW.js} +2 -2
  20. package/dist/{post-effect-CuoYvrhb.js.map → post-effect-CaiqDlhW.js.map} +1 -1
  21. package/dist/{post-effect-compiler-Bps8QbiJ.js → post-effect-compiler-jSvOVe0U.js} +3 -3
  22. package/dist/{post-effect-compiler-Bps8QbiJ.js.map → post-effect-compiler-jSvOVe0U.js.map} +1 -1
  23. package/dist/{prefab-overrides-76IhcF-e.d.ts → prefab-overrides-CS8_cG66.d.ts} +1559 -252
  24. package/dist/prefab-overrides-CS8_cG66.d.ts.map +1 -0
  25. package/dist/{prefab-overrides-DGiGTSN-.js → prefab-overrides-DRP2DcnC.js} +450 -30
  26. package/dist/prefab-overrides-DRP2DcnC.js.map +1 -0
  27. package/dist/prefab.d.ts +2 -2
  28. package/dist/prefab.js +2 -2
  29. package/dist/{reflection-probe-C0pzGrG_.js → reflection-probe-AS8d4uKv.js} +30 -12
  30. package/dist/{reflection-probe-C0pzGrG_.js.map → reflection-probe-AS8d4uKv.js.map} +1 -1
  31. package/dist/{reflection-probes-B8_vK9YR.js → reflection-probes-CUZcOjNW.js} +115 -22
  32. package/dist/reflection-probes-CUZcOjNW.js.map +1 -0
  33. package/dist/{render-path-Be7WgN7r.js → render-path-D11i_7X8.js} +3 -2
  34. package/dist/{render-path-Be7WgN7r.js.map → render-path-D11i_7X8.js.map} +1 -1
  35. package/dist/{scene-color-passes-DlNr-qyZ.js → scene-color-passes-B93qTOka.js} +35 -12
  36. package/dist/scene-color-passes-B93qTOka.js.map +1 -0
  37. package/dist/{shader-material-DCjYDdkh.js → shader-material-CJIDFvSb.js} +2 -2
  38. package/dist/{shader-material-DCjYDdkh.js.map → shader-material-CJIDFvSb.js.map} +1 -1
  39. package/dist/{shader-material-Cjfq7nFS.js → shader-material-CuwK9tWC.js} +5 -5
  40. package/dist/{shader-material-Cjfq7nFS.js.map → shader-material-CuwK9tWC.js.map} +1 -1
  41. package/dist/{shader-pragma-cjEC-EPK.js → shader-pragma-ljmAbVc2.js} +2 -2
  42. package/dist/{shader-pragma-cjEC-EPK.js.map → shader-pragma-ljmAbVc2.js.map} +1 -1
  43. package/dist/{surface-shader-D40hXQ8c.js → surface-shader-DY9_aC9L.js} +4 -4
  44. package/dist/{surface-shader-D40hXQ8c.js.map → surface-shader-DY9_aC9L.js.map} +1 -1
  45. package/package.json +1 -1
  46. package/dist/ignifx-error-Der0bpHK.js.map +0 -1
  47. package/dist/prefab-overrides-76IhcF-e.d.ts.map +0 -1
  48. package/dist/prefab-overrides-DGiGTSN-.js.map +0 -1
  49. package/dist/reflection-probes-B8_vK9YR.js.map +0 -1
  50. package/dist/scene-color-passes-DlNr-qyZ.js.map +0 -1
@@ -205,6 +205,11 @@ declare const CoreErrorCode: {
205
205
  readonly invalidMeshFile: "IGX-0507";
206
206
  /** An asset needs a Lite decoder that `@ignifx/vite-plugin`'s `decoders` option left out of the build. */
207
207
  readonly decoderLeftOut: "IGX-0508";
208
+ /**
209
+ * A `.basis` texture was loaded where its transcoder cannot come from: Babylon Lite fetches it
210
+ * from `cdn.babylonjs.com` only, which ignifx does not load code from. Use `.ktx2`.
211
+ */
212
+ readonly basisTranscoderRemote: "IGX-0509";
208
213
  /** A serialized number was `NaN` or infinite. */
209
214
  readonly nonFiniteNumber: "IGX-0601";
210
215
  /** A serialized `$entity`/`$component` reference could not be resolved. */
@@ -293,6 +298,10 @@ declare const CoreErrorCode: {
293
298
  readonly renderTextureCameraDetached: "IGX-0732";
294
299
  /** `maxWaitMs` given to `app.renderer.renderToTexture` or `app.renderer.nextFrame` is not a finite number of 0 or more. */
295
300
  readonly invalidFrameWait: "IGX-0733";
301
+ /** `bakeLightProbes` was given a grid, ray count or distance it cannot bake. */
302
+ readonly invalidLightProbeBake: "IGX-0734";
303
+ /** A `MeshRenderer`'s lightmap is not drawn as declared: the entity is not static, the material is not PBR, or the placement is not the identity. */
304
+ readonly lightmapNotApplied: "IGX-0735";
296
305
  /** The host exposes no Web Crypto implementation. */
297
306
  readonly cryptoUnavailable: "IGX-1420";
298
307
  /** A storage namespace name is not a legal namespace segment. */
@@ -5659,111 +5668,183 @@ interface FrameStateController {
5659
5668
  endCallback(): void;
5660
5669
  }
5661
5670
  //#endregion
5662
- //#region src/render/reflection-probe.d.ts
5671
+ //#region src/render/light-probe-asset.d.ts
5663
5672
  /**
5664
- * The `ReflectionProbe` component (`docs/plan/2026-11-gi-phase-2-execution-plan.md`, step B1).
5673
+ * Light probes (`docs/plan/2026-11-gi-phase-2-execution-plan.md`, step B2): a regular grid of baked
5674
+ * irradiance samples that a `LightProbeVolume` lights PBR materials with, in place of the scene
5675
+ * environment's diffuse light. Everything here is plain data and runs in Node.
5665
5676
  *
5666
- * The component only holds settings and the "capture again" request. The renderer loads the probe's
5667
- * GPU code (`./gpu/reflection-probes.ts`, `../lite/gpu/reflection-probe.ts`) only once a world has
5668
- * a probe, so a project without one pays nothing for it (`CONSTITUTION.md` §2.5). Headless, a probe
5669
- * captures nothing.
5677
+ * Each probe stores four RGB coefficients of first-order spherical harmonics, already convolved and
5678
+ * scaled the way Babylon Lite's environment harmonics are, so the diffuse light a white surface with
5679
+ * normal `n` receives is `c0 + c1·n.y + c2·n.z + c3·n.x` (Lite's `environmentIrradiance`, L1 part).
5670
5680
  */
5671
5681
  /**
5672
- * The `as const` name table behind {@link ReflectionProbeRefreshMode}.
5682
+ * The asset type light-probe grids are registered under.
5673
5683
  *
5674
5684
  * @public
5675
5685
  */
5676
- declare const REFLECTION_PROBE_REFRESH_MODES: readonly ["once", "onDemand", "everyFrame"];
5686
+ declare const LIGHT_PROBE_ASSET_TYPE = "lightprobes";
5677
5687
  /**
5678
- * When a reflection probe renders its cube map again.
5688
+ * The address extensions that select the light-probe loader.
5679
5689
  *
5680
- * @remarks
5681
- * - `"once"` (default): when the probe is first ready, and again on {@link ReflectionProbe.refresh}.
5682
- * - `"onDemand"`: only on {@link ReflectionProbe.refresh}; until then the probe reflects nothing.
5683
- * - `"everyFrame"`: every frame, six extra scene passes each frame. Use it for one probe at most, and
5684
- * only on desktop at the `high` quality tier (nothing caps it yet).
5690
+ * @public
5691
+ */
5692
+ declare const LIGHT_PROBE_FILE_EXTENSIONS: readonly string[];
5693
+ /**
5694
+ * The `format` header every `.probes.json` carries.
5685
5695
  *
5686
5696
  * @public
5687
5697
  */
5688
- type ReflectionProbeRefreshMode = (typeof REFLECTION_PROBE_REFRESH_MODES)[number];
5698
+ declare const LIGHT_PROBE_FILE_FORMAT = "ignifx-probes";
5689
5699
  /**
5690
- * A point that captures the scene around it into a cube map, which nearby shiny PBR materials then
5691
- * reflect instead of the scene environment.
5700
+ * The `formatVersion` this engine reads and writes.
5701
+ *
5702
+ * @public
5703
+ */
5704
+ declare const LIGHT_PROBE_FORMAT_VERSION = 1;
5705
+ /**
5706
+ * A grid of light probes, as a `.probes.json` stores it.
5692
5707
  *
5693
5708
  * @remarks
5694
- * Each lit PBR material reflects the nearest enabled probe that has captured: a probe whose
5695
- * `boxProjection` box holds the mesh wins over one that does not, then the closer probe wins. With no
5696
- * probe, materials reflect the `Environment` again. A material shared by several meshes follows the
5697
- * first of them. Diffuse lighting still comes from the scene environment.
5709
+ * Probe `(i, j, k)` sits at `origin + (i, j, k) · cellSize`. `coefficients` holds 12 floats per probe,
5710
+ * probes ordered X fastest, then Y, then Z (`index = i + countX·(j + countY·k)`); each probe's floats
5711
+ * are `c0.rgb, c1.rgb, c2.rgb, c3.rgb` in linear RGB (see the module remarks).
5712
+ *
5713
+ * @public
5714
+ */
5715
+ interface LightProbeData {
5716
+ /** The world position of probe `(0, 0, 0)`. */
5717
+ readonly origin: Vec3Like;
5718
+ /** The distance between neighbouring probes along each axis, in metres. */
5719
+ readonly cellSize: Vec3Like;
5720
+ /** How many probes along X, Y and Z; each at least 1. */
5721
+ readonly counts: {
5722
+ readonly x: number;
5723
+ readonly y: number;
5724
+ readonly z: number;
5725
+ };
5726
+ /** 12 floats per probe, `countX · countY · countZ · 12` in all. */
5727
+ readonly coefficients: readonly number[];
5728
+ }
5729
+ /**
5730
+ * A loaded light-probe grid.
5698
5731
  *
5699
- * The probe needs a loaded `Environment` (it reuses its lighting tables) and a canvas-backed app.
5700
- * Mip levels are box-filtered, so very rough materials look blurrier than with a prefiltered `.env`.
5732
+ * @example
5733
+ * ```ts
5734
+ * const probes = await app.assets.loadAsync<LightProbeAsset>("lighting/hall.probes.json");
5735
+ * world.createEntity("Probes").addComponent(LightProbeVolume, { probes });
5736
+ * ```
5737
+ *
5738
+ * @beta
5739
+ */
5740
+ declare class LightProbeAsset {
5741
+ /** The type name the asset service registers light-probe grids under. */
5742
+ static assetType: string;
5743
+ /** The grid. */
5744
+ readonly data: LightProbeData;
5745
+ /**
5746
+ * Wraps a checked grid. Use the loader or {@link createLightProbeAsset}.
5747
+ *
5748
+ * @param data - The grid, already checked by `readLightProbeData`.
5749
+ *
5750
+ * @internal
5751
+ */
5752
+ constructor(data: LightProbeData);
5753
+ }
5754
+ /**
5755
+ * Publishes a grid built in code, such as the result of a bake, as an asset.
5756
+ *
5757
+ * @param app - The app.
5758
+ * @param data - The grid.
5759
+ * @returns A handle a `LightProbeVolume` can take.
5760
+ * @throws IgnifxError with code `IGX-0709` when the grid is malformed.
5761
+ *
5762
+ * @beta
5763
+ */
5764
+ declare function createLightProbeAsset(app: App, data: LightProbeData): AssetHandle<LightProbeAsset>;
5765
+ /**
5766
+ * Turns a grid into the JSON a `.probes.json` file holds.
5767
+ *
5768
+ * @param data - The grid.
5769
+ * @returns The file contents, with the format header.
5770
+ *
5771
+ * @beta
5772
+ */
5773
+ declare function writeLightProbeFile(data: LightProbeData): Record<string, unknown>;
5774
+ /**
5775
+ * The diffuse light a white surface receives at a point, read from the grid on the CPU the same way
5776
+ * the shader reads it: trilinear between the eight surrounding probes, clamped at the grid's edges.
5777
+ *
5778
+ * @param data - The grid.
5779
+ * @param x - World X.
5780
+ * @param y - World Y.
5781
+ * @param z - World Z.
5782
+ * @param normal - The surface normal, unit length.
5783
+ * @returns Linear RGB.
5784
+ *
5785
+ * @beta
5786
+ */
5787
+ declare function sampleLightProbes(data: LightProbeData, x: number, y: number, z: number, normal: Vec3Like): [number, number, number];
5788
+ //#endregion
5789
+ //#region src/render/light-probe-volume.d.ts
5790
+ /**
5791
+ * Lights PBR materials with a baked light-probe grid instead of the scene environment's diffuse
5792
+ * light (`docs/plan/2026-11-gi-phase-2-execution-plan.md`, step B2).
5793
+ *
5794
+ * @remarks
5795
+ * Every lit PBR material samples the grid per pixel, blending the eight probes around it, so moving
5796
+ * objects and shared materials need nothing extra. Outside the grid the nearest edge probes apply.
5797
+ * Reflections still come from the `Environment` or a `ReflectionProbe`. With a `PostProcessStack`'s
5798
+ * `ssgi` on, the diffuse term is `P − (1 − environmentDiffuse)·E` (probes `P`, environment `E`),
5799
+ * because SSGI's discount applies to the environment and the probes replace it after. The volume needs a loaded
5800
+ * `Environment` and a canvas; its GPU code loads only once a world has one, and headless it does
5801
+ * nothing. When several volumes are enabled, the most recently created one wins.
5701
5802
  *
5702
5803
  * @example
5703
5804
  * ```ts
5704
- * const probe = world.createEntity("Room probe", { position: { x: 0, y: 1.5, z: 0 } });
5705
- * probe.addComponent(ReflectionProbe, { size: 128, boxProjection: { x: 8, y: 3, z: 8 } });
5805
+ * const probes = await app.assets.loadAsync<LightProbeAsset>("lighting/hall.probes.json");
5806
+ * world.createEntity("Probes").addComponent(LightProbeVolume, { probes });
5706
5807
  * ```
5707
5808
  *
5708
5809
  * @beta
5709
5810
  */
5710
- declare class ReflectionProbe extends Component {
5711
- #private;
5811
+ declare class LightProbeVolume extends Component {
5712
5812
  /** The namespaced registration id. */
5713
5813
  static typeId: string;
5714
5814
  /** What the component does, in one line, for an inspector. */
5715
5815
  static description: string;
5716
- /** One probe per entity. */
5816
+ /** One volume per entity. */
5717
5817
  static allowMultiple: boolean;
5718
5818
  /** The serialized field declarations (ADR-0004). */
5719
5819
  static schema: Schema;
5720
- /** Cube face size in pixels, rounded down to a power of two from 16 to 1024. Defaults to `128`. */
5721
- size: number;
5722
- /** When the probe captures again. Defaults to `"once"`. */
5723
- refreshMode: ReflectionProbeRefreshMode;
5724
- /**
5725
- * The full size, in metres, of the box (centred on the probe) that reflections are projected onto,
5726
- * or `null` (default) for no box: reflections then look infinitely far away.
5727
- */
5728
- boxProjection: Vec3Like | null;
5729
- /** The layer names the probe captures; empty (default) captures every layer. */
5730
- cullingMask: readonly string[];
5731
- /** The near clip distance of the capture, in metres. Defaults to `0.1`. */
5732
- near: number;
5733
- /** The far clip distance of the capture, in metres. Defaults to `1000`. */
5734
- far: number;
5820
+ /** The `.probes.json` grid, or `null` (default) for none. */
5821
+ probes: AssetHandle<LightProbeAsset> | null;
5822
+ /** A multiplier on the probes' light. Defaults to `1`. */
5823
+ intensity: number;
5735
5824
  /** Applies the schema defaults, exactly as `Component.define` would. */
5736
5825
  constructor();
5737
5826
  /**
5738
- * Asks the probe to capture again from the next frame, whatever its `refreshMode`.
5739
- *
5740
- * @remarks
5741
- * Call it after the static scene around the probe changed, such as a door opening. A capture
5742
- * repeats over a few frames, so meshes whose materials are still compiling are caught.
5743
- */
5744
- refresh(): void;
5745
- /**
5746
- * Reads and clears the request {@link ReflectionProbe.refresh} made.
5827
+ * The grid this volume lights with right now.
5747
5828
  *
5748
- * @returns Whether a capture was requested since the last call.
5829
+ * @returns The loaded asset, or `null` while there is none or it is still loading.
5749
5830
  *
5750
5831
  * @internal
5751
5832
  */
5752
- consumeRefreshRequest(): boolean;
5833
+ loadedProbes(): LightProbeAsset | null;
5753
5834
  }
5754
5835
  //#endregion
5755
- //#region src/render/gpu/reflection-probe-host.d.ts
5836
+ //#region src/render/gpu/light-probe-host.d.ts
5756
5837
  /**
5757
- * The renderer's handle on reflection probes (GI B1): it loads the probe chunk
5758
- * (`./reflection-probes.ts`) the first frame a world has a probe and forwards every frame to it.
5759
- * Device-only, like the rest of `src/render/gpu/`: a headless renderer never creates one.
5838
+ * The renderer's handle on light probes (GI B2): it loads the light-probe chunk (`./light-probes.ts`)
5839
+ * the first frame a world has a `LightProbeVolume` and forwards every frame to it. Device-only, like
5840
+ * the rest of `src/render/gpu/`: a headless renderer never creates one.
5760
5841
  *
5761
5842
  * @internal
5762
5843
  */
5763
- declare class ReflectionProbeHost {
5844
+ declare class LightProbeHost {
5764
5845
  #private;
5765
5846
  /**
5766
- * Creates the host; nothing loads until a probe exists.
5847
+ * Creates the host; nothing loads until a volume exists.
5767
5848
  *
5768
5849
  * @param engine - The engine.
5769
5850
  * @param scene - The registered render scene.
@@ -5771,23 +5852,97 @@ declare class ReflectionProbeHost {
5771
5852
  */
5772
5853
  constructor(engine: LiteEngine, scene: LiteScene, onError: (error: unknown) => void);
5773
5854
  /**
5774
- * Whether the chunk is loaded and running.
5855
+ * Whether the chunk is loaded and a grid lights the scene.
5775
5856
  *
5776
- * @returns `true` once a probe has loaded it.
5857
+ * @returns `true` while a volume's grid is applied to the materials.
5777
5858
  */
5778
- get isActive(): boolean;
5859
+ get isLighting(): boolean;
5779
5860
  /**
5780
- * Runs one frame of probe work, loading the chunk first when a probe exists.
5861
+ * Runs one frame of light-probe work, loading the chunk first when a volume exists.
5781
5862
  *
5782
- * @param world - The world.
5783
- * @param probes - Every `ReflectionProbe` in it.
5784
- * @param isHdr - Whether `rendering.hdr` is on.
5863
+ * @param volumes - Every `LightProbeVolume` in the world.
5785
5864
  */
5786
- update(world: World, probes: readonly ReflectionProbe[], isHdr: boolean): void;
5787
- /** Frees every probe. Idempotent. */
5865
+ update(volumes: readonly LightProbeVolume[]): void;
5866
+ /** Takes the grid off every material and frees it. Idempotent. */
5788
5867
  dispose(): void;
5789
5868
  }
5790
5869
  //#endregion
5870
+ //#region src/lite/material.d.ts
5871
+ /**
5872
+ * Material half of the Babylon Lite adapter (`docs/architecture/07-rendering.md` §2.6): the three
5873
+ * material kinds a `MaterialAsset` can produce, built from plain ignifx props.
5874
+ *
5875
+ * Everything here is `@internal`, and every colour that reaches it is **linear** — the sRGB decode
5876
+ * belongs to the asset layer.
5877
+ *
5878
+ * ## What a Lite material is (verified against `@babylonjs/lite@1.27.0`)
5879
+ *
5880
+ * - A material is plain data plus one private `_buildGroup` function; `createPbrMaterial` is
5881
+ * literally `{ ...props, _buildGroup, _uboVersion: 0 }` (`lib/material/pbr/pbr-material.js`), so
5882
+ * none of these factories touches the GPU and all of them run under the null engine.
5883
+ * - **The build group is a per-family singleton.** `getPbrGroupBuilder()`, `getStandardGroupBuilder()`
5884
+ * and `getShaderGroupBuilder()` each memoise one function for the whole process
5885
+ * (`lib/material/pbr/pbr-material.js`, `lib/material/standard/create-standard-material.js`,
5886
+ * `lib/material/shader/shader-material.js` line 123), and a scene keys its renderable groups by
5887
+ * that function (`lib/scene/scene-core.js`, `addToScene`). "Material family" in
5888
+ * `docs/architecture/07-rendering.md` §1.1 therefore means *pbr*, *standard*, *shader* or *node* —
5889
+ * **not** an individual material. Only node materials get a per-material builder
5890
+ * (`lib/material/node/node-material.js`). This is what makes {@link warmUpMaterialFamilies} in
5891
+ * `./gpu/warm-up.ts` cheap: one hidden mesh per family covers every material in it.
5892
+ * - Scalar and vector edits only need `markMaterialUboDirty` (`index.d.ts` 6974), which bumps
5893
+ * `_uboVersion`. Anything that changes the compiled feature set — binding or clearing a texture,
5894
+ * flipping `doubleSided`, changing culling — needs {@link rebuildMaterialPipelines}.
5895
+ *
5896
+ * ## The custom WGSL family lives elsewhere
5897
+ *
5898
+ * `createShaderMaterial` and the `setShader*` setters are in `./gpu/shader-material.ts`, not here:
5899
+ * this module is statically reachable from every app through the material asset layer, and Babylon
5900
+ * Lite exports one barrel, so a static import of the shader factory would put Lite's whole
5901
+ * shader-material pipeline in every entry chunk. That module is reached through a dynamic
5902
+ * `import()` instead (`docs/plan/2026-09-terrain-particles-shaders.md` §3.1, "Bundle cost").
5903
+ */
5904
+ /**
5905
+ * The Babylon Lite material a `MaterialAsset` owns, re-exported under an ignifx name
5906
+ * (`CONSTITUTION.md` §3.4, coding standards §4).
5907
+ *
5908
+ * @remarks
5909
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
5910
+ *
5911
+ * @public
5912
+ */
5913
+ type LiteMaterial = Material;
5914
+ /**
5915
+ * A Babylon Lite physically based material, re-exported under an ignifx name.
5916
+ *
5917
+ * @remarks
5918
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
5919
+ *
5920
+ * @public
5921
+ */
5922
+ type LitePbrMaterial = PbrMaterialProps;
5923
+ /**
5924
+ * A Babylon Lite Babylon-Standard material, re-exported under an ignifx name.
5925
+ *
5926
+ * @remarks
5927
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
5928
+ *
5929
+ * @public
5930
+ */
5931
+ type LiteStandardMaterial = StandardMaterialProps;
5932
+ /**
5933
+ * How a material's alpha channel is interpreted, in glTF's vocabulary, in the order the inspector
5934
+ * lists them (`docs/architecture/07-rendering.md` §2.4).
5935
+ *
5936
+ * @public
5937
+ */
5938
+ declare const MATERIAL_ALPHA_MODES: readonly ["opaque", "mask", "blend"];
5939
+ /**
5940
+ * The union of the alpha modes a material can declare.
5941
+ *
5942
+ * @public
5943
+ */
5944
+ type MaterialAlphaMode = (typeof MATERIAL_ALPHA_MODES)[number];
5945
+ //#endregion
5791
5946
  //#region src/render/shader-declaration.d.ts
5792
5947
  /**
5793
5948
  * The vocabulary a `// @ignifx` pragma declares: the three authoring forms, the WGSL types and
@@ -7235,130 +7390,54 @@ declare class SurfaceShaderBinding {
7235
7390
  get lite(): LiteMaterialPlugin | null;
7236
7391
  }
7237
7392
  //#endregion
7238
- //#region src/lite/material.d.ts
7393
+ //#region src/render/material-asset.d.ts
7239
7394
  /**
7240
- * Material half of the Babylon Lite adapter (`docs/architecture/07-rendering.md` §2.6): the three
7241
- * material kinds a `MaterialAsset` can produce, built from plain ignifx props.
7242
- *
7243
- * Everything here is `@internal`, and every colour that reaches it is **linear** — the sRGB decode
7244
- * belongs to the asset layer.
7395
+ * `MaterialAsset` and the `ignifx.material` file format
7396
+ * (`docs/architecture/07-rendering.md` §2.6, `06-serialization-and-scene-format.md` §6).
7245
7397
  *
7246
- * ## What a Lite material is (verified against `@babylonjs/lite@1.27.0`)
7398
+ * ## Decisions the documents left open
7247
7399
  *
7248
- * - A material is plain data plus one private `_buildGroup` function; `createPbrMaterial` is
7249
- * literally `{ ...props, _buildGroup, _uboVersion: 0 }` (`lib/material/pbr/pbr-material.js`), so
7250
- * none of these factories touches the GPU and all of them run under the null engine.
7251
- * - **The build group is a per-family singleton.** `getPbrGroupBuilder()`, `getStandardGroupBuilder()`
7252
- * and `getShaderGroupBuilder()` each memoise one function for the whole process
7253
- * (`lib/material/pbr/pbr-material.js`, `lib/material/standard/create-standard-material.js`,
7254
- * `lib/material/shader/shader-material.js` line 123), and a scene keys its renderable groups by
7255
- * that function (`lib/scene/scene-core.js`, `addToScene`). "Material family" in
7256
- * `docs/architecture/07-rendering.md` §1.1 therefore means *pbr*, *standard*, *shader* or *node* —
7257
- * **not** an individual material. Only node materials get a per-material builder
7258
- * (`lib/material/node/node-material.js`). This is what makes {@link warmUpMaterialFamilies} in
7259
- * `./gpu/warm-up.ts` cheap: one hidden mesh per family covers every material in it.
7260
- * - Scalar and vector edits only need `markMaterialUboDirty` (`index.d.ts` 6974), which bumps
7261
- * `_uboVersion`. Anything that changes the compiled feature set — binding or clearing a texture,
7262
- * flipping `doubleSided`, changing culling — needs {@link rebuildMaterialPipelines}.
7400
+ * - **The file is flat.** §2.6 lists the PBR properties directly, so a `.material.json` carries the
7401
+ * format header, a `type` discriminator, and the properties of that type at the top level. There
7402
+ * is no per-type sub-object to reach through.
7403
+ * - **Colours in the file are sRGB.** `06-serialization-and-scene-format.md` §3 is explicit that
7404
+ * colours are sRGB in memory and in files and that the conversion to linear "belongs to the
7405
+ * renderer". This module is that boundary: `baseColor`, `emissive`, `diffuse`, and `specular` are
7406
+ * decoded here and handed to the adapter linear. Factors that are not colours — `metallic`,
7407
+ * `roughness`, `alpha` — are unitless and pass through.
7408
+ * - **`"type": "shader"` is values applied to a `ShaderAsset`.** §2.6 lists the family, and the
7409
+ * WGSL attribute, uniform, sampler, storage, define, and pipeline layout is declared by the
7410
+ * `.wgsl` file's own `// @ignifx` pragmas rather than by the material file
7411
+ * (`src/render/shader-pragma.ts`, `docs/plan/2026-09-terrain-particles-shaders.md` §3.1). So a
7412
+ * shader `.material.json` names the shader, the values, the textures, and the defines, and
7413
+ * nothing about Babylon Lite's `ShaderMaterialOptions` reaches the public API
7414
+ * (`CONSTITUTION.md` §3.4). `IGX-0708` is still what an unknown `type` string produces.
7415
+ * - **A shader material casts PCF shadows, and must not cast ESM ones.** Measured on a device
7416
+ * (2026-09-08): a mesh wearing a shader material casts into a PCF or CSM shadow map with no flag
7417
+ * at all, because the depth-only target compiles no fragment stage. An **ESM** generator is
7418
+ * different — Babylon Lite has no shader-family material view for it and writes the fragment
7419
+ * colour's red channel into the exponential map
7420
+ * (`lib/shadow/esm-directional-shadow-generator.js` 230–245), so a shader-material caster paints
7421
+ * nonsense into an ESM map. The renderer keeps such meshes out of ESM caster lists (`IGX-0724`);
7422
+ * a project that wants shadows from a custom shader picks `pcf` or `csm`.
7423
+ * - **The shader methods are the only kind-specific members.** `setUniform`, `getUniform`,
7424
+ * `setTexture`, `setDefine`, and `setStorageBuffer` throw `IGX-0718` on a PBR or Standard
7425
+ * material, and `setBaseColor`, `setMetallicRoughness`, and `setAlpha` throw it on a shader
7426
+ * material: a shader material's "base colour" is whatever its file chose to call one, and
7427
+ * silently writing a field nothing reads is worse than refusing.
7428
+ * - **PBR extensions (`clearcoat`, `sheen`, `transmission`, …) are not implemented** for the same
7429
+ * reason: each is a sub-record with its own textures, and §2.6 wants them opt-in so unused shader
7430
+ * code is tree-shaken. The loader reports an unknown top-level key rather than silently dropping
7431
+ * it.
7263
7432
  *
7264
- * ## The custom WGSL family lives elsewhere
7433
+ * ## Headless
7265
7434
  *
7266
- * `createShaderMaterial` and the `setShader*` setters are in `./gpu/shader-material.ts`, not here:
7267
- * this module is statically reachable from every app through the material asset layer, and Babylon
7268
- * Lite exports one barrel, so a static import of the shader factory would put Lite's whole
7269
- * shader-material pipeline in every entry chunk. That module is reached through a dynamic
7270
- * `import()` instead (`docs/plan/2026-09-terrain-particles-shaders.md` §3.1, "Bundle cost").
7435
+ * `createPbrMaterial` and `createStandardMaterial` are pure data plus one build-group function
7436
+ * (ADR-0002 Validation), so a material loads **completely** under the null engine; only the textures
7437
+ * it references come back empty. That is what makes the material half of a scene testable in Node.
7271
7438
  */
7272
7439
  /**
7273
- * The Babylon Lite material a `MaterialAsset` owns, re-exported under an ignifx name
7274
- * (`CONSTITUTION.md` §3.4, coding standards §4).
7275
- *
7276
- * @remarks
7277
- * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
7278
- *
7279
- * @public
7280
- */
7281
- type LiteMaterial = Material;
7282
- /**
7283
- * A Babylon Lite physically based material, re-exported under an ignifx name.
7284
- *
7285
- * @remarks
7286
- * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
7287
- *
7288
- * @public
7289
- */
7290
- type LitePbrMaterial = PbrMaterialProps;
7291
- /**
7292
- * A Babylon Lite Babylon-Standard material, re-exported under an ignifx name.
7293
- *
7294
- * @remarks
7295
- * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
7296
- *
7297
- * @public
7298
- */
7299
- type LiteStandardMaterial = StandardMaterialProps;
7300
- /**
7301
- * How a material's alpha channel is interpreted, in glTF's vocabulary, in the order the inspector
7302
- * lists them (`docs/architecture/07-rendering.md` §2.4).
7303
- *
7304
- * @public
7305
- */
7306
- declare const MATERIAL_ALPHA_MODES: readonly ["opaque", "mask", "blend"];
7307
- /**
7308
- * The union of the alpha modes a material can declare.
7309
- *
7310
- * @public
7311
- */
7312
- type MaterialAlphaMode = (typeof MATERIAL_ALPHA_MODES)[number];
7313
- //#endregion
7314
- //#region src/render/material-asset.d.ts
7315
- /**
7316
- * `MaterialAsset` and the `ignifx.material` file format
7317
- * (`docs/architecture/07-rendering.md` §2.6, `06-serialization-and-scene-format.md` §6).
7318
- *
7319
- * ## Decisions the documents left open
7320
- *
7321
- * - **The file is flat.** §2.6 lists the PBR properties directly, so a `.material.json` carries the
7322
- * format header, a `type` discriminator, and the properties of that type at the top level. There
7323
- * is no per-type sub-object to reach through.
7324
- * - **Colours in the file are sRGB.** `06-serialization-and-scene-format.md` §3 is explicit that
7325
- * colours are sRGB in memory and in files and that the conversion to linear "belongs to the
7326
- * renderer". This module is that boundary: `baseColor`, `emissive`, `diffuse`, and `specular` are
7327
- * decoded here and handed to the adapter linear. Factors that are not colours — `metallic`,
7328
- * `roughness`, `alpha` — are unitless and pass through.
7329
- * - **`"type": "shader"` is values applied to a `ShaderAsset`.** §2.6 lists the family, and the
7330
- * WGSL attribute, uniform, sampler, storage, define, and pipeline layout is declared by the
7331
- * `.wgsl` file's own `// @ignifx` pragmas rather than by the material file
7332
- * (`src/render/shader-pragma.ts`, `docs/plan/2026-09-terrain-particles-shaders.md` §3.1). So a
7333
- * shader `.material.json` names the shader, the values, the textures, and the defines, and
7334
- * nothing about Babylon Lite's `ShaderMaterialOptions` reaches the public API
7335
- * (`CONSTITUTION.md` §3.4). `IGX-0708` is still what an unknown `type` string produces.
7336
- * - **A shader material casts PCF shadows, and must not cast ESM ones.** Measured on a device
7337
- * (2026-09-08): a mesh wearing a shader material casts into a PCF or CSM shadow map with no flag
7338
- * at all, because the depth-only target compiles no fragment stage. An **ESM** generator is
7339
- * different — Babylon Lite has no shader-family material view for it and writes the fragment
7340
- * colour's red channel into the exponential map
7341
- * (`lib/shadow/esm-directional-shadow-generator.js` 230–245), so a shader-material caster paints
7342
- * nonsense into an ESM map. The renderer keeps such meshes out of ESM caster lists (`IGX-0724`);
7343
- * a project that wants shadows from a custom shader picks `pcf` or `csm`.
7344
- * - **The shader methods are the only kind-specific members.** `setUniform`, `getUniform`,
7345
- * `setTexture`, `setDefine`, and `setStorageBuffer` throw `IGX-0718` on a PBR or Standard
7346
- * material, and `setBaseColor`, `setMetallicRoughness`, and `setAlpha` throw it on a shader
7347
- * material: a shader material's "base colour" is whatever its file chose to call one, and
7348
- * silently writing a field nothing reads is worse than refusing.
7349
- * - **PBR extensions (`clearcoat`, `sheen`, `transmission`, …) are not implemented** for the same
7350
- * reason: each is a sub-record with its own textures, and §2.6 wants them opt-in so unused shader
7351
- * code is tree-shaken. The loader reports an unknown top-level key rather than silently dropping
7352
- * it.
7353
- *
7354
- * ## Headless
7355
- *
7356
- * `createPbrMaterial` and `createStandardMaterial` are pure data plus one build-group function
7357
- * (ADR-0002 Validation), so a material loads **completely** under the null engine; only the textures
7358
- * it references come back empty. That is what makes the material half of a scene testable in Node.
7359
- */
7360
- /**
7361
- * The asset type materials are registered under.
7440
+ * The asset type materials are registered under.
7362
7441
  *
7363
7442
  * @public
7364
7443
  */
@@ -7688,85 +7767,1081 @@ declare class MaterialAsset {
7688
7767
  * picks the new material up on the next `PreRender`, and the frame after that draws with the new
7689
7768
  * pipeline — so treat it as a level-load or settings-screen operation, not a per-frame one.
7690
7769
  *
7691
- * @param name - The declared define's name.
7692
- * @param value - The new value; a boolean compiles to `bool`, a number to `f32`.
7693
- * @throws IgnifxError with code `IGX-0718` unless this is a `"shader"` material, or `IGX-0712`
7694
- * when the shader declares no such define.
7770
+ * @param name - The declared define's name.
7771
+ * @param value - The new value; a boolean compiles to `bool`, a number to `f32`.
7772
+ * @throws IgnifxError with code `IGX-0718` unless this is a `"shader"` material, or `IGX-0712`
7773
+ * when the shader declares no such define.
7774
+ */
7775
+ setDefine(name: string, value: boolean | number): void;
7776
+ /**
7777
+ * Binds a read-only storage buffer to one of the shader's declared bindings.
7778
+ *
7779
+ * @param name - The declared binding's name.
7780
+ * @param buffer - The buffer, or `null` to unbind. A shader material with an unbound declared
7781
+ * storage buffer is not drawable ({@link MaterialAsset.isDrawable}).
7782
+ * @throws IgnifxError with code `IGX-0718` unless this is a `"shader"` material, or `IGX-0712`
7783
+ * when the shader declares no such storage buffer.
7784
+ */
7785
+ setStorageBuffer(name: string, buffer: AssetHandle<StorageBufferAsset> | null): void;
7786
+ /**
7787
+ * Releases what the material holds beyond its Babylon Lite object: a shader material's per-frame
7788
+ * uniform registration and its hot-reload hook.
7789
+ *
7790
+ * @remarks
7791
+ * The `material` asset type's `unload` runs it when the last holder releases the handle, so a
7792
+ * game that pairs `load`/`release` or uses `using` never has to. Calling it twice is a no-op, and
7793
+ * it is a no-op on a PBR or Standard material, which own nothing of the kind.
7794
+ */
7795
+ dispose(): void;
7796
+ /**
7797
+ * Builds an independent copy of this material from the same declaration — the per-renderer
7798
+ * variation path of `docs/architecture/07-rendering.md` §2.6.
7799
+ *
7800
+ * @remarks
7801
+ * The copy shares the original's *textures* (they are addressed assets, and the handles are
7802
+ * retained by whoever loaded them) and nothing else: it is a second Lite material in the same
7803
+ * family, so it costs no extra shader compilation.
7804
+ *
7805
+ * @param app - The app whose asset service publishes the copy.
7806
+ * @returns The copy's handle, with one holder — the caller.
7807
+ */
7808
+ clone(app: App): AssetHandle<MaterialAsset>;
7809
+ }
7810
+ /**
7811
+ * Builds a Lite material from a declaration and publishes it as an in-memory asset.
7812
+ *
7813
+ * @param app - The app whose asset service publishes it.
7814
+ * @param definition - The declaration.
7815
+ * @param textures - The texture handles the declaration's slots resolved to, in slot order.
7816
+ * @returns The handle, with one holder — the caller.
7817
+ *
7818
+ * @example
7819
+ * ```ts
7820
+ * using red = createMaterialAsset(app, pbrMaterialDefinition({ name: "red", baseColor: { r: 1, g: 0, b: 0, a: 1 } }), []);
7821
+ * ```
7822
+ *
7823
+ * @public
7824
+ */
7825
+ declare function createMaterialAsset(app: App, definition: MaterialDefinition, textures: readonly AssetHandle<TextureAsset>[]): AssetHandle<MaterialAsset>;
7826
+ /**
7827
+ * Fills in a PBR declaration's defaults, so callers name only what they mean to change.
7828
+ *
7829
+ * @param overrides - The properties to set.
7830
+ * @returns A complete declaration.
7831
+ *
7832
+ * @example
7833
+ * ```ts
7834
+ * pbrMaterialDefinition({ name: "gold", metallic: 1, roughness: 0.25 });
7835
+ * ```
7836
+ *
7837
+ * @public
7838
+ */
7839
+ declare function pbrMaterialDefinition(overrides?: Partial<Omit<PbrMaterialDefinition, "kind">>): PbrMaterialDefinition;
7840
+ /**
7841
+ * Fills in a Standard declaration's defaults.
7842
+ *
7843
+ * @param overrides - The properties to set.
7844
+ * @returns A complete declaration.
7845
+ *
7846
+ * @public
7847
+ */
7848
+ declare function standardMaterialDefinition(overrides?: Partial<Omit<StandardMaterialDefinition, "kind">>): StandardMaterialDefinition;
7849
+ //#endregion
7850
+ //#region src/render/lightmap-asset.d.ts
7851
+ /**
7852
+ * Lightmaps (`docs/plan/2026-11-gi-phase-2-execution-plan.md`, step B3): a baked texture that static
7853
+ * `MeshRenderer`s sample through their second UV set, and the per-entity placement of each renderer
7854
+ * in it. Everything here is plain data and runs in Node; the GPU half is `./gpu/lightmaps.ts`.
7855
+ */
7856
+ /**
7857
+ * The asset type lightmaps are registered under.
7858
+ *
7859
+ * @public
7860
+ */
7861
+ declare const LIGHTMAP_ASSET_TYPE = "lightmap";
7862
+ /**
7863
+ * The address extensions that select the lightmap loader.
7864
+ *
7865
+ * @public
7866
+ */
7867
+ declare const LIGHTMAP_FILE_EXTENSIONS: readonly string[];
7868
+ /**
7869
+ * The `format` header every `.lightmap.json` carries.
7870
+ *
7871
+ * @public
7872
+ */
7873
+ declare const LIGHTMAP_FILE_FORMAT = "ignifx-lightmap";
7874
+ /**
7875
+ * The `formatVersion` this engine reads and writes.
7876
+ *
7877
+ * @public
7878
+ */
7879
+ declare const LIGHTMAP_FORMAT_VERSION = 1;
7880
+ /**
7881
+ * Where one renderer's UV2 square sits in a lightmap atlas: the lightmap is sampled at
7882
+ * `uv2 · scale + offset`.
7883
+ *
7884
+ * @public
7885
+ */
7886
+ interface LightmapPlacement {
7887
+ /** The atlas-space size of the renderer's UV2 square; each component above 0. */
7888
+ readonly scale: Vec2Like;
7889
+ /** The atlas-space position of the square's `(0, 0)` corner. */
7890
+ readonly offset: Vec2Like;
7891
+ }
7892
+ /**
7893
+ * The placement every entity without an entry gets: the whole texture.
7894
+ *
7895
+ * @public
7896
+ */
7897
+ declare const IDENTITY_LIGHTMAP_PLACEMENT: LightmapPlacement;
7898
+ /**
7899
+ * A lightmap as a `.lightmap.json` stores it.
7900
+ *
7901
+ * @public
7902
+ */
7903
+ interface LightmapFileData {
7904
+ /** The texture's asset address, resolved like any other address against the asset root. */
7905
+ readonly texture: string;
7906
+ /** Per-entity placements, keyed by entity uid; an entity without one samples the whole texture. */
7907
+ readonly entries: Readonly<Record<string, LightmapPlacement>>;
7908
+ }
7909
+ /**
7910
+ * A loaded lightmap: a texture and where each entity's UV2 square sits in it.
7911
+ *
7912
+ * @remarks
7913
+ * A `MeshRenderer` names it in its `lightmap` record. Only placements equal to
7914
+ * {@link IDENTITY_LIGHTMAP_PLACEMENT} are honoured for now: Babylon Lite 1.34's lightmap fragment
7915
+ * samples `uv2` without a transform, so a renderer with another placement logs `IGX-0735` once and
7916
+ * samples the whole texture until the atlas transform lands (GI plan §5, spike P2).
7917
+ *
7918
+ * @example
7919
+ * ```ts
7920
+ * const lightmap = await app.assets.loadAsync<LightmapAsset>("lighting/hall.lightmap.json");
7921
+ * entity.isStatic = true;
7922
+ * entity.addComponent(MeshRenderer, { mesh, lightmap: { asset: lightmap, mode: "add", level: 1, gamma: false, uv2: true } });
7923
+ * ```
7924
+ *
7925
+ * @beta
7926
+ */
7927
+ declare class LightmapAsset {
7928
+ /** The type name the asset service registers lightmaps under. */
7929
+ static assetType: string;
7930
+ /** The baked texture. The asset does not own the handle: its loader or creator does. */
7931
+ readonly texture: AssetHandle<TextureAsset>;
7932
+ /** Per-entity placements, keyed by entity uid. */
7933
+ readonly entries: Readonly<Record<string, LightmapPlacement>>;
7934
+ /**
7935
+ * Wraps a texture and its checked placements. Use the loader or {@link createLightmapAsset}.
7936
+ *
7937
+ * @param texture - The baked texture.
7938
+ * @param entries - Placements already checked by `readLightmapEntries`.
7939
+ *
7940
+ * @internal
7941
+ */
7942
+ constructor(texture: AssetHandle<TextureAsset>, entries: Readonly<Record<string, LightmapPlacement>>);
7943
+ /**
7944
+ * The placement of one entity's UV2 square.
7945
+ *
7946
+ * @param entityId - The entity's uid.
7947
+ * @returns Its entry, or {@link IDENTITY_LIGHTMAP_PLACEMENT} when it has none.
7948
+ */
7949
+ placementOf(entityId: string): LightmapPlacement;
7950
+ }
7951
+ /**
7952
+ * Publishes a lightmap built in code, such as a texture from `TextureAsset.fromPixels`.
7953
+ *
7954
+ * @param app - The app.
7955
+ * @param texture - The baked texture; the caller keeps owning the handle.
7956
+ * @param entries - Per-entity placements, keyed by entity uid. Defaults to none.
7957
+ * @returns A handle a `MeshRenderer`'s `lightmap.asset` can take.
7958
+ * @throws IgnifxError with code `IGX-0709` when a placement is malformed.
7959
+ *
7960
+ * @beta
7961
+ */
7962
+ declare function createLightmapAsset(app: App, texture: AssetHandle<TextureAsset>, entries?: Readonly<Record<string, LightmapPlacement>>): AssetHandle<LightmapAsset>;
7963
+ /**
7964
+ * Turns a lightmap description into the JSON a `.lightmap.json` file holds.
7965
+ *
7966
+ * @param data - The texture address and placements.
7967
+ * @returns The file contents, with the format header.
7968
+ *
7969
+ * @beta
7970
+ */
7971
+ declare function writeLightmapFile(data: LightmapFileData): Record<string, unknown>;
7972
+ //#endregion
7973
+ //#region src/lite/gpu/mesh.d.ts
7974
+ /**
7975
+ * Mesh half of the Babylon Lite adapter (`docs/architecture/07-rendering.md` §2.3). Every function
7976
+ * here needs a WebGPU device — `createMeshFromData` uploads four vertex buffers through
7977
+ * `engine._device` (`lib/mesh/mesh.js`, `uploadMeshToGPU`) and the null engine has no `_device` —
7978
+ * so the whole module lives under `src/lite/gpu/` and is covered by the browser test project.
7979
+ *
7980
+ * Everything here is `@internal`.
7981
+ *
7982
+ * ## Ownership, cloning, and disposal (verified against `@babylonjs/lite@1.27.0`)
7983
+ *
7984
+ * - `cloneTransformNode(mesh)` (`index.d.ts` 1776, `lib/scene/transform-node.js`) shallow-clones a
7985
+ * mesh: the clone gets a fresh transform and **the same `_gpu` wrapper object**, with
7986
+ * `retain(_gpu)` bumping a reference count. So N clones of one template share exactly one set of
7987
+ * GPU buffers — that is spike S2.4's "instancing shares GPU buffers", and it is provable by
7988
+ * object identity rather than by measuring memory.
7989
+ * - Disposal is driven entirely by scene membership. `removeFromScene` calls `unregisterMeshScene`,
7990
+ * and only when the mesh has left its **last** scene does it queue `disposeMeshGpu`, which calls
7991
+ * `release(_gpu)` and destroys the buffers only when the count drops to one
7992
+ * (`lib/scene/scene-remove.js`, `lib/mesh/mesh-dispose.js`, `lib/resource/ref-count.js`). A
7993
+ * template that is never added to a scene therefore keeps its buffers alive no matter how many
7994
+ * clones come and go — which is what `docs/architecture/07-rendering.md` §2.3 means by "the
7995
+ * template's buffers stay alive while the asset is retained".
7996
+ * - The flip side is that Lite exports **no** mesh disposer. The only public way to release a
7997
+ * template's buffers is {@link disposeMeshTemplate}: add it to a scene and take it out again.
7998
+ * - `removeFromScene` also recursively removes a mesh's `children` and nulls its `parent`, so
7999
+ * removing a `Model`'s root removes the whole instantiated subtree in one call.
8000
+ * - Hiding is `setSubtreeVisible` (exported as `setMeshVisible` too, `index.d.ts` 11199): it
8001
+ * cascades `visible` down the subtree and bumps a global visibility epoch. Never remove a mesh
8002
+ * from the scene to hide it — that disposes it.
8003
+ *
8004
+ * ## Updating a mesh's vertices (verified against `lib/mesh/mesh-factories.js`)
8005
+ *
8006
+ * `updateMesh*` writes the GPU buffer and **nothing else**. Three consequences, all of them
8007
+ * surprising enough to be worth stating where the calls are:
8008
+ *
8009
+ * 1. **The retained CPU arrays are not replaced.** `createMeshFromData` keeps `_cpuPositions`,
8010
+ * `_cpuNormals`, `_cpuUvs` and `_cpuIndices` — the arrays it was handed — and Lite's CPU ray
8011
+ * pick reads them (`lib/picking/ray-pick.js`). Only `updateMeshGeometry`/`resizeMeshGeometry`
8012
+ * re-retain, through `retainMeshGeometry`. So an update that hands over a *different* array
8013
+ * leaves picking looking at the old geometry, while an update after mutating the retained array
8014
+ * in place leaves picking exact. `MeshAsset` keeps its own copy in step for that reason.
8015
+ * 2. **Bounds are not recomputed.** `retainMeshGeometry` is what calls `computeAabb` and writes
8016
+ * `boundMin`/`boundMax`; the partial updaters do not. `Mesh`'s own declaration says a consumer
8017
+ * "MAY overwrite these with a wider hand-computed box", so {@link setMeshBounds} exists and
8018
+ * `MeshAsset.updatePositions` uses it.
8019
+ * 3. **A cloned template cannot be updated at all.** `writeVertexAttributeRange` throws
8020
+ * (`ThrowLiteError(360)`) when `mesh._gpu._refCount > 1`, and cloning a mesh retains that very
8021
+ * wrapper. A `MeshAsset` a `MeshRenderer` has drawn is therefore frozen; a mesh meant to be
8022
+ * edited is a renderable of its own, which is the shape the terrain chunk adapter uses.
8023
+ */
8024
+ /**
8025
+ * The Babylon Lite mesh a `MeshAsset` template and a `MeshRenderer` clone are, re-exported under an
8026
+ * ignifx name so feature code can name the type without importing `@babylonjs/lite`
8027
+ * (`CONSTITUTION.md` §3.4, coding standards §4).
8028
+ *
8029
+ * @remarks
8030
+ * Unstable: it is Lite's own type, reachable only through documented `.lite` escape hatches, and it
8031
+ * is excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
8032
+ *
8033
+ * @public
8034
+ */
8035
+ type LiteMesh = Mesh;
8036
+ //#endregion
8037
+ //#region src/render/mesh-asset.d.ts
8038
+ /**
8039
+ * Mesh templates share geometry with renderer clones (ADR-0002).
8040
+ * Factories register a loaded handle with one caller-owned hold; release it when no longer needed.
8041
+ * Existing clones survive collection, but a disposed template cannot make new clones.
8042
+ * Headless mesh assets keep component state without GPU geometry.
8043
+ */
8044
+ /**
8045
+ * The asset type primitives are registered under.
8046
+ *
8047
+ * @public
8048
+ */
8049
+ declare const MESH_ASSET_TYPE = "mesh";
8050
+ /**
8051
+ * How {@link MeshAsset.box} sizes its box, in metres. Give `size` for a cube, or the three
8052
+ * dimensions.
8053
+ *
8054
+ * @public
8055
+ */
8056
+ interface BoxMeshOptions {
8057
+ /** Edge length on every axis. */
8058
+ readonly size?: number;
8059
+ /** Size along X, overriding `size`. */
8060
+ readonly width?: number;
8061
+ /** Size along Y, overriding `size`. */
8062
+ readonly height?: number;
8063
+ /** Size along Z, overriding `size`. */
8064
+ readonly depth?: number;
8065
+ }
8066
+ /**
8067
+ * How {@link MeshAsset.sphere} tessellates its sphere.
8068
+ *
8069
+ * @public
8070
+ */
8071
+ interface SphereMeshOptions {
8072
+ /** Diameter on every axis, in metres. Lite defaults to 1. */
8073
+ readonly diameter?: number;
8074
+ /** Ring count; higher is smoother. Lite defaults to 32. */
8075
+ readonly segments?: number;
8076
+ }
8077
+ /**
8078
+ * How {@link MeshAsset.plane} sizes its quad, which lies in the XY plane facing `-Z`.
8079
+ *
8080
+ * @public
8081
+ */
8082
+ interface PlaneMeshOptions {
8083
+ /** Edge length on both axes, in metres. */
8084
+ readonly size?: number;
8085
+ /** Width, overriding `size`. */
8086
+ readonly width?: number;
8087
+ /** Height, overriding `size`. */
8088
+ readonly height?: number;
8089
+ }
8090
+ /**
8091
+ * How {@link MeshAsset.ground} sizes and subdivides its grid, which lies in the XZ plane facing
8092
+ * `+Y`.
8093
+ *
8094
+ * @public
8095
+ */
8096
+ interface GroundMeshOptions {
8097
+ /** Size along X, in metres. */
8098
+ readonly width?: number;
8099
+ /** Size along Z, in metres. */
8100
+ readonly height?: number;
8101
+ /** Quads per side. */
8102
+ readonly subdivisions?: number;
8103
+ /** UV multiplier, for tiling a texture across the grid. */
8104
+ readonly uvScale?: readonly [number, number];
8105
+ }
8106
+ /**
8107
+ * How {@link MeshAsset.cylinder} sizes its cylinder, which stands along Y.
8108
+ *
8109
+ * @public
8110
+ */
8111
+ interface CylinderMeshOptions {
8112
+ /** Height along Y, in metres. */
8113
+ readonly height?: number;
8114
+ /** Diameter of both ends. */
8115
+ readonly diameter?: number;
8116
+ /** Diameter of the top cap, overriding `diameter` — a cone is `diameterTop: 0`. */
8117
+ readonly diameterTop?: number;
8118
+ /** Diameter of the bottom cap, overriding `diameter`. */
8119
+ readonly diameterBottom?: number;
8120
+ /** Radial segment count. */
8121
+ readonly tessellation?: number;
8122
+ }
8123
+ /**
8124
+ * How {@link MeshAsset.capsule} sizes its capsule, which stands along Y.
8125
+ *
8126
+ * @remarks
8127
+ * `height` is the **total** height including both caps, the same convention `@ignifx/physics` uses
8128
+ * for a capsule collider, so one pair of numbers describes both.
8129
+ *
8130
+ * @public
8131
+ */
8132
+ interface CapsuleMeshOptions {
8133
+ /** Total height including both caps, in metres. */
8134
+ readonly height?: number;
8135
+ /** Radius of the body and the caps. */
8136
+ readonly radius?: number;
8137
+ /** Radial segment count. */
8138
+ readonly tessellation?: number;
8139
+ }
8140
+ /**
8141
+ * How {@link MeshAsset.torus} sizes its ring, which lies in the XZ plane.
8142
+ *
8143
+ * @public
8144
+ */
8145
+ interface TorusMeshOptions {
8146
+ /** Outer diameter, in metres. */
8147
+ readonly diameter?: number;
8148
+ /** Tube thickness, in metres. */
8149
+ readonly thickness?: number;
8150
+ /** Segment count around the ring. */
8151
+ readonly tessellation?: number;
8152
+ }
8153
+ /**
8154
+ * The primitive shapes a `MeshAsset` factory and a `.mesh.json` file can build.
8155
+ *
8156
+ * @public
8157
+ */
8158
+ declare const MESH_PRIMITIVES: readonly ["box", "sphere", "plane", "ground", "cylinder", "capsule", "torus"];
8159
+ /**
8160
+ * One of {@link MESH_PRIMITIVES}.
8161
+ *
8162
+ * @public
8163
+ */
8164
+ type MeshPrimitive = (typeof MESH_PRIMITIVES)[number];
8165
+ /**
8166
+ * A primitive and the options its factory takes: what a `.mesh.json` file declares.
8167
+ *
8168
+ * @public
8169
+ */
8170
+ type MeshPrimitiveDefinition = {
8171
+ readonly primitive: "box";
8172
+ readonly options: BoxMeshOptions;
8173
+ } | {
8174
+ readonly primitive: "sphere";
8175
+ readonly options: SphereMeshOptions;
8176
+ } | {
8177
+ readonly primitive: "plane";
8178
+ readonly options: PlaneMeshOptions;
8179
+ } | {
8180
+ readonly primitive: "ground";
8181
+ readonly options: GroundMeshOptions;
8182
+ } | {
8183
+ readonly primitive: "cylinder";
8184
+ readonly options: CylinderMeshOptions;
8185
+ } | {
8186
+ readonly primitive: "capsule";
8187
+ readonly options: CapsuleMeshOptions;
8188
+ } | {
8189
+ readonly primitive: "torus";
8190
+ readonly options: TorusMeshOptions;
8191
+ };
8192
+ /**
8193
+ * Raw vertex data for {@link MeshAsset.fromData}.
8194
+ *
8195
+ * @remarks
8196
+ * Lite keeps references to these arrays rather than copying them — they are what its CPU ray pick
8197
+ * and its bounds read (`lib/mesh/mesh-factories.js`). Mutating one behind Lite's back changes what
8198
+ * a pick reports without changing what the GPU draws; the sanctioned way to change geometry after
8199
+ * the fact is {@link MeshAsset.updatePositions} and its three siblings, which re-upload, keep this
8200
+ * copy in step, and re-fit the bounds.
8201
+ *
8202
+ * @public
8203
+ */
8204
+ interface MeshGeometryData {
8205
+ /** Three floats per vertex. */
8206
+ readonly positions: Float32Array;
8207
+ /** Three floats per vertex, one normal each. */
8208
+ readonly normals: Float32Array;
8209
+ /** Three indices per triangle. */
8210
+ readonly indices: Uint32Array;
8211
+ /** Two floats per vertex, or omitted for a mesh with no texture coordinates. */
8212
+ readonly uvs?: Float32Array;
8213
+ /**
8214
+ * Two floats per vertex for the second UV set (`uv2` in a shader), or omitted. Lightmaps, baked
8215
+ * ambient occlusion, and the parent-LOD height a terrain morph reads all ride here.
8216
+ */
8217
+ readonly uvs2?: Float32Array;
8218
+ /** Four floats per vertex — `xyz` plus a handedness `w` — or omitted. A normal map needs them. */
8219
+ readonly tangents?: Float32Array;
8220
+ /**
8221
+ * Four floats per vertex, linear RGBA, or omitted. A material has to be one that reads the colour
8222
+ * attribute; set `hasVertexAlpha` on the Lite mesh if the alpha is meant to blend.
8223
+ */
8224
+ readonly colors?: Float32Array;
8225
+ }
8226
+ /**
8227
+ * The Babylon Lite objects a {@link MeshAsset} owns. Unstable escape hatch
8228
+ * (`docs/architecture/00-overview.md` §3).
8229
+ *
8230
+ * @public
8231
+ */
8232
+ interface MeshAssetLiteHandles {
8233
+ /** The template mesh, or `null` under a headless app, which uploads no geometry. */
8234
+ readonly mesh: LiteMesh | null;
8235
+ }
8236
+ /**
8237
+ * A geometry template a `MeshRenderer` draws (`docs/architecture/07-rendering.md` §2.3).
8238
+ *
8239
+ * @remarks
8240
+ * Build one with a primitive factory or {@link MeshAsset.fromData}; each returns the handle the
8241
+ * `MeshRenderer.mesh` field takes. A `.mesh.json` file loads the same primitives by address
8242
+ * (`app.assets.load("meshes/crate.mesh.json")`), so a scene file can name one. A glTF mesh
8243
+ * arrives as part of a `ModelAsset` instead — a glTF is a tree of meshes, materials, and
8244
+ * animations, not one buffer.
8245
+ *
8246
+ * @example
8247
+ * ```ts
8248
+ * const box = MeshAsset.box(app, { size: 2 }); // one reference, owned by this code
8249
+ * const cube = app.world.createEntity("Cube");
8250
+ * cube.addComponent(MeshRenderer, { mesh: box }); // the field takes no reference
8251
+ * // Once nothing draws the box any more:
8252
+ * box.release();
8253
+ * ```
8254
+ *
8255
+ * @public
8256
+ */
8257
+ declare class MeshAsset {
8258
+ #private;
8259
+ /** The type name the asset service registers meshes under. */
8260
+ static assetType: string;
8261
+ /** A human-readable name, used in diagnostics and as the Lite mesh's name. */
8262
+ readonly name: string;
8263
+ /**
8264
+ * Wraps a template mesh. Use the static factories; the engine constructs assets.
8265
+ *
8266
+ * @param name - A human-readable name.
8267
+ * @param mesh - The template, or `null` when the app is headless.
8268
+ * @param scene - The scene the template is released through, or `null` when there is nothing to
8269
+ * release.
8270
+ * @param geometry - The vertex arrays the asset was built from, when it came from
8271
+ * {@link MeshAsset.fromData}; `null` for a primitive, whose arrays Lite generated and never
8272
+ * handed back. It is what makes the `update*` methods legal.
8273
+ * @param engine - The engine an update writes through, or `null` under a headless app.
8274
+ *
8275
+ * @internal
8276
+ */
8277
+ constructor(name: string, mesh: LiteMesh | null, scene: LiteScene | null, geometry?: MeshGeometryData | null, engine?: LiteEngine | null);
8278
+ /**
8279
+ * The Babylon Lite objects the asset owns. Unstable escape hatch
8280
+ * (`docs/architecture/00-overview.md` §3).
8281
+ *
8282
+ * @returns The template mesh, or `null` under a headless app.
8283
+ */
8284
+ get lite(): MeshAssetLiteHandles;
8285
+ /**
8286
+ * Whether the template's GPU buffers have been released.
8287
+ *
8288
+ * @returns `true` once {@link MeshAsset.dispose} has run.
8289
+ */
8290
+ get isDisposed(): boolean;
8291
+ /**
8292
+ * The vertex arrays the asset was built from, for CPU-side work such as a light-probe bake.
8293
+ *
8294
+ * @returns The arrays for a mesh built with {@link MeshAsset.fromData}; `null` for a primitive.
8295
+ *
8296
+ * @internal
8297
+ */
8298
+ get cpuGeometry(): MeshGeometryData | null;
8299
+ /**
8300
+ * How many vertices the geometry has.
8301
+ *
8302
+ * @remarks
8303
+ * Known for a mesh built with {@link MeshAsset.fromData} — headless included — and `0` for a
8304
+ * primitive: Lite generates a primitive's arrays internally and 1.27.0's `Mesh` exposes no vertex
8305
+ * count, only the opaque `MeshGPU` handle it says a user never touches (`index.d.ts` 7230).
8306
+ *
8307
+ * @returns The vertex count, or `0`.
8308
+ */
8309
+ get vertexCount(): number;
8310
+ /**
8311
+ * How many indices the geometry has — three per triangle.
8312
+ *
8313
+ * @returns The index count, or `0`; see {@link MeshAsset.vertexCount}.
8314
+ */
8315
+ get indexCount(): number;
8316
+ /**
8317
+ * Re-uploads vertex positions and re-fits the bounds.
8318
+ *
8319
+ * @remarks
8320
+ * Only a mesh from {@link MeshAsset.fromData} can be updated, and only while nothing has cloned it:
8321
+ * Lite refuses to write a vertex buffer with more than one owner, and a `MeshRenderer` clone is a
8322
+ * second owner.
8323
+ *
8324
+ * Lite's `updateMeshPositions` writes the GPU buffer and stops there, so this also copies the range
8325
+ * into the asset's own position array — the one Lite retained and CPU picking reads — and rewrites
8326
+ * the bounds from the whole of it, `O(vertexCount)` per call. Passing the asset's own array skips
8327
+ * the copy.
8328
+ *
8329
+ * @param data - Three floats per vertex, read from index 0.
8330
+ * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
8331
+ * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
8332
+ * @throws IgnifxError with code `IGX-0702` when the mesh did not come from
8333
+ * {@link MeshAsset.fromData}, or has been disposed.
8334
+ * @throws IgnifxError with code `IGX-0725` when the range falls outside the mesh or `data` is too
8335
+ * short for it.
8336
+ *
8337
+ * @example
8338
+ * ```ts
8339
+ * const grid = MeshAsset.fromData(app, "grid", { positions, normals, indices });
8340
+ * positions[1] += 0.5;
8341
+ * grid.value.updatePositions(positions);
8342
+ * ```
8343
+ */
8344
+ updatePositions(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
8345
+ /**
8346
+ * Re-uploads vertex normals.
8347
+ *
8348
+ * @remarks
8349
+ * The same rules as {@link MeshAsset.updatePositions}, minus the bounds: a normal cannot move a
8350
+ * bounding box. The range is copied into the asset's own normal array so that a later
8351
+ * `updatePositions` sees a consistent mesh.
8352
+ *
8353
+ * @param data - Three floats per vertex.
8354
+ * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
8355
+ * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
8356
+ * @throws IgnifxError with code `IGX-0702` or `IGX-0725`; see
8357
+ * {@link MeshAsset.updatePositions}.
8358
+ */
8359
+ updateNormals(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
8360
+ /**
8361
+ * Re-uploads texture coordinates.
8362
+ *
8363
+ * @remarks
8364
+ * Lite makes the upload a **no-op** when the mesh was created without UVs, rather than an error,
8365
+ * so a mesh whose `MeshGeometryData` named none silently ignores this. The range check still runs.
8366
+ *
8367
+ * @param data - Two floats per vertex.
8368
+ * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
8369
+ * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
8370
+ * @throws IgnifxError with code `IGX-0702` or `IGX-0725`; see
8371
+ * {@link MeshAsset.updatePositions}.
8372
+ */
8373
+ updateUvs(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
8374
+ /**
8375
+ * Re-uploads vertex colours.
8376
+ *
8377
+ * @remarks
8378
+ * Four floats per vertex, linear RGBA. A no-op on the GPU when the mesh was created without
8379
+ * colours, exactly as {@link MeshAsset.updateUvs} is.
8380
+ *
8381
+ * @param data - Four floats per vertex.
8382
+ * @param vertexOffset - The first vertex to overwrite. Defaults to `0`.
8383
+ * @param vertexCount - How many vertices to write. Defaults to as many as `data` holds.
8384
+ * @throws IgnifxError with code `IGX-0702` or `IGX-0725`; see
8385
+ * {@link MeshAsset.updatePositions}.
8386
+ */
8387
+ updateColors(data: Float32Array, vertexOffset?: number, vertexCount?: number): void;
8388
+ /**
8389
+ * Releases the template's GPU buffers.
8390
+ *
8391
+ * @remarks
8392
+ * Lite exports no mesh disposer: a mesh's buffers are freed when it leaves its last scene, so the
8393
+ * adapter adds the template to a scene and takes it straight out again
8394
+ * (`src/lite/gpu/mesh.ts`). Clones still in a scene keep the shared buffers alive; what the
8395
+ * template loses is the ability to be cloned again. Calling it twice is a no-op, and it is a
8396
+ * no-op under a headless app, which has no buffers.
8397
+ */
8398
+ dispose(): void;
8399
+ /** Releases the template when the asset leaves a `using` block. */
8400
+ [Symbol.dispose](): void;
8401
+ /**
8402
+ * Creates a box template and publishes it.
8403
+ *
8404
+ * @param app - The app whose engine uploads the geometry and whose asset service holds the handle.
8405
+ * @param options - A uniform `size`, or per-axis dimensions.
8406
+ * @returns The handle, with one holder — the caller.
8407
+ *
8408
+ * @example
8409
+ * ```ts
8410
+ * const box = MeshAsset.box(app, { width: 2, height: 1, depth: 3 });
8411
+ * ```
8412
+ */
8413
+ static box(app: App, options?: BoxMeshOptions): AssetHandle<MeshAsset>;
8414
+ /**
8415
+ * Creates a sphere template and publishes it.
8416
+ *
8417
+ * @param app - The app that owns the engine and the asset service.
8418
+ * @param options - Diameter and ring count.
8419
+ * @returns The handle, with one holder.
8420
+ */
8421
+ static sphere(app: App, options?: SphereMeshOptions): AssetHandle<MeshAsset>;
8422
+ /**
8423
+ * Creates a quad template in the XY plane and publishes it.
8424
+ *
8425
+ * @param app - The app that owns the engine and the asset service.
8426
+ * @param options - A uniform `size`, or width and height.
8427
+ * @returns The handle, with one holder.
8428
+ */
8429
+ static plane(app: App, options?: PlaneMeshOptions): AssetHandle<MeshAsset>;
8430
+ /**
8431
+ * Creates a subdivided grid in the XZ plane and publishes it.
8432
+ *
8433
+ * @param app - The app that owns the engine and the asset service.
8434
+ * @param options - Width, depth, subdivisions, and UV scale.
8435
+ * @returns The handle, with one holder.
8436
+ */
8437
+ static ground(app: App, options?: GroundMeshOptions): AssetHandle<MeshAsset>;
8438
+ /**
8439
+ * Creates a cylinder template standing along Y and publishes it.
8440
+ *
8441
+ * @param app - The app that owns the engine and the asset service.
8442
+ * @param options - Height, diameters, and tessellation.
8443
+ * @returns The handle, with one holder.
8444
+ */
8445
+ static cylinder(app: App, options?: CylinderMeshOptions): AssetHandle<MeshAsset>;
8446
+ /**
8447
+ * Creates a capsule template standing along Y and publishes it.
8448
+ *
8449
+ * @param app - The app that owns the engine and the asset service.
8450
+ * @param options - Total height, radius, and tessellation.
8451
+ * @returns The handle, with one holder.
8452
+ */
8453
+ static capsule(app: App, options?: CapsuleMeshOptions): AssetHandle<MeshAsset>;
8454
+ /**
8455
+ * Creates a torus template in the XZ plane and publishes it.
8456
+ *
8457
+ * @param app - The app that owns the engine and the asset service.
8458
+ * @param options - Diameter, thickness, and tessellation.
8459
+ * @returns The handle, with one holder.
8460
+ */
8461
+ static torus(app: App, options?: TorusMeshOptions): AssetHandle<MeshAsset>;
8462
+ /**
8463
+ * Creates a template from raw vertex data and publishes it.
8464
+ *
8465
+ * @param app - The app that owns the engine and the asset service.
8466
+ * @param name - A human-readable name.
8467
+ * @param data - Positions, normals, indices, and any of the four optional attributes. Lite keeps
8468
+ * references to the arrays; a caller that means to edit them afterwards does so through the
8469
+ * `update*` methods, which keep Lite's own copy and its bounds in step.
8470
+ * @returns The handle, with one holder.
8471
+ *
8472
+ * @example
8473
+ * ```ts
8474
+ * const triangle = MeshAsset.fromData(app, "triangle", {
8475
+ * positions: Float32Array.from([0, 0, 0, 1, 0, 0, 0, 1, 0]),
8476
+ * normals: Float32Array.from([0, 0, -1, 0, 0, -1, 0, 0, -1]),
8477
+ * indices: Uint32Array.from([0, 1, 2]),
8478
+ * });
8479
+ * ```
8480
+ */
8481
+ static fromData(app: App, name: string, data: MeshGeometryData): AssetHandle<MeshAsset>;
8482
+ }
8483
+ //#endregion
8484
+ //#region src/render/mesh-renderer.d.ts
8485
+ /**
8486
+ * The `MeshRenderer` component (`docs/architecture/07-rendering.md` §2.3): one clone of a
8487
+ * `MeshAsset`, drawn with a `MaterialAsset`.
8488
+ *
8489
+ * ## Cloning, not sharing
8490
+ *
8491
+ * The asset holds the template; the renderer holds a clone parented under the entity's node.
8492
+ * `cloneTransformNode` shallow-clones the mesh — fresh transform, **same** `_gpu` wrapper with its
8493
+ * reference count bumped — so a hundred renderers of one asset upload one set of vertex buffers
8494
+ * (ADR-0002 Validation). Removing the component calls `removeFromScene` on the clone, which is what
8495
+ * frees its share.
8496
+ *
8497
+ * ## Hiding is `visible`, never removal
8498
+ *
8499
+ * Lite disposes a mesh that leaves its last scene, so `enabled = false` must not remove anything.
8500
+ * `visible` is derived from `entity.activeInHierarchy && component.enabled` and written on the
8501
+ * clone's subtree; the mesh stays in the scene, keeps its buffers, and comes back the moment the
8502
+ * flag flips. That is `07-rendering.md` §2.3's rule, and the browser test asserts both halves: the
8503
+ * pixel returns to the clear colour, and the mesh is still in the scene.
8504
+ *
8505
+ * `displayHidden` hides the same way, and makes the clone unpickable too, but is not a field: scene
8506
+ * files do not save it, so a system
8507
+ * that chooses what is drawn without changing the document (a `LodGroup` in an edit-mode app,
8508
+ * ADR-0028) switches it instead of `enabled`.
8509
+ *
8510
+ * ## Decisions the documents left open
8511
+ *
8512
+ * - **The clone's Lite `id` is the entity's uid.** Lite's light include/exclude lists match on
8513
+ * `Mesh.id` strings (`lib/render/lights-ubo.js`), and §2.2 maps `Light.includeOnly` onto them
8514
+ * from *entity* references. The uid is the one identifier both sides can name.
8515
+ * - **`materials` beyond the first is accepted and ignored.** §2.3 says "one per submesh", but
8516
+ * Lite's `Mesh.material` is a single value and Lite has no submesh material list in 1.27.0, so
8517
+ * there is nothing for the extra entries to drive. The field keeps its array shape so files do
8518
+ * not have to change if submeshes land; the renderer uses index 0, or the default material when
8519
+ * the array is empty.
8520
+ *
8521
+ * ## Headless
8522
+ *
8523
+ * A headless `MeshAsset` carries no geometry, so there is nothing to clone: the component keeps its
8524
+ * fields, reports `lite.mesh === null`, and touches no scene (`07-rendering.md` §6).
8525
+ */
8526
+ /**
8527
+ * How a lightmap combines with a material's shading: `"add"` adds the baked light to it,
8528
+ * `"shadowmap"` multiplies it (Babylon Lite's `useAsShadowmap`).
8529
+ *
8530
+ * @beta
8531
+ */
8532
+ declare const LIGHTMAP_MODES: readonly ["add", "shadowmap"];
8533
+ /**
8534
+ * One of {@link LIGHTMAP_MODES}.
8535
+ *
8536
+ * @beta
8537
+ */
8538
+ type LightmapMode = (typeof LIGHTMAP_MODES)[number];
8539
+ /**
8540
+ * The `lightmap` record of a {@link MeshRenderer} (GI Phase 2, step B3).
8541
+ *
8542
+ * @remarks
8543
+ * Mutable, because a schema `record()` field is a plain object a script edits in place.
8544
+ *
8545
+ * @beta
8546
+ */
8547
+ interface MeshRendererLightmap {
8548
+ /** The `.lightmap.json` to sample, or `null` for none. */
8549
+ asset: AssetHandle<LightmapAsset> | null;
8550
+ /** Add the baked light, or multiply the shading by it. */
8551
+ mode: LightmapMode;
8552
+ /** A multiplier on the sample. */
8553
+ level: number;
8554
+ /** Decode the sample from sRGB to linear; leave it off for a texture already decoded on load. */
8555
+ gamma: boolean;
8556
+ /** Sample with the mesh's second UV set (`uvs2`); `false` uses the first. */
8557
+ uv2: boolean;
8558
+ }
8559
+ /**
8560
+ * Draws a mesh asset with a material (`docs/architecture/07-rendering.md` §2.3).
8561
+ *
8562
+ * @example
8563
+ * ```ts
8564
+ * const box = MeshAsset.box(app, { size: 1 }); // release it once nothing draws it
8565
+ * const cube = world.createEntity("Cube");
8566
+ * cube.addComponent(MeshRenderer, { mesh: box, castShadows: true });
8567
+ * ```
8568
+ *
8569
+ * @public
8570
+ */
8571
+ declare class MeshRenderer extends Component implements ComponentHooks {
8572
+ #private;
8573
+ /** The namespaced registration id. */
8574
+ static typeId: string;
8575
+ /** What the component does, in one line, for an inspector. */
8576
+ static description: string;
8577
+ /** Several renderers on one entity draw several meshes from one transform, which is useful. */
8578
+ static allowMultiple: boolean;
8579
+ /** The serialized field declarations (ADR-0004). */
8580
+ static schema: Schema;
8581
+ mesh: AssetHandle<MeshAsset> | null;
8582
+ materials: (AssetHandle<MaterialAsset> | null)[];
8583
+ castShadows: boolean;
8584
+ receiveShadows: boolean;
8585
+ renderOrder: number;
8586
+ pickable: boolean;
8587
+ /**
8588
+ * A baked lightmap, or `null` (default) for none (GI Phase 2, step B3).
8589
+ *
8590
+ * @remarks
8591
+ * Only a renderer on a static entity (`entity.isStatic`) with a PBR material samples it; it then
8592
+ * draws with its own copy of the material (`MaterialAsset.clone`), so later edits of the shared
8593
+ * material do not reach it. Anything else draws without the lightmap and logs `IGX-0735` once.
8594
+ * The GPU code loads only once a renderer samples one, and headless nothing happens.
8595
+ *
8596
+ * @beta
8597
+ */
8598
+ lightmap: MeshRendererLightmap | null;
8599
+ /** Applies the schema defaults, exactly as `Component.define` would. */
8600
+ constructor();
8601
+ /**
8602
+ * The Babylon Lite mesh this renderer draws. Unstable escape hatch
8603
+ * (`docs/architecture/00-overview.md` §3).
8604
+ *
8605
+ * @returns The clone, or `null` when there is nothing to draw.
8606
+ */
8607
+ get lite(): {
8608
+ readonly mesh: LiteSceneNode | null;
8609
+ };
8610
+ /**
8611
+ * A display-only hide: while `true` the mesh is neither drawn nor picked, whatever `enabled` and
8612
+ * `pickable` say.
8613
+ *
8614
+ * @remarks
8615
+ * It is not a schema field, so scene files do not save it, a serializer never reads it, and
8616
+ * `enabled` keeps its authored value. That makes it the switch for a system that chooses what is
8617
+ * drawn without changing the document: `@ignifx/3d`'s `LodGroup` uses it in place of `enabled` in
8618
+ * an edit-mode app (ADR-0028). It starts `false` and takes effect at the next render sync;
8619
+ * {@link MeshRenderer.isVisible} reports the outcome. Lite's pickers ignore visibility, so the
8620
+ * clone is also made unpickable while hidden: `app.renderer.pickAsync` and `world.raycastRender`
8621
+ * neither return it nor let it occlude, as with `pickable: false`.
8622
+ *
8623
+ * It is one flag with one owner, not a count. In an edit-mode app the `LodGroup` that lists the
8624
+ * renderer as a level owns it: the group sets and clears it whenever it switches, so a value
8625
+ * written by anything else lasts only until then. A renderer belongs to at most one `LodGroup`; a
8626
+ * second group that lists it leaves it alone and warns with `IGX-1217`.
8627
+ *
8628
+ * @returns `true` while the mesh is hidden for display.
8629
+ *
8630
+ * @example
8631
+ * ```ts
8632
+ * renderer.displayHidden = true; // not drawn, and `renderer.enabled` is still `true`
8633
+ * ```
8634
+ */
8635
+ get displayHidden(): boolean;
8636
+ /**
8637
+ * Hides the mesh for display, or shows it again; `enabled` is not touched.
8638
+ *
8639
+ * @param value - `true` to hide it.
8640
+ */
8641
+ set displayHidden(value: boolean);
8642
+ /**
8643
+ * Whether the mesh is currently drawn: its own `enabled` flag and its entity's
8644
+ * `activeInHierarchy`, less {@link MeshRenderer.displayHidden}, materialised onto Lite's
8645
+ * `visible`.
8646
+ *
8647
+ * @returns `true` when the clone is visible.
8648
+ */
8649
+ get isVisible(): boolean;
8650
+ /** Nothing to do at attach: the clone is built on the first sync, once `mesh` has been decoded. */
8651
+ onAttach(): void;
8652
+ /** Removes the clone from the scene, releasing its share of the template's buffers. */
8653
+ onDetach(): void;
8654
+ /**
8655
+ * Rebuilds the clone when `mesh` changed, then writes every other field that changed. The
8656
+ * `PreRender` system calls it.
8657
+ *
8658
+ * @param renderer - The rendering service, for the scene and the default material.
8659
+ * @returns `true` when the scene's renderable set changed, which the system coalesces into one
8660
+ * `rebuildSceneRenderables`.
8661
+ *
8662
+ * @internal
8663
+ */
8664
+ sync(renderer: RendererImpl): boolean;
8665
+ /**
8666
+ * Whether the material this renderer draws with is a `"shader"` material.
8667
+ *
8668
+ * @remarks
8669
+ * The render sync system asks before it builds an ESM caster list: Babylon Lite 1.27.0 has no ESM
8670
+ * shadow view for the shader family and writes the fragment colour's red channel into the map
8671
+ * (`lib/shadow/esm-directional-shadow-generator.js` 230–245), so such a mesh is left out of it and
8672
+ * reported once with `IGX-0724`. PCF and CSM generators take it.
8673
+ *
8674
+ * @returns `true` when the first declared material is loaded and is a shader material.
8675
+ *
8676
+ * @internal
8677
+ */
8678
+ get usesShaderMaterial(): boolean;
8679
+ /**
8680
+ * Appends this renderer's mesh to a shadow caster list, when it casts.
8681
+ *
8682
+ * @param out - The caster list being built.
8683
+ *
8684
+ * @internal
8685
+ */
8686
+ collectCasters(out: LiteMesh[]): void;
8687
+ /**
8688
+ * Whether the caster contribution of this renderer changed since the last frame.
8689
+ *
8690
+ * @returns `true` when `castShadows` or visibility moved.
8691
+ *
8692
+ * @internal
7695
8693
  */
7696
- setDefine(name: string, value: boolean | number): void;
8694
+ consumeCasterChange(): boolean;
8695
+ }
8696
+ //#endregion
8697
+ //#region src/render/gpu/lightmap-host.d.ts
8698
+ /**
8699
+ * The renderer's handle on lightmaps (GI B3): it decides whether a `MeshRenderer` samples its
8700
+ * lightmap, loads the lightmap chunk (`./lightmaps.ts`) the first time one does, and hands the
8701
+ * renderer its lightmapped material. Device-only, like the rest of `src/render/gpu/`: only a
8702
+ * renderer with a clone in the scene asks.
8703
+ *
8704
+ * @internal
8705
+ */
8706
+ declare class LightmapHost {
8707
+ #private;
7697
8708
  /**
7698
- * Binds a read-only storage buffer to one of the shader's declared bindings.
8709
+ * Creates the host; nothing loads until a renderer samples a lightmap.
7699
8710
  *
7700
- * @param name - The declared binding's name.
7701
- * @param buffer - The buffer, or `null` to unbind. A shader material with an unbound declared
7702
- * storage buffer is not drawable ({@link MaterialAsset.isDrawable}).
7703
- * @throws IgnifxError with code `IGX-0718` unless this is a `"shader"` material, or `IGX-0712`
7704
- * when the shader declares no such storage buffer.
8711
+ * @param app - The app, for the clones and the log.
8712
+ * @param scene - The registered render scene.
8713
+ * @param onError - Where a failed chunk load goes.
7705
8714
  */
7706
- setStorageBuffer(name: string, buffer: AssetHandle<StorageBufferAsset> | null): void;
8715
+ constructor(app: App, scene: LiteScene, onError: (error: unknown) => void);
7707
8716
  /**
7708
- * Releases what the material holds beyond its Babylon Lite object: a shader material's per-frame
7709
- * uniform registration and its hot-reload hook.
8717
+ * How many renderers draw with a lightmap right now.
7710
8718
  *
7711
- * @remarks
7712
- * The `material` asset type's `unload` runs it when the last holder releases the handle, so a
7713
- * game that pairs `load`/`release` or uses `using` never has to. Calling it twice is a no-op, and
7714
- * it is a no-op on a PBR or Standard material, which own nothing of the kind.
8719
+ * @returns The number of lightmapped clones.
7715
8720
  */
7716
- dispose(): void;
8721
+ get count(): number;
7717
8722
  /**
7718
- * Builds an independent copy of this material from the same declaration — the per-renderer
7719
- * variation path of `docs/architecture/07-rendering.md` §2.6.
8723
+ * The material a renderer draws with this frame.
7720
8724
  *
7721
8725
  * @remarks
7722
- * The copy shares the original's *textures* (they are addressed assets, and the handles are
7723
- * retained by whoever loaded them) and nothing else: it is a second Lite material in the same
7724
- * family, so it costs no extra shader compilation.
8726
+ * A renderer samples its lightmap when its `lightmap.asset` is loaded, its entity is static and its
8727
+ * material is PBR; otherwise it draws with `base`, and a static or PBR mismatch logs `IGX-0735`
8728
+ * once. A placement other than the identity also logs `IGX-0735`, and the whole texture is used.
7725
8729
  *
7726
- * @param app - The app whose asset service publishes the copy.
7727
- * @returns The copy's handle, with one holder — the caller.
8730
+ * @param owner - The renderer.
8731
+ * @param base - The material it declares (or the default material).
8732
+ * @returns The Lite material to draw with.
7728
8733
  */
7729
- clone(app: App): AssetHandle<MaterialAsset>;
8734
+ materialFor(owner: MeshRenderer, base: MaterialAsset): LiteMaterial;
8735
+ /**
8736
+ * Drops a renderer's lightmapped clone, if it has one.
8737
+ *
8738
+ * @param owner - The renderer.
8739
+ */
8740
+ release(owner: MeshRenderer): void;
8741
+ /** Rebuilds the clones made this frame; the renderer calls it after every `MeshRenderer` synced. */
8742
+ flush(): void;
8743
+ /** Drops every clone. Idempotent. */
8744
+ dispose(): void;
7730
8745
  }
8746
+ //#endregion
8747
+ //#region src/render/reflection-probe.d.ts
7731
8748
  /**
7732
- * Builds a Lite material from a declaration and publishes it as an in-memory asset.
7733
- *
7734
- * @param app - The app whose asset service publishes it.
7735
- * @param definition - The declaration.
7736
- * @param textures - The texture handles the declaration's slots resolved to, in slot order.
7737
- * @returns The handle, with one holder — the caller.
8749
+ * The `ReflectionProbe` component (`docs/plan/2026-11-gi-phase-2-execution-plan.md`, step B1).
7738
8750
  *
7739
- * @example
7740
- * ```ts
7741
- * using red = createMaterialAsset(app, pbrMaterialDefinition({ name: "red", baseColor: { r: 1, g: 0, b: 0, a: 1 } }), []);
7742
- * ```
8751
+ * The component only holds settings and the "capture again" request. The renderer loads the probe's
8752
+ * GPU code (`./gpu/reflection-probes.ts`, `../lite/gpu/reflection-probe.ts`) only once a world has
8753
+ * a probe, so a project without one pays nothing for it (`CONSTITUTION.md` §2.5). Headless, a probe
8754
+ * captures nothing.
8755
+ */
8756
+ /**
8757
+ * The `as const` name table behind {@link ReflectionProbeRefreshMode}.
7743
8758
  *
7744
8759
  * @public
7745
8760
  */
7746
- declare function createMaterialAsset(app: App, definition: MaterialDefinition, textures: readonly AssetHandle<TextureAsset>[]): AssetHandle<MaterialAsset>;
8761
+ declare const REFLECTION_PROBE_REFRESH_MODES: readonly ["once", "onDemand", "everyFrame"];
7747
8762
  /**
7748
- * Fills in a PBR declaration's defaults, so callers name only what they mean to change.
7749
- *
7750
- * @param overrides - The properties to set.
7751
- * @returns A complete declaration.
8763
+ * When a reflection probe renders its cube map again.
7752
8764
  *
7753
- * @example
7754
- * ```ts
7755
- * pbrMaterialDefinition({ name: "gold", metallic: 1, roughness: 0.25 });
7756
- * ```
8765
+ * @remarks
8766
+ * - `"once"` (default): when the probe is first ready, and again on {@link ReflectionProbe.refresh}.
8767
+ * - `"onDemand"`: only on {@link ReflectionProbe.refresh}; until then the probe reflects nothing.
8768
+ * - `"everyFrame"`: every frame, six extra scene passes each frame. Use it for one probe at most, on
8769
+ * desktop. The `low` and `medium` quality tiers (`rendering.quality`) treat it as `"once"`.
7757
8770
  *
7758
8771
  * @public
7759
8772
  */
7760
- declare function pbrMaterialDefinition(overrides?: Partial<Omit<PbrMaterialDefinition, "kind">>): PbrMaterialDefinition;
8773
+ type ReflectionProbeRefreshMode = (typeof REFLECTION_PROBE_REFRESH_MODES)[number];
7761
8774
  /**
7762
- * Fills in a Standard declaration's defaults.
8775
+ * A point that captures the scene around it into a cube map, which nearby shiny PBR materials then
8776
+ * reflect instead of the scene environment.
7763
8777
  *
7764
- * @param overrides - The properties to set.
7765
- * @returns A complete declaration.
8778
+ * @remarks
8779
+ * Each lit PBR material reflects the nearest enabled probe that has captured: a probe whose
8780
+ * `boxProjection` box holds the mesh wins over one that does not, then the closer probe wins. With no
8781
+ * probe, materials reflect the `Environment` again. A material shared by several meshes follows the
8782
+ * first of them. Diffuse lighting still comes from the scene environment.
7766
8783
  *
7767
- * @public
8784
+ * The probe needs a loaded `Environment` (it reuses its lighting tables) and a canvas-backed app;
8785
+ * until an environment map is loaded it waits, holding no GPU memory and costing no frame time. A
8786
+ * `rendering.quality` tier caps `size` and allows `"everyFrame"` only at `high` (below, the probe
8787
+ * captures as `"once"`); with the `custom` tier nothing is capped.
8788
+ * Mip levels are box-filtered, so very rough materials look blurrier than with a prefiltered `.env`.
8789
+ *
8790
+ * @example
8791
+ * ```ts
8792
+ * const probe = world.createEntity("Room probe", { position: { x: 0, y: 1.5, z: 0 } });
8793
+ * probe.addComponent(ReflectionProbe, { size: 128, boxProjection: { x: 8, y: 3, z: 8 } });
8794
+ * ```
8795
+ *
8796
+ * @beta
7768
8797
  */
7769
- declare function standardMaterialDefinition(overrides?: Partial<Omit<StandardMaterialDefinition, "kind">>): StandardMaterialDefinition;
8798
+ declare class ReflectionProbe extends Component {
8799
+ #private;
8800
+ /** The namespaced registration id. */
8801
+ static typeId: string;
8802
+ /** What the component does, in one line, for an inspector. */
8803
+ static description: string;
8804
+ /** One probe per entity. */
8805
+ static allowMultiple: boolean;
8806
+ /** The serialized field declarations (ADR-0004). */
8807
+ static schema: Schema;
8808
+ /**
8809
+ * Cube face size in pixels, rounded down to a power of two from 16 to 1024. Defaults to `128`. A
8810
+ * `rendering.quality` tier caps it: 64 at `low`, 128 at `medium`, 256 at `high`.
8811
+ */
8812
+ size: number;
8813
+ /** When the probe captures again. Defaults to `"once"`. */
8814
+ refreshMode: ReflectionProbeRefreshMode;
8815
+ /**
8816
+ * The full size, in metres, of the box (centred on the probe) that reflections are projected onto,
8817
+ * or `null` (default) for no box: reflections then look infinitely far away.
8818
+ */
8819
+ boxProjection: Vec3Like | null;
8820
+ /** The layer names the probe captures; empty (default) captures every layer. */
8821
+ cullingMask: readonly string[];
8822
+ /** The near clip distance of the capture, in metres. Defaults to `0.1`. */
8823
+ near: number;
8824
+ /** The far clip distance of the capture, in metres. Defaults to `1000`. */
8825
+ far: number;
8826
+ /** Applies the schema defaults, exactly as `Component.define` would. */
8827
+ constructor();
8828
+ /**
8829
+ * Asks the probe to capture again from the next frame, whatever its `refreshMode`.
8830
+ *
8831
+ * @remarks
8832
+ * Call it after the static scene around the probe changed, such as a door opening. A capture
8833
+ * repeats over a few frames, so meshes whose materials are still compiling are caught.
8834
+ */
8835
+ refresh(): void;
8836
+ /**
8837
+ * Reads and clears the request {@link ReflectionProbe.refresh} made.
8838
+ *
8839
+ * @returns Whether a capture was requested since the last call.
8840
+ *
8841
+ * @internal
8842
+ */
8843
+ consumeRefreshRequest(): boolean;
8844
+ }
7770
8845
  //#endregion
7771
8846
  //#region src/lite/render-features.d.ts
7772
8847
  /**
@@ -7875,9 +8950,14 @@ type AmbientOcclusionQuality = (typeof AMBIENT_OCCLUSION_QUALITIES)[number];
7875
8950
  *
7876
8951
  * @remarks
7877
8952
  * - `"custom"` (default): every effect is exactly as the section and the `PostProcessStack`s say.
7878
- * - `"low"`: GTAO at half resolution; no HDR, TAA, contact shadows or SSGI.
7879
- * - `"medium"`: adds HDR and TAA, and lets a stack run contact shadows.
7880
- * - `"high"`: GTAO at full resolution, and lets a stack run SSGI.
8953
+ * - `"low"`: GTAO at half resolution; no HDR, TAA, contact shadows or SSGI; reflection probes at
8954
+ * 64 pixels a face at most.
8955
+ * - `"medium"`: adds HDR and TAA, lets a stack run contact shadows, and reflection probes up to 128.
8956
+ * - `"high"`: GTAO at full resolution, lets a stack run SSGI, reflection probes up to 256, and lets
8957
+ * a probe capture every frame.
8958
+ *
8959
+ * Below `"high"`, a `ReflectionProbe` with `refreshMode: "everyFrame"` captures as `"once"`.
8960
+ * Light probes and lightmaps run at every tier.
7881
8961
  *
7882
8962
  * @public
7883
8963
  */
@@ -7906,6 +8986,10 @@ interface RenderingQualityPreset {
7906
8986
  readonly contactShadows: boolean;
7907
8987
  /** Whether a `PostProcessStack`'s `ssgi` record may run. */
7908
8988
  readonly ssgi: boolean;
8989
+ /** The largest cube face a `ReflectionProbe` captures at, in pixels; a larger `size` is clamped. */
8990
+ readonly reflectionProbeMaxSize: number;
8991
+ /** Whether a `ReflectionProbe` may use `refreshMode: "everyFrame"`; below, it acts as `"once"`. */
8992
+ readonly reflectionProbeEveryFrame: boolean;
7909
8993
  }
7910
8994
  /**
7911
8995
  * Screen-space ambient occlusion (GTAO) on indirect light: `rendering.ambientOcclusion`
@@ -8141,6 +9225,51 @@ declare function defaultAutoExposureSettings(): AutoExposureSettings;
8141
9225
  */
8142
9226
  declare function defaultRenderingSettings(): RenderingSettings;
8143
9227
  //#endregion
9228
+ //#region src/render/gpu/reflection-probe-host.d.ts
9229
+ /**
9230
+ * The renderer's handle on reflection probes (GI B1): it loads the probe chunk
9231
+ * (`./reflection-probes.ts`) the first frame a world has a probe and forwards every frame to it.
9232
+ * Device-only, like the rest of `src/render/gpu/`: a headless renderer never creates one.
9233
+ *
9234
+ * @internal
9235
+ */
9236
+ declare class ReflectionProbeHost {
9237
+ #private;
9238
+ /**
9239
+ * Creates the host; nothing loads until a probe exists.
9240
+ *
9241
+ * @param engine - The engine.
9242
+ * @param scene - The registered render scene.
9243
+ * @param onError - Where a failed chunk load goes.
9244
+ * @param warn - Where a probe's warning goes: a message with an `{entity}` slot, and the name.
9245
+ */
9246
+ constructor(engine: LiteEngine, scene: LiteScene, onError: (error: unknown) => void, warn: (message: string, entityName: string) => void);
9247
+ /**
9248
+ * Whether the chunk is loaded and running.
9249
+ *
9250
+ * @returns `true` once a probe has loaded it.
9251
+ */
9252
+ get isActive(): boolean;
9253
+ /**
9254
+ * Runs one frame of probe work, loading the chunk first when a probe exists.
9255
+ *
9256
+ * @param world - The world.
9257
+ * @param probes - Every `ReflectionProbe` in it.
9258
+ * @param isHdr - Whether `rendering.hdr` is on.
9259
+ * @param tier - The `rendering.quality` preset; `null` for `"custom"`.
9260
+ * @param hasEnvironment - Whether the scene has an environment map; until it has, the chunk is
9261
+ * not even loaded, since a probe needs the map's lighting tables.
9262
+ */
9263
+ update(world: World, probes: readonly ReflectionProbe[], isHdr: boolean, tier: RenderingQualityPreset | null, hasEnvironment: boolean): void;
9264
+ /**
9265
+ * Drops the probes' GPU state when the device is lost (`app.events.onDeviceLost`), before Lite's
9266
+ * recovery rebuilds the materials; they capture again once frames resume.
9267
+ */
9268
+ handleDeviceLost(): void;
9269
+ /** Frees every probe. Idempotent. */
9270
+ dispose(): void;
9271
+ }
9272
+ //#endregion
8144
9273
  //#region src/lite/gpu/render-path.d.ts
8145
9274
  /**
8146
9275
  * The HDR half of a presenter, when `rendering.hdr` built one (`./hdr-output.ts`).
@@ -8231,6 +9360,14 @@ interface ScenePass {
8231
9360
  readonly target: RenderTarget;
8232
9361
  /** That target's colour format. */
8233
9362
  readonly format: GPUTextureFormat;
9363
+ /**
9364
+ * Whether a post-process task may write {@link ScenePass.target} directly. `false` on the plain
9365
+ * path: its target is allocated lazily, and a post-process task that writes it reallocates it in
9366
+ * `record()` (Lite's `buildRenderTarget`, `lib/engine/render-target.js`), destroying the texture
9367
+ * the scene task and every pass recorded before it hold, so the frame is rejected and presents
9368
+ * black. The HDR target is eager and survives that.
9369
+ */
9370
+ readonly isTargetWritable: boolean;
8234
9371
  }
8235
9372
  //#endregion
8236
9373
  //#region src/lite/gpu/scene-inputs.d.ts
@@ -9375,17 +10512,56 @@ declare class RendererImpl implements Renderer {
9375
10512
  */
9376
10513
  updateAmbientOcclusion(): void;
9377
10514
  /**
9378
- * The reflection probes' per-frame work (`ReflectionProbe`, GI B1): loads their chunk the first
9379
- * time a world has one, then captures what is due and points each lit PBR material at its probe.
9380
- * The `PreRender` system calls it every frame; it does nothing until a probe exists, and nothing
9381
- * on a headless app.
10515
+ * The baked-lighting components' per-frame work (GI Phase 2): `ReflectionProbe` (B1) captures
10516
+ * what is due and points each lit PBR material at its probe; `LightProbeVolume` (B2) keeps the
10517
+ * winning grid on every lit PBR material; lightmaps (B3) rebuild the material copies the
10518
+ * `MeshRenderer`s took this frame. Each loads its own chunk the first time a world has one
10519
+ * of its components. The `PreRender` system calls it every frame; it does nothing on a headless
10520
+ * app.
9382
10521
  *
9383
10522
  * @param world - The world being reconciled.
9384
10523
  * @param probes - Every `ReflectionProbe` in it.
10524
+ * @param volumes - Every `LightProbeVolume` in it.
10525
+ *
10526
+ * @internal
10527
+ */
10528
+ updateBakedLighting(world: World, probes: readonly ReflectionProbe[], volumes: readonly LightProbeVolume[]): void;
10529
+ /**
10530
+ * The material a `MeshRenderer` draws with this frame: its own lightmapped copy of `base` when it
10531
+ * samples a lightmap (GI B3), else `base`'s. Only a renderer with a clone in the scene asks, so
10532
+ * never a headless one.
10533
+ *
10534
+ * @param owner - The renderer.
10535
+ * @param base - The material asset it declares, or the default material.
10536
+ * @returns The Lite material.
10537
+ *
10538
+ * @internal
10539
+ */
10540
+ lightmapMaterial(owner: MeshRenderer, base: MaterialAsset): LiteMaterial;
10541
+ /**
10542
+ * Drops a `MeshRenderer`'s lightmapped material copy, if it has one.
10543
+ *
10544
+ * @param owner - The renderer.
10545
+ *
10546
+ * @internal
10547
+ */
10548
+ releaseLightmap(owner: MeshRenderer): void;
10549
+ /**
10550
+ * The lightmaps' host, for tests and diagnostics.
10551
+ *
10552
+ * @returns The host, or `null` before a renderer asked for a material.
9385
10553
  *
9386
10554
  * @internal
9387
10555
  */
9388
- updateReflectionProbes(world: World, probes: readonly ReflectionProbe[]): void;
10556
+ get lightmapHost(): LightmapHost | null;
10557
+ /**
10558
+ * The light probes' host, for tests and diagnostics.
10559
+ *
10560
+ * @returns The host, or `null` on a headless app and before the first frame.
10561
+ *
10562
+ * @internal
10563
+ */
10564
+ get lightProbeHost(): LightProbeHost | null;
9389
10565
  /**
9390
10566
  * The reflection probes' host, for tests and diagnostics.
9391
10567
  *
@@ -14691,6 +15867,113 @@ interface Extension {
14691
15867
  dispose?(app: App): void;
14692
15868
  }
14693
15869
  //#endregion
15870
+ //#region src/serialization/instance-targets.d.ts
15871
+ /**
15872
+ * Reads a prefab (or any scene) file by the address an `instance` entry names, for
15873
+ * {@link resolveInstancePath} and {@link enumerateInstanceTargets}.
15874
+ *
15875
+ * @remarks
15876
+ * The address is passed exactly as the entry's `scene.$asset` holds it. Return `null` or
15877
+ * `undefined` for a file that is not available; the walk then stops there, as the loader stops at
15878
+ * a scene that is not loaded.
15879
+ *
15880
+ * @param address - The instanced scene's address.
15881
+ * @returns The parsed file, or `null`/`undefined` when it cannot be read.
15882
+ *
15883
+ * @public
15884
+ */
15885
+ type PrefabReader = (address: string) => SceneFile | null | undefined;
15886
+ /**
15887
+ * One entity or component inside a prefab instance of a scene file, named by its instance path
15888
+ * (`docs/architecture/06-serialization-and-scene-format.md` §2).
15889
+ *
15890
+ * @public
15891
+ */
15892
+ interface InstanceTarget {
15893
+ /** What the path names: an `$entity` or a `$component` reference target. */
15894
+ readonly kind: "entity" | "component";
15895
+ /**
15896
+ * The instance path, `"<carrierUid>/…/<uid>"`: what a `{ "$entity" | "$component": … }`
15897
+ * reference in the scene writes to reach the target.
15898
+ */
15899
+ readonly path: string;
15900
+ /** The uid of the scene entity carrying the `instance` entry: the path's first segment. */
15901
+ readonly carrier: string;
15902
+ /** The address of the prefab file that declares the target, as its `instance` entry names it. */
15903
+ readonly address: string;
15904
+ /** The target's record in that file, or for a component the record of the entity holding it. */
15905
+ readonly entity: SceneFileEntity;
15906
+ /** The component's record, or `null` for an entity. */
15907
+ readonly component: SceneFileComponent | null;
15908
+ /**
15909
+ * The display names from the carrier down to {@link InstanceTarget.entity}: the carrier's name
15910
+ * first, then each entity's. A prefab's single root merges into the entity instancing it, so it
15911
+ * adds no name. A label reads `labels.join(" › ")`, plus the component type for a component.
15912
+ */
15913
+ readonly labels: readonly string[];
15914
+ /**
15915
+ * The prefix of an override path on the carrier's `instance` entry that addresses the target:
15916
+ * `"<entityUid>/components/<componentPath>"` for a component (append `/props/<field>` or
15917
+ * `/enabled`), where the component path is an instance path when the component sits in a nested
15918
+ * prefab, and `"<entityUid>"` for an entity of the instanced file itself. `null` for an entity
15919
+ * inside a nested prefab, which overrides do not reach.
15920
+ */
15921
+ readonly overridePath: string | null;
15922
+ }
15923
+ /**
15924
+ * Finds the entity or component an instance path names inside a scene file's prefab instances,
15925
+ * without loading anything: the rules the loader resolves `$entity` and `$component` references
15926
+ * by.
15927
+ *
15928
+ * @remarks
15929
+ * A pure function over files. The path's first segment is the uid of an entity of `scene` that
15930
+ * carries an `instance` entry; each later segment but the last names an entity of the prefab
15931
+ * reached so far that itself instances a prefab; the last names the target by the uid its own file
15932
+ * gives it. A prefab's single root merges into the entity instancing it, so a prefab that root
15933
+ * instances is searched at the same level, with no extra segment.
15934
+ *
15935
+ * @param scene - The scene file holding the path.
15936
+ * @param path - The instance path, `"<carrierUid>/…/<uid>"`.
15937
+ * @param readScene - Reads the prefab files the path walks through.
15938
+ * @param kind - What the reference expects: `"entity"` for `$entity`, `"component"` for
15939
+ * `$component`. Omitted, an entity is looked for first, then a component.
15940
+ * @returns The target, or `null` when the path is a plain uid or names nothing.
15941
+ *
15942
+ * @example
15943
+ * ```ts
15944
+ * const target = resolveInstancePath(sceneFile, "01J…CRATE/01J…LID", (address) => files.get(address));
15945
+ * ```
15946
+ *
15947
+ * @public
15948
+ */
15949
+ declare function resolveInstancePath(scene: SceneFile, path: string, readScene: PrefabReader, kind?: "entity" | "component"): InstanceTarget | null;
15950
+ /**
15951
+ * Lists every entity and component an instance path can reach inside a scene file's prefab
15952
+ * instances, with the path, a label chain, and the override path that addresses it.
15953
+ *
15954
+ * @remarks
15955
+ * A pure function over files, for tools such as an editor's reference picker. Each path is the
15956
+ * shortest form {@link resolveInstancePath} resolves. A prefab's single root is not listed as an
15957
+ * entity: it merges into the carrier, which the scene names by its plain uid; its components are
15958
+ * listed. Components an override `add`s are not listed: they keep no uid from a prefab file. The
15959
+ * walk stops at a file `readScene` cannot read, at a prefab that would instance itself, and 16
15960
+ * files deep.
15961
+ *
15962
+ * @param scene - The scene file.
15963
+ * @param readScene - Reads the prefab files.
15964
+ * @returns The targets, in scene order of their carriers, then depth first in file order.
15965
+ *
15966
+ * @example
15967
+ * ```ts
15968
+ * const components = enumerateInstanceTargets(sceneFile, (address) => files.get(address)).filter(
15969
+ * (target) => target.kind === "component",
15970
+ * );
15971
+ * ```
15972
+ *
15973
+ * @public
15974
+ */
15975
+ declare function enumerateInstanceTargets(scene: SceneFile, readScene: PrefabReader): InstanceTarget[];
15976
+ //#endregion
14694
15977
  //#region src/serialization/overrides.d.ts
14695
15978
  /**
14696
15979
  * The parsed form of an instance override `path`
@@ -14710,6 +15993,18 @@ interface Extension {
14710
15993
  * <uid>/components/<uid>/props/<field>[/<key>…] → prop
14711
15994
  * ```
14712
15995
  *
15996
+ * The component segment may also be an instance path, which reaches a component of a prefab the
15997
+ * instanced file itself instances: `"<nestedInstanceUid>/<componentUid>"`, where the first segment
15998
+ * is the uid of the entity carrying the nested `instance` entry in the instanced file and must
15999
+ * equal the path's entity segment, and the last is the uid the nested prefab file gives the
16000
+ * component. Deeper nesting adds one segment per nested instance, as in references
16001
+ * (`"<nestedInstanceUid>/<deeperInstanceUid>/<componentUid>"`). The component segment then runs up to
16002
+ * the first `props` or `enabled` segment, so a component uid cannot be either word.
16003
+ *
16004
+ * ```text
16005
+ * <uid>/components/<uid>/<uid>…/<uid>/props/<field> → prop, component "<uid>/<uid>…/<uid>"
16006
+ * ```
16007
+ *
14713
16008
  * @public
14714
16009
  */
14715
16010
  type OverridePath = {
@@ -14775,7 +16070,9 @@ interface PrefabOverrideSelection {
14775
16070
  * Override paths to act on. A path selects every override at that path or below it, so
14776
16071
  * `"<entityUid>"` selects everything on that entity and `"<entityUid>/components/<componentUid>"`
14777
16072
  * selects a component's removal, its `enabled` flag, and its props. An `add` to
14778
- * `<entityUid>/components` sits at `<entityUid>/components/<addedUid>`. Omitted, every override
16073
+ * `<entityUid>/components` sits at `<entityUid>/components/<addedUid>`. A component of a nested
16074
+ * prefab is selected by its instance path the same way:
16075
+ * `"<nestedInstanceUid>/components/<nestedInstanceUid>/<componentUid>"`. Omitted, every override
14779
16076
  * is selected.
14780
16077
  */
14781
16078
  readonly paths?: readonly string[];
@@ -14796,6 +16093,13 @@ interface PrefabApplyOptions extends PrefabOverrideSelection {
14796
16093
  * Omitted, none is applied.
14797
16094
  */
14798
16095
  readonly rootComponents?: readonly SceneFileComponent[];
16096
+ /**
16097
+ * Reads the prefabs the prefab file itself instances, by the address its `instance` entries name.
16098
+ * An override of a nested prefab's component (an instance path in its component segment) is
16099
+ * applied by moving it onto the nested `instance` entry of the prefab file, which needs the
16100
+ * nested file to find the entity holding the component. Omitted, such overrides are skipped.
16101
+ */
16102
+ readonly readScene?: PrefabReader;
14799
16103
  }
14800
16104
  /**
14801
16105
  * A component of the instance root that {@link applyOverridesToAsset} left on the instance, and why.
@@ -14865,9 +16169,12 @@ interface PrefabApplyResult {
14865
16169
  * - On a prefab with exactly one root, the instance root's own `name`, `transform`, and other entity
14866
16170
  * fields are its placement, not prefab content, so overrides of the root's entity fields and
14867
16171
  * transform are skipped.
14868
- * - Overrides reach only the prefab's own entities. Content of a scene the prefab itself instances
14869
- * is not addressable by an override path, so a nested prefab is never edited: an override that
14870
- * names something the prefab file does not hold is skipped.
16172
+ * - A nested prefab is never edited. An override of a nested prefab's component, whose component
16173
+ * segment is an instance path (`"<nestedInstanceUid>/<componentUid>"`), moves onto the prefab
16174
+ * file's nested `instance` entry instead, rewritten into that entry's own paths, replacing an
16175
+ * override there at the same path and op. It needs {@link PrefabApplyOptions.readScene}; without
16176
+ * it, or when the path names nothing, it is skipped. Any other override that names something the
16177
+ * prefab file does not hold is skipped.
14871
16178
  * - An override is skipped when an earlier override that stays on the instance overlaps its path, so
14872
16179
  * the instance keeps the value it had.
14873
16180
  * - A skipped override stays on the returned instance.
@@ -14921,5 +16228,5 @@ declare function applyOverridesToAsset(instance: SceneFileInstance, asset: Scene
14921
16228
  */
14922
16229
  declare function revertOverrides(instance: SceneFileInstance, selection?: PrefabOverrideSelection): SceneFileInstance;
14923
16230
  //#endregion
14924
- export { TWEEN_VALUE_KINDS as $, ComponentRefFieldSpec as $a, SceneFile as $i, RENDERING_SETTINGS_SECTION as $n, JsonObject as $o, SHADER_BLEND_MODES as $r, InstantiateOptions as $t, ServiceClassKey as A, QUAT_IDENTITY as Aa, Script as Ai, RenderOverlay as An, AssetLoader as Ao, LiteShaderMaterial as Ar, FRAME_HISTORY_LENGTH as At, WaitInstruction as B, Vec3Like as Ba, decodeValue as Bi, forceRendererDeviceLossForTesting as Bn, FetchLike as Bo, TEXTURE_ASSET_TYPE as Br, ComponentInitValue as Bt, FrameState as C, VEC3_RIGHT as Ca, ReflectionProbeRefreshMode as Ci, RENDER_TEXTURE_MAX_SIZE as Cn, ScriptCallbackKind as Co, LitePbrMaterial as Cr, HotReloadModule as Ct, Phase as D, VEC2_ONE as Da, RESERVED_LAYER_NAMES as Di, RENDER_DIAGNOSTICS_COUNTERS as Dn, AssetHandle as Do, SurfaceShaderBinding as Dr, HotReloadStatics as Dt, PHASE_NAMES as E, Vec3 as Ea, MAX_LAYERS as Ei, FrameWaitOptions as En, INVALID_HANDLE as Eo, MaterialAlphaMode as Er, HotReloadReport as Et, System as F, MutableVec2 as Fa, DecodeResult as Fi, RenderTaskTiming as Fn, AssetState as Fo, LiteStorageBuffer as Fr, createFrameSample as Ft, TWEEN_LOOP_FOREVER as G, ComponentReplacement as Ga, SceneAsset as Gi, AMBIENT_OCCLUSION_QUALITIES as Gn, DeferredQueue as Go, SHADER_ASSET_TYPE as Gr, Component as Gt, TweenProps as H, TagSet as Ha, encodeValue as Hi, isWebGpuAvailable as Hn, LoaderContext as Ho, TextureAssetLiteHandles as Hr, ComponentType as Ht, SystemContext as I, MutableVec3 as Ia, ReferenceDecoder as Ii, RenderTaskTimings as In, AssetTypeDefinition as Io, ShaderMaterialDefinition as Ir, resetFrameSample as It, EASINGS as J, AssetFieldSpec as Ja, createSceneAsset as Ji, AutoExposureSettings as Jn, SignalHandler as Jo, IGNIFX_UNIFORM_NAMES as Jr, Entity as Jt, Tween as K, ScriptClassInfo as Ka, SceneAssetToken as Ki, AmbientOcclusionQuality as Kn, Disconnect as Ko, SHADER_FILE_EXTENSIONS as Kr, ComponentDefinition as Kt, SystemEditMode as L, MutableVec4 as La, ReferenceEncoder as Li, Renderer as Ln, Assets as Lo, ShaderMaterialDefinitionInput as Lr, DiagnosticsGroup as Lt, ServiceNameKey as M, ColorLike as Ma, ScriptDefinition as Mi, RenderPick as Mn, AssetManifestEntry as Mo, StorageBufferAsset as Mr, FrameSample as Mt, ServiceRegistry as N, Mat4Like as Na, SceneInstance as Ni, RenderPickIgnore as Nn, AssetProgress as No, StorageBufferAssetLiteHandles as Nr, PHASE_COUNT as Nt, RegisterComponentOptions as O, VEC2_ZERO as Oa, createLayerTable as Oi, RENDER_DIAGNOSTICS_GROUP as On, AssetLoadError as Oo, SurfaceShaderInit as Or, Diagnostics as Ot, SortingLayersSettings as P, MutableQuat as Pa, UidRemap as Pi, RenderPickOptions as Pn, AssetRef as Po, createStorageBufferAsset as Pr, PhaseIndex as Pt, resolveEase as Q, ColorFieldSpec as Qa, SCENE_FORMAT_VERSION as Qi, RENDERING_QUALITIES as Qn, JsonArray as Qo, SHADER_ATTRIBUTE_NAMES as Qr, CreateSceneOptions as Qt, Time as R, QuatLike as Ra, canonicalizeNumber as Ri, RendererImpl as Rn, AssetsSettings as Ro, shaderMaterialDefinition as Rr, createDiagnosticsGroup as Rt, ExtensionContext as S, VEC3_ONE as Sa, ReflectionProbe as Si, EDITOR_ONLY_METADATA_KEY as Sn, PhysicsCallbackName as So, LiteMaterial as Sr, HotReloadKind as St, PHASES as T, VEC3_ZERO as Ta, LayerTable as Ti, LiteCamera as Tn, EntityHandle as To, MATERIAL_ALPHA_MODES as Tr, HotReloadPolicy as Tt, TweenTargetValue as U, ComponentClassInfo as Ua, SchemaIssue as Ui, LiteShadowGenerator as Un, RegisterAssetOptions as Uo, TextureImportOptions as Ur, ConcreteComponentType as Ut, createServiceKey as V, Vec4Like as Va, encodeProps as Vi, RenderSurface as Vn, LoadOptions as Vo, TextureAsset as Vr, ComponentStatics as Vt, Tweens as W, ComponentRegistry as Wa, SchemaIssueCode as Wi, SHADOW_TECHNIQUES as Wn, ConnectOptions as Wo, LiteTexture2D as Wr, ScriptStatics as Wt, EasingFunction as X, AssetTypeToken as Xa, SCENE_FILE_EXTENSIONS as Xi, CanvasAlphaMode as Xn, SignalOptions as Xo, LITE_SYSTEM_UNIFORM_NAMES as Xr, SetParentOptions as Xt, EASING_NAMES as Y, AssetRefValue as Ya, SCENE_ASSET_TYPE as Yi, CANVAS_ALPHA_MODES as Yn, SignalLike as Yo, IgnifxUniformName as Yr, EntityPrefabLink as Yt, EasingName as Z, BoolFieldSpec as Za, SCENE_FILE_FORMAT as Zi, DEFAULT_BRDF_LUT_ADDRESS as Zn, SignalOwner as Zo, LiteSystemUniformName as Zr, CreateEntityOptions as Zt, CoroutineHost as _, LiteSceneNode as _a, ShaderTextureFallback as _i, RayVector as _n, PartialFieldsOf as _o, STANDARD_TEXTURE_SLOTS as _r, LogLevel as _t, PrefabOverrideSkip as a, SceneFileTransform as aa, SURFACE_HOOK_NAMES as ai, AddComponentFromRecordOptions as an, CustomFieldSpec as ao, defaultRenderingSettings as ar, IgnifxError as as, StoredValue as at, ErrorReport as b, VEC3_FORWARD as ba, SurfaceHookName as bi, Mat4 as bn, StringFieldSpec as bo, pbrMaterialDefinition as br, LogThreshold as bt, EntityOverrideField as c, sceneFileJsonSchema as ca, ShaderBlendMode as ci, SceneBuildResult as cn, FieldDefinition as co, MATERIAL_FILE_FORMAT as cr, formatErrorMessage as cs, PlatformInfo as ct, App as d, SchemaDescription as da, ShaderDefineDeclaration as di, assertSceneDependenciesLoaded as dn, FieldSpec as do, MaterialAsset as dr, CoreErrorCode as ds, WebGpuInfo as dt, SceneFileAssetRef as ea, SHADER_CULL_MODES as ei, LoadProgress as en, ComponentTypeToken as eo, RenderingFeatureSettings as er, JsonValue as es, TweenValueKind as et, AppEvents as f, SchemaDescriptionMeta as fa, ShaderInstancingMode as fi, instantiateScene as fn, FieldsOf as fo, MaterialAssetLiteHandles as fr, ErrorCode as fs, platformInternals as ft, CoroutineHandle as g, Transform as ga, ShaderTextureDeclaration as gi, Ray as gn, OptionalFieldSpec as go, PbrMaterialDefinition as gr, LOG_LEVEL_SEVERITY as gt, Coroutine as h, toJsonSchema as ha, ShaderStorageDeclaration as hi, PROJECTIONS as hn, NumberFieldSpec as ho, PBR_TEXTURE_SLOTS as hr, isValidErrorCode as hs, createLogger as ht, PrefabOverrideSelection as i, SceneFileOverride as ia, SHADER_UNIFORM_TYPES as ii, WorldLiteHandles as in, CustomFieldCodec as io, defaultAutoExposureSettings as ir, ErrorFormatMode as is, StorageBackend as it, ServiceKey as j, Quat as ja, ScriptCallbacks as ji, RenderOverlayLiteHandles as jn, AssetManifest as jo, STORAGE_BUFFER_ASSET_TYPE as jr, ProfileScope as jt, RegisterSystemOptions as k, Vec2 as ka, LayerMask as ki, RenderCapture as kn, AssetLoadErrorOptions as ko, SurfaceShaderReference as kr, DiagnosticsOptions as kt, OverridePath as l, stringifySceneFile as la, ShaderCullMode as li, SceneLoadIssue as ln, FieldKind as lo, MATERIAL_FORMAT_VERSION as lr, isIgnifxError as ls, PlatformKind as lt, AppSettings as m, describeSchema as ma, ShaderPipelineState as mi, CameraProjection as mn, MapFieldSpec as mo, MaterialKind as mr, THIRD_PARTY_ERROR_PREFIX as ms, LoggerOptions as mt, PrefabApplyResult as n, SceneFileEntity as na, SHADER_KINDS as ni, LoadSceneOptions as nn, CurveKey as no, RenderingSettings as nr, LiteScene as ns, Storage as nt, applyOverridesToAsset as o, describeSceneFileFormat as oa, SURFACE_UNIFORM_BLOCK as oi, ComponentBuildResult as on, EntityRefFieldSpec as oo, MATERIAL_ASSET_TYPE as or, IgnifxErrorOptions as os, StoredValueKind as ot, AppLiteHandles as p, SchemaFieldDescription as pa, ShaderKind as pi, Camera as pn, LayerMaskFieldSpec as po, MaterialDefinition as pr, ErrorRange as ps, Logger as pt, TweenOptions as q, ArrayFieldSpec as qa, computeSceneHash as qi, AmbientOcclusionSettings as qn, Signal as qo, ShaderAsset as qr, ComponentHooks as qt, PrefabComponentSkip as r, SceneFileInstance as ra, SHADER_TEXTURE_FALLBACKS as ri, World as rn, CurveValue as ro, TaaSettings as rr, ErrorContext as rs, storageInternals as rt, revertOverrides as s, isSceneFileHeader as sa, ShaderAttributeName$1 as si, InstantiateSceneOptions as sn, EnumFieldSpec as so, MATERIAL_FILE_EXTENSION as sr, assertNever as ss, GpuAdapterInfo as st, PrefabApplyOptions as t, SceneFileComponent as ta, SHADER_INSTANCING_MODES as ti, LoadSceneFileOptions as tn, CurveFieldSpec as to, RenderingQuality as tr, LiteEngine as ts, TweenableValue as tt, parseOverridePath as u, JsonSchemaObject as ua, ShaderDeclaration as ui, addComponentFromRecord as un, FieldOptions as uo, MATERIAL_KINDS as ur, CORE_ERROR_MESSAGES as us, PlatformOs as ut, CoroutineYield as v, VEC3_BACKWARD as va, ShaderUniformDeclaration as vi, createRay as vn, RecordFieldSpec as vo, StandardMaterialDefinition as vr, LogRecord as vt, LayersSettings as w, VEC3_UP as wa, DEFAULT_LAYER as wi, RenderTexture as wn, ComponentHandle as wo, LiteStandardMaterial as wr, HotReloadOptions as wt, Extension as x, VEC3_LEFT as xa, REFLECTION_PROBE_REFRESH_MODES as xi, Mat4Elements as xn, VectorFieldSpec as xo, standardMaterialDefinition as xr, HotReloadHost as xt, DeviceLostInfo as y, VEC3_DOWN as ya, ShaderUniformType$1 as yi, MAT4_IDENTITY as yn, Schema as yo, createMaterialAsset as yr, LogSink as yt, TimeSettings as z, Vec2Like as za, decodeProps as zi, RenderingFeature as zn, BatchHandle as zo, PixelTextureOptions as zr, ComponentInit as zt };
14925
- //# sourceMappingURL=prefab-overrides-76IhcF-e.d.ts.map
16231
+ export { EASING_NAMES as $, JsonSchemaObject as $a, LitePbrMaterial as $i, CANVAS_ALPHA_MODES as $n, FieldOptions as $o, STANDARD_TEXTURE_SLOTS as $r, CORE_ERROR_MESSAGES as $s, EntityPrefabLink as $t, PHASE_NAMES as A, encodeProps as Aa, SHADER_BLEND_MODES as Ai, FrameWaitOptions as An, Vec4Like as Ao, TorusMeshOptions as Ar, LoadOptions as As, HotReloadReport as At, SystemContext as B, SCENE_FILE_FORMAT as Ba, ShaderCullMode as Bi, RenderTaskTimings as Bn, BoolFieldSpec as Bo, createLightmapAsset as Br, SignalOwner as Bs, resetFrameSample as Bt, DeviceLostInfo as C, UidRemap as Ca, SHADER_FILE_EXTENSIONS as Ci, MAT4_IDENTITY as Cn, MutableQuat as Co, MeshAsset as Cr, AssetRef as Cs, LogSink as Ct, FrameState as D, canonicalizeNumber as Da, LITE_SYSTEM_UNIFORM_NAMES as Di, RENDER_TEXTURE_MAX_SIZE as Dn, QuatLike as Do, MeshPrimitiveDefinition as Dr, AssetsSettings as Ds, HotReloadModule as Dt, ExtensionContext as E, ReferenceEncoder as Ea, IgnifxUniformName as Ei, EDITOR_ONLY_METADATA_KEY as En, MutableVec4 as Eo, MeshPrimitive as Er, Assets as Es, HotReloadKind as Et, ServiceKey as F, SceneAssetToken as Fa, SHADER_UNIFORM_TYPES as Fi, RenderOverlayLiteHandles as Fn, ScriptClassInfo as Fo, LIGHTMAP_FILE_FORMAT as Fr, Disconnect as Fs, ProfileScope as Ft, createServiceKey as G, SceneFileEntity as Ga, ShaderPipelineState as Gi, RenderSurface as Gn, CurveKey as Go, MATERIAL_FORMAT_VERSION as Gr, LiteScene as Gs, ComponentStatics as Gt, Time as H, SceneFile as Ha, ShaderDefineDeclaration as Hi, RendererImpl as Hn, ComponentRefFieldSpec as Ho, MATERIAL_ASSET_TYPE as Hr, JsonObject as Hs, createDiagnosticsGroup as Ht, ServiceNameKey as I, computeSceneHash as Ia, SURFACE_HOOK_NAMES as Ii, RenderPick as In, ArrayFieldSpec as Io, LIGHTMAP_FORMAT_VERSION as Ir, Signal as Is, FrameSample as It, Tweens as J, SceneFileTransform as Ja, ShaderTextureFallback as Ji, SHADOW_TECHNIQUES as Jn, CustomFieldSpec as Jo, MaterialAssetLiteHandles as Jr, IgnifxError as Js, ScriptStatics as Jt, TweenProps as K, SceneFileInstance as Ka, ShaderStorageDeclaration as Ki, isWebGpuAvailable as Kn, CurveValue as Ko, MATERIAL_KINDS as Kr, ErrorContext as Ks, ComponentType as Kt, ServiceRegistry as L, createSceneAsset as La, SURFACE_UNIFORM_BLOCK as Li, RenderPickIgnore as Ln, AssetFieldSpec as Lo, LightmapAsset as Lr, SignalHandler as Ls, PHASE_COUNT as Lt, RegisterComponentOptions as M, SchemaIssue as Ma, SHADER_INSTANCING_MODES as Mi, RENDER_DIAGNOSTICS_GROUP as Mn, ComponentClassInfo as Mo, IDENTITY_LIGHTMAP_PLACEMENT as Mr, RegisterAssetOptions as Ms, Diagnostics as Mt, RegisterSystemOptions as N, SchemaIssueCode as Na, SHADER_KINDS as Ni, RenderCapture as Nn, ComponentRegistry as No, LIGHTMAP_ASSET_TYPE as Nr, ConnectOptions as Ns, DiagnosticsOptions as Nt, LayersSettings as O, decodeProps as Oa, LiteSystemUniformName as Oi, RenderTexture as On, Vec2Like as Oo, PlaneMeshOptions as Or, BatchHandle as Os, HotReloadOptions as Ot, ServiceClassKey as P, SceneAsset as Pa, SHADER_TEXTURE_FALLBACKS as Pi, RenderOverlay as Pn, ComponentReplacement as Po, LIGHTMAP_FILE_EXTENSIONS as Pr, DeferredQueue as Ps, FRAME_HISTORY_LENGTH as Pt, EASINGS as Q, stringifySceneFile as Qa, LiteMaterial as Qi, AutoExposureSettings as Qn, FieldKind as Qo, PbrMaterialDefinition as Qr, isIgnifxError as Qs, Entity as Qt, SortingLayersSettings as R, SCENE_ASSET_TYPE as Ra, ShaderAttributeName$1 as Ri, RenderPickOptions as Rn, AssetRefValue as Ro, LightmapFileData as Rr, SignalLike as Rs, PhaseIndex as Rt, CoroutineYield as S, SceneInstance as Sa, SHADER_ASSET_TYPE as Si, createRay as Sn, Mat4Like as So, MESH_PRIMITIVES as Sr, AssetProgress as Ss, LogRecord as St, Extension as T, ReferenceDecoder as Ta, IGNIFX_UNIFORM_NAMES as Ti, Mat4Elements as Tn, MutableVec3 as To, MeshGeometryData as Tr, AssetTypeDefinition as Ts, HotReloadHost as Tt, TimeSettings as U, SceneFileAssetRef as Ua, ShaderInstancingMode as Ui, RenderingFeature as Un, ComponentTypeToken as Uo, MATERIAL_FILE_EXTENSION as Ur, JsonValue as Us, ComponentInit as Ut, SystemEditMode as V, SCENE_FORMAT_VERSION as Va, ShaderDeclaration as Vi, Renderer as Vn, ColorFieldSpec as Vo, writeLightmapFile as Vr, JsonArray as Vs, DiagnosticsGroup as Vt, WaitInstruction as W, SceneFileComponent as Wa, ShaderKind as Wi, forceRendererDeviceLossForTesting as Wn, CurveFieldSpec as Wo, MATERIAL_FILE_FORMAT as Wr, LiteEngine as Ws, ComponentInitValue as Wt, Tween as X, isSceneFileHeader as Xa, ShaderUniformType$1 as Xi, AmbientOcclusionQuality as Xn, EnumFieldSpec as Xo, MaterialKind as Xr, assertNever as Xs, ComponentDefinition as Xt, TWEEN_LOOP_FOREVER as Y, describeSceneFileFormat as Ya, ShaderUniformDeclaration as Yi, AMBIENT_OCCLUSION_QUALITIES as Yn, EntityRefFieldSpec as Yo, MaterialDefinition as Yr, IgnifxErrorOptions as Ys, Component as Yt, TweenOptions as Z, sceneFileJsonSchema as Za, SurfaceHookName as Zi, AmbientOcclusionSettings as Zn, FieldDefinition as Zo, PBR_TEXTURE_SLOTS as Zr, formatErrorMessage as Zs, ComponentHooks as Zt, AppLiteHandles as _, createLayerTable as _a, TEXTURE_ASSET_TYPE as _i, Camera as _n, VEC2_ZERO as _o, BoxMeshOptions as _r, AssetLoadError as _s, Logger as _t, PrefabOverrideSkip as a, LIGHT_PROBE_FILE_EXTENSIONS as aa, SurfaceShaderInit as ai, LoadSceneFileOptions as an, Transform as ao, RenderingQuality as ar, OptionalFieldSpec as as, TweenableValue as at, CoroutineHandle as b, ScriptCallbacks as ba, TextureImportOptions as bi, Ray as bn, Quat as bo, GroundMeshOptions as br, AssetManifest as bs, LOG_LEVEL_SEVERITY as bt, EntityOverrideField as c, LightProbeAsset as ca, STORAGE_BUFFER_ASSET_TYPE as ci, WorldLiteHandles as cn, VEC3_DOWN as co, defaultAutoExposureSettings as cr, Schema as cs, StorageBackend as ct, InstanceTarget as d, sampleLightProbes as da, createStorageBufferAsset as di, InstantiateSceneOptions as dn, VEC3_ONE as do, ReflectionProbe as dr, PhysicsCallbackName as ds, GpuAdapterInfo as dt, LiteStandardMaterial as ea, CoreErrorCode as ec, StandardMaterialDefinition as ei, SetParentOptions as en, SchemaDescription as eo, CanvasAlphaMode as er, FieldSpec as es, EasingFunction as et, PrefabReader as f, writeLightProbeFile as fa, LiteStorageBuffer as fi, SceneBuildResult as fn, VEC3_RIGHT as fo, ReflectionProbeRefreshMode as fr, ScriptCallbackKind as fs, PlatformInfo as ft, AppEvents as g, RESERVED_LAYER_NAMES as ga, PixelTextureOptions as gi, instantiateScene as gn, VEC2_ONE as go, MeshRendererLightmap as gr, AssetHandle as gs, platformInternals as gt, App as h, MAX_LAYERS as ha, shaderMaterialDefinition as hi, assertSceneDependenciesLoaded as hn, Vec3 as ho, MeshRenderer as hr, INVALID_HANDLE as hs, WebGpuInfo as ht, PrefabOverrideSelection as i, LIGHT_PROBE_ASSET_TYPE as ia, isValidErrorCode as ic, SurfaceShaderBinding as ii, LoadProgress as in, toJsonSchema as io, RenderingFeatureSettings as ir, NumberFieldSpec as is, TweenValueKind as it, Phase as j, encodeValue as ja, SHADER_CULL_MODES as ji, RENDER_DIAGNOSTICS_COUNTERS as jn, TagSet as jo, LiteMesh as jr, LoaderContext as js, HotReloadStatics as jt, PHASES as k, decodeValue as ka, SHADER_ATTRIBUTE_NAMES as ki, LiteCamera as kn, Vec3Like as ko, SphereMeshOptions as kr, FetchLike as ks, HotReloadPolicy as kt, OverridePath as l, LightProbeData as la, StorageBufferAsset as li, AddComponentFromRecordOptions as ln, VEC3_FORWARD as lo, defaultRenderingSettings as lr, StringFieldSpec as ls, StoredValue as lt, resolveInstancePath as m, LayerTable as ma, ShaderMaterialDefinitionInput as mi, addComponentFromRecord as mn, VEC3_ZERO as mo, LightmapMode as mr, EntityHandle as ms, PlatformOs as mt, PrefabApplyResult as n, MaterialAlphaMode as na, ErrorRange as nc, pbrMaterialDefinition as ni, CreateSceneOptions as nn, SchemaFieldDescription as no, RENDERING_QUALITIES as nr, LayerMaskFieldSpec as ns, resolveEase as nt, applyOverridesToAsset as o, LIGHT_PROBE_FILE_FORMAT as oa, SurfaceShaderReference as oi, LoadSceneOptions as on, LiteSceneNode as oo, RenderingSettings as or, PartialFieldsOf as os, Storage as ot, enumerateInstanceTargets as p, DEFAULT_LAYER as pa, ShaderMaterialDefinition as pi, SceneLoadIssue as pn, VEC3_UP as po, LIGHTMAP_MODES as pr, ComponentHandle as ps, PlatformKind as pt, TweenTargetValue as q, SceneFileOverride as qa, ShaderTextureDeclaration as qi, LiteShadowGenerator as qn, CustomFieldCodec as qo, MaterialAsset as qr, ErrorFormatMode as qs, ConcreteComponentType as qt, PrefabComponentSkip as r, LightProbeVolume as ra, THIRD_PARTY_ERROR_PREFIX as rc, standardMaterialDefinition as ri, InstantiateOptions as rn, describeSchema as ro, RENDERING_SETTINGS_SECTION as rr, MapFieldSpec as rs, TWEEN_VALUE_KINDS as rt, revertOverrides as s, LIGHT_PROBE_FORMAT_VERSION as sa, LiteShaderMaterial as si, World as sn, VEC3_BACKWARD as so, TaaSettings as sr, RecordFieldSpec as ss, storageInternals as st, PrefabApplyOptions as t, MATERIAL_ALPHA_MODES as ta, ErrorCode as tc, createMaterialAsset as ti, CreateEntityOptions as tn, SchemaDescriptionMeta as to, DEFAULT_BRDF_LUT_ADDRESS as tr, FieldsOf as ts, EasingName as tt, parseOverridePath as u, createLightProbeAsset as ua, StorageBufferAssetLiteHandles as ui, ComponentBuildResult as un, VEC3_LEFT as uo, REFLECTION_PROBE_REFRESH_MODES as ur, VectorFieldSpec as us, StoredValueKind as ut, AppSettings as v, LayerMask as va, TextureAsset as vi, CameraProjection as vn, Vec2 as vo, CapsuleMeshOptions as vr, AssetLoadErrorOptions as vs, LoggerOptions as vt, ErrorReport as w, DecodeResult as wa, ShaderAsset as wi, Mat4 as wn, MutableVec2 as wo, MeshAssetLiteHandles as wr, AssetState as ws, LogThreshold as wt, CoroutineHost as x, ScriptDefinition as xa, LiteTexture2D as xi, RayVector as xn, ColorLike as xo, MESH_ASSET_TYPE as xr, AssetManifestEntry as xs, LogLevel as xt, Coroutine as y, Script as ya, TextureAssetLiteHandles as yi, PROJECTIONS as yn, QUAT_IDENTITY as yo, CylinderMeshOptions as yr, AssetLoader as ys, createLogger as yt, System as z, SCENE_FILE_EXTENSIONS as za, ShaderBlendMode as zi, RenderTaskTiming as zn, AssetTypeToken as zo, LightmapPlacement as zr, SignalOptions as zs, createFrameSample as zt };
16232
+ //# sourceMappingURL=prefab-overrides-CS8_cG66.d.ts.map