@ignifx/core 0.18.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 (43) hide show
  1. package/dist/{environment-DZ6WUHbm.js → environment-Bf4aphSb.js} +2 -2
  2. package/dist/{environment-DZ6WUHbm.js.map → environment-Bf4aphSb.js.map} +1 -1
  3. package/dist/{ignifx-error-B8ByiSfJ.js → ignifx-error-DwIZKxA2.js} +4 -1
  4. package/dist/ignifx-error-DwIZKxA2.js.map +1 -0
  5. package/dist/index.d.ts +49 -687
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js +1326 -834
  8. package/dist/index.js.map +1 -1
  9. package/dist/{light-probe-asset-B60_X-yN.js → light-probe-asset-BqfSrJe9.js} +2 -2
  10. package/dist/{light-probe-asset-B60_X-yN.js.map → light-probe-asset-BqfSrJe9.js.map} +1 -1
  11. package/dist/{light-probes-DkYN89Qw.js → light-probes-DyLapYX9.js} +3 -3
  12. package/dist/{light-probes-DkYN89Qw.js.map → light-probes-DyLapYX9.js.map} +1 -1
  13. package/dist/lightmaps-LO6Ygtwe.js +137 -0
  14. package/dist/lightmaps-LO6Ygtwe.js.map +1 -0
  15. package/dist/{material-plugin-CiAmriQ_.js → material-plugin-DapJNj04.js} +2 -2
  16. package/dist/{material-plugin-CiAmriQ_.js.map → material-plugin-DapJNj04.js.map} +1 -1
  17. package/dist/{post-effect-CQnlX1RH.js → post-effect-CaiqDlhW.js} +2 -2
  18. package/dist/{post-effect-CQnlX1RH.js.map → post-effect-CaiqDlhW.js.map} +1 -1
  19. package/dist/{post-effect-compiler-C_7HTHZy.js → post-effect-compiler-jSvOVe0U.js} +3 -3
  20. package/dist/{post-effect-compiler-C_7HTHZy.js.map → post-effect-compiler-jSvOVe0U.js.map} +1 -1
  21. package/dist/{prefab-overrides-BLQn5yHS.d.ts → prefab-overrides-CS8_cG66.d.ts} +1334 -251
  22. package/dist/prefab-overrides-CS8_cG66.d.ts.map +1 -0
  23. package/dist/{prefab-overrides-DT-wHHAJ.js → prefab-overrides-DRP2DcnC.js} +450 -30
  24. package/dist/prefab-overrides-DRP2DcnC.js.map +1 -0
  25. package/dist/prefab.d.ts +2 -2
  26. package/dist/prefab.js +2 -2
  27. package/dist/{reflection-probe-DlVsl3zJ.js → reflection-probe-AS8d4uKv.js} +30 -12
  28. package/dist/{reflection-probe-DlVsl3zJ.js.map → reflection-probe-AS8d4uKv.js.map} +1 -1
  29. package/dist/{reflection-probes-B8S9WnVX.js → reflection-probes-CUZcOjNW.js} +115 -22
  30. package/dist/reflection-probes-CUZcOjNW.js.map +1 -0
  31. package/dist/{shader-material-CaAkv5nT.js → shader-material-CJIDFvSb.js} +2 -2
  32. package/dist/{shader-material-CaAkv5nT.js.map → shader-material-CJIDFvSb.js.map} +1 -1
  33. package/dist/{shader-material-C2_UCYdO.js → shader-material-CuwK9tWC.js} +4 -4
  34. package/dist/{shader-material-C2_UCYdO.js.map → shader-material-CuwK9tWC.js.map} +1 -1
  35. package/dist/{shader-pragma-DmZpxGUo.js → shader-pragma-ljmAbVc2.js} +2 -2
  36. package/dist/{shader-pragma-DmZpxGUo.js.map → shader-pragma-ljmAbVc2.js.map} +1 -1
  37. package/dist/{surface-shader-BeDRofOV.js → surface-shader-DY9_aC9L.js} +4 -4
  38. package/dist/{surface-shader-BeDRofOV.js.map → surface-shader-DY9_aC9L.js.map} +1 -1
  39. package/package.json +1 -1
  40. package/dist/ignifx-error-B8ByiSfJ.js.map +0 -1
  41. package/dist/prefab-overrides-BLQn5yHS.d.ts.map +0 -1
  42. package/dist/prefab-overrides-DT-wHHAJ.js.map +0 -1
  43. package/dist/reflection-probes-B8S9WnVX.js.map +0 -1
package/dist/index.js CHANGED
@@ -1,18 +1,18 @@
1
- import { a as CORE_ERROR_MESSAGES, c as THIRD_PARTY_ERROR_PREFIX, i as isIgnifxError, l as isValidErrorCode, n as assertNever, o as CoreErrorCode, r as formatErrorMessage, s as ErrorRange, t as IgnifxError } from "./ignifx-error-B8ByiSfJ.js";
2
- import { A as vec2, B as readPickedTag, C as layerMask, D as record, E as quat, F as raycastScene, G as toComponentHandle, H as Component, I as raycastSceneWhere, J as assertNoInheritedFieldNames, K as toEntityHandle, L as readOwnerTag, M as vec4, N as FieldKind, O as str, P as createPickRay, R as readPickedIdentity, S as i32, T as optional, U as componentInternals, V as setPickRay, W as INVALID_HANDLE, X as defineSchema, Y as createDefaults, Z as Signal, _ as custom, a as EDITOR_ONLY_METADATA_KEY, b as f32, c as assertRenderTextureSize, d as array, f as asset, g as curve, h as componentRef, j as vec3, k as u32, l as bindFrameCameras, m as color, n as ReflectionProbe, o as RENDER_TEXTURE_MAX_SIZE, p as bool, q as applyInit, s as RenderTextureImpl, t as REFLECTION_PROBE_REFRESH_MODES, u as renderTextureUnusableError, v as entityRef, w as map, x as f64, y as enumOf, z as readPickedMeshName } from "./reflection-probe-DlVsl3zJ.js";
3
- import { A as asJsonArray, B as normalizeExtension, C as encodeValue, D as indexPath, E as childPath, L as isAbsoluteAddress, M as setOwnJsonProperty, N as SchemaIssueCode, O as isArray, P as issue, R as joinRoot, S as encodeProps, T as VECTOR_COMPONENTS, V as splitFragment, _ as describeSchema, a as SceneAssetToken, b as decodeProps, c as findSceneDependency, d as SCENE_FILE_FORMAT, f as SCENE_FORMAT_VERSION, g as stringifySceneFile, h as sceneFileJsonSchema, i as parseOverridePath, j as asJsonObject, k as isPlainObject, l as SCENE_ASSET_TYPE, m as isSceneFileHeader, n as revertOverrides, o as computeSceneHash, p as describeSceneFileFormat, r as applyOverrides, s as createSceneAsset, t as applyOverridesToAsset, u as SCENE_FILE_EXTENSIONS, v as toJsonSchema, w as COLOR_CHANNELS, x as decodeValue, y as canonicalizeNumber, z as matchExtension } from "./prefab-overrides-DT-wHHAJ.js";
1
+ import { a as CORE_ERROR_MESSAGES, c as THIRD_PARTY_ERROR_PREFIX, i as isIgnifxError, l as isValidErrorCode, n as assertNever, o as CoreErrorCode, r as formatErrorMessage, s as ErrorRange, t as IgnifxError } from "./ignifx-error-DwIZKxA2.js";
2
+ import { A as u32, B as readPickedMeshName, C as i32, D as quat, E as optional, F as createPickRay, G as INVALID_HANDLE, H as setPickRay, I as raycastScene, J as applyInit, K as toComponentHandle, L as raycastSceneWhere, M as vec3, N as vec4, O as record, P as FieldKind, Q as Signal, R as readOwnerTag, S as f64, T as map, U as Component, V as readPickedTag, W as componentInternals, X as createDefaults, Y as assertNoInheritedFieldNames, Z as defineSchema, _ as curve, b as enumOf, c as RenderTextureImpl, d as renderTextureUnusableError, f as array, g as componentRef, h as color, j as vec2, k as str, l as assertRenderTextureSize, m as bool, n as ReflectionProbe, o as EDITOR_ONLY_METADATA_KEY, p as asset, q as toEntityHandle, s as RENDER_TEXTURE_MAX_SIZE, t as REFLECTION_PROBE_REFRESH_MODES, u as bindFrameCameras, v as custom, w as layerMask, x as f32, y as entityRef, z as readPickedIdentity } from "./reflection-probe-AS8d4uKv.js";
3
+ import { A as childPath, C as canonicalizeNumber, D as encodeValue, E as encodeProps, F as asJsonObject, G as splitFragment, H as joinRoot, I as setOwnJsonProperty, L as SchemaIssueCode, M as isArray, N as isPlainObject, O as COLOR_CHANNELS, P as asJsonArray, R as issue, S as toJsonSchema, T as decodeValue, U as matchExtension, V as isAbsoluteAddress, W as normalizeExtension, _ as describeSceneFileFormat, a as applyOverrides, b as stringifySceneFile, c as remapInstancePath, d as createSceneAsset, f as findSceneDependency, g as SCENE_FORMAT_VERSION, h as SCENE_FILE_FORMAT, i as resolveInstancePath, j as indexPath, k as VECTOR_COMPONENTS, l as SceneAssetToken, m as SCENE_FILE_EXTENSIONS, n as revertOverrides, o as parseOverridePath, p as SCENE_ASSET_TYPE, r as enumerateInstanceTargets, s as instancePathResolver, t as applyOverridesToAsset, u as computeSceneHash, v as isSceneFileHeader, w as decodeProps, x as describeSchema, y as sceneFileJsonSchema } from "./prefab-overrides-DRP2DcnC.js";
4
4
  import { _ as smoothStep, a as clamp, c as deltaAngleDegrees, d as lerpAngleDegrees, f as moveTowards, g as sign, h as repeat, i as approximately, l as inverseLerp, m as radToDeg, n as EPSILON, o as clamp01, p as pingPong, r as RAD_TO_DEG, s as degToRad, t as DEG_TO_RAD, u as lerp, v as wrapAngleDegrees } from "./math-utils-BcDnL-gi.js";
5
5
  import { n as Mat4, r as basisToQuatToRef, t as MAT4_IDENTITY } from "./mat4-D6exvAuO.js";
6
6
  import { a as localRotation, d as setNodeName, f as setNodeSelfVisible, i as localPosition, l as readWorldMatrix, m as worldMatrixVersion, n as disposeNode, o as localScale, p as tagNode, r as linkParent, s as parentNode, t as createNode, u as reparentKeepingWorld } from "./node-DznSvwap.js";
7
7
  import { t as Color } from "./color-DrR6GFTd.js";
8
- import { a as readSceneImageProcessing, c as setSceneEnvironmentRotation, l as setSceneFog, n as installSceneEnvironment, o as setSceneClearColor, r as loadSceneEnvironment, s as setSceneEnvironmentBlur, t as TONE_MAPPING_NAMES, u as setSceneImageProcessingOptions } from "./environment-DZ6WUHbm.js";
8
+ import { a as readSceneImageProcessing, c as setSceneEnvironmentRotation, i as readSceneEnvironment, l as setSceneFog, n as installSceneEnvironment, o as setSceneClearColor, r as loadSceneEnvironment, s as setSceneEnvironmentBlur, t as TONE_MAPPING_NAMES, u as setSceneImageProcessingOptions } from "./environment-Bf4aphSb.js";
9
9
  import { a as markMaterialDirty, c as setPbrBaseColor, i as createStandardMaterialFromProps, l as setPbrMetallicRoughness, n as createDefaultMaterial, r as createPbrMaterialFromProps, s as setMaterialAlpha, t as MATERIAL_ALPHA_MODES } from "./material-CGk5mAah.js";
10
10
  import { A as setMeshReceiveShadows, C as overrideSubtreeMaterials, D as setMeshId, E as setMeshBounds, F as updateMeshPositions$1, I as updateMeshUvs$1, M as setMeshSubtreeVisible, N as updateMeshColors$1, O as setMeshMaterial, P as updateMeshNormals$1, S as disposeMeshTemplate, T as removeMeshFromScene, _ as createMeshFromGeometry, a as VEC3_ONE, b as createTorusMesh, c as VEC3_ZERO, d as cloneMeshUnderNode, f as collectSubtreeMeshes, g as createGroundMesh, h as createCylinderMesh, i as VEC3_LEFT, j as setMeshRenderOrder, k as setMeshPickable, l as Vec3, m as createCapsuleMesh, n as VEC3_DOWN, o as VEC3_RIGHT, p as createBoxMesh, r as VEC3_FORWARD, s as VEC3_UP, t as VEC3_BACKWARD, u as addMeshToScene, v as createPlaneMesh, w as recomputeMeshBounds, x as detachMeshBounds, y as createSphereMesh } from "./vec3-Cc19wl4r.js";
11
- import { a as LightProbeAsset, c as readLightProbeFile, d as writeLightProbeFile, i as LIGHT_PROBE_FORMAT_VERSION, l as readLightProbeGrid, n as LIGHT_PROBE_FILE_EXTENSIONS, o as createLightProbeAsset, r as LIGHT_PROBE_FILE_FORMAT, t as LIGHT_PROBE_ASSET_TYPE, u as sampleLightProbes } from "./light-probe-asset-B60_X-yN.js";
12
- import { a as postEffectValuesCodec, i as declaredTextureBinding, n as POST_EFFECT_FUNCTION, r as customEffect, t as POST_EFFECT_BUILTIN_UNIFORMS } from "./post-effect-CQnlX1RH.js";
11
+ import { a as LightProbeAsset, c as readLightProbeFile, d as writeLightProbeFile, i as LIGHT_PROBE_FORMAT_VERSION, l as readLightProbeGrid, n as LIGHT_PROBE_FILE_EXTENSIONS, o as createLightProbeAsset, r as LIGHT_PROBE_FILE_FORMAT, t as LIGHT_PROBE_ASSET_TYPE, u as sampleLightProbes } from "./light-probe-asset-BqfSrJe9.js";
12
+ import { a as postEffectValuesCodec, i as declaredTextureBinding, n as POST_EFFECT_FUNCTION, r as customEffect, t as POST_EFFECT_BUILTIN_UNIFORMS } from "./post-effect-CaiqDlhW.js";
13
13
  import { n as installOffscreenRenderPath } from "./render-path-D11i_7X8.js";
14
14
  import { a as SHADER_BLEND_MODES, c as SHADER_KINDS, d as SURFACE_HOOK_NAMES, f as SURFACE_UNIFORM_BLOCK, i as SHADER_ATTRIBUTE_NAMES, l as SHADER_TEXTURE_FALLBACKS, o as SHADER_CULL_MODES, r as LITE_SYSTEM_UNIFORM_NAMES, s as SHADER_INSTANCING_MODES, t as IGNIFX_UNIFORM_NAMES, u as SHADER_UNIFORM_TYPES } from "./shader-declaration-5q__jycG.js";
15
- import { a as defineMaterialPlugin, i as MATERIAL_PLUGIN_SAMPLER_BUDGET, n as MATERIAL_PLUGIN_DEFAULT_PRIORITY, o as isLiteMaterialPluginPoint, r as MATERIAL_PLUGIN_RESERVED_NAMES, t as LITE_MATERIAL_PLUGIN_POINTS } from "./material-plugin-CiAmriQ_.js";
15
+ import { a as defineMaterialPlugin, i as MATERIAL_PLUGIN_SAMPLER_BUDGET, n as MATERIAL_PLUGIN_DEFAULT_PRIORITY, o as isLiteMaterialPluginPoint, r as MATERIAL_PLUGIN_RESERVED_NAMES, t as LITE_MATERIAL_PLUGIN_POINTS } from "./material-plugin-DapJNj04.js";
16
16
  import { acquireTexture, addTask, addToScene, buildFrameGraphTask, captureScreenshot, cloneTransformNode, createBloomPostProcessTask, createCsmDirectionalShadowGenerator, createDirectionalLight, createEngine, createEsmDirectionalShadowGenerator, createFontFromBuffer, createFreeCamera, createGpuPicker, createHemisphericLight, createImageProcessingTask, createMeshFromData, createNullEngine, createPcfDirectionalShadowGenerator, createPcfSpotlightShadowGenerator, createPointLight, createRenderTarget, createSceneContext, createSmaaPostProcessTask, createSpotLight, createStorageBuffer, createTexture2DFromPixels, disableOrthographicCamera, disposeEngine, disposePicker, disposeScene, disposeStorageBuffer, enableBoneControl, enableDeviceLostSceneRecovery, enableMaterialPlugins, enableMaterialStencil, enableOrthographicCamera, enablePbrLightmap, enableSkeletonShadows, enableStandardSkeleton, forceWebGpuDeviceLossForTesting, getEffectiveAspectRatio, getFrameGraph, getProjectionMatrix, getRenderTaskGpuTimings, getViewMatrix, getViewProjectionMatrix, isPbrMaterial, isShaderMaterial, loadTexture2D, onBeforeRender, pickAsync, rebuildSceneRenderables, registerScene, registerSceneWithShadowSupport, releaseTexture, removeFromScene, renderFrame, resizeEngine, resolveCameraViewport, setGpuTimingEnabled, setRenderTaskGpuTimingEnabled, setShadowTaskCasterMeshes, setSubtreeVisible, setSurfaceSize, startEngine, stopEngine, updateStorageBuffer, updateTexture2DFromPixels } from "@babylonjs/lite";
17
17
  //#region src/assets/types.ts
18
18
  /**
@@ -3903,7 +3903,7 @@ function createServiceKey(name) {
3903
3903
  *
3904
3904
  * @public
3905
3905
  */
3906
- const VERSION = "0.18.0";
3906
+ const VERSION = "0.19.0";
3907
3907
  //#endregion
3908
3908
  //#region src/assets/delivery-system.ts
3909
3909
  /**
@@ -5494,7 +5494,7 @@ let surfaceLayer = null;
5494
5494
  * @internal
5495
5495
  */
5496
5496
  async function loadShaderSupport() {
5497
- const loaded = shaderLayer ?? await import("./shader-material-C2_UCYdO.js").then((n) => n.n);
5497
+ const loaded = shaderLayer ?? await import("./shader-material-CuwK9tWC.js").then((n) => n.n);
5498
5498
  shaderLayer = loaded;
5499
5499
  await loaded.loadShaderMaterialAdapter();
5500
5500
  return loaded;
@@ -5517,7 +5517,7 @@ function shaderSupport() {
5517
5517
  * @internal
5518
5518
  */
5519
5519
  async function loadSurfaceShaderSupport() {
5520
- const loaded = surfaceLayer ?? await import("./surface-shader-BeDRofOV.js");
5520
+ const loaded = surfaceLayer ?? await import("./surface-shader-DY9_aC9L.js");
5521
5521
  surfaceLayer = loaded;
5522
5522
  return loaded;
5523
5523
  }
@@ -8585,7 +8585,7 @@ var LightProbeHost = class {
8585
8585
  }
8586
8586
  if (volumes.length === 0 || this.#isLoading || this.#isDisposed) return;
8587
8587
  this.#isLoading = true;
8588
- import("./light-probes-DkYN89Qw.js").then((module) => module.createLightProbeRuntime(this.#engine, this.#scene)).then((created) => {
8588
+ import("./light-probes-DyLapYX9.js").then((module) => module.createLightProbeRuntime(this.#engine, this.#scene)).then((created) => {
8589
8589
  if (this.#isDisposed) {
8590
8590
  created.dispose();
8591
8591
  return;
@@ -8601,6 +8601,370 @@ var LightProbeHost = class {
8601
8601
  }
8602
8602
  };
8603
8603
  //#endregion
8604
+ //#region src/render/lightmap-asset.ts
8605
+ /**
8606
+ * Lightmaps (`docs/plan/2026-11-gi-phase-2-execution-plan.md`, step B3): a baked texture that static
8607
+ * `MeshRenderer`s sample through their second UV set, and the per-entity placement of each renderer
8608
+ * in it. Everything here is plain data and runs in Node; the GPU half is `./gpu/lightmaps.ts`.
8609
+ */
8610
+ /**
8611
+ * The asset type lightmaps are registered under.
8612
+ *
8613
+ * @public
8614
+ */
8615
+ const LIGHTMAP_ASSET_TYPE = "lightmap";
8616
+ /**
8617
+ * The address extensions that select the lightmap loader.
8618
+ *
8619
+ * @public
8620
+ */
8621
+ const LIGHTMAP_FILE_EXTENSIONS = Object.freeze([".lightmap.json"]);
8622
+ /**
8623
+ * The `format` header every `.lightmap.json` carries.
8624
+ *
8625
+ * @public
8626
+ */
8627
+ const LIGHTMAP_FILE_FORMAT = "ignifx-lightmap";
8628
+ /**
8629
+ * The `formatVersion` this engine reads and writes.
8630
+ *
8631
+ * @public
8632
+ */
8633
+ const LIGHTMAP_FORMAT_VERSION = 1;
8634
+ /**
8635
+ * The placement every entity without an entry gets: the whole texture.
8636
+ *
8637
+ * @public
8638
+ */
8639
+ const IDENTITY_LIGHTMAP_PLACEMENT = Object.freeze({
8640
+ scale: Object.freeze({
8641
+ x: 1,
8642
+ y: 1
8643
+ }),
8644
+ offset: Object.freeze({
8645
+ x: 0,
8646
+ y: 0
8647
+ })
8648
+ });
8649
+ /**
8650
+ * A loaded lightmap: a texture and where each entity's UV2 square sits in it.
8651
+ *
8652
+ * @remarks
8653
+ * A `MeshRenderer` names it in its `lightmap` record. Only placements equal to
8654
+ * {@link IDENTITY_LIGHTMAP_PLACEMENT} are honoured for now: Babylon Lite 1.34's lightmap fragment
8655
+ * samples `uv2` without a transform, so a renderer with another placement logs `IGX-0735` once and
8656
+ * samples the whole texture until the atlas transform lands (GI plan §5, spike P2).
8657
+ *
8658
+ * @example
8659
+ * ```ts
8660
+ * const lightmap = await app.assets.loadAsync<LightmapAsset>("lighting/hall.lightmap.json");
8661
+ * entity.isStatic = true;
8662
+ * entity.addComponent(MeshRenderer, { mesh, lightmap: { asset: lightmap, mode: "add", level: 1, gamma: false, uv2: true } });
8663
+ * ```
8664
+ *
8665
+ * @beta
8666
+ */
8667
+ var LightmapAsset = class {
8668
+ /** The type name the asset service registers lightmaps under. */
8669
+ static assetType = LIGHTMAP_ASSET_TYPE;
8670
+ /** The baked texture. The asset does not own the handle: its loader or creator does. */
8671
+ texture;
8672
+ /** Per-entity placements, keyed by entity uid. */
8673
+ entries;
8674
+ /**
8675
+ * Wraps a texture and its checked placements. Use the loader or {@link createLightmapAsset}.
8676
+ *
8677
+ * @param texture - The baked texture.
8678
+ * @param entries - Placements already checked by `readLightmapEntries`.
8679
+ *
8680
+ * @internal
8681
+ */
8682
+ constructor(texture, entries) {
8683
+ this.texture = texture;
8684
+ this.entries = entries;
8685
+ }
8686
+ /**
8687
+ * The placement of one entity's UV2 square.
8688
+ *
8689
+ * @param entityId - The entity's uid.
8690
+ * @returns Its entry, or {@link IDENTITY_LIGHTMAP_PLACEMENT} when it has none.
8691
+ */
8692
+ placementOf(entityId) {
8693
+ return Object.hasOwn(this.entries, entityId) ? this.entries[entityId] ?? IDENTITY_LIGHTMAP_PLACEMENT : IDENTITY_LIGHTMAP_PLACEMENT;
8694
+ }
8695
+ };
8696
+ /**
8697
+ * Publishes a lightmap built in code, such as a texture from `TextureAsset.fromPixels`.
8698
+ *
8699
+ * @param app - The app.
8700
+ * @param texture - The baked texture; the caller keeps owning the handle.
8701
+ * @param entries - Per-entity placements, keyed by entity uid. Defaults to none.
8702
+ * @returns A handle a `MeshRenderer`'s `lightmap.asset` can take.
8703
+ * @throws IgnifxError with code `IGX-0709` when a placement is malformed.
8704
+ *
8705
+ * @beta
8706
+ */
8707
+ function createLightmapAsset(app, texture, entries = {}) {
8708
+ return app.assets.register(new LightmapAsset(texture, readLightmapEntries(entries, "lightmap entries")), { type: LIGHTMAP_ASSET_TYPE });
8709
+ }
8710
+ /**
8711
+ * Turns a lightmap description into the JSON a `.lightmap.json` file holds.
8712
+ *
8713
+ * @param data - The texture address and placements.
8714
+ * @returns The file contents, with the format header.
8715
+ *
8716
+ * @beta
8717
+ */
8718
+ function writeLightmapFile(data) {
8719
+ const entries = {};
8720
+ for (const id of Object.keys(data.entries).toSorted()) {
8721
+ const placement = data.entries[id];
8722
+ if (placement !== void 0) entries[id] = {
8723
+ scale: {
8724
+ x: placement.scale.x,
8725
+ y: placement.scale.y
8726
+ },
8727
+ offset: {
8728
+ x: placement.offset.x,
8729
+ y: placement.offset.y
8730
+ }
8731
+ };
8732
+ }
8733
+ return {
8734
+ format: LIGHTMAP_FILE_FORMAT,
8735
+ formatVersion: 1,
8736
+ texture: data.texture,
8737
+ entries
8738
+ };
8739
+ }
8740
+ /**
8741
+ * Reads a parsed `.lightmap.json`.
8742
+ *
8743
+ * @param parsed - The parsed JSON.
8744
+ * @param address - The file's address, for the error.
8745
+ * @returns The texture address and checked placements.
8746
+ * @throws IgnifxError with code `IGX-0709` when the header, the texture or a placement is wrong.
8747
+ *
8748
+ * @internal
8749
+ */
8750
+ function readLightmapFile(parsed, address) {
8751
+ const file = asRecord$1(parsed);
8752
+ if (file === null || file["format"] !== "ignifx-lightmap" || file["formatVersion"] !== 1) throw invalid(address, `it must start with { "format": "${LIGHTMAP_FILE_FORMAT}", "formatVersion": 1 }`);
8753
+ const texture = file["texture"];
8754
+ if (typeof texture !== "string" || texture.trim() === "") throw invalid(address, "texture must be the lightmap texture's asset address");
8755
+ return {
8756
+ texture,
8757
+ entries: readLightmapEntries(file["entries"] ?? {}, address)
8758
+ };
8759
+ }
8760
+ /**
8761
+ * Checks a set of per-entity placements.
8762
+ *
8763
+ * @remarks
8764
+ * A placement may leave out `scale` or `offset`; the missing half takes the identity's.
8765
+ *
8766
+ * @param value - The candidate `entries` object.
8767
+ * @param address - Where it came from, for the error.
8768
+ * @returns Checked copies, keyed by entity uid.
8769
+ * @throws IgnifxError with code `IGX-0709` on a malformed placement.
8770
+ *
8771
+ * @internal
8772
+ */
8773
+ function readLightmapEntries(value, address) {
8774
+ const record = asRecord$1(value);
8775
+ if (record === null) throw invalid(address, "entries must be an object keyed by entity id");
8776
+ const entries = {};
8777
+ for (const id of Object.keys(record)) {
8778
+ const entry = asRecord$1(record[id]);
8779
+ const scale = entry === null ? null : readVec2(entry["scale"], IDENTITY_LIGHTMAP_PLACEMENT.scale, (n) => n > 0);
8780
+ const offset = entry === null ? null : readVec2(entry["offset"], IDENTITY_LIGHTMAP_PLACEMENT.offset, () => true);
8781
+ if (id === "" || scale === null || offset === null) throw invalid(address, `entries["${id}"] must be { scale?: { x, y }, offset?: { x, y } } with finite numbers and a scale above 0`);
8782
+ entries[id] = {
8783
+ scale,
8784
+ offset
8785
+ };
8786
+ }
8787
+ return entries;
8788
+ }
8789
+ /**
8790
+ * Whether a placement is the identity, the only one Babylon Lite 1.34 can draw (GI plan §5, P2).
8791
+ *
8792
+ * @param placement - The placement.
8793
+ * @returns `true` for scale `(1, 1)` and offset `(0, 0)`.
8794
+ *
8795
+ * @internal
8796
+ */
8797
+ function isIdentityLightmapPlacement(placement) {
8798
+ const { scale, offset } = placement;
8799
+ return scale.x === 1 && scale.y === 1 && offset.x === 0 && offset.y === 0;
8800
+ }
8801
+ /**
8802
+ * Reads `{ x, y }` whose components are finite and pass a check, or takes a default when absent.
8803
+ *
8804
+ * @param value - The candidate, `undefined` when the field is absent.
8805
+ * @param fallback - The value an absent field takes.
8806
+ * @param check - The per-component test beyond finiteness.
8807
+ * @returns A copy, or `null` when it is malformed.
8808
+ */
8809
+ function readVec2(value, fallback, check) {
8810
+ if (value === void 0) return {
8811
+ x: fallback.x,
8812
+ y: fallback.y
8813
+ };
8814
+ const record = asRecord$1(value);
8815
+ const x = record?.["x"];
8816
+ const y = record?.["y"];
8817
+ if (typeof x !== "number" || typeof y !== "number" || ![x, y].every((n) => Number.isFinite(n) && check(n))) return null;
8818
+ return {
8819
+ x,
8820
+ y
8821
+ };
8822
+ }
8823
+ /**
8824
+ * Narrows a value to a plain record.
8825
+ *
8826
+ * @param value - The candidate.
8827
+ * @returns The record, or `null` for anything else.
8828
+ */
8829
+ function asRecord$1(value) {
8830
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
8831
+ return value;
8832
+ }
8833
+ /**
8834
+ * The error for a malformed lightmap.
8835
+ *
8836
+ * @param address - Where it came from.
8837
+ * @param problem - What is wrong.
8838
+ * @returns The error.
8839
+ */
8840
+ function invalid(address, problem) {
8841
+ return new IgnifxError(CoreErrorCode.invalidAssetFile, `${address} is not an ${LIGHTMAP_FILE_FORMAT} file.`, {
8842
+ context: {
8843
+ file: address,
8844
+ format: LIGHTMAP_FILE_FORMAT
8845
+ },
8846
+ hint: `Fix the file: ${problem}.`
8847
+ });
8848
+ }
8849
+ //#endregion
8850
+ //#region src/render/gpu/lightmap-host.ts
8851
+ /**
8852
+ * The renderer's handle on lightmaps (GI B3): it decides whether a `MeshRenderer` samples its
8853
+ * lightmap, loads the lightmap chunk (`./lightmaps.ts`) the first time one does, and hands the
8854
+ * renderer its lightmapped material. Device-only, like the rest of `src/render/gpu/`: only a
8855
+ * renderer with a clone in the scene asks.
8856
+ *
8857
+ * @internal
8858
+ */
8859
+ var LightmapHost = class {
8860
+ #app;
8861
+ #scene;
8862
+ #onError;
8863
+ #runtime = null;
8864
+ #isLoading = false;
8865
+ #isDisposed = false;
8866
+ /** The last `IGX-0735` reason reported per renderer, so each is logged once. */
8867
+ #reported = /* @__PURE__ */ new WeakMap();
8868
+ /**
8869
+ * Creates the host; nothing loads until a renderer samples a lightmap.
8870
+ *
8871
+ * @param app - The app, for the clones and the log.
8872
+ * @param scene - The registered render scene.
8873
+ * @param onError - Where a failed chunk load goes.
8874
+ */
8875
+ constructor(app, scene, onError) {
8876
+ this.#app = app;
8877
+ this.#scene = scene;
8878
+ this.#onError = onError;
8879
+ }
8880
+ /**
8881
+ * How many renderers draw with a lightmap right now.
8882
+ *
8883
+ * @returns The number of lightmapped clones.
8884
+ */
8885
+ get count() {
8886
+ return this.#runtime?.count ?? 0;
8887
+ }
8888
+ /**
8889
+ * The material a renderer draws with this frame.
8890
+ *
8891
+ * @remarks
8892
+ * A renderer samples its lightmap when its `lightmap.asset` is loaded, its entity is static and its
8893
+ * material is PBR; otherwise it draws with `base`, and a static or PBR mismatch logs `IGX-0735`
8894
+ * once. A placement other than the identity also logs `IGX-0735`, and the whole texture is used.
8895
+ *
8896
+ * @param owner - The renderer.
8897
+ * @param base - The material it declares (or the default material).
8898
+ * @returns The Lite material to draw with.
8899
+ */
8900
+ materialFor(owner, base) {
8901
+ const settings = owner.lightmap;
8902
+ const handle = settings?.asset ?? null;
8903
+ const lightmap = handle !== null && handle.state === "loaded" ? handle.value : null;
8904
+ if (settings === null || lightmap === null || this.#isDisposed) {
8905
+ this.release(owner);
8906
+ return base.lite.material;
8907
+ }
8908
+ const entity = owner.entity;
8909
+ let problem = null;
8910
+ if (!entity.isStatic) problem = "its entity is not static (entity.isStatic)";
8911
+ else if (base.kind !== "pbr") problem = `its material is a ${base.kind} material; lightmaps need a pbr one`;
8912
+ if (problem !== null) {
8913
+ this.#report(owner, problem);
8914
+ this.release(owner);
8915
+ return base.lite.material;
8916
+ }
8917
+ if (!isIdentityLightmapPlacement(lightmap.placementOf(entity.uid))) this.#report(owner, "its lightmap entry has a scale or offset, which is not applied yet; it samples the whole texture");
8918
+ const runtime = this.#runtime;
8919
+ if (runtime === null) {
8920
+ this.#load();
8921
+ return base.lite.material;
8922
+ }
8923
+ return runtime.materialFor(owner, base, lightmap, settings);
8924
+ }
8925
+ /**
8926
+ * Drops a renderer's lightmapped clone, if it has one.
8927
+ *
8928
+ * @param owner - The renderer.
8929
+ */
8930
+ release(owner) {
8931
+ this.#runtime?.release(owner);
8932
+ }
8933
+ /** Rebuilds the clones made this frame; the renderer calls it after every `MeshRenderer` synced. */
8934
+ flush() {
8935
+ this.#runtime?.flush();
8936
+ }
8937
+ /** Drops every clone. Idempotent. */
8938
+ dispose() {
8939
+ this.#isDisposed = true;
8940
+ this.#runtime?.dispose();
8941
+ this.#runtime = null;
8942
+ }
8943
+ /** Loads the chunk once. */
8944
+ #load() {
8945
+ if (this.#isLoading || this.#isDisposed) return;
8946
+ this.#isLoading = true;
8947
+ import("./lightmaps-LO6Ygtwe.js").then((module) => module.createLightmapRuntime(this.#app, this.#scene)).then((created) => {
8948
+ if (this.#isDisposed) {
8949
+ created.dispose();
8950
+ return;
8951
+ }
8952
+ this.#runtime = created;
8953
+ }).catch(this.#onError);
8954
+ }
8955
+ /**
8956
+ * Logs `IGX-0735` for a renderer, once per distinct reason.
8957
+ *
8958
+ * @param owner - The renderer.
8959
+ * @param problem - Why its lightmap is not drawn as declared.
8960
+ */
8961
+ #report(owner, problem) {
8962
+ if (this.#reported.get(owner) === problem) return;
8963
+ this.#reported.set(owner, problem);
8964
+ this.#app.log.warn(`${CoreErrorCode.lightmapNotApplied}: {entity}'s MeshRenderer lightmap: ${problem}.`, owner.entity.name);
8965
+ }
8966
+ };
8967
+ //#endregion
8604
8968
  //#region src/render/gpu/reflection-probe-host.ts
8605
8969
  /**
8606
8970
  * The renderer's handle on reflection probes (GI B1): it loads the probe chunk
@@ -8613,6 +8977,7 @@ var ReflectionProbeHost = class {
8613
8977
  #engine;
8614
8978
  #scene;
8615
8979
  #onError;
8980
+ #warn;
8616
8981
  #runtime = null;
8617
8982
  #isLoading = false;
8618
8983
  #isDisposed = false;
@@ -8622,11 +8987,13 @@ var ReflectionProbeHost = class {
8622
8987
  * @param engine - The engine.
8623
8988
  * @param scene - The registered render scene.
8624
8989
  * @param onError - Where a failed chunk load goes.
8990
+ * @param warn - Where a probe's warning goes: a message with an `{entity}` slot, and the name.
8625
8991
  */
8626
- constructor(engine, scene, onError) {
8992
+ constructor(engine, scene, onError, warn) {
8627
8993
  this.#engine = engine;
8628
8994
  this.#scene = scene;
8629
8995
  this.#onError = onError;
8996
+ this.#warn = warn;
8630
8997
  }
8631
8998
  /**
8632
8999
  * Whether the chunk is loaded and running.
@@ -8642,15 +9009,18 @@ var ReflectionProbeHost = class {
8642
9009
  * @param world - The world.
8643
9010
  * @param probes - Every `ReflectionProbe` in it.
8644
9011
  * @param isHdr - Whether `rendering.hdr` is on.
9012
+ * @param tier - The `rendering.quality` preset; `null` for `"custom"`.
9013
+ * @param hasEnvironment - Whether the scene has an environment map; until it has, the chunk is
9014
+ * not even loaded, since a probe needs the map's lighting tables.
8645
9015
  */
8646
- update(world, probes, isHdr) {
9016
+ update(world, probes, isHdr, tier, hasEnvironment) {
8647
9017
  if (this.#runtime !== null) {
8648
- this.#runtime.update(world, probes, isHdr);
9018
+ this.#runtime.update(world, probes, isHdr, tier, hasEnvironment);
8649
9019
  return;
8650
9020
  }
8651
- if (probes.length === 0 || this.#isLoading || this.#isDisposed) return;
9021
+ if (probes.length === 0 || !hasEnvironment || this.#isLoading || this.#isDisposed) return;
8652
9022
  this.#isLoading = true;
8653
- import("./reflection-probes-B8S9WnVX.js").then(async (module) => module.createReflectionProbeRuntime(this.#engine, this.#scene)).then((created) => {
9023
+ import("./reflection-probes-CUZcOjNW.js").then(async (module) => module.createReflectionProbeRuntime(this.#engine, this.#scene, this.#warn)).then((created) => {
8654
9024
  if (this.#isDisposed) {
8655
9025
  created.dispose();
8656
9026
  return;
@@ -8658,6 +9028,13 @@ var ReflectionProbeHost = class {
8658
9028
  this.#runtime = created;
8659
9029
  }).catch(this.#onError);
8660
9030
  }
9031
+ /**
9032
+ * Drops the probes' GPU state when the device is lost (`app.events.onDeviceLost`), before Lite's
9033
+ * recovery rebuilds the materials; they capture again once frames resume.
9034
+ */
9035
+ handleDeviceLost() {
9036
+ this.#runtime?.handleDeviceLost();
9037
+ }
8661
9038
  /** Frees every probe. Idempotent. */
8662
9039
  dispose() {
8663
9040
  this.#isDisposed = true;
@@ -9103,9 +9480,14 @@ const AMBIENT_OCCLUSION_QUALITIES = ["half", "full"];
9103
9480
  *
9104
9481
  * @remarks
9105
9482
  * - `"custom"` (default): every effect is exactly as the section and the `PostProcessStack`s say.
9106
- * - `"low"`: GTAO at half resolution; no HDR, TAA, contact shadows or SSGI.
9107
- * - `"medium"`: adds HDR and TAA, and lets a stack run contact shadows.
9108
- * - `"high"`: GTAO at full resolution, and lets a stack run SSGI.
9483
+ * - `"low"`: GTAO at half resolution; no HDR, TAA, contact shadows or SSGI; reflection probes at
9484
+ * 64 pixels a face at most.
9485
+ * - `"medium"`: adds HDR and TAA, lets a stack run contact shadows, and reflection probes up to 128.
9486
+ * - `"high"`: GTAO at full resolution, lets a stack run SSGI, reflection probes up to 256, and lets
9487
+ * a probe capture every frame.
9488
+ *
9489
+ * Below `"high"`, a `ReflectionProbe` with `refreshMode: "everyFrame"` captures as `"once"`.
9490
+ * Light probes and lightmaps run at every tier.
9109
9491
  *
9110
9492
  * @public
9111
9493
  */
@@ -9115,7 +9497,10 @@ const RENDERING_QUALITIES = [
9115
9497
  "medium",
9116
9498
  "high"
9117
9499
  ];
9118
- /** The presets of the three named tiers; `"custom"` has none. Bloom and tone mapping stay as authored. */
9500
+ /**
9501
+ * The presets of the three named tiers; `"custom"` has none. Bloom and tone mapping stay as authored.
9502
+ * Light probes and lightmaps run at every tier: baked lighting is the low-end path.
9503
+ */
9119
9504
  const QUALITY_PRESETS = {
9120
9505
  low: {
9121
9506
  hdr: false,
@@ -9123,7 +9508,9 @@ const QUALITY_PRESETS = {
9123
9508
  ambientOcclusion: true,
9124
9509
  ambientOcclusionQuality: "half",
9125
9510
  contactShadows: false,
9126
- ssgi: false
9511
+ ssgi: false,
9512
+ reflectionProbeMaxSize: 64,
9513
+ reflectionProbeEveryFrame: false
9127
9514
  },
9128
9515
  medium: {
9129
9516
  hdr: true,
@@ -9131,7 +9518,9 @@ const QUALITY_PRESETS = {
9131
9518
  ambientOcclusion: true,
9132
9519
  ambientOcclusionQuality: "half",
9133
9520
  contactShadows: true,
9134
- ssgi: false
9521
+ ssgi: false,
9522
+ reflectionProbeMaxSize: 128,
9523
+ reflectionProbeEveryFrame: false
9135
9524
  },
9136
9525
  high: {
9137
9526
  hdr: true,
@@ -9139,7 +9528,9 @@ const QUALITY_PRESETS = {
9139
9528
  ambientOcclusion: true,
9140
9529
  ambientOcclusionQuality: "full",
9141
9530
  contactShadows: true,
9142
- ssgi: true
9531
+ ssgi: true,
9532
+ reflectionProbeMaxSize: 256,
9533
+ reflectionProbeEveryFrame: true
9143
9534
  }
9144
9535
  };
9145
9536
  /**
@@ -9346,7 +9737,7 @@ function renderingSettingsSchema() {
9346
9737
  tooltip: "Camera jump per frame, in world units, that resets history."
9347
9738
  })
9348
9739
  }, { tooltip: "Temporal anti-aliasing (jittered frames accumulated over time). Needs rendering.hdr." }),
9349
- quality: enumOf(RENDERING_QUALITIES, "custom", { tooltip: "Quality tier. low: half-res GTAO. medium: adds HDR, TAA, contact shadows. high: full-res GTAO, SSGI. custom: as set. Fields you set win." })
9740
+ quality: enumOf(RENDERING_QUALITIES, "custom", { tooltip: "Quality tier. low: half-res GTAO, 64 px reflection probes. medium: adds HDR, TAA, contact shadows, 128 px probes. high: full-res GTAO, SSGI, 256 px probes, everyFrame probes. custom: as set. Fields you set win." })
9350
9741
  });
9351
9742
  }
9352
9743
  /**
@@ -9717,8 +10108,12 @@ var RendererImpl = class {
9717
10108
  #ambientOcclusion = null;
9718
10109
  /** The reflection probes' host, created on the first frame of a canvas-backed app (GI B1). */
9719
10110
  #reflectionProbes = null;
10111
+ /** Detaches the reflection probes' `app.events.onDeviceLost` handler. */
10112
+ #disconnectProbeDeviceLoss = null;
9720
10113
  /** The light probes' host, created with the reflection probes' one (GI B2). */
9721
10114
  #lightProbes = null;
10115
+ /** The lightmaps' host, created when the first renderer with a clone asks for its material (GI B3). */
10116
+ #lightmaps = null;
9722
10117
  /** The TAA passes (`../lite/gpu/taa.ts`), when `rendering.taa` installed them. */
9723
10118
  #taa = null;
9724
10119
  #defaultMaterial = null;
@@ -10550,7 +10945,8 @@ var RendererImpl = class {
10550
10945
  /**
10551
10946
  * The baked-lighting components' per-frame work (GI Phase 2): `ReflectionProbe` (B1) captures
10552
10947
  * what is due and points each lit PBR material at its probe; `LightProbeVolume` (B2) keeps the
10553
- * winning grid on every lit PBR material. Each loads its own chunk the first time a world has one
10948
+ * winning grid on every lit PBR material; lightmaps (B3) rebuild the material copies the
10949
+ * `MeshRenderer`s took this frame. Each loads its own chunk the first time a world has one
10554
10950
  * of its components. The `PreRender` system calls it every frame; it does nothing on a headless
10555
10951
  * app.
10556
10952
  *
@@ -10581,10 +10977,62 @@ var RendererImpl = class {
10581
10977
  component: null
10582
10978
  });
10583
10979
  };
10584
- this.#reflectionProbes ??= new ReflectionProbeHost(this.engine, this.scene, onError);
10980
+ if (this.#reflectionProbes === null) {
10981
+ const host = new ReflectionProbeHost(this.engine, this.scene, onError, (message, entityName) => {
10982
+ this.#app.log.warn(message, entityName);
10983
+ });
10984
+ this.#reflectionProbes = host;
10985
+ this.#disconnectProbeDeviceLoss = this.#app.events.onDeviceLost.connect(() => {
10986
+ host.handleDeviceLost();
10987
+ });
10988
+ }
10585
10989
  this.#lightProbes ??= new LightProbeHost(this.engine, this.scene, onError);
10586
- this.#reflectionProbes.update(world, probes, (this.#presenter?.hdr ?? null) !== null);
10990
+ this.#reflectionProbes.update(world, probes, (this.#presenter?.hdr ?? null) !== null, this.qualityPreset, readSceneEnvironment(this.scene) !== null);
10587
10991
  this.#lightProbes.update(volumes);
10992
+ this.#lightmaps?.flush();
10993
+ }
10994
+ /**
10995
+ * The material a `MeshRenderer` draws with this frame: its own lightmapped copy of `base` when it
10996
+ * samples a lightmap (GI B3), else `base`'s. Only a renderer with a clone in the scene asks, so
10997
+ * never a headless one.
10998
+ *
10999
+ * @param owner - The renderer.
11000
+ * @param base - The material asset it declares, or the default material.
11001
+ * @returns The Lite material.
11002
+ *
11003
+ * @internal
11004
+ */
11005
+ lightmapMaterial(owner, base) {
11006
+ this.#lightmaps ??= new LightmapHost(this.#app, this.scene, (error) => {
11007
+ this.#app.onError.emit({
11008
+ error,
11009
+ source: "system",
11010
+ phase: null,
11011
+ entity: null,
11012
+ component: null
11013
+ });
11014
+ });
11015
+ return this.#lightmaps.materialFor(owner, base);
11016
+ }
11017
+ /**
11018
+ * Drops a `MeshRenderer`'s lightmapped material copy, if it has one.
11019
+ *
11020
+ * @param owner - The renderer.
11021
+ *
11022
+ * @internal
11023
+ */
11024
+ releaseLightmap(owner) {
11025
+ this.#lightmaps?.release(owner);
11026
+ }
11027
+ /**
11028
+ * The lightmaps' host, for tests and diagnostics.
11029
+ *
11030
+ * @returns The host, or `null` before a renderer asked for a material.
11031
+ *
11032
+ * @internal
11033
+ */
11034
+ get lightmapHost() {
11035
+ return this.#lightmaps;
10588
11036
  }
10589
11037
  /**
10590
11038
  * The light probes' host, for tests and diagnostics.
@@ -10841,10 +11289,14 @@ var RendererImpl = class {
10841
11289
  this.#afterRebuild.length = 0;
10842
11290
  this.#ambientOcclusion?.dispose();
10843
11291
  this.#ambientOcclusion = null;
11292
+ this.#disconnectProbeDeviceLoss?.();
11293
+ this.#disconnectProbeDeviceLoss = null;
10844
11294
  this.#reflectionProbes?.dispose();
10845
11295
  this.#reflectionProbes = null;
10846
11296
  this.#lightProbes?.dispose();
10847
11297
  this.#lightProbes = null;
11298
+ this.#lightmaps?.dispose();
11299
+ this.#lightmaps = null;
10848
11300
  this.#sceneInputsHost?.dispose();
10849
11301
  this.#sceneInputsHost = null;
10850
11302
  this.#taa = null;
@@ -12913,6 +13365,623 @@ function createLightProbeLoader() {
12913
13365
  };
12914
13366
  }
12915
13367
  //#endregion
13368
+ //#region src/lite/gpu/texture.ts
13369
+ /**
13370
+ * Loads a 2D texture from a URL.
13371
+ *
13372
+ * @param engine - The engine that owns the GPU texture.
13373
+ * @param url - Where to fetch it from.
13374
+ * @param options - Sampler, mipmap, colour-space, and decode options.
13375
+ * @returns The texture. Its reference count starts at an implicit one.
13376
+ *
13377
+ * @example
13378
+ * ```ts
13379
+ * const albedo = await loadTexture(engine, "textures/hero-albedo.png", { srgb: true });
13380
+ * ```
13381
+ *
13382
+ * @internal
13383
+ */
13384
+ function loadTexture(engine, url, options) {
13385
+ return loadTexture2D(engine, url, options);
13386
+ }
13387
+ /**
13388
+ * Loads a KTX2 (Basis Universal) texture from a URL, transcoded to the device's best compressed
13389
+ * format.
13390
+ *
13391
+ * @remarks
13392
+ * Lite's KTX2 glue is imported on first use (`./decoders.ts`), so a game that never loads a `.ktx2`
13393
+ * does not carry it. The decoder script and its transcoders load from wherever
13394
+ * `applyLiteDecoderUrls` last pointed Lite, or from `cdn.babylonjs.com` when nothing did. Sampler and
13395
+ * sRGB options apply; `mipMaps`, `invertY` and `premultiplyAlpha` do not — the file's rows and mips
13396
+ * are uploaded as stored (`./decoders.ts` explains the orientation).
13397
+ *
13398
+ * @param engine - The engine that owns the GPU texture.
13399
+ * @param url - Where to fetch it from.
13400
+ * @param options - Colour space and sampler.
13401
+ * @returns The texture. Its reference count starts at an implicit one.
13402
+ *
13403
+ * @example
13404
+ * ```ts
13405
+ * const albedo = await loadKtx2Texture(engine, "textures/hero-albedo.ktx2", { srgb: true });
13406
+ * ```
13407
+ *
13408
+ * @internal
13409
+ */
13410
+ async function loadKtx2Texture(engine, url, options = {}) {
13411
+ return (await import("./decoders-BUQrlS8U.js")).loadKtx2TextureWithOptions(engine, url, options);
13412
+ }
13413
+ /**
13414
+ * Loads a Basis Universal (`.basis`) texture from a URL.
13415
+ *
13416
+ * @remarks
13417
+ * Babylon Lite 1.34 always fetches the Basis transcoder from `cdn.babylonjs.com` and offers no
13418
+ * setter for it, so this works only where the page may load scripts from that origin. Prefer
13419
+ * `.ktx2`, which carries the same Basis payloads and whose decoder is served locally.
13420
+ *
13421
+ * @param engine - The engine that owns the GPU texture.
13422
+ * @param url - Where to fetch it from.
13423
+ * @param options - Colour space and sampler.
13424
+ * @returns The texture.
13425
+ *
13426
+ * @internal
13427
+ */
13428
+ async function loadBasisTexture(engine, url, options = {}) {
13429
+ return (await import("./decoders-BUQrlS8U.js")).loadBasisTextureWithOptions(engine, url, options);
13430
+ }
13431
+ /**
13432
+ * Creates a 2D texture from tightly packed RGBA8 bytes.
13433
+ *
13434
+ * @param engine - The engine that owns the GPU texture.
13435
+ * @param data - `width * height * 4` bytes, row-major, top row first, straight alpha.
13436
+ * @param width - The width in texels, at least 1.
13437
+ * @param height - The height in texels, at least 1.
13438
+ * @param options - Sampler and colour-space overrides.
13439
+ * @returns The texture, created with `COPY_DST` so {@link updateTextureFromPixels} can write to it.
13440
+ * Its reference count starts at an implicit one.
13441
+ *
13442
+ * @internal
13443
+ */
13444
+ function createTextureFromPixels(engine, data, width, height, options) {
13445
+ return createTexture2DFromPixels(engine, data, width, height, {
13446
+ addressModeU: options.addressModeU,
13447
+ addressModeV: options.addressModeV,
13448
+ minFilter: options.minFilter,
13449
+ magFilter: options.magFilter,
13450
+ srgb: options.srgb
13451
+ });
13452
+ }
13453
+ /**
13454
+ * Writes a rectangular region of a pixel texture.
13455
+ *
13456
+ * @remarks
13457
+ * Only legal on a texture from {@link createTextureFromPixels}: any other `Texture2D` was created
13458
+ * without `COPY_DST` usage and WebGPU rejects the write.
13459
+ *
13460
+ * @param engine - The engine that owns the texture.
13461
+ * @param texture - The target.
13462
+ * @param data - `width * height * 4` bytes for the region, row-major.
13463
+ * @param x - The destination origin's column, in texels.
13464
+ * @param y - The destination origin's row, in texels.
13465
+ * @param width - The region's width, in texels.
13466
+ * @param height - The region's height, in texels.
13467
+ *
13468
+ * @internal
13469
+ */
13470
+ function updateTextureFromPixels(engine, texture, data, x, y, width, height) {
13471
+ updateTexture2DFromPixels(engine, texture, data, x, y, width, height);
13472
+ }
13473
+ /**
13474
+ * Claims a share of a texture, so a later {@link releaseTextureHandle} by someone else does not
13475
+ * destroy it.
13476
+ *
13477
+ * @param texture - The texture to retain.
13478
+ *
13479
+ * @internal
13480
+ */
13481
+ function retainTexture(texture) {
13482
+ acquireTexture(texture);
13483
+ }
13484
+ /**
13485
+ * Gives up a share of a texture, destroying it when the last share goes.
13486
+ *
13487
+ * @param texture - The texture to release.
13488
+ * @returns `true` when this call destroyed the underlying `GPUTexture`.
13489
+ *
13490
+ * @internal
13491
+ */
13492
+ function releaseTextureHandle(texture) {
13493
+ return releaseTexture(texture);
13494
+ }
13495
+ //#endregion
13496
+ //#region src/render/gpu/texture-pixels.ts
13497
+ /**
13498
+ * The device-only half of `TextureAsset` (`docs/architecture/07-rendering.md` §6).
13499
+ *
13500
+ * Each function takes the engine or the texture as a nullable and returns early when it is `null`,
13501
+ * so the asset keeps no headless branch of its own.
13502
+ */
13503
+ /**
13504
+ * Creates a texture from tightly packed RGBA8 bytes, or nothing under a headless app.
13505
+ *
13506
+ * @param isHeadless - Whether the app has a device.
13507
+ * @param engine - The engine that uploads it.
13508
+ * @param data - `width * height * 4` bytes, row-major, top row first, straight alpha.
13509
+ * @param width - The width in texels.
13510
+ * @param height - The height in texels.
13511
+ * @param options - The resolved import options; only the sampler subset reaches Lite.
13512
+ * @returns The texture, or `null`.
13513
+ *
13514
+ * @internal
13515
+ */
13516
+ function createPixelTexture(isHeadless, engine, data, width, height, options) {
13517
+ if (isHeadless) return null;
13518
+ return createTextureFromPixels(engine, data, width, height, {
13519
+ addressModeU: options.addressModeU,
13520
+ addressModeV: options.addressModeV,
13521
+ minFilter: options.minFilter,
13522
+ magFilter: options.magFilter,
13523
+ srgb: options.srgb
13524
+ });
13525
+ }
13526
+ /**
13527
+ * Writes a rectangular region of a pixel texture, when it still has one.
13528
+ *
13529
+ * @param engine - The engine that owns the queue.
13530
+ * @param texture - The target, or `null` when the app is headless or the share was released.
13531
+ * @param data - The region's RGBA8 bytes.
13532
+ * @param x - The destination column.
13533
+ * @param y - The destination row.
13534
+ * @param width - The region width.
13535
+ * @param height - The region height.
13536
+ *
13537
+ * @internal
13538
+ */
13539
+ function writePixelTexture(engine, texture, data, x, y, width, height) {
13540
+ if (texture === null) return;
13541
+ updateTextureFromPixels(engine, texture, data, x, y, width, height);
13542
+ }
13543
+ /**
13544
+ * Claims an extra share of a texture, when there is one.
13545
+ *
13546
+ * @param texture - The texture, or `null`.
13547
+ *
13548
+ * @internal
13549
+ */
13550
+ function retainTextureShare(texture) {
13551
+ if (texture === null) return;
13552
+ retainTexture(texture);
13553
+ }
13554
+ /**
13555
+ * Gives up a share of a texture, when there is one.
13556
+ *
13557
+ * @param texture - The texture, or `null`.
13558
+ * @returns `true` when this call destroyed the underlying `GPUTexture`.
13559
+ *
13560
+ * @internal
13561
+ */
13562
+ function releaseTextureShare(texture) {
13563
+ return texture === null ? false : releaseTextureHandle(texture);
13564
+ }
13565
+ //#endregion
13566
+ //#region src/render/texture-asset.ts
13567
+ /**
13568
+ * `TextureAsset` (`docs/architecture/05-assets-and-loading.md` §5, `07-rendering.md` §7): a GPU
13569
+ * texture plus the import options the build recorded for it.
13570
+ *
13571
+ * ## Lifetime, and why the loader does not `acquireTexture`
13572
+ *
13573
+ * Lite reference-counts `GPUTexture`s in a process-wide pool keyed by the underlying texture
13574
+ * (`lib/resource/gpu-pool.js`): `acquireTexture` increments, `releaseTexture` decrements and
13575
+ * destroys at zero, and **a texture that was never acquired starts at an implicit count of one**.
13576
+ * A freshly loaded texture is therefore already owned once, by the asset that loaded it. Calling
13577
+ * `acquireTexture` in the loader — which `07-rendering.md` §7 could be read as asking for — would
13578
+ * put the count at two and make the matching `releaseTexture` on unload free nothing: a leak, not a
13579
+ * safety net. So the loader acquires nothing and {@link TextureAsset.releaseGpu} releases the one
13580
+ * implicit share when the asset is unloaded.
13581
+ *
13582
+ * Sharing is expressed one level up instead. A `MaterialAsset` that samples a texture pulls it in
13583
+ * with `ctx.loadDependency`, which retains the *asset handle*; the texture's GPU share is released
13584
+ * only when the last asset holding that handle is collected. That is the same rule every other
13585
+ * dependency follows, and it is observable through `handle.refCount`.
13586
+ * {@link TextureAsset.retainGpu} exists for the rare case where a Lite object outlives its asset.
13587
+ *
13588
+ * {@link TextureAsset.fromPixels} is the other way in: RGBA8 bytes, no file, published at a
13589
+ * `memory:texture/<ulid>` address the way `MeshAsset`'s primitive factories are. It is the **only**
13590
+ * kind of texture {@link TextureAsset.update} accepts, because `createTexture2DFromPixels` is what
13591
+ * asks WebGPU for `COPY_DST` usage (`index.d.ts` 13400). The bytes are copied at creation and not
13592
+ * retained; the asset keeps only the size, which is what `update` validates against.
13593
+ *
13594
+ * ## Headless
13595
+ *
13596
+ * `loadTexture2D` uploads through `engine._device`, which the null engine has none of, so a
13597
+ * headless load produces an asset with `lite.texture === null` — the `gpu: null` shape
13598
+ * `05-assets-and-loading.md` §5 requires of every GPU loader. `fromPixels` behaves the same way and
13599
+ * still validates and records the size, so a Node test can assert that a generator wrote the right
13600
+ * number of bytes without a device.
13601
+ */
13602
+ /**
13603
+ * The asset type textures are registered under.
13604
+ *
13605
+ * @public
13606
+ */
13607
+ const TEXTURE_ASSET_TYPE = "texture";
13608
+ /**
13609
+ * A loaded 2D texture (`docs/architecture/05-assets-and-loading.md` §5).
13610
+ *
13611
+ * @example
13612
+ * ```ts
13613
+ * const albedo = await app.assets.loadAsync<TextureAsset>("textures/hero-albedo.png");
13614
+ * albedo.value.options.srgb; // what the .meta.json sidecar asked for
13615
+ * ```
13616
+ *
13617
+ * @public
13618
+ */
13619
+ var TextureAsset = class TextureAsset {
13620
+ /** The type name the asset service registers textures under. */
13621
+ static assetType = TEXTURE_ASSET_TYPE;
13622
+ /** The address the texture was loaded from. */
13623
+ address;
13624
+ /** The resolved import options, sidecar values merged onto the defaults. */
13625
+ options;
13626
+ #texture;
13627
+ #pixelSource;
13628
+ /**
13629
+ * Wraps a loaded texture. The `texture` loader and {@link TextureAsset.fromPixels} construct
13630
+ * these.
13631
+ *
13632
+ * @param address - The address it was loaded from, or the `memory:` address it was published at.
13633
+ * @param texture - The GPU texture, or `null` when the app is headless.
13634
+ * @param options - The resolved import options.
13635
+ * @param pixelSource - The engine and size of a texture built from raw pixels, or `null` for a
13636
+ * texture that came from a file. It is what makes {@link TextureAsset.update} legal.
13637
+ *
13638
+ * @internal
13639
+ */
13640
+ constructor(address, texture, options, pixelSource = null) {
13641
+ this.address = address;
13642
+ this.#texture = texture;
13643
+ this.options = options;
13644
+ this.#pixelSource = pixelSource;
13645
+ }
13646
+ /**
13647
+ * The Babylon Lite objects the asset owns. Unstable escape hatch.
13648
+ *
13649
+ * @returns The GPU texture, or `null` under a headless app.
13650
+ */
13651
+ get lite() {
13652
+ return { texture: this.#texture };
13653
+ }
13654
+ /**
13655
+ * The texture's width, in texels.
13656
+ *
13657
+ * @remarks
13658
+ * Known for every texture that reached the GPU — Lite records it on the texture handle
13659
+ * (`index.d.ts` 12876) — and for a headless {@link TextureAsset.fromPixels} texture, which
13660
+ * remembers the size it was asked for. A texture **loaded** from a file under a headless app
13661
+ * decoded nothing, so it reports `0`.
13662
+ *
13663
+ * @returns The width, or `0` when nothing knows it.
13664
+ */
13665
+ get width() {
13666
+ return this.#texture?.width ?? this.#pixelSource?.width ?? 0;
13667
+ }
13668
+ /**
13669
+ * The texture's height, in texels.
13670
+ *
13671
+ * @returns The height, or `0`; see {@link TextureAsset.width}.
13672
+ */
13673
+ get height() {
13674
+ return this.#texture?.height ?? this.#pixelSource?.height ?? 0;
13675
+ }
13676
+ /**
13677
+ * Whether the GPU texture has been given up.
13678
+ *
13679
+ * @returns `true` once {@link TextureAsset.releaseGpu} has run.
13680
+ */
13681
+ get isReleased() {
13682
+ return this.#texture === null;
13683
+ }
13684
+ /**
13685
+ * Claims an extra share of the GPU texture, so releasing the asset does not destroy it.
13686
+ *
13687
+ * @remarks
13688
+ * Only needed when a Lite object has to outlive the asset that loaded it. Ordinary sharing goes
13689
+ * through `ctx.loadDependency`, which counts the asset handle instead.
13690
+ */
13691
+ retainGpu() {
13692
+ retainTextureShare(this.#texture);
13693
+ }
13694
+ /**
13695
+ * Gives up the asset's share of the GPU texture, destroying it when it was the last one. Calling
13696
+ * it twice is a no-op, and it is a no-op under a headless app.
13697
+ *
13698
+ * @returns `true` when this call destroyed the underlying `GPUTexture`.
13699
+ */
13700
+ releaseGpu() {
13701
+ const texture = this.#texture;
13702
+ this.#texture = null;
13703
+ return releaseTextureShare(texture);
13704
+ }
13705
+ /**
13706
+ * Writes a rectangular region of the texture from RGBA8 bytes.
13707
+ *
13708
+ * @remarks
13709
+ * Only a texture from {@link TextureAsset.fromPixels} can be written to: that is the factory that
13710
+ * asks WebGPU for `COPY_DST` usage. The region defaults to the whole texture. Nothing is uploaded
13711
+ * under a headless app, but the size check still runs, so a generator's arithmetic is testable
13712
+ * without a device.
13713
+ *
13714
+ * The texture has one mip level, so there is no chain to regenerate and an update is complete the
13715
+ * moment the queue drains.
13716
+ *
13717
+ * @param data - `width * height * 4` bytes for the region, row-major, top row first.
13718
+ * @param x - The destination origin's column. Defaults to `0`.
13719
+ * @param y - The destination origin's row. Defaults to `0`.
13720
+ * @param width - The region's width. Defaults to the texture's width.
13721
+ * @param height - The region's height. Defaults to the texture's height.
13722
+ * @throws IgnifxError with code `IGX-0702` when the texture did not come from
13723
+ * {@link TextureAsset.fromPixels}.
13724
+ * @throws IgnifxError with code `IGX-0722` when the region falls outside the texture or `data` is
13725
+ * not exactly `width * height * 4` bytes long.
13726
+ *
13727
+ * @example
13728
+ * ```ts
13729
+ * const splat = TextureAsset.fromPixels(app, "splat", pixels, 256, 256);
13730
+ * pixels[0] = 255;
13731
+ * splat.value.update(pixels.subarray(0, 4), 0, 0, 1, 1); // one texel
13732
+ * ```
13733
+ */
13734
+ update(data, x = 0, y = 0, width, height) {
13735
+ const source = this.#pixelSource;
13736
+ if (source === null) throw new IgnifxError(CoreErrorCode.invalidRuntime, `${this.address} was not created by TextureAsset.fromPixels, so it cannot be updated.`, {
13737
+ context: {
13738
+ asset: this.address,
13739
+ member: "TextureAsset.update()"
13740
+ },
13741
+ hint: "Only a texture built with TextureAsset.fromPixels carries the COPY_DST usage an update needs."
13742
+ });
13743
+ const regionWidth = width ?? source.width;
13744
+ const regionHeight = height ?? source.height;
13745
+ assertPixelRegion(this.address, data, source, x, y, regionWidth, regionHeight);
13746
+ writePixelTexture(source.engine, this.#texture, data, x, y, regionWidth, regionHeight);
13747
+ }
13748
+ /**
13749
+ * Creates a texture from tightly packed RGBA8 bytes and publishes it as an in-memory asset.
13750
+ *
13751
+ * @remarks
13752
+ * The bytes are `width * height * 4` long, row-major, **top row first**, with straight (not
13753
+ * premultiplied) alpha. They are copied into the GPU texture and not retained.
13754
+ *
13755
+ * The result is the only kind of texture {@link TextureAsset.update} accepts. Ownership follows
13756
+ * the rule every in-code asset follows: the caller holds the handle, releasing it (or letting a
13757
+ * `using` block do it) runs the `texture` type's unload, which releases the GPU share.
13758
+ *
13759
+ * @param app - The app whose engine uploads the texture and whose asset service holds the handle.
13760
+ * @param name - A human-readable name. It becomes the asset's `address` — the string diagnostics
13761
+ * and the `IGX-0722` message name it by — while the handle's own address is the generated
13762
+ * `memory:texture/<ulid>` the asset service published it at.
13763
+ * @param data - `width * height * 4` bytes.
13764
+ * @param width - The width in texels, at least 1.
13765
+ * @param height - The height in texels, at least 1.
13766
+ * @param options - Sampler and colour-space overrides; `nearest`, `clamp`, no sRGB by default.
13767
+ * @returns The handle, already loaded, with one holder — the caller.
13768
+ * @throws IgnifxError with code `IGX-0722` when `width` or `height` is not a positive integer, or
13769
+ * `data` is not exactly `width * height * 4` bytes long.
13770
+ *
13771
+ * @example
13772
+ * ```ts
13773
+ * const pixels = new Uint8Array(2 * 2 * 4);
13774
+ * pixels.fill(255);
13775
+ * using ramp = TextureAsset.fromPixels(app, "ramp", pixels, 2, 2, { filter: "nearest" });
13776
+ * ```
13777
+ */
13778
+ static fromPixels(app, name, data, width, height, options) {
13779
+ assertPixelSize(name, data, width, height);
13780
+ const resolved = resolvePixelOptions(options);
13781
+ const engine = app.lite.engine;
13782
+ const texture = createPixelTexture(app.isHeadless, engine, data, width, height, resolved);
13783
+ const asset = new TextureAsset(name, texture, resolved, {
13784
+ engine,
13785
+ width,
13786
+ height
13787
+ });
13788
+ return app.assets.register(asset, { type: TEXTURE_ASSET_TYPE });
13789
+ }
13790
+ };
13791
+ /**
13792
+ * How many bytes one RGBA8 texel occupies.
13793
+ */
13794
+ const BYTES_PER_TEXEL = 4;
13795
+ /**
13796
+ * Checks that a byte count matches a texture size.
13797
+ *
13798
+ * @param asset - The name or address named in the error.
13799
+ * @param data - The pixel bytes.
13800
+ * @param width - The width in texels.
13801
+ * @param height - The height in texels.
13802
+ * @throws IgnifxError with code `IGX-0722` when the size is not a positive integer pair or the byte
13803
+ * count does not match.
13804
+ */
13805
+ function assertPixelSize(asset, data, width, height) {
13806
+ const valid = Number.isInteger(width) && Number.isInteger(height) && width > 0 && height > 0;
13807
+ const expected = width * height * BYTES_PER_TEXEL;
13808
+ if (valid && data.length === expected) return;
13809
+ throw new IgnifxError(CoreErrorCode.invalidPixelData, `${asset}: ${String(data.length)} bytes of pixel data do not match ${String(width)}x${String(height)} RGBA.`, {
13810
+ context: {
13811
+ asset,
13812
+ bytes: data.length,
13813
+ width,
13814
+ height
13815
+ },
13816
+ hint: "RGBA8 pixel data is exactly width * height * 4 bytes, row-major with the top row first."
13817
+ });
13818
+ }
13819
+ /**
13820
+ * Checks that an update's region lies inside the texture and that the byte count matches it.
13821
+ *
13822
+ * @param asset - The address named in the error.
13823
+ * @param data - The pixel bytes.
13824
+ * @param source - The texture's recorded size.
13825
+ * @param x - The region's origin column.
13826
+ * @param y - The region's origin row.
13827
+ * @param width - The region's width.
13828
+ * @param height - The region's height.
13829
+ * @throws IgnifxError with code `IGX-0722` when the region does not fit or the byte count is wrong.
13830
+ */
13831
+ function assertPixelRegion(asset, data, source, x, y, width, height) {
13832
+ if (!(Number.isInteger(x) && Number.isInteger(y) && x >= 0 && y >= 0 && x + width <= source.width && y + height <= source.height)) throw new IgnifxError(CoreErrorCode.invalidPixelData, `${asset}: the region ${String(width)}x${String(height)} at (${String(x)}, ${String(y)}) falls outside a ${String(source.width)}x${String(source.height)} texture.`, {
13833
+ context: {
13834
+ asset,
13835
+ bytes: data.length,
13836
+ x,
13837
+ y,
13838
+ width,
13839
+ height
13840
+ },
13841
+ hint: "An update writes inside the texture it was created with; recreate it to change its size."
13842
+ });
13843
+ assertPixelSize(asset, data, width, height);
13844
+ }
13845
+ /**
13846
+ * Fills in {@link PixelTextureOptions}'s defaults as a complete {@link TextureImportOptions}, so a
13847
+ * pixel texture reports its sampler state the way a loaded one does.
13848
+ *
13849
+ * @param options - What the caller named.
13850
+ * @returns The resolved options.
13851
+ */
13852
+ function resolvePixelOptions(options) {
13853
+ const filter = options?.filter ?? "nearest";
13854
+ const wrap = options?.wrap === "repeat" ? "repeat" : "clamp-to-edge";
13855
+ return {
13856
+ srgb: options?.srgb ?? false,
13857
+ mipMaps: false,
13858
+ addressModeU: wrap,
13859
+ addressModeV: wrap,
13860
+ minFilter: filter,
13861
+ magFilter: filter,
13862
+ invertY: false,
13863
+ premultiplyAlpha: false
13864
+ };
13865
+ }
13866
+ /**
13867
+ * The import options a texture gets when its sidecar names none: Lite's own defaults, with `srgb`
13868
+ * off so that a data map is never silently decoded.
13869
+ *
13870
+ * @returns A fresh option set.
13871
+ *
13872
+ * @internal
13873
+ */
13874
+ function defaultTextureImportOptions() {
13875
+ return {
13876
+ srgb: false,
13877
+ mipMaps: true,
13878
+ addressModeU: "repeat",
13879
+ addressModeV: "repeat",
13880
+ minFilter: "linear",
13881
+ magFilter: "linear",
13882
+ invertY: true,
13883
+ premultiplyAlpha: false
13884
+ };
13885
+ }
13886
+ /**
13887
+ * Reads the `texture` block of a `.meta.json` sidecar over the defaults.
13888
+ *
13889
+ * @remarks
13890
+ * Unknown keys and values of the wrong type are ignored rather than rejected: a sidecar is written
13891
+ * by hand and shared with other tools, and a typo in an optional import hint must not stop a game
13892
+ * from starting (`CONSTITUTION.md` §3.9 — the asset still loads, with the documented default).
13893
+ *
13894
+ * @param meta - The whole sidecar, or `null` when the manifest recorded none.
13895
+ * @returns The resolved options.
13896
+ *
13897
+ * @internal
13898
+ */
13899
+ function readTextureImportOptions(meta) {
13900
+ const defaults = defaultTextureImportOptions();
13901
+ const raw = meta === null ? void 0 : meta[TEXTURE_ASSET_TYPE];
13902
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return defaults;
13903
+ const block = raw;
13904
+ return {
13905
+ srgb: readBoolean$1(block, "srgb", defaults.srgb),
13906
+ mipMaps: readBoolean$1(block, "mipMaps", defaults.mipMaps),
13907
+ addressModeU: readString$2(block, "addressModeU", defaults.addressModeU),
13908
+ addressModeV: readString$2(block, "addressModeV", defaults.addressModeV),
13909
+ minFilter: readString$2(block, "minFilter", defaults.minFilter),
13910
+ magFilter: readString$2(block, "magFilter", defaults.magFilter),
13911
+ invertY: readBoolean$1(block, "invertY", defaults.invertY),
13912
+ premultiplyAlpha: readBoolean$1(block, "premultiplyAlpha", defaults.premultiplyAlpha)
13913
+ };
13914
+ }
13915
+ /**
13916
+ * Turns the resolved options into the shape `loadTexture2D` takes.
13917
+ *
13918
+ * @remarks
13919
+ * The sampler strings are handed to Lite as declared; WebGPU rejects a mode or filter it does not
13920
+ * know, and that failure is a clearer signal than an ignored option would be.
13921
+ *
13922
+ * @param options - The resolved import options.
13923
+ * @returns Lite's options.
13924
+ *
13925
+ * @internal
13926
+ */
13927
+ function toLiteTextureOptions(options) {
13928
+ return {
13929
+ srgb: options.srgb,
13930
+ mipMaps: options.mipMaps,
13931
+ addressModeU: options.addressModeU,
13932
+ addressModeV: options.addressModeV,
13933
+ minFilter: options.minFilter,
13934
+ magFilter: options.magFilter,
13935
+ invertY: options.invertY,
13936
+ premultiplyAlpha: options.premultiplyAlpha
13937
+ };
13938
+ }
13939
+ /**
13940
+ * Reads a boolean out of a sidecar block.
13941
+ *
13942
+ * @param block - The sidecar sub-object.
13943
+ * @param key - The property name.
13944
+ * @param fallback - What to use when the property is absent or not a boolean.
13945
+ * @returns The value.
13946
+ */
13947
+ function readBoolean$1(block, key, fallback) {
13948
+ const value = block[key];
13949
+ return typeof value === "boolean" ? value : fallback;
13950
+ }
13951
+ /**
13952
+ * Reads a string out of a sidecar block.
13953
+ *
13954
+ * @param block - The sidecar sub-object.
13955
+ * @param key - The property name.
13956
+ * @param fallback - What to use when the property is absent or not a string.
13957
+ * @returns The value.
13958
+ */
13959
+ function readString$2(block, key, fallback) {
13960
+ const value = block[key];
13961
+ return typeof value === "string" ? value : fallback;
13962
+ }
13963
+ //#endregion
13964
+ //#region src/render/loaders/lightmap-loader.ts
13965
+ /**
13966
+ * Builds the loader for `.lightmap.json` lightmaps (GI Phase 2, step B3). The texture the file names
13967
+ * loads as a dependency, so it is released with the lightmap; a texture that fails to load fails
13968
+ * the lightmap.
13969
+ *
13970
+ * @returns The loader to register with `ctx.registerAssetLoader`.
13971
+ *
13972
+ * @beta
13973
+ */
13974
+ function createLightmapLoader() {
13975
+ return {
13976
+ type: LIGHTMAP_ASSET_TYPE,
13977
+ extensions: LIGHTMAP_FILE_EXTENSIONS,
13978
+ async load(ctx) {
13979
+ const file = readLightmapFile(await ctx.fetchJson(), ctx.address);
13980
+ return new LightmapAsset(await ctx.loadDependency(file.texture, { type: TEXTURE_ASSET_TYPE }), file.entries);
13981
+ }
13982
+ };
13983
+ }
13984
+ //#endregion
12916
13985
  //#region src/render/shader-material-definition.ts
12917
13986
  /**
12918
13987
  * Builds a `"shader"` material declaration, recording the addresses of the handles it is given.
@@ -13155,7 +14224,7 @@ async function loadTextures(ctx, addresses) {
13155
14224
  */
13156
14225
  function readPbr(file, textures, surfaces) {
13157
14226
  return pbrMaterialDefinition({
13158
- name: readString$2(file, "name", ""),
14227
+ name: readString$1(file, "name", ""),
13159
14228
  baseColor: readColor(file, "baseColor", {
13160
14229
  r: 1,
13161
14230
  g: 1,
@@ -13175,8 +14244,8 @@ function readPbr(file, textures, surfaces) {
13175
14244
  alphaMode: readAlphaMode(file),
13176
14245
  alphaCutoff: readNumber(file, "alphaCutoff", .5),
13177
14246
  alpha: readNumber(file, "alpha", 1),
13178
- doubleSided: readBoolean$1(file, "doubleSided", false),
13179
- unlit: readBoolean$1(file, "unlit", false),
14247
+ doubleSided: readBoolean(file, "doubleSided", false),
14248
+ unlit: readBoolean(file, "unlit", false),
13180
14249
  environmentIntensity: readNumber(file, "environmentIntensity", 1),
13181
14250
  textures,
13182
14251
  surfaces
@@ -13192,7 +14261,7 @@ function readPbr(file, textures, surfaces) {
13192
14261
  */
13193
14262
  function readStandard(file, textures, surfaces) {
13194
14263
  return standardMaterialDefinition({
13195
- name: readString$2(file, "name", ""),
14264
+ name: readString$1(file, "name", ""),
13196
14265
  diffuse: readColor(file, "diffuse", {
13197
14266
  r: 1,
13198
14267
  g: 1,
@@ -13214,8 +14283,8 @@ function readStandard(file, textures, surfaces) {
13214
14283
  }),
13215
14284
  alpha: readNumber(file, "alpha", 1),
13216
14285
  alphaCutoff: readNumber(file, "alphaCutoff", 0),
13217
- doubleSided: readBoolean$1(file, "doubleSided", false),
13218
- unlit: readBoolean$1(file, "unlit", false),
14286
+ doubleSided: readBoolean(file, "doubleSided", false),
14287
+ unlit: readBoolean(file, "unlit", false),
13219
14288
  textures,
13220
14289
  surfaces
13221
14290
  });
@@ -13257,10 +14326,10 @@ function readSurfaceReferences(file, address) {
13257
14326
  const record = entry;
13258
14327
  references.push({
13259
14328
  shader,
13260
- name: readString$2(record, "name", ""),
14329
+ name: readString$1(record, "name", ""),
13261
14330
  values: readValues(record),
13262
14331
  textures: readTextureRecord(record),
13263
- enabled: readBoolean$1(record, "enabled", true),
14332
+ enabled: readBoolean(record, "enabled", true),
13264
14333
  priority: readNumber(record, "priority", SURFACE_PRIORITY)
13265
14334
  });
13266
14335
  }
@@ -13346,7 +14415,7 @@ function readNumber(file, key, fallback) {
13346
14415
  * @param fallback - What to use when it is absent or not a boolean.
13347
14416
  * @returns The value.
13348
14417
  */
13349
- function readBoolean$1(file, key, fallback) {
14418
+ function readBoolean(file, key, fallback) {
13350
14419
  const value = file[key];
13351
14420
  return typeof value === "boolean" ? value : fallback;
13352
14421
  }
@@ -13358,7 +14427,7 @@ function readBoolean$1(file, key, fallback) {
13358
14427
  * @param fallback - What to use when it is absent or not a string.
13359
14428
  * @returns The value.
13360
14429
  */
13361
- function readString$2(file, key, fallback) {
14430
+ function readString$1(file, key, fallback) {
13362
14431
  const value = file[key];
13363
14432
  return typeof value === "string" ? value : fallback;
13364
14433
  }
@@ -13403,7 +14472,7 @@ function channel(value, fallback) {
13403
14472
  * value of the wrong shape.
13404
14473
  */
13405
14474
  async function loadShaderMaterial(ctx, file) {
13406
- const address = readString$2(file, "shader", "");
14475
+ const address = readString$1(file, "shader", "");
13407
14476
  if (address === "") throw new IgnifxError(CoreErrorCode.invalidAssetFile, `${ctx.address} declares no shader.`, {
13408
14477
  context: {
13409
14478
  file: ctx.address,
@@ -13416,7 +14485,7 @@ async function loadShaderMaterial(ctx, file) {
13416
14485
  const [resolved] = await Promise.all([loadNamedTextures(ctx, requested), loadShaderSupport()]);
13417
14486
  return buildMaterialAsset(shaderMaterialDefinition({
13418
14487
  shader: address,
13419
- name: readString$2(file, "name", address),
14488
+ name: readString$1(file, "name", address),
13420
14489
  values: readValues(file),
13421
14490
  textures: resolved.addresses,
13422
14491
  defines: readDefines(file)
@@ -14500,7 +15569,7 @@ let effectLayer = null;
14500
15569
  * @internal
14501
15570
  */
14502
15571
  async function loadPostEffectSupport() {
14503
- const [compiler, effects] = await Promise.all([compilerLayer ?? import("./post-effect-compiler-C_7HTHZy.js"), effectLayer ?? import("./effect-task-CMbuO6Kb.js")]);
15572
+ const [compiler, effects] = await Promise.all([compilerLayer ?? import("./post-effect-compiler-jSvOVe0U.js"), effectLayer ?? import("./effect-task-CMbuO6Kb.js")]);
14504
15573
  compilerLayer = compiler;
14505
15574
  effectLayer = effects;
14506
15575
  }
@@ -14509,740 +15578,144 @@ async function loadPostEffectSupport() {
14509
15578
  *
14510
15579
  * @returns The module, or `null` before any `.post.wgsl` has been loaded.
14511
15580
  *
14512
- * @internal
14513
- */
14514
- function postEffectCompiler() {
14515
- return compilerLayer;
14516
- }
14517
- /**
14518
- * The Babylon Lite effect adapter, if it has been loaded.
14519
- *
14520
- * @returns The module, or `null` before any `.post.wgsl` has been loaded.
14521
- *
14522
- * @internal
14523
- */
14524
- function effectTaskSupport() {
14525
- return effectLayer;
14526
- }
14527
- //#endregion
14528
- //#region src/render/shader-asset.ts
14529
- /**
14530
- * One `.wgsl` file: its text and the declaration its `// @ignifx` pragmas carry
14531
- * (`docs/plan/2026-09-terrain-particles-shaders.md` §3.1, ADR-0024).
14532
- *
14533
- * The asset is the program plus the schema of what a material may set on it, never the values. It
14534
- * needs no device, so a `.wgsl` loads completely in Node. Two facts an author has to know:
14535
- *
14536
- * - The whole file is handed to Babylon Lite as **both** the vertex and the fragment source
14537
- * (`lib/material/shader/shader-pipeline.js` 66–79), so structs and helpers are shared and the file
14538
- * must compile in both stages — `textureSample` is fragment-only; vertex code uses
14539
- * `textureSampleLevel` or `textureLoad`.
14540
- * - Lite's system uniforms are read as `shaderSystem.<name>`; everything else, including the
14541
- * uniforms ignifx supplies, as `shaderUniforms.<name>`.
14542
- */
14543
- /**
14544
- * The asset type shaders are registered under.
14545
- *
14546
- * @public
14547
- */
14548
- const SHADER_ASSET_TYPE = "shader";
14549
- /**
14550
- * The address extensions that select the shader loader.
14551
- *
14552
- * @remarks
14553
- * `.surface.wgsl` and `.post.wgsl` both end in `.wgsl`, so one extension covers all three forms.
14554
- *
14555
- * @public
14556
- */
14557
- const SHADER_FILE_EXTENSIONS = Object.freeze([".wgsl"]);
14558
- /**
14559
- * A loaded `.wgsl` file: its source and what its pragmas declare
14560
- * (`docs/plan/2026-09-terrain-particles-shaders.md` §3.1).
14561
- *
14562
- * @remarks
14563
- * Shaders are shared: many materials reference one shader asset, and each material holds its own
14564
- * values. Editing the file in development re-parses the declaration and rebuilds every material
14565
- * built from it in place (`docs/architecture/05-assets-and-loading.md` §7).
14566
- *
14567
- * @example
14568
- * ```ts
14569
- * const dissolve = await app.assets.loadAsync<ShaderAsset>("shaders/dissolve.wgsl");
14570
- * dissolve.value.declaration.uniforms.map((uniform) => uniform.name); // ["progress", "edgeColor"]
14571
- * ```
14572
- *
14573
- * @public
14574
- */
14575
- var ShaderAsset = class {
14576
- /** The type name the asset service registers shaders under. */
14577
- static assetType = SHADER_ASSET_TYPE;
14578
- /** The address the shader was loaded from. */
14579
- address;
14580
- /** The whole file, as written. It is handed to Babylon Lite as both the vertex and the fragment source. */
14581
- source;
14582
- /** What the file's `// @ignifx` pragmas declare. */
14583
- declaration;
14584
- /**
14585
- * Wraps a parsed shader file. The `shader` loader constructs these.
14586
- *
14587
- * @param address - The address it was loaded from.
14588
- * @param source - The whole file.
14589
- * @param declaration - The parsed pragmas.
14590
- *
14591
- * @internal
14592
- */
14593
- constructor(address, source, declaration) {
14594
- this.address = address;
14595
- this.source = source;
14596
- this.declaration = declaration;
14597
- }
14598
- /**
14599
- * Which of the three authoring forms the file declared.
14600
- *
14601
- * @returns `"shader"`, `"surface"`, or `"post"`.
14602
- */
14603
- get kind() {
14604
- return this.declaration.kind;
14605
- }
14606
- };
14607
- //#endregion
14608
- //#region src/render/loaders/shader-loader.ts
14609
- /**
14610
- * The `shader` asset loader: `.wgsl` to `ShaderAsset`
14611
- * (`docs/plan/2026-09-terrain-particles-shaders.md` §3.1).
14612
- *
14613
- * One loader covers all three forms, because `.surface.wgsl` and `.post.wgsl` both end in `.wgsl`;
14614
- * the `@ignifx shader|surface|post` pragma is what says which form a file is.
14615
- */
14616
- /**
14617
- * Builds the loader for `.wgsl` addresses.
14618
- *
14619
- * @remarks
14620
- * A parse failure fails the load, unlike a malformed `.material.json` property: a shader whose
14621
- * declaration cannot be read has no usable fallback (`CONSTITUTION.md` §3.9).
14622
- *
14623
- * The loader is also where the custom-shader layers are pulled into memory. A `ShaderAsset` can only
14624
- * come from here, so awaiting them here is what lets `createMaterialAsset` and the `.material.json`
14625
- * loader build a shader material synchronously (`../shader-support.ts`).
14626
- *
14627
- * @returns The loader to register with `ctx.registerAssetLoader`.
14628
- *
14629
- * @example
14630
- * ```ts
14631
- * ctx.registerAssetLoader(createShaderLoader());
14632
- * ```
14633
- *
14634
- * @public
14635
- */
14636
- function createShaderLoader() {
14637
- return {
14638
- type: SHADER_ASSET_TYPE,
14639
- extensions: SHADER_FILE_EXTENSIONS,
14640
- async load(ctx) {
14641
- const [source, pragma] = await Promise.all([ctx.fetchText(), import("./shader-pragma-DmZpxGUo.js")]);
14642
- const declaration = pragma.parseShaderDeclaration(source, ctx.address);
14643
- await loadShaderSupport();
14644
- if (declaration.kind === "surface") await loadSurfaceShaderSupport();
14645
- else if (declaration.kind === "post") await loadPostEffectSupport();
14646
- return new ShaderAsset(ctx.address, source, declaration);
14647
- }
14648
- };
14649
- }
14650
- //#endregion
14651
- //#region src/lite/gpu/texture.ts
14652
- /**
14653
- * Loads a 2D texture from a URL.
14654
- *
14655
- * @param engine - The engine that owns the GPU texture.
14656
- * @param url - Where to fetch it from.
14657
- * @param options - Sampler, mipmap, colour-space, and decode options.
14658
- * @returns The texture. Its reference count starts at an implicit one.
14659
- *
14660
- * @example
14661
- * ```ts
14662
- * const albedo = await loadTexture(engine, "textures/hero-albedo.png", { srgb: true });
14663
- * ```
14664
- *
14665
- * @internal
14666
- */
14667
- function loadTexture(engine, url, options) {
14668
- return loadTexture2D(engine, url, options);
14669
- }
14670
- /**
14671
- * Loads a KTX2 (Basis Universal) texture from a URL, transcoded to the device's best compressed
14672
- * format.
14673
- *
14674
- * @remarks
14675
- * Lite's KTX2 glue is imported on first use (`./decoders.ts`), so a game that never loads a `.ktx2`
14676
- * does not carry it. The decoder script and its transcoders load from wherever
14677
- * `applyLiteDecoderUrls` last pointed Lite, or from `cdn.babylonjs.com` when nothing did. Sampler and
14678
- * sRGB options apply; `mipMaps`, `invertY` and `premultiplyAlpha` do not — the file's rows and mips
14679
- * are uploaded as stored (`./decoders.ts` explains the orientation).
14680
- *
14681
- * @param engine - The engine that owns the GPU texture.
14682
- * @param url - Where to fetch it from.
14683
- * @param options - Colour space and sampler.
14684
- * @returns The texture. Its reference count starts at an implicit one.
14685
- *
14686
- * @example
14687
- * ```ts
14688
- * const albedo = await loadKtx2Texture(engine, "textures/hero-albedo.ktx2", { srgb: true });
14689
- * ```
14690
- *
14691
- * @internal
14692
- */
14693
- async function loadKtx2Texture(engine, url, options = {}) {
14694
- return (await import("./decoders-BUQrlS8U.js")).loadKtx2TextureWithOptions(engine, url, options);
14695
- }
14696
- /**
14697
- * Loads a Basis Universal (`.basis`) texture from a URL.
14698
- *
14699
- * @remarks
14700
- * Babylon Lite 1.34 always fetches the Basis transcoder from `cdn.babylonjs.com` and offers no
14701
- * setter for it, so this works only where the page may load scripts from that origin. Prefer
14702
- * `.ktx2`, which carries the same Basis payloads and whose decoder is served locally.
14703
- *
14704
- * @param engine - The engine that owns the GPU texture.
14705
- * @param url - Where to fetch it from.
14706
- * @param options - Colour space and sampler.
14707
- * @returns The texture.
14708
- *
14709
- * @internal
14710
- */
14711
- async function loadBasisTexture(engine, url, options = {}) {
14712
- return (await import("./decoders-BUQrlS8U.js")).loadBasisTextureWithOptions(engine, url, options);
14713
- }
14714
- /**
14715
- * Creates a 2D texture from tightly packed RGBA8 bytes.
14716
- *
14717
- * @param engine - The engine that owns the GPU texture.
14718
- * @param data - `width * height * 4` bytes, row-major, top row first, straight alpha.
14719
- * @param width - The width in texels, at least 1.
14720
- * @param height - The height in texels, at least 1.
14721
- * @param options - Sampler and colour-space overrides.
14722
- * @returns The texture, created with `COPY_DST` so {@link updateTextureFromPixels} can write to it.
14723
- * Its reference count starts at an implicit one.
14724
- *
14725
- * @internal
14726
- */
14727
- function createTextureFromPixels(engine, data, width, height, options) {
14728
- return createTexture2DFromPixels(engine, data, width, height, {
14729
- addressModeU: options.addressModeU,
14730
- addressModeV: options.addressModeV,
14731
- minFilter: options.minFilter,
14732
- magFilter: options.magFilter,
14733
- srgb: options.srgb
14734
- });
14735
- }
14736
- /**
14737
- * Writes a rectangular region of a pixel texture.
14738
- *
14739
- * @remarks
14740
- * Only legal on a texture from {@link createTextureFromPixels}: any other `Texture2D` was created
14741
- * without `COPY_DST` usage and WebGPU rejects the write.
14742
- *
14743
- * @param engine - The engine that owns the texture.
14744
- * @param texture - The target.
14745
- * @param data - `width * height * 4` bytes for the region, row-major.
14746
- * @param x - The destination origin's column, in texels.
14747
- * @param y - The destination origin's row, in texels.
14748
- * @param width - The region's width, in texels.
14749
- * @param height - The region's height, in texels.
14750
- *
14751
- * @internal
14752
- */
14753
- function updateTextureFromPixels(engine, texture, data, x, y, width, height) {
14754
- updateTexture2DFromPixels(engine, texture, data, x, y, width, height);
14755
- }
14756
- /**
14757
- * Claims a share of a texture, so a later {@link releaseTextureHandle} by someone else does not
14758
- * destroy it.
14759
- *
14760
- * @param texture - The texture to retain.
14761
- *
14762
- * @internal
14763
- */
14764
- function retainTexture(texture) {
14765
- acquireTexture(texture);
14766
- }
14767
- /**
14768
- * Gives up a share of a texture, destroying it when the last share goes.
14769
- *
14770
- * @param texture - The texture to release.
14771
- * @returns `true` when this call destroyed the underlying `GPUTexture`.
14772
- *
14773
- * @internal
14774
- */
14775
- function releaseTextureHandle(texture) {
14776
- return releaseTexture(texture);
14777
- }
14778
- //#endregion
14779
- //#region src/render/gpu/texture-pixels.ts
14780
- /**
14781
- * The device-only half of `TextureAsset` (`docs/architecture/07-rendering.md` §6).
14782
- *
14783
- * Each function takes the engine or the texture as a nullable and returns early when it is `null`,
14784
- * so the asset keeps no headless branch of its own.
14785
- */
14786
- /**
14787
- * Creates a texture from tightly packed RGBA8 bytes, or nothing under a headless app.
14788
- *
14789
- * @param isHeadless - Whether the app has a device.
14790
- * @param engine - The engine that uploads it.
14791
- * @param data - `width * height * 4` bytes, row-major, top row first, straight alpha.
14792
- * @param width - The width in texels.
14793
- * @param height - The height in texels.
14794
- * @param options - The resolved import options; only the sampler subset reaches Lite.
14795
- * @returns The texture, or `null`.
14796
- *
14797
- * @internal
14798
- */
14799
- function createPixelTexture(isHeadless, engine, data, width, height, options) {
14800
- if (isHeadless) return null;
14801
- return createTextureFromPixels(engine, data, width, height, {
14802
- addressModeU: options.addressModeU,
14803
- addressModeV: options.addressModeV,
14804
- minFilter: options.minFilter,
14805
- magFilter: options.magFilter,
14806
- srgb: options.srgb
14807
- });
14808
- }
14809
- /**
14810
- * Writes a rectangular region of a pixel texture, when it still has one.
14811
- *
14812
- * @param engine - The engine that owns the queue.
14813
- * @param texture - The target, or `null` when the app is headless or the share was released.
14814
- * @param data - The region's RGBA8 bytes.
14815
- * @param x - The destination column.
14816
- * @param y - The destination row.
14817
- * @param width - The region width.
14818
- * @param height - The region height.
14819
- *
14820
- * @internal
14821
- */
14822
- function writePixelTexture(engine, texture, data, x, y, width, height) {
14823
- if (texture === null) return;
14824
- updateTextureFromPixels(engine, texture, data, x, y, width, height);
14825
- }
14826
- /**
14827
- * Claims an extra share of a texture, when there is one.
14828
- *
14829
- * @param texture - The texture, or `null`.
14830
- *
14831
- * @internal
14832
- */
14833
- function retainTextureShare(texture) {
14834
- if (texture === null) return;
14835
- retainTexture(texture);
15581
+ * @internal
15582
+ */
15583
+ function postEffectCompiler() {
15584
+ return compilerLayer;
14836
15585
  }
14837
15586
  /**
14838
- * Gives up a share of a texture, when there is one.
15587
+ * The Babylon Lite effect adapter, if it has been loaded.
14839
15588
  *
14840
- * @param texture - The texture, or `null`.
14841
- * @returns `true` when this call destroyed the underlying `GPUTexture`.
15589
+ * @returns The module, or `null` before any `.post.wgsl` has been loaded.
14842
15590
  *
14843
15591
  * @internal
14844
15592
  */
14845
- function releaseTextureShare(texture) {
14846
- return texture === null ? false : releaseTextureHandle(texture);
15593
+ function effectTaskSupport() {
15594
+ return effectLayer;
14847
15595
  }
14848
15596
  //#endregion
14849
- //#region src/render/texture-asset.ts
15597
+ //#region src/render/shader-asset.ts
14850
15598
  /**
14851
- * `TextureAsset` (`docs/architecture/05-assets-and-loading.md` §5, `07-rendering.md` §7): a GPU
14852
- * texture plus the import options the build recorded for it.
14853
- *
14854
- * ## Lifetime, and why the loader does not `acquireTexture`
14855
- *
14856
- * Lite reference-counts `GPUTexture`s in a process-wide pool keyed by the underlying texture
14857
- * (`lib/resource/gpu-pool.js`): `acquireTexture` increments, `releaseTexture` decrements and
14858
- * destroys at zero, and **a texture that was never acquired starts at an implicit count of one**.
14859
- * A freshly loaded texture is therefore already owned once, by the asset that loaded it. Calling
14860
- * `acquireTexture` in the loader — which `07-rendering.md` §7 could be read as asking for — would
14861
- * put the count at two and make the matching `releaseTexture` on unload free nothing: a leak, not a
14862
- * safety net. So the loader acquires nothing and {@link TextureAsset.releaseGpu} releases the one
14863
- * implicit share when the asset is unloaded.
14864
- *
14865
- * Sharing is expressed one level up instead. A `MaterialAsset` that samples a texture pulls it in
14866
- * with `ctx.loadDependency`, which retains the *asset handle*; the texture's GPU share is released
14867
- * only when the last asset holding that handle is collected. That is the same rule every other
14868
- * dependency follows, and it is observable through `handle.refCount`.
14869
- * {@link TextureAsset.retainGpu} exists for the rare case where a Lite object outlives its asset.
15599
+ * One `.wgsl` file: its text and the declaration its `// @ignifx` pragmas carry
15600
+ * (`docs/plan/2026-09-terrain-particles-shaders.md` §3.1, ADR-0024).
14870
15601
  *
14871
- * {@link TextureAsset.fromPixels} is the other way in: RGBA8 bytes, no file, published at a
14872
- * `memory:texture/<ulid>` address the way `MeshAsset`'s primitive factories are. It is the **only**
14873
- * kind of texture {@link TextureAsset.update} accepts, because `createTexture2DFromPixels` is what
14874
- * asks WebGPU for `COPY_DST` usage (`index.d.ts` 13400). The bytes are copied at creation and not
14875
- * retained; the asset keeps only the size, which is what `update` validates against.
15602
+ * The asset is the program plus the schema of what a material may set on it, never the values. It
15603
+ * needs no device, so a `.wgsl` loads completely in Node. Two facts an author has to know:
14876
15604
  *
14877
- * ## Headless
15605
+ * - The whole file is handed to Babylon Lite as **both** the vertex and the fragment source
15606
+ * (`lib/material/shader/shader-pipeline.js` 66–79), so structs and helpers are shared and the file
15607
+ * must compile in both stages — `textureSample` is fragment-only; vertex code uses
15608
+ * `textureSampleLevel` or `textureLoad`.
15609
+ * - Lite's system uniforms are read as `shaderSystem.<name>`; everything else, including the
15610
+ * uniforms ignifx supplies, as `shaderUniforms.<name>`.
15611
+ */
15612
+ /**
15613
+ * The asset type shaders are registered under.
14878
15614
  *
14879
- * `loadTexture2D` uploads through `engine._device`, which the null engine has none of, so a
14880
- * headless load produces an asset with `lite.texture === null` — the `gpu: null` shape
14881
- * `05-assets-and-loading.md` §5 requires of every GPU loader. `fromPixels` behaves the same way and
14882
- * still validates and records the size, so a Node test can assert that a generator wrote the right
14883
- * number of bytes without a device.
15615
+ * @public
14884
15616
  */
15617
+ const SHADER_ASSET_TYPE = "shader";
14885
15618
  /**
14886
- * The asset type textures are registered under.
15619
+ * The address extensions that select the shader loader.
15620
+ *
15621
+ * @remarks
15622
+ * `.surface.wgsl` and `.post.wgsl` both end in `.wgsl`, so one extension covers all three forms.
14887
15623
  *
14888
15624
  * @public
14889
15625
  */
14890
- const TEXTURE_ASSET_TYPE = "texture";
15626
+ const SHADER_FILE_EXTENSIONS = Object.freeze([".wgsl"]);
14891
15627
  /**
14892
- * A loaded 2D texture (`docs/architecture/05-assets-and-loading.md` §5).
15628
+ * A loaded `.wgsl` file: its source and what its pragmas declare
15629
+ * (`docs/plan/2026-09-terrain-particles-shaders.md` §3.1).
15630
+ *
15631
+ * @remarks
15632
+ * Shaders are shared: many materials reference one shader asset, and each material holds its own
15633
+ * values. Editing the file in development re-parses the declaration and rebuilds every material
15634
+ * built from it in place (`docs/architecture/05-assets-and-loading.md` §7).
14893
15635
  *
14894
15636
  * @example
14895
15637
  * ```ts
14896
- * const albedo = await app.assets.loadAsync<TextureAsset>("textures/hero-albedo.png");
14897
- * albedo.value.options.srgb; // what the .meta.json sidecar asked for
15638
+ * const dissolve = await app.assets.loadAsync<ShaderAsset>("shaders/dissolve.wgsl");
15639
+ * dissolve.value.declaration.uniforms.map((uniform) => uniform.name); // ["progress", "edgeColor"]
14898
15640
  * ```
14899
15641
  *
14900
15642
  * @public
14901
15643
  */
14902
- var TextureAsset = class TextureAsset {
14903
- /** The type name the asset service registers textures under. */
14904
- static assetType = TEXTURE_ASSET_TYPE;
14905
- /** The address the texture was loaded from. */
15644
+ var ShaderAsset = class {
15645
+ /** The type name the asset service registers shaders under. */
15646
+ static assetType = SHADER_ASSET_TYPE;
15647
+ /** The address the shader was loaded from. */
14906
15648
  address;
14907
- /** The resolved import options, sidecar values merged onto the defaults. */
14908
- options;
14909
- #texture;
14910
- #pixelSource;
15649
+ /** The whole file, as written. It is handed to Babylon Lite as both the vertex and the fragment source. */
15650
+ source;
15651
+ /** What the file's `// @ignifx` pragmas declare. */
15652
+ declaration;
14911
15653
  /**
14912
- * Wraps a loaded texture. The `texture` loader and {@link TextureAsset.fromPixels} construct
14913
- * these.
15654
+ * Wraps a parsed shader file. The `shader` loader constructs these.
14914
15655
  *
14915
- * @param address - The address it was loaded from, or the `memory:` address it was published at.
14916
- * @param texture - The GPU texture, or `null` when the app is headless.
14917
- * @param options - The resolved import options.
14918
- * @param pixelSource - The engine and size of a texture built from raw pixels, or `null` for a
14919
- * texture that came from a file. It is what makes {@link TextureAsset.update} legal.
15656
+ * @param address - The address it was loaded from.
15657
+ * @param source - The whole file.
15658
+ * @param declaration - The parsed pragmas.
14920
15659
  *
14921
15660
  * @internal
14922
15661
  */
14923
- constructor(address, texture, options, pixelSource = null) {
15662
+ constructor(address, source, declaration) {
14924
15663
  this.address = address;
14925
- this.#texture = texture;
14926
- this.options = options;
14927
- this.#pixelSource = pixelSource;
14928
- }
14929
- /**
14930
- * The Babylon Lite objects the asset owns. Unstable escape hatch.
14931
- *
14932
- * @returns The GPU texture, or `null` under a headless app.
14933
- */
14934
- get lite() {
14935
- return { texture: this.#texture };
14936
- }
14937
- /**
14938
- * The texture's width, in texels.
14939
- *
14940
- * @remarks
14941
- * Known for every texture that reached the GPU — Lite records it on the texture handle
14942
- * (`index.d.ts` 12876) — and for a headless {@link TextureAsset.fromPixels} texture, which
14943
- * remembers the size it was asked for. A texture **loaded** from a file under a headless app
14944
- * decoded nothing, so it reports `0`.
14945
- *
14946
- * @returns The width, or `0` when nothing knows it.
14947
- */
14948
- get width() {
14949
- return this.#texture?.width ?? this.#pixelSource?.width ?? 0;
14950
- }
14951
- /**
14952
- * The texture's height, in texels.
14953
- *
14954
- * @returns The height, or `0`; see {@link TextureAsset.width}.
14955
- */
14956
- get height() {
14957
- return this.#texture?.height ?? this.#pixelSource?.height ?? 0;
14958
- }
14959
- /**
14960
- * Whether the GPU texture has been given up.
14961
- *
14962
- * @returns `true` once {@link TextureAsset.releaseGpu} has run.
14963
- */
14964
- get isReleased() {
14965
- return this.#texture === null;
14966
- }
14967
- /**
14968
- * Claims an extra share of the GPU texture, so releasing the asset does not destroy it.
14969
- *
14970
- * @remarks
14971
- * Only needed when a Lite object has to outlive the asset that loaded it. Ordinary sharing goes
14972
- * through `ctx.loadDependency`, which counts the asset handle instead.
14973
- */
14974
- retainGpu() {
14975
- retainTextureShare(this.#texture);
14976
- }
14977
- /**
14978
- * Gives up the asset's share of the GPU texture, destroying it when it was the last one. Calling
14979
- * it twice is a no-op, and it is a no-op under a headless app.
14980
- *
14981
- * @returns `true` when this call destroyed the underlying `GPUTexture`.
14982
- */
14983
- releaseGpu() {
14984
- const texture = this.#texture;
14985
- this.#texture = null;
14986
- return releaseTextureShare(texture);
14987
- }
14988
- /**
14989
- * Writes a rectangular region of the texture from RGBA8 bytes.
14990
- *
14991
- * @remarks
14992
- * Only a texture from {@link TextureAsset.fromPixels} can be written to: that is the factory that
14993
- * asks WebGPU for `COPY_DST` usage. The region defaults to the whole texture. Nothing is uploaded
14994
- * under a headless app, but the size check still runs, so a generator's arithmetic is testable
14995
- * without a device.
14996
- *
14997
- * The texture has one mip level, so there is no chain to regenerate and an update is complete the
14998
- * moment the queue drains.
14999
- *
15000
- * @param data - `width * height * 4` bytes for the region, row-major, top row first.
15001
- * @param x - The destination origin's column. Defaults to `0`.
15002
- * @param y - The destination origin's row. Defaults to `0`.
15003
- * @param width - The region's width. Defaults to the texture's width.
15004
- * @param height - The region's height. Defaults to the texture's height.
15005
- * @throws IgnifxError with code `IGX-0702` when the texture did not come from
15006
- * {@link TextureAsset.fromPixels}.
15007
- * @throws IgnifxError with code `IGX-0722` when the region falls outside the texture or `data` is
15008
- * not exactly `width * height * 4` bytes long.
15009
- *
15010
- * @example
15011
- * ```ts
15012
- * const splat = TextureAsset.fromPixels(app, "splat", pixels, 256, 256);
15013
- * pixels[0] = 255;
15014
- * splat.value.update(pixels.subarray(0, 4), 0, 0, 1, 1); // one texel
15015
- * ```
15016
- */
15017
- update(data, x = 0, y = 0, width, height) {
15018
- const source = this.#pixelSource;
15019
- if (source === null) throw new IgnifxError(CoreErrorCode.invalidRuntime, `${this.address} was not created by TextureAsset.fromPixels, so it cannot be updated.`, {
15020
- context: {
15021
- asset: this.address,
15022
- member: "TextureAsset.update()"
15023
- },
15024
- hint: "Only a texture built with TextureAsset.fromPixels carries the COPY_DST usage an update needs."
15025
- });
15026
- const regionWidth = width ?? source.width;
15027
- const regionHeight = height ?? source.height;
15028
- assertPixelRegion(this.address, data, source, x, y, regionWidth, regionHeight);
15029
- writePixelTexture(source.engine, this.#texture, data, x, y, regionWidth, regionHeight);
15664
+ this.source = source;
15665
+ this.declaration = declaration;
15030
15666
  }
15031
15667
  /**
15032
- * Creates a texture from tightly packed RGBA8 bytes and publishes it as an in-memory asset.
15033
- *
15034
- * @remarks
15035
- * The bytes are `width * height * 4` long, row-major, **top row first**, with straight (not
15036
- * premultiplied) alpha. They are copied into the GPU texture and not retained.
15037
- *
15038
- * The result is the only kind of texture {@link TextureAsset.update} accepts. Ownership follows
15039
- * the rule every in-code asset follows: the caller holds the handle, releasing it (or letting a
15040
- * `using` block do it) runs the `texture` type's unload, which releases the GPU share.
15041
- *
15042
- * @param app - The app whose engine uploads the texture and whose asset service holds the handle.
15043
- * @param name - A human-readable name. It becomes the asset's `address` — the string diagnostics
15044
- * and the `IGX-0722` message name it by — while the handle's own address is the generated
15045
- * `memory:texture/<ulid>` the asset service published it at.
15046
- * @param data - `width * height * 4` bytes.
15047
- * @param width - The width in texels, at least 1.
15048
- * @param height - The height in texels, at least 1.
15049
- * @param options - Sampler and colour-space overrides; `nearest`, `clamp`, no sRGB by default.
15050
- * @returns The handle, already loaded, with one holder — the caller.
15051
- * @throws IgnifxError with code `IGX-0722` when `width` or `height` is not a positive integer, or
15052
- * `data` is not exactly `width * height * 4` bytes long.
15668
+ * Which of the three authoring forms the file declared.
15053
15669
  *
15054
- * @example
15055
- * ```ts
15056
- * const pixels = new Uint8Array(2 * 2 * 4);
15057
- * pixels.fill(255);
15058
- * using ramp = TextureAsset.fromPixels(app, "ramp", pixels, 2, 2, { filter: "nearest" });
15059
- * ```
15670
+ * @returns `"shader"`, `"surface"`, or `"post"`.
15060
15671
  */
15061
- static fromPixels(app, name, data, width, height, options) {
15062
- assertPixelSize(name, data, width, height);
15063
- const resolved = resolvePixelOptions(options);
15064
- const engine = app.lite.engine;
15065
- const texture = createPixelTexture(app.isHeadless, engine, data, width, height, resolved);
15066
- const asset = new TextureAsset(name, texture, resolved, {
15067
- engine,
15068
- width,
15069
- height
15070
- });
15071
- return app.assets.register(asset, { type: TEXTURE_ASSET_TYPE });
15672
+ get kind() {
15673
+ return this.declaration.kind;
15072
15674
  }
15073
15675
  };
15676
+ //#endregion
15677
+ //#region src/render/loaders/shader-loader.ts
15074
15678
  /**
15075
- * How many bytes one RGBA8 texel occupies.
15076
- */
15077
- const BYTES_PER_TEXEL = 4;
15078
- /**
15079
- * Checks that a byte count matches a texture size.
15080
- *
15081
- * @param asset - The name or address named in the error.
15082
- * @param data - The pixel bytes.
15083
- * @param width - The width in texels.
15084
- * @param height - The height in texels.
15085
- * @throws IgnifxError with code `IGX-0722` when the size is not a positive integer pair or the byte
15086
- * count does not match.
15087
- */
15088
- function assertPixelSize(asset, data, width, height) {
15089
- const valid = Number.isInteger(width) && Number.isInteger(height) && width > 0 && height > 0;
15090
- const expected = width * height * BYTES_PER_TEXEL;
15091
- if (valid && data.length === expected) return;
15092
- throw new IgnifxError(CoreErrorCode.invalidPixelData, `${asset}: ${String(data.length)} bytes of pixel data do not match ${String(width)}x${String(height)} RGBA.`, {
15093
- context: {
15094
- asset,
15095
- bytes: data.length,
15096
- width,
15097
- height
15098
- },
15099
- hint: "RGBA8 pixel data is exactly width * height * 4 bytes, row-major with the top row first."
15100
- });
15101
- }
15102
- /**
15103
- * Checks that an update's region lies inside the texture and that the byte count matches it.
15104
- *
15105
- * @param asset - The address named in the error.
15106
- * @param data - The pixel bytes.
15107
- * @param source - The texture's recorded size.
15108
- * @param x - The region's origin column.
15109
- * @param y - The region's origin row.
15110
- * @param width - The region's width.
15111
- * @param height - The region's height.
15112
- * @throws IgnifxError with code `IGX-0722` when the region does not fit or the byte count is wrong.
15113
- */
15114
- function assertPixelRegion(asset, data, source, x, y, width, height) {
15115
- if (!(Number.isInteger(x) && Number.isInteger(y) && x >= 0 && y >= 0 && x + width <= source.width && y + height <= source.height)) throw new IgnifxError(CoreErrorCode.invalidPixelData, `${asset}: the region ${String(width)}x${String(height)} at (${String(x)}, ${String(y)}) falls outside a ${String(source.width)}x${String(source.height)} texture.`, {
15116
- context: {
15117
- asset,
15118
- bytes: data.length,
15119
- x,
15120
- y,
15121
- width,
15122
- height
15123
- },
15124
- hint: "An update writes inside the texture it was created with; recreate it to change its size."
15125
- });
15126
- assertPixelSize(asset, data, width, height);
15127
- }
15128
- /**
15129
- * Fills in {@link PixelTextureOptions}'s defaults as a complete {@link TextureImportOptions}, so a
15130
- * pixel texture reports its sampler state the way a loaded one does.
15131
- *
15132
- * @param options - What the caller named.
15133
- * @returns The resolved options.
15134
- */
15135
- function resolvePixelOptions(options) {
15136
- const filter = options?.filter ?? "nearest";
15137
- const wrap = options?.wrap === "repeat" ? "repeat" : "clamp-to-edge";
15138
- return {
15139
- srgb: options?.srgb ?? false,
15140
- mipMaps: false,
15141
- addressModeU: wrap,
15142
- addressModeV: wrap,
15143
- minFilter: filter,
15144
- magFilter: filter,
15145
- invertY: false,
15146
- premultiplyAlpha: false
15147
- };
15148
- }
15149
- /**
15150
- * The import options a texture gets when its sidecar names none: Lite's own defaults, with `srgb`
15151
- * off so that a data map is never silently decoded.
15152
- *
15153
- * @returns A fresh option set.
15679
+ * The `shader` asset loader: `.wgsl` to `ShaderAsset`
15680
+ * (`docs/plan/2026-09-terrain-particles-shaders.md` §3.1).
15154
15681
  *
15155
- * @internal
15682
+ * One loader covers all three forms, because `.surface.wgsl` and `.post.wgsl` both end in `.wgsl`;
15683
+ * the `@ignifx shader|surface|post` pragma is what says which form a file is.
15156
15684
  */
15157
- function defaultTextureImportOptions() {
15158
- return {
15159
- srgb: false,
15160
- mipMaps: true,
15161
- addressModeU: "repeat",
15162
- addressModeV: "repeat",
15163
- minFilter: "linear",
15164
- magFilter: "linear",
15165
- invertY: true,
15166
- premultiplyAlpha: false
15167
- };
15168
- }
15169
15685
  /**
15170
- * Reads the `texture` block of a `.meta.json` sidecar over the defaults.
15686
+ * Builds the loader for `.wgsl` addresses.
15171
15687
  *
15172
15688
  * @remarks
15173
- * Unknown keys and values of the wrong type are ignored rather than rejected: a sidecar is written
15174
- * by hand and shared with other tools, and a typo in an optional import hint must not stop a game
15175
- * from starting (`CONSTITUTION.md` §3.9 — the asset still loads, with the documented default).
15176
- *
15177
- * @param meta - The whole sidecar, or `null` when the manifest recorded none.
15178
- * @returns The resolved options.
15689
+ * A parse failure fails the load, unlike a malformed `.material.json` property: a shader whose
15690
+ * declaration cannot be read has no usable fallback (`CONSTITUTION.md` §3.9).
15179
15691
  *
15180
- * @internal
15181
- */
15182
- function readTextureImportOptions(meta) {
15183
- const defaults = defaultTextureImportOptions();
15184
- const raw = meta === null ? void 0 : meta[TEXTURE_ASSET_TYPE];
15185
- if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return defaults;
15186
- const block = raw;
15187
- return {
15188
- srgb: readBoolean(block, "srgb", defaults.srgb),
15189
- mipMaps: readBoolean(block, "mipMaps", defaults.mipMaps),
15190
- addressModeU: readString$1(block, "addressModeU", defaults.addressModeU),
15191
- addressModeV: readString$1(block, "addressModeV", defaults.addressModeV),
15192
- minFilter: readString$1(block, "minFilter", defaults.minFilter),
15193
- magFilter: readString$1(block, "magFilter", defaults.magFilter),
15194
- invertY: readBoolean(block, "invertY", defaults.invertY),
15195
- premultiplyAlpha: readBoolean(block, "premultiplyAlpha", defaults.premultiplyAlpha)
15196
- };
15197
- }
15198
- /**
15199
- * Turns the resolved options into the shape `loadTexture2D` takes.
15692
+ * The loader is also where the custom-shader layers are pulled into memory. A `ShaderAsset` can only
15693
+ * come from here, so awaiting them here is what lets `createMaterialAsset` and the `.material.json`
15694
+ * loader build a shader material synchronously (`../shader-support.ts`).
15200
15695
  *
15201
- * @remarks
15202
- * The sampler strings are handed to Lite as declared; WebGPU rejects a mode or filter it does not
15203
- * know, and that failure is a clearer signal than an ignored option would be.
15696
+ * @returns The loader to register with `ctx.registerAssetLoader`.
15204
15697
  *
15205
- * @param options - The resolved import options.
15206
- * @returns Lite's options.
15698
+ * @example
15699
+ * ```ts
15700
+ * ctx.registerAssetLoader(createShaderLoader());
15701
+ * ```
15207
15702
  *
15208
- * @internal
15703
+ * @public
15209
15704
  */
15210
- function toLiteTextureOptions(options) {
15705
+ function createShaderLoader() {
15211
15706
  return {
15212
- srgb: options.srgb,
15213
- mipMaps: options.mipMaps,
15214
- addressModeU: options.addressModeU,
15215
- addressModeV: options.addressModeV,
15216
- minFilter: options.minFilter,
15217
- magFilter: options.magFilter,
15218
- invertY: options.invertY,
15219
- premultiplyAlpha: options.premultiplyAlpha
15707
+ type: SHADER_ASSET_TYPE,
15708
+ extensions: SHADER_FILE_EXTENSIONS,
15709
+ async load(ctx) {
15710
+ const [source, pragma] = await Promise.all([ctx.fetchText(), import("./shader-pragma-ljmAbVc2.js")]);
15711
+ const declaration = pragma.parseShaderDeclaration(source, ctx.address);
15712
+ await loadShaderSupport();
15713
+ if (declaration.kind === "surface") await loadSurfaceShaderSupport();
15714
+ else if (declaration.kind === "post") await loadPostEffectSupport();
15715
+ return new ShaderAsset(ctx.address, source, declaration);
15716
+ }
15220
15717
  };
15221
15718
  }
15222
- /**
15223
- * Reads a boolean out of a sidecar block.
15224
- *
15225
- * @param block - The sidecar sub-object.
15226
- * @param key - The property name.
15227
- * @param fallback - What to use when the property is absent or not a boolean.
15228
- * @returns The value.
15229
- */
15230
- function readBoolean(block, key, fallback) {
15231
- const value = block[key];
15232
- return typeof value === "boolean" ? value : fallback;
15233
- }
15234
- /**
15235
- * Reads a string out of a sidecar block.
15236
- *
15237
- * @param block - The sidecar sub-object.
15238
- * @param key - The property name.
15239
- * @param fallback - What to use when the property is absent or not a string.
15240
- * @returns The value.
15241
- */
15242
- function readString$1(block, key, fallback) {
15243
- const value = block[key];
15244
- return typeof value === "string" ? value : fallback;
15245
- }
15246
15719
  //#endregion
15247
15720
  //#region src/render/loaders/texture-loader.ts
15248
15721
  /**
@@ -15617,6 +16090,13 @@ function asMesh(node) {
15617
16090
  * fields, reports `lite.mesh === null`, and touches no scene (`07-rendering.md` §6).
15618
16091
  */
15619
16092
  /**
16093
+ * How a lightmap combines with a material's shading: `"add"` adds the baked light to it,
16094
+ * `"shadowmap"` multiplies it (Babylon Lite's `useAsShadowmap`).
16095
+ *
16096
+ * @beta
16097
+ */
16098
+ const LIGHTMAP_MODES = ["add", "shadowmap"];
16099
+ /**
15620
16100
  * Draws a mesh asset with a material (`docs/architecture/07-rendering.md` §2.3).
15621
16101
  *
15622
16102
  * @example
@@ -15707,7 +16187,9 @@ var MeshRenderer = class MeshRenderer extends Component {
15707
16187
  }
15708
16188
  /** Removes the clone from the scene, releasing its share of the template's buffers. */
15709
16189
  onDetach() {
15710
- this.#releaseClone(rendererInternals(this.app.renderer));
16190
+ const renderer = rendererInternals(this.app.renderer);
16191
+ renderer.releaseLightmap(this);
16192
+ this.#releaseClone(renderer);
15711
16193
  }
15712
16194
  /**
15713
16195
  * Rebuilds the clone when `mesh` changed, then writes every other field that changed. The
@@ -15723,7 +16205,7 @@ var MeshRenderer = class MeshRenderer extends Component {
15723
16205
  const changed = this.#ensureClone(renderer);
15724
16206
  const instance = this.#instance;
15725
16207
  if (instance === null) return changed;
15726
- instance.applyMaterial(this.#material(renderer));
16208
+ instance.applyMaterial(renderer.lightmapMaterial(this, this.#materialAsset(renderer)));
15727
16209
  instance.applyDisplacement(this.#displacement(), this.entity.transform);
15728
16210
  instance.applyFlags(this.receiveShadows, this.renderOrder, this.pickable && !this.#displayHidden);
15729
16211
  instance.applyVisible(this.isEnabledInHierarchy && !this.#displayHidden);
@@ -15796,8 +16278,17 @@ var MeshRenderer = class MeshRenderer extends Component {
15796
16278
  * @returns The Lite material.
15797
16279
  */
15798
16280
  #material(renderer) {
16281
+ return this.#materialAsset(renderer).lite.material;
16282
+ }
16283
+ /**
16284
+ * The material asset this renderer draws with: the first it declares, or the app's default.
16285
+ *
16286
+ * @param renderer - The rendering service, for the default material.
16287
+ * @returns The material asset.
16288
+ */
16289
+ #materialAsset(renderer) {
15799
16290
  const declared = this.materials[0];
15800
- return declared?.state === "loaded" ? declared.value.lite.material : renderer.defaultMaterial().lite.material;
16291
+ return declared?.state === "loaded" ? declared.value : renderer.defaultMaterial();
15801
16292
  }
15802
16293
  /**
15803
16294
  * How far the material's vertex stage may move a vertex: its shaders' `// @ignifx displace`.
@@ -15834,7 +16325,17 @@ function meshRendererSchema() {
15834
16325
  castShadows: bool(true, { tooltip: "Whether this mesh is rendered into shadow maps." }),
15835
16326
  receiveShadows: bool(true, { tooltip: "Whether shadow maps darken this mesh." }),
15836
16327
  renderOrder: i32(0, { tooltip: "Sort key within the opaque or transparent phase; lower draws first." }),
15837
- pickable: bool(true, { tooltip: "Whether picking considers this mesh at all." })
16328
+ pickable: bool(true, { tooltip: "Whether picking considers this mesh at all." }),
16329
+ lightmap: optional(record({
16330
+ asset: asset(LightmapAsset, { tooltip: "The baked .lightmap.json to sample." }),
16331
+ mode: enumOf(LIGHTMAP_MODES, "add", { tooltip: "add adds the baked light to the shading; shadowmap multiplies the shading by it." }),
16332
+ level: f32(1, {
16333
+ min: 0,
16334
+ tooltip: "A multiplier on the lightmap sample."
16335
+ }),
16336
+ gamma: bool(false, { tooltip: "Decode the sample from sRGB to linear; off for a texture already decoded." }),
16337
+ uv2: bool(true, { tooltip: "Sample with the mesh's second UV set; off uses the first." })
16338
+ }), { tooltip: "A baked lightmap; drawn only on a static entity with a PBR material." })
15838
16339
  });
15839
16340
  }
15840
16341
  //#endregion
@@ -22341,6 +22842,7 @@ function registerRendering(ctx) {
22341
22842
  ctx.registerAssetLoader(createFontLoader());
22342
22843
  ctx.registerAssetLoader(createShaderLoader());
22343
22844
  ctx.registerAssetLoader(createLightProbeLoader());
22845
+ ctx.registerAssetLoader(createLightmapLoader());
22344
22846
  ctx.registerAssetLoader({
22345
22847
  type: STORAGE_BUFFER_ASSET_TYPE,
22346
22848
  extensions: [],
@@ -29732,95 +30234,6 @@ var SceneInstance = class {
29732
30234
  if (index >= 0) this.#roots.splice(index, 1);
29733
30235
  }
29734
30236
  };
29735
- /**
29736
- * Builds the instance path tables of an expansion.
29737
- *
29738
- * @param expanded - The expansion.
29739
- * @returns The resolver.
29740
- *
29741
- * @internal
29742
- */
29743
- function instancePathResolver(expanded) {
29744
- const keysOfRoot = /* @__PURE__ */ new Map();
29745
- const entities = /* @__PURE__ */ new Map();
29746
- const components = /* @__PURE__ */ new Map();
29747
- for (const instance of expanded.instances) {
29748
- if (instance.rootUid === null) continue;
29749
- const keys = keysOfRoot.get(instance.rootUid) ?? [];
29750
- keys.push(instance.key);
29751
- keysOfRoot.set(instance.rootUid, keys);
29752
- if (instance.root !== null) {
29753
- tableOf(entities, instance.key).set(instance.root.sourceUid, instance.rootUid);
29754
- fillComponents(tableOf(components, instance.key), instance.root.componentSourceUids);
29755
- }
29756
- }
29757
- for (const entity of expanded.entities) {
29758
- if (entity.instanceKey === null) continue;
29759
- tableOf(entities, entity.instanceKey).set(entity.sourceUid, entity.data.uid);
29760
- fillComponents(tableOf(components, entity.instanceKey), entity.componentSourceUids);
29761
- }
29762
- const lookup = (tables, root, uid) => {
29763
- for (const key of keysOfRoot.get(root) ?? []) {
29764
- const found = tables.get(key)?.get(uid);
29765
- if (found !== void 0) return found;
29766
- }
29767
- return null;
29768
- };
29769
- const resolve = (path, last) => {
29770
- const segments = path.split("/");
29771
- if (segments.length < 2) return null;
29772
- let root = segments[0] ?? null;
29773
- for (let index = 1; index < segments.length && root !== null; index += 1) {
29774
- const segment = segments[index] ?? "";
29775
- root = lookup(index === segments.length - 1 ? last : entities, root, segment);
29776
- }
29777
- return root;
29778
- };
29779
- return {
29780
- entity: (path) => resolve(path, entities),
29781
- component: (path) => resolve(path, components)
29782
- };
29783
- }
29784
- /**
29785
- * Rewrites the first segment of an instance path, which names an entity of the file the path is
29786
- * written in, through that file's uid table.
29787
- *
29788
- * @param path - The path, or a plain uid.
29789
- * @param keys - Source uid to expanded uid for the file.
29790
- * @returns The rewritten path, or `null` when `path` is not a path.
29791
- *
29792
- * @internal
29793
- */
29794
- function remapInstancePath(path, keys) {
29795
- const at = path.indexOf("/");
29796
- if (at <= 0) return null;
29797
- const head = path.slice(0, at);
29798
- return `${keys.get(head) ?? head}${path.slice(at)}`;
29799
- }
29800
- /**
29801
- * The table of one instance key, created on first use.
29802
- *
29803
- * @param tables - The tables by instance key.
29804
- * @param key - The instance key.
29805
- * @returns The table.
29806
- */
29807
- function tableOf(tables, key) {
29808
- let table = tables.get(key);
29809
- if (table === void 0) {
29810
- table = /* @__PURE__ */ new Map();
29811
- tables.set(key, table);
29812
- }
29813
- return table;
29814
- }
29815
- /**
29816
- * Adds an expanded-to-source component table, inverted, to an instance's component table.
29817
- *
29818
- * @param into - Source component uid to expanded uid.
29819
- * @param sourceUids - Expanded component uid to source component uid.
29820
- */
29821
- function fillComponents(into, sourceUids) {
29822
- for (const [expanded, source] of sourceUids) into.set(source, expanded);
29823
- }
29824
30237
  //#endregion
29825
30238
  //#region src/serialization/expand.ts
29826
30239
  /**
@@ -30021,7 +30434,34 @@ function expandInstance(asset, instance, carrier, chain, state) {
30021
30434
  const overrides = instance.overrides;
30022
30435
  if (overrides !== void 0 && overrides.length > 0) applyOverrides(overrides, produced, (message) => {
30023
30436
  state.options.report(CoreErrorCode.instanceHashMismatch, `${asset.address}: ${message}`);
30024
- });
30437
+ }, nestedResolver(produced, state));
30438
+ }
30439
+ /**
30440
+ * Resolves the override component segments that are instance paths into the prefabs an instanced
30441
+ * file itself instances. Their copies are already expanded, with fresh uids, when the outer
30442
+ * overrides run, so the path is read through the expansion's instance path tables: the first
30443
+ * segment is a uid of the instanced file, which `produced` maps to its copy.
30444
+ *
30445
+ * @param produced - The instanced file's override targets, by the uid the file gives each entity.
30446
+ * @param state - The expansion so far.
30447
+ * @returns The resolver; it builds its tables on first use, so overrides without such a path cost
30448
+ * nothing.
30449
+ */
30450
+ function nestedResolver(produced, state) {
30451
+ let paths = null;
30452
+ return (path) => {
30453
+ const at = path.indexOf("/");
30454
+ const head = produced.get(path.slice(0, at));
30455
+ if (head === void 0) return null;
30456
+ paths ??= instancePathResolver(state);
30457
+ const uid = paths.component(`${head.data.uid}${path.slice(at)}`);
30458
+ if (uid === null) return null;
30459
+ for (const entity of state.entities) if (entity.data.components.some((component) => component.uid === uid)) return {
30460
+ data: entity.data,
30461
+ uid
30462
+ };
30463
+ return null;
30464
+ };
30025
30465
  }
30026
30466
  /**
30027
30467
  * Reports, or throws, an `IGX-0604` hash mismatch.
@@ -33091,11 +33531,12 @@ var Vec4 = class Vec4 {
33091
33531
  * - **Per probe.** `rays` directions on a Fibonacci sphere. A hit returns the surface's albedo (the
33092
33532
  * material's base or diffuse colour, decoded to linear) times the direct light there, with a
33093
33533
  * shadow ray per directional, point or spot light and the hemispheric lights unshadowed. A miss
33094
- * returns `sky` plus the hemispheric lights. Directional, point and spot lights the probe sees are
33095
- * added exactly, as clamped-cosine lobes. Spot cones are ignored.
33534
+ * returns `sky` plus the hemispheric lights. With `directLight: "include"`, the directional, point
33535
+ * and spot lights the probe sees are added exactly, as clamped-cosine lobes; by default they are
33536
+ * left out, because those lights still light the scene in real time. Spot cones are ignored.
33096
33537
  * - **Units.** Lite's: a white surface lit by the result shows `c0 + c1·n.y + c2·n.z + c3·n.x`, so a
33097
- * uniform sky of radiance `L` bakes to `c0 = L`, and a directional light of intensity `I` to
33098
- * `c0 = I/4` and a first-order term of `I/2` along its direction.
33538
+ * uniform sky of radiance `L` bakes to `c0 = L`, and an included directional light of intensity
33539
+ * `I` to `c0 = I/4` and a first-order term of `I/2` along its direction.
33099
33540
  */
33100
33541
  /** The basis factors: `Y00² · 4π` is 1 and `(2/3) · Y1m² · 4π` is 2, per sample. */
33101
33542
  const BAND1_PER_SAMPLE = 2;
@@ -33105,24 +33546,28 @@ const SURFACE_OFFSET = .001;
33105
33546
  const GOLDEN_ANGLE = 2.399963229728653;
33106
33547
  /** The most rays one probe may trace. */
33107
33548
  const MAX_RAYS = 4096;
33549
+ /** How long the bake works before it yields to the host, in milliseconds (half a 60 Hz frame). */
33550
+ const YIELD_BUDGET_MS = 8;
33108
33551
  /**
33109
33552
  * Bakes a light-probe grid from a world's mesh renderers and lights, on the CPU.
33110
33553
  *
33111
33554
  * @remarks
33112
33555
  * One bounce, first-order harmonics, deterministic. Only meshes built with `MeshAsset.fromData`
33113
- * cast and bounce light (see {@link LightProbeBakeResult.skipped}). Cost grows with probes × rays ×
33556
+ * cast and bounce light (see {@link LightProbeBakeResult.skipped}). By default a probe holds the
33557
+ * bounce but not the direct light of directional, point and spot lights, which keep lighting the
33558
+ * scene in real time (see {@link LightProbeBakeOptions.directLight}). Cost grows with probes × rays ×
33114
33559
  * triangles; it is meant for small scenes and tools, not for every frame.
33115
33560
  *
33116
- * The bake is asynchronous: it yields to the host after each probe, reports progress through
33117
- * `onProgress`, and stops at the next probe once `signal` aborts.
33561
+ * The bake is asynchronous: it yields to the host after every ~8 ms of work, reports progress
33562
+ * through `onProgress` after each probe, and stops at the next probe once `signal` aborts.
33118
33563
  *
33119
33564
  * @param world - The world to bake. Its meshes and lights are read once, when the bake starts.
33120
33565
  * @param options - The grid, the quality, and the cancellation and progress hooks.
33121
33566
  * @returns The grid and what was traced.
33122
33567
  * @throws IgnifxError with code `IGX-0734`, before tracing anything, for a grid the `.probes.json`
33123
33568
  * format cannot hold (whole counts, `counts.x` ≤ 1024, `counts.y × counts.z` ≤ 4096, finite
33124
- * `origin` and positive `cellSize`), `rays` outside 1–4096, or a `maxDistance` that is not finite
33125
- * and positive. The promise rejects with `signal.reason` when the bake is aborted.
33569
+ * `origin` and positive `cellSize`), `rays` outside 1–4096, a `maxDistance` that is not finite
33570
+ * and positive, or a `directLight` other than `"include"` or `"exclude"`. The promise rejects with `signal.reason` when the bake is aborted.
33126
33571
  *
33127
33572
  * @example
33128
33573
  * ```ts
@@ -33144,14 +33589,20 @@ async function bakeLightProbes(world, options) {
33144
33589
  const { origin, cellSize, counts } = settings.grid;
33145
33590
  const total = counts.x * counts.y * counts.z;
33146
33591
  const coefficients = [];
33592
+ const clock = createPerformanceClock();
33593
+ let sliceStart = clock.nowMs();
33147
33594
  for (let probe = 0; probe < total; probe += 1) {
33148
33595
  const i = probe % counts.x;
33149
33596
  const j = Math.floor(probe / counts.x) % counts.y;
33150
33597
  const k = Math.floor(probe / (counts.x * counts.y));
33151
33598
  coefficients.push(...bakeProbe(scene, lights, origin.x + i * cellSize.x, origin.y + j * cellSize.y, origin.z + k * cellSize.z, settings));
33152
33599
  options.onProgress?.(probe + 1, total);
33153
- await yieldToHost();
33154
33600
  options.signal?.throwIfAborted();
33601
+ if (clock.nowMs() - sliceStart >= YIELD_BUDGET_MS && probe + 1 < total) {
33602
+ await yieldToHost();
33603
+ options.signal?.throwIfAborted();
33604
+ sliceStart = clock.nowMs();
33605
+ }
33155
33606
  }
33156
33607
  return {
33157
33608
  data: {
@@ -33182,6 +33633,8 @@ function readBakeOptions(options) {
33182
33633
  if (!Number.isSafeInteger(rays) || rays < 1 || rays > MAX_RAYS) throw fail(`rays must be a whole number from 1 to ${String(MAX_RAYS)}`);
33183
33634
  const maxDistance = options.maxDistance ?? 100;
33184
33635
  if (!Number.isFinite(maxDistance) || maxDistance <= 0) throw fail("maxDistance must be a finite number above 0");
33636
+ const directLight = options.directLight ?? "exclude";
33637
+ if (directLight !== "include" && directLight !== "exclude") throw fail("directLight must be \"include\" or \"exclude\"");
33185
33638
  return {
33186
33639
  grid,
33187
33640
  rays,
@@ -33191,7 +33644,8 @@ function readBakeOptions(options) {
33191
33644
  g: 0,
33192
33645
  b: 0,
33193
33646
  a: 1
33194
- }, false)
33647
+ }, false),
33648
+ includeDirect: directLight === "include"
33195
33649
  };
33196
33650
  }
33197
33651
  /**
@@ -33204,7 +33658,7 @@ function fail(problem) {
33204
33658
  return new IgnifxError(CoreErrorCode.invalidLightProbeBake, `bakeLightProbes(): ${problem}.`, { context: { problem } });
33205
33659
  }
33206
33660
  /**
33207
- * Lets the host run before the next probe.
33661
+ * Lets the host run before the next slice of probes.
33208
33662
  *
33209
33663
  * @returns A promise that settles on a later task.
33210
33664
  */
@@ -33251,7 +33705,7 @@ function bakeProbe(scene, lights, px, py, pz, settings) {
33251
33705
  sh[9 + channel] = read(sh, 9 + channel) + BAND1_PER_SAMPLE * value * dx / rays;
33252
33706
  }
33253
33707
  }
33254
- addDirectLobes(scene, lights, px, py, pz, sh);
33708
+ if (settings.includeDirect) addDirectLobes(scene, lights, px, py, pz, sh);
33255
33709
  return sh;
33256
33710
  }
33257
33711
  /**
@@ -33720,6 +34174,7 @@ function describeSchemas() {
33720
34174
  "ignifx/material-file": describeMaterialFileFormat(),
33721
34175
  "ignifx/environment-file": describeEnvironmentFileFormat(),
33722
34176
  "ignifx/light-probe-file": describeLightProbeFileFormat(),
34177
+ "ignifx/lightmap-file": describeLightmapFileFormat(),
33723
34178
  "ignifx/mesh-file": describeMeshFileFormat()
33724
34179
  };
33725
34180
  }
@@ -34082,6 +34537,42 @@ function describeLightProbeFileFormat() {
34082
34537
  }
34083
34538
  };
34084
34539
  }
34540
+ /**
34541
+ * Describes the `.lightmap.json` lightmap format (GI Phase 2, step B3).
34542
+ *
34543
+ * @returns The description of the top-level file fields.
34544
+ *
34545
+ * @beta
34546
+ */
34547
+ function describeLightmapFileFormat() {
34548
+ return {
34549
+ title: "Lightmap file",
34550
+ format: LIGHTMAP_FILE_FORMAT,
34551
+ description: "A baked lightmap texture that static MeshRenderers sample through their second UV set, and where each entity's UV2 square sits in it.",
34552
+ fields: {
34553
+ format: {
34554
+ kind: "str",
34555
+ default: LIGHTMAP_FILE_FORMAT,
34556
+ description: `Always "${LIGHTMAP_FILE_FORMAT}".`
34557
+ },
34558
+ formatVersion: {
34559
+ kind: "u32",
34560
+ default: 1,
34561
+ description: "The file format version; 1 before ignifx 1.0."
34562
+ },
34563
+ texture: {
34564
+ kind: "str",
34565
+ default: "",
34566
+ description: "The lightmap texture's asset address (a .png, .ktx2 or other texture); required."
34567
+ },
34568
+ entries: {
34569
+ kind: "map",
34570
+ default: {},
34571
+ description: "Per entity uid, { scale: { x, y }, offset: { x, y } }: the entity's UV2 square in the texture (sampled at uv2 · scale + offset; scale above 0). Missing halves and missing entities take scale 1, offset 0. Only the identity is drawn until the atlas transform lands."
34572
+ }
34573
+ }
34574
+ };
34575
+ }
34085
34576
  //#endregion
34086
34577
  //#region src/serialization/instance-lookup.ts
34087
34578
  /**
@@ -34554,10 +35045,11 @@ function writeInstance(root, origin, references, report) {
34554
35045
  * Diffs every direct member of an instance against the record the instanced file holds for it.
34555
35046
  *
34556
35047
  * @remarks
34557
- * Only entities the instanced file itself declares are diffed. An entity that came from a scene
34558
- * the instanced scene itself instanced is not addressable by the §2 path grammar — its uid lives in
34559
- * a third file — so deep edits inside a nested prefab are not written back; `flatten: true` is the
34560
- * escape hatch.
35048
+ * Only entities the instanced file itself declares are diffed. Content that came from a scene the
35049
+ * instanced scene itself instanced is not diffed: an override can address a nested prefab's
35050
+ * component by instance path, but the diff would need the nested file with the outer prefab's own
35051
+ * overrides applied, so deep edits inside a nested prefab are not written back; `flatten: true` is
35052
+ * the escape hatch.
34561
35053
  *
34562
35054
  * An instance root that stands for its scene's single root is diffed against that root's record
34563
35055
  * too, but only for the components the scene put on it: its name, transform, and other entity
@@ -35546,6 +36038,6 @@ function settingsJsonSchema(app) {
35546
36038
  };
35547
36039
  }
35548
36040
  //#endregion
35549
- export { AMBIENT_OCCLUSION_QUALITIES, ASSET_DIAGNOSTICS_COUNTERS, ASSET_DIAGNOSTICS_GROUP, ASSET_MANIFEST_FORMAT, ASSET_MANIFEST_VERSION, AssetLoadError, CANVAS_ALPHA_MODES, CORE_ERROR_MESSAGES, Camera, Color, Component, ComponentRegistry, CoreErrorCode, DEFAULT_ASSET_CONCURRENCY, DEFAULT_ASSET_ROOT, DEFAULT_BRDF_LUT_ADDRESS, DEFAULT_LAYER, DEFAULT_MEMORY_SINK_LIMIT, DEFAULT_STORAGE_NAMESPACE, DEG_TO_RAD, Diagnostics, EASINGS, EASING_NAMES, EDITOR_ONLY_METADATA_KEY, EMPTY_ASSET_MANIFEST, ENVIRONMENT_ASSET_TYPE, ENVIRONMENT_FILE_EXTENSION, ENVIRONMENT_FILE_EXTENSIONS, ENVIRONMENT_FILE_FORMAT, ENVIRONMENT_FORMAT_VERSION, EPSILON, Entity, Environment, EnvironmentAsset, ErrorRange, FOG_MODE_NAMES, FONT_ASSET_TYPE, FONT_FILE_EXTENSIONS, FRAME_HISTORY_LENGTH, FieldKind, FontAsset, IGNIFX_UNIFORM_NAMES, INVALID_HANDLE, IgnifxError, IndexedDbStorageBackend, InstancedMeshRenderer, LIGHT_PROBE_ASSET_TYPE, LIGHT_PROBE_FILE_EXTENSIONS, LIGHT_PROBE_FILE_FORMAT, LIGHT_PROBE_FORMAT_VERSION, LIGHT_TYPES, LITE_MATERIAL_PLUGIN_POINTS, LITE_SYSTEM_UNIFORM_NAMES, LOG_LEVEL_SEVERITY, LayerMask, LayerTable, Light, LightProbeAsset, LightProbeVolume, LogLevel, MAT4_IDENTITY, MATERIAL_ALPHA_MODES, MATERIAL_ASSET_TYPE, MATERIAL_FILE_EXTENSION, MATERIAL_FILE_FORMAT, MATERIAL_FORMAT_VERSION, MATERIAL_KINDS, MATERIAL_PLUGIN_DEFAULT_PRIORITY, MATERIAL_PLUGIN_RESERVED_NAMES, MATERIAL_PLUGIN_SAMPLER_BUDGET, MAX_LAYERS, MAX_ULID_TIME_MS, MESH_ASSET_TYPE, MESH_FILE_EXTENSION, MESH_FILE_FORMAT, MESH_FORMAT_VERSION, MESH_PRIMITIVES, MESH_PRIMITIVE_OPTIONS, MODEL_ASSET_TYPE, MODEL_FILE_EXTENSIONS, Mat4, MaterialAsset, MemoryStorageBackend, MeshAsset, MeshRenderer, Model, ModelAsset, NAMESPACE_SEGMENT_MAX_LENGTH, PBR_TEXTURE_SLOTS, PHASES, PHASE_COUNT, PHASE_NAMES, POST_EFFECT_BUILTIN_UNIFORMS, POST_EFFECT_FUNCTION, PROJECTIONS, Phase, PhysicsCallbackName, PostProcessStack, QUAT_IDENTITY, Quat, RAD_TO_DEG, REFLECTION_PROBE_REFRESH_MODES, RENDERING_QUALITIES, RENDERING_SETTINGS_SECTION, RENDER_DIAGNOSTICS_COUNTERS, RENDER_DIAGNOSTICS_GROUP, RENDER_TEXTURE_MAX_SIZE, RESERVED_LAYER_NAMES, ReflectionProbe, SCENE_ASSET_TYPE, SCENE_FILE_EXTENSIONS, SCENE_FILE_FORMAT, SCENE_FORMAT_VERSION, SETTINGS_DESCRIPTION_FORMAT, SHADER_ASSET_TYPE, SHADER_ATTRIBUTE_NAMES, SHADER_BLEND_MODES, SHADER_CULL_MODES, SHADER_FILE_EXTENSIONS, SHADER_INSTANCING_MODES, SHADER_KINDS, SHADER_TEXTURE_FALLBACKS, SHADER_UNIFORM_TYPES, SHADOW_TECHNIQUES, STANDARD_TEXTURE_SLOTS, STORAGE_BUFFER_ASSET_TYPE, STORAGE_KEY_MAX_LENGTH, SURFACE_HOOK_NAMES, SURFACE_UNIFORM_BLOCK, SceneAssetToken, SceneInstance, SchemaIssueCode, Script, ScriptCallbackKind, ShaderAsset, Signal, StorageBufferAsset, TEXTURE_ASSET_TYPE, THIRD_PARTY_ERROR_PREFIX, TONE_MAPPING_NAMES, TWEEN_LOOP_FOREVER, TWEEN_SYSTEM_ORDER, TWEEN_VALUE_KINDS, TagSet, TextureAsset, Transform, Tween, UidRemap, VEC2_ONE, VEC2_ZERO, VEC3_BACKWARD, VEC3_DOWN, VEC3_FORWARD, VEC3_LEFT, VEC3_ONE, VEC3_RIGHT, VEC3_UP, VEC3_ZERO, VERSION, Vec2, Vec3, Vec4, World, addComponentFromRecord, applyInit, applyOverridesToAsset, approximately, array, assertNever, assertSceneDependenciesLoaded, asset, assetRef, bakeLightProbes, binaryAssetLoader, bool, canonicalizeNumber, clamp, clamp01, color, componentRef, computeSceneHash, coreExtension, createApp, createAssetManifest, createConsoleSink, createCryptoRandom, createDefaults, createDiagnosticsGroup, createEnvironmentLoader, createErrorCodeRegistry, createFileStorageBackend, createFontLoader, createFrameSample, createLayerTable, createLightProbeAsset, createLightProbeLoader, createLogger, createManualClock, createMaterialAsset, createMaterialLoader, createMemorySink, createMeshLoader, createModelLoader, createPerformanceClock, createRay, createSceneAsset, createSceneLoader, createSeededRandom, createServiceKey, createShaderLoader, createStorageBufferAsset, createTextureLoader, createUlidFactory, curve, custom, customEffect, decodeProps, decodeValue, defaultAutoExposureSettings, defaultRenderingSettings, defineExtension, defineMaterialPlugin, defineSchema, degToRad, deltaAngleDegrees, describeEnvironmentFileFormat, describeLightProbeFileFormat, describeMaterialFileFormat, describeMeshFileFormat, describeRegisteredSchemas, describeSceneFileFormat, describeSchema, describeSchemas, describeSettings, encodeProps, encodeValue, entityRef, enumOf, environmentDefinition, f32, f64, forceRendererDeviceLossForTesting, formatErrorMessage, generateUlid, i32, instanceComponentAt, instanceEntityAt, instantiateScene, inverseLerp, isAssetRef, isIgnifxError, isLiteMaterialPluginPoint, isSceneFileHeader, isUlid, isValidErrorCode, isWebGpuAvailable, jsonAssetLoader, layerMask, lerp, lerpAngleDegrees, loadSceneDependencies, map, meshFileJsonSchema, moveTowards, optional, parseOverridePath, pbrMaterialDefinition, pingPong, platformInternals, quat, radToDeg, record, repeat, resetFrameSample, resolveEase, revertOverrides, sampleLightProbes, sceneFileJsonSchema, serializeComponent, serializeEntity, serializeScene, settingsJsonSchema, shaderMaterialDefinition, sign, smoothStep, standardMaterialDefinition, storageInternals, str, stringifySceneFile, textAssetLoader, toJsonSchema, transformSchema, u32, validateProps, validateSceneFile, validateValue, vec2, vec3, vec4, waitFixedUpdate, waitSeconds, waitSecondsRealtime, waitUntil, waitWhile, wrapAngleDegrees, writeLightProbeFile };
36041
+ export { AMBIENT_OCCLUSION_QUALITIES, ASSET_DIAGNOSTICS_COUNTERS, ASSET_DIAGNOSTICS_GROUP, ASSET_MANIFEST_FORMAT, ASSET_MANIFEST_VERSION, AssetLoadError, CANVAS_ALPHA_MODES, CORE_ERROR_MESSAGES, Camera, Color, Component, ComponentRegistry, CoreErrorCode, DEFAULT_ASSET_CONCURRENCY, DEFAULT_ASSET_ROOT, DEFAULT_BRDF_LUT_ADDRESS, DEFAULT_LAYER, DEFAULT_MEMORY_SINK_LIMIT, DEFAULT_STORAGE_NAMESPACE, DEG_TO_RAD, Diagnostics, EASINGS, EASING_NAMES, EDITOR_ONLY_METADATA_KEY, EMPTY_ASSET_MANIFEST, ENVIRONMENT_ASSET_TYPE, ENVIRONMENT_FILE_EXTENSION, ENVIRONMENT_FILE_EXTENSIONS, ENVIRONMENT_FILE_FORMAT, ENVIRONMENT_FORMAT_VERSION, EPSILON, Entity, Environment, EnvironmentAsset, ErrorRange, FOG_MODE_NAMES, FONT_ASSET_TYPE, FONT_FILE_EXTENSIONS, FRAME_HISTORY_LENGTH, FieldKind, FontAsset, IDENTITY_LIGHTMAP_PLACEMENT, IGNIFX_UNIFORM_NAMES, INVALID_HANDLE, IgnifxError, IndexedDbStorageBackend, InstancedMeshRenderer, LIGHTMAP_ASSET_TYPE, LIGHTMAP_FILE_EXTENSIONS, LIGHTMAP_FILE_FORMAT, LIGHTMAP_FORMAT_VERSION, LIGHTMAP_MODES, LIGHT_PROBE_ASSET_TYPE, LIGHT_PROBE_FILE_EXTENSIONS, LIGHT_PROBE_FILE_FORMAT, LIGHT_PROBE_FORMAT_VERSION, LIGHT_TYPES, LITE_MATERIAL_PLUGIN_POINTS, LITE_SYSTEM_UNIFORM_NAMES, LOG_LEVEL_SEVERITY, LayerMask, LayerTable, Light, LightProbeAsset, LightProbeVolume, LightmapAsset, LogLevel, MAT4_IDENTITY, MATERIAL_ALPHA_MODES, MATERIAL_ASSET_TYPE, MATERIAL_FILE_EXTENSION, MATERIAL_FILE_FORMAT, MATERIAL_FORMAT_VERSION, MATERIAL_KINDS, MATERIAL_PLUGIN_DEFAULT_PRIORITY, MATERIAL_PLUGIN_RESERVED_NAMES, MATERIAL_PLUGIN_SAMPLER_BUDGET, MAX_LAYERS, MAX_ULID_TIME_MS, MESH_ASSET_TYPE, MESH_FILE_EXTENSION, MESH_FILE_FORMAT, MESH_FORMAT_VERSION, MESH_PRIMITIVES, MESH_PRIMITIVE_OPTIONS, MODEL_ASSET_TYPE, MODEL_FILE_EXTENSIONS, Mat4, MaterialAsset, MemoryStorageBackend, MeshAsset, MeshRenderer, Model, ModelAsset, NAMESPACE_SEGMENT_MAX_LENGTH, PBR_TEXTURE_SLOTS, PHASES, PHASE_COUNT, PHASE_NAMES, POST_EFFECT_BUILTIN_UNIFORMS, POST_EFFECT_FUNCTION, PROJECTIONS, Phase, PhysicsCallbackName, PostProcessStack, QUAT_IDENTITY, Quat, RAD_TO_DEG, REFLECTION_PROBE_REFRESH_MODES, RENDERING_QUALITIES, RENDERING_SETTINGS_SECTION, RENDER_DIAGNOSTICS_COUNTERS, RENDER_DIAGNOSTICS_GROUP, RENDER_TEXTURE_MAX_SIZE, RESERVED_LAYER_NAMES, ReflectionProbe, SCENE_ASSET_TYPE, SCENE_FILE_EXTENSIONS, SCENE_FILE_FORMAT, SCENE_FORMAT_VERSION, SETTINGS_DESCRIPTION_FORMAT, SHADER_ASSET_TYPE, SHADER_ATTRIBUTE_NAMES, SHADER_BLEND_MODES, SHADER_CULL_MODES, SHADER_FILE_EXTENSIONS, SHADER_INSTANCING_MODES, SHADER_KINDS, SHADER_TEXTURE_FALLBACKS, SHADER_UNIFORM_TYPES, SHADOW_TECHNIQUES, STANDARD_TEXTURE_SLOTS, STORAGE_BUFFER_ASSET_TYPE, STORAGE_KEY_MAX_LENGTH, SURFACE_HOOK_NAMES, SURFACE_UNIFORM_BLOCK, SceneAssetToken, SceneInstance, SchemaIssueCode, Script, ScriptCallbackKind, ShaderAsset, Signal, StorageBufferAsset, TEXTURE_ASSET_TYPE, THIRD_PARTY_ERROR_PREFIX, TONE_MAPPING_NAMES, TWEEN_LOOP_FOREVER, TWEEN_SYSTEM_ORDER, TWEEN_VALUE_KINDS, TagSet, TextureAsset, Transform, Tween, UidRemap, VEC2_ONE, VEC2_ZERO, VEC3_BACKWARD, VEC3_DOWN, VEC3_FORWARD, VEC3_LEFT, VEC3_ONE, VEC3_RIGHT, VEC3_UP, VEC3_ZERO, VERSION, Vec2, Vec3, Vec4, World, addComponentFromRecord, applyInit, applyOverridesToAsset, approximately, array, assertNever, assertSceneDependenciesLoaded, asset, assetRef, bakeLightProbes, binaryAssetLoader, bool, canonicalizeNumber, clamp, clamp01, color, componentRef, computeSceneHash, coreExtension, createApp, createAssetManifest, createConsoleSink, createCryptoRandom, createDefaults, createDiagnosticsGroup, createEnvironmentLoader, createErrorCodeRegistry, createFileStorageBackend, createFontLoader, createFrameSample, createLayerTable, createLightProbeAsset, createLightProbeLoader, createLightmapAsset, createLightmapLoader, createLogger, createManualClock, createMaterialAsset, createMaterialLoader, createMemorySink, createMeshLoader, createModelLoader, createPerformanceClock, createRay, createSceneAsset, createSceneLoader, createSeededRandom, createServiceKey, createShaderLoader, createStorageBufferAsset, createTextureLoader, createUlidFactory, curve, custom, customEffect, decodeProps, decodeValue, defaultAutoExposureSettings, defaultRenderingSettings, defineExtension, defineMaterialPlugin, defineSchema, degToRad, deltaAngleDegrees, describeEnvironmentFileFormat, describeLightProbeFileFormat, describeLightmapFileFormat, describeMaterialFileFormat, describeMeshFileFormat, describeRegisteredSchemas, describeSceneFileFormat, describeSchema, describeSchemas, describeSettings, encodeProps, encodeValue, entityRef, enumOf, enumerateInstanceTargets, environmentDefinition, f32, f64, forceRendererDeviceLossForTesting, formatErrorMessage, generateUlid, i32, instanceComponentAt, instanceEntityAt, instantiateScene, inverseLerp, isAssetRef, isIgnifxError, isLiteMaterialPluginPoint, isSceneFileHeader, isUlid, isValidErrorCode, isWebGpuAvailable, jsonAssetLoader, layerMask, lerp, lerpAngleDegrees, loadSceneDependencies, map, meshFileJsonSchema, moveTowards, optional, parseOverridePath, pbrMaterialDefinition, pingPong, platformInternals, quat, radToDeg, record, repeat, resetFrameSample, resolveEase, resolveInstancePath, revertOverrides, sampleLightProbes, sceneFileJsonSchema, serializeComponent, serializeEntity, serializeScene, settingsJsonSchema, shaderMaterialDefinition, sign, smoothStep, standardMaterialDefinition, storageInternals, str, stringifySceneFile, textAssetLoader, toJsonSchema, transformSchema, u32, validateProps, validateSceneFile, validateValue, vec2, vec3, vec4, waitFixedUpdate, waitSeconds, waitSecondsRealtime, waitUntil, waitWhile, wrapAngleDegrees, writeLightProbeFile, writeLightmapFile };
35550
36042
 
35551
36043
  //# sourceMappingURL=index.js.map