babylon.quarks 0.26.0 → 0.28.0

package/src/shaderVariants.ts

@@ -0,0 +1,245 @@
+import {Constants} from '@babylonjs/core/Engines/constants';
+import type {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
+import {Vector3} from 'quarks.core';
+import {ShaderContext, shaderProgram, ShaderProgram, ShaderSettings} from './shaderProgram';
+import {
+    normalizeErosion,
+    normalizeGradientMap,
+    normalizeMapUV,
+    normalizeMeshRim,
+    normalizeUVDistortion,
+    RenderMode,
+} from './VFXBatch';
+
+/**
+ * One shader the library can compile: a {@link ShaderProgram} with the settings that produce it,
+ * named for the renderer's benefit. See {@link shaderVariants}.
+ */
+export interface ShaderVariant {
+    /** The render mode and the features compiled in, for a report. */
+    name: string;
+    /** The program a batch with these settings builds. */
+    program: ShaderProgram;
+}
+
+/** A texture reference for settings that only ask whether one is set; it is never sampled. */
+const TEXTURE = {} as BaseTexture;
+
+/** The settings of a bare batch in `renderMode`: no texture, no effects, fog off, 1×1 sheet. */
+function bare(renderMode: RenderMode): ShaderSettings {
+    return {
+        renderMode,
+        texture: null,
+        reflectionAtlas: null,
+        uTileCount: 1,
+        vTileCount: 1,
+        blendTiles: false,
+        softParticles: false,
+        materialAlphaTest: 0,
+        materialTransparent: true,
+        materialBlendMode: Constants.ALPHA_COMBINE,
+        applyFog: false,
+        pivot: undefined,
+        minParticleSize: 0,
+        maxParticleSize: Infinity,
+        lighting: renderMode === RenderMode.Mesh ? 'fixed' : undefined,
+        rim: undefined,
+        mapUV: undefined,
+        uvDistortion: undefined,
+        gradientMap: undefined,
+        erosion: undefined,
+    };
+}
+
+/** A settings change with the name it adds to the variant. */
+interface Axis {
+    name: string;
+    settings?: Partial<ShaderSettings>;
+    context?: Partial<ShaderContext>;
+}
+
+const NONE: Axis = {name: ''};
+
+/** The render modes and the mode-specific features: quad pivot and size limits, mesh lighting, rim and reflection. */
+const TARGETS: Axis[] = [
+    {name: 'billboard', settings: {renderMode: RenderMode.BillBoard}},
+    {name: 'vertical billboard', settings: {renderMode: RenderMode.VerticalBillBoard}},
+    {name: 'horizontal billboard', settings: {renderMode: RenderMode.HorizontalBillBoard}},
+    {name: 'stretched', settings: {renderMode: RenderMode.StretchedBillBoard}},
+    {name: 'beam', settings: {renderMode: RenderMode.Beam}},
+    {name: 'mesh', settings: {renderMode: RenderMode.Mesh}},
+    {name: 'mesh scene lit', settings: {renderMode: RenderMode.Mesh, lighting: 'scene'}},
+    {name: 'mesh unlit', settings: {renderMode: RenderMode.Mesh, lighting: 'unlit'}},
+    {name: 'mesh rim', settings: {renderMode: RenderMode.Mesh, rim: normalizeMeshRim({mode: 'add'})}},
+    {
+        name: 'mesh unlit rim mix',
+        settings: {renderMode: RenderMode.Mesh, lighting: 'unlit', rim: normalizeMeshRim({mode: 'mix'})},
+    },
+    {
+        name: 'mesh unlit rim fade',
+        settings: {renderMode: RenderMode.Mesh, lighting: 'unlit', rim: normalizeMeshRim({mode: 'fade'})},
+    },
+    {
+        name: 'mesh reflecting',
+        settings: {renderMode: RenderMode.Mesh, reflectionAtlas: TEXTURE},
+        context: {envAtlasReady: true},
+    },
+    {
+        name: 'mesh unlit reflecting rim fade',
+        settings: {
+            renderMode: RenderMode.Mesh,
+            lighting: 'unlit',
+            reflectionAtlas: TEXTURE,
+            rim: normalizeMeshRim({mode: 'fade'}),
+        },
+        context: {envAtlasReady: true},
+    },
+    {name: 'trail', settings: {renderMode: RenderMode.Trail}},
+];
+
+/** Pivot and screen-size limits, which only the quad modes read. */
+const QUAD: Axis[] = [
+    NONE,
+    {name: 'pivot', settings: {pivot: new Vector3(0.5, 0, 0)}},
+    {name: 'size limits', settings: {minParticleSize: 0.01}},
+    {name: 'pivot size limits', settings: {pivot: new Vector3(0, 0.5, 0.5), maxParticleSize: 0.5}},
+];
+
+const TILE: Axis[] = [
+    NONE,
+    {name: 'sheet', settings: {uTileCount: 4, vTileCount: 2}},
+    {name: 'sheet blend', settings: {uTileCount: 4, vTileCount: 2, blendTiles: true}},
+];
+const MAP: Axis[] = [NONE, {name: 'map', settings: {texture: TEXTURE}}];
+const SOFT: Axis[] = [
+    NONE,
+    {name: 'soft', settings: {softParticles: true}, context: {depth: {packed: false}}},
+    {name: 'soft packed', settings: {softParticles: true}, context: {depth: {packed: true}}},
+];
+const ALPHA_TEST: Axis[] = [NONE, {name: 'alpha test', settings: {materialAlphaTest: 0.5}}];
+const FOG: Axis[] = [
+    NONE,
+    {name: 'fog', settings: {applyFog: true}},
+    {name: 'fog additive', settings: {applyFog: true, materialBlendMode: Constants.ALPHA_ADD}},
+];
+
+/** The blend resolves (see `blendCategory`), with and without the fog each one takes. */
+const BLEND: Axis[] = [
+    {name: 'premultiplied', settings: {materialBlendMode: Constants.ALPHA_PREMULTIPLIED}},
+    {name: 'premultiplied fog', settings: {materialBlendMode: Constants.ALPHA_PREMULTIPLIED, applyFog: true}},
+    {name: 'one-one', settings: {materialBlendMode: Constants.ALPHA_ONEONE}},
+    {name: 'one-one fog', settings: {materialBlendMode: Constants.ALPHA_ONEONE, applyFog: true}},
+    {name: 'multiply', settings: {materialBlendMode: Constants.ALPHA_MULTIPLY}},
+    {name: 'multiply fog', settings: {materialBlendMode: Constants.ALPHA_MULTIPLY, applyFog: true}},
+    {
+        name: 'multiply fog alpha test',
+        settings: {materialBlendMode: Constants.ALPHA_MULTIPLY, applyFog: true, materialAlphaTest: 0.5},
+    },
+    {name: 'opaque', settings: {materialTransparent: false}},
+];
+
+/** Texture effects (`chunks/surface.ts`), alone and together, on both UV channels. */
+const SURFACE: Axis[] = (() => {
+    const uv0 = normalizeMapUV({tiling: [2, 2]});
+    const uv1 = normalizeMapUV({channel: 1, tiling: [2, 2]});
+    const distortion0 = normalizeUVDistortion({map: TEXTURE});
+    const distortion1 = normalizeUVDistortion({map: TEXTURE, mapUV: {channel: 1}});
+    const gradient = normalizeGradientMap({ramp: TEXTURE});
+    const erosion = normalizeErosion({});
+    const erosionMask0 = normalizeErosion({mask: TEXTURE});
+    const erosionMask1 = normalizeErosion({mask: TEXTURE, maskUV: {channel: 1}});
+    return [
+        {name: 'map transform', settings: {mapUV: uv0}},
+        {name: 'map transform uv1', settings: {mapUV: uv1}},
+        {name: 'gradient map', settings: {gradientMap: gradient}},
+        {name: 'erosion', settings: {erosion}},
+        {name: 'erosion mask', settings: {erosion: erosionMask0}},
+        {name: 'erosion mask uv1', settings: {erosion: erosionMask1}},
+        {name: 'distortion', settings: {uvDistortion: distortion0}},
+        {name: 'distortion uv1', settings: {uvDistortion: distortion1}},
+        {
+            name: 'map transform distortion gradient erosion mask',
+            settings: {mapUV: uv0, uvDistortion: distortion0, gradientMap: gradient, erosion: erosionMask0},
+        },
+        {
+            name: 'map transform uv1 distortion gradient erosion',
+            settings: {mapUV: uv1, uvDistortion: distortion0, gradientMap: gradient, erosion},
+        },
+        {
+            name: 'every effect on uv1',
+            settings: {mapUV: uv1, uvDistortion: distortion1, gradientMap: gradient, erosion: erosionMask1},
+        },
+    ];
+})();
+
+/** The targets the texture effects are tried on: one per vertex shader and fragment family. */
+const SURFACE_TARGETS = [
+    'billboard',
+    'stretched',
+    'beam',
+    'mesh',
+    'mesh unlit',
+    'mesh unlit rim mix',
+    'mesh reflecting',
+    'trail',
+];
+
+/** A mesh batch whose geometry has a second UV set. */
+const MESH_UV2: Axis = {name: 'uv2', context: {meshUV2: true}};
+
+/** Soft, alpha-tested and fogged at once, to try the effects with the rest of the fragment. */
+const EVERYTHING_ELSE: Axis = {
+    name: 'soft packed alpha test fog one-one',
+    settings: {softParticles: true, materialAlphaTest: 0.5, applyFog: true, materialBlendMode: Constants.ALPHA_ONEONE},
+    context: {depth: {packed: true}},
+};
+
+/**
+ * Every shader program the library can compile, one per distinct set of defines: every render
+ * mode with every combination of sheet, map, soft particles, alpha test and fog, every blend
+ * resolve with and without fog and soft particles, and the texture effects alone and together on
+ * each shader family. What a shader validator compiles, and what
+ * an application can warm the shader cache with before its first frame (Unity's
+ * ShaderVariantCollection). Built by {@link shaderProgram}, so a variant here is a material a
+ * batch would build.
+ */
+export function shaderVariants(): ShaderVariant[] {
+    const seen = new Set<string>();
+    const out: ShaderVariant[] = [];
+    const add = (axes: Axis[]) => {
+        const settings = bare(RenderMode.BillBoard);
+        const context: ShaderContext = {depth: null, envAtlasReady: false, meshUV2: false};
+        for (const axis of axes) {
+            Object.assign(settings, axis.settings);
+            Object.assign(context, axis.context);
+        }
+        const program = shaderProgram(settings, context);
+        const key = program.name + ' ' + program.defines.join(',');
+        if (seen.has(key)) {
+            return;
+        }
+        seen.add(key);
+        const features = axes.map((axis) => axis.name).filter((name) => name !== '');
+        out.push({name: `${features.join(', ')} [${program.defines.join(',') || 'none'}]`, program});
+    };
+
+    for (const target of TARGETS)
+        for (const quad of QUAD)
+            for (const tile of TILE)
+                for (const map of MAP)
+                    for (const soft of SOFT)
+                        for (const alphaTest of ALPHA_TEST)
+                            for (const fog of FOG) add([target, quad, tile, map, soft, alphaTest, fog]);
+
+    for (const target of TARGETS)
+        for (const blend of BLEND)
+            for (const soft of SOFT.slice(0, 2)) for (const map of MAP) add([target, blend, soft, map]);
+
+    for (const target of TARGETS.filter((t) => SURFACE_TARGETS.includes(t.name)))
+        for (const uv2 of target.settings?.renderMode === RenderMode.Mesh ? [NONE, MESH_UV2] : [NONE])
+            for (const surface of SURFACE)
+                for (const map of MAP)
+                    for (const tile of [NONE, TILE[2]])
+                        for (const rest of [NONE, EVERYTHING_ELSE]) add([target, uv2, surface, map, tile, rest]);
+    return out;
+}

package/src/shaders/chunks/blend.ts

@@ -0,0 +1,31 @@
+/**
+ * The blend resolve for the particle shaders, in both shader languages.
+ *
+ * Every fade in the shaders (soft particles, erosion, a rim fade, alpha over life) lowers alpha
+ * only, so that alpha means coverage. Blend modes that take the colour at full weight
+ * (`BLEND_PREMULTIPLY`: one-one, premultiplied, screen, subtract, …) would ignore it, so the
+ * resolve multiplies the colour by its alpha; modes that multiply the frame (`BLEND_MULTIPLY`)
+ * move it toward white instead. It runs last, after fog and the soft fade. See `blendCategory`.
+ */
+
+/** Resolves the vec4 lvalue `color` for the blend mode, GLSL. */
+export function blendFragmentGLSL(color: string): string {
+    return /* glsl */ `
+#if defined(BLEND_PREMULTIPLY)
+    ${color}.rgb *= ${color}.a;
+#elif defined(BLEND_MULTIPLY)
+    ${color}.rgb = mix(vec3(1.0), ${color}.rgb, ${color}.a);
+#endif
+`;
+}
+
+/** Resolves the `var` vec4 `color` for the blend mode, WGSL. */
+export function blendFragmentWGSL(color: string): string {
+    return /* wgsl */ `
+#if defined(BLEND_PREMULTIPLY)
+    ${color} = vec4f(${color}.rgb * ${color}.a, ${color}.a);
+#elif defined(BLEND_MULTIPLY)
+    ${color} = vec4f(mix(vec3f(1.0), ${color}.rgb, ${color}.a), ${color}.a);
+#endif
+`;
+}

package/src/shaders/chunks/fog.ts

@@ -11,7 +11,8 @@
  *
  * Additive particles cannot fade toward a fog colour (that would add fog to
  * the whole screen), so under `FOG_ADDITIVE` they fade toward black instead,
- * which is what Unity does for additive materials.
+ * and multiplying particles (`FOG_MULTIPLY`) toward white, which leaves the
+ * frame as it is: what Unity does for additive and multiply materials.
  */
 
 /** Vertex-side declaration, GLSL. */
@@ -44,7 +45,8 @@ float quarksFogFactor() {
     float fogDensity = vFogInfos.w;
     float fogDistance = length(vFogDistance);
     if (vFogInfos.x == 3.0) {
-        fogCoeff = (fogEnd - fogDistance) / (fogEnd - fogStart);
+        // A zero-width band is a cut at its distance, not a division by zero.
+        fogCoeff = (fogEnd - fogDistance) / max(fogEnd - fogStart, 1e-6);
     } else if (vFogInfos.x == 1.0) {
         fogCoeff = exp(-fogDistance * fogDensity);
     } else if (vFogInfos.x == 2.0) {
@@ -61,8 +63,10 @@ export function fogFragmentGLSL(rgb: string): string {
 #ifdef FOG
     {
         float fogFactor = quarksFogFactor();
-#ifdef FOG_ADDITIVE
+#if defined(FOG_ADDITIVE)
         ${rgb} *= fogFactor;
+#elif defined(FOG_MULTIPLY)
+        ${rgb} = mix(vec3(1.0), ${rgb}, fogFactor);
 #else
         ${rgb} = mix(vFogColor, ${rgb}, fogFactor);
 #endif
@@ -101,15 +105,18 @@ fn quarksFog(rgb: vec3f, fogDistanceVector: vec3f) -> vec3f {
     let fogDensity = uniforms.vFogInfos.w;
     let fogDistance = length(fogDistanceVector);
     if (uniforms.vFogInfos.x == 3.0) {
-        fogCoeff = (fogEnd - fogDistance) / (fogEnd - fogStart);
+        // A zero-width band is a cut at its distance, not a division by zero.
+        fogCoeff = (fogEnd - fogDistance) / max(fogEnd - fogStart, 1e-6);
     } else if (uniforms.vFogInfos.x == 1.0) {
         fogCoeff = exp(-fogDistance * fogDensity);
     } else if (uniforms.vFogInfos.x == 2.0) {
         fogCoeff = exp(-fogDistance * fogDistance * fogDensity * fogDensity);
     }
     let fogFactor = clamp(fogCoeff, 0.0, 1.0);
-#ifdef FOG_ADDITIVE
+#if defined(FOG_ADDITIVE)
     return rgb * fogFactor;
+#elif defined(FOG_MULTIPLY)
+    return mix(vec3f(1.0), rgb, fogFactor);
 #else
     return mix(uniforms.vFogColor, rgb, fogFactor);
 #endif

package/src/shaders/chunks/sheet.ts

@@ -0,0 +1,111 @@
+/**
+ * The flipbook (sprite sheet) cell for the sprite, stretched and mesh vertex
+ * shaders, in both shader languages: Unity's Texture Sheet Animation, Unreal's
+ * SubUV.
+ *
+ * `uvTile` is the particle's frame, counted along the rows from the top-left
+ * cell; `tileCountX` and `tileCountY` are the sheet's columns and rows. The
+ * frame is wrapped into the sheet, so a frame past the last cell starts over
+ * and a negative one counts back from the end, in both languages alike (the
+ * WGSL `%` truncates where GLSL's `mod` floors, so the wrap is spelled out).
+ * Under `TILE_BLEND` the next frame, wrapped the same way, is passed with the
+ * fraction between the two, for the fragment to cross-fade (Unity's flipbook
+ * blending).
+ */
+
+/**
+ * The cell of `frame` on a sheet of `columns` × `rows`, counted along the rows
+ * from the top-left cell and wrapped into the sheet, as the shaders count it.
+ * For a host that lays its cells out on the CPU, such as the trail.
+ */
+export function sheetCell(frame: number, columns: number, rows: number): {column: number; row: number} {
+    const total = columns * rows;
+    const tile = wrap(Math.floor(frame), total);
+    return {column: wrap(tile, columns), row: Math.floor(tile / columns)};
+}
+
+/** A floored modulo, as GLSL's `mod`: never negative for a positive divisor. */
+function wrap(value: number, divisor: number): number {
+    return value - divisor * Math.floor(value / divisor);
+}
+
+/** Vertex-side declarations, GLSL: the sheet's size and the cell varyings. */
+export const sheetVertexDeclarationGLSL = /* glsl */ `
+#ifdef UV_TILE
+uniform float tileCountX;
+uniform float tileCountY;
+#endif
+#ifdef TILE_BLEND
+varying vec2 vUV2;
+varying float vTileBlend;
+#endif
+`;
+
+/**
+ * Writes `vUV` (and the blend varyings) from the quad UV expression `uv` and the
+ * frame `uvTile`, GLSL.
+ */
+export function sheetVertexGLSL(uv: string): string {
+    return /* glsl */ `
+#ifdef UV_TILE
+    {
+        vec2 tc = vec2(tileCountX, tileCountY);
+        float tileTotal = tc.x * tc.y;
+        float baseTile = mod(floor(uvTile), tileTotal);
+        vec2 tileUV = vec2(mod(baseTile, tc.x), tc.y - 1.0 - floor(baseTile / tc.x)) / tc;
+        vUV = ${uv} / tc + tileUV;
+#ifdef TILE_BLEND
+        float nextTile = mod(baseTile + 1.0, tileTotal);
+        vec2 nextUV = vec2(mod(nextTile, tc.x), tc.y - 1.0 - floor(nextTile / tc.x)) / tc;
+        vUV2 = ${uv} / tc + nextUV;
+        vTileBlend = fract(uvTile);
+#endif
+    }
+#else
+    vUV = ${uv};
+#endif
+`;
+}
+
+/** Vertex-side declarations, WGSL: the sheet's size and the cell varyings. */
+export const sheetVertexDeclarationWGSL = /* wgsl */ `
+#ifdef UV_TILE
+uniform tileCountX: f32;
+uniform tileCountY: f32;
+
+// A floored modulo, as GLSL's mod: never negative for a positive divisor.
+fn quarksWrap(value: f32, divisor: f32) -> f32 {
+    return value - divisor * floor(value / divisor);
+}
+#endif
+#ifdef TILE_BLEND
+varying vUV2: vec2f;
+varying vTileBlend: f32;
+#endif
+`;
+
+/**
+ * Writes `vertexOutputs.vUV` (and the blend varyings) from the quad UV
+ * expression `uv` and the frame `vertexInputs.uvTile`, WGSL.
+ */
+export function sheetVertexWGSL(uv: string): string {
+    return /* wgsl */ `
+#ifdef UV_TILE
+    {
+        let tc = vec2f(uniforms.tileCountX, uniforms.tileCountY);
+        let tileTotal = tc.x * tc.y;
+        let baseTile = quarksWrap(floor(vertexInputs.uvTile), tileTotal);
+        let tileUV = vec2f(quarksWrap(baseTile, tc.x), tc.y - 1.0 - floor(baseTile / tc.x)) / tc;
+        vertexOutputs.vUV = ${uv} / tc + tileUV;
+#ifdef TILE_BLEND
+        let nextTile = quarksWrap(baseTile + 1.0, tileTotal);
+        let nextUV = vec2f(quarksWrap(nextTile, tc.x), tc.y - 1.0 - floor(nextTile / tc.x)) / tc;
+        vertexOutputs.vUV2 = ${uv} / tc + nextUV;
+        vertexOutputs.vTileBlend = fract(vertexInputs.uvTile);
+#endif
+    }
+#else
+    vertexOutputs.vUV = ${uv};
+#endif
+`;
+}

package/src/shaders/chunks/soft.ts

@@ -0,0 +1,85 @@
+/**
+ * Soft particles for the particle shaders, in both shader languages.
+ *
+ * The fragment reads the scene depth behind it from `depthTexture`, turns it into view depth with
+ * the coefficients in `projParams` (see `softDepthParams`), and fades out over the distance in
+ * `softParams` as it nears the scene, as Unity's soft particles and Unreal's Depth Fade do. The
+ * fade lowers alpha only and runs after fog and before the blend resolve (`blend.ts`), so it reads
+ * as coverage in every blend mode and both languages produce the same colour.
+ *
+ * `SOFT_DEPTH_PACKED` reads a depth packed into four 8-bit channels, as a Babylon
+ * `DepthRenderer` of type `UNSIGNED_BYTE` writes it.
+ */
+
+/** Fragment-side declaration and depth decode, GLSL. */
+export const softFragmentDeclarationGLSL = /* glsl */ `
+#ifdef SOFT_PARTICLES
+uniform sampler2D depthTexture;
+uniform vec2 softParams;
+uniform vec4 projParams;
+varying vec4 projPosition;
+varying float linearDepth;
+
+float quarksSceneDepth(vec4 texel) {
+#ifdef SOFT_DEPTH_PACKED
+    float d = dot(texel, vec4(1.0 / (255.0 * 255.0 * 255.0), 1.0 / (255.0 * 255.0), 1.0 / 255.0, 1.0));
+#else
+    float d = texel.r;
+#endif
+    float denominator = projParams.z * d + projParams.w;
+    float depth = abs(denominator) > 1e-8 ? abs((projParams.x * d + projParams.y) / denominator) : 0.0;
+    // Nothing drawn there reads as infinitely far.
+    return depth > 0.0 ? depth : 1e30;
+}
+#endif
+`;
+
+/** Fades the alpha of the vec4 lvalue `target` as the fragment nears the scene behind it, GLSL. */
+export function softFragmentGLSL(target: string): string {
+    return /* glsl */ `
+#ifdef SOFT_PARTICLES
+    {
+        vec2 softUV = 0.5 * (projPosition.xy / projPosition.w) + 0.5;
+        float sceneDepth = quarksSceneDepth(texture2D(depthTexture, softUV));
+        ${target}.a *= clamp(softParams.y * ((sceneDepth - softParams.x) - linearDepth), 0.0, 1.0);
+    }
+#endif
+`;
+}
+
+/** Fragment-side declaration and depth decode, WGSL. */
+export const softFragmentDeclarationWGSL = /* wgsl */ `
+#ifdef SOFT_PARTICLES
+var depthTextureSampler: sampler;
+var depthTexture: texture_2d<f32>;
+uniform softParams: vec2f;
+uniform projParams: vec4f;
+varying projPosition: vec4f;
+varying linearDepth: f32;
+
+fn quarksSceneDepth(texel: vec4f) -> f32 {
+#ifdef SOFT_DEPTH_PACKED
+    let d = dot(texel, vec4f(1.0 / (255.0 * 255.0 * 255.0), 1.0 / (255.0 * 255.0), 1.0 / 255.0, 1.0));
+#else
+    let d = texel.r;
+#endif
+    let denominator = uniforms.projParams.z * d + uniforms.projParams.w;
+    let depth = select(0.0, abs((uniforms.projParams.x * d + uniforms.projParams.y) / denominator), abs(denominator) > 1e-8);
+    // Nothing drawn there reads as infinitely far.
+    return select(1e30, depth, depth > 0.0);
+}
+#endif
+`;
+
+/** Fades the alpha of the `var` vec4 `target` as the fragment nears the scene behind it, WGSL. */
+export function softFragmentWGSL(target: string): string {
+    return /* wgsl */ `
+#ifdef SOFT_PARTICLES
+    {
+        let softUV = 0.5 * (fragmentInputs.projPosition.xy / fragmentInputs.projPosition.w) + 0.5;
+        let sceneDepth = quarksSceneDepth(textureSample(depthTexture, depthTextureSampler, softUV));
+        ${target}.a *= clamp(uniforms.softParams.y * ((sceneDepth - uniforms.softParams.x) - fragmentInputs.linearDepth), 0.0, 1.0);
+    }
+#endif
+`;
+}

package/src/shaders/chunks/surface.ts

@@ -35,8 +35,8 @@
  *   on the way down the shape eats away from its lowest mask values first — a
  *   noise mask dissolves it, a gradient mask wipes it. `erosionParams` is
  *   (softness, edge width); the edge band just above the cut glows in
- *   `erosionEdgeColor`. Erosion only changes alpha, so blend modes that
- *   ignore alpha (one-one, premultiplied) show a hard cut.
+ *   `erosionEdgeColor`. Erosion only changes alpha, which the blend resolve
+ *   (`blend.ts`) turns into coverage in every blend mode.
  */
 
 /** Fragment-side declarations, GLSL. */
@@ -108,6 +108,7 @@ export function surfaceColorGLSL(tileBlend: boolean): string {
     baseColor.a = 1.0;
     float erosionMaskValue = 1.0;
 #endif
+#if defined(USE_MAP) || defined(GRADIENT_MAP)
 #ifdef USE_MAP
     vec4 texColor = texture2D(map, mapUV);
     ${
@@ -130,6 +131,10 @@ export function surfaceColorGLSL(tileBlend: boolean): string {
     #endif`
             : ''
     }
+#else
+    // No map: the ramp is looked up at white, its far end.
+    vec4 texColor = vec4(1.0);
+#endif
     #ifdef GRADIENT_MAP
         float rampAt = clamp(dot(texColor, gradientMapChannel), 0.0, 1.0);
         vec4 ramp = texture2D(gradientMap, vec2(mix(gradientMapRange.x, gradientMapRange.y, rampAt), 0.5));
@@ -221,6 +226,7 @@ export function surfaceColorWGSL(tileBlend: boolean): string {
     baseColor.a = 1.0;
     var erosionMaskValue = 1.0;
 #endif
+#if defined(USE_MAP) || defined(GRADIENT_MAP)
 #ifdef USE_MAP
     var texColor = textureSample(map, mapSampler, mapUV);
     ${
@@ -243,6 +249,10 @@ export function surfaceColorWGSL(tileBlend: boolean): string {
     #endif`
             : ''
     }
+#else
+    // No map: the ramp is looked up at white, its far end.
+    var texColor = vec4f(1.0);
+#endif
     #ifdef GRADIENT_MAP
         let rampAt = clamp(dot(texColor, uniforms.gradientMapChannel), 0.0, 1.0);
         let ramp = textureSample(gradientMap, gradientMapSampler, vec2f(mix(uniforms.gradientMapRange.x, uniforms.gradientMapRange.y, rampAt), 0.5));

package/src/shaders/local_particle_physics_vert.glsl.ts

@@ -1,4 +1,5 @@
 import {fogVertexDeclarationGLSL, fogVertexGLSL} from './chunks/fog';
+import {sheetVertexDeclarationGLSL, sheetVertexGLSL} from './chunks/sheet';
 
 export default /* glsl */ `
 attribute vec3 position;
@@ -13,11 +14,7 @@ attribute float uvTile;
 uniform mat4 world;
 uniform mat4 view;
 uniform mat4 projection;
-
-#ifdef UV_TILE
-uniform float tileCountX;
-uniform float tileCountY;
-#endif
+${sheetVertexDeclarationGLSL}
 
 varying vec2 vUV;
 varying vec4 vColor;
@@ -32,11 +29,6 @@ varying vec2 vUV1;
 varying vec3 vNormal;
 varying vec3 vWorldPos;
 
-#ifdef TILE_BLEND
-varying vec2 vUV2;
-varying float vTileBlend;
-#endif
-
 #ifdef SOFT_PARTICLES
 varying vec4 projPosition;
 varying float linearDepth;
@@ -53,7 +45,15 @@ ${fogVertexDeclarationGLSL}
 void main() {
     vec3 scaledPosition = position * size;
     vec3 rotatedPosition = applyQuaternion(scaledPosition, rotation);
-    vec3 rotatedNormal = normalize(applyQuaternion(normal, rotation));
+    // A normal scales by the inverse of the size, so a stretched mesh keeps its normals
+    // perpendicular; a flat size counts as a sliver rather than dividing by zero.
+    vec3 safeSize = vec3(
+        abs(size.x) > 1e-6 ? size.x : 1e-6,
+        abs(size.y) > 1e-6 ? size.y : 1e-6,
+        abs(size.z) > 1e-6 ? size.z : 1e-6);
+    // A mirrored size (an odd number of negative components) turns the winding inside out, so the
+    // normal is turned with it and the fragment's front-face test agrees with the geometry.
+    vec3 rotatedNormal = normalize(applyQuaternion(normal / safeSize, rotation)) * sign(safeSize.x * safeSize.y * safeSize.z);
     vec3 localPos = rotatedPosition + offset;
 
     vec4 worldPos = world * vec4(localPos, 1.0);
@@ -66,25 +66,11 @@ ${fogVertexGLSL('viewPos.xyz')}
 
 #ifdef SOFT_PARTICLES
     projPosition = gl_Position;
-    linearDepth = -viewPos.z;
+    // View depth is +z ahead of a left-handed camera and -z ahead of a right-handed one.
+    linearDepth = abs(viewPos.z);
 #endif
 
-#ifdef UV_TILE
-    vec2 tc = vec2(tileCountX, tileCountY);
-    float baseTile = floor(uvTile);
-    float tileU = mod(baseTile, tc.x) / tc.x;
-    float tileV = 1.0 - floor(baseTile / tc.x) / tc.y - 1.0 / tc.y;
-    vUV = uv / tc + vec2(tileU, tileV);
-    #ifdef TILE_BLEND
-        float nextTile = ceil(uvTile);
-        float nextU = mod(nextTile, tc.x) / tc.x;
-        float nextV = 1.0 - floor(nextTile / tc.x) / tc.y - 1.0 / tc.y;
-        vUV2 = uv / tc + vec2(nextU, nextV);
-        vTileBlend = fract(uvTile);
-    #endif
-#else
-    vUV = uv;
-#endif
+${sheetVertexGLSL('uv')}
 
 #ifdef UV1
 #ifdef MESH_UV2