@ignifx/core 0.8.0 → 0.9.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.
- package/dist/index.d.ts +123 -88
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +329 -239
- package/dist/index.js.map +1 -1
- package/dist/{instanced-mesh-instance-gguMoIeZ.js → instanced-mesh-instance-DYwH0vLi.js} +2 -2
- package/dist/{instanced-mesh-instance-gguMoIeZ.js.map → instanced-mesh-instance-DYwH0vLi.js.map} +1 -1
- package/dist/{material-plugin-Cfw_h_Mg.js → material-plugin-BRnhfw7K.js} +2 -2
- package/dist/material-plugin-BRnhfw7K.js.map +1 -0
- package/dist/{surface-shader-DAWIDdaa.js → surface-shader-Br17yysO.js} +2 -2
- package/dist/{surface-shader-DAWIDdaa.js.map → surface-shader-Br17yysO.js.map} +1 -1
- package/dist/{vec3-B31o_KF_.js → vec3-T2PasQZv.js} +2 -2
- package/dist/{vec3-B31o_KF_.js.map → vec3-T2PasQZv.js.map} +1 -1
- package/package.json +2 -2
- package/dist/material-plugin-Cfw_h_Mg.js.map +0 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ignifx/core",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"description": "ignifx core: app, world, entities, components, scripts, and the Babylon Lite adapter boundary.",
|
|
5
5
|
"homepage": "https://ignifx.com",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -27,7 +27,7 @@
|
|
|
27
27
|
"provenance": false
|
|
28
28
|
},
|
|
29
29
|
"dependencies": {
|
|
30
|
-
"@babylonjs/lite": "1.
|
|
30
|
+
"@babylonjs/lite": "1.34.0"
|
|
31
31
|
},
|
|
32
32
|
"devDependencies": {
|
|
33
33
|
"@arethetypeswrong/cli": "^0.18.5",
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"material-plugin-Cfw_h_Mg.js","names":[],"sources":["../src/lite/material.ts","../src/render/material-plugin.ts"],"sourcesContent":["import {\n createPbrMaterial,\n createStandardMaterial,\n enableMaterialTracking,\n markMaterialUboDirty,\n rebuildMaterial,\n setPbrAlphaCutoff,\n setPbrEmissive,\n setPbrUnlit,\n setStandardBumpTexture,\n setStandardEmissiveTexture,\n setStandardOpacityTexture,\n setStandardSpecularTexture,\n} from \"@babylonjs/lite\";\nimport { assertNever } from \"../errors/ignifx-error.js\";\nimport type { Material, PbrMaterialProps, SceneContext, StandardMaterialProps, Texture2D } from \"@babylonjs/lite\";\n\n/**\n * Material half of the Babylon Lite adapter (`docs/architecture/07-rendering.md` §2.6): the three\n * material kinds a `MaterialAsset` can produce, built from plain ignifx props.\n *\n * Everything here is `@internal`, and every colour that reaches it is **linear** — the sRGB decode\n * belongs to the asset layer.\n *\n * ## What a Lite material is (verified against `@babylonjs/lite@1.27.0`)\n *\n * - A material is plain data plus one private `_buildGroup` function; `createPbrMaterial` is\n * literally `{ ...props, _buildGroup, _uboVersion: 0 }` (`lib/material/pbr/pbr-material.js`), so\n * none of these factories touches the GPU and all of them run under the null engine.\n * - **The build group is a per-family singleton.** `getPbrGroupBuilder()`, `getStandardGroupBuilder()`\n * and `getShaderGroupBuilder()` each memoise one function for the whole process\n * (`lib/material/pbr/pbr-material.js`, `lib/material/standard/create-standard-material.js`,\n * `lib/material/shader/shader-material.js` line 123), and a scene keys its renderable groups by\n * that function (`lib/scene/scene-core.js`, `addToScene`). \"Material family\" in\n * `docs/architecture/07-rendering.md` §1.1 therefore means *pbr*, *standard*, *shader* or *node* —\n * **not** an individual material. Only node materials get a per-material builder\n * (`lib/material/node/node-material.js`). This is what makes {@link warmUpMaterialFamilies} in\n * `./gpu/warm-up.ts` cheap: one hidden mesh per family covers every material in it.\n * - Scalar and vector edits only need `markMaterialUboDirty` (`index.d.ts` 6974), which bumps\n * `_uboVersion`. Anything that changes the compiled feature set — binding or clearing a texture,\n * flipping `doubleSided`, changing culling — needs {@link rebuildMaterialPipelines}.\n *\n * ## The custom WGSL family lives elsewhere\n *\n * `createShaderMaterial` and the `setShader*` setters are in `./gpu/shader-material.ts`, not here:\n * this module is statically reachable from every app through the material asset layer, and Babylon\n * Lite exports one barrel, so a static import of the shader factory would put Lite's whole\n * shader-material pipeline in every entry chunk. That module is reached through a dynamic\n * `import()` instead (`docs/plan/2026-09-terrain-particles-shaders.md` §3.1, \"Bundle cost\").\n */\n\n/**\n * The Babylon Lite material a `MaterialAsset` owns, re-exported under an ignifx name\n * (`CONSTITUTION.md` §3.4, coding standards §4).\n *\n * @remarks\n * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.\n *\n * @public\n */\nexport type LiteMaterial = Material;\n\n/**\n * A Babylon Lite physically based material, re-exported under an ignifx name.\n *\n * @remarks\n * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.\n *\n * @public\n */\nexport type LitePbrMaterial = PbrMaterialProps;\n\n/**\n * A Babylon Lite Babylon-Standard material, re-exported under an ignifx name.\n *\n * @remarks\n * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.\n *\n * @public\n */\nexport type LiteStandardMaterial = StandardMaterialProps;\n\n/** glTF's default alpha cutoff, used when a `\"mask\"` material declares none. */\nconst DEFAULT_ALPHA_CUTOFF = 0.5;\n\n/**\n * How a material's alpha channel is interpreted, in glTF's vocabulary, in the order the inspector\n * lists them (`docs/architecture/07-rendering.md` §2.4).\n *\n * @public\n */\nexport const MATERIAL_ALPHA_MODES = [\"opaque\", \"mask\", \"blend\"] as const;\n\n/**\n * The union of the alpha modes a material can declare.\n *\n * @public\n */\nexport type MaterialAlphaMode = (typeof MATERIAL_ALPHA_MODES)[number];\n\n/**\n * The physically based material properties an ignifx `.material.json` declares\n * (`docs/architecture/06-serialization-and-scene-format.md` §6). Every field is optional; an\n * omitted field leaves Lite's own default in place.\n *\n * @internal\n */\nexport interface PbrMaterialInput {\n /** A human-readable name, used for glTF material overrides and diagnostics. */\n readonly name?: string;\n /** Linear base colour and alpha, multiplied with the base colour texture. */\n readonly baseColor?: readonly [number, number, number, number];\n /** The base colour texture. Load it with an sRGB format. */\n readonly baseColorTexture?: Texture2D;\n /** Metallic factor, 0 to 1. */\n readonly metallic?: number;\n /** Roughness factor, 0 to 1. */\n readonly roughness?: number;\n /** The packed occlusion/roughness/metallic texture (glTF `ORM`). */\n readonly metallicRoughnessTexture?: Texture2D;\n /** The tangent-space normal map. */\n readonly normalTexture?: Texture2D;\n /** Normal map strength. */\n readonly normalScale?: number;\n /** Linear emissive colour. */\n readonly emissive?: readonly [number, number, number];\n /** The emissive texture. */\n readonly emissiveTexture?: Texture2D;\n /** A separate occlusion texture, sampled on UV1 when the ORM texture is not used for it. */\n readonly occlusionTexture?: Texture2D;\n /** How strongly ambient occlusion darkens the surface, 0 to 1. */\n readonly occlusionStrength?: number;\n /** How the alpha channel is interpreted. */\n readonly alphaMode?: MaterialAlphaMode;\n /** The cutoff below which a `\"mask\"` material discards a fragment. */\n readonly alphaCutoff?: number;\n /** Overall material alpha, 0 to 1. */\n readonly alpha?: number;\n /** Whether back faces are drawn. */\n readonly doubleSided?: boolean;\n /** Whether lighting is skipped entirely. */\n readonly unlit?: boolean;\n /** How strongly the environment map contributes. */\n readonly environmentIntensity?: number;\n}\n\n/**\n * The Babylon-Standard material properties an ignifx `.material.json` declares, for the cheap\n * non-PBR path (`docs/architecture/07-rendering.md` §2.6).\n *\n * @internal\n */\nexport interface StandardMaterialInput {\n /** A human-readable name. */\n readonly name?: string;\n /** Linear diffuse colour. */\n readonly diffuse?: readonly [number, number, number];\n /** The diffuse texture. */\n readonly diffuseTexture?: Texture2D;\n /** Linear specular colour. */\n readonly specular?: readonly [number, number, number];\n /** Specular exponent; higher values give a tighter highlight. */\n readonly specularPower?: number;\n /** The specular texture. */\n readonly specularTexture?: Texture2D;\n /** Linear emissive colour. */\n readonly emissive?: readonly [number, number, number];\n /** The emissive texture. */\n readonly emissiveTexture?: Texture2D;\n /** The tangent-space normal map. */\n readonly normalTexture?: Texture2D;\n /** The opacity texture. */\n readonly opacityTexture?: Texture2D;\n /** Overall material alpha, 0 to 1. */\n readonly alpha?: number;\n /** The cutoff below which a fragment is discarded. `0` disables the alpha test. */\n readonly alphaCutoff?: number;\n /** Whether back faces are drawn. */\n readonly doubleSided?: boolean;\n /** Whether lighting is skipped entirely. */\n readonly unlit?: boolean;\n}\n\n/**\n * Builds a Lite PBR material from ignifx props.\n *\n * @param input - The declared properties.\n * @returns The material. It holds no GPU resource of its own; the textures it references do.\n *\n * @example\n * ```ts\n * const gold = createPbrMaterialFromProps({ baseColor: [1, 0.77, 0.34, 1], metallic: 1, roughness: 0.25 });\n * ```\n *\n * @internal\n */\nexport function createPbrMaterialFromProps(input: PbrMaterialInput): PbrMaterialProps {\n const props: Partial<PbrMaterialProps> = {};\n if (input.name !== undefined) {\n props.name = input.name;\n }\n if (input.baseColor !== undefined) {\n props.baseColorFactor = [input.baseColor[0], input.baseColor[1], input.baseColor[2], input.baseColor[3]];\n }\n if (input.baseColorTexture !== undefined) {\n props.baseColorTexture = input.baseColorTexture;\n }\n if (input.metallic !== undefined) {\n props.metallicFactor = input.metallic;\n }\n if (input.roughness !== undefined) {\n props.roughnessFactor = input.roughness;\n }\n if (input.metallicRoughnessTexture !== undefined) {\n props.ormTexture = input.metallicRoughnessTexture;\n }\n if (input.normalTexture !== undefined) {\n props.normalTexture = input.normalTexture;\n }\n if (input.normalScale !== undefined) {\n props.normalTextureScale = input.normalScale;\n }\n if (input.emissiveTexture !== undefined) {\n props.emissiveTexture = input.emissiveTexture;\n }\n if (input.occlusionTexture !== undefined) {\n props.occlusionTexture = input.occlusionTexture;\n }\n if (input.occlusionStrength !== undefined) {\n props.occlusionStrength = input.occlusionStrength;\n }\n if (input.alpha !== undefined) {\n props.alpha = input.alpha;\n }\n if (input.doubleSided !== undefined) {\n props.doubleSided = input.doubleSided;\n }\n if (input.environmentIntensity !== undefined) {\n props.environmentIntensity = input.environmentIntensity;\n }\n if (input.alphaMode === \"blend\") {\n props.alphaBlend = true;\n }\n const material = createPbrMaterial(props);\n if (input.alphaMode === \"mask\") {\n setPbrAlphaCutoff(material, input.alphaCutoff ?? DEFAULT_ALPHA_CUTOFF);\n }\n if (input.emissive !== undefined) {\n setPbrEmissive(material, [input.emissive[0], input.emissive[1], input.emissive[2]]);\n }\n if (input.unlit === true) {\n setPbrUnlit(material);\n }\n return material;\n}\n\n/**\n * Builds a Lite Standard material from ignifx props.\n *\n * @param input - The declared properties.\n * @returns The material.\n *\n * @internal\n */\nexport function createStandardMaterialFromProps(input: StandardMaterialInput): StandardMaterialProps {\n const material = createStandardMaterial();\n if (input.name !== undefined) {\n material.name = input.name;\n }\n if (input.diffuse !== undefined) {\n writeTriple(material.diffuseColor, input.diffuse);\n }\n if (input.specular !== undefined) {\n writeTriple(material.specularColor, input.specular);\n }\n if (input.emissive !== undefined) {\n writeTriple(material.emissiveColor, input.emissive);\n }\n if (input.specularPower !== undefined) {\n material.specularPower = input.specularPower;\n }\n if (input.alpha !== undefined) {\n material.alpha = input.alpha;\n }\n if (input.alphaCutoff !== undefined) {\n material.alphaCutOff = input.alphaCutoff;\n }\n if (input.doubleSided !== undefined) {\n material.backFaceCulling = !input.doubleSided;\n }\n if (input.unlit !== undefined) {\n material.disableLighting = input.unlit;\n }\n if (input.diffuseTexture !== undefined) {\n material.diffuseTexture = input.diffuseTexture;\n }\n if (input.specularTexture !== undefined) {\n setStandardSpecularTexture(material, input.specularTexture);\n }\n if (input.emissiveTexture !== undefined) {\n setStandardEmissiveTexture(material, input.emissiveTexture);\n }\n if (input.normalTexture !== undefined) {\n setStandardBumpTexture(material, input.normalTexture);\n }\n if (input.opacityTexture !== undefined) {\n setStandardOpacityTexture(material, input.opacityTexture);\n }\n return material;\n}\n\n/**\n * The material a `MeshRenderer` uses when it declares none: a neutral, fully rough dielectric.\n *\n * @returns A fresh material. Callers share one instance per app rather than one per renderer.\n *\n * @internal\n */\nexport function createDefaultMaterial(): PbrMaterialProps {\n return createPbrMaterialFromProps({\n name: \"ignifx:default\",\n baseColor: [1, 1, 1, 1],\n metallic: 0,\n roughness: 0.9,\n });\n}\n\n/**\n * Replaces a PBR material's linear base colour.\n *\n * @param material - The material to change.\n * @param r - The linear red component.\n * @param g - The linear green component.\n * @param b - The linear blue component.\n * @param a - The alpha component.\n *\n * @internal\n */\nexport function setPbrBaseColor(material: PbrMaterialProps, r: number, g: number, b: number, a: number): void {\n const factor = material.baseColorFactor;\n if (factor === undefined) {\n material.baseColorFactor = [r, g, b, a];\n } else {\n factor[0] = r;\n factor[1] = g;\n factor[2] = b;\n factor[3] = a;\n }\n markMaterialDirty(material);\n}\n\n/**\n * Replaces a PBR material's metallic and roughness factors.\n *\n * @param material - The material to change.\n * @param metallic - The metallic factor, 0 to 1.\n * @param roughness - The roughness factor, 0 to 1.\n *\n * @internal\n */\nexport function setPbrMetallicRoughness(material: PbrMaterialProps, metallic: number, roughness: number): void {\n material.metallicFactor = metallic;\n material.roughnessFactor = roughness;\n markMaterialDirty(material);\n}\n\n/**\n * Replaces a material's overall alpha.\n *\n * @param material - The PBR or Standard material to change.\n * @param alpha - The new alpha, 0 to 1.\n *\n * @internal\n */\nexport function setMaterialAlpha(material: PbrMaterialProps | StandardMaterialProps, alpha: number): void {\n material.alpha = alpha;\n markMaterialDirty(material);\n}\n\n/**\n * Marks a material's uniform block for re-upload on the next frame.\n *\n * @remarks\n * This is the cheap path and covers every scalar, vector, and colour edit. It does **not** cover\n * changes that alter the compiled feature set; those go through {@link rebuildMaterialPipelines}.\n *\n * @param material - The material that changed.\n *\n * @internal\n */\nexport function markMaterialDirty(material: Material): void {\n markMaterialUboDirty(material);\n}\n\n/**\n * Rebuilds the renderables of a material whose compiled feature set changed.\n *\n * @remarks\n * Needed after binding or clearing a texture, changing culling, or toggling a sub-feature\n * (`index.d.ts` 9413). `rebuildFrameGraph` is left off so a component can batch several material\n * edits and rebuild the frame graph once.\n *\n * @param scene - The scene the material renders in.\n * @param material - The material that changed.\n *\n * @internal\n */\nexport function rebuildMaterialPipelines(scene: SceneContext, material: Material): void {\n rebuildMaterial(scene, material);\n}\n\n/**\n * Installs automatic dirty tracking on a material, so property writes mark its uniform block\n * without an explicit {@link markMaterialDirty}.\n *\n * @remarks\n * Lite installs the tracker by rewriting the material's property descriptors, and the module that\n * does it is loaded lazily, so this is asynchronous (`index.d.ts` 4480,\n * `lib/material/observable-material.js`). Opt-in only: it costs an accessor call per write, which\n * the zero-allocation rules (coding standards §7) do not want on every material.\n *\n * @param material - The PBR or Standard material to track.\n * @returns A promise that resolves once the tracker is installed.\n *\n * @internal\n */\nexport function enableMaterialChangeTracking(material: PbrMaterialProps | StandardMaterialProps): Promise<void> {\n return enableMaterialTracking(material);\n}\n\n/**\n * Reports whether Lite will alpha-blend a material declared with this alpha mode.\n *\n * @param mode - The declared alpha mode.\n * @returns `true` for `\"blend\"`, `false` for `\"opaque\"` and `\"mask\"`.\n *\n * @internal\n */\nexport function isBlendedAlphaMode(mode: MaterialAlphaMode): boolean {\n switch (mode) {\n case \"opaque\":\n case \"mask\":\n return false;\n case \"blend\":\n return true;\n default:\n return assertNever(mode, \"material alpha mode\");\n }\n}\n\n/**\n * Writes three components into a Lite colour tuple in place.\n *\n * @param target - The tuple Lite owns.\n * @param source - The values to copy.\n */\nfunction writeTriple(target: [number, number, number], source: readonly [number, number, number]): void {\n target[0] = source[0];\n target[1] = source[1];\n target[2] = source[2];\n}\n","import { CoreErrorCode } from \"../errors/error-codes.js\";\nimport { assertNever, IgnifxError } from \"../errors/ignifx-error.js\";\nimport { SHADER_UNIFORM_TYPES } from \"./shader-declaration.js\";\nimport type { ShaderTextureDeclaration, ShaderUniformDeclaration, ShaderUniformType } from \"./shader-declaration.js\";\n\n/**\n * The raw Babylon Lite material-plugin points, as a `@beta` escape hatch\n * (`docs/plan/2026-09-terrain-particles-shaders.md` §3.2, ADR-0024).\n *\n * `@beta` because the meaning of each point is whatever the surrounding Lite template declares at\n * that line; ignifx's stable contract is the three hooks of `./surface-shader.ts`. Four rules read\n * out of `@babylonjs/lite@1.27.0`'s `lib/` on 2026-09-08:\n *\n * - Plugin uniforms and samplers are **fragment-stage only** on both families\n * (`lib/material/plugin/plugin-bridge-shared.js` 99), and there is no vertex helper-function\n * channel, so vertex code may read only attributes, `mesh.world` and the scene block, and must be\n * statements rather than functions.\n * - `CUSTOM_FRAGMENT_BEFORE_FINALCOLORCOMPOSITION` is injected **twice** — Lite maps it to the two\n * adjacent PBR slots `AI` and `NI` — so its code must be idempotent or guard itself with a flag\n * set at an earlier point, and must declare nothing at statement level.\n * - Only PBR carries `CUSTOM_FRAGMENT_UPDATE_DIFFUSE` after `CUSTOM_FRAGMENT_UPDATE_ALPHA`;\n * Standard's template orders them the other way and has no `AI`/`NI`/`MF` slots.\n * - `roughness` and `metallic` are `let` in the PBR template and cannot be written.\n */\n\n/**\n * The Babylon Lite injection points a {@link MaterialPluginDefinition} may fill in.\n *\n * @remarks\n * The names are Lite's own (`MaterialPluginPoint`, `index.d.ts` 7084) and are taught verbatim,\n * because a plugin's code is written against the template around the point.\n *\n * @beta\n */\nexport const LITE_MATERIAL_PLUGIN_POINTS = [\n \"CUSTOM_FRAGMENT_DEFINITIONS\",\n \"CUSTOM_FRAGMENT_MAIN_BEGIN\",\n \"CUSTOM_FRAGMENT_UPDATE_ALPHA\",\n \"CUSTOM_FRAGMENT_UPDATE_DIFFUSE\",\n \"CUSTOM_FRAGMENT_BEFORE_LIGHTS\",\n \"CUSTOM_FRAGMENT_BEFORE_FINALCOLORCOMPOSITION\",\n \"CUSTOM_FRAGMENT_BEFORE_FRAGCOLOR\",\n \"CUSTOM_VERTEX_MAIN_BEGIN\",\n \"CUSTOM_VERTEX_UPDATE_WORLDPOS\",\n \"CUSTOM_VERTEX_MAIN_END\",\n] as const;\n\n/**\n * One of Babylon Lite's ten material-plugin injection points.\n *\n * @beta\n */\nexport type LiteMaterialPluginPoint = (typeof LITE_MATERIAL_PLUGIN_POINTS)[number];\n\n/**\n * The default priority Babylon Lite gives a plugin with none (`index.d.ts` 7057).\n *\n * @beta\n */\nexport const MATERIAL_PLUGIN_DEFAULT_PRIORITY = 500;\n\n/**\n * How many `texture`/`sampler` pairs one material's plugins may declare together.\n *\n * @remarks\n * Measured on a device on 2026-09-08 (spike S0.2): a fully textured PBR material — base colour,\n * normal, ORM, emissive — with image-based lighting and one PCF shadow light already binds seven\n * textures and seven samplers of the sixteen per stage that every WebGPU implementation guarantees,\n * SwiftShader included, and Lite requests no higher `requiredLimits`. Nine is what is left, and it\n * drops to eight with a second shadow light and seven with a lightmap, so a material that means to\n * be portable should stay well under the cap.\n *\n * @beta\n */\nexport const MATERIAL_PLUGIN_SAMPLER_BUDGET = 9;\n\n/**\n * The WGSL names the PBR and Standard templates already own, which a plugin may not reuse for a\n * uniform field or a sampler.\n *\n * @remarks\n * A plugin's fields land in the host's own uniform block and its samplers in the host's own bind\n * group, so a collision is a duplicate WGSL declaration and the whole material stops compiling with\n * a message that names neither the plugin nor the field. Refusing at attach time is the difference\n * between a sentence and a shader dump. Read from `pbr-template.js` `_baseMaterialUboFields` and\n * `_baseBindings`, and `standard-template.js` `materialStruct` and `_baseBindings`.\n *\n * @beta\n */\nexport const MATERIAL_PLUGIN_RESERVED_NAMES: readonly string[] = Object.freeze([\n // Blocks and entry points the templates declare.\n \"material\",\n \"mesh\",\n \"scene\",\n \"lights\",\n \"pluginUbo\",\n \"shadowParams\",\n \"main\",\n // PBR material uniform fields.\n \"environmentIntensity\",\n \"directIntensity\",\n \"reflectance\",\n \"materialAlpha\",\n \"baseColorFactor\",\n \"metallicFactor\",\n \"roughnessFactor\",\n \"normalScale\",\n \"lightFalloffMode\",\n \"anisotropyParams\",\n // PBR samplers.\n \"baseColorTexture\",\n \"baseColorSampler\",\n \"normalTexture\",\n \"normalSampler_\",\n \"ormTexture\",\n \"ormSampler\",\n \"emissiveTexture\",\n \"emissiveSampler\",\n \"specGlossTexture\",\n \"specGlossSampler\",\n // Standard samplers (`standard-template.js` uses two-letter names).\n \"dT\",\n \"dS\",\n \"mat\",\n \"up\",\n]);\n\n/**\n * What a raw material plugin declares: a name, the values and textures it wants beside the host\n * material's own, and the WGSL it injects.\n *\n * @beta\n */\nexport interface MaterialPluginDefinition {\n /** The plugin's identity. It is part of Lite's pipeline cache key, so it must be stable. */\n readonly name: string;\n /** Lower runs first; Lite's own default is {@link MATERIAL_PLUGIN_DEFAULT_PRIORITY}. */\n readonly priority: number;\n /** The uniform fields appended to the host material's uniform block. Fragment stage only. */\n readonly uniforms: readonly ShaderUniformDeclaration[];\n /** The `texture`/`sampler` pairs added to the host material's bind group. Fragment stage only. */\n readonly textures: readonly ShaderTextureDeclaration[];\n /** The WGSL to inject, by point. Vertex points take statements; there are no vertex helpers. */\n readonly code: Readonly<Partial<Record<LiteMaterialPluginPoint, string>>>;\n}\n\n/**\n * The properties {@link defineMaterialPlugin} accepts; everything but `name` and `code` has a\n * default.\n *\n * @beta\n */\nexport interface MaterialPluginDefinitionInit {\n /** The plugin's identity. */\n readonly name: string;\n /** Lower runs first. Defaults to {@link MATERIAL_PLUGIN_DEFAULT_PRIORITY}. */\n readonly priority?: number;\n /** The uniform fields. Defaults to none. */\n readonly uniforms?: readonly ShaderUniformDeclaration[];\n /** The samplers. Defaults to none. */\n readonly textures?: readonly ShaderTextureDeclaration[];\n /** The WGSL to inject, by point. */\n readonly code: Readonly<Partial<Record<LiteMaterialPluginPoint, string>>>;\n}\n\n/** Matches a WGSL identifier. */\nconst IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;\n\n/** Matches a legal plugin name: an identifier, optionally with `.`, `:`, or `-` inside it. */\nconst PLUGIN_NAME = /^[A-Za-z_][A-Za-z0-9_]*(?:[.:-][A-Za-z0-9_]+)*$/;\n\n/**\n * Validates a raw material-plugin declaration and fills in its defaults.\n *\n * @remarks\n * Nothing here reaches a device: the result is plain data that `attachSurfaceShaders` and\n * `attachMaterialPlugin` turn into a Lite plugin. The checks are the ones whose failure would\n * otherwise surface as a WGSL compile error with no mention of the plugin — an empty `code`, a\n * duplicate or reserved binding name, a name that is not a WGSL identifier, an unknown injection\n * point, or more samplers than {@link MATERIAL_PLUGIN_SAMPLER_BUDGET}.\n *\n * The **surface-shader compiler produces one of these**, so a bug in this validation is a bug in\n * every surface shader too, which is why it lives here rather than inside the compiler.\n *\n * @param definition - The declaration.\n * @returns The same declaration with `priority`, `uniforms`, and `textures` filled in.\n * @throws IgnifxError with code `IGX-0723` when `code` fills in no point, `IGX-0712` when a name is\n * not a legal, unique, unreserved WGSL identifier or a point name is unknown, or `IGX-0726` when the\n * plugin alone exceeds the sampler budget.\n *\n * @example\n * ```ts\n * const tint = defineMaterialPlugin({\n * name: \"tint\",\n * code: { CUSTOM_FRAGMENT_UPDATE_ALPHA: \"baseColor = baseColor * vec3<f32>(1.0, 0.5, 0.5);\" },\n * });\n * ```\n *\n * @beta\n */\nexport function defineMaterialPlugin(definition: MaterialPluginDefinitionInit): MaterialPluginDefinition {\n const name = definition.name;\n if (!PLUGIN_NAME.test(name)) {\n throw new IgnifxError(\n CoreErrorCode.unknownShaderBinding,\n `${JSON.stringify(name)} is not a legal material-plugin name.`,\n {\n context: { plugin: name, name },\n hint: \"Start with a letter or underscore; letters, digits, underscores, and inner . : - follow.\",\n },\n );\n }\n const points = Object.keys(definition.code);\n let filled = 0;\n for (const point of points) {\n if (!isLiteMaterialPluginPoint(point)) {\n throw new IgnifxError(CoreErrorCode.unknownShaderBinding, `${name} declares no Lite point named ${point}.`, {\n context: { plugin: name, name: point, point },\n hint: `The ten points are ${LITE_MATERIAL_PLUGIN_POINTS.join(\", \")}.`,\n });\n }\n if ((definition.code[point] ?? \"\").trim().length > 0) {\n filled += 1;\n }\n }\n if (filled === 0) {\n throw new IgnifxError(CoreErrorCode.surfaceHookMissing, `${name} injects no WGSL at any Lite point.`, {\n context: { plugin: name, name },\n hint: \"Fill in at least one of the ten points, or do not attach the plugin.\",\n });\n }\n const uniforms = definition.uniforms ?? [];\n const textures = definition.textures ?? [];\n const seen = new Set<string>();\n for (const uniform of uniforms) {\n assertBindingName(name, uniform.name, seen);\n assertUniformType(name, uniform.name, uniform.type);\n }\n for (const texture of textures) {\n assertBindingName(name, texture.name, seen);\n assertBindingName(name, `${texture.name}Sampler`, seen);\n }\n if (textures.length > MATERIAL_PLUGIN_SAMPLER_BUDGET) {\n throw new IgnifxError(\n CoreErrorCode.surfaceSamplerBudgetExceeded,\n `${name} declares ${String(textures.length)} samplers; a material's plugins may declare ${String(MATERIAL_PLUGIN_SAMPLER_BUDGET)} together.`,\n {\n context: { plugin: name, samplers: textures.length, budget: MATERIAL_PLUGIN_SAMPLER_BUDGET },\n hint: \"Pack the maps into fewer textures — an RGBA control map rather than four masks.\",\n },\n );\n }\n return {\n name,\n priority: definition.priority ?? MATERIAL_PLUGIN_DEFAULT_PRIORITY,\n uniforms,\n textures,\n code: definition.code,\n };\n}\n\n/**\n * Whether a string is one of Lite's ten injection points.\n *\n * @param value - The candidate.\n * @returns `true` when Lite accepts it.\n *\n * @beta\n */\nexport function isLiteMaterialPluginPoint(value: string): value is LiteMaterialPluginPoint {\n for (const point of LITE_MATERIAL_PLUGIN_POINTS) {\n if (point === value) {\n return true;\n }\n }\n return false;\n}\n\n/**\n * How many floats one uniform of a declared type occupies on the CPU side.\n *\n * @param type - The declared WGSL type.\n * @returns The component count: 1, 2, 3, 4, or 16.\n *\n * @internal\n */\nexport function uniformComponentCount(type: ShaderUniformType): number {\n switch (type) {\n case \"vec2<f32>\": {\n return 2;\n }\n case \"vec3<f32>\": {\n return 3;\n }\n case \"vec4<f32>\": {\n return 4;\n }\n case \"mat4x4<f32>\": {\n return 16;\n }\n case \"f32\":\n case \"u32\":\n case \"i32\": {\n return 1;\n }\n default: {\n return assertNever(type, \"shader uniform type\");\n }\n }\n}\n\n/**\n * Refuses a binding name that is not a unique, unreserved WGSL identifier.\n *\n * @param plugin - The plugin's name, for the message.\n * @param binding - The candidate name.\n * @param seen - The names already taken by this plugin; the accepted name is added.\n * @throws IgnifxError with code `IGX-0712`.\n */\nfunction assertBindingName(plugin: string, binding: string, seen: Set<string>): void {\n if (!IDENTIFIER.test(binding)) {\n throw new IgnifxError(\n CoreErrorCode.unknownShaderBinding,\n `${plugin} declares ${JSON.stringify(binding)}, which is not a WGSL identifier.`,\n { context: { plugin, name: binding }, hint: \"Use letters, digits, and underscores, starting with a letter.\" },\n );\n }\n if (MATERIAL_PLUGIN_RESERVED_NAMES.includes(binding)) {\n throw new IgnifxError(\n CoreErrorCode.unknownShaderBinding,\n `${plugin} declares ${binding}, which Babylon Lite's own PBR or Standard shader already owns.`,\n { context: { plugin, name: binding }, hint: \"Rename it; a plugin shares the host material's WGSL namespace.\" },\n );\n }\n if (seen.has(binding)) {\n throw new IgnifxError(CoreErrorCode.unknownShaderBinding, `${plugin} declares ${binding} twice.`, {\n context: { plugin, name: binding },\n hint: \"Every uniform and texture of one plugin needs its own name.\",\n });\n }\n seen.add(binding);\n}\n\n/**\n * Refuses a uniform type Lite's plugin bridge cannot carry.\n *\n * @param plugin - The plugin's name, for the message.\n * @param binding - The uniform's name.\n * @param type - The declared type.\n * @throws IgnifxError with code `IGX-0712`.\n */\nfunction assertUniformType(plugin: string, binding: string, type: ShaderUniformType): void {\n if (!SHADER_UNIFORM_TYPES.includes(type)) {\n throw new IgnifxError(CoreErrorCode.unknownShaderBinding, `${plugin}.${binding} declares the type ${type}.`, {\n context: { plugin, name: binding, type },\n hint: `The plugin uniform types are ${SHADER_UNIFORM_TYPES.join(\", \")}.`,\n });\n }\n}\n"],"mappings":"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"}
|