@ignifx/core 0.13.0 → 0.15.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 (59) hide show
  1. package/dist/agx-tone-mapping-Cgt844j6.js +53 -0
  2. package/dist/agx-tone-mapping-Cgt844j6.js.map +1 -0
  3. package/dist/auto-exposure-uzPn0beO.js +246 -0
  4. package/dist/auto-exposure-uzPn0beO.js.map +1 -0
  5. package/dist/bloom-hdr-CLtQj-oY.js +315 -0
  6. package/dist/bloom-hdr-CLtQj-oY.js.map +1 -0
  7. package/dist/contact-shadows-T523EXaP.js +84 -0
  8. package/dist/contact-shadows-T523EXaP.js.map +1 -0
  9. package/dist/{environment-C9AjYJgV.js → environment-DPi0_0SP.js} +19 -5
  10. package/dist/environment-DPi0_0SP.js.map +1 -0
  11. package/dist/gtao-_nr0b6-E.js +630 -0
  12. package/dist/gtao-_nr0b6-E.js.map +1 -0
  13. package/dist/hdr-output-BrUvpAsE.js +525 -0
  14. package/dist/hdr-output-BrUvpAsE.js.map +1 -0
  15. package/dist/{ignifx-error-Dq2qJMkZ.js → ignifx-error-oYdVnT1S.js} +16 -1
  16. package/dist/ignifx-error-oYdVnT1S.js.map +1 -0
  17. package/dist/index.d.ts +753 -18
  18. package/dist/index.d.ts.map +1 -1
  19. package/dist/index.js +1679 -183
  20. package/dist/index.js.map +1 -1
  21. package/dist/{instanced-mesh-instance-DYwH0vLi.js → instanced-mesh-instance-NnODkvqK.js} +2 -2
  22. package/dist/{instanced-mesh-instance-DYwH0vLi.js.map → instanced-mesh-instance-NnODkvqK.js.map} +1 -1
  23. package/dist/mat4-D6exvAuO.js +949 -0
  24. package/dist/mat4-D6exvAuO.js.map +1 -0
  25. package/dist/material-CGk5mAah.js +204 -0
  26. package/dist/material-CGk5mAah.js.map +1 -0
  27. package/dist/{material-plugin-BOCB7Stt.js → material-plugin-BUlqLsap.js} +3 -204
  28. package/dist/material-plugin-BUlqLsap.js.map +1 -0
  29. package/dist/{post-effect-compiler-Dw6zW2cG.js → post-effect-compiler-CRek8VxQ.js} +2 -2
  30. package/dist/{post-effect-compiler-Dw6zW2cG.js.map → post-effect-compiler-CRek8VxQ.js.map} +1 -1
  31. package/dist/render-path-Be7WgN7r.js +166 -0
  32. package/dist/render-path-Be7WgN7r.js.map +1 -0
  33. package/dist/render-texture-C_TnaSz2.js +200 -0
  34. package/dist/render-texture-C_TnaSz2.js.map +1 -0
  35. package/dist/scene-color-passes-DlNr-qyZ.js +65 -0
  36. package/dist/scene-color-passes-DlNr-qyZ.js.map +1 -0
  37. package/dist/scene-inputs-BxGOsnIZ.js +318 -0
  38. package/dist/scene-inputs-BxGOsnIZ.js.map +1 -0
  39. package/dist/{shader-material-DRZmqA_S.js → shader-material-B6p66wB8.js} +18 -7
  40. package/dist/shader-material-B6p66wB8.js.map +1 -0
  41. package/dist/{shader-material-BxQn9FT4.js → shader-material-C0TAUr4t.js} +102 -4
  42. package/dist/shader-material-C0TAUr4t.js.map +1 -0
  43. package/dist/{shader-pragma-DrFm5f5m.js → shader-pragma-BKCoZTTA.js} +2 -2
  44. package/dist/{shader-pragma-DrFm5f5m.js.map → shader-pragma-BKCoZTTA.js.map} +1 -1
  45. package/dist/ssgi-Dm-maZrc.js +113 -0
  46. package/dist/ssgi-Dm-maZrc.js.map +1 -0
  47. package/dist/{surface-shader-BgZchRBe.js → surface-shader-BaK0kvBB.js} +5 -4
  48. package/dist/{surface-shader-BgZchRBe.js.map → surface-shader-BaK0kvBB.js.map} +1 -1
  49. package/dist/taa-BwBZLy11.js +480 -0
  50. package/dist/taa-BwBZLy11.js.map +1 -0
  51. package/dist/{vec3-T2PasQZv.js → vec3-D-0Y2mzE.js} +4 -948
  52. package/dist/vec3-D-0Y2mzE.js.map +1 -0
  53. package/package.json +1 -1
  54. package/dist/environment-C9AjYJgV.js.map +0 -1
  55. package/dist/ignifx-error-Dq2qJMkZ.js.map +0 -1
  56. package/dist/material-plugin-BOCB7Stt.js.map +0 -1
  57. package/dist/shader-material-BxQn9FT4.js.map +0 -1
  58. package/dist/shader-material-DRZmqA_S.js.map +0 -1
  59. package/dist/vec3-T2PasQZv.js.map +0 -1
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hdr-output-BrUvpAsE.js","names":[],"sources":["../src/lite/gpu/hdr-output.ts"],"sourcesContent":["import {\n AcesToneMapping,\n addTask,\n addTaskBefore,\n buildFrameGraphTask,\n createEffectRenderTask,\n createEffectWrapper,\n createRenderTarget,\n createRenderTask,\n createSurfaceRenderTargetTexture,\n enableMaterialPlugins,\n getFrameGraph,\n getPbrUnlit,\n isPbrMaterial,\n isStandardMaterial,\n NeutralToneMapping,\n onRenderTargetTextureResize,\n reconcileMaterialPlugins,\n setEffectTexture,\n setEffectUniforms,\n setEnvironmentRotation,\n setFog,\n StandardToneMapping,\n} from \"@babylonjs/lite\";\nimport { rebuildMaterialPipelines } from \"../material.js\";\nimport { AGX_CALL_WGSL, AGX_HELPERS_WGSL, AGX_TONE_MAPPING_ID } from \"./agx-tone-mapping.js\";\nimport { DEPTH_STENCIL_FORMAT, markHdrScene } from \"./render-path.js\";\nimport type { AutoExposurePass } from \"./auto-exposure.js\";\nimport type { HdrOutputHandle, ScenePresenter } from \"./render-path.js\";\nimport type {\n EffectWrapper,\n EngineContext,\n FogConfig,\n ImageProcessingConfig,\n MaterialPlugin,\n RenderTarget,\n SceneContext,\n Task,\n Texture2D,\n} from \"@babylonjs/lite\";\n\n/**\n * The HDR render path (`docs/plan/2026-11-gi-phase-1-execution-plan.md`, step G2): the frame graph\n * a scene gets when the project declares `rendering.hdr`. Its own chunk: `../engine.ts` imports it\n * only when the setting is on, so a project without HDR loads none of it (`CONSTITUTION.md` §2.5).\n *\n * ```text\n * [shadow] → scene ──→ hdr (rgba16float) ─ [custom effects, linear] ─→ output ──→ swapchain\n * └──→ sceneColor ─ (built-in effects)\n * ```\n *\n * - **Linear colour.** Lite's PBR shader ends every fragment with fog, exposure, the curve, a\n * `pow(1/2.2)` encode, a clamp and contrast (`lib/material/pbr/pbr-template.js` line 171), so an\n * `rgba16float` target alone still holds values ≤ 1. {@link createLinearOutputPlugin} saves the\n * colour before that block and restores it before the fragment is written (spike S1).\n * - **The output pass** applies the scene's `imageProcessing` — exposure, contrast and the curve\n * the `Environment` set, or `loadEnvironment` set — then the same encode, clamp and contrast,\n * so a PBR-only scene presents the same bytes as without HDR, within half-float rounding.\n * - **Two output tasks.** A task cannot change its target once recorded, so there is one that\n * writes the swapchain and one that writes `sceneColor`, an ordinary colour target a\n * `PostProcessStack` chain reads. {@link ScenePresenter.setPresentEnabled} switches between them,\n * so the frame runs exactly one.\n *\n * - **Every other colour writer (step G3).** The restore re-applies the PBR fog, so a fogged scene\n * keeps its fog. A Standard material (and a surface shader on one) gets\n * {@link createStandardLinearPlugin}, which decodes its display colour; a surface shader on a PBR\n * host is caught by the PBR plugin, because its composite runs before the save. Lite's environment\n * skyboxes (`.env`, `.dds`) are patched to return the cube map's linear colour\n * ({@link linearSkyboxFragment}). Custom `.wgsl` materials (particles, foliage) are wrapped by\n * `./shader-material.ts`, which asks {@link markHdrScene}'s record. Sprites need nothing: a\n * `SpriteRenderer` draws its own pass onto the swapchain after the scene, so it never passes\n * through the output pass. Under HDR, Standard and custom-shader colour now gets the scene's\n * exposure, curve and contrast like everything else; with Lite's defaults (exposure 1, contrast 1,\n * no curve) that is the identity and the image matches the plain path.\n * - **Fog colour.** The scene's fog colour is stored decoded here, so the Standard fog block blends\n * in linear space and the PBR restore can use it as is.\n * - **Custom effects first.** A `PostProcessStack`'s custom effects ordered before any built-in one\n * are inserted before the output pass ({@link HdrOutputHandle.insertLinearTask}) and the output\n * pass reads the last one's result ({@link HdrOutputHandle.setOutputSource}). Bloom, SMAA and\n * Lite's image-processing task stay after it: they expect display colour and 8-bit targets.\n *\n * Not covered: Lite's six-face `loadSkybox` cube and its solid-colour and ground backgrounds, which\n * have fixed shaders with no patch point; they still encode twice under HDR.\n */\n\n/**\n * The colour format of the HDR scene target.\n *\n * @internal\n */\nexport const HDR_SCENE_FORMAT: GPUTextureFormat = \"rgba16float\";\n\n/**\n * The name the linear-output plugin carries; part of Lite's pipeline cache key.\n *\n * @internal\n */\nexport const LINEAR_OUTPUT_PLUGIN_NAME = \"ignifx-hdr-linear-output\";\n\n/**\n * The name the Standard material's decode plugin carries.\n *\n * @internal\n */\nexport const STANDARD_LINEAR_PLUGIN_NAME = \"ignifx-hdr-linear-standard\";\n\n/**\n * The name the unlit PBR material's plugin carries.\n *\n * @internal\n */\nexport const UNLIT_LINEAR_PLUGIN_NAME = \"ignifx-hdr-linear-unlit\";\n\n/**\n * Where the skybox patch sits in Lite's skybox patch list: after rotation (0) and blur (1)\n * (`lib/scene/set-environment-rotation.js`, `lib/scene/set-environment-blur.js`).\n */\nconst SKYBOX_PATCH_ORDER = 8;\n\n/**\n * Lite's fog factor (`lib/shader/wgsl-fog.js`) under an ignifx name: the PBR shader declares\n * `calcFogFactor` only when the scene has fog, and the plugin code must compile either way.\n */\nconst FOG_FACTOR_WGSL =\n \"fn ignifxFogFactor(d:vec3<f32>)->f32{var k:f32=1.0;let mode=scene.vFogInfos.x;let dist=length(d);\" +\n \"if(mode==3.0){k=(scene.vFogInfos.z-dist)/(scene.vFogInfos.z-scene.vFogInfos.y);}\" +\n \"else if(mode==1.0){k=1.0/pow(2.71828,dist*scene.vFogInfos.w);}\" +\n \"else if(mode==2.0){k=1.0/pow(2.71828,dist*dist*scene.vFogInfos.w*scene.vFogInfos.w);}\" +\n \"return clamp(k,0.0,1.0);}\";\n\n/**\n * The PBR fog block (`lib/material/pbr/pbr-fog-wgsl.js`) on the restored colour, except that the\n * fog colour is already linear: the HDR path stores it decoded.\n */\nconst FOG_RESTORE_WGSL =\n \"if(scene.vFogInfos.x>0.0){color=mix(scene.vFogColor.rgb,color,\" +\n \"pow(ignifxFogFactor((scene.view*vec4<f32>(input.worldPos,1.0)).xyz),2.2));}\";\n\n/**\n * The frame-graph task names, in the order they run after `\"scene\"`.\n *\n * @internal\n */\nexport const HDR_OUTPUT_TASK_NAMES = { toChain: \"ignifx:hdr-output-chain\", toSwapchain: \"ignifx:hdr-output\" } as const;\n\n/**\n * The curve numbers the output shader branches on.\n *\n * @internal\n */\nexport const HDR_CURVE = { none: 0, standard: 1, aces: 2, neutral: 3, agx: 4 } as const;\n\n/** The output pass's uniform block: exposure, contrast, curve, padding. */\nconst UNIFORM_FLOATS = 4;\n\n/**\n * Builds the material plugin that keeps a PBR fragment's colour linear.\n *\n * @remarks\n * `CUSTOM_FRAGMENT_BEFORE_FINALCOLORCOMPOSITION` is injected at two slots (`AI`, `NI`;\n * `lib/material/plugin/plugin-bridge-shared.js` line 13), so the save is an assignment, never a\n * `let`; the second one, after indirect light, wins. Priority 0 puts the restore ahead of any other\n * plugin's `CUSTOM_FRAGMENT_BEFORE_FRAGCOLOR` code, which then works on linear colour.\n *\n * @returns The plugin. Plain data, so one object can be shared by every material.\n *\n * @internal\n */\nexport function createLinearOutputPlugin(): MaterialPlugin {\n const fragment = {\n CUSTOM_FRAGMENT_DEFINITIONS: `var<private> ignifxLinearColor: vec3<f32>;${FOG_FACTOR_WGSL}`,\n CUSTOM_FRAGMENT_BEFORE_FINALCOLORCOMPOSITION: \"ignifxLinearColor = color;\",\n CUSTOM_FRAGMENT_BEFORE_FRAGCOLOR: `color = ignifxLinearColor;${FOG_RESTORE_WGSL}`,\n };\n return {\n name: LINEAR_OUTPUT_PLUGIN_NAME,\n priority: 0,\n getCustomCode: (stage) => (stage === \"fragment\" ? fragment : null),\n };\n}\n\n/**\n * Builds the plugin that keeps an unlit PBR material's colour linear.\n *\n * @remarks\n * With no environment, Lite's unlit fragment assigns its colour at the `NI` slot\n * (`lib/material/pbr/fragments/unlit-fragment.js`), after the linear-output plugin's save there, so\n * the save would hold the lit colour. This plugin recomputes the unlit colour instead\n * (`baseColor * material.unlitColor`, both in scope before the fragment is written), then applies\n * the fog the restore would.\n *\n * @returns The plugin, shared by every unlit PBR material.\n *\n * @internal\n */\nexport function createUnlitLinearPlugin(): MaterialPlugin {\n const fragment = {\n CUSTOM_FRAGMENT_DEFINITIONS: FOG_FACTOR_WGSL,\n CUSTOM_FRAGMENT_BEFORE_FRAGCOLOR: `color = baseColor*material.unlitColor;${FOG_RESTORE_WGSL}`,\n };\n return {\n name: UNLIT_LINEAR_PLUGIN_NAME,\n priority: 0,\n getCustomCode: (stage) => (stage === \"fragment\" ? fragment : null),\n };\n}\n\n/**\n * Builds the plugin that turns a Standard material's colour linear.\n *\n * @remarks\n * Lite's Standard shader does no image processing and no encode: what it writes is the colour that\n * is displayed. The plugin decodes it with the exact inverse of the output pass's encode\n * (`pow(c, 2.2)`), so the output pass gives it back. It runs at the `BC` slot, before Lite's Standard fog\n * block (the `BA` slot), which then mixes in the decoded fog colour. Priority 1000 puts it after any\n * surface shader's own `CUSTOM_FRAGMENT_BEFORE_FRAGCOLOR` code.\n *\n * @returns The plugin, shared by every Standard material.\n *\n * @internal\n */\nexport function createStandardLinearPlugin(): MaterialPlugin {\n const fragment = {\n CUSTOM_FRAGMENT_BEFORE_FRAGCOLOR: \"color=vec4<f32>(pow(max(color.rgb,vec3<f32>(0.0)),vec3<f32>(2.2)),color.a);\",\n };\n return {\n name: STANDARD_LINEAR_PLUGIN_NAME,\n priority: 1000,\n getCustomCode: (stage) => (stage === \"fragment\" ? fragment : null),\n };\n}\n\n/**\n * Makes one of Lite's environment skybox shaders return the cube map's linear colour.\n *\n * @remarks\n * The `.env` (`\"hdr\"`) and `.dds` skyboxes multiply by `mesh.exposureLinear`, then encode, clamp\n * and apply contrast themselves (`lib/material/pbr/background-hdr-skybox.js`,\n * `lib/_chunks/background-dds-skybox-*.js`), and Lite gives them no material plugin point. The patch\n * returns the colour just before that multiply, so the output pass applies exposure, the curve and\n * the encode once. Code after the inserted `return` is unreachable, which WGSL accepts. A shader the\n * pattern does not match is returned unchanged.\n *\n * @param fragment - The skybox fragment WGSL, after Lite's own rotation and blur patches.\n * @returns The patched WGSL.\n *\n * @internal\n */\nexport function linearSkyboxFragment(fragment: string): string {\n const match = /\\b([A-Za-z_]\\w*)\\*=mesh\\.exposureLinear;/u.exec(fragment);\n if (match === null) {\n return fragment;\n }\n return `${fragment.slice(0, match.index)}return vec4<f32>(${match[1] ?? \"\"},1.0);${fragment.slice(match.index)}`;\n}\n\n/**\n * A fog configuration with its colour decoded the way Lite's PBR fog block decodes it.\n *\n * @param fog - The configuration the `Environment` installed, colour in sRGB.\n * @returns A fresh configuration, colour linear.\n *\n * @internal\n */\nexport function linearFogConfig(fog: FogConfig): FogConfig {\n return {\n mode: fog.mode,\n density: fog.density,\n start: fog.start,\n end: fog.end,\n color: [fog.color[0] ** 2.2, fog.color[1] ** 2.2, fog.color[2] ** 2.2],\n };\n}\n\n/**\n * Builds the output pass's fragment shader.\n *\n * @remarks\n * The curves are Lite's own WGSL (`ToneMapping.helpersWGSL`/`callWGSL`) and ignifx's AgX in the\n * same form (`./agx-tone-mapping.ts`, so both paths run one function), which read the exposure\n * from `scene.vImageInfos.x`; naming the uniform block `scene` lets them drop in unchanged. One\n * shader holds all of them and branches on a uniform, so a curve change uploads 16 bytes instead\n * of compiling a pipeline. The encode, clamp and contrast copy the PBR template's tail.\n *\n * @param autoExposure - Whether binding 2 holds the auto exposure texel (`./auto-exposure.ts`),\n * `log2` of a multiplier applied before the curve.\n * @returns The WGSL, with Lite's `effectFragment` entry point.\n *\n * @internal\n */\nexport function hdrOutputFragmentWgsl(autoExposure = false): string {\n return [\n AcesToneMapping.helpersWGSL,\n NeutralToneMapping.helpersWGSL,\n AGX_HELPERS_WGSL,\n \"struct HdrOutputUniforms{vImageInfos:vec4<f32>};\",\n \"@group(0)@binding(0)var<uniform>scene:HdrOutputUniforms;\",\n \"@group(0)@binding(1)var hdrColor:texture_2d<f32>;\",\n autoExposure ? \"@group(0)@binding(2)var autoExposure:texture_2d<f32>;\" : \"\",\n \"@fragment fn effectFragment(fragment:EffectVertexOutput)->@location(0)vec4<f32>{\",\n \"let texel=textureLoad(hdrColor,vec2<i32>(fragment.position.xy),0);\",\n \"var color=max(texel.rgb,vec3<f32>(0.0));\",\n autoExposure ? \"color*=exp2(textureLoad(autoExposure,vec2<i32>(0,0),0).r);\" : \"\",\n \"let curve=i32(scene.vImageInfos.z+0.5);\",\n `if(curve==${String(HDR_CURVE.standard)}){${StandardToneMapping.callWGSL}}`,\n `else if(curve==${String(HDR_CURVE.aces)}){${AcesToneMapping.callWGSL}}`,\n `else if(curve==${String(HDR_CURVE.neutral)}){${NeutralToneMapping.callWGSL}}`,\n `else if(curve==${String(HDR_CURVE.agx)}){${AGX_CALL_WGSL}}`,\n \"else{color*=scene.vImageInfos.x;}\",\n \"color=pow(color,vec3<f32>(1.0/2.2));\",\n \"color=clamp(color,vec3<f32>(0.0),vec3<f32>(1.0));\",\n \"let highContrast=color*color*(3.0-2.0*color);\",\n \"if(scene.vImageInfos.y<1.0){color=mix(vec3<f32>(0.5),color,scene.vImageInfos.y);}\",\n \"else{color=mix(color,highContrast,scene.vImageInfos.y-1.0);}\",\n \"color=max(color,vec3<f32>(0.0));\",\n \"return vec4<f32>(color,texel.a);\",\n \"}\",\n ].join(\"\\n\");\n}\n\n/**\n * The curve number for a scene's image processing.\n *\n * @remarks\n * Tone mapping switched on with no curve named is Lite's standard curve (`pbr-renderable.js`). A\n * custom Lite curve the output pass does not know falls back to the standard one.\n *\n * @param processing - The scene's image processing.\n * @returns One of {@link HDR_CURVE}.\n *\n * @internal\n */\nexport function hdrCurveOf(processing: Pick<ImageProcessingConfig, \"toneMappingEnabled\" | \"toneMapping\">): number {\n if (!processing.toneMappingEnabled) {\n return HDR_CURVE.none;\n }\n const id = processing.toneMapping?.id;\n if (id === AcesToneMapping.id) {\n return HDR_CURVE.aces;\n }\n if (id === AGX_TONE_MAPPING_ID) {\n return HDR_CURVE.agx;\n }\n return id === NeutralToneMapping.id ? HDR_CURVE.neutral : HDR_CURVE.standard;\n}\n\n/**\n * Writes the output pass's uniforms and says whether they changed.\n *\n * @param processing - The scene's image processing.\n * @param out - The four floats: exposure, contrast, curve, padding.\n * @returns `true` when `out` now differs from what it held.\n *\n * @internal\n */\nexport function writeHdrOutputUniforms(processing: ImageProcessingConfig, out: Float32Array): boolean {\n const curve = hdrCurveOf(processing);\n if (out[0] === processing.exposure && out[1] === processing.contrast && out[2] === curve) {\n return false;\n }\n out[0] = processing.exposure;\n out[1] = processing.contrast;\n out[2] = curve;\n return true;\n}\n\n/**\n * Builds the HDR render path and appends it to the scene's frame graph.\n *\n * @remarks\n * The same contract as `installOffscreenRenderPath` in `./render-path.ts`: call it right after\n * `createSceneContext(engine, { defaultRenderTask: false })` and before `registerScene`. It also\n * installs Lite's material-plugin bridges, which the linear-output plugin needs before the scene is\n * registered. With MSAA on, the scene draws into a multisampled `rgba16float` target that resolves\n * into the sampled one.\n *\n * @param engine - The engine, which is also the primary surface.\n * @param scene - The scene created with no default render task.\n * @param installAutoExposure - Builds the auto exposure passes over the HDR texture, between the\n * scene task and the output tasks (`./auto-exposure.ts`); omitted when auto exposure is off.\n * @returns The presenter, with its {@link ScenePresenter.hdr} handle set.\n *\n * @internal\n */\nexport function installHdrRenderPath(\n engine: EngineContext,\n scene: SceneContext,\n installAutoExposure?: (hdrTexture: Texture2D) => AutoExposurePass,\n): ScenePresenter {\n enableMaterialPlugins(scene);\n markHdrScene(scene);\n installLinearSkybox(scene);\n const hdr = createSurfaceRenderTargetTexture(engine, {\n lbl: \"ignifx:scene-hdr\",\n format: HDR_SCENE_FORMAT,\n samples: 1,\n size: engine,\n });\n const isMultisampled = engine.msaaSamples > 1;\n const config: { name: string; rt: RenderTarget; rst?: RenderTarget; depth?: RenderTarget } = {\n name: \"scene\",\n rt: hdr.rt,\n };\n if (isMultisampled) {\n config.rt = createRenderTarget({\n lbl: \"ignifx:scene-hdr-msaa\",\n format: HDR_SCENE_FORMAT,\n dFormat: DEPTH_STENCIL_FORMAT,\n samples: engine.msaaSamples,\n size: engine,\n });\n config.rst = hdr.rt;\n } else {\n config.depth = createRenderTarget({\n lbl: \"ignifx:scene-depth\",\n dFormat: DEPTH_STENCIL_FORMAT,\n samples: 1,\n size: engine,\n });\n }\n const sceneTask: Task = createRenderTask(config, engine, scene);\n addTask(scene, sceneTask);\n const autoExposure = installAutoExposure?.(hdr.texture) ?? null;\n\n const effect: EffectWrapper = createEffectWrapper(engine, {\n name: \"ignifx:hdr-output\",\n fragmentWGSL: hdrOutputFragmentWgsl(autoExposure !== null),\n bindings: [\n { name: \"hdrOutput\", binding: 0, kind: \"uniform\", uniformByteLength: UNIFORM_FLOATS * 4 },\n { name: \"hdrColor\", binding: 1, kind: \"texture\" },\n ...(autoExposure === null\n ? []\n : [\n {\n name: \"autoExposure\",\n binding: 2,\n kind: \"texture\" as const,\n textureSampleType: \"unfilterable-float\" as const,\n },\n ]),\n ],\n });\n setEffectTexture(effect, 1, hdr.texture);\n if (autoExposure !== null) {\n setEffectTexture(effect, 2, autoExposure.exposureTexture);\n }\n // What the output pass reads: the scene, or the last linear effect a PostProcessStack put first.\n let outputSource: Texture2D | null = null;\n // A resize swaps the texture behind the facade; the wrapper's cached bind group still holds the\n // old view until a texture write marks it dirty.\n onRenderTargetTextureResize(hdr, () => {\n setEffectTexture(effect, 1, outputSource ?? hdr.texture);\n });\n const uniforms = new Float32Array(UNIFORM_FLOATS);\n uniforms[0] = Number.NaN;\n writeHdrOutputUniforms(scene.imageProcessing, uniforms);\n setEffectUniforms(effect, uniforms);\n\n const sceneColor = createRenderTarget({ lbl: \"ignifx:scene-color\", format: engine.format, samples: 1, size: engine });\n const toChain: Task = createEffectRenderTask(\n { name: HDR_OUTPUT_TASK_NAMES.toChain, effect, target: sceneColor, clear: true },\n engine,\n scene,\n );\n const toSwapchain: Task = createEffectRenderTask(\n { name: HDR_OUTPUT_TASK_NAMES.toSwapchain, effect, target: engine.scRT, clear: true },\n engine,\n scene,\n );\n addTask(scene, toChain);\n addTask(scene, toSwapchain);\n toChain.executionEnabled = false;\n\n const plugins: LinearPlugins = {\n pbr: createLinearOutputPlugin(),\n unlit: createUnlitLinearPlugin(),\n standard: createStandardLinearPlugin(),\n };\n let linearFog: FogConfig | null = null;\n const handle: HdrOutputHandle = {\n sceneTexture: hdr.texture,\n exposureTexture: autoExposure?.exposureTexture ?? null,\n sceneTarget: hdr.rt,\n sceneTask,\n sceneTargetTexture: hdr,\n update(isSceneRegistered: boolean): void {\n autoExposure?.update();\n if (writeHdrOutputUniforms(scene.imageProcessing, uniforms)) {\n setEffectUniforms(effect, uniforms);\n }\n // The `Environment` installs a fresh sRGB config on every change; it is swapped for a decoded\n // copy once, before the frame reads it (`setFog` re-registers nothing it already has).\n const fog = scene.fog;\n if (fog !== null && fog !== linearFog) {\n linearFog = linearFogConfig(fog);\n setFog(scene, linearFog);\n }\n attachLinearOutput(scene, plugins, isSceneRegistered);\n },\n insertLinearTask(task: Task, isFrameGraphBuilt: boolean): void {\n addTaskBefore(scene, task, toChain);\n if (isFrameGraphBuilt) {\n buildFrameGraphTask(getFrameGraph(scene), task);\n }\n },\n setOutputSource(texture: Texture2D | null): void {\n if (texture === outputSource) {\n return;\n }\n outputSource = texture;\n setEffectTexture(effect, 1, texture ?? hdr.texture);\n },\n };\n let isPresentEnabled = true;\n return {\n sceneColor,\n swapchain: engine.scRT,\n setPresentEnabled(enabled: boolean): void {\n isPresentEnabled = enabled;\n toSwapchain.executionEnabled = enabled;\n toChain.executionEnabled = !enabled;\n },\n get isPresentEnabled(): boolean {\n return isPresentEnabled;\n },\n hdr: handle,\n scenePass: { task: sceneTask, target: hdr.rt, format: HDR_SCENE_FORMAT },\n };\n}\n\n/** The two shared plugins the per-frame walk hands out. */\ninterface LinearPlugins {\n /** The save, restore and fog for PBR materials, PBR skyboxes included. */\n readonly pbr: MaterialPlugin;\n /** The recompute and fog for unlit PBR materials. */\n readonly unlit: MaterialPlugin;\n /** The decode for Standard materials. */\n readonly standard: MaterialPlugin;\n}\n\n/**\n * Makes Lite's environment skyboxes write linear colour (see {@link linearSkyboxFragment}).\n *\n * @remarks\n * Lite composes a skybox's fragment through `scene._environmentSkyboxShaderComposer`, which runs the\n * loaders in `scene._environmentSkyboxShaderPatchLoaders` in order\n * (`lib/material/pbr/environment-skybox-shader-composer.js`). Neither field is declared in\n * `index.d.ts`, and the composer is created only by Lite's own registration, which also prepends\n * the scene uniforms the `.env` skybox needs. `setEnvironmentRotation(scene, 0)` is that\n * registration with no visible effect (rotation 0 is what the scene has); the `Environment`\n * overwrites it with its own rotation later. The patch is installed before any environment loads,\n * and pinned by `test/render/hdr-coverage.browser.test.ts`.\n *\n * @param scene - The HDR scene.\n */\nfunction installLinearSkybox(scene: SceneContext): void {\n setEnvironmentRotation(scene, 0);\n // Boundary assertion (coding standards §5.2): the loader list is a plain array Lite keeps on the\n // scene object it created; see the remarks for the `lib/` file that reads it.\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n const slots = scene as SceneContext & SkyboxPatchSlots;\n // oxlint-disable-next-line no-underscore-dangle\n const loaders = (slots._environmentSkyboxShaderPatchLoaders ??= []);\n loaders[SKYBOX_PATCH_ORDER] = () => Promise.resolve({ _apply: linearSkyboxFragment });\n}\n\n/** The undeclared Lite scene field the skybox patch writes (adapter-internal mirror, standards §5.1). */\ninterface SkyboxPatchSlots {\n /** Lite's skybox shader patches, by order; each resolves to an object whose `_apply` edits the WGSL. */\n _environmentSkyboxShaderPatchLoaders?: (SkyboxPatchLoader | undefined)[];\n}\n\n/** One entry of Lite's skybox patch list. */\ntype SkyboxPatchLoader = () => Promise<{ readonly _apply: (fragment: string, kind: string) => string }>;\n\n/**\n * Gives every PBR and Standard material in the scene its linear-output plugin, once.\n *\n * @remarks\n * A walk rather than a hook at material creation, because materials come from several places\n * (material assets, glTF models, `.lite` code) and a surface shader replaces a material's whole\n * plugin list; a material that lost the plugin gets it back on the next frame. A PBR skybox\n * (`setPbrSkybox`) is a PBR material and gets the PBR plugin. Lite's mesh factories leave\n * `material` `null` until one is assigned.\n *\n * @param scene - The scene to walk.\n * @param shared - The shared plugins.\n * @param isSceneRegistered - Whether a patched material's pipelines must be rebuilt.\n */\nfunction attachLinearOutput(scene: SceneContext, shared: LinearPlugins, isSceneRegistered: boolean): void {\n const meshes = scene.meshes;\n for (let index = 0; index < meshes.length; index += 1) {\n const material = meshes[index]?.material;\n // Declared non-null, but Lite's mesh factories create meshes with `material: null`\n // (`lib/mesh/mesh-factories.js`), and `isPbrMaterial(null)` throws.\n // oxlint-disable-next-line typescript/no-unnecessary-condition\n if (material === undefined || material === null) {\n continue;\n }\n let plugin: MaterialPlugin;\n if (isPbrMaterial(material)) {\n plugin = getPbrUnlit(material) === undefined ? shared.pbr : shared.unlit;\n } else if (isStandardMaterial(material)) {\n plugin = shared.standard;\n } else {\n continue;\n }\n const current = material.plugins ?? [];\n // A PBR material that became unlit, or stopped being so, swaps one plugin for the other.\n let stale: MaterialPlugin | null = null;\n if (plugin === shared.pbr) {\n stale = shared.unlit;\n } else if (plugin === shared.unlit) {\n stale = shared.pbr;\n }\n const hasStale = stale !== null && current.includes(stale);\n if (current.includes(plugin) && !hasStale) {\n continue;\n }\n const kept = hasStale ? current.filter((other) => other !== stale) : current;\n material.plugins = kept.includes(plugin) ? kept : [...kept, plugin];\n if (plugin === shared.standard) {\n // The Standard bridge bakes a plugin signature per material, which only happens for meshes it\n // saw at `enableMaterialPlugins` or at a material change; this bakes and rebuilds it now.\n void reconcileMaterialPlugins(scene, material);\n continue;\n }\n if (isSceneRegistered) {\n rebuildMaterialPipelines(scene, material);\n }\n }\n}\n"],"mappings":"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"}
@@ -168,6 +168,8 @@ const CoreErrorCode = {
168
168
  physicsCallbackOutsideFixedStep: "IGX-0409",
169
169
  /** A second, different simulation scene was handed to a world that already has one. */
170
170
  simulationSceneAlreadySet: "IGX-0410",
171
+ /** One `Extension` object was handed to a second app while the first still runs it. */
172
+ extensionInstalledTwice: "IGX-0411",
171
173
  /** An asset's value was read before the asset finished loading. */
172
174
  assetNotLoaded: "IGX-0501",
173
175
  /** An asset load was aborted through its `AbortSignal`. */
@@ -260,6 +262,14 @@ const CoreErrorCode = {
260
262
  instancingLodWithoutCulling: "IGX-0727",
261
263
  /** `app.renderer.openOverlay()` was called on a headless app, or before `app.start()` registered the render scene. */
262
264
  overlayNeedsRenderScene: "IGX-0728",
265
+ /** A render texture was rendered into or read on a headless app, or before `app.start()` started the render loop. */
266
+ renderTextureNeedsRenderLoop: "IGX-0729",
267
+ /** `app.renderer.createRenderTexture` was given a side that is not a whole number from 1 to 4096. */
268
+ invalidRenderTextureSize: "IGX-0730",
269
+ /** A render texture was used after `dispose()`, or with another app's renderer. */
270
+ renderTextureUnusable: "IGX-0731",
271
+ /** `app.renderer.renderToTexture` was given a camera that is not attached to an entity. */
272
+ renderTextureCameraDetached: "IGX-0732",
263
273
  /** The host exposes no Web Crypto implementation. */
264
274
  cryptoUnavailable: "IGX-1420",
265
275
  /** A storage namespace name is not a legal namespace segment. */
@@ -334,6 +344,7 @@ const CORE_ERROR_MESSAGES = {
334
344
  "IGX-0408": "The {section} settings section is invalid: {issues}.",
335
345
  "IGX-0409": "Physics callbacks are dispatched inside the fixed loop only; {callback} was not.",
336
346
  "IGX-0410": "A world has one simulation scene, and this world already has a different one.",
347
+ "IGX-0411": "The {extension} extension object is already installed in another app that has not been disposed.",
337
348
  "IGX-0501": "The asset {asset} has no value yet because it is still loading.",
338
349
  "IGX-0502": "Loading {asset} was aborted.",
339
350
  "IGX-0503": "The app that owned the asset {asset} was disposed before loading finished.",
@@ -378,6 +389,10 @@ const CORE_ERROR_MESSAGES = {
378
389
  "IGX-0726": "{samplers} plugin samplers are declared; {budget} fit beside a textured PBR material.",
379
390
  "IGX-0727": "{entity} declares an InstancedMeshRenderer lod with gpuCulling off; the LOD mesh never draws. Turn gpuCulling on.",
380
391
  "IGX-0728": "openOverlay() needs a canvas-backed app whose render scene is registered.",
392
+ "IGX-0729": "{member} needs a canvas-backed app whose render loop is running.",
393
+ "IGX-0730": "A render texture of {width}x{height}: each side must be a whole number from 1 to {max}.",
394
+ "IGX-0731": "{member}: the render texture is disposed or belongs to another app.",
395
+ "IGX-0732": "renderToTexture() needs a camera attached to an entity.",
381
396
  "IGX-1420": "This host does not expose Web Crypto.",
382
397
  "IGX-1421": "{namespace} is not a valid storage namespace.",
383
398
  "IGX-1422": "That storage key is empty, too long, or contains a control character.",
@@ -562,4 +577,4 @@ function assertNever(value, what) {
562
577
  //#endregion
563
578
  export { CORE_ERROR_MESSAGES as a, THIRD_PARTY_ERROR_PREFIX as c, isIgnifxError as i, isValidErrorCode as l, assertNever as n, CoreErrorCode as o, formatErrorMessage as r, ErrorRange as s, IgnifxError as t };
564
579
 
565
- //# sourceMappingURL=ignifx-error-Dq2qJMkZ.js.map
580
+ //# sourceMappingURL=ignifx-error-oYdVnT1S.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ignifx-error-oYdVnT1S.js","names":[],"sources":["../src/errors/error-codes.ts","../src/errors/ignifx-error.ts"],"sourcesContent":["/**\n * The error code registry data: the subsystem ranges from\n * `docs/architecture/15-devtools-and-diagnostics.md` §1, the codes `@ignifx/core` itself owns, and\n * the format rule every code must satisfy.\n *\n * This module is pure data plus one predicate; it imports nothing, which is what lets\n * {@link IgnifxError} depend on it without a cycle (coding standards §4).\n */\n\n/**\n * The two-digit prefix each subsystem owns inside the `IGX-####` space\n * (`docs/architecture/15-devtools-and-diagnostics.md` §1). A code is the prefix followed by a\n * two-digit ordinal, so `rendering` owns `IGX-0700` through `IGX-0799`.\n *\n * @example\n * ```ts\n * const code = `IGX-${ErrorRange.rendering}01` satisfies ErrorCode; // \"IGX-0701\"\n * ```\n *\n * @public\n */\nexport const ErrorRange = {\n /** App lifecycle, phases, time, coroutines, destruction. */\n lifecycle: \"01\",\n /** Components, scripts, and their registration. */\n components: \"02\",\n /** Scenes, scene instances, layers. */\n scenes: \"03\",\n /** The extension host and its contract. */\n extensions: \"04\",\n /** Asset handles, loaders, and caching. */\n assets: \"05\",\n /** Schemas, scene/prefab JSON, references. */\n serialization: \"06\",\n /** The renderer and the Babylon Lite adapter. */\n rendering: \"07\",\n /** Input devices, actions, and bindings. */\n input: \"08\",\n /** 3D physics. */\n physics: \"09\",\n /** Audio buses, sources, and clips. */\n audio: \"10\",\n /** The 2D toolkit. */\n twoD: \"11\",\n /** The 3D toolkit. */\n threeD: \"12\",\n /** The UI overlay. */\n ui: \"13\",\n /** Platform integration (browser, Electron). */\n platform: \"14\",\n /** Devtools, logging, and diagnostics. */\n devtools: \"15\",\n /** Terrain assets, chunks, and queries. */\n terrain: \"16\",\n /** Particle systems, 3D and 2D. */\n particles: \"17\",\n /** The editor host package and its Vite plugin. */\n editorHost: \"18\",\n} as const;\n\n/**\n * The union of the two-digit subsystem prefixes declared by `ErrorRange`.\n *\n * @public\n */\nexport type ErrorRange = (typeof ErrorRange)[keyof typeof ErrorRange];\n\n/**\n * The first digit of the range reserved for extensions published outside the `@ignifx` scope\n * (`IGX-9000` through `IGX-9999`). First-party subsystems never allocate here.\n *\n * @public\n */\nexport const THIRD_PARTY_ERROR_PREFIX = \"9\";\n\n/**\n * The shape of every ignifx diagnostic code: the literal `IGX-` followed by four digits.\n *\n * @remarks\n * The template literal is the widest useful type; it accepts strings such as `\"IGX-1\"` that are not\n * real codes. {@link isValidErrorCode} is the runtime check, `CoreErrorCode` is the narrowed\n * string-literal union for the codes this package owns, and extensions narrow their own the same\n * way.\n *\n * @public\n */\nexport type ErrorCode = `IGX-${number}`;\n\n/**\n * Every diagnostic code `@ignifx/core` can throw, keyed by an intention-revealing name so call\n * sites read as prose and the compiler catches typos (coding standards §5.2 — `as const` objects in\n * place of enums).\n *\n * @example\n * ```ts\n * throw new IgnifxError(CoreErrorCode.mutationAfterDestroy, \"The entity has been destroyed.\", {\n * context: { entity: entity.uid },\n * });\n * ```\n *\n * @remarks\n * Code blocks reserved for other first-party packages, which cannot import this table\n * (`docs/architecture/00-overview.md` §2): `@ignifx/cli` owns `IGX-1401`–`IGX-1419`; `@ignifx/electron`\n * owns `IGX-1460`–`IGX-1499` (core's own platform codes therefore stop at `IGX-1459`); `@ignifx/devtools`\n * owns `IGX-1550`–`IGX-1599` (core's own devtools-range codes stop at `IGX-1549`);\n * `@ignifx/vite-plugin` owns `IGX-0550`–`IGX-0599` and `IGX-0650`–`IGX-0699`. Core allocates its\n * own codes from the bottom of each range and, in the platform range, from `IGX-1420` upward —\n * which is where `app.platform` and `app.storage` live, because storage is a *platform* service:\n * the same three calls resolve to IndexedDB, a directory, or the Electron bridge depending only on\n * the host, so a failure is a platform failure and not a serialization or asset one.\n *\n * @public\n */\nexport const CoreErrorCode = {\n /** An entity, component, or app was used after it had been destroyed or disposed. */\n mutationAfterDestroy: \"IGX-0101\",\n /** `destroyImmediate()` was called from inside a lifecycle callback. */\n destroyImmediateInCallback: \"IGX-0102\",\n /** A signal handler asked for deferred delivery on a signal that has no scheduler. */\n deferredSignalWithoutScheduler: \"IGX-0103\",\n /** A signal handler threw and no handler-error reporter was installed. */\n signalHandlerThrew: \"IGX-0104\",\n /** `app.step()` was called while Babylon Lite's render loop was driving the frames. */\n stepOutsideHeadless: \"IGX-0105\",\n /** An app was used after `app.dispose()` had run. */\n appDisposed: \"IGX-0106\",\n /** A part of the app was reached before `createApp()` had finished building it. */\n appNotReady: \"IGX-0107\",\n /** A `Time` property was set to a value outside its documented domain. */\n invalidTimeValue: \"IGX-0108\",\n /** A `app.tweens.to(...)` option was outside its documented domain. */\n invalidTweenOptions: \"IGX-0109\",\n /** A tweened field is not a number, `Vec2`, `Vec3`, or `Quat`, or is not writable. */\n tweenFieldNotTweenable: \"IGX-0110\",\n /** A coroutine was started in an edit-mode app by a script whose class does not run in edit mode. */\n coroutineInEditMode: \"IGX-0111\",\n /** A component declared through `requires` is missing from the entity. */\n requiredComponentMissing: \"IGX-0201\",\n /** A second instance of a component type that does not allow multiples was added. */\n multipleComponentsNotAllowed: \"IGX-0202\",\n /** Two component types were registered under the same `typeId`. */\n duplicateComponentTypeId: \"IGX-0203\",\n /** A component without a `typeId` was serialized. */\n componentTypeIdMissing: \"IGX-0204\",\n /** `Transform` was removed or disabled; every entity must keep exactly one enabled transform. */\n transformIsNotRemovable: \"IGX-0205\",\n /** A component's engine-assigned state was read before the engine attached it to an entity. */\n componentNotAttached: \"IGX-0206\",\n /** A hot-reloaded class kept the `\"patch\"` policy while its schema shape changed. */\n hotReloadSchemaChanged: \"IGX-0207\",\n /** `app.hotReload.apply()` was called from inside a lifecycle callback. */\n hotReloadInsideCallback: \"IGX-0208\",\n /** A component class's `static requires` chain loops, through the class itself or a class it requires. */\n requiresCycle: \"IGX-0209\",\n /** A scene was instantiated before it had finished loading. */\n sceneNotLoaded: \"IGX-0301\",\n /** Instantiating a scene would place an instance inside itself. */\n sceneInstanceCycle: \"IGX-0302\",\n /** A layer name that the project settings do not declare was used. */\n unknownLayer: \"IGX-0303\",\n /** Two layer slots were given the same name. */\n duplicateLayerName: \"IGX-0304\",\n /** The project settings declare more layer names than the 32 available slots. */\n tooManyLayers: \"IGX-0305\",\n /** Reparenting an entity under its own descendant would make the scene tree cyclic. */\n parentingCycle: \"IGX-0306\",\n /** A scene file names a component `typeId` that no extension has registered. */\n unknownComponentTypeId: \"IGX-0307\",\n /** A file handed to the scene loader does not carry the `ignifx.scene` format header. */\n notASceneFile: \"IGX-0308\",\n /** An operation that only accepts a scene root was given an entity that has a parent. */\n entityIsNotSceneRoot: \"IGX-0309\",\n /** Two extensions defined the same app property. */\n appPropertyAlreadyDefined: \"IGX-0401\",\n /** The `requires` graph of the registered extensions contains a cycle. */\n extensionRequiresCycle: \"IGX-0402\",\n /** An extension declares a `requires` entry that was never registered. */\n extensionMissing: \"IGX-0403\",\n /** An extension's `engine` range does not match the running core version. */\n extensionEngineMismatch: \"IGX-0404\",\n /** `ctx.require()` asked for a service that no earlier extension registered. */\n serviceNotRegistered: \"IGX-0405\",\n /** Two extensions were registered under the same name. */\n duplicateExtensionName: \"IGX-0406\",\n /** `ctx.settings()` asked for a settings section that was never registered. */\n unknownSettingsSection: \"IGX-0407\",\n /** A project settings section did not validate against the schema its extension registered. */\n invalidSettings: \"IGX-0408\",\n /** An extension dispatched a physics callback from outside the fixed loop. */\n physicsCallbackOutsideFixedStep: \"IGX-0409\",\n /** A second, different simulation scene was handed to a world that already has one. */\n simulationSceneAlreadySet: \"IGX-0410\",\n /** One `Extension` object was handed to a second app while the first still runs it. */\n extensionInstalledTwice: \"IGX-0411\",\n /** An asset's value was read before the asset finished loading. */\n assetNotLoaded: \"IGX-0501\",\n /** An asset load was aborted through its `AbortSignal`. */\n assetLoadAborted: \"IGX-0502\",\n /** An asset promise outlived the app that owned it. */\n assetAppDisposed: \"IGX-0503\",\n /** No registered loader claims the address's type or extension. */\n assetNoLoader: \"IGX-0504\",\n /** An asset load failed after its last retry. */\n assetLoadFailed: \"IGX-0505\",\n /** Two loaders were registered for the same asset type. */\n duplicateAssetLoader: \"IGX-0506\",\n /** A `.mesh.json` file names an unknown primitive, or an option the primitive does not take or cannot use. */\n invalidMeshFile: \"IGX-0507\",\n /** A serialized number was `NaN` or infinite. */\n nonFiniteNumber: \"IGX-0601\",\n /** A serialized `$entity`/`$component` reference could not be resolved. */\n unresolvedReference: \"IGX-0602\",\n /** A scene, prefab, or manifest declares a format version this build cannot read. */\n unsupportedFormatVersion: \"IGX-0603\",\n /** A scene instance's override hash does not match the scene file it was recorded against. */\n instanceHashMismatch: \"IGX-0604\",\n /** A value had the wrong JavaScript or JSON type for its schema field kind. */\n schemaTypeMismatch: \"IGX-0605\",\n /** A value had the right type but fell outside its schema field's declared value domain. */\n schemaOutOfRange: \"IGX-0606\",\n /**\n * A property bag named a field the schema does not declare, or a schema declaration named a field\n * it may not use: not identifier-like, a `Component`/`Script` member, or an `Object.prototype`\n * member such as `constructor` or `__proto__`.\n */\n schemaUnknownField: \"IGX-0607\",\n /** A scene file failed structural validation against the generated scene-file JSON Schema. */\n sceneFileInvalid: \"IGX-0608\",\n /** An instance override declares a `path` the override grammar does not accept. */\n invalidOverridePath: \"IGX-0609\",\n /** WebGPU is not available in the current environment. */\n webGpuUnavailable: \"IGX-0701\",\n /** A runtime handle was used after disposal, or was not created by ignifx. */\n invalidRuntime: \"IGX-0702\",\n /** Shadows were requested from a light kind Babylon Lite cannot shadow. */\n shadowsUnsupportedForLight: \"IGX-0703\",\n /** A rendering feature opt-in was requested after the render scene had been registered. */\n renderingFeatureTooLate: \"IGX-0704\",\n /** A second `Environment` was enabled in one world; the most recent one wins. */\n multipleEnvironments: \"IGX-0705\",\n /** A world rendered with no enabled camera, so nothing was drawn. */\n noEnabledCamera: \"IGX-0706\",\n /** A screenshot was requested with no render loop running, so no frame will ever be presented. */\n screenshotNeedsRenderLoop: \"IGX-0707\",\n /** A material file declares a family this build cannot construct. */\n unsupportedMaterialKind: \"IGX-0708\",\n /** An asset file does not carry the format header its loader requires. */\n invalidAssetFile: \"IGX-0709\",\n /** A `PostProcessStack` was attached without the `postProcessing` rendering feature. */\n postProcessingFeatureOff: \"IGX-0710\",\n /** An `Environment.skybox` asks for a background the environment it installed cannot draw. */\n skyboxFixedAtLoad: \"IGX-0711\",\n /** A shader material was asked for a uniform, texture, or storage buffer its shader never declared. */\n unknownShaderBinding: \"IGX-0712\",\n /** A shader uniform was written with a value whose shape does not match its declared type. */\n shaderValueMismatch: \"IGX-0713\",\n /** A shader declares a main-light uniform, but the world has no enabled directional light. */\n shaderLightUniformWithoutLight: \"IGX-0714\",\n /** A shader failed to compile or rebuild; the previous material stays in use. */\n shaderCompileFailed: \"IGX-0715\",\n /** A surface shader was attached without the `materialPlugins` rendering feature. */\n surfaceShaderFeatureOff: \"IGX-0716\",\n /** An `InstancedMeshRenderer` setting Lite fixes at scene registration was changed afterwards. */\n instancingSettingTooLate: \"IGX-0717\",\n /** A shader-material method was called on a PBR or Standard material. */\n notAShaderMaterial: \"IGX-0718\",\n /** A `.wgsl` file carries an `@ignifx` pragma this build cannot read. */\n invalidShaderPragma: \"IGX-0719\",\n /** A storage buffer update reaches past the buffer's capacity. */\n storageBufferOutOfRange: \"IGX-0720\",\n /** More instances were written to an `InstancedMeshRenderer` than its capacity holds. */\n instancedCapacityExceeded: \"IGX-0721\",\n /** Pixel data handed to a texture does not match its declared size. */\n invalidPixelData: \"IGX-0722\",\n /** A surface shader cannot run on its host: no hook, a hook the host lacks, or a Standard host. */\n surfaceHookMissing: \"IGX-0723\",\n /** A shader-material mesh was left out of an ESM shadow caster list, which Lite cannot render for it. */\n shaderMaterialEsmCasterSkipped: \"IGX-0724\",\n /** A `MeshAsset` vertex update named a range the geometry cannot hold. */\n invalidGeometryUpdate: \"IGX-0725\",\n /** The surface shaders attached to one material declare more samplers than fit beside the host material. */\n surfaceSamplerBudgetExceeded: \"IGX-0726\",\n /** An `InstancedMeshRenderer` declares a LOD partner with `gpuCulling` off, so the partner never draws. */\n instancingLodWithoutCulling: \"IGX-0727\",\n /** `app.renderer.openOverlay()` was called on a headless app, or before `app.start()` registered the render scene. */\n overlayNeedsRenderScene: \"IGX-0728\",\n /** A render texture was rendered into or read on a headless app, or before `app.start()` started the render loop. */\n renderTextureNeedsRenderLoop: \"IGX-0729\",\n /** `app.renderer.createRenderTexture` was given a side that is not a whole number from 1 to 4096. */\n invalidRenderTextureSize: \"IGX-0730\",\n /** A render texture was used after `dispose()`, or with another app's renderer. */\n renderTextureUnusable: \"IGX-0731\",\n /** `app.renderer.renderToTexture` was given a camera that is not attached to an entity. */\n renderTextureCameraDetached: \"IGX-0732\",\n /** The host exposes no Web Crypto implementation. */\n cryptoUnavailable: \"IGX-1420\",\n /** A storage namespace name is not a legal namespace segment. */\n storageInvalidNamespace: \"IGX-1421\",\n /** A storage key is empty, too long, or contains a control character. */\n storageInvalidKey: \"IGX-1422\",\n /** A value handed to `app.storage.set` has no JSON form. */\n storageValueNotSerializable: \"IGX-1423\",\n /** The storage backend refused a write because the host is out of quota or disk space. */\n storageQuotaExceeded: \"IGX-1424\",\n /** The storage backend failed for a reason the engine cannot classify. */\n storageBackendFailed: \"IGX-1425\",\n /** A stored value could not be read back; the store was damaged or written by something else. */\n storageValueCorrupt: \"IGX-1426\",\n /** An error code was registered twice. */\n duplicateErrorCode: \"IGX-1501\",\n /** An error code does not match `IGX-####` in a known range. */\n malformedErrorCode: \"IGX-1502\",\n /** A diagnostics counter group was registered twice. */\n duplicateDiagnosticsGroup: \"IGX-1503\",\n /** A diagnostics counter name was not declared when its group was registered. */\n unknownDiagnosticsCounter: \"IGX-1504\",\n /** A `switch` over a union reached a case the type system said was impossible. */\n unreachableCase: \"IGX-1505\",\n /** `app.hotReload.reloadScene()` was given an instance that was not built from a scene asset. */\n sceneNotReloadable: \"IGX-1506\",\n} as const;\n\n/**\n * The union of the codes `@ignifx/core` owns. Use it to narrow `catch` blocks to core failures.\n *\n * @public\n */\nexport type CoreErrorCode = (typeof CoreErrorCode)[keyof typeof CoreErrorCode];\n\n/**\n * The one-line message template for every `CoreErrorCode`. Templates name context keys in\n * braces (`{entity}`); the throwing call site substitutes the values it has and puts the same\n * identifiers in {@link IgnifxError.context} so production builds stay useful without the prose.\n *\n * @public\n */\nexport const CORE_ERROR_MESSAGES: Readonly<Record<CoreErrorCode, string>> = {\n \"IGX-0101\": \"{target} has been destroyed and can no longer be used.\",\n \"IGX-0102\": \"destroyImmediate() cannot run inside the {phase} callback; use destroy() instead.\",\n \"IGX-0103\": \"Deferred signal delivery needs a scheduler; construct the signal with a deferred queue.\",\n \"IGX-0104\": \"A signal handler threw.\",\n \"IGX-0105\": \"step() is only available in headless mode or while the render loop is stopped.\",\n \"IGX-0106\": \"The app has been disposed; {member} is no longer available.\",\n \"IGX-0107\": \"{member} is not available until createApp() resolves.\",\n \"IGX-0108\": \"{property} must be {domain}; got {value}.\",\n \"IGX-0109\": \"The tween option {option} must be {domain}; got {value}.\",\n \"IGX-0110\": \"{field} is not a number, Vec2, Vec3, or Quat on the tween target.\",\n \"IGX-0111\": \"{script} cannot start a coroutine in edit mode because its class does not run in edit mode.\",\n \"IGX-0201\": \"{component} requires {required} on the same entity.\",\n \"IGX-0202\": \"{component} does not allow multiple instances on one entity.\",\n \"IGX-0203\": \"The component type id {typeId} is already registered by {owner}.\",\n \"IGX-0204\": \"{component} cannot be serialized because it has no typeId.\",\n \"IGX-0205\": \"Transform cannot be removed or disabled.\",\n \"IGX-0206\": \"{component} is not attached to an entity yet.\",\n \"IGX-0207\":\n '{component} changed its schema shape under the \"patch\" hot-reload policy; its instances were re-created.',\n \"IGX-0208\": \"app.hotReload.apply() cannot run inside the {phase} callback; apply it between frames.\",\n \"IGX-0209\": \"{component} has a static requires cycle: {cycle}.\",\n \"IGX-0301\": \"The scene {scene} is not loaded yet.\",\n \"IGX-0302\": \"Instantiating {scene} under {entity} would nest the scene inside itself.\",\n \"IGX-0303\": \"{layer} is not a layer declared in the project settings.\",\n \"IGX-0304\": \"The layer name {layer} is declared twice.\",\n \"IGX-0305\": \"The project settings declare {count} layers; at most {limit} fit in the 32 slots.\",\n \"IGX-0306\": \"{entity} cannot be parented to {parent}, which is inside its own subtree.\",\n \"IGX-0307\": \"{typeId} is not a registered component type.\",\n \"IGX-0308\": \"{file} is not an ignifx scene file.\",\n \"IGX-0309\": \"{entity} is not a scene root; only roots can move between scene instances.\",\n \"IGX-0401\": \"The app property {property} is already defined by {owner}.\",\n \"IGX-0402\": \"The extension requires graph contains a cycle: {cycle}.\",\n \"IGX-0403\": \"{extension} requires {required}, which is not registered.\",\n \"IGX-0404\": \"{extension} supports engine {range} but the running core is {version}.\",\n \"IGX-0405\": \"The service {service} required by {extension} is not registered.\",\n \"IGX-0406\": \"The extension name {extension} is registered twice.\",\n \"IGX-0407\": \"{section} is not a registered settings section.\",\n \"IGX-0408\": \"The {section} settings section is invalid: {issues}.\",\n \"IGX-0409\": \"Physics callbacks are dispatched inside the fixed loop only; {callback} was not.\",\n \"IGX-0410\": \"A world has one simulation scene, and this world already has a different one.\",\n \"IGX-0411\": \"The {extension} extension object is already installed in another app that has not been disposed.\",\n \"IGX-0501\": \"The asset {asset} has no value yet because it is still loading.\",\n \"IGX-0502\": \"Loading {asset} was aborted.\",\n \"IGX-0503\": \"The app that owned the asset {asset} was disposed before loading finished.\",\n \"IGX-0504\": \"No loader is registered for {asset}.\",\n \"IGX-0505\": \"Loading {asset} from {url} failed after {attempts} attempts.\",\n \"IGX-0506\": \"A loader for the asset type {type} is already registered.\",\n \"IGX-0507\": \"{file} is not a valid mesh file: {problem}\",\n \"IGX-0601\": \"{field} must be a finite number.\",\n \"IGX-0602\": \"The reference {reference} in {scene} could not be resolved.\",\n \"IGX-0603\": \"{file} declares format version {version}, which this build cannot read.\",\n \"IGX-0604\": \"The overrides recorded for {scene} do not match the scene file.\",\n \"IGX-0605\": \"{field} has the wrong type for a {kind} field.\",\n \"IGX-0606\": \"{field} is outside the declared value domain.\",\n \"IGX-0607\": \"{field} is not a field this schema declares, or not a name a schema field may use.\",\n \"IGX-0608\": \"{file} does not match the scene file schema.\",\n \"IGX-0609\": \"{path} is not a valid instance override path.\",\n \"IGX-0701\": \"WebGPU is not available in this environment.\",\n \"IGX-0702\": \"This handle was already disposed, or was not created by ignifx.\",\n \"IGX-0703\": \"Babylon Lite has no shadow generator for a {lightType} light.\",\n \"IGX-0704\": \"The rendering feature {feature} must be enabled before the scene is registered.\",\n \"IGX-0705\": \"{entity} enabled a second Environment in this world; the most recent one wins.\",\n \"IGX-0706\": \"This world has no enabled camera, so nothing is drawn.\",\n \"IGX-0707\": \"captureScreenshot() needs a running render loop; a headless app never presents a frame.\",\n \"IGX-0708\": \"{asset} declares the material kind {kind}, which this build cannot construct.\",\n \"IGX-0709\": \"{file} is not an {format} file.\",\n \"IGX-0710\": \"{entity} attached a PostProcessStack, but rendering.features.postProcessing is off.\",\n \"IGX-0711\":\n \"{entity} asks for an Environment.skybox that {asset} was not loaded with; declare it in the .environment.json.\",\n \"IGX-0712\": \"{name} is not a uniform, texture, storage buffer, or plugin binding that is declared.\",\n \"IGX-0713\": \"{name} on {material} expects {expected}, not {actual}.\",\n \"IGX-0714\": \"{material} declares {name}, but this world has no enabled directional light; zeros are uploaded.\",\n \"IGX-0715\": \"{asset} failed to compile; the previous material stays in use. {message}\",\n \"IGX-0716\": \"{material} carries a surface shader, but rendering.features.materialPlugins is off.\",\n \"IGX-0717\": \"{entity} changed {field} on an InstancedMeshRenderer after the scene was registered.\",\n \"IGX-0718\": \"{material} is a {kind} material; {method} needs a shader material.\",\n \"IGX-0719\": \"{asset} line {line}: {message}\",\n \"IGX-0720\": \"{buffer}: an update of {bytes} bytes at offset {offset} exceeds the {capacity}-byte buffer.\",\n \"IGX-0721\": \"{entity}: {count} instances exceed the capacity of {capacity}.\",\n \"IGX-0722\": \"{asset}: {bytes} bytes of pixel data do not match {width}x{height} RGBA.\",\n \"IGX-0723\":\n \"A surface shader or post effect declares no hook this host can run: displace, surface, composite, or mainFragment.\",\n \"IGX-0724\":\n \"{entity} uses a shader material under ESM shadows; Babylon Lite 1.27.0 cannot render it into an ESM map, so it casts no shadow. Use pcf shadows or castShadows: false.\",\n \"IGX-0725\": \"{asset}: an update of {count} vertices at offset {offset} does not fit the {total}-vertex mesh.\",\n \"IGX-0726\": \"{samplers} plugin samplers are declared; {budget} fit beside a textured PBR material.\",\n \"IGX-0727\":\n \"{entity} declares an InstancedMeshRenderer lod with gpuCulling off; the LOD mesh never draws. Turn gpuCulling on.\",\n \"IGX-0728\": \"openOverlay() needs a canvas-backed app whose render scene is registered.\",\n \"IGX-0729\": \"{member} needs a canvas-backed app whose render loop is running.\",\n \"IGX-0730\": \"A render texture of {width}x{height}: each side must be a whole number from 1 to {max}.\",\n \"IGX-0731\": \"{member}: the render texture is disposed or belongs to another app.\",\n \"IGX-0732\": \"renderToTexture() needs a camera attached to an entity.\",\n \"IGX-1420\": \"This host does not expose Web Crypto.\",\n \"IGX-1421\": \"{namespace} is not a valid storage namespace.\",\n \"IGX-1422\": \"That storage key is empty, too long, or contains a control character.\",\n \"IGX-1423\": \"The value stored at {key} has no JSON form.\",\n \"IGX-1424\": \"The {backend} storage backend has no quota left for {operation}.\",\n \"IGX-1425\": \"The {backend} storage backend could not {operation}.\",\n \"IGX-1426\": \"The value stored at {key} could not be read back.\",\n \"IGX-1501\": \"The error code {code} is already registered by {owner}.\",\n \"IGX-1502\": \"{code} is not a valid IGX-#### code in a known range.\",\n \"IGX-1503\": \"The diagnostics group {group} is already registered.\",\n \"IGX-1504\": \"{counter} is not a counter of the diagnostics group {group}.\",\n \"IGX-1505\": \"Unreachable case reached for {what}.\",\n \"IGX-1506\": \"The scene instance {scene} was not built from a scene asset, so it cannot be reloaded.\",\n};\n\n/** The fixed length of an `IGX-####` code. */\nconst ERROR_CODE_LENGTH = 8;\n\n/** Where the four digits start inside an `IGX-####` code. */\nconst ERROR_CODE_DIGITS_OFFSET = 4;\n\n/** The characters allowed in the numeric part of a code. */\nconst DIGITS = \"0123456789\";\n\n/**\n * Reports whether a string is a well-formed ignifx error code.\n *\n * @remarks\n * The rule has exactly two parts and the `ignifx/error-code-format` lint rule mirrors it:\n *\n * 1. the string is `IGX-` followed by four ASCII digits, and\n * 2. the first two digits are one of the fifteen `ErrorRange` prefixes, or the first digit is\n * {@link THIRD_PARTY_ERROR_PREFIX} (the third-party block `IGX-9000`–`IGX-9999`).\n *\n * @param code - The candidate code.\n * @returns `true` when the code is well formed and inside an allocated range. The signature is a\n * type predicate, so a validated string narrows to {@link ErrorCode} without a type assertion.\n *\n * @example\n * ```ts\n * isValidErrorCode(\"IGX-0701\"); // true — rendering\n * isValidErrorCode(\"IGX-9042\"); // true — third party\n * isValidErrorCode(\"IGX-1801\"); // false — no subsystem owns 18\n * ```\n *\n * @public\n */\nexport function isValidErrorCode(code: string): code is ErrorCode {\n // The literal below is the prefix the `ignifx/error-code-format` rule looks for. This function is\n // the validator that rule mirrors, not a throw site, so the rule is switched off for one line.\n // eslint-disable-next-line ignifx/error-code-format -- see the comment above\n if (code.length !== ERROR_CODE_LENGTH || !code.startsWith(\"IGX-\")) {\n return false;\n }\n const digits = code.slice(ERROR_CODE_DIGITS_OFFSET);\n for (const digit of digits) {\n if (!DIGITS.includes(digit)) {\n return false;\n }\n }\n const prefix = digits.slice(0, 2);\n if (prefix.startsWith(THIRD_PARTY_ERROR_PREFIX)) {\n return true;\n }\n for (const range of Object.values(ErrorRange)) {\n if (range === prefix) {\n return true;\n }\n }\n return false;\n}\n","import { CoreErrorCode, type ErrorCode } from \"./error-codes.js\";\n\n/**\n * The identifiers that make a failure actionable: entity and component uids, asset keys, layer\n * names, extension names. Values are primitives so the whole record survives being sent to a\n * devtools panel or a log sink without cloning engine objects.\n *\n * @public\n */\nexport type ErrorContext = Readonly<Record<string, string | number | boolean | null>>;\n\n/**\n * How much of an error is spelled out in `Error.message`.\n *\n * @remarks\n * `\"development\"` writes the full sentence, the context values, and the hint. `\"production\"` keeps\n * the code and the *names* of the context keys and drops every value and the prose, so shipped\n * games neither leak content paths nor pay for message strings (`CONSTITUTION.md` §3.9). The\n * structured `code`, `context`, and `hint` properties are populated in both modes.\n *\n * @public\n */\nexport type ErrorFormatMode = \"development\" | \"production\";\n\n/**\n * Options accepted by {@link IgnifxError}. Extends the standard `ErrorOptions`, so `cause` keeps\n * the original failure when an error is wrapped.\n *\n * @public\n */\nexport interface IgnifxErrorOptions extends ErrorOptions {\n /** Identifiers that locate the failure. Defaults to an empty record. */\n readonly context?: ErrorContext;\n /** One sentence telling the developer what to do about it. Defaults to `null`. */\n readonly hint?: string | null;\n /** How verbose `message` should be. Defaults to `\"development\"`. */\n readonly mode?: ErrorFormatMode;\n}\n\n/** Shared empty context so the common case allocates nothing. */\nconst EMPTY_CONTEXT: ErrorContext = {};\n\n/**\n * Builds the `Error.message` of an {@link IgnifxError}.\n *\n * @remarks\n * Development messages read `IGX-0201: Mover requires Rigidbody. [entity=01J…] Hint: add it.`\n * Production messages read `IGX-0201 [entity]` — enough to look the code up in the registry and to\n * know which identifiers the `context` property carries, with no prose in the bundle.\n *\n * @param code - The stable diagnostic code.\n * @param message - The actionable development sentence.\n * @param context - Identifiers that locate the failure.\n * @param hint - A remedy sentence, or `null`.\n * @param mode - Whether to format for development or production.\n * @returns The formatted message.\n *\n * @example\n * ```ts\n * formatErrorMessage(\"IGX-0303\", \"Enemy is not a declared layer.\", { layer: \"Enemy\" }, null, \"production\");\n * // \"IGX-0303 [layer]\"\n * ```\n *\n * @public\n */\nexport function formatErrorMessage(\n code: ErrorCode,\n message: string,\n context: ErrorContext,\n hint: string | null,\n mode: ErrorFormatMode,\n): string {\n const keys = Object.keys(context);\n if (mode === \"production\") {\n return keys.length === 0 ? code : `${code} [${keys.join(\", \")}]`;\n }\n let formatted = `${code}: ${message}`;\n if (keys.length > 0) {\n const parts: string[] = [];\n for (const key of keys) {\n parts.push(`${key}=${String(context[key] ?? null)}`);\n }\n formatted += ` [${parts.join(\", \")}]`;\n }\n if (hint !== null && hint.length > 0) {\n formatted += ` Hint: ${hint}`;\n }\n return formatted;\n}\n\n/**\n * The error every ignifx API throws for misuse (`CONSTITUTION.md` §3.9). It always carries a stable\n * `IGX-####` `code` and the `context` identifiers needed to find the offending object,\n * so a production build can compact the human-readable half without losing meaning.\n *\n * @example\n * ```ts\n * try {\n * world.instantiate(scene);\n * } catch (error) {\n * if (isIgnifxError(error) && error.code === CoreErrorCode.sceneNotLoaded) {\n * await scene.load();\n * }\n * }\n * ```\n *\n * @public\n */\nexport class IgnifxError extends Error {\n /** The stable diagnostic code for this failure. */\n readonly code: ErrorCode;\n\n /** Identifiers that locate the failure (entity uid, component type id, asset key, …). */\n readonly context: ErrorContext;\n\n /** One sentence telling the developer how to fix it, or `null` when there is nothing to add. */\n readonly hint: string | null;\n\n /**\n * Creates an ignifx error.\n *\n * @param code - The stable `IGX-####` code for the failure.\n * @param message - An actionable description of what went wrong, used in development mode.\n * @param options - Context, hint, format mode, and the standard `cause`.\n */\n constructor(code: ErrorCode, message: string, options?: IgnifxErrorOptions) {\n const context = options?.context ?? EMPTY_CONTEXT;\n const hint = options?.hint ?? null;\n super(formatErrorMessage(code, message, context, hint, options?.mode ?? \"development\"), options);\n this.name = \"IgnifxError\";\n this.code = code;\n this.context = context;\n this.hint = hint;\n }\n}\n\n/**\n * Narrows an unknown value — a `catch` binding, a rejected promise, a signal payload — to an\n * {@link IgnifxError}.\n *\n * @param value - The value to test.\n * @returns `true` when the value is an ignifx error produced by this copy of `@ignifx/core`.\n *\n * @example\n * ```ts\n * app.onError.connect((report) => {\n * if (isIgnifxError(report.error)) {\n * console.warn(report.error.code, report.error.context);\n * }\n * });\n * ```\n *\n * @public\n */\nexport function isIgnifxError(value: unknown): value is IgnifxError {\n return value instanceof IgnifxError;\n}\n\n/**\n * The default branch of an exhaustive `switch` (coding standards §5.2). The compiler rejects the\n * call as soon as a new union member is left unhandled, and at runtime it throws rather than\n * falling through silently.\n *\n * @param value - The value the type system proved impossible.\n * @param what - What was being switched over, for the message.\n * @throws IgnifxError with code `IGX-1505`; the function never returns.\n *\n * @example\n * ```ts\n * switch (level) {\n * case \"debug\":\n * return 10;\n * default:\n * return assertNever(level, \"log level\");\n * }\n * ```\n *\n * @public\n */\nexport function assertNever(value: never, what: string): never {\n throw new IgnifxError(CoreErrorCode.unreachableCase, `Unreachable case reached for ${what}.`, {\n context: { what, value: String(value) },\n });\n}\n"],"mappings":"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"}