@ignifx/core 0.11.0 → 0.12.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 (28) hide show
  1. package/dist/{environment-BCjfp1jB.js → environment-C9AjYJgV.js} +2 -2
  2. package/dist/{environment-BCjfp1jB.js.map → environment-C9AjYJgV.js.map} +1 -1
  3. package/dist/{ignifx-error-RpK-lWwE.js → ignifx-error-Dq2qJMkZ.js} +10 -3
  4. package/dist/ignifx-error-Dq2qJMkZ.js.map +1 -0
  5. package/dist/index.d.ts +105 -17
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js +360 -78
  8. package/dist/index.js.map +1 -1
  9. package/dist/json-CzZZ6K4x.js +24 -0
  10. package/dist/json-CzZZ6K4x.js.map +1 -0
  11. package/dist/{material-plugin-CWtV7DkH.js → material-plugin-BOCB7Stt.js} +2 -2
  12. package/dist/{material-plugin-CWtV7DkH.js.map → material-plugin-BOCB7Stt.js.map} +1 -1
  13. package/dist/{post-effect-C42XJFmo.js → post-effect-BHl7U56q.js} +5 -4
  14. package/dist/post-effect-BHl7U56q.js.map +1 -0
  15. package/dist/{post-effect-compiler-pOvXae-i.js → post-effect-compiler-Dw6zW2cG.js} +3 -3
  16. package/dist/{post-effect-compiler-pOvXae-i.js.map → post-effect-compiler-Dw6zW2cG.js.map} +1 -1
  17. package/dist/{shader-material-B6wwFCKB.js → shader-material-BxQn9FT4.js} +2 -2
  18. package/dist/{shader-material-B6wwFCKB.js.map → shader-material-BxQn9FT4.js.map} +1 -1
  19. package/dist/{shader-material-C4VjLTfV.js → shader-material-DRZmqA_S.js} +10 -6
  20. package/dist/shader-material-DRZmqA_S.js.map +1 -0
  21. package/dist/{shader-pragma-qO9_6sTd.js → shader-pragma-DrFm5f5m.js} +2 -2
  22. package/dist/{shader-pragma-qO9_6sTd.js.map → shader-pragma-DrFm5f5m.js.map} +1 -1
  23. package/dist/{surface-shader-BaR7Kg-F.js → surface-shader-BgZchRBe.js} +4 -4
  24. package/dist/{surface-shader-BaR7Kg-F.js.map → surface-shader-BgZchRBe.js.map} +1 -1
  25. package/package.json +1 -1
  26. package/dist/ignifx-error-RpK-lWwE.js.map +0 -1
  27. package/dist/post-effect-C42XJFmo.js.map +0 -1
  28. package/dist/shader-material-C4VjLTfV.js.map +0 -1
@@ -1,4 +1,4 @@
1
- import { n as assertNever } from "./ignifx-error-RpK-lWwE.js";
1
+ import { n as assertNever } from "./ignifx-error-Dq2qJMkZ.js";
2
2
  import { s as degToRad } from "./math-utils-BcDnL-gi.js";
3
3
  import { t as Color } from "./color-DrR6GFTd.js";
4
4
  import { AcesToneMapping, NeutralToneMapping, StandardToneMapping, loadEnvironment, setEnvironmentBlur, setEnvironmentRotation, setFog, setSceneImageProcessing } from "@babylonjs/lite";
@@ -280,4 +280,4 @@ function toneMappingCurve(name) {
280
280
  //#endregion
281
281
  export { readSceneImageProcessing as a, setSceneEnvironmentRotation as c, readSceneEnvironment as i, setSceneFog as l, installSceneEnvironment as n, setSceneClearColor as o, loadSceneEnvironment as r, setSceneEnvironmentBlur as s, TONE_MAPPING_NAMES as t, setSceneImageProcessingOptions as u };
282
282
 
283
- //# sourceMappingURL=environment-BCjfp1jB.js.map
283
+ //# sourceMappingURL=environment-C9AjYJgV.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"environment-BCjfp1jB.js","names":[],"sources":["../src/lite/gpu/environment.ts"],"sourcesContent":["import {\n AcesToneMapping,\n loadEnvironment,\n loadSkybox,\n NeutralToneMapping,\n setEnvironmentBlur,\n setEnvironmentRotation,\n setFog,\n setSceneImageProcessing,\n StandardToneMapping,\n} from \"@babylonjs/lite\";\nimport { assertNever } from \"../../errors/ignifx-error.js\";\nimport { Color } from \"../../math/color.js\";\nimport { degToRad } from \"../../math/math-utils.js\";\nimport type { EnvironmentTextures, SceneContext, ToneMapping } from \"@babylonjs/lite\";\n\n/**\n * Environment half of the Babylon Lite adapter (`docs/architecture/07-rendering.md` §2.5): image\n * based lighting, the skybox, fog, image processing, and the clear colour.\n *\n * Everything here is `@internal`. Loading uploads cube maps, so the module is GPU-only.\n *\n * ## The BRDF LUT is mandatory (verified against `@babylonjs/lite@1.27.0`)\n *\n * `loadEnvironment(scene, url, options)` (`index.d.ts` 6779) takes a **required** `brdfUrl`: Lite\n * decodes the split-sum BRDF lookup table from a pre-baked RGBD PNG rather than computing it, \"for\n * pixel-perfect parity\" with Babylon.js (`lib/_chunks/env-helpers-*.js`, `loadBrdfImage`, which\n * `fetch`es the URL and decodes it with `createImageBitmap`). ignifx ships that PNG as\n * `tests/fixtures/assets/brdf-lut.png`, decoded from Babylon.js's own\n * `_environmentBRDFBase64Texture` (`packages/dev/core/src/Misc/brdfTextureTools.ts`, Apache-2.0).\n * It is 256×256 RGBA8 and 23 KB.\n *\n * ## Fog\n *\n * `SceneContext.fog` is `FogConfig | null` (`index.d.ts` 5350) with a numeric `mode`; Lite exports\n * no named constants for it, so {@link FOG_MODES} maps ignifx's names onto the numbers.\n *\n * **Fog has to be installed with `setFog`, not by assigning the field.** `scene.fog` is what the PBR\n * group builder reads to decide whether a material's program gets the fog block at all\n * (`lib/material/pbr/pbr-renderable.js` 140-159, `PBR_HAS_FOG`), but the block it compiles reads\n * `scene.vFogInfos.x` out of the scene uniform buffer — and the only writer of those slots is\n * `writeFogUbo`, which nothing registers except `setFog`\n * (`lib/scene/scene-ubo-extras.js`: `setFog` is `scene.fog = config` **plus**\n * `_registerSceneUboContributor(scene, writeFogUbo)`, and `_writePassSceneUBO` runs\n * `scene._sceneUboContributors` and nothing else, `lib/frame-graph/render-task.js` 372-379).\n * Lite says as much in `index.d.ts` 10471: \"importing `setFog` is what pulls the fog UBO writer into\n * the bundle\". Assigning `scene.fog` alone therefore compiles the fog block into every PBR pipeline\n * and leaves `vFogInfos` zeroed, so `vFogInfos.x > 0.0` is never true and the scene renders with no\n * fog at all — the cost with none of the effect.\n *\n * A **fresh** config object goes in on every change, because a render task caches its scene UBO on\n * the identity of `scene.fog` (`s[1] === fog`, `lib/frame-graph/render-task.js` 355-371): mutating\n * the installed object in place leaves the cache key equal and the new density or colour never\n * reaches the GPU. Turning fog off writes mode `0`, which is what the already-compiled fog block\n * reads as \"no fog\"; dropping the field back to `null` would only stop the writer and leave the last\n * fog standing. A scene that never had fog keeps its `null` and pays nothing.\n *\n * ## Image processing\n *\n * `setSceneImageProcessing` is **async** (`index.d.ts` 10917) because tone mapping is baked into\n * the PBR shaders at `registerScene` time; changing it recompiles the affected pipelines\n * (`rebuildScenePbrPipelines`). Setting exposure or contrast alone still goes through the same\n * call. Note that `loadEnvironment` **overwrites** all three (`toneMappingEnabled = true`,\n * `exposure = 0.8`, `contrast = 1.2`) as a side effect of installing an environment, which is why\n * the `Environment` component re-applies its own image processing after every install.\n *\n * ## Swapping the installed environment: `scene._envTextures`\n *\n * Lite 1.27.0 declares **no** public way to replace, clear, or read back a registered scene's\n * environment. `index.d.ts` has no `scene.environmentTexture`, no `unloadEnvironment`, and no\n * setter of any kind; `loadEnvironment` is the only installer and it fetches, decodes, and uploads\n * a fresh cube map every call. What it actually installs is one field —\n * `scene._envTextures = textures` (`lib/_chunks/env-helpers-CRI1i-A3.js` 24, and the same line in\n * `lib/loader-hdr/load-hdr.js` 23, `lib/loader-env/load-dds-env.js` 177 and\n * `lib/loader-gltf/gltf-ext-lights-image-based.js` 65) — and every consumer reads that field:\n *\n * - the PBR group builder, which bakes the cube view and sampler into each material's bind group\n * (`lib/material/pbr/pbr-material.js` 12 → `lib/material/pbr/pbr-renderable.js`);\n * - the scene-uniform packer, for `lodGenerationScale` (`lib/frame-graph/scene-uniforms-pack.js` 21);\n * - the env UBO contributor, for the diffuse spherical harmonics (`lib/scene/scene-ubo-extras.js` 24);\n * - the blur contributor, for `lodGenerationOffset` (`lib/scene/set-environment-blur.js` 8);\n * - the render task's scene-UBO cache key, which is keyed on the **object identity** of the field\n * (`lib/frame-graph/render-task.js` 358), so a new object re-uploads the harmonics by itself.\n *\n * Lite's own device-lost recovery replaces the field exactly this way\n * (`lib/loader-env/environment-recovery.js` 16 and 38), so {@link installSceneEnvironment} writes it\n * too. Bind groups are the one consumer that does *not* re-read it: they hold the `GPUTextureView`,\n * so a swap only reaches the specular reflection once the material groups have been rebuilt, which\n * `rebuildSceneRenderables` does (`lib/scene/scene-rebuild.js`, `rebuildEachGroup`). The\n * `Environment` component therefore reports an install as a topology change and lets the render-sync\n * system fire its one coalesced rebuild. This is the only place in ignifx that touches a Lite field\n * `index.d.ts` does not declare, which is what the adapter boundary exists for\n * (`CONSTITUTION.md` §3.4, ADR-0002); it is pinned by\n * `packages/core/test/lite/render/environment.browser.test.ts`, which fails loudly if the field is\n * renamed.\n */\n\n/**\n * The GPU-resident image-based-lighting textures `loadEnvironment` resolves to, re-exported under an\n * ignifx name (`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 LiteEnvironmentTextures = EnvironmentTextures;\n\n/**\n * ignifx fog mode names mapped to the numbers `FogConfig.mode` uses.\n *\n * @internal\n */\nexport const FOG_MODES = {\n /** No fog. */\n none: 0,\n /** Exponential fog. */\n exp: 1,\n /** Squared-exponential fog. */\n exp2: 2,\n /** Linear fog between `start` and `end`. */\n linear: 3,\n} as const;\n\n/**\n * The union of the fog mode names.\n *\n * @internal\n */\nexport type FogMode = keyof typeof FOG_MODES;\n\n/**\n * The tone-mapping curves `docs/architecture/07-rendering.md` §2.5 exposes.\n *\n * @public\n */\nexport const TONE_MAPPING_NAMES = [\"none\", \"standard\", \"aces\", \"neutral\"] as const;\n\n/**\n * The union of the tone-mapping curve names.\n *\n * @internal\n */\nexport type ToneMappingName = (typeof TONE_MAPPING_NAMES)[number];\n\n/**\n * The image processing Lite's PBR shaders apply: exposure, contrast and the tone-mapping curve.\n *\n * @internal\n */\nexport interface ImageProcessingState {\n /** The exposure multiplier. */\n exposure: number;\n /** The contrast multiplier. */\n contrast: number;\n /** The tone-mapping curve, or `\"none\"`. */\n curve: ToneMappingName;\n}\n\n/**\n * How an ignifx `Environment` component configures image based lighting.\n *\n * @internal\n */\nexport interface EnvironmentLoadOptions {\n /** The `.env` file holding the prefiltered specular cube map and its spherical harmonics. */\n readonly url: string;\n /** The RGBD PNG BRDF lookup table. Required by Lite. */\n readonly brdfUrl: string;\n /** A `.dds` or `.env` skybox. Omit for a flat background. */\n readonly skyboxUrl?: string;\n /** The skybox cube's size, in metres. Lite defaults to 20. */\n readonly skyboxSize?: number;\n /** Skip the skybox entirely. */\n readonly skipSkybox?: boolean;\n /** Skip the reflective ground plane Lite would otherwise add. */\n readonly skipGround?: boolean;\n /** A texture for that ground plane. */\n readonly groundTextureUrl?: string;\n}\n\n/**\n * Loads an `.env` environment and installs it on a scene.\n *\n * @param scene - The scene to light.\n * @param options - The environment, BRDF, and skybox URLs.\n * @returns The GPU-resident environment textures, for materials that need them explicitly.\n *\n * @example\n * ```ts\n * await loadSceneEnvironment(scene, {\n * url: \"environments/studio.env\",\n * brdfUrl: \"environments/brdf-lut.png\",\n * });\n * ```\n *\n * @internal\n */\nexport function loadSceneEnvironment(\n scene: SceneContext,\n options: EnvironmentLoadOptions,\n): Promise<EnvironmentTextures> {\n const liteOptions: {\n brdfUrl: string;\n skyboxUrl?: string;\n skyboxSize?: number;\n skipSkybox?: boolean;\n skipGround?: boolean;\n groundTextureUrl?: string;\n } = { brdfUrl: options.brdfUrl };\n if (options.skyboxUrl !== undefined) {\n liteOptions.skyboxUrl = options.skyboxUrl;\n }\n if (options.skyboxSize !== undefined) {\n liteOptions.skyboxSize = options.skyboxSize;\n }\n if (options.skipSkybox !== undefined) {\n liteOptions.skipSkybox = options.skipSkybox;\n }\n if (options.skipGround !== undefined) {\n liteOptions.skipGround = options.skipGround;\n }\n if (options.groundTextureUrl !== undefined) {\n liteOptions.groundTextureUrl = options.groundTextureUrl;\n }\n return loadEnvironment(scene, options.url, liteOptions);\n}\n\n/**\n * The scene fields Babylon Lite 1.27.0 writes for image-based lighting but does not declare in\n * `index.d.ts`. Adapter-internal Lite mirror (coding standards §5.1); see the module header for the\n * `lib/` lines that prove each one.\n */\ninterface SceneEnvironmentSlot {\n /** What `loadEnvironment` installed, or `undefined` on a scene that has never had one. */\n _envTextures?: EnvironmentTextures | undefined;\n}\n\n/**\n * Views a scene through its undeclared environment slot.\n *\n * @param scene - The scene.\n * @returns The same object, typed so the slot is reachable.\n */\nfunction environmentSlotOf(scene: SceneContext): SceneEnvironmentSlot {\n // Boundary assertion (coding standards §5.2): `SceneContext` is a plain object literal Lite\n // creates in `lib/scene/scene-core.js`, and `_envTextures` is one of its own fields — it is\n // absent from `index.d.ts` because it is not part of Lite's declared surface, not because it is\n // a different object. See the module header for every `lib/` line that reads or writes it.\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n return scene as SceneContext & SceneEnvironmentSlot;\n}\n\n/**\n * Reports which environment textures a scene is currently lit by.\n *\n * @param scene - The scene to inspect.\n * @returns The installed textures, or `null` when no environment has ever been installed.\n *\n * @internal\n */\nexport function readSceneEnvironment(scene: SceneContext): EnvironmentTextures | null {\n // The underscore is Lite's, not ignifx's: coding standards §5.1 reserves `_field` for exactly\n // this, an adapter-internal mirror of a Lite field, and the module header proves the name.\n // oxlint-disable-next-line no-underscore-dangle\n return environmentSlotOf(scene)._envTextures ?? null;\n}\n\n/**\n * Points a scene at an already-loaded set of environment textures, without loading anything.\n *\n * @remarks\n * This is how an `Environment` component swaps environments at runtime: the textures belong to the\n * `EnvironmentAsset` that loaded them and stay alive as long as its handle is retained, so\n * switching between two loaded assets uploads nothing and frees nothing.\n *\n * The specular reflection follows only after the scene's material groups are rebuilt\n * (`rebuildRenderables` in `../shadow.ts`): a PBR bind group holds the cube map's `GPUTextureView`,\n * not the slot. The diffuse harmonics and the LOD scale follow immediately, because the render\n * task's scene-UBO cache is keyed on this object's identity.\n *\n * @param scene - The scene to light.\n * @param textures - The textures to light it with.\n * @returns `true` when the scene was lit by something else and now is not — the caller owes a\n * renderable rebuild; `false` when these textures were already installed and nothing was written.\n *\n * @example\n * ```ts\n * if (installSceneEnvironment(scene, asset.lite.textures)) {\n * await rebuildRenderables(scene);\n * }\n * ```\n *\n * @internal\n */\nexport function installSceneEnvironment(scene: SceneContext, textures: EnvironmentTextures): boolean {\n const slot = environmentSlotOf(scene);\n // As in `readSceneEnvironment`: an adapter-internal Lite mirror (coding standards §5.1).\n // oxlint-disable-next-line no-underscore-dangle\n if (slot._envTextures === textures) {\n return false;\n }\n // oxlint-disable-next-line no-underscore-dangle\n slot._envTextures = textures;\n return true;\n}\n\n/**\n * Loads a six-face cube-map skybox from a base URL.\n *\n * @param scene - The scene to give a background.\n * @param baseUrl - The URL prefix each face name is appended to.\n * @param extension - The face file extension, such as `\".jpg\"`.\n * @param size - The skybox cube's size, in metres.\n * @returns A promise that resolves when the faces are uploaded.\n *\n * @internal\n */\nexport function loadSceneSkybox(scene: SceneContext, baseUrl: string, extension: string, size?: number): Promise<void> {\n return loadSkybox(scene, baseUrl, extension, size);\n}\n\n/**\n * Rotates the environment around the world Y axis.\n *\n * @param scene - The scene to rotate the environment of.\n * @param degrees - The rotation, in degrees.\n *\n * @internal\n */\nexport function setSceneEnvironmentRotation(scene: SceneContext, degrees: number): void {\n setEnvironmentRotation(scene, degToRad(degrees));\n}\n\n/**\n * Blurs the visible skybox. Babylon Lite patches only the skybox shader; no material reads the value.\n *\n * @param scene - The scene to change.\n * @param blur - The blur amount, 0 to 1.\n *\n * @internal\n */\nexport function setSceneEnvironmentBlur(scene: SceneContext, blur: number): void {\n setEnvironmentBlur(scene, blur);\n}\n\n/**\n * Sets the colour the scene is cleared to each frame, so that it presents as the sRGB value given.\n *\n * @remarks\n * Lite stores the clear value into the colour target untouched. Tone mapping, image processing and\n * bloom's threshold never apply to it on the GPU (the renderer applies image processing before this\n * call, `src/render/image-processing-color.ts`), and Lite's own transmission and solid-skybox paths read it\n * as the colour that should come out (`lib/frame-graph/transmission.js` `executeRenderTaskLinear`,\n * `lib/material/pbr/background-solid-skybox.js`). The default surface format is not an sRGB one,\n * so the sRGB value is written unchanged. Only an `*-srgb` surface view (`rendering.srgb: true`)\n * encodes on write; there the value is decoded first, so that the GPU's encoding gives it back.\n * Every target ignifx renders the scene into uses the surface's format (`./render-path.ts`), so\n * the same rule holds on the offscreen path.\n *\n * @param scene - The scene to change.\n * @param r - The sRGB red component, 0 to 1.\n * @param g - The sRGB green component, 0 to 1.\n * @param b - The sRGB blue component, 0 to 1.\n * @param a - The alpha component; only meaningful with a premultiplied canvas alpha mode.\n *\n * @internal\n */\nexport function setSceneClearColor(scene: SceneContext, r: number, g: number, b: number, a: number): void {\n const clear = scene.clearColor;\n const decode = isSrgbEncodingFormat(scene.surface.format);\n clear.r = decode ? Color.srgbToLinear(r) : r;\n clear.g = decode ? Color.srgbToLinear(g) : g;\n clear.b = decode ? Color.srgbToLinear(b) : b;\n clear.a = a;\n}\n\n/**\n * Whether a colour target of this format encodes linear values to sRGB as they are stored.\n *\n * @param format - The target's format. Lite's null engine has none.\n * @returns `true` for an `*-srgb` format.\n *\n * @internal\n */\nexport function isSrgbEncodingFormat(format: string | undefined): boolean {\n return format?.endsWith(\"-srgb\") === true;\n}\n\n/**\n * Configures the scene's fog, or turns it off.\n *\n * @param scene - The scene to change.\n * @param mode - The fog falloff, or `\"none\"` to disable it.\n * @param r - The sRGB red component of the fog colour; Lite's fog block decodes it itself.\n * @param g - The sRGB green component.\n * @param b - The sRGB blue component.\n * @param density - The density, for the exponential modes.\n * @param start - Where linear fog begins, in metres.\n * @param end - Where linear fog reaches full strength, in metres.\n *\n * @internal\n */\nexport function setSceneFog(\n scene: SceneContext,\n mode: FogMode,\n r: number,\n g: number,\n b: number,\n density: number,\n start: number,\n end: number,\n): void {\n if (mode === \"none\" && scene.fog === null) {\n // A scene that never had fog pays nothing: no contributor, no fog block in any PBR pipeline.\n return;\n }\n setFog(scene, { mode: FOG_MODES[mode], density, start, end, color: [r, g, b] });\n}\n\n/**\n * Sets exposure, contrast, and the tone-mapping curve.\n *\n * @remarks\n * Asynchronous by nature: tone mapping is compiled into the PBR shaders, so changing it after\n * `registerScene` recompiles the scene's PBR pipelines. Exposure and contrast alone are uniform\n * values, but Lite routes them through the same call.\n *\n * @param scene - The scene to change.\n * @param exposure - The exposure multiplier.\n * @param contrast - The contrast multiplier.\n * @param toneMapping - The curve, or `\"none\"` to leave the colour untouched.\n * @returns A promise that resolves when any affected pipeline has been rebuilt.\n *\n * @internal\n */\nexport function setSceneImageProcessingOptions(\n scene: SceneContext,\n exposure: number,\n contrast: number,\n toneMapping: ToneMappingName,\n): Promise<void> {\n if (toneMapping === \"none\") {\n return setSceneImageProcessing(scene, { exposure, contrast, toneMappingEnabled: false });\n }\n return setSceneImageProcessing(scene, {\n exposure,\n contrast,\n toneMappingEnabled: true,\n toneMapping: toneMappingCurve(toneMapping),\n });\n}\n\n/**\n * Reads the image processing the scene's PBR shaders currently apply.\n *\n * @remarks\n * Read from Lite rather than from the `Environment` component, because Lite's `loadEnvironment`\n * also writes it (exposure 0.8, contrast 1.2, the standard curve) and the clear colour has to match\n * what the shaders actually do. A custom Lite curve set through `.lite` reads as `\"none\"`.\n *\n * @param scene - The scene.\n * @param out - Receives the exposure, contrast and curve.\n * @returns `out`.\n *\n * @internal\n */\nexport function readSceneImageProcessing(scene: SceneContext, out: ImageProcessingState): ImageProcessingState {\n const processing = scene.imageProcessing;\n out.exposure = processing.exposure;\n out.contrast = processing.contrast;\n out.curve = processing.toneMappingEnabled ? curveName(processing.toneMapping ?? StandardToneMapping) : \"none\";\n return out;\n}\n\n/**\n * Maps a Lite curve object back onto its ignifx name.\n *\n * @param curve - The Lite curve.\n * @returns The name, or `\"none\"` for a curve ignifx does not know.\n */\nfunction curveName(curve: ToneMapping): ToneMappingName {\n switch (curve.id) {\n case StandardToneMapping.id:\n return \"standard\";\n case AcesToneMapping.id:\n return \"aces\";\n case NeutralToneMapping.id:\n return \"neutral\";\n default:\n return \"none\";\n }\n}\n\n/**\n * Maps an ignifx tone-mapping name onto the Lite curve object.\n *\n * @param name - The curve name; `\"none\"` is handled by the caller.\n * @returns The Lite curve.\n */\nfunction toneMappingCurve(name: Exclude<ToneMappingName, \"none\">): ToneMapping {\n switch (name) {\n case \"standard\":\n return StandardToneMapping;\n case \"aces\":\n return AcesToneMapping;\n case \"neutral\":\n return NeutralToneMapping;\n default:\n return assertNever(name, \"tone mapping\");\n }\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"environment-C9AjYJgV.js","names":[],"sources":["../src/lite/gpu/environment.ts"],"sourcesContent":["import {\n AcesToneMapping,\n loadEnvironment,\n loadSkybox,\n NeutralToneMapping,\n setEnvironmentBlur,\n setEnvironmentRotation,\n setFog,\n setSceneImageProcessing,\n StandardToneMapping,\n} from \"@babylonjs/lite\";\nimport { assertNever } from \"../../errors/ignifx-error.js\";\nimport { Color } from \"../../math/color.js\";\nimport { degToRad } from \"../../math/math-utils.js\";\nimport type { EnvironmentTextures, SceneContext, ToneMapping } from \"@babylonjs/lite\";\n\n/**\n * Environment half of the Babylon Lite adapter (`docs/architecture/07-rendering.md` §2.5): image\n * based lighting, the skybox, fog, image processing, and the clear colour.\n *\n * Everything here is `@internal`. Loading uploads cube maps, so the module is GPU-only.\n *\n * ## The BRDF LUT is mandatory (verified against `@babylonjs/lite@1.27.0`)\n *\n * `loadEnvironment(scene, url, options)` (`index.d.ts` 6779) takes a **required** `brdfUrl`: Lite\n * decodes the split-sum BRDF lookup table from a pre-baked RGBD PNG rather than computing it, \"for\n * pixel-perfect parity\" with Babylon.js (`lib/_chunks/env-helpers-*.js`, `loadBrdfImage`, which\n * `fetch`es the URL and decodes it with `createImageBitmap`). ignifx ships that PNG as\n * `tests/fixtures/assets/brdf-lut.png`, decoded from Babylon.js's own\n * `_environmentBRDFBase64Texture` (`packages/dev/core/src/Misc/brdfTextureTools.ts`, Apache-2.0).\n * It is 256×256 RGBA8 and 23 KB.\n *\n * ## Fog\n *\n * `SceneContext.fog` is `FogConfig | null` (`index.d.ts` 5350) with a numeric `mode`; Lite exports\n * no named constants for it, so {@link FOG_MODES} maps ignifx's names onto the numbers.\n *\n * **Fog has to be installed with `setFog`, not by assigning the field.** `scene.fog` is what the PBR\n * group builder reads to decide whether a material's program gets the fog block at all\n * (`lib/material/pbr/pbr-renderable.js` 140-159, `PBR_HAS_FOG`), but the block it compiles reads\n * `scene.vFogInfos.x` out of the scene uniform buffer — and the only writer of those slots is\n * `writeFogUbo`, which nothing registers except `setFog`\n * (`lib/scene/scene-ubo-extras.js`: `setFog` is `scene.fog = config` **plus**\n * `_registerSceneUboContributor(scene, writeFogUbo)`, and `_writePassSceneUBO` runs\n * `scene._sceneUboContributors` and nothing else, `lib/frame-graph/render-task.js` 372-379).\n * Lite says as much in `index.d.ts` 10471: \"importing `setFog` is what pulls the fog UBO writer into\n * the bundle\". Assigning `scene.fog` alone therefore compiles the fog block into every PBR pipeline\n * and leaves `vFogInfos` zeroed, so `vFogInfos.x > 0.0` is never true and the scene renders with no\n * fog at all — the cost with none of the effect.\n *\n * A **fresh** config object goes in on every change, because a render task caches its scene UBO on\n * the identity of `scene.fog` (`s[1] === fog`, `lib/frame-graph/render-task.js` 355-371): mutating\n * the installed object in place leaves the cache key equal and the new density or colour never\n * reaches the GPU. Turning fog off writes mode `0`, which is what the already-compiled fog block\n * reads as \"no fog\"; dropping the field back to `null` would only stop the writer and leave the last\n * fog standing. A scene that never had fog keeps its `null` and pays nothing.\n *\n * ## Image processing\n *\n * `setSceneImageProcessing` is **async** (`index.d.ts` 10917) because tone mapping is baked into\n * the PBR shaders at `registerScene` time; changing it recompiles the affected pipelines\n * (`rebuildScenePbrPipelines`). Setting exposure or contrast alone still goes through the same\n * call. Note that `loadEnvironment` **overwrites** all three (`toneMappingEnabled = true`,\n * `exposure = 0.8`, `contrast = 1.2`) as a side effect of installing an environment, which is why\n * the `Environment` component re-applies its own image processing after every install.\n *\n * ## Swapping the installed environment: `scene._envTextures`\n *\n * Lite 1.27.0 declares **no** public way to replace, clear, or read back a registered scene's\n * environment. `index.d.ts` has no `scene.environmentTexture`, no `unloadEnvironment`, and no\n * setter of any kind; `loadEnvironment` is the only installer and it fetches, decodes, and uploads\n * a fresh cube map every call. What it actually installs is one field —\n * `scene._envTextures = textures` (`lib/_chunks/env-helpers-CRI1i-A3.js` 24, and the same line in\n * `lib/loader-hdr/load-hdr.js` 23, `lib/loader-env/load-dds-env.js` 177 and\n * `lib/loader-gltf/gltf-ext-lights-image-based.js` 65) — and every consumer reads that field:\n *\n * - the PBR group builder, which bakes the cube view and sampler into each material's bind group\n * (`lib/material/pbr/pbr-material.js` 12 → `lib/material/pbr/pbr-renderable.js`);\n * - the scene-uniform packer, for `lodGenerationScale` (`lib/frame-graph/scene-uniforms-pack.js` 21);\n * - the env UBO contributor, for the diffuse spherical harmonics (`lib/scene/scene-ubo-extras.js` 24);\n * - the blur contributor, for `lodGenerationOffset` (`lib/scene/set-environment-blur.js` 8);\n * - the render task's scene-UBO cache key, which is keyed on the **object identity** of the field\n * (`lib/frame-graph/render-task.js` 358), so a new object re-uploads the harmonics by itself.\n *\n * Lite's own device-lost recovery replaces the field exactly this way\n * (`lib/loader-env/environment-recovery.js` 16 and 38), so {@link installSceneEnvironment} writes it\n * too. Bind groups are the one consumer that does *not* re-read it: they hold the `GPUTextureView`,\n * so a swap only reaches the specular reflection once the material groups have been rebuilt, which\n * `rebuildSceneRenderables` does (`lib/scene/scene-rebuild.js`, `rebuildEachGroup`). The\n * `Environment` component therefore reports an install as a topology change and lets the render-sync\n * system fire its one coalesced rebuild. This is the only place in ignifx that touches a Lite field\n * `index.d.ts` does not declare, which is what the adapter boundary exists for\n * (`CONSTITUTION.md` §3.4, ADR-0002); it is pinned by\n * `packages/core/test/lite/render/environment.browser.test.ts`, which fails loudly if the field is\n * renamed.\n */\n\n/**\n * The GPU-resident image-based-lighting textures `loadEnvironment` resolves to, re-exported under an\n * ignifx name (`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 LiteEnvironmentTextures = EnvironmentTextures;\n\n/**\n * ignifx fog mode names mapped to the numbers `FogConfig.mode` uses.\n *\n * @internal\n */\nexport const FOG_MODES = {\n /** No fog. */\n none: 0,\n /** Exponential fog. */\n exp: 1,\n /** Squared-exponential fog. */\n exp2: 2,\n /** Linear fog between `start` and `end`. */\n linear: 3,\n} as const;\n\n/**\n * The union of the fog mode names.\n *\n * @internal\n */\nexport type FogMode = keyof typeof FOG_MODES;\n\n/**\n * The tone-mapping curves `docs/architecture/07-rendering.md` §2.5 exposes.\n *\n * @public\n */\nexport const TONE_MAPPING_NAMES = [\"none\", \"standard\", \"aces\", \"neutral\"] as const;\n\n/**\n * The union of the tone-mapping curve names.\n *\n * @internal\n */\nexport type ToneMappingName = (typeof TONE_MAPPING_NAMES)[number];\n\n/**\n * The image processing Lite's PBR shaders apply: exposure, contrast and the tone-mapping curve.\n *\n * @internal\n */\nexport interface ImageProcessingState {\n /** The exposure multiplier. */\n exposure: number;\n /** The contrast multiplier. */\n contrast: number;\n /** The tone-mapping curve, or `\"none\"`. */\n curve: ToneMappingName;\n}\n\n/**\n * How an ignifx `Environment` component configures image based lighting.\n *\n * @internal\n */\nexport interface EnvironmentLoadOptions {\n /** The `.env` file holding the prefiltered specular cube map and its spherical harmonics. */\n readonly url: string;\n /** The RGBD PNG BRDF lookup table. Required by Lite. */\n readonly brdfUrl: string;\n /** A `.dds` or `.env` skybox. Omit for a flat background. */\n readonly skyboxUrl?: string;\n /** The skybox cube's size, in metres. Lite defaults to 20. */\n readonly skyboxSize?: number;\n /** Skip the skybox entirely. */\n readonly skipSkybox?: boolean;\n /** Skip the reflective ground plane Lite would otherwise add. */\n readonly skipGround?: boolean;\n /** A texture for that ground plane. */\n readonly groundTextureUrl?: string;\n}\n\n/**\n * Loads an `.env` environment and installs it on a scene.\n *\n * @param scene - The scene to light.\n * @param options - The environment, BRDF, and skybox URLs.\n * @returns The GPU-resident environment textures, for materials that need them explicitly.\n *\n * @example\n * ```ts\n * await loadSceneEnvironment(scene, {\n * url: \"environments/studio.env\",\n * brdfUrl: \"environments/brdf-lut.png\",\n * });\n * ```\n *\n * @internal\n */\nexport function loadSceneEnvironment(\n scene: SceneContext,\n options: EnvironmentLoadOptions,\n): Promise<EnvironmentTextures> {\n const liteOptions: {\n brdfUrl: string;\n skyboxUrl?: string;\n skyboxSize?: number;\n skipSkybox?: boolean;\n skipGround?: boolean;\n groundTextureUrl?: string;\n } = { brdfUrl: options.brdfUrl };\n if (options.skyboxUrl !== undefined) {\n liteOptions.skyboxUrl = options.skyboxUrl;\n }\n if (options.skyboxSize !== undefined) {\n liteOptions.skyboxSize = options.skyboxSize;\n }\n if (options.skipSkybox !== undefined) {\n liteOptions.skipSkybox = options.skipSkybox;\n }\n if (options.skipGround !== undefined) {\n liteOptions.skipGround = options.skipGround;\n }\n if (options.groundTextureUrl !== undefined) {\n liteOptions.groundTextureUrl = options.groundTextureUrl;\n }\n return loadEnvironment(scene, options.url, liteOptions);\n}\n\n/**\n * The scene fields Babylon Lite 1.27.0 writes for image-based lighting but does not declare in\n * `index.d.ts`. Adapter-internal Lite mirror (coding standards §5.1); see the module header for the\n * `lib/` lines that prove each one.\n */\ninterface SceneEnvironmentSlot {\n /** What `loadEnvironment` installed, or `undefined` on a scene that has never had one. */\n _envTextures?: EnvironmentTextures | undefined;\n}\n\n/**\n * Views a scene through its undeclared environment slot.\n *\n * @param scene - The scene.\n * @returns The same object, typed so the slot is reachable.\n */\nfunction environmentSlotOf(scene: SceneContext): SceneEnvironmentSlot {\n // Boundary assertion (coding standards §5.2): `SceneContext` is a plain object literal Lite\n // creates in `lib/scene/scene-core.js`, and `_envTextures` is one of its own fields — it is\n // absent from `index.d.ts` because it is not part of Lite's declared surface, not because it is\n // a different object. See the module header for every `lib/` line that reads or writes it.\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n return scene as SceneContext & SceneEnvironmentSlot;\n}\n\n/**\n * Reports which environment textures a scene is currently lit by.\n *\n * @param scene - The scene to inspect.\n * @returns The installed textures, or `null` when no environment has ever been installed.\n *\n * @internal\n */\nexport function readSceneEnvironment(scene: SceneContext): EnvironmentTextures | null {\n // The underscore is Lite's, not ignifx's: coding standards §5.1 reserves `_field` for exactly\n // this, an adapter-internal mirror of a Lite field, and the module header proves the name.\n // oxlint-disable-next-line no-underscore-dangle\n return environmentSlotOf(scene)._envTextures ?? null;\n}\n\n/**\n * Points a scene at an already-loaded set of environment textures, without loading anything.\n *\n * @remarks\n * This is how an `Environment` component swaps environments at runtime: the textures belong to the\n * `EnvironmentAsset` that loaded them and stay alive as long as its handle is retained, so\n * switching between two loaded assets uploads nothing and frees nothing.\n *\n * The specular reflection follows only after the scene's material groups are rebuilt\n * (`rebuildRenderables` in `../shadow.ts`): a PBR bind group holds the cube map's `GPUTextureView`,\n * not the slot. The diffuse harmonics and the LOD scale follow immediately, because the render\n * task's scene-UBO cache is keyed on this object's identity.\n *\n * @param scene - The scene to light.\n * @param textures - The textures to light it with.\n * @returns `true` when the scene was lit by something else and now is not — the caller owes a\n * renderable rebuild; `false` when these textures were already installed and nothing was written.\n *\n * @example\n * ```ts\n * if (installSceneEnvironment(scene, asset.lite.textures)) {\n * await rebuildRenderables(scene);\n * }\n * ```\n *\n * @internal\n */\nexport function installSceneEnvironment(scene: SceneContext, textures: EnvironmentTextures): boolean {\n const slot = environmentSlotOf(scene);\n // As in `readSceneEnvironment`: an adapter-internal Lite mirror (coding standards §5.1).\n // oxlint-disable-next-line no-underscore-dangle\n if (slot._envTextures === textures) {\n return false;\n }\n // oxlint-disable-next-line no-underscore-dangle\n slot._envTextures = textures;\n return true;\n}\n\n/**\n * Loads a six-face cube-map skybox from a base URL.\n *\n * @param scene - The scene to give a background.\n * @param baseUrl - The URL prefix each face name is appended to.\n * @param extension - The face file extension, such as `\".jpg\"`.\n * @param size - The skybox cube's size, in metres.\n * @returns A promise that resolves when the faces are uploaded.\n *\n * @internal\n */\nexport function loadSceneSkybox(scene: SceneContext, baseUrl: string, extension: string, size?: number): Promise<void> {\n return loadSkybox(scene, baseUrl, extension, size);\n}\n\n/**\n * Rotates the environment around the world Y axis.\n *\n * @param scene - The scene to rotate the environment of.\n * @param degrees - The rotation, in degrees.\n *\n * @internal\n */\nexport function setSceneEnvironmentRotation(scene: SceneContext, degrees: number): void {\n setEnvironmentRotation(scene, degToRad(degrees));\n}\n\n/**\n * Blurs the visible skybox. Babylon Lite patches only the skybox shader; no material reads the value.\n *\n * @param scene - The scene to change.\n * @param blur - The blur amount, 0 to 1.\n *\n * @internal\n */\nexport function setSceneEnvironmentBlur(scene: SceneContext, blur: number): void {\n setEnvironmentBlur(scene, blur);\n}\n\n/**\n * Sets the colour the scene is cleared to each frame, so that it presents as the sRGB value given.\n *\n * @remarks\n * Lite stores the clear value into the colour target untouched. Tone mapping, image processing and\n * bloom's threshold never apply to it on the GPU (the renderer applies image processing before this\n * call, `src/render/image-processing-color.ts`), and Lite's own transmission and solid-skybox paths read it\n * as the colour that should come out (`lib/frame-graph/transmission.js` `executeRenderTaskLinear`,\n * `lib/material/pbr/background-solid-skybox.js`). The default surface format is not an sRGB one,\n * so the sRGB value is written unchanged. Only an `*-srgb` surface view (`rendering.srgb: true`)\n * encodes on write; there the value is decoded first, so that the GPU's encoding gives it back.\n * Every target ignifx renders the scene into uses the surface's format (`./render-path.ts`), so\n * the same rule holds on the offscreen path.\n *\n * @param scene - The scene to change.\n * @param r - The sRGB red component, 0 to 1.\n * @param g - The sRGB green component, 0 to 1.\n * @param b - The sRGB blue component, 0 to 1.\n * @param a - The alpha component; only meaningful with a premultiplied canvas alpha mode.\n *\n * @internal\n */\nexport function setSceneClearColor(scene: SceneContext, r: number, g: number, b: number, a: number): void {\n const clear = scene.clearColor;\n const decode = isSrgbEncodingFormat(scene.surface.format);\n clear.r = decode ? Color.srgbToLinear(r) : r;\n clear.g = decode ? Color.srgbToLinear(g) : g;\n clear.b = decode ? Color.srgbToLinear(b) : b;\n clear.a = a;\n}\n\n/**\n * Whether a colour target of this format encodes linear values to sRGB as they are stored.\n *\n * @param format - The target's format. Lite's null engine has none.\n * @returns `true` for an `*-srgb` format.\n *\n * @internal\n */\nexport function isSrgbEncodingFormat(format: string | undefined): boolean {\n return format?.endsWith(\"-srgb\") === true;\n}\n\n/**\n * Configures the scene's fog, or turns it off.\n *\n * @param scene - The scene to change.\n * @param mode - The fog falloff, or `\"none\"` to disable it.\n * @param r - The sRGB red component of the fog colour; Lite's fog block decodes it itself.\n * @param g - The sRGB green component.\n * @param b - The sRGB blue component.\n * @param density - The density, for the exponential modes.\n * @param start - Where linear fog begins, in metres.\n * @param end - Where linear fog reaches full strength, in metres.\n *\n * @internal\n */\nexport function setSceneFog(\n scene: SceneContext,\n mode: FogMode,\n r: number,\n g: number,\n b: number,\n density: number,\n start: number,\n end: number,\n): void {\n if (mode === \"none\" && scene.fog === null) {\n // A scene that never had fog pays nothing: no contributor, no fog block in any PBR pipeline.\n return;\n }\n setFog(scene, { mode: FOG_MODES[mode], density, start, end, color: [r, g, b] });\n}\n\n/**\n * Sets exposure, contrast, and the tone-mapping curve.\n *\n * @remarks\n * Asynchronous by nature: tone mapping is compiled into the PBR shaders, so changing it after\n * `registerScene` recompiles the scene's PBR pipelines. Exposure and contrast alone are uniform\n * values, but Lite routes them through the same call.\n *\n * @param scene - The scene to change.\n * @param exposure - The exposure multiplier.\n * @param contrast - The contrast multiplier.\n * @param toneMapping - The curve, or `\"none\"` to leave the colour untouched.\n * @returns A promise that resolves when any affected pipeline has been rebuilt.\n *\n * @internal\n */\nexport function setSceneImageProcessingOptions(\n scene: SceneContext,\n exposure: number,\n contrast: number,\n toneMapping: ToneMappingName,\n): Promise<void> {\n if (toneMapping === \"none\") {\n return setSceneImageProcessing(scene, { exposure, contrast, toneMappingEnabled: false });\n }\n return setSceneImageProcessing(scene, {\n exposure,\n contrast,\n toneMappingEnabled: true,\n toneMapping: toneMappingCurve(toneMapping),\n });\n}\n\n/**\n * Reads the image processing the scene's PBR shaders currently apply.\n *\n * @remarks\n * Read from Lite rather than from the `Environment` component, because Lite's `loadEnvironment`\n * also writes it (exposure 0.8, contrast 1.2, the standard curve) and the clear colour has to match\n * what the shaders actually do. A custom Lite curve set through `.lite` reads as `\"none\"`.\n *\n * @param scene - The scene.\n * @param out - Receives the exposure, contrast and curve.\n * @returns `out`.\n *\n * @internal\n */\nexport function readSceneImageProcessing(scene: SceneContext, out: ImageProcessingState): ImageProcessingState {\n const processing = scene.imageProcessing;\n out.exposure = processing.exposure;\n out.contrast = processing.contrast;\n out.curve = processing.toneMappingEnabled ? curveName(processing.toneMapping ?? StandardToneMapping) : \"none\";\n return out;\n}\n\n/**\n * Maps a Lite curve object back onto its ignifx name.\n *\n * @param curve - The Lite curve.\n * @returns The name, or `\"none\"` for a curve ignifx does not know.\n */\nfunction curveName(curve: ToneMapping): ToneMappingName {\n switch (curve.id) {\n case StandardToneMapping.id:\n return \"standard\";\n case AcesToneMapping.id:\n return \"aces\";\n case NeutralToneMapping.id:\n return \"neutral\";\n default:\n return \"none\";\n }\n}\n\n/**\n * Maps an ignifx tone-mapping name onto the Lite curve object.\n *\n * @param name - The curve name; `\"none\"` is handled by the caller.\n * @returns The Lite curve.\n */\nfunction toneMappingCurve(name: Exclude<ToneMappingName, \"none\">): ToneMapping {\n switch (name) {\n case \"standard\":\n return StandardToneMapping;\n case \"aces\":\n return AcesToneMapping;\n case \"neutral\":\n return NeutralToneMapping;\n default:\n return assertNever(name, \"tone mapping\");\n }\n}\n"],"mappings":"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"}
@@ -128,6 +128,8 @@ const CoreErrorCode = {
128
128
  hotReloadSchemaChanged: "IGX-0207",
129
129
  /** `app.hotReload.apply()` was called from inside a lifecycle callback. */
130
130
  hotReloadInsideCallback: "IGX-0208",
131
+ /** A component class's `static requires` chain loops, through the class itself or a class it requires. */
132
+ requiresCycle: "IGX-0209",
131
133
  /** A scene was instantiated before it had finished loading. */
132
134
  sceneNotLoaded: "IGX-0301",
133
135
  /** Instantiating a scene would place an instance inside itself. */
@@ -192,7 +194,11 @@ const CoreErrorCode = {
192
194
  schemaTypeMismatch: "IGX-0605",
193
195
  /** A value had the right type but fell outside its schema field's declared value domain. */
194
196
  schemaOutOfRange: "IGX-0606",
195
- /** A schema declaration or a property bag named a field the schema does not declare. */
197
+ /**
198
+ * A property bag named a field the schema does not declare, or a schema declaration named a field
199
+ * it may not use: not identifier-like, a `Component`/`Script` member, or an `Object.prototype`
200
+ * member such as `constructor` or `__proto__`.
201
+ */
196
202
  schemaUnknownField: "IGX-0607",
197
203
  /** A scene file failed structural validation against the generated scene-file JSON Schema. */
198
204
  sceneFileInvalid: "IGX-0608",
@@ -308,6 +314,7 @@ const CORE_ERROR_MESSAGES = {
308
314
  "IGX-0206": "{component} is not attached to an entity yet.",
309
315
  "IGX-0207": "{component} changed its schema shape under the \"patch\" hot-reload policy; its instances were re-created.",
310
316
  "IGX-0208": "app.hotReload.apply() cannot run inside the {phase} callback; apply it between frames.",
317
+ "IGX-0209": "{component} has a static requires cycle: {cycle}.",
311
318
  "IGX-0301": "The scene {scene} is not loaded yet.",
312
319
  "IGX-0302": "Instantiating {scene} under {entity} would nest the scene inside itself.",
313
320
  "IGX-0303": "{layer} is not a layer declared in the project settings.",
@@ -340,7 +347,7 @@ const CORE_ERROR_MESSAGES = {
340
347
  "IGX-0604": "The overrides recorded for {scene} do not match the scene file.",
341
348
  "IGX-0605": "{field} has the wrong type for a {kind} field.",
342
349
  "IGX-0606": "{field} is outside the declared value domain.",
343
- "IGX-0607": "{field} is not a field this schema declares.",
350
+ "IGX-0607": "{field} is not a field this schema declares, or not a name a schema field may use.",
344
351
  "IGX-0608": "{file} does not match the scene file schema.",
345
352
  "IGX-0609": "{path} is not a valid instance override path.",
346
353
  "IGX-0701": "WebGPU is not available in this environment.",
@@ -555,4 +562,4 @@ function assertNever(value, what) {
555
562
  //#endregion
556
563
  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 };
557
564
 
558
- //# sourceMappingURL=ignifx-error-RpK-lWwE.js.map
565
+ //# sourceMappingURL=ignifx-error-Dq2qJMkZ.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ignifx-error-Dq2qJMkZ.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 /** 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 /** 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-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-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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"}
package/dist/index.d.ts CHANGED
@@ -147,6 +147,8 @@ export declare const CoreErrorCode: {
147
147
  readonly hotReloadSchemaChanged: "IGX-0207";
148
148
  /** `app.hotReload.apply()` was called from inside a lifecycle callback. */
149
149
  readonly hotReloadInsideCallback: "IGX-0208";
150
+ /** A component class's `static requires` chain loops, through the class itself or a class it requires. */
151
+ readonly requiresCycle: "IGX-0209";
150
152
  /** A scene was instantiated before it had finished loading. */
151
153
  readonly sceneNotLoaded: "IGX-0301";
152
154
  /** Instantiating a scene would place an instance inside itself. */
@@ -211,7 +213,11 @@ export declare const CoreErrorCode: {
211
213
  readonly schemaTypeMismatch: "IGX-0605";
212
214
  /** A value had the right type but fell outside its schema field's declared value domain. */
213
215
  readonly schemaOutOfRange: "IGX-0606";
214
- /** A schema declaration or a property bag named a field the schema does not declare. */
216
+ /**
217
+ * A property bag named a field the schema does not declare, or a schema declaration named a field
218
+ * it may not use: not identifier-like, a `Component`/`Script` member, or an `Object.prototype`
219
+ * member such as `constructor` or `__proto__`.
220
+ */
215
221
  readonly schemaUnknownField: "IGX-0607";
216
222
  /** A scene file failed structural validation against the generated scene-file JSON Schema. */
217
223
  readonly sceneFileInvalid: "IGX-0608";
@@ -1953,7 +1959,9 @@ export declare class ComponentRegistry {
1953
1959
  * an id is kept, and {@link ComponentRegistry.registrarOf} reports it.
1954
1960
  * @returns What the registry worked out about the class.
1955
1961
  * @throws IgnifxError with code `IGX-0203` when the id is already registered by another class, or
1956
- * when the id is not `<namespace>/<Name>`.
1962
+ * when the id is not `<namespace>/<Name>`, `IGX-0209` when the class's `static requires`
1963
+ * graph contains a cycle, and `IGX-0607` when its `static schema` names a field after an
1964
+ * `Object.prototype` member.
1957
1965
  */
1958
1966
  register(type: ConcreteComponentType, typeId?: string, registrar?: string): ComponentClassInfo;
1959
1967
  /**
@@ -1990,7 +1998,10 @@ export declare class ComponentRegistry {
1990
1998
  *
1991
1999
  * @param type - The replacement class. It must declare the `typeId` it replaces.
1992
2000
  * @returns The freshly built info for the replacement, and the class it replaced.
1993
- * @throws IgnifxError with code `IGX-0204` when the replacement declares no `typeId`.
2001
+ * @throws IgnifxError with code `IGX-0204` when the replacement declares no `typeId`,
2002
+ * `IGX-0209` when its `static requires` graph contains a cycle, and `IGX-0607` when its
2003
+ * `static schema` names a field after an `Object.prototype` member; in every case the registry is
2004
+ * left unchanged.
1994
2005
  *
1995
2006
  * @example
1996
2007
  * ```ts
@@ -2005,6 +2016,8 @@ export declare class ComponentRegistry {
2005
2016
  *
2006
2017
  * @param type - The component class.
2007
2018
  * @returns The cached class info.
2019
+ * @throws IgnifxError with code `IGX-0209` when the class's `static requires` graph contains a
2020
+ * cycle, and `IGX-0607` when its `static schema` names a field after an `Object.prototype` member.
2008
2021
  */
2009
2022
  describe(type: ComponentType): ComponentClassInfo;
2010
2023
  /**
@@ -4099,6 +4112,14 @@ interface SchemaDescription {
4099
4112
  * prop by prop. Absent on every other component and on file formats.
4100
4113
  */
4101
4114
  readonly builtIn?: boolean;
4115
+ /**
4116
+ * The components the class lists in `static requires`, as type ids (`null` for a class without a
4117
+ * `typeId`), in declaration order. `addComponent` adds each one that is missing, so an editor adds
4118
+ * them itself, and a scene file may list them in any order. A component on the entity whose class
4119
+ * extends a required class counts as present. Set by {@link describeRegisteredSchemas}, or by the
4120
+ * caller through {@link SchemaDescriptionMeta}; absent when the class requires nothing.
4121
+ */
4122
+ readonly requires?: readonly (string | null)[];
4102
4123
  }
4103
4124
  /**
4104
4125
  * Optional overrides for {@link describeSchema}.
@@ -4118,6 +4139,8 @@ interface SchemaDescriptionMeta {
4118
4139
  readonly package?: string;
4119
4140
  /** Whether the component is the entity's own built-in block, copied onto the description. */
4120
4141
  readonly builtIn?: boolean;
4142
+ /** The type ids of the components the class requires, copied onto the description. */
4143
+ readonly requires?: readonly (string | null)[];
4121
4144
  }
4122
4145
  /**
4123
4146
  * A JSON Schema fragment. Kept as a plain JSON object because the generated document is assembled
@@ -4139,7 +4162,7 @@ type JsonSchemaObject = JsonObject;
4139
4162
  * @param typeId - The component's namespaced registration id, for example `mygame/Mover`.
4140
4163
  * @param schema - The component's declared fields.
4141
4164
  * @param meta - Overrides for the title, format grouping, and summary, and the component's
4142
- * `allowMultiple`, `package` and `builtIn` when the caller knows them.
4165
+ * `allowMultiple`, `package`, `builtIn` and `requires` when the caller knows them.
4143
4166
  * @returns The description entry.
4144
4167
  *
4145
4168
  * @example
@@ -4489,7 +4512,11 @@ export declare const SchemaIssueCode: {
4489
4512
  readonly typeMismatch: "IGX-0605";
4490
4513
  /** A value had the right type but fell outside the field's declared value domain. */
4491
4514
  readonly outOfRange: "IGX-0606";
4492
- /** A property was supplied that the schema does not declare. */
4515
+ /**
4516
+ * A property was supplied that the schema does not declare, or a schema declaration named a field
4517
+ * it may not use: not identifier-like, a `Component`/`Script` member, or an `Object.prototype`
4518
+ * member such as `constructor` or `__proto__`.
4519
+ */
4493
4520
  readonly unknownField: "IGX-0607";
4494
4521
  };
4495
4522
  /**
@@ -4928,8 +4955,8 @@ export declare abstract class Script extends Component {
4928
4955
  * @typeParam S - The schema being declared.
4929
4956
  * @param schema - The field definitions, keyed by the property name they become.
4930
4957
  * @returns An abstract class to extend.
4931
- * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like or collides
4932
- * with a `Component`/`Script` member.
4958
+ * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like, collides
4959
+ * with a `Component`/`Script` member, or names an `Object.prototype` member such as `constructor`.
4933
4960
  *
4934
4961
  * @example
4935
4962
  * ```ts
@@ -9591,6 +9618,15 @@ interface InstantiateSceneOptions {
9591
9618
  readonly rootEntity?: Entity | null;
9592
9619
  /** `true` turns an `IGX-0604` hash mismatch from a diagnostic into a throw. */
9593
9620
  readonly strictInstanceHashes?: boolean;
9621
+ /**
9622
+ * How an `entityRef` or `componentRef` resolves when the build made nothing with its uid: a uid
9623
+ * the file does not declare, or one of a component an instance's `remove` override deleted. A
9624
+ * tool that builds part of a larger document, such as an editor rebuilding one prefab instance,
9625
+ * resolves the rest of the document here, so the part decodes as the whole file would; this
9626
+ * includes a reference an instance's overrides hold. The uids the build made come first, and
9627
+ * `asset()` fields never use it. Omitted, such a reference is `null` with an `IGX-0602` issue.
9628
+ */
9629
+ readonly outsideReferences?: Pick<ReferenceDecoder, "entity" | "component">;
9594
9630
  }
9595
9631
  /**
9596
9632
  * What {@link instantiateScene} produced.
@@ -10940,7 +10976,8 @@ export declare class Entity {
10940
10976
  * @returns The attached component.
10941
10977
  * @throws IgnifxError with code `IGX-0202` when the class does not allow multiple instances and
10942
10978
  * the entity already has one, `IGX-0605`/`IGX-0606`/`IGX-0607` when `init` does not match the
10943
- * schema, and `IGX-0101` when the entity has been destroyed.
10979
+ * schema, `IGX-0209` when the class's `static requires` graph contains a cycle, and `IGX-0101`
10980
+ * when the entity has been destroyed.
10944
10981
  */
10945
10982
  addComponent<T extends Component>(type: ConcreteComponentType<T>, init?: ComponentInit<T>): T;
10946
10983
  /**
@@ -11176,8 +11213,8 @@ export declare abstract class Component implements SignalOwner {
11176
11213
  * @typeParam S - The schema being declared.
11177
11214
  * @param schema - The field definitions, keyed by the property name they become.
11178
11215
  * @returns An abstract class to extend.
11179
- * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like or collides
11180
- * with a `Component`/`Script` member.
11216
+ * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like, collides
11217
+ * with a `Component`/`Script` member, or names an `Object.prototype` member such as `constructor`.
11181
11218
  *
11182
11219
  * @example
11183
11220
  * ```ts
@@ -11948,7 +11985,9 @@ interface HotReloadHost {
11948
11985
  * Applies replaced component classes to the running app.
11949
11986
  *
11950
11987
  * @param modules - The replaced modules and the classes they export.
11951
- * @returns What was reloaded.
11988
+ * @returns What was reloaded. A replacement the registry refuses — for example one whose
11989
+ * `static requires` loops (`IGX-0209`) — is collected in `errors`, and the class it would have
11990
+ * replaced stays registered.
11952
11991
  * @throws IgnifxError with code `IGX-0208` when called from inside a lifecycle callback, where a
11953
11992
  * half-swapped world would be observable.
11954
11993
  */
@@ -11959,7 +11998,7 @@ interface HotReloadHost {
11959
11998
  *
11960
11999
  * @param instance - The instance to rebuild. It is unloaded and a fresh one takes its place.
11961
12000
  * @returns The new instance.
11962
- * @throws IgnifxError with code `IGX-0209` when the instance was not built from a scene asset.
12001
+ * @throws IgnifxError with code `IGX-1506` when the instance was not built from a scene asset.
11963
12002
  */
11964
12003
  reloadScene(instance: SceneInstance): Promise<SceneInstance>;
11965
12004
  }
@@ -17351,6 +17390,11 @@ export declare function meshFileJsonSchema(): JsonSchemaObject;
17351
17390
  * flag flips. That is `07-rendering.md` §2.3's rule, and the browser test asserts both halves: the
17352
17391
  * pixel returns to the clear colour, and the mesh is still in the scene.
17353
17392
  *
17393
+ * `displayHidden` hides the same way, and makes the clone unpickable too, but is not a field: scene
17394
+ * files do not save it, so a system
17395
+ * that chooses what is drawn without changing the document (a `LodGroup` in an edit-mode app,
17396
+ * ADR-0028) switches it instead of `enabled`.
17397
+ *
17354
17398
  * ## Decisions the documents left open
17355
17399
  *
17356
17400
  * - **The clone's Lite `id` is the entity's uid.** Lite's light include/exclude lists match on
@@ -17404,9 +17448,42 @@ export declare class MeshRenderer extends Component implements ComponentHooks {
17404
17448
  get lite(): {
17405
17449
  readonly mesh: LiteSceneNode | null;
17406
17450
  };
17451
+ /**
17452
+ * A display-only hide: while `true` the mesh is neither drawn nor picked, whatever `enabled` and
17453
+ * `pickable` say.
17454
+ *
17455
+ * @remarks
17456
+ * It is not a schema field, so scene files do not save it, a serializer never reads it, and
17457
+ * `enabled` keeps its authored value. That makes it the switch for a system that chooses what is
17458
+ * drawn without changing the document: `@ignifx/3d`'s `LodGroup` uses it in place of `enabled` in
17459
+ * an edit-mode app (ADR-0028). It starts `false` and takes effect at the next render sync;
17460
+ * {@link MeshRenderer.isVisible} reports the outcome. Lite's pickers ignore visibility, so the
17461
+ * clone is also made unpickable while hidden: `app.renderer.pickAsync` and `world.raycastRender`
17462
+ * neither return it nor let it occlude, as with `pickable: false`.
17463
+ *
17464
+ * It is one flag with one owner, not a count. In an edit-mode app the `LodGroup` that lists the
17465
+ * renderer as a level owns it: the group sets and clears it whenever it switches, so a value
17466
+ * written by anything else lasts only until then. A renderer belongs to at most one `LodGroup`; a
17467
+ * second group that lists it leaves it alone and warns with `IGX-1217`.
17468
+ *
17469
+ * @returns `true` while the mesh is hidden for display.
17470
+ *
17471
+ * @example
17472
+ * ```ts
17473
+ * renderer.displayHidden = true; // not drawn, and `renderer.enabled` is still `true`
17474
+ * ```
17475
+ */
17476
+ get displayHidden(): boolean;
17477
+ /**
17478
+ * Hides the mesh for display, or shows it again; `enabled` is not touched.
17479
+ *
17480
+ * @param value - `true` to hide it.
17481
+ */
17482
+ set displayHidden(value: boolean);
17407
17483
  /**
17408
17484
  * Whether the mesh is currently drawn: its own `enabled` flag and its entity's
17409
- * `activeInHierarchy`, materialised onto Lite's `visible`.
17485
+ * `activeInHierarchy`, less {@link MeshRenderer.displayHidden}, materialised onto Lite's
17486
+ * `visible`.
17410
17487
  *
17411
17488
  * @returns `true` when the clone is visible.
17412
17489
  */
@@ -18443,7 +18520,8 @@ type EntityOverrideField = "name" | "active" | "static" | "layer" | "tags";
18443
18520
  *
18444
18521
  * @param path - The `path` string from the file.
18445
18522
  * @returns The parsed path.
18446
- * @throws IgnifxError with code `IGX-0609` when the path does not match the grammar.
18523
+ * @throws IgnifxError with code `IGX-0609` when the path does not match the grammar, or when a
18524
+ * property step is `__proto__`.
18447
18525
  *
18448
18526
  * @example
18449
18527
  * ```ts
@@ -18657,6 +18735,10 @@ interface SceneFileIssue {
18657
18735
  * (`CONSTITUTION.md` §2.3). The generated document remains the artefact the Vite plugin and editors
18658
18736
  * validate against; this is the same rule set, executable at load time.
18659
18737
  *
18738
+ * Two checks go beyond what JSON Schema can say: uids are unique within the file, and no two
18739
+ * overrides of one instance share an identity (path, `op`, and an added component's uid), both
18740
+ * reported as issues like any other.
18741
+ *
18660
18742
  * Component `props` are *not* checked here: `decodeProps` already reports every field problem with
18661
18743
  * a schema issue code, per field, which is more precise than a document-level match.
18662
18744
  *
@@ -18679,7 +18761,8 @@ export declare function validateSceneFile(value: unknown): readonly SceneFileIss
18679
18761
  /**
18680
18762
  * Describes every component an app has registered, the engine's, its extensions' and the game's,
18681
18763
  * the way {@link describeSchema} describes one, plus what only the registry knows: whether an
18682
- * entity may hold more than one (`allowMultiple`) and which package registered it (`package`).
18764
+ * entity may hold more than one (`allowMultiple`), which package registered it (`package`), and
18765
+ * which components it adds when they are missing (`requires`, its classes' type ids).
18683
18766
  * This is what an external inspector, such as the ignifx editor, is generated from.
18684
18767
  *
18685
18768
  * @remarks
@@ -18702,6 +18785,7 @@ export declare function validateSceneFile(value: unknown): readonly SceneFileIss
18702
18785
  * const schemas = describeRegisteredSchemas(app.world.registry, describeSchemas());
18703
18786
  * schemas["ignifx/Camera"]?.package; // "@ignifx/core"
18704
18787
  * schemas["ignifx/Camera"]?.allowMultiple; // false
18788
+ * schemas["ignifx/ThirdPersonController"]?.requires; // ["ignifx/CharacterController"] once @ignifx/3d is registered
18705
18789
  * ```
18706
18790
  *
18707
18791
  * @public
@@ -18963,6 +19047,8 @@ export declare function array<T>(item: FieldDefinition<T>, defaultValue?: readon
18963
19047
  * @param fields - The sub-fields.
18964
19048
  * @param options - Inspector and serializer metadata.
18965
19049
  * @returns The field definition.
19050
+ * @throws IgnifxError with code `IGX-0607` when a sub-field name is an `Object.prototype` member
19051
+ * such as `__proto__`, `constructor`, or `toString`.
18966
19052
  *
18967
19053
  * @example
18968
19054
  * ```ts
@@ -19075,8 +19161,10 @@ export declare function custom<T>(codec: CustomFieldCodec<T>, options?: FieldOpt
19075
19161
  *
19076
19162
  * @param fields - The field definitions, keyed by the property name they become.
19077
19163
  * @returns The same object, with its precise type preserved.
19078
- * @throws A `TypeError` when a field name is not identifier-like, starts with `_`, or collides with
19079
- * a `Component`/`Script` member such as `enabled` or `update`.
19164
+ * @throws IgnifxError with code `IGX-0607` when a field name is not identifier-like, starts with
19165
+ * `_`, collides with a `Component`/`Script` member such as `enabled` or `update`, or names an
19166
+ * `Object.prototype` member such as `constructor` or `toString`, or when `fields` is not a plain
19167
+ * object (a literal `__proto__: …` key sets its prototype rather than declaring a field).
19080
19168
  *
19081
19169
  * @example
19082
19170
  * ```ts