@vgai/engine 0.5.13 → 0.5.14

package/dist/render/particles-factory.js

@@ -2,13 +2,16 @@
 /**
  * Converts ParticlesDescriptor JSON → three.quarks ParticleSystem.
  *
- * Shared between the editor entity-factory and the runtime scene-loader.
+ * A published engine entry point (the export map is the wildcard `./*`): the
+ * one in-repo caller is the godot-compat capability's `createCpuParticles3D`,
+ * and user games outside this repo reach it directly.
  * The schema mirrors quarks' native JSON format, so most fields pass through
  * directly to quarks' fromJSON or constructor methods.
  */
 import { ApplyForce, ChangeEmitDirection, CircleEmitter, ColorGeneratorFromJSON, ColorOverLife, ConeEmitter, DonutEmitter, ForceOverLife, FrameOverLife, GravityForce, GridEmitter, HemisphereEmitter, LimitSpeedOverLife, Noise, OrbitOverLife, PointEmitter, Vector3 as QVector3, RectangleEmitter, RotationOverLife, SizeOverLife, SpeedOverLife, SphereEmitter, TurbulenceField, ValueGeneratorFromJSON, WidthOverLength, } from 'quarks.core';
 import * as THREE from 'three';
 import { ParticleSystem, RenderMode } from 'three.quarks';
+import { armSoftParticleDepth, disarmSoftParticleDepth } from './soft-particle-depth';
 // --- Render mode mapping ---
 const RENDER_MODE_MAP = {
     billboard: RenderMode.BillBoard,
@@ -20,15 +23,79 @@ const RENDER_MODE_MAP = {
 };
 // --- Texture loader (shared cache) ---
 import { textureLoader } from '../loader';
+const WRAP = {
+    clamp: THREE.ClampToEdgeWrapping,
+    repeat: THREE.RepeatWrapping,
+    mirror: THREE.MirroredRepeatWrapping,
+};
+/** `minFilter` is where the two sampler axes MEET — `filter` chooses linear vs nearest and
+ *  `mipmaps` chooses whether the mip chain is sampled at all — and three spells the four
+ *  combinations as four constants. A table rather than nested conditionals, which read as a
+ *  puzzle. (`magFilter` has no mip half; it is the `filter` axis alone.) */
+const MIN_FILTER = {
+    'linear/mips': THREE.LinearMipmapLinearFilter,
+    'linear/no-mips': THREE.LinearFilter,
+    'nearest/mips': THREE.NearestMipmapNearestFilter,
+    'nearest/no-mips': THREE.NearestFilter,
+};
 const particleTexCache = new Map();
-function loadParticleTexture(url) {
-    const cached = particleTexCache.get(url);
+/**
+ * The sprite texture for a material's `map`, loaded once per URL+sampler.
+ *
+ * Two things are decided here rather than left to three's loader defaults:
+ *
+ *  - **COLOUR SPACE.** `THREE.TextureLoader` leaves `colorSpace` at `NoColorSpace`, which tells
+ *    three the texels are already linear — so an ordinary sRGB PNG sprite is composited
+ *    UNDECODED and every mid-tone comes out far too bright. A `map` is a colour texture by
+ *    definition (three's own `GLTFLoader` states `SRGBColorSpace` on `baseColorTexture` for the
+ *    same reason), so this states sRGB unconditionally. It is not a descriptor field: there is no
+ *    correct second value for this slot. Measured 2026-08-14 against real Godot 3.6/GLES3 — a
+ *    128,128,128 sprite read back 0.5015 there and 0.7373 here, and after this line 0.5019; the
+ *    whole A/B is in `godot-compat/cpu-particles-3d.ts`'s header.
+ *  - **SAMPLER.** `material.mapSampler`, when the descriptor carries one. The cache key includes
+ *    it because two emitters may name ONE image and want different sampling of it — a URL-only
+ *    key would hand the second one the first's configured texture.
+ *
+ * `flipY` is deliberately untouched: the billboard quad this shader draws is built by
+ * `three.quarks` with three's own V-up UVs, so three's `flipY = true` is the consistent half of
+ * that pair.
+ */
+function loadParticleTexture(url, sampler) {
+    const key = sampler === undefined ? url : `${url}\u0000${JSON.stringify(sampler)}`;
+    const cached = particleTexCache.get(key);
     if (cached)
         return cached;
     const tex = textureLoader.load(url);
-    particleTexCache.set(url, tex);
+    tex.colorSpace = THREE.SRGBColorSpace;
+    if (sampler !== undefined)
+        applyMapSampler(tex, sampler);
+    particleTexCache.set(key, tex);
     return tex;
 }
+/** One `mapSampler` onto three's own texture properties. An unstated field is left at three's
+ *  default rather than restated — see {@link loadParticleTexture}. */
+function applyMapSampler(tex, sampler) {
+    if (sampler.wrap !== undefined) {
+        tex.wrapS = WRAP[sampler.wrap];
+        tex.wrapT = WRAP[sampler.wrap];
+    }
+    if (sampler.filter !== undefined || sampler.mipmaps !== undefined) {
+        // An unstated axis takes three's own default, which is linear and mipmapped.
+        const filter = sampler.filter ?? 'linear';
+        const mips = sampler.mipmaps === false ? 'no-mips' : 'mips';
+        if (sampler.filter !== undefined) {
+            tex.magFilter = filter === 'linear' ? THREE.LinearFilter : THREE.NearestFilter;
+        }
+        tex.minFilter = MIN_FILTER[`${filter}/${mips}`];
+    }
+    if (sampler.mipmaps !== undefined)
+        tex.generateMipmaps = sampler.mipmaps;
+    // Anisotropy rides through unclamped: three's own `WebGLTextures` uploads
+    // `Math.min(texture.anisotropy, capabilities.getMaxAnisotropy())`, so the renderer's real
+    // capability is what binds and a second clamp here would have no effect.
+    if (sampler.anisotropy !== undefined)
+        tex.anisotropy = sampler.anisotropy;
+}
 // --- Helpers ---
 /** Strip keys with undefined values so exactOptionalPropertyTypes is satisfied. */
 function defined(obj) {
@@ -116,7 +183,7 @@ function createBehavior(json) {
 function createParticleMaterial(mat) {
     const textures = {};
     if (mat.map)
-        textures['map'] = loadParticleTexture(mat.map);
+        textures['map'] = loadParticleTexture(mat.map, mat.mapSampler);
     const blending = mat.blending === 'normal' ? THREE.NormalBlending : THREE.AdditiveBlending;
     const transparent = mat.transparent !== false;
     const depthWrite = mat.depthWrite ?? false;
@@ -316,15 +383,31 @@ export function scrubParticleSystemTo(system, time, step = 1 / 60) {
 }
 /**
  * Register a particle system with a BatchedRenderer.
+ *
+ * This is also the ONE seat that arms the scene-depth prepass: a system built
+ * with `softParticles` compiles its batch with three.quarks' `SOFT_PARTICLES`
+ * define, which samples a `depthTexture` uniform nothing else in this engine
+ * would ever fill (see `render/soft-particle-depth.ts` for what an unfilled one
+ * does to the frame). Arming here — rather than in
+ * {@link createParticleSystemFromData} — is what makes it correct: the uniform
+ * lives on the BATCH, and no batch exists until a renderer is handed the
+ * system.
  */
 export function registerParticleSystem(batchedRenderer, system) {
     batchedRenderer.addSystem(system);
+    if (system.softParticles)
+        armSoftParticleDepth(batchedRenderer);
 }
 /**
  * Unregister a particle system from a BatchedRenderer.
+ *
+ * Disarms the depth prepass — one decrement against the arming above, so a
+ * renderer hosting several soft systems stays armed until its last one leaves.
  */
 export function unregisterParticleSystem(batchedRenderer, system) {
     batchedRenderer.deleteSystem(system);
+    if (system.softParticles)
+        disarmSoftParticleDepth(batchedRenderer);
 }
 /**
  * Default particle data for creating a new particle emitter via AddSectionMenu.

package/dist/render/soft-particle-depth.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Scene DEPTH for three.quarks' soft particles — the pass that makes
+ * `ParticlesDescriptor.softParticles` a real effect instead of a footgun.
+ *
+ * ## What three.quarks needs, and what it does when nobody supplies it
+ *
+ * A batch built with `softParticles` compiles its fragment stage with
+ * `SOFT_PARTICLES` defined, which brings in these two chunks verbatim
+ * (`three.quarks@0.16.0`, `src/shaders/chunks/soft_pars_fragment.glsl.ts` and
+ * `soft_fragment.glsl.ts`):
+ *
+ * ```glsl
+ *     uniform sampler2D depthTexture;
+ *     uniform vec4 projParams;
+ *     uniform vec2 softParams;
+ *
+ *     varying vec4 projPosition;
+ *     varying float linearDepth;
+ *
+ *     #define SOFT_NEAR_FADE softParams.x
+ *     #define SOFT_INV_FADE_DISTANCE softParams.y
+ *
+ *     #define zNear projParams.x
+ *     #define zFar projParams.y
+ *
+ *     float linearize_depth(float d)
+ *     {
+ *         return (zFar * zNear) / (zFar - d * (zFar - zNear));
+ *     }
+ * ```
+ *
+ * ```glsl
+ *     vec2 p2 = projPosition.xy / projPosition.w;
+ *
+ *     p2 = 0.5 * p2 + 0.5;
+ *
+ *     float readDepth = texture2D(depthTexture, p2.xy).r;
+ *     float viewDepth = linearize_depth(readDepth);
+ *
+ *     float softParticlesFade = saturate(SOFT_INV_FADE_DISTANCE * ((viewDepth - SOFT_NEAR_FADE) - linearDepth));
+ *
+ *     gl_FragColor *= softParticlesFade;
+ * ```
+ *
+ * `depthTexture` is a `new Uniform(null)` until something calls
+ * `BatchedRenderer.setDepthTexture` / `VFXBatch.applyDepthTexture`
+ * (`BatchedRenderer.ts:191-196`, `VFXBatch.ts:93-101`). With it null the sampler
+ * reads black, `readDepth` is `0`, `viewDepth` collapses to `zNear`, and
+ * `softParticlesFade` saturates to `0` — every particle multiplied away. That is
+ * the failure this module exists to make impossible: {@link farDepthTexture} is
+ * bound to every `BatchedRenderer` this engine constructs, so the WORST case is
+ * `readDepth = 1` ⇒ `viewDepth = zFar` ⇒ fade `1`, i.e. pixel-identical to a
+ * batch that never had `SOFT_PARTICLES` at all.
+ *
+ * ## The pass, and what it costs
+ *
+ * The fade needs the depth of the geometry BEHIND the particle, which cannot be
+ * the depth attachment the particle is being drawn into (sampling a texture
+ * attached to the bound framebuffer is a feedback loop). So it is a real
+ * PREPASS: one extra `renderer.render(scene, camera)` into a depth-only target,
+ * with the armed particle renderers and every transparent surface hidden and a
+ * colour-write-disabled override material in place.
+ *
+ * That cost is paid ONLY while something is armed. {@link armSoftParticleDepth}
+ * is called from `particles-factory.ts`'s `registerParticleSystem` when the
+ * system it is registering asked for `softParticles`; with the registry empty
+ * {@link SoftParticleDepthPass.render} returns before it touches the scene, so a
+ * world with no soft particles pays one `Set.size` read per frame and nothing
+ * else. Armed, per frame per camera it costs: one scene traverse (to find the
+ * transparent surfaces to hide), one extra geometry-only scene draw with shadow
+ * updates suppressed, and a drawing-buffer-sized depth target
+ * (`UnsignedIntType` depth + an unread RGBA8 colour attachment ≈ 8
+ * bytes/pixel).
+ *
+ * ## Why TRANSPARENT surfaces are hidden
+ *
+ * Godot's own `DEPTH_TEXTURE` — the one `proximity_fade_enabled` samples — is
+ * the OPAQUE pass's depth: `BaseMaterial3D`'s default `depth_draw_opaque` means
+ * a transparent material contributes no depth. Reproducing that is not
+ * cosmetic; without it the starter kit's coin would fade its stars against the
+ * translucent glow quad sitting in front of them rather than against the floor.
+ *
+ * ## Resource ownership
+ *
+ * - {@link farDepthTexture}'s 1x1 texture is a module singleton, created on
+ *   first use and NEVER disposed: it is bound into every renderer's uniforms as
+ *   the safe default, so there is no moment at which the last user is known.
+ *   One texel, one allocation per process.
+ * - The armed-renderer registry is written by exactly two functions,
+ *   {@link armSoftParticleDepth} / {@link disarmSoftParticleDepth}, whose only
+ *   callers are `registerParticleSystem` / `unregisterParticleSystem`.
+ * - The render target and override material belong to the
+ *   {@link SoftParticleDepthPass} instance and die with its `dispose()`. The
+ *   pass itself is owned by whichever adapter mount created it (the R3F adapter
+ *   and `setup-three-root-adapter`), and that mount's teardown is the one path
+ *   allowed to end it.
+ */
+import * as THREE from 'three';
+import type { BatchedRenderer } from 'three.quarks';
+/**
+ * A 1x1 texture whose red channel is 1.0 — "the depth buffer says nothing is in
+ * front of anything".
+ *
+ * Bound to a `BatchedRenderer` the moment it is constructed, so a batch that
+ * later compiles with `SOFT_PARTICLES` inherits it (`BatchedRenderer.addSystem`
+ * applies `this.depthTexture` to each batch it creates). Feeding
+ * `linearize_depth` a `1.0` yields `(zFar * zNear) / (zFar - (zFar - zNear))`,
+ * which is `zFar`, so the fade term is `saturate(k * (zFar - linearDepth))` — 1
+ * for every fragment in front of the far plane. The fade is INERT rather than
+ * wrong, which is what makes an undriven surface (a design-time preview, a host
+ * with no pass) render exactly as it did before soft particles existed.
+ */
+export declare function farDepthTexture(): THREE.DataTexture;
+/** Record that `renderer` hosts one more soft-particle system, so passes stop skipping it. */
+export declare function armSoftParticleDepth(renderer: BatchedRenderer): void;
+/**
+ * The other half of {@link armSoftParticleDepth}. On the LAST soft system the
+ * renderer is dropped from the registry and handed the inert far-depth default
+ * back, so a batch that outlives its registration never keeps sampling a scene
+ * depth nobody is refreshing.
+ */
+export declare function disarmSoftParticleDepth(renderer: BatchedRenderer): void;
+/** Test/diagnostic read of the registry — how many renderers a pass would consider. */
+export declare function armedSoftParticleRendererCount(): number;
+/** The subset of `THREE.WebGLRenderer` this pass drives, so a host can supply its own. */
+export interface SoftParticleDepthRenderer {
+    getDrawingBufferSize(target: THREE.Vector2): THREE.Vector2;
+    getRenderTarget(): THREE.WebGLRenderTarget | null;
+    setRenderTarget(target: THREE.WebGLRenderTarget | null): void;
+    render(scene: THREE.Object3D, camera: THREE.Camera): void;
+    /** Optional because a stub renderer legitimately has none — see {@link SoftParticleDepthPass}. */
+    readonly shadowMap?: {
+        autoUpdate: boolean;
+        needsUpdate: boolean;
+    };
+}
+export interface SoftParticleDepthPass {
+    /**
+     * Draw scene depth and hand it to every armed renderer under `scene`.
+     *
+     * A no-op — not one draw call, not one traversal — while nothing is armed.
+     * Call it after gameplay has moved the frame's transforms and before the
+     * frame is drawn.
+     */
+    render(renderer: SoftParticleDepthRenderer, scene: THREE.Scene, camera: THREE.Camera): void;
+    dispose(): void;
+}
+export declare function createSoftParticleDepthPass(): SoftParticleDepthPass;
+//# sourceMappingURL=soft-particle-depth.d.ts.map

package/dist/render/soft-particle-depth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"soft-particle-depth.d.ts","sourceRoot":"","sources":["../../src/render/soft-particle-depth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAepD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,IAAI,KAAK,CAAC,WAAW,CAOnD;AAED,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAQvE;AAED,uFAAuF;AACvF,wBAAgB,8BAA8B,IAAI,MAAM,CAEvD;AAED,0FAA0F;AAC1F,MAAM,WAAW,yBAAyB;IACxC,oBAAoB,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC3D,eAAe,IAAI,KAAK,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAClD,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAAC;IAC9D,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC1D,kGAAkG;IAClG,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,UAAU,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC;CACpE;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,EAAE,yBAAyB,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC5F,OAAO,IAAI,IAAI,CAAC;CACjB;AA+CD,wBAAgB,2BAA2B,IAAI,qBAAqB,CA0GnE"}

package/dist/render/soft-particle-depth.js

@@ -0,0 +1,305 @@
+/**
+ * Scene DEPTH for three.quarks' soft particles — the pass that makes
+ * `ParticlesDescriptor.softParticles` a real effect instead of a footgun.
+ *
+ * ## What three.quarks needs, and what it does when nobody supplies it
+ *
+ * A batch built with `softParticles` compiles its fragment stage with
+ * `SOFT_PARTICLES` defined, which brings in these two chunks verbatim
+ * (`three.quarks@0.16.0`, `src/shaders/chunks/soft_pars_fragment.glsl.ts` and
+ * `soft_fragment.glsl.ts`):
+ *
+ * ```glsl
+ *     uniform sampler2D depthTexture;
+ *     uniform vec4 projParams;
+ *     uniform vec2 softParams;
+ *
+ *     varying vec4 projPosition;
+ *     varying float linearDepth;
+ *
+ *     #define SOFT_NEAR_FADE softParams.x
+ *     #define SOFT_INV_FADE_DISTANCE softParams.y
+ *
+ *     #define zNear projParams.x
+ *     #define zFar projParams.y
+ *
+ *     float linearize_depth(float d)
+ *     {
+ *         return (zFar * zNear) / (zFar - d * (zFar - zNear));
+ *     }
+ * ```
+ *
+ * ```glsl
+ *     vec2 p2 = projPosition.xy / projPosition.w;
+ *
+ *     p2 = 0.5 * p2 + 0.5;
+ *
+ *     float readDepth = texture2D(depthTexture, p2.xy).r;
+ *     float viewDepth = linearize_depth(readDepth);
+ *
+ *     float softParticlesFade = saturate(SOFT_INV_FADE_DISTANCE * ((viewDepth - SOFT_NEAR_FADE) - linearDepth));
+ *
+ *     gl_FragColor *= softParticlesFade;
+ * ```
+ *
+ * `depthTexture` is a `new Uniform(null)` until something calls
+ * `BatchedRenderer.setDepthTexture` / `VFXBatch.applyDepthTexture`
+ * (`BatchedRenderer.ts:191-196`, `VFXBatch.ts:93-101`). With it null the sampler
+ * reads black, `readDepth` is `0`, `viewDepth` collapses to `zNear`, and
+ * `softParticlesFade` saturates to `0` — every particle multiplied away. That is
+ * the failure this module exists to make impossible: {@link farDepthTexture} is
+ * bound to every `BatchedRenderer` this engine constructs, so the WORST case is
+ * `readDepth = 1` ⇒ `viewDepth = zFar` ⇒ fade `1`, i.e. pixel-identical to a
+ * batch that never had `SOFT_PARTICLES` at all.
+ *
+ * ## The pass, and what it costs
+ *
+ * The fade needs the depth of the geometry BEHIND the particle, which cannot be
+ * the depth attachment the particle is being drawn into (sampling a texture
+ * attached to the bound framebuffer is a feedback loop). So it is a real
+ * PREPASS: one extra `renderer.render(scene, camera)` into a depth-only target,
+ * with the armed particle renderers and every transparent surface hidden and a
+ * colour-write-disabled override material in place.
+ *
+ * That cost is paid ONLY while something is armed. {@link armSoftParticleDepth}
+ * is called from `particles-factory.ts`'s `registerParticleSystem` when the
+ * system it is registering asked for `softParticles`; with the registry empty
+ * {@link SoftParticleDepthPass.render} returns before it touches the scene, so a
+ * world with no soft particles pays one `Set.size` read per frame and nothing
+ * else. Armed, per frame per camera it costs: one scene traverse (to find the
+ * transparent surfaces to hide), one extra geometry-only scene draw with shadow
+ * updates suppressed, and a drawing-buffer-sized depth target
+ * (`UnsignedIntType` depth + an unread RGBA8 colour attachment ≈ 8
+ * bytes/pixel).
+ *
+ * ## Why TRANSPARENT surfaces are hidden
+ *
+ * Godot's own `DEPTH_TEXTURE` — the one `proximity_fade_enabled` samples — is
+ * the OPAQUE pass's depth: `BaseMaterial3D`'s default `depth_draw_opaque` means
+ * a transparent material contributes no depth. Reproducing that is not
+ * cosmetic; without it the starter kit's coin would fade its stars against the
+ * translucent glow quad sitting in front of them rather than against the floor.
+ *
+ * ## Resource ownership
+ *
+ * - {@link farDepthTexture}'s 1x1 texture is a module singleton, created on
+ *   first use and NEVER disposed: it is bound into every renderer's uniforms as
+ *   the safe default, so there is no moment at which the last user is known.
+ *   One texel, one allocation per process.
+ * - The armed-renderer registry is written by exactly two functions,
+ *   {@link armSoftParticleDepth} / {@link disarmSoftParticleDepth}, whose only
+ *   callers are `registerParticleSystem` / `unregisterParticleSystem`.
+ * - The render target and override material belong to the
+ *   {@link SoftParticleDepthPass} instance and die with its `dispose()`. The
+ *   pass itself is owned by whichever adapter mount created it (the R3F adapter
+ *   and `setup-three-root-adapter`), and that mount's teardown is the one path
+ *   allowed to end it.
+ */
+import * as THREE from 'three';
+/**
+ * The renderers hosting at least one system that asked for `softParticles`, and
+ * HOW MANY — a renderer may batch several emitters and must stay armed until
+ * the last one leaves.
+ *
+ * Module-scoped because the pass is per-MOUNT while a renderer is per-emitter:
+ * two worlds may be mounted at once and each pass filters this map down to the
+ * renderers actually parented under the scene it is rendering.
+ */
+const armed = new Map();
+let farDepth;
+/**
+ * A 1x1 texture whose red channel is 1.0 — "the depth buffer says nothing is in
+ * front of anything".
+ *
+ * Bound to a `BatchedRenderer` the moment it is constructed, so a batch that
+ * later compiles with `SOFT_PARTICLES` inherits it (`BatchedRenderer.addSystem`
+ * applies `this.depthTexture` to each batch it creates). Feeding
+ * `linearize_depth` a `1.0` yields `(zFar * zNear) / (zFar - (zFar - zNear))`,
+ * which is `zFar`, so the fade term is `saturate(k * (zFar - linearDepth))` — 1
+ * for every fragment in front of the far plane. The fade is INERT rather than
+ * wrong, which is what makes an undriven surface (a design-time preview, a host
+ * with no pass) render exactly as it did before soft particles existed.
+ */
+export function farDepthTexture() {
+    if (farDepth === undefined) {
+        farDepth = new THREE.DataTexture(new Uint8Array([255, 255, 255, 255]), 1, 1);
+        farDepth.name = 'soft-particle-far-depth';
+        farDepth.needsUpdate = true;
+    }
+    return farDepth;
+}
+/** Record that `renderer` hosts one more soft-particle system, so passes stop skipping it. */
+export function armSoftParticleDepth(renderer) {
+    armed.set(renderer, (armed.get(renderer) ?? 0) + 1);
+}
+/**
+ * The other half of {@link armSoftParticleDepth}. On the LAST soft system the
+ * renderer is dropped from the registry and handed the inert far-depth default
+ * back, so a batch that outlives its registration never keeps sampling a scene
+ * depth nobody is refreshing.
+ */
+export function disarmSoftParticleDepth(renderer) {
+    const remaining = (armed.get(renderer) ?? 0) - 1;
+    if (remaining > 0) {
+        armed.set(renderer, remaining);
+        return;
+    }
+    if (!armed.delete(renderer))
+        return;
+    renderer.setDepthTexture(farDepthTexture());
+}
+/** Test/diagnostic read of the registry — how many renderers a pass would consider. */
+export function armedSoftParticleRendererCount() {
+    return armed.size;
+}
+/** Is `node` inside `root`'s subtree? Walks parents, so it is O(depth), not O(scene). */
+function isUnder(node, root) {
+    for (let at = node; at !== null; at = at.parent) {
+        if (at === root)
+            return true;
+    }
+    return false;
+}
+/** Godot's `depth_draw_opaque`: a transparent surface contributes no depth. */
+function drawsIntoDepth(object) {
+    const material = object.material;
+    if (material === undefined)
+        return true;
+    return Array.isArray(material)
+        ? !material.every((entry) => entry.transparent)
+        : !material.transparent;
+}
+/**
+ * The three renderer members this prepass CANNOT do without — the render-target
+ * swap it draws through, and the buffer size it sizes that target from.
+ *
+ * A real `WebGLRenderer` has all of them. A DESIGN-TIME settle does not: a
+ * stand-in that only has to answer `render` mounts a world so the editor can
+ * read it, and reaching for `getDrawingBufferSize` on one threw
+ * `renderer.getDrawingBufferSize is not a function` out of the first driven
+ * frame — so a world whose particles merely *declare* a proximity fade could
+ * not be settled at all. A prepass is an EFFECT: with no renderer to run it on,
+ * the right answer is the inert far-depth default every batch is already bound
+ * to (see {@link farDepthTexture}), which is pixel-identical to a batch that
+ * never asked for soft particles. So this degrades, loudly and once, instead of
+ * taking the frame down with it.
+ */
+const REQUIRED_RENDERER_MEMBERS = [
+    'getDrawingBufferSize',
+    'getRenderTarget',
+    'setRenderTarget',
+    'render',
+];
+/** The required members `renderer` does not implement, in declaration order. */
+function missingRendererMembers(renderer) {
+    const held = renderer;
+    return REQUIRED_RENDERER_MEMBERS.filter((name) => typeof held[name] !== 'function');
+}
+export function createSoftParticleDepthPass() {
+    let target = null;
+    /** Warned about already — one line per pass, not one per frame. */
+    let warnedIncapable = false;
+    const override = new THREE.MeshBasicMaterial({ colorWrite: false });
+    override.name = 'soft-particle-depth-prepass';
+    const size = new THREE.Vector2();
+    const hidden = [];
+    const resize = (width, height) => {
+        if (target !== null && target.width === width && target.height === height)
+            return target;
+        target?.dispose();
+        const depthTexture = new THREE.DepthTexture(width, height, THREE.UnsignedIntType);
+        depthTexture.name = 'soft-particle-scene-depth';
+        const next = new THREE.WebGLRenderTarget(width, height, { depthBuffer: true, depthTexture });
+        target = next;
+        return next;
+    };
+    return {
+        render(renderer, scene, camera) {
+            if (armed.size === 0)
+                return;
+            const consumers = [];
+            for (const candidate of armed.keys()) {
+                if (isUnder(candidate, scene))
+                    consumers.push(candidate);
+            }
+            if (consumers.length === 0)
+                return;
+            // See REQUIRED_RENDERER_MEMBERS: a renderer that cannot swap render
+            // targets cannot run a prepass, and the frame is worth more than the
+            // fade. Every consumer keeps the far-depth default it was armed with.
+            const missing = missingRendererMembers(renderer);
+            if (missing.length > 0) {
+                if (!warnedIncapable) {
+                    warnedIncapable = true;
+                    // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to throwing out of the frame
+                    console.warn(`soft-particle depth prepass skipped: this renderer implements none of ${missing.join(', ')}. ` +
+                        `${String(consumers.length)} particle batch(es) keep the inert far-depth default, so they ` +
+                        'draw unfaded — the same pixels as a batch that never declared a proximity fade. A real ' +
+                        'WebGLRenderer has these; a design-time settle stand-in does not.');
+                }
+                return;
+            }
+            renderer.getDrawingBufferSize(size);
+            const width = Math.max(1, Math.floor(size.x));
+            const height = Math.max(1, Math.floor(size.y));
+            const rt = resize(width, height);
+            // Hidden for the prepass: the particles themselves (they are what samples
+            // this depth) and every transparent surface (Godot's opaque-only depth).
+            hidden.length = 0;
+            for (const consumer of consumers) {
+                if (consumer.visible) {
+                    consumer.visible = false;
+                    hidden.push(consumer);
+                }
+            }
+            scene.traverse((object) => {
+                if (!object.visible)
+                    return;
+                if (drawsIntoDepth(object))
+                    return;
+                object.visible = false;
+                hidden.push(object);
+            });
+            const previousTarget = renderer.getRenderTarget();
+            const previousOverride = scene.overrideMaterial;
+            // three re-renders every shadow map on EVERY `render()` call while
+            // `shadowMap.autoUpdate` is on, so without this the prepass would double
+            // the frame's shadow cost for a pass that writes depth and nothing else.
+            // Both flags are restored below; the frame's own draw re-renders them.
+            const shadows = renderer.shadowMap;
+            const previousAutoUpdate = shadows?.autoUpdate ?? false;
+            const previousNeedsUpdate = shadows?.needsUpdate ?? false;
+            if (shadows !== undefined) {
+                shadows.autoUpdate = false;
+                shadows.needsUpdate = false;
+            }
+            scene.overrideMaterial = override;
+            try {
+                renderer.setRenderTarget(rt);
+                renderer.render(scene, camera);
+            }
+            finally {
+                renderer.setRenderTarget(previousTarget);
+                scene.overrideMaterial = previousOverride;
+                if (shadows !== undefined) {
+                    shadows.autoUpdate = previousAutoUpdate;
+                    shadows.needsUpdate = previousNeedsUpdate;
+                }
+                for (const object of hidden)
+                    object.visible = true;
+                hidden.length = 0;
+            }
+            for (const consumer of consumers)
+                consumer.setDepthTexture(rt.depthTexture);
+        },
+        dispose() {
+            // Every consumer this pass fed now points at a texture that is about to
+            // go away. Hand them the inert default back rather than a disposed one.
+            for (const candidate of armed.keys())
+                candidate.setDepthTexture(farDepthTexture());
+            target?.dispose();
+            target = null;
+            override.dispose();
+        },
+    };
+}