@ignifx/core 0.19.0 → 0.21.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 (45) hide show
  1. package/dist/{gtao-_nr0b6-E.js → gtao-Bpu5-0Ne.js} +2 -2
  2. package/dist/{gtao-_nr0b6-E.js.map → gtao-Bpu5-0Ne.js.map} +1 -1
  3. package/dist/{hdr-output-Dbv0lhFl.js → hdr-output-DBQwMphy.js} +2 -2
  4. package/dist/{hdr-output-Dbv0lhFl.js.map → hdr-output-DBQwMphy.js.map} +1 -1
  5. package/dist/index.d.ts +181 -21
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js +1616 -174
  8. package/dist/index.js.map +1 -1
  9. package/dist/{instanced-mesh-instance-BMhREEfx.js → instanced-mesh-instance-B-fXKSrY.js} +2 -2
  10. package/dist/{instanced-mesh-instance-BMhREEfx.js.map → instanced-mesh-instance-B-fXKSrY.js.map} +1 -1
  11. package/dist/{light-probes-DyLapYX9.js → light-probes-DDojYajw.js} +2 -2
  12. package/dist/{light-probes-DyLapYX9.js.map → light-probes-DDojYajw.js.map} +1 -1
  13. package/dist/lightmaps-BUUIIkt9.js +230 -0
  14. package/dist/lightmaps-BUUIIkt9.js.map +1 -0
  15. package/dist/{material-CGk5mAah.js → material-myMbl9mW.js} +37 -2
  16. package/dist/{material-CGk5mAah.js.map → material-myMbl9mW.js.map} +1 -1
  17. package/dist/{post-effect-CaiqDlhW.js → post-effect-Cu3Enpz7.js} +2 -2
  18. package/dist/{post-effect-CaiqDlhW.js.map → post-effect-Cu3Enpz7.js.map} +1 -1
  19. package/dist/{post-effect-compiler-jSvOVe0U.js → post-effect-compiler-cCq9lcHt.js} +2 -2
  20. package/dist/{post-effect-compiler-jSvOVe0U.js.map → post-effect-compiler-cCq9lcHt.js.map} +1 -1
  21. package/dist/{prefab-overrides-DRP2DcnC.js → prefab-overrides-C2GsgOQc.js} +24 -7
  22. package/dist/prefab-overrides-C2GsgOQc.js.map +1 -0
  23. package/dist/{prefab-overrides-CS8_cG66.d.ts → prefab-overrides-htDc_5Po.d.ts} +53 -12
  24. package/dist/prefab-overrides-htDc_5Po.d.ts.map +1 -0
  25. package/dist/prefab.d.ts +1 -1
  26. package/dist/prefab.js +1 -1
  27. package/dist/{reflection-probe-AS8d4uKv.js → reflection-probe-QkD1Fo_d.js} +79 -3
  28. package/dist/{reflection-probe-AS8d4uKv.js.map → reflection-probe-QkD1Fo_d.js.map} +1 -1
  29. package/dist/{reflection-probes-CUZcOjNW.js → reflection-probes-CAzSuqf8.js} +298 -21
  30. package/dist/reflection-probes-CAzSuqf8.js.map +1 -0
  31. package/dist/{shader-material-CuwK9tWC.js → shader-material-TM4f8eKA.js} +2 -2
  32. package/dist/{shader-material-CuwK9tWC.js.map → shader-material-TM4f8eKA.js.map} +1 -1
  33. package/dist/{ssgi-Dm-maZrc.js → ssgi-DSnhqotl.js} +2 -2
  34. package/dist/{ssgi-Dm-maZrc.js.map → ssgi-DSnhqotl.js.map} +1 -1
  35. package/dist/{surface-shader-DY9_aC9L.js → surface-shader-rpPpeosD.js} +4 -4
  36. package/dist/{surface-shader-DY9_aC9L.js.map → surface-shader-rpPpeosD.js.map} +1 -1
  37. package/dist/{vec3-Cc19wl4r.js → vec3-2C3LBZnt.js} +55 -3
  38. package/dist/vec3-2C3LBZnt.js.map +1 -0
  39. package/package.json +1 -1
  40. package/dist/lightmaps-LO6Ygtwe.js +0 -137
  41. package/dist/lightmaps-LO6Ygtwe.js.map +0 -1
  42. package/dist/prefab-overrides-CS8_cG66.d.ts.map +0 -1
  43. package/dist/prefab-overrides-DRP2DcnC.js.map +0 -1
  44. package/dist/reflection-probes-CUZcOjNW.js.map +0 -1
  45. package/dist/vec3-Cc19wl4r.js.map +0 -1
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lightmaps-BUUIIkt9.js","names":[],"sources":["../src/lite/gpu/lightmap.ts","../src/render/gpu/lightmaps.ts"],"sourcesContent":["import { enableMaterialPlugins, enablePbrLightmap, isPbrMaterial, setPbrLightmap } from \"@babylonjs/lite\";\nimport { markMaterialDirty } from \"../material.js\";\nimport type { Material, MaterialPlugin, SceneContext, Texture2D } from \"@babylonjs/lite\";\n\n/**\n * Lightmaps on the GPU (`docs/plan/2026-11-gi-phase-2-execution-plan.md`, step B3). Loaded with\n * `../../render/gpu/lightmaps.ts` as one chunk, only once a static `MeshRenderer` names a loaded\n * lightmap (`CONSTITUTION.md` §2.5). Every Lite claim was read from `@babylonjs/lite@1.34.0`.\n *\n * - **Late enable.** `enablePbrLightmap` (`index.d.ts` 5342) asks to be awaited before\n * `registerScene`, but all it does is register the fragment extension in a process-wide map whose\n * sorted cache it resets (`lib/material/pbr/pbr-flags.js`, `_registerPbrExt`). A material that has\n * no `lightmapTexture` reports no lightmap feature bits (`lightmap-fragment.js`, `detect`), so\n * pipelines built before the call keep their keys, and a material built after it sees the\n * extension. The chunk therefore enables it on load; `rendering.features.lightmaps` only does it\n * earlier.\n * - **Per-material.** `setPbrLightmap` (12635) writes the texture, level, UV set, blend mode and\n * decode onto one material and claims TEXCOORD_1 for it, so a renderer gets its own material\n * before the call. Only `level` is a uniform (`writeLightmapUBO`); the rest are feature bits, so a\n * change of them needs a new material.\n * - **Atlas placement (GI plan §5, spike P2).** The fragment samples `input.uv2` raw (line 24) and\n * ignores the texture's `uScale`/`uOffset`, so Lite has no lightmap UV transform. The PBR vertex\n * template writes `out.uv2 = uv2;` just before the `CUSTOM_VERTEX_MAIN_END` slot\n * (`lib/material/pbr/pbr-template.js` 133, `pbr-template-ext.js` 71), so a plugin there rewrites\n * the varying the lightmap reads: {@link lightmapAtlasPlugin}. The scale and offset are WGSL\n * constants rather than uniforms, because a vertex-visible plugin uniform needs\n * `enablePbrMaterialPluginVertexData` (`index.d.ts` 5349), whose bridge maps\n * `CUSTOM_FRAGMENT_BEFORE_FINALCOLORCOMPOSITION` to the `NI` slot only\n * (`lib/material/plugin/pbr-plugin-vertex-data.js` versus `plugin-bridge-shared.js`, which also\n * injects it at `AI`), and the light-probe, HDR-output and SSGI plugins count on the double\n * injection. So each distinct placement is its own pipeline variant. The varying exists only\n * when the lightmap samples TEXCOORD_1 and the mesh has a `uvs2` buffer (`pbr-compose.js` 42), so\n * the plugin is only for that case. Lite's own V flip, when the texture asks for one, applies to\n * the transformed coordinate, as it does to the raw one.\n */\n\n/**\n * The options one material's lightmap is drawn with.\n *\n * @internal\n */\nexport interface LiteLightmapOptions {\n /** Intensity multiplier on the sample. */\n readonly level: number;\n /** `true` multiplies the shaded colour (Lite's `useAsShadowmap`); `false` adds to it. */\n readonly shadowmap: boolean;\n /** Decode the sample from sRGB to linear (`pow(x, 2.2)`). */\n readonly gamma: boolean;\n /** Sample with the second UV set (`TEXCOORD_1`) rather than the first. */\n readonly uv2: boolean;\n /**\n * Where the renderer's UV2 square sits in the texture (`uv2 · scale + offset`), or `null` for the\n * whole texture. Only honoured with `uv2` on a mesh that has a second UV set.\n */\n readonly atlas: LiteLightmapAtlas | null;\n}\n\n/**\n * One renderer's placement in a lightmap atlas, as plain numbers.\n *\n * @internal\n */\nexport interface LiteLightmapAtlas {\n /** The atlas-space size of the renderer's UV2 square. */\n readonly scale: { readonly x: number; readonly y: number };\n /** The atlas-space position of the square's `(0, 0)` corner. */\n readonly offset: { readonly x: number; readonly y: number };\n}\n\n/** The atlas plugins made so far, by WGSL; a plugin holds no state, so one per placement does. */\nlet atlasPlugins: Map<string, MaterialPlugin> | null = null;\n\n/** The name every atlas plugin carries; the WGSL tells placements apart in Lite's cache key. */\nexport const LIGHTMAP_ATLAS_PLUGIN_NAME = \"ignifx-lightmap-atlas\";\n\n/**\n * A WGSL float literal, always with a decimal point or an exponent.\n *\n * @param value - A finite number.\n * @returns The literal.\n */\nfunction float(value: number): string {\n const text = String(value);\n return /[.e]/.test(text) ? text : `${text}.0`;\n}\n\n/**\n * The vertex code that moves the lightmap's UV2 varying into the renderer's atlas square.\n *\n * @param atlas - The placement.\n * @returns WGSL for `CUSTOM_VERTEX_MAIN_END`.\n *\n * @internal\n */\nexport function lightmapAtlasWgsl(atlas: LiteLightmapAtlas): string {\n const { scale, offset } = atlas;\n return (\n `out.uv2=out.uv2*vec2<f32>(${float(scale.x)},${float(scale.y)})` +\n `+vec2<f32>(${float(offset.x)},${float(offset.y)});`\n );\n}\n\n/**\n * The plugin that applies one atlas placement, shared by every material with that placement.\n *\n * @remarks\n * Only valid on a material whose lightmap samples TEXCOORD_1 drawn on a mesh with a `uvs2` buffer:\n * anywhere else `out.uv2` does not exist and the pipeline fails to compile.\n *\n * @param atlas - The placement.\n * @returns The plugin; the same object for the same placement.\n *\n * @internal\n */\nexport function lightmapAtlasPlugin(atlas: LiteLightmapAtlas): MaterialPlugin {\n const code = lightmapAtlasWgsl(atlas);\n atlasPlugins ??= new Map();\n let plugin = atlasPlugins.get(code);\n if (plugin === undefined) {\n const vertex = { CUSTOM_VERTEX_MAIN_END: code };\n plugin = {\n name: LIGHTMAP_ATLAS_PLUGIN_NAME,\n getCustomCode: (stage) => (stage === \"vertex\" ? vertex : null),\n };\n atlasPlugins.set(code, plugin);\n }\n return plugin;\n}\n\n/**\n * Whether a plugin is an atlas plugin.\n *\n * @param plugin - Any plugin.\n * @returns `true` for one {@link lightmapAtlasPlugin} made.\n */\nfunction isAtlasPlugin(plugin: MaterialPlugin): boolean {\n return plugin.name === LIGHTMAP_ATLAS_PLUGIN_NAME;\n}\n\n/**\n * Installs Lite's PBR lightmap extension. Idempotent.\n *\n * @returns A promise that settles once the extension is registered.\n *\n * @internal\n */\nexport function enableLightmaps(): Promise<void> {\n return enablePbrLightmap();\n}\n\n/**\n * Gives a PBR material a lightmap.\n *\n * @remarks\n * With an `atlas` placement (and `uv2`), the material also gets the {@link lightmapAtlasPlugin} for\n * it, replacing an earlier one, and the scene's material-plugin bridges are installed first\n * (idempotent; light probes install them after `registerScene` the same way). The caller rebuilds\n * the material's pipelines afterwards.\n *\n * @param scene - The registered scene.\n * @param material - A material no other mesh shares, not yet built with other lightmap options.\n * @param texture - The lightmap.\n * @param options - How it is drawn.\n * @returns `false` when the material is not PBR, so nothing was set.\n *\n * @internal\n */\nexport function applyLightmap(\n scene: SceneContext,\n material: Material,\n texture: Texture2D,\n options: LiteLightmapOptions,\n): boolean {\n if (!isPbrMaterial(material)) {\n return false;\n }\n setPbrLightmap(material, texture, {\n level: options.level,\n coordIndex: options.uv2 ? 1 : 0,\n useAsShadowmap: options.shadowmap,\n gamma: options.gamma,\n });\n const current = material.plugins ?? [];\n const kept = current.some(isAtlasPlugin) ? current.filter((plugin) => !isAtlasPlugin(plugin)) : current;\n if (options.atlas !== null && options.uv2) {\n enableMaterialPlugins(scene);\n material.plugins = [...kept, lightmapAtlasPlugin(options.atlas)];\n } else if (kept !== current) {\n material.plugins = kept;\n }\n return true;\n}\n\n/**\n * Changes a lightmapped material's intensity; only its uniform block is rewritten.\n *\n * @param material - A material {@link applyLightmap} set up.\n * @param level - The new multiplier.\n *\n * @internal\n */\nexport function setLightmapLevel(material: Material, level: number): void {\n if (isPbrMaterial(material) && material.lightmapLevel !== level) {\n material.lightmapLevel = level;\n markMaterialDirty(material);\n }\n}\n","import { applyLightmap, enableLightmaps, lightmapAtlasWgsl, setLightmapLevel } from \"../../lite/gpu/lightmap.js\";\nimport { rebuildMaterialPipelines, syncPbrFactors } from \"../../lite/material.js\";\nimport type { App } from \"../../app/types.js\";\nimport type { AssetHandle } from \"../../assets/types.js\";\nimport type { LiteLightmapOptions } from \"../../lite/gpu/lightmap.js\";\nimport type { LiteTexture2D } from \"../../lite/gpu/texture.js\";\nimport type { LiteMaterial } from \"../../lite/material.js\";\nimport type { LiteScene } from \"../../lite/scene.js\";\nimport type { LightmapAsset, LightmapPlacement } from \"../lightmap-asset.js\";\nimport type { MaterialAsset } from \"../material-asset.js\";\nimport type { LightmapMode, MeshRendererLightmap } from \"../mesh-renderer.js\";\n\n/**\n * The render layer's half of lightmaps (`docs/plan/2026-11-gi-phase-2-execution-plan.md`, step B3):\n * one material clone per lightmapped renderer. Loaded with `../../lite/gpu/lightmap.ts` as one\n * chunk, only once a static `MeshRenderer` names a loaded lightmap.\n *\n * `MaterialAsset`s are shared, and a lightmap is per renderer, so each renderer draws with\n * `MaterialAsset.clone` of its material carrying the lightmap. The clone is rebuilt when the\n * material, the lightmap, its texture, a compiled option (`mode`, `gamma`, `uv2`) or the atlas\n * placement changes; a `level` change only rewrites the clone's uniform block. A placement other\n * than the whole texture is a vertex plugin on the clone (`../../lite/gpu/lightmap.ts`), one\n * pipeline variant per distinct placement. Nothing here allocates on a frame where no clone changes. Edits made to the shared material through\n * its factor setters (`setBaseColor`, `setMetallicRoughness`, `setAlpha`) are copied onto the clone\n * the next frame it is asked for (a comparison of seven numbers per frame); a reloaded material is a\n * new asset, so it gets a new clone.\n *\n * ## Two frames, because of how Lite plumbs `uv2`\n *\n * Lite decides whether its PBR group carries the `uv2` attribute and varying when it builds the\n * group, from the meshes' materials at that time (`lib/material/pbr/pbr-renderable.js`, `hasAnyUv2`).\n * A `mesh.material` swap reuses the group's single-mesh rebuild (`lib/scene/scene-material-swap.js`),\n * whose composer has no `uv2` then, and a lightmap that samples `input.uv2` fails to compile; the\n * pipeline keeps failing after a later group rebuild, because the broken composition was cached\n * under the same feature key (measured in `lightmap.browser.test.ts`). So the renderer first draws\n * with a plain clone, which compiles like its base material, and on the next\n * {@link LightmapRuntime.flush} the clone gets its lightmap and `rebuildMaterial`, which for a built\n * PBR scene rebuilds the whole PBR group (`lib/scene/scene-runtime-mesh-build.js`, `B`) and so\n * composes the lightmap with `uv2`. That costs one PBR group rebuild per frame that new lightmapped\n * renderers arrive in, and one frame without the lightmap.\n */\n\n/**\n * How many distinct atlas placements may be alive before the runtime warns once: each compiles its\n * own pipeline variant per pass.\n *\n * @internal\n */\nexport const LIGHTMAP_PLACEMENT_WARNING_THRESHOLD = 64;\n\n/** One renderer's clone and what it was built from. */\ninterface Entry {\n readonly base: MaterialAsset;\n readonly lightmap: LightmapAsset;\n readonly texture: LiteTexture2D;\n /** The compiled options: a change of any of them needs a new clone. */\n readonly mode: LightmapMode;\n readonly gamma: boolean;\n readonly uv2: boolean;\n /** The atlas placement applied, or `null` for the whole texture; compared by reference. */\n readonly atlas: LightmapPlacement | null;\n /** The placement's WGSL, which tells distinct placements apart, or `null` without one. */\n readonly atlasKey: string | null;\n readonly clone: AssetHandle<MaterialAsset>;\n /** The intensity the next flush applies; it follows the record every frame. */\n level: number;\n /** Whether the lightmap is set on the clone yet. */\n isApplied: boolean;\n /** Whether the clone was given up, so a pending flush skips it. */\n isReleased: boolean;\n}\n\n/**\n * The lightmaps of a renderer.\n *\n * @internal\n */\nexport interface LightmapRuntime {\n /** How many renderers draw with a lightmapped clone. */\n readonly count: number;\n /**\n * The material a renderer draws with: its lightmapped clone, built or refreshed as needed.\n *\n * @param owner - The renderer, as a map key.\n * @param base - The material it declares.\n * @param lightmap - The loaded lightmap.\n * @param settings - Its `lightmap` record.\n * @param atlas - The renderer's placement in the texture, or `null` to sample all of it. The host\n * passes one only for a UV2 lightmap on a mesh with a second UV set; a placement object from the\n * asset keeps its identity, so a new one rebuilds the clone.\n * @returns The clone's Lite material, or `base`'s while the texture is not on the GPU.\n */\n materialFor(\n owner: object,\n base: MaterialAsset,\n lightmap: LightmapAsset,\n settings: MeshRendererLightmap,\n atlas: LightmapPlacement | null,\n ): LiteMaterial;\n /**\n * Drops a renderer's clone, if it has one.\n *\n * @param owner - The renderer.\n */\n release(owner: object): void;\n /** Gives the clones handed out a frame ago their lightmap; the renderer calls it after every `MeshRenderer` synced. */\n flush(): void;\n /** Drops every clone. */\n dispose(): void;\n}\n\n/**\n * Installs Lite's lightmap extension and creates the runtime.\n *\n * @param app - The app whose asset service publishes the clones.\n * @param scene - The registered render scene.\n * @returns The runtime, once the extension is registered.\n *\n * @internal\n */\nexport async function createLightmapRuntime(app: App, scene: LiteScene): Promise<LightmapRuntime> {\n await enableLightmaps();\n const entries = new Map<object, Entry>();\n /** Clones handed out this frame, and those whose meshes have drawn them plain for a frame. */\n let fresh: Entry[] = [];\n let due: Entry[] = [];\n /** Live renderers per distinct placement, for the pipeline-count warning. */\n const placements = new Map<string, number>();\n let hasWarnedPlacements = false;\n\n const release = (owner: object): void => {\n const entry = entries.get(owner);\n if (entry !== undefined) {\n entries.delete(owner);\n entry.isReleased = true;\n if (entry.atlasKey !== null) {\n const left = (placements.get(entry.atlasKey) ?? 1) - 1;\n if (left > 0) {\n placements.set(entry.atlasKey, left);\n } else {\n placements.delete(entry.atlasKey);\n }\n }\n entry.clone.release();\n }\n };\n\n return {\n get count(): number {\n return entries.size;\n },\n materialFor(owner, base, lightmap, settings, atlas): LiteMaterial {\n const handle = lightmap.texture;\n const texture = handle.state === \"loaded\" ? handle.value.lite.texture : null;\n if (texture === null) {\n release(owner);\n return base.lite.material;\n }\n const current = entries.get(owner);\n if (\n current !== undefined &&\n current.base === base &&\n current.lightmap === lightmap &&\n current.texture === texture &&\n current.mode === settings.mode &&\n current.gamma === settings.gamma &&\n current.uv2 === settings.uv2 &&\n current.atlas === atlas\n ) {\n const material = current.clone.value.lite.material;\n syncPbrFactors(base.lite.material, material);\n current.level = settings.level;\n if (current.isApplied) {\n setLightmapLevel(material, settings.level);\n }\n return material;\n }\n release(owner);\n const clone = base.clone(app);\n // The clone replays the declaration, so it takes the edits made to the base since it loaded.\n syncPbrFactors(base.lite.material, clone.value.lite.material);\n const entry: Entry = {\n base,\n lightmap,\n texture,\n mode: settings.mode,\n gamma: settings.gamma,\n uv2: settings.uv2,\n atlas,\n atlasKey: atlas === null ? null : lightmapAtlasWgsl(atlas),\n clone,\n level: settings.level,\n isApplied: false,\n isReleased: false,\n };\n entries.set(owner, entry);\n if (entry.atlasKey !== null) {\n placements.set(entry.atlasKey, (placements.get(entry.atlasKey) ?? 0) + 1);\n if (!hasWarnedPlacements && placements.size > LIGHTMAP_PLACEMENT_WARNING_THRESHOLD) {\n hasWarnedPlacements = true;\n app.log.warn(\n `${String(placements.size)} distinct lightmap atlas placements are in use; each compiles its own ` +\n \"shader pipeline per pass, which costs load time and memory. A shared-UV approach is planned; \" +\n \"until then, bake UV2 that already points into the atlas and leave the entries empty.\",\n );\n }\n }\n fresh.push(entry);\n return clone.value.lite.material;\n },\n release,\n flush(): void {\n for (const entry of due) {\n if (entry.isReleased) {\n continue;\n }\n const material = entry.clone.value.lite.material;\n const options: LiteLightmapOptions = {\n level: entry.level,\n shadowmap: entry.mode === \"shadowmap\",\n gamma: entry.gamma,\n uv2: entry.uv2,\n atlas: entry.atlas,\n };\n if (applyLightmap(scene, material, entry.texture, options)) {\n entry.isApplied = true;\n rebuildMaterialPipelines(scene, material);\n }\n }\n due = fresh;\n fresh = [];\n },\n dispose(): void {\n fresh = [];\n due = [];\n for (const owner of entries.keys()) {\n release(owner);\n }\n },\n };\n}\n"],"mappings":"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"}
@@ -146,6 +146,41 @@ function setPbrMetallicRoughness(material, metallic, roughness) {
146
146
  markMaterialDirty(material);
147
147
  }
148
148
  /**
149
+ * Makes one PBR material's base colour, metallic, roughness and alpha factors (what
150
+ * `MaterialAsset`'s setters write) equal another's, such as a renderer's lightmapped copy of a
151
+ * shared material. Writes, and marks the copy dirty, only when something differs.
152
+ *
153
+ * @param from - The material to read.
154
+ * @param to - The material to change.
155
+ * @returns `true` when `to` changed.
156
+ *
157
+ * @internal
158
+ */
159
+ function syncPbrFactors(from, to) {
160
+ const color = from.baseColorFactor ?? [
161
+ 1,
162
+ 1,
163
+ 1,
164
+ 1
165
+ ];
166
+ const current = to.baseColorFactor ?? [
167
+ 1,
168
+ 1,
169
+ 1,
170
+ 1
171
+ ];
172
+ const metallic = from.metallicFactor ?? 1;
173
+ const roughness = from.roughnessFactor ?? 1;
174
+ const alpha = from.alpha ?? 1;
175
+ if (color[0] === current[0] && color[1] === current[1] && color[2] === current[2] && color[3] === current[3] && metallic === (to.metallicFactor ?? 1) && roughness === (to.roughnessFactor ?? 1) && alpha === (to.alpha ?? 1)) return false;
176
+ setPbrBaseColor(to, color[0], color[1], color[2], color[3]);
177
+ to.metallicFactor = metallic;
178
+ to.roughnessFactor = roughness;
179
+ to.alpha = alpha;
180
+ markMaterialDirty(to);
181
+ return true;
182
+ }
183
+ /**
149
184
  * Replaces a material's overall alpha.
150
185
  *
151
186
  * @param material - The PBR or Standard material to change.
@@ -199,6 +234,6 @@ function writeTriple(target, source) {
199
234
  target[2] = source[2];
200
235
  }
201
236
  //#endregion
202
- export { markMaterialDirty as a, setPbrBaseColor as c, createStandardMaterialFromProps as i, setPbrMetallicRoughness as l, createDefaultMaterial as n, rebuildMaterialPipelines as o, createPbrMaterialFromProps as r, setMaterialAlpha as s, MATERIAL_ALPHA_MODES as t };
237
+ export { markMaterialDirty as a, setPbrBaseColor as c, createStandardMaterialFromProps as i, setPbrMetallicRoughness as l, createDefaultMaterial as n, rebuildMaterialPipelines as o, createPbrMaterialFromProps as r, setMaterialAlpha as s, MATERIAL_ALPHA_MODES as t, syncPbrFactors as u };
203
238
 
204
- //# sourceMappingURL=material-CGk5mAah.js.map
239
+ //# sourceMappingURL=material-myMbl9mW.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"material-CGk5mAah.js","names":[],"sources":["../src/lite/material.ts"],"sourcesContent":["import {\n createPbrMaterial,\n createStandardMaterial,\n enableMaterialTracking,\n markMaterialUboDirty,\n rebuildMaterial,\n setPbrAlphaCutoff,\n setPbrEmissive,\n setPbrUnlit,\n setStandardBumpTexture,\n setStandardEmissiveTexture,\n setStandardOpacityTexture,\n setStandardSpecularTexture,\n} from \"@babylonjs/lite\";\nimport { assertNever } from \"../errors/ignifx-error.js\";\nimport type { Material, PbrMaterialProps, SceneContext, StandardMaterialProps, Texture2D } from \"@babylonjs/lite\";\n\n/**\n * Material half of the Babylon Lite adapter (`docs/architecture/07-rendering.md` §2.6): the three\n * material kinds a `MaterialAsset` can produce, built from plain ignifx props.\n *\n * Everything here is `@internal`, and every colour that reaches it is **linear** — the sRGB decode\n * belongs to the asset layer.\n *\n * ## What a Lite material is (verified against `@babylonjs/lite@1.27.0`)\n *\n * - A material is plain data plus one private `_buildGroup` function; `createPbrMaterial` is\n * literally `{ ...props, _buildGroup, _uboVersion: 0 }` (`lib/material/pbr/pbr-material.js`), so\n * none of these factories touches the GPU and all of them run under the null engine.\n * - **The build group is a per-family singleton.** `getPbrGroupBuilder()`, `getStandardGroupBuilder()`\n * and `getShaderGroupBuilder()` each memoise one function for the whole process\n * (`lib/material/pbr/pbr-material.js`, `lib/material/standard/create-standard-material.js`,\n * `lib/material/shader/shader-material.js` line 123), and a scene keys its renderable groups by\n * that function (`lib/scene/scene-core.js`, `addToScene`). \"Material family\" in\n * `docs/architecture/07-rendering.md` §1.1 therefore means *pbr*, *standard*, *shader* or *node* —\n * **not** an individual material. Only node materials get a per-material builder\n * (`lib/material/node/node-material.js`). This is what makes {@link warmUpMaterialFamilies} in\n * `./gpu/warm-up.ts` cheap: one hidden mesh per family covers every material in it.\n * - Scalar and vector edits only need `markMaterialUboDirty` (`index.d.ts` 6974), which bumps\n * `_uboVersion`. Anything that changes the compiled feature set — binding or clearing a texture,\n * flipping `doubleSided`, changing culling — needs {@link rebuildMaterialPipelines}.\n *\n * ## The custom WGSL family lives elsewhere\n *\n * `createShaderMaterial` and the `setShader*` setters are in `./gpu/shader-material.ts`, not here:\n * this module is statically reachable from every app through the material asset layer, and Babylon\n * Lite exports one barrel, so a static import of the shader factory would put Lite's whole\n * shader-material pipeline in every entry chunk. That module is reached through a dynamic\n * `import()` instead (`docs/plan/2026-09-terrain-particles-shaders.md` §3.1, \"Bundle cost\").\n */\n\n/**\n * The Babylon Lite material a `MaterialAsset` owns, re-exported under an ignifx name\n * (`CONSTITUTION.md` §3.4, coding standards §4).\n *\n * @remarks\n * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.\n *\n * @public\n */\nexport type LiteMaterial = Material;\n\n/**\n * A Babylon Lite physically based material, re-exported under an ignifx name.\n *\n * @remarks\n * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.\n *\n * @public\n */\nexport type LitePbrMaterial = PbrMaterialProps;\n\n/**\n * A Babylon Lite Babylon-Standard material, re-exported under an ignifx name.\n *\n * @remarks\n * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.\n *\n * @public\n */\nexport type LiteStandardMaterial = StandardMaterialProps;\n\n/** glTF's default alpha cutoff, used when a `\"mask\"` material declares none. */\nconst DEFAULT_ALPHA_CUTOFF = 0.5;\n\n/**\n * How a material's alpha channel is interpreted, in glTF's vocabulary, in the order the inspector\n * lists them (`docs/architecture/07-rendering.md` §2.4).\n *\n * @public\n */\nexport const MATERIAL_ALPHA_MODES = [\"opaque\", \"mask\", \"blend\"] as const;\n\n/**\n * The union of the alpha modes a material can declare.\n *\n * @public\n */\nexport type MaterialAlphaMode = (typeof MATERIAL_ALPHA_MODES)[number];\n\n/**\n * The physically based material properties an ignifx `.material.json` declares\n * (`docs/architecture/06-serialization-and-scene-format.md` §6). Every field is optional; an\n * omitted field leaves Lite's own default in place.\n *\n * @internal\n */\nexport interface PbrMaterialInput {\n /** A human-readable name, used for glTF material overrides and diagnostics. */\n readonly name?: string;\n /** Linear base colour and alpha, multiplied with the base colour texture. */\n readonly baseColor?: readonly [number, number, number, number];\n /** The base colour texture. Load it with an sRGB format. */\n readonly baseColorTexture?: Texture2D;\n /** Metallic factor, 0 to 1. */\n readonly metallic?: number;\n /** Roughness factor, 0 to 1. */\n readonly roughness?: number;\n /** The packed occlusion/roughness/metallic texture (glTF `ORM`). */\n readonly metallicRoughnessTexture?: Texture2D;\n /** The tangent-space normal map. */\n readonly normalTexture?: Texture2D;\n /** Normal map strength. */\n readonly normalScale?: number;\n /** Linear emissive colour. */\n readonly emissive?: readonly [number, number, number];\n /** The emissive texture. */\n readonly emissiveTexture?: Texture2D;\n /** A separate occlusion texture, sampled on UV1 when the ORM texture is not used for it. */\n readonly occlusionTexture?: Texture2D;\n /** How strongly ambient occlusion darkens the surface, 0 to 1. */\n readonly occlusionStrength?: number;\n /** How the alpha channel is interpreted. */\n readonly alphaMode?: MaterialAlphaMode;\n /** The cutoff below which a `\"mask\"` material discards a fragment. */\n readonly alphaCutoff?: number;\n /** Overall material alpha, 0 to 1. */\n readonly alpha?: number;\n /** Whether back faces are drawn. */\n readonly doubleSided?: boolean;\n /** Whether lighting is skipped entirely. */\n readonly unlit?: boolean;\n /** How strongly the environment map contributes. */\n readonly environmentIntensity?: number;\n}\n\n/**\n * The Babylon-Standard material properties an ignifx `.material.json` declares, for the cheap\n * non-PBR path (`docs/architecture/07-rendering.md` §2.6).\n *\n * @internal\n */\nexport interface StandardMaterialInput {\n /** A human-readable name. */\n readonly name?: string;\n /** Linear diffuse colour. */\n readonly diffuse?: readonly [number, number, number];\n /** The diffuse texture. */\n readonly diffuseTexture?: Texture2D;\n /** Linear specular colour. */\n readonly specular?: readonly [number, number, number];\n /** Specular exponent; higher values give a tighter highlight. */\n readonly specularPower?: number;\n /** The specular texture. */\n readonly specularTexture?: Texture2D;\n /** Linear emissive colour. */\n readonly emissive?: readonly [number, number, number];\n /** The emissive texture. */\n readonly emissiveTexture?: Texture2D;\n /** The tangent-space normal map. */\n readonly normalTexture?: Texture2D;\n /** The opacity texture. */\n readonly opacityTexture?: Texture2D;\n /** Overall material alpha, 0 to 1. */\n readonly alpha?: number;\n /** The cutoff below which a fragment is discarded. `0` disables the alpha test. */\n readonly alphaCutoff?: number;\n /** Whether back faces are drawn. */\n readonly doubleSided?: boolean;\n /** Whether lighting is skipped entirely. */\n readonly unlit?: boolean;\n}\n\n/**\n * Builds a Lite PBR material from ignifx props.\n *\n * @param input - The declared properties.\n * @returns The material. It holds no GPU resource of its own; the textures it references do.\n *\n * @example\n * ```ts\n * const gold = createPbrMaterialFromProps({ baseColor: [1, 0.77, 0.34, 1], metallic: 1, roughness: 0.25 });\n * ```\n *\n * @internal\n */\nexport function createPbrMaterialFromProps(input: PbrMaterialInput): PbrMaterialProps {\n const props: Partial<PbrMaterialProps> = {};\n if (input.name !== undefined) {\n props.name = input.name;\n }\n if (input.baseColor !== undefined) {\n props.baseColorFactor = [input.baseColor[0], input.baseColor[1], input.baseColor[2], input.baseColor[3]];\n }\n if (input.baseColorTexture !== undefined) {\n props.baseColorTexture = input.baseColorTexture;\n }\n if (input.metallic !== undefined) {\n props.metallicFactor = input.metallic;\n }\n if (input.roughness !== undefined) {\n props.roughnessFactor = input.roughness;\n }\n if (input.metallicRoughnessTexture !== undefined) {\n props.ormTexture = input.metallicRoughnessTexture;\n }\n if (input.normalTexture !== undefined) {\n props.normalTexture = input.normalTexture;\n }\n if (input.normalScale !== undefined) {\n props.normalTextureScale = input.normalScale;\n }\n if (input.emissiveTexture !== undefined) {\n props.emissiveTexture = input.emissiveTexture;\n }\n if (input.occlusionTexture !== undefined) {\n props.occlusionTexture = input.occlusionTexture;\n }\n if (input.occlusionStrength !== undefined) {\n props.occlusionStrength = input.occlusionStrength;\n }\n if (input.alpha !== undefined) {\n props.alpha = input.alpha;\n }\n if (input.doubleSided !== undefined) {\n props.doubleSided = input.doubleSided;\n }\n if (input.environmentIntensity !== undefined) {\n props.environmentIntensity = input.environmentIntensity;\n }\n if (input.alphaMode === \"blend\") {\n props.alphaBlend = true;\n }\n const material = createPbrMaterial(props);\n if (input.alphaMode === \"mask\") {\n setPbrAlphaCutoff(material, input.alphaCutoff ?? DEFAULT_ALPHA_CUTOFF);\n }\n if (input.emissive !== undefined) {\n setPbrEmissive(material, [input.emissive[0], input.emissive[1], input.emissive[2]]);\n }\n if (input.unlit === true) {\n setPbrUnlit(material);\n }\n return material;\n}\n\n/**\n * Builds a Lite Standard material from ignifx props.\n *\n * @param input - The declared properties.\n * @returns The material.\n *\n * @internal\n */\nexport function createStandardMaterialFromProps(input: StandardMaterialInput): StandardMaterialProps {\n const material = createStandardMaterial();\n if (input.name !== undefined) {\n material.name = input.name;\n }\n if (input.diffuse !== undefined) {\n writeTriple(material.diffuseColor, input.diffuse);\n }\n if (input.specular !== undefined) {\n writeTriple(material.specularColor, input.specular);\n }\n if (input.emissive !== undefined) {\n writeTriple(material.emissiveColor, input.emissive);\n }\n if (input.specularPower !== undefined) {\n material.specularPower = input.specularPower;\n }\n if (input.alpha !== undefined) {\n material.alpha = input.alpha;\n }\n if (input.alphaCutoff !== undefined) {\n material.alphaCutOff = input.alphaCutoff;\n }\n if (input.doubleSided !== undefined) {\n material.backFaceCulling = !input.doubleSided;\n }\n if (input.unlit !== undefined) {\n material.disableLighting = input.unlit;\n }\n if (input.diffuseTexture !== undefined) {\n material.diffuseTexture = input.diffuseTexture;\n }\n if (input.specularTexture !== undefined) {\n setStandardSpecularTexture(material, input.specularTexture);\n }\n if (input.emissiveTexture !== undefined) {\n setStandardEmissiveTexture(material, input.emissiveTexture);\n }\n if (input.normalTexture !== undefined) {\n setStandardBumpTexture(material, input.normalTexture);\n }\n if (input.opacityTexture !== undefined) {\n setStandardOpacityTexture(material, input.opacityTexture);\n }\n return material;\n}\n\n/**\n * The material a `MeshRenderer` uses when it declares none: a neutral, fully rough dielectric.\n *\n * @returns A fresh material. Callers share one instance per app rather than one per renderer.\n *\n * @internal\n */\nexport function createDefaultMaterial(): PbrMaterialProps {\n return createPbrMaterialFromProps({\n name: \"ignifx:default\",\n baseColor: [1, 1, 1, 1],\n metallic: 0,\n roughness: 0.9,\n });\n}\n\n/**\n * Replaces a PBR material's linear base colour.\n *\n * @param material - The material to change.\n * @param r - The linear red component.\n * @param g - The linear green component.\n * @param b - The linear blue component.\n * @param a - The alpha component.\n *\n * @internal\n */\nexport function setPbrBaseColor(material: PbrMaterialProps, r: number, g: number, b: number, a: number): void {\n const factor = material.baseColorFactor;\n if (factor === undefined) {\n material.baseColorFactor = [r, g, b, a];\n } else {\n factor[0] = r;\n factor[1] = g;\n factor[2] = b;\n factor[3] = a;\n }\n markMaterialDirty(material);\n}\n\n/**\n * Replaces a PBR material's metallic and roughness factors.\n *\n * @param material - The material to change.\n * @param metallic - The metallic factor, 0 to 1.\n * @param roughness - The roughness factor, 0 to 1.\n *\n * @internal\n */\nexport function setPbrMetallicRoughness(material: PbrMaterialProps, metallic: number, roughness: number): void {\n material.metallicFactor = metallic;\n material.roughnessFactor = roughness;\n markMaterialDirty(material);\n}\n\n/**\n * Replaces a material's overall alpha.\n *\n * @param material - The PBR or Standard material to change.\n * @param alpha - The new alpha, 0 to 1.\n *\n * @internal\n */\nexport function setMaterialAlpha(material: PbrMaterialProps | StandardMaterialProps, alpha: number): void {\n material.alpha = alpha;\n markMaterialDirty(material);\n}\n\n/**\n * Marks a material's uniform block for re-upload on the next frame.\n *\n * @remarks\n * This is the cheap path and covers every scalar, vector, and colour edit. It does **not** cover\n * changes that alter the compiled feature set; those go through {@link rebuildMaterialPipelines}.\n *\n * @param material - The material that changed.\n *\n * @internal\n */\nexport function markMaterialDirty(material: Material): void {\n markMaterialUboDirty(material);\n}\n\n/**\n * Rebuilds the renderables of a material whose compiled feature set changed.\n *\n * @remarks\n * Needed after binding or clearing a texture, changing culling, or toggling a sub-feature\n * (`index.d.ts` 11133). `rebuildFrameGraph` is left off so a component can batch several material\n * edits and rebuild the frame graph once.\n *\n * @param scene - The scene the material renders in.\n * @param material - The material that changed.\n *\n * @internal\n */\nexport function rebuildMaterialPipelines(scene: SceneContext, material: Material): void {\n // Since 1.34 a PBR rebuild in a built scene finishes asynchronously, and Lite reports its failure\n // itself (`lib/material/material-rebuild.js`, `rebuildMaterial`), so nothing is left to await.\n void rebuildMaterial(scene, material);\n}\n\n/**\n * Installs automatic dirty tracking on a material, so property writes mark its uniform block\n * without an explicit {@link markMaterialDirty}.\n *\n * @remarks\n * Lite installs the tracker by rewriting the material's property descriptors, and the module that\n * does it is loaded lazily, so this is asynchronous (`index.d.ts` 4480,\n * `lib/material/observable-material.js`). Opt-in only: it costs an accessor call per write, which\n * the zero-allocation rules (coding standards §7) do not want on every material.\n *\n * @param material - The PBR or Standard material to track.\n * @returns A promise that resolves once the tracker is installed.\n *\n * @internal\n */\nexport function enableMaterialChangeTracking(material: PbrMaterialProps | StandardMaterialProps): Promise<void> {\n return enableMaterialTracking(material);\n}\n\n/**\n * Reports whether Lite will alpha-blend a material declared with this alpha mode.\n *\n * @param mode - The declared alpha mode.\n * @returns `true` for `\"blend\"`, `false` for `\"opaque\"` and `\"mask\"`.\n *\n * @internal\n */\nexport function isBlendedAlphaMode(mode: MaterialAlphaMode): boolean {\n switch (mode) {\n case \"opaque\":\n case \"mask\":\n return false;\n case \"blend\":\n return true;\n default:\n return assertNever(mode, \"material alpha mode\");\n }\n}\n\n/**\n * Writes three components into a Lite colour tuple in place.\n *\n * @param target - The tuple Lite owns.\n * @param source - The values to copy.\n */\nfunction writeTriple(target: [number, number, number], source: readonly [number, number, number]): void {\n target[0] = source[0];\n target[1] = source[1];\n target[2] = source[2];\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"material-myMbl9mW.js","names":[],"sources":["../src/lite/material.ts"],"sourcesContent":["import {\n createPbrMaterial,\n createStandardMaterial,\n enableMaterialTracking,\n markMaterialUboDirty,\n rebuildMaterial,\n setPbrAlphaCutoff,\n setPbrEmissive,\n setPbrUnlit,\n setStandardBumpTexture,\n setStandardEmissiveTexture,\n setStandardOpacityTexture,\n setStandardSpecularTexture,\n} from \"@babylonjs/lite\";\nimport { assertNever } from \"../errors/ignifx-error.js\";\nimport type { Material, PbrMaterialProps, SceneContext, StandardMaterialProps, Texture2D } from \"@babylonjs/lite\";\n\n/**\n * Material half of the Babylon Lite adapter (`docs/architecture/07-rendering.md` §2.6): the three\n * material kinds a `MaterialAsset` can produce, built from plain ignifx props.\n *\n * Everything here is `@internal`, and every colour that reaches it is **linear** — the sRGB decode\n * belongs to the asset layer.\n *\n * ## What a Lite material is (verified against `@babylonjs/lite@1.27.0`)\n *\n * - A material is plain data plus one private `_buildGroup` function; `createPbrMaterial` is\n * literally `{ ...props, _buildGroup, _uboVersion: 0 }` (`lib/material/pbr/pbr-material.js`), so\n * none of these factories touches the GPU and all of them run under the null engine.\n * - **The build group is a per-family singleton.** `getPbrGroupBuilder()`, `getStandardGroupBuilder()`\n * and `getShaderGroupBuilder()` each memoise one function for the whole process\n * (`lib/material/pbr/pbr-material.js`, `lib/material/standard/create-standard-material.js`,\n * `lib/material/shader/shader-material.js` line 123), and a scene keys its renderable groups by\n * that function (`lib/scene/scene-core.js`, `addToScene`). \"Material family\" in\n * `docs/architecture/07-rendering.md` §1.1 therefore means *pbr*, *standard*, *shader* or *node* —\n * **not** an individual material. Only node materials get a per-material builder\n * (`lib/material/node/node-material.js`). This is what makes {@link warmUpMaterialFamilies} in\n * `./gpu/warm-up.ts` cheap: one hidden mesh per family covers every material in it.\n * - Scalar and vector edits only need `markMaterialUboDirty` (`index.d.ts` 6974), which bumps\n * `_uboVersion`. Anything that changes the compiled feature set — binding or clearing a texture,\n * flipping `doubleSided`, changing culling — needs {@link rebuildMaterialPipelines}.\n *\n * ## The custom WGSL family lives elsewhere\n *\n * `createShaderMaterial` and the `setShader*` setters are in `./gpu/shader-material.ts`, not here:\n * this module is statically reachable from every app through the material asset layer, and Babylon\n * Lite exports one barrel, so a static import of the shader factory would put Lite's whole\n * shader-material pipeline in every entry chunk. That module is reached through a dynamic\n * `import()` instead (`docs/plan/2026-09-terrain-particles-shaders.md` §3.1, \"Bundle cost\").\n */\n\n/**\n * The Babylon Lite material a `MaterialAsset` owns, re-exported under an ignifx name\n * (`CONSTITUTION.md` §3.4, coding standards §4).\n *\n * @remarks\n * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.\n *\n * @public\n */\nexport type LiteMaterial = Material;\n\n/**\n * A Babylon Lite physically based material, re-exported under an ignifx name.\n *\n * @remarks\n * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.\n *\n * @public\n */\nexport type LitePbrMaterial = PbrMaterialProps;\n\n/**\n * A Babylon Lite Babylon-Standard material, re-exported under an ignifx name.\n *\n * @remarks\n * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.\n *\n * @public\n */\nexport type LiteStandardMaterial = StandardMaterialProps;\n\n/** glTF's default alpha cutoff, used when a `\"mask\"` material declares none. */\nconst DEFAULT_ALPHA_CUTOFF = 0.5;\n\n/**\n * How a material's alpha channel is interpreted, in glTF's vocabulary, in the order the inspector\n * lists them (`docs/architecture/07-rendering.md` §2.4).\n *\n * @public\n */\nexport const MATERIAL_ALPHA_MODES = [\"opaque\", \"mask\", \"blend\"] as const;\n\n/**\n * The union of the alpha modes a material can declare.\n *\n * @public\n */\nexport type MaterialAlphaMode = (typeof MATERIAL_ALPHA_MODES)[number];\n\n/**\n * The physically based material properties an ignifx `.material.json` declares\n * (`docs/architecture/06-serialization-and-scene-format.md` §6). Every field is optional; an\n * omitted field leaves Lite's own default in place.\n *\n * @internal\n */\nexport interface PbrMaterialInput {\n /** A human-readable name, used for glTF material overrides and diagnostics. */\n readonly name?: string;\n /** Linear base colour and alpha, multiplied with the base colour texture. */\n readonly baseColor?: readonly [number, number, number, number];\n /** The base colour texture. Load it with an sRGB format. */\n readonly baseColorTexture?: Texture2D;\n /** Metallic factor, 0 to 1. */\n readonly metallic?: number;\n /** Roughness factor, 0 to 1. */\n readonly roughness?: number;\n /** The packed occlusion/roughness/metallic texture (glTF `ORM`). */\n readonly metallicRoughnessTexture?: Texture2D;\n /** The tangent-space normal map. */\n readonly normalTexture?: Texture2D;\n /** Normal map strength. */\n readonly normalScale?: number;\n /** Linear emissive colour. */\n readonly emissive?: readonly [number, number, number];\n /** The emissive texture. */\n readonly emissiveTexture?: Texture2D;\n /** A separate occlusion texture, sampled on UV1 when the ORM texture is not used for it. */\n readonly occlusionTexture?: Texture2D;\n /** How strongly ambient occlusion darkens the surface, 0 to 1. */\n readonly occlusionStrength?: number;\n /** How the alpha channel is interpreted. */\n readonly alphaMode?: MaterialAlphaMode;\n /** The cutoff below which a `\"mask\"` material discards a fragment. */\n readonly alphaCutoff?: number;\n /** Overall material alpha, 0 to 1. */\n readonly alpha?: number;\n /** Whether back faces are drawn. */\n readonly doubleSided?: boolean;\n /** Whether lighting is skipped entirely. */\n readonly unlit?: boolean;\n /** How strongly the environment map contributes. */\n readonly environmentIntensity?: number;\n}\n\n/**\n * The Babylon-Standard material properties an ignifx `.material.json` declares, for the cheap\n * non-PBR path (`docs/architecture/07-rendering.md` §2.6).\n *\n * @internal\n */\nexport interface StandardMaterialInput {\n /** A human-readable name. */\n readonly name?: string;\n /** Linear diffuse colour. */\n readonly diffuse?: readonly [number, number, number];\n /** The diffuse texture. */\n readonly diffuseTexture?: Texture2D;\n /** Linear specular colour. */\n readonly specular?: readonly [number, number, number];\n /** Specular exponent; higher values give a tighter highlight. */\n readonly specularPower?: number;\n /** The specular texture. */\n readonly specularTexture?: Texture2D;\n /** Linear emissive colour. */\n readonly emissive?: readonly [number, number, number];\n /** The emissive texture. */\n readonly emissiveTexture?: Texture2D;\n /** The tangent-space normal map. */\n readonly normalTexture?: Texture2D;\n /** The opacity texture. */\n readonly opacityTexture?: Texture2D;\n /** Overall material alpha, 0 to 1. */\n readonly alpha?: number;\n /** The cutoff below which a fragment is discarded. `0` disables the alpha test. */\n readonly alphaCutoff?: number;\n /** Whether back faces are drawn. */\n readonly doubleSided?: boolean;\n /** Whether lighting is skipped entirely. */\n readonly unlit?: boolean;\n}\n\n/**\n * Builds a Lite PBR material from ignifx props.\n *\n * @param input - The declared properties.\n * @returns The material. It holds no GPU resource of its own; the textures it references do.\n *\n * @example\n * ```ts\n * const gold = createPbrMaterialFromProps({ baseColor: [1, 0.77, 0.34, 1], metallic: 1, roughness: 0.25 });\n * ```\n *\n * @internal\n */\nexport function createPbrMaterialFromProps(input: PbrMaterialInput): PbrMaterialProps {\n const props: Partial<PbrMaterialProps> = {};\n if (input.name !== undefined) {\n props.name = input.name;\n }\n if (input.baseColor !== undefined) {\n props.baseColorFactor = [input.baseColor[0], input.baseColor[1], input.baseColor[2], input.baseColor[3]];\n }\n if (input.baseColorTexture !== undefined) {\n props.baseColorTexture = input.baseColorTexture;\n }\n if (input.metallic !== undefined) {\n props.metallicFactor = input.metallic;\n }\n if (input.roughness !== undefined) {\n props.roughnessFactor = input.roughness;\n }\n if (input.metallicRoughnessTexture !== undefined) {\n props.ormTexture = input.metallicRoughnessTexture;\n }\n if (input.normalTexture !== undefined) {\n props.normalTexture = input.normalTexture;\n }\n if (input.normalScale !== undefined) {\n props.normalTextureScale = input.normalScale;\n }\n if (input.emissiveTexture !== undefined) {\n props.emissiveTexture = input.emissiveTexture;\n }\n if (input.occlusionTexture !== undefined) {\n props.occlusionTexture = input.occlusionTexture;\n }\n if (input.occlusionStrength !== undefined) {\n props.occlusionStrength = input.occlusionStrength;\n }\n if (input.alpha !== undefined) {\n props.alpha = input.alpha;\n }\n if (input.doubleSided !== undefined) {\n props.doubleSided = input.doubleSided;\n }\n if (input.environmentIntensity !== undefined) {\n props.environmentIntensity = input.environmentIntensity;\n }\n if (input.alphaMode === \"blend\") {\n props.alphaBlend = true;\n }\n const material = createPbrMaterial(props);\n if (input.alphaMode === \"mask\") {\n setPbrAlphaCutoff(material, input.alphaCutoff ?? DEFAULT_ALPHA_CUTOFF);\n }\n if (input.emissive !== undefined) {\n setPbrEmissive(material, [input.emissive[0], input.emissive[1], input.emissive[2]]);\n }\n if (input.unlit === true) {\n setPbrUnlit(material);\n }\n return material;\n}\n\n/**\n * Builds a Lite Standard material from ignifx props.\n *\n * @param input - The declared properties.\n * @returns The material.\n *\n * @internal\n */\nexport function createStandardMaterialFromProps(input: StandardMaterialInput): StandardMaterialProps {\n const material = createStandardMaterial();\n if (input.name !== undefined) {\n material.name = input.name;\n }\n if (input.diffuse !== undefined) {\n writeTriple(material.diffuseColor, input.diffuse);\n }\n if (input.specular !== undefined) {\n writeTriple(material.specularColor, input.specular);\n }\n if (input.emissive !== undefined) {\n writeTriple(material.emissiveColor, input.emissive);\n }\n if (input.specularPower !== undefined) {\n material.specularPower = input.specularPower;\n }\n if (input.alpha !== undefined) {\n material.alpha = input.alpha;\n }\n if (input.alphaCutoff !== undefined) {\n material.alphaCutOff = input.alphaCutoff;\n }\n if (input.doubleSided !== undefined) {\n material.backFaceCulling = !input.doubleSided;\n }\n if (input.unlit !== undefined) {\n material.disableLighting = input.unlit;\n }\n if (input.diffuseTexture !== undefined) {\n material.diffuseTexture = input.diffuseTexture;\n }\n if (input.specularTexture !== undefined) {\n setStandardSpecularTexture(material, input.specularTexture);\n }\n if (input.emissiveTexture !== undefined) {\n setStandardEmissiveTexture(material, input.emissiveTexture);\n }\n if (input.normalTexture !== undefined) {\n setStandardBumpTexture(material, input.normalTexture);\n }\n if (input.opacityTexture !== undefined) {\n setStandardOpacityTexture(material, input.opacityTexture);\n }\n return material;\n}\n\n/**\n * The material a `MeshRenderer` uses when it declares none: a neutral, fully rough dielectric.\n *\n * @returns A fresh material. Callers share one instance per app rather than one per renderer.\n *\n * @internal\n */\nexport function createDefaultMaterial(): PbrMaterialProps {\n return createPbrMaterialFromProps({\n name: \"ignifx:default\",\n baseColor: [1, 1, 1, 1],\n metallic: 0,\n roughness: 0.9,\n });\n}\n\n/**\n * Replaces a PBR material's linear base colour.\n *\n * @param material - The material to change.\n * @param r - The linear red component.\n * @param g - The linear green component.\n * @param b - The linear blue component.\n * @param a - The alpha component.\n *\n * @internal\n */\nexport function setPbrBaseColor(material: PbrMaterialProps, r: number, g: number, b: number, a: number): void {\n const factor = material.baseColorFactor;\n if (factor === undefined) {\n material.baseColorFactor = [r, g, b, a];\n } else {\n factor[0] = r;\n factor[1] = g;\n factor[2] = b;\n factor[3] = a;\n }\n markMaterialDirty(material);\n}\n\n/**\n * Replaces a PBR material's metallic and roughness factors.\n *\n * @param material - The material to change.\n * @param metallic - The metallic factor, 0 to 1.\n * @param roughness - The roughness factor, 0 to 1.\n *\n * @internal\n */\nexport function setPbrMetallicRoughness(material: PbrMaterialProps, metallic: number, roughness: number): void {\n material.metallicFactor = metallic;\n material.roughnessFactor = roughness;\n markMaterialDirty(material);\n}\n\n/**\n * Makes one PBR material's base colour, metallic, roughness and alpha factors (what\n * `MaterialAsset`'s setters write) equal another's, such as a renderer's lightmapped copy of a\n * shared material. Writes, and marks the copy dirty, only when something differs.\n *\n * @param from - The material to read.\n * @param to - The material to change.\n * @returns `true` when `to` changed.\n *\n * @internal\n */\nexport function syncPbrFactors(from: PbrMaterialProps, to: PbrMaterialProps): boolean {\n const color = from.baseColorFactor ?? [1, 1, 1, 1];\n const current = to.baseColorFactor ?? [1, 1, 1, 1];\n const metallic = from.metallicFactor ?? 1;\n const roughness = from.roughnessFactor ?? 1;\n const alpha = from.alpha ?? 1;\n if (\n color[0] === current[0] &&\n color[1] === current[1] &&\n color[2] === current[2] &&\n color[3] === current[3] &&\n metallic === (to.metallicFactor ?? 1) &&\n roughness === (to.roughnessFactor ?? 1) &&\n alpha === (to.alpha ?? 1)\n ) {\n return false;\n }\n setPbrBaseColor(to, color[0], color[1], color[2], color[3]);\n to.metallicFactor = metallic;\n to.roughnessFactor = roughness;\n to.alpha = alpha;\n markMaterialDirty(to);\n return true;\n}\n\n/**\n * Replaces a material's overall alpha.\n *\n * @param material - The PBR or Standard material to change.\n * @param alpha - The new alpha, 0 to 1.\n *\n * @internal\n */\nexport function setMaterialAlpha(material: PbrMaterialProps | StandardMaterialProps, alpha: number): void {\n material.alpha = alpha;\n markMaterialDirty(material);\n}\n\n/**\n * Marks a material's uniform block for re-upload on the next frame.\n *\n * @remarks\n * This is the cheap path and covers every scalar, vector, and colour edit. It does **not** cover\n * changes that alter the compiled feature set; those go through {@link rebuildMaterialPipelines}.\n *\n * @param material - The material that changed.\n *\n * @internal\n */\nexport function markMaterialDirty(material: Material): void {\n markMaterialUboDirty(material);\n}\n\n/**\n * Rebuilds the renderables of a material whose compiled feature set changed.\n *\n * @remarks\n * Needed after binding or clearing a texture, changing culling, or toggling a sub-feature\n * (`index.d.ts` 11133). `rebuildFrameGraph` is left off so a component can batch several material\n * edits and rebuild the frame graph once.\n *\n * @param scene - The scene the material renders in.\n * @param material - The material that changed.\n *\n * @internal\n */\nexport function rebuildMaterialPipelines(scene: SceneContext, material: Material): void {\n // Since 1.34 a PBR rebuild in a built scene finishes asynchronously, and Lite reports its failure\n // itself (`lib/material/material-rebuild.js`, `rebuildMaterial`), so nothing is left to await.\n void rebuildMaterial(scene, material);\n}\n\n/**\n * Installs automatic dirty tracking on a material, so property writes mark its uniform block\n * without an explicit {@link markMaterialDirty}.\n *\n * @remarks\n * Lite installs the tracker by rewriting the material's property descriptors, and the module that\n * does it is loaded lazily, so this is asynchronous (`index.d.ts` 4480,\n * `lib/material/observable-material.js`). Opt-in only: it costs an accessor call per write, which\n * the zero-allocation rules (coding standards §7) do not want on every material.\n *\n * @param material - The PBR or Standard material to track.\n * @returns A promise that resolves once the tracker is installed.\n *\n * @internal\n */\nexport function enableMaterialChangeTracking(material: PbrMaterialProps | StandardMaterialProps): Promise<void> {\n return enableMaterialTracking(material);\n}\n\n/**\n * Reports whether Lite will alpha-blend a material declared with this alpha mode.\n *\n * @param mode - The declared alpha mode.\n * @returns `true` for `\"blend\"`, `false` for `\"opaque\"` and `\"mask\"`.\n *\n * @internal\n */\nexport function isBlendedAlphaMode(mode: MaterialAlphaMode): boolean {\n switch (mode) {\n case \"opaque\":\n case \"mask\":\n return false;\n case \"blend\":\n return true;\n default:\n return assertNever(mode, \"material alpha mode\");\n }\n}\n\n/**\n * Writes three components into a Lite colour tuple in place.\n *\n * @param target - The tuple Lite owns.\n * @param source - The values to copy.\n */\nfunction writeTriple(target: [number, number, number], source: readonly [number, number, number]): void {\n target[0] = source[0];\n target[1] = source[1];\n target[2] = source[2];\n}\n"],"mappings":"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"}
@@ -1,4 +1,4 @@
1
- import { F as asJsonObject, I as setOwnJsonProperty } from "./prefab-overrides-DRP2DcnC.js";
1
+ import { F as asJsonObject, I as setOwnJsonProperty } from "./prefab-overrides-C2GsgOQc.js";
2
2
  //#region src/render/post-effect.ts
3
3
  /**
4
4
  * What a `PostProcessStack` needs to describe a custom `// @ignifx post` effect: its settings record,
@@ -126,4 +126,4 @@ function postEffectValuesCodec() {
126
126
  //#endregion
127
127
  export { postEffectValuesCodec as a, declaredTextureBinding as i, POST_EFFECT_FUNCTION as n, customEffect as r, POST_EFFECT_BUILTIN_UNIFORMS as t };
128
128
 
129
- //# sourceMappingURL=post-effect-CaiqDlhW.js.map
129
+ //# sourceMappingURL=post-effect-Cu3Enpz7.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"post-effect-CaiqDlhW.js","names":[],"sources":["../src/render/post-effect.ts"],"sourcesContent":["import { setOwnJsonProperty } from \"../schema/json.js\";\nimport { asJsonObject } from \"../serialization/json-view.js\";\nimport type { ShaderAsset } from \"./shader-asset.js\";\nimport type { ShaderTextureDeclaration, ShaderUniformType } from \"./shader-declaration.js\";\nimport type { TextureAsset } from \"./texture-asset.js\";\nimport type { AssetHandle } from \"../assets/types.js\";\nimport type { JsonValue } from \"../schema/json.js\";\nimport type { CustomFieldCodec } from \"../schema/types.js\";\n\n/**\n * What a `PostProcessStack` needs to describe a custom `// @ignifx post` effect: its settings record,\n * the uniforms every effect gets for free, and the schema codec its `values` round-trip through\n * (`docs/plan/2026-09-terrain-particles-shaders.md` §3.3).\n *\n * `PostProcessStack` is in every game's static graph, so the WGSL generator and the uniform layout\n * live in `./post-effect-compiler.ts`, which the `.wgsl` loader pulls in only for a `post` file.\n */\n\n/**\n * The name a `// @ignifx post` file gives its fragment function.\n *\n * @public\n */\nexport const POST_EFFECT_FUNCTION = \"mainFragment\";\n\n/**\n * The uniforms every post effect's `shaderUniforms` block carries before the file's own, in this\n * order.\n *\n * @remarks\n * `screenSize` is in backing-store pixels — `canvas.width`/`canvas.height` — like everything else\n * the engine reports (`docs/architecture/07-rendering.md` §3). The three clocks are the app's, so\n * `time` freezes under `app.pause()` and `unscaledTime` does not.\n *\n * @public\n */\nexport const POST_EFFECT_BUILTIN_UNIFORMS: readonly { readonly name: string; readonly type: ShaderUniformType }[] =\n Object.freeze([\n { name: \"screenSize\", type: \"vec2<f32>\" },\n { name: \"time\", type: \"f32\" },\n { name: \"unscaledTime\", type: \"f32\" },\n { name: \"deltaTime\", type: \"f32\" },\n ]);\n\n/**\n * One custom effect on a `PostProcessStack` (`docs/architecture/07-rendering.md` §2.7).\n *\n * @public\n */\nexport interface CustomEffectSettings {\n /** The `// @ignifx post` shader; `null` records nothing. */\n shader: AssetHandle<ShaderAsset> | null;\n /** Whether the effect runs. */\n enabled: boolean;\n /** Position in the chain; lower runs first, alongside bloom's and SMAA's `order`. */\n order: number;\n /** Overrides of the file's declared uniform defaults, by declared name. */\n values: Record<string, number | readonly number[]>;\n /** Textures for the file's declared samplers, by declared name. */\n textures: Record<string, AssetHandle<TextureAsset> | null>;\n}\n\n/**\n * What {@link customEffect} accepts: a shader and whichever fields differ from the defaults.\n *\n * @public\n */\nexport interface CustomEffectInit {\n /** The `// @ignifx post` shader. */\n readonly shader: AssetHandle<ShaderAsset> | null;\n /** Whether the effect runs. Defaults to `true`. */\n readonly enabled?: boolean;\n /** Position in the chain. Defaults to `10`, which is after the built-ins' defaults. */\n readonly order?: number;\n /** Overrides of the file's declared uniform defaults. */\n readonly values?: Readonly<Record<string, number | readonly number[]>>;\n /** Textures for the file's declared samplers. */\n readonly textures?: Readonly<Record<string, AssetHandle<TextureAsset> | null>>;\n}\n\n/**\n * Fills in a custom effect's defaults, so a caller names only what it means to set.\n *\n * @param init - The shader and the fields to set.\n * @returns A complete settings record, ready to push onto `PostProcessStack.custom`.\n *\n * @example\n * ```ts\n * stack.custom.push(customEffect({ shader: vignette, order: 5, values: { amount: 0.6 } }));\n * ```\n *\n * @public\n */\nexport function customEffect(init: CustomEffectInit): CustomEffectSettings {\n return {\n shader: init.shader,\n enabled: init.enabled ?? true,\n order: init.order ?? 10,\n values: { ...init.values },\n textures: { ...init.textures },\n };\n}\n\n/**\n * The binding index of the chain's current colour.\n *\n * @internal\n */\nexport const INPUT_TEXTURE_BINDING = 1;\n\n/**\n * The binding index of the chain's current colour sampler.\n *\n * @internal\n */\nexport const INPUT_SAMPLER_BINDING = 2;\n\n/** The first binding index a declared texture takes. */\nconst FIRST_DECLARED_BINDING = 3;\n\n/**\n * The binding index of one declared texture, and of its sampler.\n *\n * @param index - The texture's index in declaration order.\n * @returns The texture's binding; the sampler is one higher.\n *\n * @internal\n */\nexport function declaredTextureBinding(index: number): number {\n return FIRST_DECLARED_BINDING + index * 2;\n}\n\n/**\n * One member of a compiled effect's uniform struct, with the byte offset the generated WGSL puts it\n * at.\n *\n * @internal\n */\nexport interface PostEffectUniformField {\n /** The WGSL member name. */\n readonly name: string;\n /** The WGSL type. */\n readonly type: ShaderUniformType;\n /** How many floats the value holds. */\n readonly components: number;\n /** Where the member starts in the uniform buffer, in bytes. */\n readonly byteOffset: number;\n}\n\n/**\n * A `// @ignifx post` file compiled into what Babylon Lite's fullscreen effect path needs.\n *\n * @internal\n */\nexport interface CompiledPostEffect {\n /** The shader's address, for diagnostics and for the chain's identity. */\n readonly address: string;\n /** The whole fragment module: the bindings, the generated structs, the file, and the entry point. */\n readonly fragmentWGSL: string;\n /** The uniform members, built-ins first, in struct order. */\n readonly uniforms: readonly PostEffectUniformField[];\n /** The members by name, for a value write. */\n readonly byName: ReadonlyMap<string, PostEffectUniformField>;\n /** How large the uniform buffer has to be. */\n readonly uniformByteLength: number;\n /** The file's declared samplers, in declaration order. */\n readonly textures: readonly ShaderTextureDeclaration[];\n}\n\n/**\n * The codec that round-trips a custom effect's `values` record through a scene file.\n *\n * @remarks\n * A schema field cannot describe these: the uniforms are declared by the `.wgsl`, so `map(f32)`\n * would drop every vector and colour uniform and `map(vec4)` would write `amount: 0.6` as four\n * floats. The codec round-trips exactly what a shader file allows — a number or an array of numbers.\n *\n * @returns The codec, for a `custom()` field.\n *\n * @internal\n */\nexport function postEffectValuesCodec(): CustomFieldCodec<Record<string, number | readonly number[]>> {\n return {\n createDefault(): Record<string, number | readonly number[]> {\n return {};\n },\n serialize(value: Record<string, number | readonly number[]>): JsonValue {\n const json: Record<string, JsonValue> = {};\n // Lexicographic, so two saves of the same state are byte-identical\n // (`docs/architecture/06-serialization-and-scene-format.md` §1).\n for (const name of Object.keys(value).toSorted()) {\n const entry = value[name];\n setOwnJsonProperty(json, name, typeof entry === \"number\" ? entry : [...(entry ?? [])]);\n }\n return json;\n },\n deserialize(json: JsonValue): Record<string, number | readonly number[]> {\n const value: Record<string, number | readonly number[]> = {};\n const object = asJsonObject(json);\n if (object === null) {\n return value;\n }\n for (const name of Object.keys(object)) {\n const entry = object[name];\n // Defined, not assigned: a `__proto__` key from a file stays a name instead of a prototype.\n if (typeof entry === \"number\") {\n setOwnJsonProperty(value, name, entry);\n } else if (Array.isArray(entry)) {\n setOwnJsonProperty(\n value,\n name,\n entry.map((component) => (typeof component === \"number\" ? component : 0)),\n );\n }\n }\n return value;\n },\n jsonSchema: {\n type: \"object\",\n additionalProperties: {\n oneOf: [{ type: \"number\" }, { type: \"array\", items: { type: \"number\" } }],\n },\n },\n };\n}\n"],"mappings":";;;;;;;;;;;;;;;AAuBA,MAAa,uBAAuB;;;;;;;;;;;;AAapC,MAAa,+BACX,OAAO,OAAO;CACZ;EAAE,MAAM;EAAc,MAAM;CAAY;CACxC;EAAE,MAAM;EAAQ,MAAM;CAAM;CAC5B;EAAE,MAAM;EAAgB,MAAM;CAAM;CACpC;EAAE,MAAM;EAAa,MAAM;CAAM;AACnC,CAAC;;;;;;;;;;;;;;AAmDH,SAAgB,aAAa,MAA8C;CACzE,OAAO;EACL,QAAQ,KAAK;EACb,SAAS,KAAK,WAAW;EACzB,OAAO,KAAK,SAAS;EACrB,QAAQ,EAAE,GAAG,KAAK,OAAO;EACzB,UAAU,EAAE,GAAG,KAAK,SAAS;CAC/B;AACF;;AAiBA,MAAM,yBAAyB;;;;;;;;;AAU/B,SAAgB,uBAAuB,OAAuB;CAC5D,OAAO,yBAAyB,QAAQ;AAC1C;;;;;;;;;;;;;AAmDA,SAAgB,wBAAsF;CACpG,OAAO;EACL,gBAA4D;GAC1D,OAAO,CAAC;EACV;EACA,UAAU,OAA8D;GACtE,MAAM,OAAkC,CAAC;GAGzC,KAAK,MAAM,QAAQ,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,GAAG;IAChD,MAAM,QAAQ,MAAM;IACpB,mBAAmB,MAAM,MAAM,OAAO,UAAU,WAAW,QAAQ,CAAC,GAAI,SAAS,CAAC,CAAE,CAAC;GACvF;GACA,OAAO;EACT;EACA,YAAY,MAA6D;GACvE,MAAM,QAAoD,CAAC;GAC3D,MAAM,SAAS,aAAa,IAAI;GAChC,IAAI,WAAW,MACb,OAAO;GAET,KAAK,MAAM,QAAQ,OAAO,KAAK,MAAM,GAAG;IACtC,MAAM,QAAQ,OAAO;IAErB,IAAI,OAAO,UAAU,UACnB,mBAAmB,OAAO,MAAM,KAAK;SAChC,IAAI,MAAM,QAAQ,KAAK,GAC5B,mBACE,OACA,MACA,MAAM,KAAK,cAAe,OAAO,cAAc,WAAW,YAAY,CAAE,CAC1E;GAEJ;GACA,OAAO;EACT;EACA,YAAY;GACV,MAAM;GACN,sBAAsB,EACpB,OAAO,CAAC,EAAE,MAAM,SAAS,GAAG;IAAE,MAAM;IAAS,OAAO,EAAE,MAAM,SAAS;GAAE,CAAC,EAC1E;EACF;CACF;AACF"}
1
+ {"version":3,"file":"post-effect-Cu3Enpz7.js","names":[],"sources":["../src/render/post-effect.ts"],"sourcesContent":["import { setOwnJsonProperty } from \"../schema/json.js\";\nimport { asJsonObject } from \"../serialization/json-view.js\";\nimport type { ShaderAsset } from \"./shader-asset.js\";\nimport type { ShaderTextureDeclaration, ShaderUniformType } from \"./shader-declaration.js\";\nimport type { TextureAsset } from \"./texture-asset.js\";\nimport type { AssetHandle } from \"../assets/types.js\";\nimport type { JsonValue } from \"../schema/json.js\";\nimport type { CustomFieldCodec } from \"../schema/types.js\";\n\n/**\n * What a `PostProcessStack` needs to describe a custom `// @ignifx post` effect: its settings record,\n * the uniforms every effect gets for free, and the schema codec its `values` round-trip through\n * (`docs/plan/2026-09-terrain-particles-shaders.md` §3.3).\n *\n * `PostProcessStack` is in every game's static graph, so the WGSL generator and the uniform layout\n * live in `./post-effect-compiler.ts`, which the `.wgsl` loader pulls in only for a `post` file.\n */\n\n/**\n * The name a `// @ignifx post` file gives its fragment function.\n *\n * @public\n */\nexport const POST_EFFECT_FUNCTION = \"mainFragment\";\n\n/**\n * The uniforms every post effect's `shaderUniforms` block carries before the file's own, in this\n * order.\n *\n * @remarks\n * `screenSize` is in backing-store pixels — `canvas.width`/`canvas.height` — like everything else\n * the engine reports (`docs/architecture/07-rendering.md` §3). The three clocks are the app's, so\n * `time` freezes under `app.pause()` and `unscaledTime` does not.\n *\n * @public\n */\nexport const POST_EFFECT_BUILTIN_UNIFORMS: readonly { readonly name: string; readonly type: ShaderUniformType }[] =\n Object.freeze([\n { name: \"screenSize\", type: \"vec2<f32>\" },\n { name: \"time\", type: \"f32\" },\n { name: \"unscaledTime\", type: \"f32\" },\n { name: \"deltaTime\", type: \"f32\" },\n ]);\n\n/**\n * One custom effect on a `PostProcessStack` (`docs/architecture/07-rendering.md` §2.7).\n *\n * @public\n */\nexport interface CustomEffectSettings {\n /** The `// @ignifx post` shader; `null` records nothing. */\n shader: AssetHandle<ShaderAsset> | null;\n /** Whether the effect runs. */\n enabled: boolean;\n /** Position in the chain; lower runs first, alongside bloom's and SMAA's `order`. */\n order: number;\n /** Overrides of the file's declared uniform defaults, by declared name. */\n values: Record<string, number | readonly number[]>;\n /** Textures for the file's declared samplers, by declared name. */\n textures: Record<string, AssetHandle<TextureAsset> | null>;\n}\n\n/**\n * What {@link customEffect} accepts: a shader and whichever fields differ from the defaults.\n *\n * @public\n */\nexport interface CustomEffectInit {\n /** The `// @ignifx post` shader. */\n readonly shader: AssetHandle<ShaderAsset> | null;\n /** Whether the effect runs. Defaults to `true`. */\n readonly enabled?: boolean;\n /** Position in the chain. Defaults to `10`, which is after the built-ins' defaults. */\n readonly order?: number;\n /** Overrides of the file's declared uniform defaults. */\n readonly values?: Readonly<Record<string, number | readonly number[]>>;\n /** Textures for the file's declared samplers. */\n readonly textures?: Readonly<Record<string, AssetHandle<TextureAsset> | null>>;\n}\n\n/**\n * Fills in a custom effect's defaults, so a caller names only what it means to set.\n *\n * @param init - The shader and the fields to set.\n * @returns A complete settings record, ready to push onto `PostProcessStack.custom`.\n *\n * @example\n * ```ts\n * stack.custom.push(customEffect({ shader: vignette, order: 5, values: { amount: 0.6 } }));\n * ```\n *\n * @public\n */\nexport function customEffect(init: CustomEffectInit): CustomEffectSettings {\n return {\n shader: init.shader,\n enabled: init.enabled ?? true,\n order: init.order ?? 10,\n values: { ...init.values },\n textures: { ...init.textures },\n };\n}\n\n/**\n * The binding index of the chain's current colour.\n *\n * @internal\n */\nexport const INPUT_TEXTURE_BINDING = 1;\n\n/**\n * The binding index of the chain's current colour sampler.\n *\n * @internal\n */\nexport const INPUT_SAMPLER_BINDING = 2;\n\n/** The first binding index a declared texture takes. */\nconst FIRST_DECLARED_BINDING = 3;\n\n/**\n * The binding index of one declared texture, and of its sampler.\n *\n * @param index - The texture's index in declaration order.\n * @returns The texture's binding; the sampler is one higher.\n *\n * @internal\n */\nexport function declaredTextureBinding(index: number): number {\n return FIRST_DECLARED_BINDING + index * 2;\n}\n\n/**\n * One member of a compiled effect's uniform struct, with the byte offset the generated WGSL puts it\n * at.\n *\n * @internal\n */\nexport interface PostEffectUniformField {\n /** The WGSL member name. */\n readonly name: string;\n /** The WGSL type. */\n readonly type: ShaderUniformType;\n /** How many floats the value holds. */\n readonly components: number;\n /** Where the member starts in the uniform buffer, in bytes. */\n readonly byteOffset: number;\n}\n\n/**\n * A `// @ignifx post` file compiled into what Babylon Lite's fullscreen effect path needs.\n *\n * @internal\n */\nexport interface CompiledPostEffect {\n /** The shader's address, for diagnostics and for the chain's identity. */\n readonly address: string;\n /** The whole fragment module: the bindings, the generated structs, the file, and the entry point. */\n readonly fragmentWGSL: string;\n /** The uniform members, built-ins first, in struct order. */\n readonly uniforms: readonly PostEffectUniformField[];\n /** The members by name, for a value write. */\n readonly byName: ReadonlyMap<string, PostEffectUniformField>;\n /** How large the uniform buffer has to be. */\n readonly uniformByteLength: number;\n /** The file's declared samplers, in declaration order. */\n readonly textures: readonly ShaderTextureDeclaration[];\n}\n\n/**\n * The codec that round-trips a custom effect's `values` record through a scene file.\n *\n * @remarks\n * A schema field cannot describe these: the uniforms are declared by the `.wgsl`, so `map(f32)`\n * would drop every vector and colour uniform and `map(vec4)` would write `amount: 0.6` as four\n * floats. The codec round-trips exactly what a shader file allows — a number or an array of numbers.\n *\n * @returns The codec, for a `custom()` field.\n *\n * @internal\n */\nexport function postEffectValuesCodec(): CustomFieldCodec<Record<string, number | readonly number[]>> {\n return {\n createDefault(): Record<string, number | readonly number[]> {\n return {};\n },\n serialize(value: Record<string, number | readonly number[]>): JsonValue {\n const json: Record<string, JsonValue> = {};\n // Lexicographic, so two saves of the same state are byte-identical\n // (`docs/architecture/06-serialization-and-scene-format.md` §1).\n for (const name of Object.keys(value).toSorted()) {\n const entry = value[name];\n setOwnJsonProperty(json, name, typeof entry === \"number\" ? entry : [...(entry ?? [])]);\n }\n return json;\n },\n deserialize(json: JsonValue): Record<string, number | readonly number[]> {\n const value: Record<string, number | readonly number[]> = {};\n const object = asJsonObject(json);\n if (object === null) {\n return value;\n }\n for (const name of Object.keys(object)) {\n const entry = object[name];\n // Defined, not assigned: a `__proto__` key from a file stays a name instead of a prototype.\n if (typeof entry === \"number\") {\n setOwnJsonProperty(value, name, entry);\n } else if (Array.isArray(entry)) {\n setOwnJsonProperty(\n value,\n name,\n entry.map((component) => (typeof component === \"number\" ? component : 0)),\n );\n }\n }\n return value;\n },\n jsonSchema: {\n type: \"object\",\n additionalProperties: {\n oneOf: [{ type: \"number\" }, { type: \"array\", items: { type: \"number\" } }],\n },\n },\n };\n}\n"],"mappings":";;;;;;;;;;;;;;;AAuBA,MAAa,uBAAuB;;;;;;;;;;;;AAapC,MAAa,+BACX,OAAO,OAAO;CACZ;EAAE,MAAM;EAAc,MAAM;CAAY;CACxC;EAAE,MAAM;EAAQ,MAAM;CAAM;CAC5B;EAAE,MAAM;EAAgB,MAAM;CAAM;CACpC;EAAE,MAAM;EAAa,MAAM;CAAM;AACnC,CAAC;;;;;;;;;;;;;;AAmDH,SAAgB,aAAa,MAA8C;CACzE,OAAO;EACL,QAAQ,KAAK;EACb,SAAS,KAAK,WAAW;EACzB,OAAO,KAAK,SAAS;EACrB,QAAQ,EAAE,GAAG,KAAK,OAAO;EACzB,UAAU,EAAE,GAAG,KAAK,SAAS;CAC/B;AACF;;AAiBA,MAAM,yBAAyB;;;;;;;;;AAU/B,SAAgB,uBAAuB,OAAuB;CAC5D,OAAO,yBAAyB,QAAQ;AAC1C;;;;;;;;;;;;;AAmDA,SAAgB,wBAAsF;CACpG,OAAO;EACL,gBAA4D;GAC1D,OAAO,CAAC;EACV;EACA,UAAU,OAA8D;GACtE,MAAM,OAAkC,CAAC;GAGzC,KAAK,MAAM,QAAQ,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,GAAG;IAChD,MAAM,QAAQ,MAAM;IACpB,mBAAmB,MAAM,MAAM,OAAO,UAAU,WAAW,QAAQ,CAAC,GAAI,SAAS,CAAC,CAAE,CAAC;GACvF;GACA,OAAO;EACT;EACA,YAAY,MAA6D;GACvE,MAAM,QAAoD,CAAC;GAC3D,MAAM,SAAS,aAAa,IAAI;GAChC,IAAI,WAAW,MACb,OAAO;GAET,KAAK,MAAM,QAAQ,OAAO,KAAK,MAAM,GAAG;IACtC,MAAM,QAAQ,OAAO;IAErB,IAAI,OAAO,UAAU,UACnB,mBAAmB,OAAO,MAAM,KAAK;SAChC,IAAI,MAAM,QAAQ,KAAK,GAC5B,mBACE,OACA,MACA,MAAM,KAAK,cAAe,OAAO,cAAc,WAAW,YAAY,CAAE,CAC1E;GAEJ;GACA,OAAO;EACT;EACA,YAAY;GACV,MAAM;GACN,sBAAsB,EACpB,OAAO,CAAC,EAAE,MAAM,SAAS,GAAG;IAAE,MAAM;IAAS,OAAO,EAAE,MAAM,SAAS;GAAE,CAAC,EAC1E;EACF;CACF;AACF"}
@@ -1,5 +1,5 @@
1
1
  import { n as assertNever, o as CoreErrorCode, t as IgnifxError } from "./ignifx-error-DwIZKxA2.js";
2
- import { i as declaredTextureBinding, n as POST_EFFECT_FUNCTION, t as POST_EFFECT_BUILTIN_UNIFORMS } from "./post-effect-CaiqDlhW.js";
2
+ import { i as declaredTextureBinding, n as POST_EFFECT_FUNCTION, t as POST_EFFECT_BUILTIN_UNIFORMS } from "./post-effect-Cu3Enpz7.js";
3
3
  //#region src/render/post-effect-compiler.ts
4
4
  /**
5
5
  * Turns a `// @ignifx post` file into the fragment module and uniform layout Babylon Lite's
@@ -308,4 +308,4 @@ function isBuiltinUniformName(name) {
308
308
  //#endregion
309
309
  export { compilePostEffect, compiledPostEffect, writePostEffectValues };
310
310
 
311
- //# sourceMappingURL=post-effect-compiler-jSvOVe0U.js.map
311
+ //# sourceMappingURL=post-effect-compiler-cCq9lcHt.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"post-effect-compiler-jSvOVe0U.js","names":[],"sources":["../src/render/post-effect-compiler.ts"],"sourcesContent":["import { CoreErrorCode } from \"../errors/error-codes.js\";\nimport { assertNever, IgnifxError } from \"../errors/ignifx-error.js\";\nimport {\n declaredTextureBinding,\n INPUT_SAMPLER_BINDING,\n INPUT_TEXTURE_BINDING,\n POST_EFFECT_BUILTIN_UNIFORMS,\n POST_EFFECT_FUNCTION,\n} from \"./post-effect.js\";\nimport type { CompiledPostEffect, PostEffectUniformField } from \"./post-effect.js\";\nimport type { ShaderAsset } from \"./shader-asset.js\";\nimport type { ShaderUniformType } from \"./shader-declaration.js\";\n\n/**\n * Turns a `// @ignifx post` file into the fragment module and uniform layout Babylon Lite's\n * fullscreen-effect path needs (`docs/plan/2026-09-terrain-particles-shaders.md` §3.3).\n *\n * `mainFragment` is a plain function, not an entry point: Lite hard-codes the entry-point names\n * `effectFullscreenVertex` and `effectFragment` (`lib/effect/effect-renderer.js` 7, 258-260), so the\n * entry point is generated here and forwards to it. `createEffectWrapper` takes a byte length and a\n * raw writer and computes no offsets, so the struct's member offsets are worked out here from WGSL's\n * own alignment rules and kept in step with the generated struct.\n *\n * Everything in this module is device-free and deterministic, so it is asserted in Node. It is\n * reached through `./post-effect-support.ts` so a game with no custom post effect never loads it.\n */\n\n/**\n * Compiles a `// @ignifx post` file into a full fragment module and a uniform layout.\n *\n * @remarks\n * Device-free and deterministic, so the whole thing is unit-testable: the result is a WGSL string\n * and a set of byte offsets. It is memoised per shader asset by {@link compiledPostEffect}, because\n * the chain asks for it on every rebuild.\n *\n * @param shader - The loaded shader asset.\n * @returns The compiled effect.\n * @throws IgnifxError with code `IGX-0709` when the file is not a `post` one, or `IGX-0723` when it\n * declares no `mainFragment` function.\n *\n * @example\n * ```ts\n * const compiled = compilePostEffect(vignette.value);\n * compiled.byName.get(\"amount\")?.byteOffset; // 20, right after the four built-ins\n * ```\n *\n * @internal\n */\nexport function compilePostEffect(shader: ShaderAsset): CompiledPostEffect {\n if (shader.declaration.kind !== \"post\") {\n throw new IgnifxError(\n CoreErrorCode.invalidAssetFile,\n `${shader.address} declares @ignifx ${shader.declaration.kind}, not @ignifx post.`,\n {\n context: { file: shader.address, format: \"@ignifx post\", kind: shader.declaration.kind },\n hint: \"A PostProcessStack custom effect takes a .post.wgsl file whose pragma is @ignifx post.\",\n },\n );\n }\n if (!new RegExp(`\\\\bfn\\\\s+${POST_EFFECT_FUNCTION}\\\\s*\\\\(`, \"u\").test(shader.source)) {\n throw new IgnifxError(\n CoreErrorCode.surfaceHookMissing,\n `${shader.address} declares no ${POST_EFFECT_FUNCTION} function.`,\n {\n context: { asset: shader.address, hook: POST_EFFECT_FUNCTION },\n hint: `Add fn ${POST_EFFECT_FUNCTION}(in: PostInput) -> vec4<f32>; the @fragment entry point is generated.`,\n },\n );\n }\n const declared = shader.declaration.uniforms.filter((uniform) => !isBuiltinUniformName(uniform.name));\n const layout = layOutUniforms([\n ...POST_EFFECT_BUILTIN_UNIFORMS,\n ...declared.map((uniform) => ({ name: uniform.name, type: uniform.type })),\n ]);\n const byName = new Map<string, PostEffectUniformField>();\n for (const field of layout.fields) {\n byName.set(field.name, field);\n }\n return {\n address: shader.address,\n fragmentWGSL: buildFragmentModule(shader, layout.fields),\n uniforms: layout.fields,\n byName,\n uniformByteLength: layout.byteLength,\n textures: shader.declaration.textures,\n };\n}\n\n/** The compiled form of each shader asset, so a chain rebuild recompiles nothing. */\nlet compiled: WeakMap<ShaderAsset, CompiledPostEffect> | null = null;\n\n/**\n * The compiled form of a post-effect shader, compiled once per asset.\n *\n * @remarks\n * Keyed on the `ShaderAsset` itself, so a hot reload — which replaces the asset object — recompiles\n * for free.\n *\n * @param shader - The loaded shader asset.\n * @returns The compiled effect.\n * @throws IgnifxError as {@link compilePostEffect} documents.\n *\n * @internal\n */\nexport function compiledPostEffect(shader: ShaderAsset): CompiledPostEffect {\n const cache = (compiled ??= new WeakMap<ShaderAsset, CompiledPostEffect>());\n const hit = cache.get(shader);\n if (hit !== undefined) {\n return hit;\n }\n const built = compilePostEffect(shader);\n cache.set(shader, built);\n return built;\n}\n\n/**\n * Writes an effect's current values into the bytes its uniform buffer takes.\n *\n * @remarks\n * The built-in clocks and `screenSize` are written by the caller through the same `out` buffer, so\n * this only fills in the declared members: the declaration's default first, then the settings'\n * override. Unknown names are refused, which is what makes a typo in a `.scene.json` visible.\n *\n * @param effect - The compiled effect.\n * @param shader - The shader, for its declared defaults.\n * @param values - The overrides.\n * @param out - The uniform bytes, at least `effect.uniformByteLength` long.\n * @throws IgnifxError with code `IGX-0712` for an undeclared name, or `IGX-0713` for a wrongly\n * shaped value.\n *\n * @internal\n */\nexport function writePostEffectValues(\n effect: CompiledPostEffect,\n shader: ShaderAsset,\n values: Readonly<Record<string, number | readonly number[]>>,\n out: Float32Array,\n): void {\n for (const uniform of shader.declaration.uniforms) {\n const field = effect.byName.get(uniform.name);\n if (field === undefined) {\n continue;\n }\n writeField(field, uniform.defaultValue, effect.address, out);\n }\n // `for…in` rather than `Object.keys`: the chain calls this every frame for every recorded effect\n // and a key array per effect per frame is per-frame allocation (coding standards §7).\n for (const name in values) {\n if (!Object.hasOwn(values, name)) {\n continue;\n }\n const field = effect.byName.get(name);\n const value = values[name];\n if (value === undefined) {\n continue;\n }\n if (field === undefined || isBuiltinUniformName(name)) {\n throw new IgnifxError(\n CoreErrorCode.unknownShaderBinding,\n `${effect.address} declares no uniform named ${name}.`,\n {\n context: { material: effect.address, asset: effect.address, name },\n hint: `It declares ${[...effect.byName.keys()].join(\", \")}.`,\n },\n );\n }\n writeField(field, value, effect.address, out);\n }\n}\n\n/** The result of laying out a uniform struct. */\ninterface UniformLayout {\n /** The members, in struct order. */\n readonly fields: readonly PostEffectUniformField[];\n /** The struct's size, in bytes. */\n readonly byteLength: number;\n}\n\n/**\n * Computes the byte offsets WGSL gives a struct of these members, in this order.\n *\n * @remarks\n * The rules are the WGSL specification's: a member's offset is its predecessor's end rounded up to\n * the member's alignment, and the struct's size is the last member's end rounded up to the struct's\n * alignment — the largest member alignment, and in the **uniform** address space never less than\n * 16. `vec3<f32>` is the one that catches people out: 16-aligned, 12 wide (plan §3.4).\n *\n * @param members - The members, in declaration order.\n * @returns The layout.\n */\nfunction layOutUniforms(\n members: readonly { readonly name: string; readonly type: ShaderUniformType }[],\n): UniformLayout {\n const fields: PostEffectUniformField[] = [];\n let offset = 0;\n // WGSL's uniform address space rounds a struct's alignment up to a multiple of 16, so the block's\n // size is always a multiple of 16 whatever its members are.\n let structAlignment = 16;\n for (const member of members) {\n const alignment = typeAlignment(member.type);\n const size = typeSize(member.type);\n structAlignment = Math.max(structAlignment, alignment);\n offset = roundUp(offset, alignment);\n fields.push({\n name: member.name,\n type: member.type,\n components: componentCount(member.type),\n byteOffset: offset,\n });\n offset += size;\n }\n return { fields, byteLength: roundUp(offset, structAlignment) };\n}\n\n/**\n * A WGSL type's alignment in the uniform address space, in bytes.\n *\n * @param type - The type.\n * @returns The alignment.\n */\nfunction typeAlignment(type: ShaderUniformType): number {\n switch (type) {\n case \"vec2<f32>\": {\n return 8;\n }\n case \"vec3<f32>\":\n case \"vec4<f32>\":\n case \"mat4x4<f32>\": {\n return 16;\n }\n case \"f32\":\n case \"u32\":\n case \"i32\": {\n return 4;\n }\n default: {\n return assertNever(type, \"shader uniform type\");\n }\n }\n}\n\n/**\n * A WGSL type's size, in bytes.\n *\n * @param type - The type.\n * @returns The size.\n */\nfunction typeSize(type: ShaderUniformType): number {\n switch (type) {\n case \"vec2<f32>\": {\n return 8;\n }\n case \"vec3<f32>\": {\n return 12;\n }\n case \"vec4<f32>\": {\n return 16;\n }\n case \"mat4x4<f32>\": {\n return 64;\n }\n case \"f32\":\n case \"u32\":\n case \"i32\": {\n return 4;\n }\n default: {\n return assertNever(type, \"shader uniform type\");\n }\n }\n}\n\n/**\n * How many floats one uniform of a declared type occupies.\n *\n * @remarks\n * A private copy of `material-plugin.ts`'s `uniformComponentCount`. `PostProcessStack` is in every\n * game's static graph, and importing it from there would drag `defineMaterialPlugin` and the\n * reserved-name table into a bundle that draws no custom shader at all.\n *\n * @param type - The declared WGSL type.\n * @returns The component count: 1, 2, 3, 4, or 16.\n */\nfunction componentCount(type: ShaderUniformType): number {\n switch (type) {\n case \"vec2<f32>\": {\n return 2;\n }\n case \"vec3<f32>\": {\n return 3;\n }\n case \"vec4<f32>\": {\n return 4;\n }\n case \"mat4x4<f32>\": {\n return 16;\n }\n case \"f32\":\n case \"u32\":\n case \"i32\": {\n return 1;\n }\n default: {\n return assertNever(type, \"shader uniform type\");\n }\n }\n}\n\n/**\n * Rounds a value up to a multiple of an alignment.\n *\n * @param value - The value.\n * @param alignment - The alignment, a power of two.\n * @returns The rounded value.\n */\nfunction roundUp(value: number, alignment: number): number {\n return Math.ceil(value / alignment) * alignment;\n}\n\n/**\n * The whole fragment module: bindings, generated structs, the author's file, and the entry point\n * Lite's pipeline looks for.\n *\n * @param shader - The shader asset.\n * @param fields - The uniform members, in struct order.\n * @returns The WGSL.\n */\nfunction buildFragmentModule(shader: ShaderAsset, fields: readonly PostEffectUniformField[]): string {\n const members = fields.map((field) => `${field.name}:${field.type},`).join(\"\");\n const lines: string[] = [\n `struct PostUniforms{${members}}`,\n \"@group(0)@binding(0)var<uniform>shaderUniforms:PostUniforms;\",\n `@group(0)@binding(${String(INPUT_TEXTURE_BINDING)})var inputTexture:texture_2d<f32>;`,\n `@group(0)@binding(${String(INPUT_SAMPLER_BINDING)})var inputTextureSampler:sampler;`,\n ];\n // `for…of` with an index: the iterator yields the element type rather than `T | undefined`, and\n // this runs once per compiled shader rather than per frame.\n let index = -1;\n for (const declaration of shader.declaration.textures) {\n index += 1;\n const binding = declaredTextureBinding(index);\n const type = declaration.array ? \"texture_2d_array<f32>\" : \"texture_2d<f32>\";\n lines.push(\n `@group(0)@binding(${String(binding)})var ${declaration.name}:${type};`,\n `@group(0)@binding(${String(binding + 1)})var ${declaration.name}Sampler:sampler;`,\n );\n }\n lines.push(\n \"struct PostInput{uv:vec2<f32>,position:vec2<f32>,}\",\n shader.source,\n \"@fragment fn effectFragment(fragment:EffectVertexOutput)->@location(0)vec4<f32>{\",\n \"var ignifxPostInput:PostInput;\",\n // Lite's effect vertex puts uv (0, 0) at the bottom-left, but a texture's origin is the top-left,\n // so an unflipped uv mirrors the frame on every pass (`lib/effect/effect-renderer.js` 7).\n \"ignifxPostInput.uv=vec2<f32>(fragment.uv.x,1.0-fragment.uv.y);\",\n \"ignifxPostInput.position=fragment.position.xy;\",\n `return ${POST_EFFECT_FUNCTION}(ignifxPostInput);`,\n \"}\",\n );\n return lines.join(\"\\n\");\n}\n\n/**\n * Writes one member's value into the uniform bytes.\n *\n * @param field - The member.\n * @param value - The value.\n * @param asset - The shader's address, for diagnostics.\n * @param out - The uniform floats.\n * @throws IgnifxError with code `IGX-0713` when the shape does not match.\n */\nfunction writeField(\n field: PostEffectUniformField,\n value: number | readonly number[],\n asset: string,\n out: Float32Array,\n): void {\n const index = field.byteOffset / 4;\n if (typeof value === \"number\") {\n if (field.components !== 1) {\n throw mismatch(field, asset, \"a single number\");\n }\n out[index] = value;\n return;\n }\n if (value.length !== field.components) {\n throw mismatch(field, asset, `${String(value.length)} floats`);\n }\n out.set(value instanceof Float32Array ? value : Float32Array.from(value), index);\n}\n\n/**\n * The `IGX-0713` failure a wrongly shaped value produces.\n *\n * @param field - The member.\n * @param asset - The shader's address.\n * @param actual - What the caller passed.\n * @returns The error to throw.\n */\nfunction mismatch(field: PostEffectUniformField, asset: string, actual: string): IgnifxError {\n return new IgnifxError(\n CoreErrorCode.shaderValueMismatch,\n `${field.name} on ${asset} expects ${field.type} (${String(field.components)} floats), not ${actual}.`,\n {\n context: { name: field.name, material: asset, expected: field.type, actual },\n hint: \"A post effect's values are numbers and numeric arrays; a colour takes its three or four components.\",\n },\n );\n}\n\n/**\n * Whether a name is one of the four uniforms every post effect gets for free.\n *\n * @param name - The candidate.\n * @returns `true` when the engine writes it.\n */\nfunction isBuiltinUniformName(name: string): boolean {\n for (const builtin of POST_EFFECT_BUILTIN_UNIFORMS) {\n if (builtin.name === name) {\n return true;\n }\n }\n return false;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,SAAgB,kBAAkB,QAAyC;CACzE,IAAI,OAAO,YAAY,SAAS,QAC9B,MAAM,IAAI,YACR,cAAc,kBACd,GAAG,OAAO,QAAQ,oBAAoB,OAAO,YAAY,KAAK,sBAC9D;EACE,SAAS;GAAE,MAAM,OAAO;GAAS,QAAQ;GAAgB,MAAM,OAAO,YAAY;EAAK;EACvF,MAAM;CACR,CACF;CAEF,IAAI,CAAC,IAAI,OAAO,gCAA2C,GAAG,CAAC,CAAC,KAAK,OAAO,MAAM,GAChF,MAAM,IAAI,YACR,cAAc,oBACd,GAAG,OAAO,QAAQ,eAAe,qBAAqB,aACtD;EACE,SAAS;GAAE,OAAO,OAAO;GAAS,MAAM;EAAqB;EAC7D,MAAM,UAAU,qBAAqB;CACvC,CACF;CAEF,MAAM,WAAW,OAAO,YAAY,SAAS,QAAQ,YAAY,CAAC,qBAAqB,QAAQ,IAAI,CAAC;CACpG,MAAM,SAAS,eAAe,CAC5B,GAAG,8BACH,GAAG,SAAS,KAAK,aAAa;EAAE,MAAM,QAAQ;EAAM,MAAM,QAAQ;CAAK,EAAE,CAC3E,CAAC;CACD,MAAM,yBAAS,IAAI,IAAoC;CACvD,KAAK,MAAM,SAAS,OAAO,QACzB,OAAO,IAAI,MAAM,MAAM,KAAK;CAE9B,OAAO;EACL,SAAS,OAAO;EAChB,cAAc,oBAAoB,QAAQ,OAAO,MAAM;EACvD,UAAU,OAAO;EACjB;EACA,mBAAmB,OAAO;EAC1B,UAAU,OAAO,YAAY;CAC/B;AACF;;AAGA,IAAI,WAA4D;;;;;;;;;;;;;;AAehE,SAAgB,mBAAmB,QAAyC;CAC1E,MAAM,QAAS,6BAAa,IAAI,QAAyC;CACzE,MAAM,MAAM,MAAM,IAAI,MAAM;CAC5B,IAAI,QAAQ,KAAA,GACV,OAAO;CAET,MAAM,QAAQ,kBAAkB,MAAM;CACtC,MAAM,IAAI,QAAQ,KAAK;CACvB,OAAO;AACT;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,sBACd,QACA,QACA,QACA,KACM;CACN,KAAK,MAAM,WAAW,OAAO,YAAY,UAAU;EACjD,MAAM,QAAQ,OAAO,OAAO,IAAI,QAAQ,IAAI;EAC5C,IAAI,UAAU,KAAA,GACZ;EAEF,WAAW,OAAO,QAAQ,cAAc,OAAO,SAAS,GAAG;CAC7D;CAGA,KAAK,MAAM,QAAQ,QAAQ;EACzB,IAAI,CAAC,OAAO,OAAO,QAAQ,IAAI,GAC7B;EAEF,MAAM,QAAQ,OAAO,OAAO,IAAI,IAAI;EACpC,MAAM,QAAQ,OAAO;EACrB,IAAI,UAAU,KAAA,GACZ;EAEF,IAAI,UAAU,KAAA,KAAa,qBAAqB,IAAI,GAClD,MAAM,IAAI,YACR,cAAc,sBACd,GAAG,OAAO,QAAQ,6BAA6B,KAAK,IACpD;GACE,SAAS;IAAE,UAAU,OAAO;IAAS,OAAO,OAAO;IAAS;GAAK;GACjE,MAAM,eAAe,CAAC,GAAG,OAAO,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE;EAC5D,CACF;EAEF,WAAW,OAAO,OAAO,OAAO,SAAS,GAAG;CAC9C;AACF;;;;;;;;;;;;;AAsBA,SAAS,eACP,SACe;CACf,MAAM,SAAmC,CAAC;CAC1C,IAAI,SAAS;CAGb,IAAI,kBAAkB;CACtB,KAAK,MAAM,UAAU,SAAS;EAC5B,MAAM,YAAY,cAAc,OAAO,IAAI;EAC3C,MAAM,OAAO,SAAS,OAAO,IAAI;EACjC,kBAAkB,KAAK,IAAI,iBAAiB,SAAS;EACrD,SAAS,QAAQ,QAAQ,SAAS;EAClC,OAAO,KAAK;GACV,MAAM,OAAO;GACb,MAAM,OAAO;GACb,YAAY,eAAe,OAAO,IAAI;GACtC,YAAY;EACd,CAAC;EACD,UAAU;CACZ;CACA,OAAO;EAAE;EAAQ,YAAY,QAAQ,QAAQ,eAAe;CAAE;AAChE;;;;;;;AAQA,SAAS,cAAc,MAAiC;CACtD,QAAQ,MAAR;EACE,KAAK,aACH,OAAO;EAET,KAAK;EACL,KAAK;EACL,KAAK,eACH,OAAO;EAET,KAAK;EACL,KAAK;EACL,KAAK,OACH,OAAO;EAET,SACE,OAAO,YAAY,MAAM,qBAAqB;CAElD;AACF;;;;;;;AAQA,SAAS,SAAS,MAAiC;CACjD,QAAQ,MAAR;EACE,KAAK,aACH,OAAO;EAET,KAAK,aACH,OAAO;EAET,KAAK,aACH,OAAO;EAET,KAAK,eACH,OAAO;EAET,KAAK;EACL,KAAK;EACL,KAAK,OACH,OAAO;EAET,SACE,OAAO,YAAY,MAAM,qBAAqB;CAElD;AACF;;;;;;;;;;;;AAaA,SAAS,eAAe,MAAiC;CACvD,QAAQ,MAAR;EACE,KAAK,aACH,OAAO;EAET,KAAK,aACH,OAAO;EAET,KAAK,aACH,OAAO;EAET,KAAK,eACH,OAAO;EAET,KAAK;EACL,KAAK;EACL,KAAK,OACH,OAAO;EAET,SACE,OAAO,YAAY,MAAM,qBAAqB;CAElD;AACF;;;;;;;;AASA,SAAS,QAAQ,OAAe,WAA2B;CACzD,OAAO,KAAK,KAAK,QAAQ,SAAS,IAAI;AACxC;;;;;;;;;AAUA,SAAS,oBAAoB,QAAqB,QAAmD;CAEnG,MAAM,QAAkB;EACtB,uBAFc,OAAO,KAAK,UAAU,GAAG,MAAM,KAAK,GAAG,MAAM,KAAK,EAAE,CAAC,CAAC,KAAK,EAE5C,EAAE;EAC/B;EACA,qBAAqB,OAAA,CAA4B,EAAE;EACnD,qBAAqB,OAAA,CAA4B,EAAE;CACrD;CAGA,IAAI,QAAQ;CACZ,KAAK,MAAM,eAAe,OAAO,YAAY,UAAU;EACrD,SAAS;EACT,MAAM,UAAU,uBAAuB,KAAK;EAC5C,MAAM,OAAO,YAAY,QAAQ,0BAA0B;EAC3D,MAAM,KACJ,qBAAqB,OAAO,OAAO,EAAE,OAAO,YAAY,KAAK,GAAG,KAAK,IACrE,qBAAqB,OAAO,UAAU,CAAC,EAAE,OAAO,YAAY,KAAK,iBACnE;CACF;CACA,MAAM,KACJ,sDACA,OAAO,QACP,oFACA,kCAGA,kEACA,kDACA,UAAU,qBAAqB,qBAC/B,GACF;CACA,OAAO,MAAM,KAAK,IAAI;AACxB;;;;;;;;;;AAWA,SAAS,WACP,OACA,OACA,OACA,KACM;CACN,MAAM,QAAQ,MAAM,aAAa;CACjC,IAAI,OAAO,UAAU,UAAU;EAC7B,IAAI,MAAM,eAAe,GACvB,MAAM,SAAS,OAAO,OAAO,iBAAiB;EAEhD,IAAI,SAAS;EACb;CACF;CACA,IAAI,MAAM,WAAW,MAAM,YACzB,MAAM,SAAS,OAAO,OAAO,GAAG,OAAO,MAAM,MAAM,EAAE,QAAQ;CAE/D,IAAI,IAAI,iBAAiB,eAAe,QAAQ,aAAa,KAAK,KAAK,GAAG,KAAK;AACjF;;;;;;;;;AAUA,SAAS,SAAS,OAA+B,OAAe,QAA6B;CAC3F,OAAO,IAAI,YACT,cAAc,qBACd,GAAG,MAAM,KAAK,MAAM,MAAM,WAAW,MAAM,KAAK,IAAI,OAAO,MAAM,UAAU,EAAE,gBAAgB,OAAO,IACpG;EACE,SAAS;GAAE,MAAM,MAAM;GAAM,UAAU;GAAO,UAAU,MAAM;GAAM;EAAO;EAC3E,MAAM;CACR,CACF;AACF;;;;;;;AAQA,SAAS,qBAAqB,MAAuB;CACnD,KAAK,MAAM,WAAW,8BACpB,IAAI,QAAQ,SAAS,MACnB,OAAO;CAGX,OAAO;AACT"}
1
+ {"version":3,"file":"post-effect-compiler-cCq9lcHt.js","names":[],"sources":["../src/render/post-effect-compiler.ts"],"sourcesContent":["import { CoreErrorCode } from \"../errors/error-codes.js\";\nimport { assertNever, IgnifxError } from \"../errors/ignifx-error.js\";\nimport {\n declaredTextureBinding,\n INPUT_SAMPLER_BINDING,\n INPUT_TEXTURE_BINDING,\n POST_EFFECT_BUILTIN_UNIFORMS,\n POST_EFFECT_FUNCTION,\n} from \"./post-effect.js\";\nimport type { CompiledPostEffect, PostEffectUniformField } from \"./post-effect.js\";\nimport type { ShaderAsset } from \"./shader-asset.js\";\nimport type { ShaderUniformType } from \"./shader-declaration.js\";\n\n/**\n * Turns a `// @ignifx post` file into the fragment module and uniform layout Babylon Lite's\n * fullscreen-effect path needs (`docs/plan/2026-09-terrain-particles-shaders.md` §3.3).\n *\n * `mainFragment` is a plain function, not an entry point: Lite hard-codes the entry-point names\n * `effectFullscreenVertex` and `effectFragment` (`lib/effect/effect-renderer.js` 7, 258-260), so the\n * entry point is generated here and forwards to it. `createEffectWrapper` takes a byte length and a\n * raw writer and computes no offsets, so the struct's member offsets are worked out here from WGSL's\n * own alignment rules and kept in step with the generated struct.\n *\n * Everything in this module is device-free and deterministic, so it is asserted in Node. It is\n * reached through `./post-effect-support.ts` so a game with no custom post effect never loads it.\n */\n\n/**\n * Compiles a `// @ignifx post` file into a full fragment module and a uniform layout.\n *\n * @remarks\n * Device-free and deterministic, so the whole thing is unit-testable: the result is a WGSL string\n * and a set of byte offsets. It is memoised per shader asset by {@link compiledPostEffect}, because\n * the chain asks for it on every rebuild.\n *\n * @param shader - The loaded shader asset.\n * @returns The compiled effect.\n * @throws IgnifxError with code `IGX-0709` when the file is not a `post` one, or `IGX-0723` when it\n * declares no `mainFragment` function.\n *\n * @example\n * ```ts\n * const compiled = compilePostEffect(vignette.value);\n * compiled.byName.get(\"amount\")?.byteOffset; // 20, right after the four built-ins\n * ```\n *\n * @internal\n */\nexport function compilePostEffect(shader: ShaderAsset): CompiledPostEffect {\n if (shader.declaration.kind !== \"post\") {\n throw new IgnifxError(\n CoreErrorCode.invalidAssetFile,\n `${shader.address} declares @ignifx ${shader.declaration.kind}, not @ignifx post.`,\n {\n context: { file: shader.address, format: \"@ignifx post\", kind: shader.declaration.kind },\n hint: \"A PostProcessStack custom effect takes a .post.wgsl file whose pragma is @ignifx post.\",\n },\n );\n }\n if (!new RegExp(`\\\\bfn\\\\s+${POST_EFFECT_FUNCTION}\\\\s*\\\\(`, \"u\").test(shader.source)) {\n throw new IgnifxError(\n CoreErrorCode.surfaceHookMissing,\n `${shader.address} declares no ${POST_EFFECT_FUNCTION} function.`,\n {\n context: { asset: shader.address, hook: POST_EFFECT_FUNCTION },\n hint: `Add fn ${POST_EFFECT_FUNCTION}(in: PostInput) -> vec4<f32>; the @fragment entry point is generated.`,\n },\n );\n }\n const declared = shader.declaration.uniforms.filter((uniform) => !isBuiltinUniformName(uniform.name));\n const layout = layOutUniforms([\n ...POST_EFFECT_BUILTIN_UNIFORMS,\n ...declared.map((uniform) => ({ name: uniform.name, type: uniform.type })),\n ]);\n const byName = new Map<string, PostEffectUniformField>();\n for (const field of layout.fields) {\n byName.set(field.name, field);\n }\n return {\n address: shader.address,\n fragmentWGSL: buildFragmentModule(shader, layout.fields),\n uniforms: layout.fields,\n byName,\n uniformByteLength: layout.byteLength,\n textures: shader.declaration.textures,\n };\n}\n\n/** The compiled form of each shader asset, so a chain rebuild recompiles nothing. */\nlet compiled: WeakMap<ShaderAsset, CompiledPostEffect> | null = null;\n\n/**\n * The compiled form of a post-effect shader, compiled once per asset.\n *\n * @remarks\n * Keyed on the `ShaderAsset` itself, so a hot reload — which replaces the asset object — recompiles\n * for free.\n *\n * @param shader - The loaded shader asset.\n * @returns The compiled effect.\n * @throws IgnifxError as {@link compilePostEffect} documents.\n *\n * @internal\n */\nexport function compiledPostEffect(shader: ShaderAsset): CompiledPostEffect {\n const cache = (compiled ??= new WeakMap<ShaderAsset, CompiledPostEffect>());\n const hit = cache.get(shader);\n if (hit !== undefined) {\n return hit;\n }\n const built = compilePostEffect(shader);\n cache.set(shader, built);\n return built;\n}\n\n/**\n * Writes an effect's current values into the bytes its uniform buffer takes.\n *\n * @remarks\n * The built-in clocks and `screenSize` are written by the caller through the same `out` buffer, so\n * this only fills in the declared members: the declaration's default first, then the settings'\n * override. Unknown names are refused, which is what makes a typo in a `.scene.json` visible.\n *\n * @param effect - The compiled effect.\n * @param shader - The shader, for its declared defaults.\n * @param values - The overrides.\n * @param out - The uniform bytes, at least `effect.uniformByteLength` long.\n * @throws IgnifxError with code `IGX-0712` for an undeclared name, or `IGX-0713` for a wrongly\n * shaped value.\n *\n * @internal\n */\nexport function writePostEffectValues(\n effect: CompiledPostEffect,\n shader: ShaderAsset,\n values: Readonly<Record<string, number | readonly number[]>>,\n out: Float32Array,\n): void {\n for (const uniform of shader.declaration.uniforms) {\n const field = effect.byName.get(uniform.name);\n if (field === undefined) {\n continue;\n }\n writeField(field, uniform.defaultValue, effect.address, out);\n }\n // `for…in` rather than `Object.keys`: the chain calls this every frame for every recorded effect\n // and a key array per effect per frame is per-frame allocation (coding standards §7).\n for (const name in values) {\n if (!Object.hasOwn(values, name)) {\n continue;\n }\n const field = effect.byName.get(name);\n const value = values[name];\n if (value === undefined) {\n continue;\n }\n if (field === undefined || isBuiltinUniformName(name)) {\n throw new IgnifxError(\n CoreErrorCode.unknownShaderBinding,\n `${effect.address} declares no uniform named ${name}.`,\n {\n context: { material: effect.address, asset: effect.address, name },\n hint: `It declares ${[...effect.byName.keys()].join(\", \")}.`,\n },\n );\n }\n writeField(field, value, effect.address, out);\n }\n}\n\n/** The result of laying out a uniform struct. */\ninterface UniformLayout {\n /** The members, in struct order. */\n readonly fields: readonly PostEffectUniformField[];\n /** The struct's size, in bytes. */\n readonly byteLength: number;\n}\n\n/**\n * Computes the byte offsets WGSL gives a struct of these members, in this order.\n *\n * @remarks\n * The rules are the WGSL specification's: a member's offset is its predecessor's end rounded up to\n * the member's alignment, and the struct's size is the last member's end rounded up to the struct's\n * alignment — the largest member alignment, and in the **uniform** address space never less than\n * 16. `vec3<f32>` is the one that catches people out: 16-aligned, 12 wide (plan §3.4).\n *\n * @param members - The members, in declaration order.\n * @returns The layout.\n */\nfunction layOutUniforms(\n members: readonly { readonly name: string; readonly type: ShaderUniformType }[],\n): UniformLayout {\n const fields: PostEffectUniformField[] = [];\n let offset = 0;\n // WGSL's uniform address space rounds a struct's alignment up to a multiple of 16, so the block's\n // size is always a multiple of 16 whatever its members are.\n let structAlignment = 16;\n for (const member of members) {\n const alignment = typeAlignment(member.type);\n const size = typeSize(member.type);\n structAlignment = Math.max(structAlignment, alignment);\n offset = roundUp(offset, alignment);\n fields.push({\n name: member.name,\n type: member.type,\n components: componentCount(member.type),\n byteOffset: offset,\n });\n offset += size;\n }\n return { fields, byteLength: roundUp(offset, structAlignment) };\n}\n\n/**\n * A WGSL type's alignment in the uniform address space, in bytes.\n *\n * @param type - The type.\n * @returns The alignment.\n */\nfunction typeAlignment(type: ShaderUniformType): number {\n switch (type) {\n case \"vec2<f32>\": {\n return 8;\n }\n case \"vec3<f32>\":\n case \"vec4<f32>\":\n case \"mat4x4<f32>\": {\n return 16;\n }\n case \"f32\":\n case \"u32\":\n case \"i32\": {\n return 4;\n }\n default: {\n return assertNever(type, \"shader uniform type\");\n }\n }\n}\n\n/**\n * A WGSL type's size, in bytes.\n *\n * @param type - The type.\n * @returns The size.\n */\nfunction typeSize(type: ShaderUniformType): number {\n switch (type) {\n case \"vec2<f32>\": {\n return 8;\n }\n case \"vec3<f32>\": {\n return 12;\n }\n case \"vec4<f32>\": {\n return 16;\n }\n case \"mat4x4<f32>\": {\n return 64;\n }\n case \"f32\":\n case \"u32\":\n case \"i32\": {\n return 4;\n }\n default: {\n return assertNever(type, \"shader uniform type\");\n }\n }\n}\n\n/**\n * How many floats one uniform of a declared type occupies.\n *\n * @remarks\n * A private copy of `material-plugin.ts`'s `uniformComponentCount`. `PostProcessStack` is in every\n * game's static graph, and importing it from there would drag `defineMaterialPlugin` and the\n * reserved-name table into a bundle that draws no custom shader at all.\n *\n * @param type - The declared WGSL type.\n * @returns The component count: 1, 2, 3, 4, or 16.\n */\nfunction componentCount(type: ShaderUniformType): number {\n switch (type) {\n case \"vec2<f32>\": {\n return 2;\n }\n case \"vec3<f32>\": {\n return 3;\n }\n case \"vec4<f32>\": {\n return 4;\n }\n case \"mat4x4<f32>\": {\n return 16;\n }\n case \"f32\":\n case \"u32\":\n case \"i32\": {\n return 1;\n }\n default: {\n return assertNever(type, \"shader uniform type\");\n }\n }\n}\n\n/**\n * Rounds a value up to a multiple of an alignment.\n *\n * @param value - The value.\n * @param alignment - The alignment, a power of two.\n * @returns The rounded value.\n */\nfunction roundUp(value: number, alignment: number): number {\n return Math.ceil(value / alignment) * alignment;\n}\n\n/**\n * The whole fragment module: bindings, generated structs, the author's file, and the entry point\n * Lite's pipeline looks for.\n *\n * @param shader - The shader asset.\n * @param fields - The uniform members, in struct order.\n * @returns The WGSL.\n */\nfunction buildFragmentModule(shader: ShaderAsset, fields: readonly PostEffectUniformField[]): string {\n const members = fields.map((field) => `${field.name}:${field.type},`).join(\"\");\n const lines: string[] = [\n `struct PostUniforms{${members}}`,\n \"@group(0)@binding(0)var<uniform>shaderUniforms:PostUniforms;\",\n `@group(0)@binding(${String(INPUT_TEXTURE_BINDING)})var inputTexture:texture_2d<f32>;`,\n `@group(0)@binding(${String(INPUT_SAMPLER_BINDING)})var inputTextureSampler:sampler;`,\n ];\n // `for…of` with an index: the iterator yields the element type rather than `T | undefined`, and\n // this runs once per compiled shader rather than per frame.\n let index = -1;\n for (const declaration of shader.declaration.textures) {\n index += 1;\n const binding = declaredTextureBinding(index);\n const type = declaration.array ? \"texture_2d_array<f32>\" : \"texture_2d<f32>\";\n lines.push(\n `@group(0)@binding(${String(binding)})var ${declaration.name}:${type};`,\n `@group(0)@binding(${String(binding + 1)})var ${declaration.name}Sampler:sampler;`,\n );\n }\n lines.push(\n \"struct PostInput{uv:vec2<f32>,position:vec2<f32>,}\",\n shader.source,\n \"@fragment fn effectFragment(fragment:EffectVertexOutput)->@location(0)vec4<f32>{\",\n \"var ignifxPostInput:PostInput;\",\n // Lite's effect vertex puts uv (0, 0) at the bottom-left, but a texture's origin is the top-left,\n // so an unflipped uv mirrors the frame on every pass (`lib/effect/effect-renderer.js` 7).\n \"ignifxPostInput.uv=vec2<f32>(fragment.uv.x,1.0-fragment.uv.y);\",\n \"ignifxPostInput.position=fragment.position.xy;\",\n `return ${POST_EFFECT_FUNCTION}(ignifxPostInput);`,\n \"}\",\n );\n return lines.join(\"\\n\");\n}\n\n/**\n * Writes one member's value into the uniform bytes.\n *\n * @param field - The member.\n * @param value - The value.\n * @param asset - The shader's address, for diagnostics.\n * @param out - The uniform floats.\n * @throws IgnifxError with code `IGX-0713` when the shape does not match.\n */\nfunction writeField(\n field: PostEffectUniformField,\n value: number | readonly number[],\n asset: string,\n out: Float32Array,\n): void {\n const index = field.byteOffset / 4;\n if (typeof value === \"number\") {\n if (field.components !== 1) {\n throw mismatch(field, asset, \"a single number\");\n }\n out[index] = value;\n return;\n }\n if (value.length !== field.components) {\n throw mismatch(field, asset, `${String(value.length)} floats`);\n }\n out.set(value instanceof Float32Array ? value : Float32Array.from(value), index);\n}\n\n/**\n * The `IGX-0713` failure a wrongly shaped value produces.\n *\n * @param field - The member.\n * @param asset - The shader's address.\n * @param actual - What the caller passed.\n * @returns The error to throw.\n */\nfunction mismatch(field: PostEffectUniformField, asset: string, actual: string): IgnifxError {\n return new IgnifxError(\n CoreErrorCode.shaderValueMismatch,\n `${field.name} on ${asset} expects ${field.type} (${String(field.components)} floats), not ${actual}.`,\n {\n context: { name: field.name, material: asset, expected: field.type, actual },\n hint: \"A post effect's values are numbers and numeric arrays; a colour takes its three or four components.\",\n },\n );\n}\n\n/**\n * Whether a name is one of the four uniforms every post effect gets for free.\n *\n * @param name - The candidate.\n * @returns `true` when the engine writes it.\n */\nfunction isBuiltinUniformName(name: string): boolean {\n for (const builtin of POST_EFFECT_BUILTIN_UNIFORMS) {\n if (builtin.name === name) {\n return true;\n }\n }\n return false;\n}\n"],"mappings":"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"}
@@ -2164,7 +2164,7 @@ function resolveInstancePath(scene, path, readScene, kind) {
2164
2164
  for (let index = 1; index < segments.length - 1; index += 1) {
2165
2165
  const found = findEntity(frame, segments[index] ?? "");
2166
2166
  if (found === null) return null;
2167
- if (found.entity.uid !== found.file.mergedRoot) frame = frameOf(found.entity, labelsOf(frame, found.file, found.entity), nextSegments(found.file, found.entity.uid), readScene, frame.seen);
2167
+ if (found.entity.uid !== found.file.mergedRoot) frame = frameOf(found.entity, labelsOf(frame, found.file, found.entity), nextSegments(found.file, found.entity.uid), readScene, ancestorsOf(frame, found.file));
2168
2168
  }
2169
2169
  const last = segments[segments.length - 1] ?? "";
2170
2170
  if (kind !== "component") {
@@ -2229,7 +2229,7 @@ function walkFrame(frame, at, prefix, carrier, readScene, into) {
2229
2229
  walkFrame(frame, at + 1, prefix, carrier, readScene, into);
2230
2230
  continue;
2231
2231
  }
2232
- walkFrame(frameOf(entity, labelsOf(frame, file, entity), nextSegments(file, entity.uid), readScene, frame.seen), 0, `${prefix}/${entity.uid}`, carrier, readScene, into);
2232
+ walkFrame(frameOf(entity, labelsOf(frame, file, entity), nextSegments(file, entity.uid), readScene, ancestorsOf(frame, file)), 0, `${prefix}/${entity.uid}`, carrier, readScene, into);
2233
2233
  }
2234
2234
  }
2235
2235
  /**
@@ -2239,12 +2239,12 @@ function walkFrame(frame, at, prefix, carrier, readScene, into) {
2239
2239
  * @param labels - The names down to and including the carrier.
2240
2240
  * @param overrideSegments - The override component path prefix for the first file.
2241
2241
  * @param readScene - Reads the files.
2242
- * @param seen - The addresses read on the way here.
2242
+ * @param ancestors - The addresses of the files enclosing the carrier, outermost first.
2243
2243
  * @returns The frame; empty when the first file cannot be read or would nest itself.
2244
2244
  */
2245
- function frameOf(carrier, labels, overrideSegments, readScene, seen) {
2245
+ function frameOf(carrier, labels, overrideSegments, readScene, ancestors) {
2246
2246
  const files = [];
2247
- const addresses = [...seen];
2247
+ const addresses = [...ancestors];
2248
2248
  let current = carrier;
2249
2249
  let segments = overrideSegments;
2250
2250
  while (current?.instance !== void 0 && addresses.length < DEPTH_LIMIT) {
@@ -2265,10 +2265,27 @@ function frameOf(carrier, labels, overrideSegments, readScene, seen) {
2265
2265
  return {
2266
2266
  files,
2267
2267
  labels,
2268
- seen: addresses
2268
+ ancestors
2269
2269
  };
2270
2270
  }
2271
2271
  /**
2272
+ * The ancestor chain of an entity a frame file declares: the frame's own ancestors, then the frame
2273
+ * files from the outermost down to and including the declaring one. A file later in the frame
2274
+ * merges into the same carrier but does not enclose the entity, so it is not an ancestor.
2275
+ *
2276
+ * @param frame - The frame.
2277
+ * @param file - The frame file declaring the entity.
2278
+ * @returns The addresses, outermost first.
2279
+ */
2280
+ function ancestorsOf(frame, file) {
2281
+ const chain = [...frame.ancestors];
2282
+ for (const candidate of frame.files) {
2283
+ chain.push(candidate.address);
2284
+ if (candidate === file) break;
2285
+ }
2286
+ return chain;
2287
+ }
2288
+ /**
2272
2289
  * The override component path prefix for the files a non-merged entity of `file` instances.
2273
2290
  *
2274
2291
  * @param file - The frame file declaring the entity.
@@ -2813,4 +2830,4 @@ function withOverrides(instance, overrides, hash) {
2813
2830
  //#endregion
2814
2831
  export { childPath as A, MEMORY_ADDRESS_PREFIX as B, canonicalizeNumber as C, encodeValue as D, encodeProps as E, asJsonObject as F, splitFragment as G, joinRoot as H, setOwnJsonProperty as I, SchemaIssueCode as L, isArray as M, isPlainObject as N, COLOR_CHANNELS as O, asJsonArray as P, issue as R, toJsonSchema as S, decodeValue as T, matchExtension as U, isAbsoluteAddress as V, normalizeExtension as W, describeSceneFileFormat as _, applyOverrides as a, stringifySceneFile as b, remapInstancePath as c, createSceneAsset as d, findSceneDependency as f, SCENE_FORMAT_VERSION as g, SCENE_FILE_FORMAT as h, resolveInstancePath as i, indexPath as j, VECTOR_COMPONENTS as k, SceneAssetToken as l, SCENE_FILE_EXTENSIONS as m, revertOverrides as n, parseOverridePath as o, SCENE_ASSET_TYPE as p, enumerateInstanceTargets as r, instancePathResolver as s, applyOverridesToAsset as t, computeSceneHash as u, isSceneFileHeader as v, decodeProps as w, describeSchema as x, sceneFileJsonSchema as y, throwSchemaError as z };
2815
2832
 
2816
- //# sourceMappingURL=prefab-overrides-DRP2DcnC.js.map
2833
+ //# sourceMappingURL=prefab-overrides-C2GsgOQc.js.map