@driftengine/core 4.8.4 → 4.8.6

package/dist/render/shaders/generated/skinBlur.wgsl.js

@@ -4,7 +4,7 @@
  * The GLSL beside this file is the source of truth. A hand edit here is discarded by
  * the next generation, and `npm run wgsl:check` fails the build when this is stale.
  */
-export const SKIN_BLUR_FRAG_WGSL = "struct Uniforms {\n    uStep: vec2<f32>,\n    uDepthToViewZ: vec4<f32>,\n    uFocal: f32,\n    uProfiles: array<vec4<f32>, 8>,\n}\n\n@group(0) @binding(1) \nvar<uniform> unnamed: Uniforms;\n@group(0) @binding(32) \nvar uSkin_t: texture_2d<f32>;\n@group(0) @binding(33) \nvar uSkin_s: sampler;\nvar<private> vUv_1: vec2<f32>;\nvar<private> fragColor: vec4<f32>;\n@group(0) @binding(34) \nvar uDepth_t: texture_2d<f32>;\n@group(0) @binding(35) \nvar uDepth_s: sampler;\n\nfn burleyMass_u0028_f1_u003b_vf3_u003b(x: ptr<function, f32>, d: ptr<function, vec3<f32>>) -> vec3<f32> {\n    let _e51 = (*x);\n    let _e53 = (*d);\n    let _e57 = (*x);\n    let _e59 = (*d);\n    return (vec3(0.5f) - ((exp((vec3(-(_e51)) / _e53)) + (exp((vec3(-(_e57)) / (_e59 * 3f))) * 3f)) * 0.125f));\n}\n\nfn viewZ_u0028_f1_u003b(depth: ptr<function, f32>) -> f32 {\n    var ndc: f32;\n\n    let _e51 = (*depth);\n    ndc = (1f - (_e51 * 2f));\n    let _e56 = unnamed.uDepthToViewZ[0u];\n    let _e57 = ndc;\n    let _e61 = unnamed.uDepthToViewZ[1u];\n    let _e65 = unnamed.uDepthToViewZ[2u];\n    let _e66 = ndc;\n    let _e70 = unnamed.uDepthToViewZ[3u];\n    return (((_e56 * _e57) + _e61) / ((_e65 * _e66) + _e70));\n}\n\nfn main_1() {\n    var own: vec4<f32>;\n    var depth_1: f32;\n    var profile: i32;\n    var d_1: vec3<f32>;\n    var widest: f32;\n    var z: f32;\n    var param: f32;\n    var pixels: f32;\n    var centre: vec3<f32>;\n    var param_1: f32;\n    var param_2: vec3<f32>;\n    var sum: vec3<f32>;\n    var weight: vec3<f32>;\n    var i: i32;\n    var outer: vec3<f32>;\n    var local: vec3<f32>;\n    var indexable: array<f32, 6>;\n    var param_3: f32;\n    var param_4: vec3<f32>;\n    var w: vec3<f32>;\n    var indexable_1: array<f32, 6>;\n    var param_5: f32;\n    var param_6: vec3<f32>;\n    var side: i32;\n    var uv: vec2<f32>;\n    var indexable_2: array<f32, 7>;\n    var tap: vec4<f32>;\n    var tapZ: f32;\n    var param_7: f32;\n    var keep: f32;\n    var cover: f32;\n\n    let _e80 = vUv_1;\n    let _e81 = textureSampleLevel(uSkin_t, uSkin_s, _e80, 0f);\n    own = _e81;\n    let _e83 = own[3u];\n    if (_e83 < 0.0001f) {\n        fragColor = vec4<f32>(0f, 0f, 0f, 0f);\n        return;\n    }\n    let _e85 = vUv_1;\n    let _e86 = textureSampleLevel(uDepth_t, uDepth_s, _e85, 0f);\n    depth_1 = _e86.x;\n    let _e88 = depth_1;\n    if (_e88 <= 0f) {\n        let _e90 = own;\n        fragColor = _e90;\n        return;\n    }\n    let _e92 = own[3u];\n    profile = clamp((i32(((_e92 * 8f) + 0.5f)) - 1i), 0i, 7i);\n    let _e98 = profile;\n    let _e101 = unnamed.uProfiles[_e98];\n    d_1 = max(_e101.xyz, vec3<f32>(0.000001f, 0.000001f, 0.000001f));\n    let _e105 = d_1[0u];\n    let _e107 = d_1[1u];\n    let _e109 = d_1[2u];\n    widest = max(_e105, max(_e107, _e109));\n    let _e112 = depth_1;\n    param = _e112;\n    let _e113 = viewZ_u0028_f1_u003b((&param));\n    z = abs(_e113);\n    let _e115 = widest;\n    let _e117 = unnamed.uFocal;\n    let _e119 = z;\n    pixels = ((_e115 * _e117) / max(_e119, 0.0001f));\n    let _e122 = pixels;\n    if (_e122 < 0.5f) {\n        let _e124 = own;\n        fragColor = _e124;\n        return;\n    }\n    let _e125 = widest;\n    param_1 = (0.2f * _e125);\n    let _e127 = d_1;\n    param_2 = _e127;\n    let _e128 = burleyMass_u0028_f1_u003b_vf3_u003b((&param_1), (&param_2));\n    centre = (_e128 * 2f);\n    let _e130 = own;\n    let _e132 = centre;\n    sum = (_e130.xyz * _e132);\n    let _e134 = centre;\n    weight = _e134;\n    i = 1i;\n    loop {\n        let _e135 = i;\n        if (_e135 < 7i) {\n            let _e137 = i;\n            if (_e137 < 6i) {\n                let _e139 = i;\n                indexable = array<f32, 6>(0.2f, 0.75f, 1.6f, 2.8f, 4.55f, 7.3f);\n                let _e142 = indexable[min(_e139, 5i)];\n                let _e143 = widest;\n                param_3 = (_e142 * _e143);\n                let _e145 = d_1;\n                param_4 = _e145;\n                let _e146 = burleyMass_u0028_f1_u003b_vf3_u003b((&param_3), (&param_4));\n                local = _e146;\n            } else {\n                local = vec3<f32>(0.5f, 0.5f, 0.5f);\n            }\n            let _e147 = local;\n            outer = _e147;\n            let _e148 = outer;\n            let _e149 = i;\n            indexable_1 = array<f32, 6>(0.2f, 0.75f, 1.6f, 2.8f, 4.55f, 7.3f);\n            let _e152 = indexable_1[(_e149 - 1i)];\n            let _e153 = widest;\n            param_5 = (_e152 * _e153);\n            let _e155 = d_1;\n            param_6 = _e155;\n            let _e156 = burleyMass_u0028_f1_u003b_vf3_u003b((&param_5), (&param_6));\n            w = (_e148 - _e156);\n            side = -1i;\n            loop {\n                let _e158 = side;\n                if (_e158 <= 1i) {\n                    let _e160 = vUv_1;\n                    let _e162 = unnamed.uStep;\n                    let _e163 = side;\n                    let _e165 = i;\n                    indexable_2 = array<f32, 7>(0f, 0.4f, 1.1f, 2.1f, 3.5f, 5.6f, 9f);\n                    let _e167 = indexable_2[_e165];\n                    let _e169 = pixels;\n                    uv = (_e160 + (_e162 * ((f32(_e163) * _e167) * _e169)));\n                    let _e173 = uv;\n                    let _e174 = textureSampleLevel(uSkin_t, uSkin_s, _e173, 0f);\n                    tap = _e174;\n                    let _e175 = uv;\n                    let _e176 = textureSampleLevel(uDepth_t, uDepth_s, _e175, 0f);\n                    param_7 = _e176.x;\n                    let _e178 = viewZ_u0028_f1_u003b((&param_7));\n                    tapZ = abs(_e178);\n                    let _e180 = tapZ;\n                    let _e181 = z;\n                    let _e184 = widest;\n                    keep = clamp((1f - (abs((_e180 - _e181)) / (4f * _e184))), 0f, 1f);\n                    let _e190 = tap[3u];\n                    let _e192 = own[3u];\n                    cover = clamp((_e190 / _e192), 0f, 1f);\n                    let _e195 = tap;\n                    let _e197 = w;\n                    let _e199 = keep;\n                    let _e201 = sum;\n                    sum = (_e201 + ((_e195.xyz * _e197) * _e199));\n                    let _e203 = w;\n                    let _e204 = cover;\n                    let _e205 = keep;\n                    let _e208 = weight;\n                    weight = (_e208 + (_e203 * (_e204 * _e205)));\n                    continue;\n                } else {\n                    break;\n                }\n                continuing {\n                    let _e210 = side;\n                    side = (_e210 + 2i);\n                }\n            }\n            continue;\n        } else {\n            break;\n        }\n        continuing {\n            let _e212 = i;\n            i = (_e212 + 1i);\n        }\n    }\n    let _e214 = sum;\n    let _e215 = weight;\n    let _e216 = (_e214 / _e215);\n    let _e218 = own[3u];\n    fragColor = vec4<f32>(_e216.x, _e216.y, _e216.z, _e218);\n    return;\n}\n\n@fragment \nfn main(@location(0) vUv: vec2<f32>) -> @location(0) vec4<f32> {\n    vUv_1 = vUv;\n    main_1();\n    let _e3 = fragColor;\n    return _e3;\n}\n";
+export const SKIN_BLUR_FRAG_WGSL = "struct Uniforms {\n    uStep: vec2<f32>,\n    uDepthToViewZ: vec4<f32>,\n    uFocal: f32,\n    uProfiles: array<vec4<f32>, 8>,\n    uApplyAlbedo: f32,\n}\n\n@group(0) @binding(1) \nvar<uniform> unnamed: Uniforms;\n@group(0) @binding(36) \nvar uAlbedo_t: texture_2d<f32>;\n@group(0) @binding(37) \nvar uAlbedo_s: sampler;\nvar<private> vUv_1: vec2<f32>;\n@group(0) @binding(32) \nvar uSkin_t: texture_2d<f32>;\n@group(0) @binding(33) \nvar uSkin_s: sampler;\nvar<private> fragColor: vec4<f32>;\n@group(0) @binding(34) \nvar uDepth_t: texture_2d<f32>;\n@group(0) @binding(35) \nvar uDepth_s: sampler;\n\nfn burleyMass_u0028_f1_u003b_vf3_u003b(x: ptr<function, f32>, d: ptr<function, vec3<f32>>) -> vec3<f32> {\n    let _e54 = (*x);\n    let _e56 = (*d);\n    let _e60 = (*x);\n    let _e62 = (*d);\n    return (vec3(0.5f) - ((exp((vec3(-(_e54)) / _e56)) + (exp((vec3(-(_e60)) / (_e62 * 3f))) * 3f)) * 0.125f));\n}\n\nfn viewZ_u0028_f1_u003b(depth: ptr<function, f32>) -> f32 {\n    var ndc: f32;\n\n    let _e54 = (*depth);\n    ndc = (1f - (_e54 * 2f));\n    let _e59 = unnamed.uDepthToViewZ[0u];\n    let _e60 = ndc;\n    let _e64 = unnamed.uDepthToViewZ[1u];\n    let _e68 = unnamed.uDepthToViewZ[2u];\n    let _e69 = ndc;\n    let _e73 = unnamed.uDepthToViewZ[3u];\n    return (((_e59 * _e60) + _e64) / ((_e68 * _e69) + _e73));\n}\n\nfn withAlbedo_u0028_vf3_u003b(light: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var albedo: vec4<f32>;\n\n    let _e55 = unnamed.uApplyAlbedo;\n    if (_e55 < 0.5f) {\n        let _e57 = (*light);\n        return _e57;\n    }\n    let _e58 = vUv_1;\n    let _e59 = textureSampleLevel(uAlbedo_t, uAlbedo_s, _e58, 0f);\n    albedo = _e59;\n    let _e60 = (*light);\n    let _e61 = albedo;\n    let _e65 = albedo[3u];\n    return ((_e60 * _e61.xyz) / vec3(max(_e65, 0.0001f)));\n}\n\nfn main_1() {\n    var own: vec4<f32>;\n    var depth_1: f32;\n    var param: vec3<f32>;\n    var profile: i32;\n    var d_1: vec3<f32>;\n    var widest: f32;\n    var z: f32;\n    var param_1: f32;\n    var pixels: f32;\n    var param_2: vec3<f32>;\n    var centre: vec3<f32>;\n    var param_3: f32;\n    var param_4: vec3<f32>;\n    var sum: vec3<f32>;\n    var weight: vec3<f32>;\n    var i: i32;\n    var outer: vec3<f32>;\n    var local: vec3<f32>;\n    var indexable: array<f32, 6>;\n    var param_5: f32;\n    var param_6: vec3<f32>;\n    var w: vec3<f32>;\n    var indexable_1: array<f32, 6>;\n    var param_7: f32;\n    var param_8: vec3<f32>;\n    var side: i32;\n    var uv: vec2<f32>;\n    var indexable_2: array<f32, 7>;\n    var tap: vec4<f32>;\n    var tapZ: f32;\n    var param_9: f32;\n    var keep: f32;\n    var cover: f32;\n    var param_10: vec3<f32>;\n\n    let _e86 = vUv_1;\n    let _e87 = textureSampleLevel(uSkin_t, uSkin_s, _e86, 0f);\n    own = _e87;\n    let _e89 = own[3u];\n    if (_e89 < 0.0001f) {\n        fragColor = vec4<f32>(0f, 0f, 0f, 0f);\n        return;\n    }\n    let _e91 = vUv_1;\n    let _e92 = textureSampleLevel(uDepth_t, uDepth_s, _e91, 0f);\n    depth_1 = _e92.x;\n    let _e94 = depth_1;\n    if (_e94 <= 0f) {\n        let _e96 = own;\n        param = _e96.xyz;\n        let _e98 = withAlbedo_u0028_vf3_u003b((&param));\n        let _e100 = own[3u];\n        fragColor = vec4<f32>(_e98.x, _e98.y, _e98.z, _e100);\n        return;\n    }\n    let _e106 = own[3u];\n    profile = clamp((i32(((_e106 * 8f) + 0.5f)) - 1i), 0i, 7i);\n    let _e112 = profile;\n    let _e115 = unnamed.uProfiles[_e112];\n    d_1 = max(_e115.xyz, vec3<f32>(0.000001f, 0.000001f, 0.000001f));\n    let _e119 = d_1[0u];\n    let _e121 = d_1[1u];\n    let _e123 = d_1[2u];\n    widest = max(_e119, max(_e121, _e123));\n    let _e126 = depth_1;\n    param_1 = _e126;\n    let _e127 = viewZ_u0028_f1_u003b((&param_1));\n    z = abs(_e127);\n    let _e129 = widest;\n    let _e131 = unnamed.uFocal;\n    let _e133 = z;\n    pixels = ((_e129 * _e131) / max(_e133, 0.0001f));\n    let _e136 = pixels;\n    if (_e136 < 0.5f) {\n        let _e138 = own;\n        param_2 = _e138.xyz;\n        let _e140 = withAlbedo_u0028_vf3_u003b((&param_2));\n        let _e142 = own[3u];\n        fragColor = vec4<f32>(_e140.x, _e140.y, _e140.z, _e142);\n        return;\n    }\n    let _e147 = widest;\n    param_3 = (0.2f * _e147);\n    let _e149 = d_1;\n    param_4 = _e149;\n    let _e150 = burleyMass_u0028_f1_u003b_vf3_u003b((&param_3), (&param_4));\n    centre = (_e150 * 2f);\n    let _e152 = own;\n    let _e154 = centre;\n    sum = (_e152.xyz * _e154);\n    let _e156 = centre;\n    weight = _e156;\n    i = 1i;\n    loop {\n        let _e157 = i;\n        if (_e157 < 7i) {\n            let _e159 = i;\n            if (_e159 < 6i) {\n                let _e161 = i;\n                indexable = array<f32, 6>(0.2f, 0.75f, 1.6f, 2.8f, 4.55f, 7.3f);\n                let _e164 = indexable[min(_e161, 5i)];\n                let _e165 = widest;\n                param_5 = (_e164 * _e165);\n                let _e167 = d_1;\n                param_6 = _e167;\n                let _e168 = burleyMass_u0028_f1_u003b_vf3_u003b((&param_5), (&param_6));\n                local = _e168;\n            } else {\n                local = vec3<f32>(0.5f, 0.5f, 0.5f);\n            }\n            let _e169 = local;\n            outer = _e169;\n            let _e170 = outer;\n            let _e171 = i;\n            indexable_1 = array<f32, 6>(0.2f, 0.75f, 1.6f, 2.8f, 4.55f, 7.3f);\n            let _e174 = indexable_1[(_e171 - 1i)];\n            let _e175 = widest;\n            param_7 = (_e174 * _e175);\n            let _e177 = d_1;\n            param_8 = _e177;\n            let _e178 = burleyMass_u0028_f1_u003b_vf3_u003b((&param_7), (&param_8));\n            w = (_e170 - _e178);\n            side = -1i;\n            loop {\n                let _e180 = side;\n                if (_e180 <= 1i) {\n                    let _e182 = vUv_1;\n                    let _e184 = unnamed.uStep;\n                    let _e185 = side;\n                    let _e187 = i;\n                    indexable_2 = array<f32, 7>(0f, 0.4f, 1.1f, 2.1f, 3.5f, 5.6f, 9f);\n                    let _e189 = indexable_2[_e187];\n                    let _e191 = pixels;\n                    uv = (_e182 + (_e184 * ((f32(_e185) * _e189) * _e191)));\n                    let _e195 = uv;\n                    let _e196 = textureSampleLevel(uSkin_t, uSkin_s, _e195, 0f);\n                    tap = _e196;\n                    let _e197 = uv;\n                    let _e198 = textureSampleLevel(uDepth_t, uDepth_s, _e197, 0f);\n                    param_9 = _e198.x;\n                    let _e200 = viewZ_u0028_f1_u003b((&param_9));\n                    tapZ = abs(_e200);\n                    let _e202 = tapZ;\n                    let _e203 = z;\n                    let _e206 = widest;\n                    keep = clamp((1f - (abs((_e202 - _e203)) / (4f * _e206))), 0f, 1f);\n                    let _e212 = tap[3u];\n                    let _e214 = own[3u];\n                    cover = clamp((_e212 / _e214), 0f, 1f);\n                    let _e217 = tap;\n                    let _e219 = w;\n                    let _e221 = keep;\n                    let _e223 = sum;\n                    sum = (_e223 + ((_e217.xyz * _e219) * _e221));\n                    let _e225 = w;\n                    let _e226 = cover;\n                    let _e227 = keep;\n                    let _e230 = weight;\n                    weight = (_e230 + (_e225 * (_e226 * _e227)));\n                    continue;\n                } else {\n                    break;\n                }\n                continuing {\n                    let _e232 = side;\n                    side = (_e232 + 2i);\n                }\n            }\n            continue;\n        } else {\n            break;\n        }\n        continuing {\n            let _e234 = i;\n            i = (_e234 + 1i);\n        }\n    }\n    let _e236 = sum;\n    let _e237 = weight;\n    param_10 = (_e236 / _e237);\n    let _e239 = withAlbedo_u0028_vf3_u003b((&param_10));\n    let _e241 = own[3u];\n    fragColor = vec4<f32>(_e239.x, _e239.y, _e239.z, _e241);\n    return;\n}\n\n@fragment \nfn main(@location(0) vUv: vec2<f32>) -> @location(0) vec4<f32> {\n    vUv_1 = vUv;\n    main_1();\n    let _e3 = fragColor;\n    return _e3;\n}\n";
 /**
  * What the transform assigned, so the renderer binds the same numbers.
  *
@@ -13,7 +13,7 @@ export const SKIN_BLUR_FRAG_WGSL = "struct Uniforms {\n    uStep: vec2<f32>,\n
 export const SKINBLUR_BINDINGS = {
     "SKIN_BLUR_FRAG": {
         "uniforms": 1,
-        "uniformSize": 176,
+        "uniformSize": 192,
         "fields": {
             "uStep": {
                 "offset": 0,
@@ -36,6 +36,11 @@ export const SKINBLUR_BINDINGS = {
                 "type": "vec4",
                 "length": 8,
                 "stride": 16
+            },
+            "uApplyAlbedo": {
+                "offset": 176,
+                "size": 4,
+                "type": "float"
             }
         },
         "textures": {
@@ -48,6 +53,11 @@ export const SKINBLUR_BINDINGS = {
                 "texture": 34,
                 "sampler": 35,
                 "type": "sampler2D"
+            },
+            "uAlbedo": {
+                "texture": 36,
+                "sampler": 37,
+                "type": "sampler2D"
             }
         }
     }

package/dist/render/shaders/particle.d.ts

@@ -37,7 +37,7 @@
 export declare const PARTICLE_BLADES = 2;
 export declare const PARTICLE_VERTS: number;
 export declare const PARTICLE_INDICES: number;
-export declare const PARTICLE_VERT = "#version 300 es\n/** Per-vertex: the quad corner, and which blade of the cross it belongs to. */\nlayout(location = 0) in vec2 aCorner;\nlayout(location = 1) in float aBlade;\n/** Per-instance. */\nlayout(location = 2) in vec3 aPos;\nlayout(location = 3) in float aSize;\nlayout(location = 4) in float aSpin;\nlayout(location = 5) in vec3 aColor;\n/** Opacity, age as a share of life, and this particle's own seed. */\nlayout(location = 6) in float aAlpha;\nlayout(location = 7) in float aAge;\nlayout(location = 8) in float aSeed;\nlayout(location = 9) in vec3 aVelocity;\n\nuniform mat4 uViewProj;\nuniform vec3 uCameraPos;\n/**\n * How far a particle is stretched along its own motion, in seconds of travel.\n *\n * Zero for smoke, which has no direction worth seeing. A spark is the opposite\n * case: an ember crossing a metre in a frame drawn as a round dot reads as a\n * floating pixel, and the same ember drawn as a short streak along its velocity\n * reads as a thrown spark. The eye gets its motion cue from the shape.\n */\nuniform float uStretchSec;\n/**\n * 1 to turn a single quad to face the camera, 0 to draw the world-fixed cross.\n *\n * **Camera-facing is the default, and the cross is the option.** It was the other way\n * round until a caller drew an additive glow with a camera looking down -Z and got a\n * bright straight line through the middle of every sprite. The cross is two blades at\n * right angles in *world* space: blade 0 spans X, blade 1 spans Z. Look down either\n * axis and that blade is edge-on, and a disc squeezed into a one-pixel column does not\n * lose the energy it was drawn with \u2014 it puts all of it in that column. Alpha-blended\n * smoke half hides it behind its own noise. Additive has nothing to hide it with.\n *\n * Fading a blade out as it turns edge-on fixes that one case and not the matching one:\n * both blades contain world Y, so a camera looking straight down sees *both* edge-on\n * and the puff is a plus sign of two lines, or nothing at all once they are faded. A\n * camera-facing quad has no angle at which it thins, which is why it is what particle\n * systems generally draw.\n *\n * The cross is still worth keeping. Two blades give real parallax when a camera moves\n * through a puff, and that is a volume cue a single quad cannot fake \u2014 worth having in\n * a ground-level world whose camera never looks far off the horizontal, where the\n * edge-on blade stays a thin sliver inside soft smoke rather than a line across a\n * spark. It also costs a brightness that swings with the view: a cross covers one\n * sprite of area seen down an axis and about 1.4 seen from the diagonal, so a puff\n * quietly pulses as the camera orbits it. A camera-facing quad covers the same area\n * from everywhere.\n */\nuniform float uCameraFacing;\n\nout vec2 vUv;\nout vec3 vColor;\nout float vAlpha;\nout float vAge;\nout float vSeed;\nout vec3 vWorldPos;\nout vec3 vNormal;\n\nvoid main() {\n  float s = sin(aSpin);\n  float c = cos(aSpin);\n  // Roll within the blade's own plane, so the two blades never look like one\n  // rigid object turning.\n  vec2 rolled = vec2(aCorner.x * c - aCorner.y * s, aCorner.x * s + aCorner.y * c);\n\n  /*\n   * The plane the corners are laid out in, built from the particle's centre rather than\n   * from the corner being transformed, so all four corners of a quad share one basis and\n   * the quad stays planar and rectangular.\n   */\n  vec3 across;\n  vec3 up;\n  float bladeGain;\n  if (uCameraFacing > 0.5) {\n    vec3 toCamera = normalize(uCameraPos - aPos);\n    /* Any reference not parallel to the view. World up serves everywhere except looking\n       straight up or down it, where the two are the same line and the cross product\n       vanishes; +Z takes over there. */\n    vec3 reference = abs(toCamera.y) > 0.999 ? vec3(0.0, 0.0, 1.0) : vec3(0.0, 1.0, 0.0);\n    across = normalize(cross(reference, toCamera));\n    up = cross(toCamera, across);\n    /*\n     * One quad, not two. Both blades face the camera here, so they would land on exactly\n     * the same pixels and the second would be nothing but the first drawn again: double\n     * the fill for double the brightness no caller asked for. Collapsing it to zero area\n     * costs nothing \u2014 the rasteriser drops a degenerate triangle before it shades \u2014 and\n     * leaves the vertex and index buffers the shape both backends already build, so a\n     * batch picks its facing without either one rebuilding its geometry.\n     */\n    bladeGain = aBlade < 0.5 ? 1.0 : 0.0;\n  } else {\n    across = aBlade < 0.5 ? vec3(1.0, 0.0, 0.0) : vec3(0.0, 0.0, 1.0);\n    up = vec3(0.0, 1.0, 0.0);\n    bladeGain = 1.0;\n  }\n  vec3 offset = (across * rolled.x + up * rolled.y) * aSize;\n\n  /*\n   * Stretched along travel. Applied as an extra displacement on the component of\n   * the corner that already points along the motion, so a stationary particle is\n   * untouched and a fast one lengthens without also getting fatter.\n   */\n  if (uStretchSec > 0.0) {\n    vec3 travel = aVelocity * uStretchSec;\n    float along = dot(normalize(offset + vec3(1e-6)), normalize(travel + vec3(1e-6)));\n    offset += travel * along * 0.5;\n  }\n\n  /* bladeGain applied here, after the stretch rather than before it, so a dropped blade\n     is degenerate whatever the stretch added: all four of its corners land on aPos. */\n  vec3 world = aPos + offset * bladeGain;\n  vUv = aCorner;\n  vColor = aColor;\n  vAlpha = aAlpha;\n  vAge = aAge;\n  vSeed = aSeed;\n  vWorldPos = world;\n  /*\n   * The blade's own facing, flipped toward the viewer. A cross has no meaningful\n   * outward normal, and a puff of smoke is not a surface \u2014 but it does have to be\n   * *lit*, and a normal facing the camera is the standard, honest cheat for a\n   * volume approximated by cards: it makes the puff read as a lump catching light\n   * from wherever the light is, rather than as a flat panel that goes black at\n   * some angles.\n   */\n  vec3 face = cross(across, up);\n  vec3 toEye = normalize(uCameraPos - world);\n  vNormal = dot(face, toEye) < 0.0 ? -face : face;\n\n  gl_Position = uViewProj * vec4(world, 1.0);\n}\n";
+export declare const PARTICLE_VERT = "#version 300 es\n/** Per-vertex: the quad corner, and which blade of the cross it belongs to. */\nlayout(location = 0) in vec2 aCorner;\nlayout(location = 1) in float aBlade;\n/** Per-instance. */\nlayout(location = 2) in vec3 aPos;\nlayout(location = 3) in float aSize;\nlayout(location = 4) in float aSpin;\nlayout(location = 5) in vec3 aColor;\n/** Opacity, age as a share of life, and this particle's own seed. */\nlayout(location = 6) in float aAlpha;\nlayout(location = 7) in float aAge;\nlayout(location = 8) in float aSeed;\nlayout(location = 9) in vec3 aVelocity;\n/**\n * A sprite's flipbook frame and its half-height: `ParticleInstances.frames` and `heights`. The\n * procedural materials read neither, and a height of 0 is a square, its height its width.\n */\nlayout(location = 10) in vec2 aSprite;\n\nuniform mat4 uViewProj;\nuniform vec3 uCameraPos;\n/**\n * How far a particle is stretched along its own motion, in seconds of travel.\n *\n * Zero for smoke, which has no direction worth seeing. A spark is the opposite\n * case: an ember crossing a metre in a frame drawn as a round dot reads as a\n * floating pixel, and the same ember drawn as a short streak along its velocity\n * reads as a thrown spark. The eye gets its motion cue from the shape.\n */\nuniform float uStretchSec;\n/**\n * 1 to turn a single quad to face the camera, 0 to draw the world-fixed cross.\n *\n * **Camera-facing is the default, and the cross is the option.** It was the other way\n * round until a caller drew an additive glow with a camera looking down -Z and got a\n * bright straight line through the middle of every sprite. The cross is two blades at\n * right angles in *world* space: blade 0 spans X, blade 1 spans Z. Look down either\n * axis and that blade is edge-on, and a disc squeezed into a one-pixel column does not\n * lose the energy it was drawn with \u2014 it puts all of it in that column. Alpha-blended\n * smoke half hides it behind its own noise. Additive has nothing to hide it with.\n *\n * Fading a blade out as it turns edge-on fixes that one case and not the matching one:\n * both blades contain world Y, so a camera looking straight down sees *both* edge-on\n * and the puff is a plus sign of two lines, or nothing at all once they are faded. A\n * camera-facing quad has no angle at which it thins, which is why it is what particle\n * systems generally draw.\n *\n * The cross is still worth keeping. Two blades give real parallax when a camera moves\n * through a puff, and that is a volume cue a single quad cannot fake \u2014 worth having in\n * a ground-level world whose camera never looks far off the horizontal, where the\n * edge-on blade stays a thin sliver inside soft smoke rather than a line across a\n * spark. It also costs a brightness that swings with the view: a cross covers one\n * sprite of area seen down an axis and about 1.4 seen from the diagonal, so a puff\n * quietly pulses as the camera orbits it. A camera-facing quad covers the same area\n * from everywhere.\n */\nuniform float uCameraFacing;\n/** How far each particle is moved toward the eye, in metres: `ParticleBatchOptions.cameraOffset`. */\nuniform float uCameraOffset;\n\nout vec2 vUv;\nout vec3 vColor;\nout float vAlpha;\nout float vAge;\nout float vSeed;\nout vec3 vWorldPos;\nout vec3 vNormal;\n/** The flipbook frame, for the sprite material; and the depth from the eye, for its fades. */\nout float vFrame;\nout float vViewDepth;\n\nvoid main() {\n  float s = sin(aSpin);\n  float c = cos(aSpin);\n  // Roll within the blade's own plane, so the two blades never look like one\n  // rigid object turning.\n  vec2 rolled = vec2(aCorner.x * c - aCorner.y * s, aCorner.x * s + aCorner.y * c);\n\n  /*\n   * The plane the corners are laid out in, built from the particle's centre rather than\n   * from the corner being transformed, so all four corners of a quad share one basis and\n   * the quad stays planar and rectangular.\n   */\n  vec3 across;\n  vec3 up;\n  float bladeGain;\n  /*\n   * **Along its travel**, `facing: 'velocity'` (2): the quad's up is the velocity seen across\n   * the view, so a streak of light or a stretched spark lies along its motion and still faces the\n   * eye. A particle at rest has no such direction and faces the camera as the default does.\n   */\n  vec3 viewer = normalize(uCameraPos - aPos);\n  vec3 alongView = aVelocity - viewer * dot(aVelocity, viewer);\n  if (uCameraFacing > 1.5 && dot(alongView, alongView) > 1e-10) {\n    up = normalize(alongView);\n    across = cross(up, viewer);\n    bladeGain = aBlade < 0.5 ? 1.0 : 0.0;\n  } else if (uCameraFacing > 0.5) {\n    vec3 toCamera = normalize(uCameraPos - aPos);\n    /* Any reference not parallel to the view. World up serves everywhere except looking\n       straight up or down it, where the two are the same line and the cross product\n       vanishes; +Z takes over there. */\n    vec3 reference = abs(toCamera.y) > 0.999 ? vec3(0.0, 0.0, 1.0) : vec3(0.0, 1.0, 0.0);\n    across = normalize(cross(reference, toCamera));\n    up = cross(toCamera, across);\n    /*\n     * One quad, not two. Both blades face the camera here, so they would land on exactly\n     * the same pixels and the second would be nothing but the first drawn again: double\n     * the fill for double the brightness no caller asked for. Collapsing it to zero area\n     * costs nothing \u2014 the rasteriser drops a degenerate triangle before it shades \u2014 and\n     * leaves the vertex and index buffers the shape both backends already build, so a\n     * batch picks its facing without either one rebuilding its geometry.\n     */\n    bladeGain = aBlade < 0.5 ? 1.0 : 0.0;\n  } else {\n    across = aBlade < 0.5 ? vec3(1.0, 0.0, 0.0) : vec3(0.0, 0.0, 1.0);\n    up = vec3(0.0, 1.0, 0.0);\n    bladeGain = 1.0;\n  }\n  vec3 offset = (across * rolled.x + up * rolled.y) * aSize;\n  /*\n   * **A sprite of two sizes** \u2014 a half-width and a half-height \u2014 rolls as a rectangle: the corner\n   * is scaled first and turned after. Only where a height was given, so a square particle keeps\n   * the arithmetic it always had to the bit.\n   */\n  if (aSprite.y > 0.0) {\n    vec2 extent = vec2(aCorner.x * aSize, aCorner.y * aSprite.y);\n    vec2 turned = vec2(extent.x * c - extent.y * s, extent.x * s + extent.y * c);\n    offset = across * turned.x + up * turned.y;\n  }\n\n  /*\n   * Stretched along travel. Applied as an extra displacement on the component of\n   * the corner that already points along the motion, so a stationary particle is\n   * untouched and a fast one lengthens without also getting fatter.\n   */\n  if (uStretchSec > 0.0) {\n    vec3 travel = aVelocity * uStretchSec;\n    float along = dot(normalize(offset + vec3(1e-6)), normalize(travel + vec3(1e-6)));\n    offset += travel * along * 0.5;\n  }\n\n  /* bladeGain applied here, after the stretch rather than before it, so a dropped blade\n     is degenerate whatever the stretch added: all four of its corners land on aPos. */\n  vec3 world = aPos + offset * bladeGain;\n  /* Toward the eye, so a sprite set into a surface is drawn in front of it. 0 moves nothing. */\n  world += viewer * uCameraOffset * bladeGain;\n  vUv = aCorner;\n  vFrame = aSprite.x;\n  vColor = aColor;\n  vAlpha = aAlpha;\n  vAge = aAge;\n  vSeed = aSeed;\n  vWorldPos = world;\n  /*\n   * The blade's own facing, flipped toward the viewer. A cross has no meaningful\n   * outward normal, and a puff of smoke is not a surface \u2014 but it does have to be\n   * *lit*, and a normal facing the camera is the standard, honest cheat for a\n   * volume approximated by cards: it makes the puff read as a lump catching light\n   * from wherever the light is, rather than as a flat panel that goes black at\n   * some angles.\n   */\n  vec3 face = cross(across, up);\n  vec3 toEye = normalize(uCameraPos - world);\n  vNormal = dot(face, toEye) < 0.0 ? -face : face;\n\n  gl_Position = uViewProj * vec4(world, 1.0);\n  /* A perspective projection's w is the depth from the eye, which is what the fades measure. */\n  vViewDepth = gl_Position.w;\n}\n";
 /**
  * Smoke, grit and dust: a soft body eroded by noise, alpha blended, and lit.
  *
@@ -80,3 +80,19 @@ export declare const PARTICLE_SPARK_FRAG = "#version 300 es\nprecision highp flo
  * existed; see `ParticleBatchOptions.fog`.
  */
 export declare const PARTICLE_MOTE_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\nin vec3 vColor;\nin float vAlpha;\nin float vAge;\nin float vSeed;\nin vec3 vWorldPos;\nin vec3 vNormal;\n\nuniform vec3 uCameraPos;\n/**\n * Whether the fragment stage mixes toward the medium's own colour at all. 0 \u2014 what a batch\n * gets by leaving ParticleBatchOptions.fog unset \u2014 leaves vColor untouched by distance, which\n * is what a caller reaching for this material over 'spark'/'smoke' is usually asking for: an\n * unlit point drawn exactly as its own colour says. 1 mixes toward mediumColor() by\n * mediumFog(), the same medium every other pass in the frame recedes into.\n */\nuniform int uFogEnabled;\n\nuniform vec3 uFogColor;\n/** Extinction per metre **at the camera's own height**, not at the base. */\nuniform float uFogDensity;\n/** Reciprocal scale height of the haze, per metre. 0 is a uniform medium. */\nuniform float uFogHeightFalloff;\n/** The camera's height, so a fragment's own height is one subtraction away. */\nuniform float uFogEyeY;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFogDensity;\nuniform float uUnderwaterFactor;\n/** 0 integrates a medium (Beer-Lambert); 1 ramps linearly between near and far. */\nuniform int uFogMode;\n/** Linear mode only: where haze begins, and where it is total. */\nuniform float uFogNear;\nuniform float uFogFar;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogMode == 1) {\n    float span = max(uFogFar - uFogNear, 1e-4);\n    float ramp = clamp((dist - uFogNear) / span, 0.0, 1.0);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uUnderwaterFogDensity * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(t) < 1e-4 ? 1e-4 : t;\n  float air = 1.0 - exp(-uFogDensity * dist * (1.0 - exp(-denom)) / denom);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uUnderwaterFogDensity * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\n\nout vec4 outColor;\n\n/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder then sRGB. See renderQuality.ts. */\nuniform int uOutputTransform;\n/** Scales the scene into the tone curve. 1 is the reference grade. See renderQuality.ts. */\nuniform float uOutputExposure;\n\n/*\n * ACES: the reference fit, not the cheap one.\n *\n * This was Narkowicz's single rational function, on the argument that the difference from\n * the reference curve is invisible next to the gain. That argument holds for a look and\n * fails for a *match*, which is what this option is for \u2014 aces exists so a world ported\n * from three.js reads the same, and three.js applies the full fit: into AP1 through\n * ACESInputMat, the RRT and ODT together, then back out through ACESOutputMat.\n *\n * The two curves are not a shade apart. Narkowicz is markedly brighter through the\n * midtones, which is exactly where an interior scene lives, and it is a large part of a\n * measured ~1.7x that survived correcting the colour space and the missing Lambert pi.\n * An approximation of a standard is the wrong thing to hold when the standard is the\n * specification.\n */\nvec3 rrtAndOdtFit(vec3 v) {\n  vec3 a = v * (v + 0.0245786) - 0.000090537;\n  vec3 b = v * (0.983729 * v + 0.4329510) + 0.238081;\n  return a / b;\n}\n\nvec3 acesFilmic(vec3 x) {\n  /*\n   * Exposure first, because a tone curve is only defined relative to one.\n   *\n   * The reference RRT and ODT are graded for a dark cinema. Every renderer that ships ACES\n   * scales its input to suit whatever it is actually shown on, and the factor each one\n   * picks is a *look*, not a standard - so this engine takes no position and reads it from\n   * the caller. Neutral by default, which is the reference grade unmodified. three.js's own\n   * pick is 1 / 0.6, for a consumer matching one.\n   */\n  x *= uOutputExposure;\n  // Columns, as GLSL reads them: sRGB -> XYZ -> D65_2_D60 -> AP1 -> RRT_SAT.\n  const mat3 ACES_INPUT = mat3(\n    0.59719, 0.07600, 0.02840,\n    0.35458, 0.90834, 0.13383,\n    0.04823, 0.01566, 0.83777\n  );\n  // ODT_SAT -> XYZ -> D60_2_D65 -> sRGB.\n  const mat3 ACES_OUTPUT = mat3(\n     1.60475, -0.10208, -0.00327,\n    -0.53108,  1.10813, -0.07276,\n    -0.07367, -0.00605,  1.07602\n  );\n  return clamp(ACES_OUTPUT * rrtAndOdtFit(ACES_INPUT * x), 0.0, 1.0);\n}\n\n/*\n * Linear to sRGB. The piecewise form rather than a plain pow: the linear toe near black\n * is where banding lives in an 8-bit buffer, and the cheap approximation puts it in the\n * wrong place.\n */\nvec3 linearToSrgb(vec3 c) {\n  vec3 low = c * 12.92;\n  vec3 high = 1.055 * pow(max(c, vec3(0.0)), vec3(1.0 / 2.4)) - 0.055;\n  return mix(high, low, step(c, vec3(0.0031308)));\n}\n\n\nvec3 highlightShoulder(vec3 c) {\n  float m = max(c.r, max(c.g, c.b));\n  if (m <= 0.8) return c;\n  float e = m - 0.8;\n  return c * ((0.8 + 0.2 * e / (e + 0.2)) / m);\n}\n\nvec3 applyOutputTransform(vec3 c) {\n  if (uOutputTransform == 0) return c;\n  if (uOutputTransform == 2) c = acesFilmic(c);\n  if (uOutputTransform == 3) c = highlightShoulder(c * uOutputExposure);\n  return linearToSrgb(c);\n}\n\n\nvoid main() {\n  /*\n   * One soft, round falloff \u2014 no erosion, no core past white, because this material draws\n   * neither a body being eaten by noise nor a light source. Squared rather than linear so the\n   * edge feathers instead of ramping, which is what keeps a field of these reading as dust\n   * rather than as a scatter of hard-edged discs.\n   */\n  float r = length(vUv);\n  float body = 1.0 - smoothstep(0.4, 1.0, r);\n  if (body <= 0.0) discard;\n  float alpha = body * body * vAlpha;\n  if (alpha <= 0.002) discard;\n\n  vec3 color = vColor;\n  if (uFogEnabled != 0) {\n    float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);\n    color = mix(color, mediumColor(), fog);\n  }\n  /*\n   * A real alpha blend (SRC_ALPHA, ONE_MINUS_SRC_ALPHA) rather than spark's energy-in-colour\n   * trick: this point genuinely occludes what little is behind it instead of adding light to it.\n   */\n  outColor = vec4(applyOutputTransform(color), alpha);\n}\n";
+/**
+ * A textured sprite: an image a consumer supplies, a cell of it at a time, at the colour and opacity
+ * each particle carries — what another engine's sprite renderer draws, and the material the three
+ * procedural ones above cannot be. Unlit: the colour is the particle's times the image's.
+ *
+ * **A flipbook** of `uCells.x` by `uCells.y` cells, numbered across then down from the top-left,
+ * a particle's frame naming one; with `uCells.z` at 1 the frame's fraction blends toward the next,
+ * so a slow flipbook does not step.
+ *
+ * **Two fades, each 0 for off.** A soft edge where the sprite meets the scene, by how far in front
+ * of the opaque depth it is over `uFade.x` metres — the hard line a flat card draws where it cuts
+ * a floor — and a fade over `uFade.y` metres in front of the eye, so a card the camera passes
+ * through does not fill the screen and vanish. The first reads a copy of the frame's depth, which
+ * is `uFade.z` at 1; where no copy can be had it is 0 and the edge stays hard.
+ */
+export declare const PARTICLE_SPRITE_FRAG: string;

package/dist/render/shaders/particle.js

@@ -1,5 +1,6 @@
 import { FOG_GLSL } from './fog.js';
 import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.js';
+import { glslIsFarDepth, glslSceneDepthToNdc } from '../depthConvention.js';
 import { MAX_POINT_LIGHTS } from '../lightBudget.js';
 /**
  * Particle materials: soft smoke, hot sparks, and unlit motes.
@@ -83,6 +84,11 @@ layout(location = 6) in float aAlpha;
 layout(location = 7) in float aAge;
 layout(location = 8) in float aSeed;
 layout(location = 9) in vec3 aVelocity;
+/**
+ * A sprite's flipbook frame and its half-height: \`ParticleInstances.frames\` and \`heights\`. The
+ * procedural materials read neither, and a height of 0 is a square, its height its width.
+ */
+layout(location = 10) in vec2 aSprite;
 
 uniform mat4 uViewProj;
 uniform vec3 uCameraPos;
@@ -122,6 +128,8 @@ uniform float uStretchSec;
  * from everywhere.
  */
 uniform float uCameraFacing;
+/** How far each particle is moved toward the eye, in metres: \`ParticleBatchOptions.cameraOffset\`. */
+uniform float uCameraOffset;
 
 out vec2 vUv;
 out vec3 vColor;
@@ -130,6 +138,9 @@ out float vAge;
 out float vSeed;
 out vec3 vWorldPos;
 out vec3 vNormal;
+/** The flipbook frame, for the sprite material; and the depth from the eye, for its fades. */
+out float vFrame;
+out float vViewDepth;
 
 void main() {
   float s = sin(aSpin);
@@ -146,7 +157,18 @@ void main() {
   vec3 across;
   vec3 up;
   float bladeGain;
-  if (uCameraFacing > 0.5) {
+  /*
+   * **Along its travel**, \`facing: 'velocity'\` (2): the quad's up is the velocity seen across
+   * the view, so a streak of light or a stretched spark lies along its motion and still faces the
+   * eye. A particle at rest has no such direction and faces the camera as the default does.
+   */
+  vec3 viewer = normalize(uCameraPos - aPos);
+  vec3 alongView = aVelocity - viewer * dot(aVelocity, viewer);
+  if (uCameraFacing > 1.5 && dot(alongView, alongView) > 1e-10) {
+    up = normalize(alongView);
+    across = cross(up, viewer);
+    bladeGain = aBlade < 0.5 ? 1.0 : 0.0;
+  } else if (uCameraFacing > 0.5) {
     vec3 toCamera = normalize(uCameraPos - aPos);
     /* Any reference not parallel to the view. World up serves everywhere except looking
        straight up or down it, where the two are the same line and the cross product
@@ -169,6 +191,16 @@ void main() {
     bladeGain = 1.0;
   }
   vec3 offset = (across * rolled.x + up * rolled.y) * aSize;
+  /*
+   * **A sprite of two sizes** — a half-width and a half-height — rolls as a rectangle: the corner
+   * is scaled first and turned after. Only where a height was given, so a square particle keeps
+   * the arithmetic it always had to the bit.
+   */
+  if (aSprite.y > 0.0) {
+    vec2 extent = vec2(aCorner.x * aSize, aCorner.y * aSprite.y);
+    vec2 turned = vec2(extent.x * c - extent.y * s, extent.x * s + extent.y * c);
+    offset = across * turned.x + up * turned.y;
+  }
 
   /*
    * Stretched along travel. Applied as an extra displacement on the component of
@@ -184,7 +216,10 @@ void main() {
   /* bladeGain applied here, after the stretch rather than before it, so a dropped blade
      is degenerate whatever the stretch added: all four of its corners land on aPos. */
   vec3 world = aPos + offset * bladeGain;
+  /* Toward the eye, so a sprite set into a surface is drawn in front of it. 0 moves nothing. */
+  world += viewer * uCameraOffset * bladeGain;
   vUv = aCorner;
+  vFrame = aSprite.x;
   vColor = aColor;
   vAlpha = aAlpha;
   vAge = aAge;
@@ -203,6 +238,8 @@ void main() {
   vNormal = dot(face, toEye) < 0.0 ? -face : face;
 
   gl_Position = uViewProj * vec4(world, 1.0);
+  /* A perspective projection's w is the depth from the eye, which is what the fades measure. */
+  vViewDepth = gl_Position.w;
 }
 `;
 /**
@@ -429,3 +466,98 @@ void main() {
   outColor = vec4(applyOutputTransform(color), alpha);
 }
 `;
+/**
+ * A textured sprite: an image a consumer supplies, a cell of it at a time, at the colour and opacity
+ * each particle carries — what another engine's sprite renderer draws, and the material the three
+ * procedural ones above cannot be. Unlit: the colour is the particle's times the image's.
+ *
+ * **A flipbook** of `uCells.x` by `uCells.y` cells, numbered across then down from the top-left,
+ * a particle's frame naming one; with `uCells.z` at 1 the frame's fraction blends toward the next,
+ * so a slow flipbook does not step.
+ *
+ * **Two fades, each 0 for off.** A soft edge where the sprite meets the scene, by how far in front
+ * of the opaque depth it is over `uFade.x` metres — the hard line a flat card draws where it cuts
+ * a floor — and a fade over `uFade.y` metres in front of the eye, so a card the camera passes
+ * through does not fill the screen and vanish. The first reads a copy of the frame's depth, which
+ * is `uFade.z` at 1; where no copy can be had it is 0 and the edge stays hard.
+ */
+export const PARTICLE_SPRITE_FRAG = `#version 300 es
+precision highp float;
+
+/* Every output of the vertex stage, in its order, read or not: the generated stages number their
+   locations in declaration order, so a fragment declaring a subset reads the wrong ones. */
+in vec2 vUv;
+in vec3 vColor;
+in float vAlpha;
+in float vAge;
+in float vSeed;
+in vec3 vWorldPos;
+in vec3 vNormal;
+in float vFrame;
+in float vViewDepth;
+
+/** The image, a surface texture: its first layer. */
+uniform mediump sampler2DArray uSprite;
+/** The frame's opaque depth, copied, for the soft edge. highp for the reason depth always is. */
+uniform highp sampler2D uDepth;
+/** Columns, rows, and 1 to blend between cells. */
+uniform vec4 uCells;
+/** The soft edge's distance, the eye fade's, and whether the depth copy is there to read. */
+uniform vec4 uFade;
+/** A depth sample to view-space metres, as the skin blur takes it. */
+uniform vec4 uDepthToViewZ;
+/** The target's size in pixels, so a fragment finds its own texel of the depth copy. */
+uniform vec2 uViewport;
+uniform vec3 uCameraPos;
+/** Whether the colour recedes into the medium: \`ParticleBatchOptions.fog\`. */
+uniform int uFogEnabled;
+${FOG_GLSL}
+
+out vec4 outColor;
+${OUTPUT_TRANSFORM_GLSL}
+
+/** Cell \`cell\` of the flipbook, at \`uv\` inside it. Integer arithmetic: see AGENTS.md. */
+vec2 cellUv(int cell, vec2 uv) {
+  int columns = max(int(uCells.x + 0.5), 1);
+  int rows = max(int(uCells.y + 0.5), 1);
+  int wrapped = cell % (columns * rows);
+  int column = wrapped % columns;
+  int row = wrapped / columns;
+  return (vec2(float(column), float(row)) + uv) / vec2(float(columns), float(rows));
+}
+
+float viewZ(float depth) {
+  float ndc = ${glslSceneDepthToNdc('depth')};
+  return (uDepthToViewZ.x * ndc + uDepthToViewZ.y) / (uDepthToViewZ.z * ndc + uDepthToViewZ.w);
+}
+
+void main() {
+  /* The corner's square to the image's: v runs down an image, and up a quad. */
+  vec2 uv = vec2(vUv.x * 0.5 + 0.5, 0.5 - vUv.y * 0.5);
+  float frame = max(vFrame, 0.0);
+  int first = int(floor(frame));
+  vec4 image = texture(uSprite, vec3(cellUv(first, uv), 0.0));
+  if (uCells.z > 0.5) {
+    vec4 next = texture(uSprite, vec3(cellUv(first + 1, uv), 0.0));
+    image = mix(image, next, fract(frame));
+  }
+
+  float fade = 1.0;
+  if (uFade.z > 0.5 && uFade.x > 0.0) {
+    float depth = textureLod(uDepth, gl_FragCoord.xy / uViewport, 0.0).r;
+    if (!(${glslIsFarDepth('depth')})) {
+      fade = clamp((abs(viewZ(depth)) - vViewDepth) / uFade.x, 0.0, 1.0);
+    }
+  }
+  if (uFade.y > 0.0) fade *= clamp(vViewDepth / uFade.y, 0.0, 1.0);
+
+  float alpha = vAlpha * image.a * fade;
+  if (alpha <= 0.001) discard;
+  vec3 color = vColor * image.rgb;
+  if (uFogEnabled != 0) {
+    float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);
+    color = mix(color, mediumColor(), fog);
+  }
+  outColor = vec4(applyOutputTransform(color), alpha);
+}
+`;

package/dist/render/shaders/skinBlur.js

@@ -6,6 +6,11 @@
  * **One pass, run twice**: along x into a target of its own, keeping the profile in the alpha, then
  * along y blended additively into the frame — its colour added, the frame's alpha kept.
  *
+ * **What it spreads is light, and the colour is applied after**, from the skin's own colour half at
+ * this pixel. Light travels beneath skin; the pigment a brow, a lip line or a freckle is made of
+ * does not, so spreading the coloured diffuse — as this did until 4.8.6 — smeared every mark on a
+ * face into the skin around it, and the blur's taps laid faint copies of each mark beside it.
+ *
  * **Refuses what is not the same skin**: a neighbour that wrote no skin, or one further in depth
  * than four of the profile's widest distances, takes no weight, and what is kept is divided by
  * what was kept, so a cheek's light does not pull toward the black beside its silhouette. A tap
@@ -32,6 +37,12 @@ uniform vec4 uDepthToViewZ;
 uniform float uFocal;
 /** Each profile's scatter distance per channel, in metres. */
 uniform vec4 uProfiles[${SKIN_PROFILES}];
+/**
+ * The skin's colour, and its coverage in the alpha: what the spread light is multiplied by on the
+ * second axis, where \`uApplyAlbedo\` is 1. Read at this pixel alone, because pigment does not move.
+ */
+uniform sampler2D uAlbedo;
+uniform float uApplyAlbedo;
 
 out vec4 fragColor;
 
@@ -48,6 +59,17 @@ vec3 burleyMass(float x, vec3 d) {
   return 0.5 - (exp(-x / d) + 3.0 * exp(-x / (3.0 * d))) * 0.125;
 }
 
+/**
+ * The spread light times the skin's colour here, on the second axis; the light as it is on the
+ * first. The colour target holds colour times coverage over coverage, so dividing gives the skin's
+ * own colour at an edge, which the light — weighted for coverage already — is then multiplied by.
+ */
+vec3 withAlbedo(vec3 light) {
+  if (uApplyAlbedo < 0.5) return light;
+  vec4 albedo = textureLod(uAlbedo, vUv, 0.0);
+  return light * albedo.rgb / max(albedo.a, 1e-4);
+}
+
 void main() {
   vec4 own = textureLod(uSkin, vUv, 0.0);
   /*
@@ -61,7 +83,7 @@ void main() {
   }
   float depth = textureLod(uDepth, vUv, 0.0).r;
   if (${glslIsFarDepth('depth')}) {
-    fragColor = own;
+    fragColor = vec4(withAlbedo(own.rgb), own.a);
     return;
   }
   /* A part-covered pixel's code is its share of the whole: read it as the nearest, which is the
@@ -73,7 +95,7 @@ void main() {
   /* The widest distance in pixels here: under half of one, there is nothing to spread across. */
   float pixels = widest * uFocal / max(z, 1e-4);
   if (pixels < 0.5) {
-    fragColor = own;
+    fragColor = vec4(withAlbedo(own.rgb), own.a);
     return;
   }
   vec3 centre = 2.0 * burleyMass(EDGES[0] * widest, d);
@@ -98,6 +120,6 @@ void main() {
       weight += w * (cover * keep);
     }
   }
-  fragColor = vec4(sum / weight, own.a);
+  fragColor = vec4(withAlbedo(sum / weight), own.a);
 }
 `;

package/dist/render/skinBlur.d.ts

@@ -3,11 +3,14 @@
  * the kernel to, and nothing at run time calls it.
  *
  * **What it spreads.** With `skinScattering: 'screen-space'`, a skin draw writes its specular to the
- * frame and its diffuse — the light that went beneath the surface — to a target of its own, with the
- * profile it scatters by in the alpha. Before anything blended is drawn, that target is blurred
- * along the screen's two axes by Burley's normalised diffusion, one width per channel, and added
- * back: light that entered a cheek leaves it a centimetre away, reddest furthest, across the
- * pixels that centimetre covers at the cheek's distance. The pre-integrated fit stays in the lit
+ * frame, the light its diffuse is made of — the light that went beneath the surface, shaded on a
+ * white surface — to a target of its own with the profile it scatters by in the alpha, and its
+ * colour to a third. Before anything blended is drawn, the light is blurred along the screen's two
+ * axes by Burley's normalised diffusion, one width per channel, multiplied by the colour at each
+ * pixel and added back: light that entered a cheek leaves it a centimetre away, reddest furthest,
+ * across the pixels that centimetre covers at the cheek's distance, and a brow stays where it is
+ * drawn. **Until 4.8.6 the coloured diffuse was spread**, which smeared every mark on a face into
+ * the skin around it and laid faint copies of each mark at the taps' offsets. The pre-integrated fit stays in the lit
  * stage for what this cannot see — a terminator's curvature — and this carries what that cannot:
  * light crossing a shadow's edge, or a nostril's rim, in the picture rather than in a fit.
  *

package/dist/render/skinBlur.js

@@ -3,11 +3,14 @@
  * the kernel to, and nothing at run time calls it.
  *
  * **What it spreads.** With `skinScattering: 'screen-space'`, a skin draw writes its specular to the
- * frame and its diffuse — the light that went beneath the surface — to a target of its own, with the
- * profile it scatters by in the alpha. Before anything blended is drawn, that target is blurred
- * along the screen's two axes by Burley's normalised diffusion, one width per channel, and added
- * back: light that entered a cheek leaves it a centimetre away, reddest furthest, across the
- * pixels that centimetre covers at the cheek's distance. The pre-integrated fit stays in the lit
+ * frame, the light its diffuse is made of — the light that went beneath the surface, shaded on a
+ * white surface — to a target of its own with the profile it scatters by in the alpha, and its
+ * colour to a third. Before anything blended is drawn, the light is blurred along the screen's two
+ * axes by Burley's normalised diffusion, one width per channel, multiplied by the colour at each
+ * pixel and added back: light that entered a cheek leaves it a centimetre away, reddest furthest,
+ * across the pixels that centimetre covers at the cheek's distance, and a brow stays where it is
+ * drawn. **Until 4.8.6 the coloured diffuse was spread**, which smeared every mark on a face into
+ * the skin around it and laid faint copies of each mark at the taps' offsets. The pre-integrated fit stays in the lit
  * stage for what this cannot see — a terminator's curvature — and this carries what that cannot:
  * light crossing a shadow's edge, or a nostril's rim, in the picture rather than in a fit.
  *

package/dist/render/surfaceModel.d.ts

@@ -18,6 +18,7 @@
  * the draw's model matrix and the eye's joint each draw, with `eyeAxisInWorld`.
  */
 import type { Vec3 } from '../math/color.ts';
+import type { LightmapRegion } from './lightmap.ts';
 /** Strands of brushed metal, satin or hair-like fibre: a highlight stretched across them. */
 export interface AnisotropicModel {
     readonly kind: 'anisotropic';
@@ -72,8 +73,18 @@ export interface EyeModel {
     /** The joint the eye turns with, or -1 for an eye placed by its model matrix alone. */
     readonly joint: number;
 }
+/**
+ * A surface whose static light was baked: the standard model, plus a lightmap page's light read at
+ * the mesh's second coordinates (`MeshData.lightmapUvs`). The material's `modelMap` is the page,
+ * from `createLightmap`; see `lightmap.ts` for what it adds and what it gives up.
+ */
+export interface LightmapModel {
+    readonly kind: 'lightmap';
+    /** Where this material's surfaces are on the page: `uv2 * scale + bias`. See `LightmapRegion`. */
+    readonly region: LightmapRegion;
+}
 /** Every model a material can name, by its `kind`: see `SurfaceMaterial.model`. */
-export type SurfaceModel = AnisotropicModel | HairModel | SkinModel | EyeModel;
+export type SurfaceModel = AnisotropicModel | HairModel | SkinModel | EyeModel | LightmapModel;
 /** A model's name, which also picks its pipeline switch: `SURFACE_MODEL_SWITCH`. */
 export type SurfaceModelKind = SurfaceModel['kind'];
 /** Every kind, in the order the lit stage declares their switches. */
@@ -109,6 +120,14 @@ export declare function eyeModel(options?: {
     axis?: Vec3;
     joint?: number;
 }): EyeModel;
+/**
+ * A baked surface, reading its region of a lightmap page: the whole page where none is named. An
+ * instanced batch's regions compose with this one, each instance's applied first: see
+ * `MeshInstances.lightmapRegions`.
+ */
+export declare function lightmapModel(options?: {
+    region?: LightmapRegion;
+}): LightmapModel;
 /**
  * A model's numbers into `out` — eight floats, `uModelParams[0]` then `[1]` — and whether a model
  * map is bound into the last. Zeros for the standard model. An eye's axis goes in with the
@@ -118,6 +137,7 @@ export declare function eyeModel(options?: {
  * - hair: shift, scatter, backlit, − · −, −, −, map
  * - skin: the scatter colour, radius · transmission, profile, −, map
  * - eye: iris radius, iris depth, ior, cornea roughness · the axis, map
+ * - lightmap: the region's scale and bias · −, −, −, map
  */
 export declare function packModel(model: SurfaceModel | null, mapped: boolean, out: Float32Array): void;
 /**

package/dist/render/surfaceModel.js

@@ -1,9 +1,11 @@
+import { lightmapRegionOf } from './lightmap.js';
 /** Every kind, in the order the lit stage declares their switches. */
 export const SURFACE_MODEL_KINDS = [
     'anisotropic',
     'hair',
     'skin',
     'eye',
+    'lightmap',
 ];
 /** The lit stage's switch for each kind. */
 export const SURFACE_MODEL_SWITCH = {
@@ -11,6 +13,7 @@ export const SURFACE_MODEL_SWITCH = {
     hair: 'MODEL_HAIR',
     skin: 'MODEL_SKIN',
     eye: 'MODEL_EYE',
+    lightmap: 'MODEL_LIGHTMAP',
 };
 /** Floats a material's model takes: `uModelParams[2]`. */
 export const MODEL_PARAM_FLOATS = 8;
@@ -75,6 +78,18 @@ export function eyeModel(options = {}) {
         joint,
     });
 }
+/**
+ * A baked surface, reading its region of a lightmap page: the whole page where none is named. An
+ * instanced batch's regions compose with this one, each instance's applied first: see
+ * `MeshInstances.lightmapRegions`.
+ */
+export function lightmapModel(options = {}) {
+    const region = lightmapRegionOf(options.region);
+    return Object.freeze({
+        kind: 'lightmap',
+        region: Object.freeze([region[0], region[1], region[2], region[3]]),
+    });
+}
 /**
  * A model's numbers into `out` — eight floats, `uModelParams[0]` then `[1]` — and whether a model
  * map is bound into the last. Zeros for the standard model. An eye's axis goes in with the
@@ -84,6 +99,7 @@ export function eyeModel(options = {}) {
  * - hair: shift, scatter, backlit, − · −, −, −, map
  * - skin: the scatter colour, radius · transmission, profile, −, map
  * - eye: iris radius, iris depth, ior, cornea roughness · the axis, map
+ * - lightmap: the region's scale and bias · −, −, −, map
  */
 export function packModel(model, mapped, out) {
     out.fill(0);
@@ -118,6 +134,12 @@ export function packModel(model, mapped, out) {
             out[5] = model.axis[1];
             out[6] = model.axis[2];
             return;
+        case 'lightmap':
+            out[0] = model.region[0];
+            out[1] = model.region[1];
+            out[2] = model.region[2];
+            out[3] = model.region[3];
+            return;
     }
 }
 /**

package/dist/render/surfaceTexture.d.ts

@@ -12,6 +12,7 @@ import type { SurfaceModel } from './surfaceModel.ts';
 import type { CompressedTextureFormat, SurfaceSource } from './compressedSource.ts';
 import type { SurfaceLayerEffect } from './surfaceEffects.ts';
 import type { CutoutMode } from './cutoutDither.ts';
+import type { LightmapTexels } from './lightmap.ts';
 /**
  * How a texture behaves past its edges and between its texels.
  *
@@ -100,6 +101,18 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
      * without culling, and a back face is lit as its front, with the normal turned to the viewer.
      */
     doubleSided?: boolean;
+    /**
+     * The lighting channels this surface takes light from, a mask: 1, 2, 3 … 255. **1 by default**,
+     * which is every light's default too, so a scene that names no channel is lit as it always was.
+     *
+     * A point or spot light shades this surface only where its `PointLightSet.lightChannels` and this
+     * share a bit — Unreal's lighting channels. A character's own key and rim lights on channel 2,
+     * and the character's materials on 3, light the character and leave the floor around it as the
+     * stage's lights alone have it. **What it does not reach**: the sun, the sky and the probes, area
+     * lights, DriftLight's volume and the GPU-driven pipeline light every surface whatever its mask.
+     * A number that is not a whole mask from 1 to 255 is channel 1.
+     */
+    lightChannels?: number;
     /**
      * How hard the normal map turns the shading normal.
      *
@@ -249,7 +262,7 @@ export declare class SurfaceTexture {
      * Uploaded unflipped either way; see the constructor body for why. Or blocks, uploaded as they are
      * where `compressed` — the formats this context samples — has theirs; see `compressedSource.ts`.
      */
-    constructor(gl: WebGL2RenderingContext, source: SurfaceSource | readonly SurfaceSource[], options?: SurfaceTextureOptions, compressed?: readonly CompressedTextureFormat[]);
+    constructor(gl: WebGL2RenderingContext, source: SurfaceSource | readonly SurfaceSource[] | LightmapTexels, options?: SurfaceTextureOptions, compressed?: readonly CompressedTextureFormat[]);
     /** Whether this texture carries an effects table, which the lit program reads only once one exists. */
     get hasEffects(): boolean;
     bindEffects(gl: WebGL2RenderingContext, unit: number, fallback: WebGLTexture): void;