@aura3d/engine 2.0.4 → 3.0.1

package/dist/rendering/effects/ParticleRenderer.js

@@ -1,3 +1,24 @@
+/**
+ * Soft-particle depth fade: 0 when the particle is behind the scene surface,
+ * ramping to 1 one fadeDistance in front of it. Pure and shared so the probe
+ * can show the exact on/off delta the renderer applies.
+ */
+export function computeSoftParticleFade(sceneDepth, particleDepth, fadeDistance) {
+    if (!Number.isFinite(sceneDepth) || !Number.isFinite(particleDepth) || !Number.isFinite(fadeDistance)) {
+        throw new RangeError("Soft-particle fade inputs must be finite numbers.");
+    }
+    if (fadeDistance <= 0) {
+        throw new RangeError("Soft-particle fadeDistance must be positive.");
+    }
+    const t = (sceneDepth - particleDepth) / fadeDistance;
+    return Math.min(1, Math.max(0, t));
+}
+/** WGSL snippet consumers can drop into their own particle render shaders. */
+export const SOFT_PARTICLE_WGSL = `
+fn auraSoftParticleFade(sceneDepth: f32, particleDepth: f32, fadeDistance: f32) -> f32 {
+  return clamp((sceneDepth - particleDepth) / max(fadeDistance, 1e-6), 0.0, 1.0);
+}
+`;
 export class ParticleRenderer {
     lastBatch = {
         sprites: [],
@@ -6,15 +27,36 @@ export class ParticleRenderer {
         bounds: null,
     };
     buildBatch(particles, options = {}) {
+        const soft = options.softParticles;
+        if (soft?.enabled) {
+            validateSoftParticles(soft);
+        }
         const sprites = particles
             .filter((particle) => particle.alive)
-            .map((particle) => ({
-            id: particle.id,
-            position: { ...particle.position },
-            color: { ...particle.color },
-            size: particle.size,
-            rotation: particle.rotation,
-        }));
+            .map((particle) => {
+            let fade = 1;
+            let alpha = particle.color.a;
+            if (soft?.enabled) {
+                const sceneDepth = soft.sceneDepthAt(particle.position);
+                const particleDepth = soft.particleDepthAt(particle.position);
+                if (!Number.isFinite(particleDepth)) {
+                    throw new RangeError("ParticleRenderer softParticles particleDepthAt must return a finite number.");
+                }
+                // Non-finite scene depth = the view ray hits no occluder: no attenuation.
+                fade = Number.isFinite(sceneDepth)
+                    ? computeSoftParticleFade(sceneDepth, particleDepth, soft.fadeDistance)
+                    : 1;
+                alpha = particle.color.a * fade;
+            }
+            return {
+                id: particle.id,
+                position: { ...particle.position },
+                color: { ...particle.color, a: alpha },
+                size: particle.size,
+                rotation: particle.rotation,
+                fade,
+            };
+        });
         sortSprites(sprites, options);
         this.lastBatch = {
             sprites,
@@ -81,6 +123,14 @@ function computeBounds(sprites) {
     }
     return { min, max };
 }
+function validateSoftParticles(soft) {
+    if (!Number.isFinite(soft.fadeDistance) || soft.fadeDistance <= 0) {
+        throw new RangeError("ParticleRenderer softParticles fadeDistance must be a finite positive number.");
+    }
+    if (typeof soft.sceneDepthAt !== "function" || typeof soft.particleDepthAt !== "function") {
+        throw new RangeError("ParticleRenderer softParticles requires sceneDepthAt and particleDepthAt functions.");
+    }
+}
 function distanceSquared(a, b) {
     const x = a.x - b.x;
     const y = a.y - b.y;

package/dist/rendering/effects/ParticleRenderer.js.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleRenderer.js","sourceRoot":"","sources":["../../../../../packages/rendering/src/effects/ParticleRenderer.ts"],"names":[],"mappings":"AAkCA,MAAM,OAAO,gBAAgB;IACnB,SAAS,GAAwB;QACvC,OAAO,EAAE,EAAE;QACX,SAAS,EAAE,CAAC;QACZ,aAAa,EAAE,CAAC;QAChB,MAAM,EAAE,IAAI;KACb,CAAC;IAEF,UAAU,CAAC,SAA8B,EAAE,UAAiC,EAAE;QAC5E,MAAM,OAAO,GAAG,SAAS;aACtB,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC;aACpC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YAClB,EAAE,EAAE,QAAQ,CAAC,EAAE;YACf,QAAQ,EAAE,EAAE,GAAG,QAAQ,CAAC,QAAQ,EAAE;YAClC,KAAK,EAAE,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE;YAC5B,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;SAC5B,CAAC,CAAC,CAAC;QACN,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAE9B,IAAI,CAAC,SAAS,GAAG;YACf,OAAO;YACP,SAAS,EAAE,OAAO,CAAC,MAAM;YACzB,aAAa,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,YAAY,CAAC,iBAAiB;YAChF,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC;SAC/B,CAAC;QAEF,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,MAAM,CAAC,MAAsB,EAAE,MAA0B,EAAE,UAAiC,EAAE;QAC5F,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACzD,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC5B,MAAM,CAAC,kBAAkB,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAC/C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,YAAY;QACV,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gBAC/C,GAAG,MAAM;gBACT,QAAQ,EAAE,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE;gBAChC,KAAK,EAAE,EAAE,GAAG,MAAM,CAAC,KAAK,EAAE;aAC3B,CAAC,CAAC;YACH,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS;YACnC,aAAa,EAAE,IAAI,CAAC,SAAS,CAAC,aAAa;YAC3C,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC9B,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE;gBACrC,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE;aACtC,CAAC,CAAC,CAAC,IAAI;SACT,CAAC;IACJ,CAAC;CACF;AAED,SAAS,WAAW,CAAC,OAAyB,EAAE,OAA8B;IAC5E,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC;IACpC,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO;IAC5B,MAAM,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IACtC,IAAI,CAAC,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,UAAU,CAAC,+EAA+E,CAAC,CAAC;IACxG,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,KAAK,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACpB,MAAM,aAAa,GAAG,eAAe,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAChG,IAAI,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,IAAI;YAAE,OAAO,aAAa,GAAG,SAAS,CAAC;QACrE,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;IACrB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,aAAa,CAAC,OAAkC;IACvD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,GAAG,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,iBAAiB,EAAE,CAAC,EAAE,MAAM,CAAC,iBAAiB,EAAE,CAAC,EAAE,MAAM,CAAC,iBAAiB,EAAE,CAAC;IACtG,MAAM,GAAG,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,iBAAiB,EAAE,CAAC,EAAE,MAAM,CAAC,iBAAiB,EAAE,CAAC,EAAE,MAAM,CAAC,iBAAiB,EAAE,CAAC;IACtG,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACzF,MAAM,IAAI,UAAU,CAAC,kFAAkF,CAAC,CAAC;QAC3G,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,GAAG,GAAG,CAAC;QACjC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;QACpD,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;QACpD,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;QACpD,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;QACpD,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;QACpD,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AACtB,CAAC;AAED,SAAS,eAAe,CAAC,CAAc,EAAE,CAAc;IACrD,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,cAAc,CAAC,KAAkB;IACxC,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC1F,CAAC"}
+{"version":3,"file":"ParticleRenderer.js","sourceRoot":"","sources":["../../../../../packages/rendering/src/effects/ParticleRenderer.ts"],"names":[],"mappings":"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"}

package/dist/rendering/effects/ParticleSystem.d.ts

@@ -1,6 +1,6 @@
 import { type Particle } from "./Particle.js";
 import { ParticleEmitter } from "./ParticleEmitter.js";
-import type { GPUParticleBackend } from "./GPUParticleBackend.js";
+import { type GPUParticleBackend, type GPUParticleEffectsInput } from "./GPUParticleBackend.js";
 import { type ParticleModule } from "./ParticleModule.js";
 export interface ParticleSystemStats {
     liveCount: number;
@@ -12,7 +12,25 @@ export interface ParticleSystemStats {
     uploadedBytes: number;
     gpuSpawns: number;
     gpuUpdates: number;
+    /** True once any spawn request (emitter or sub-emitter) exceeded capacity. Never a silent clamp. */
+    overBudget: boolean;
 }
+export interface CollectedGPUParticleEffects {
+    readonly effects: GPUParticleEffectsInput;
+    /**
+     * Modules whose per-frame hooks the compute kernel implements. The system
+     * skips their CPU update/afterIntegrate hooks on the GPU path (zero CPU
+     * per-particle work); every other module keeps its CPU hooks on both paths.
+     */
+    readonly gpuCovered: ReadonlySet<ParticleModule>;
+}
+/**
+ * Aggregate GPU-capable modules into one compute effects descriptor.
+ * Returns undefined when no module has a GPU implementation (legacy path).
+ * Overflow policy: the first N instances of a capped effect (3 planes,
+ * 2 sub-emitters) run on GPU; extras keep their exact CPU hooks.
+ */
+export declare function collectGPUParticleEffects(modules: readonly ParticleModule[]): CollectedGPUParticleEffects | undefined;
 export interface ParticleSystemOptions {
     maxParticles?: number;
     emitters?: readonly ParticleEmitter[];
@@ -30,6 +48,11 @@ export declare class ParticleSystem {
     private stats;
     private gpuBackend?;
     private preferGPU;
+    private lastSpawnRequests;
+    private lastIntegratedParticles;
+    private lastEffectsCovered;
+    /** GPU trail ring rows by particle id, fed back so history accumulates across calls. */
+    private trailRingById;
     constructor(options?: ParticleSystemOptions);
     addEmitter(emitter: ParticleEmitter): this;
     addModule(module: ParticleModule): this;
@@ -45,6 +68,27 @@ export declare class ParticleSystem {
     private initializeSpawnedOnGPU;
     private integrate;
     private integrateOnGPU;
+    /**
+     * Assemble the previous trail ring in live-particle order from per-id rows
+     * so compute history survives spawn/death reordering. Unknown ids start
+     * fresh (head = live position/age, older slots expired).
+     */
+    private assembleTrailHistory;
+    private storeTrailRings;
+    /** CPU path: turn queued sub-emitter requests into live child particles. */
+    private drainSubEmitterSpawns;
+    /**
+     * GPU path: covered sub-emitters report per-particle spawn requests from
+     * the compute kernel; uncovered ones queue CPU requests as usual. Children
+     * initialize through the GPU spawn pipeline when the backend offers one.
+     */
+    private drainSubEmitterSpawnsOnGPU;
+    /**
+     * Decode one covered sub-emitter slot from the packed kernel flags
+     * (low 16 bits = slot 0, high 16 bits = slot 1).
+     */
+    private requestsForSubEmitter;
+    private applyGPUTrailHistories;
     private compactDeadParticles;
     private createContext;
 }

package/dist/rendering/effects/ParticleSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleSystem.d.ts","sourceRoot":"","sources":["../../../../../packages/rendering/src/effects/ParticleSystem.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,QAAQ,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAwB,KAAK,cAAc,EAA8B,MAAM,qBAAqB,CAAC;AAE5G,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACtC,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACpC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,qBAAa,cAAc;IACzB,QAAQ,CAAC,SAAS,EAAE,QAAQ,EAAE,CAAM;IACpC,QAAQ,CAAC,QAAQ,EAAE,eAAe,EAAE,CAAM;IAC1C,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,CAAM;IACxC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,WAAW,SAAK;IAChB,MAAM,UAAS;IAEf,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,UAAU,CAAC,CAAqB;IACxC,OAAO,CAAC,SAAS,CAAU;gBAEf,OAAO,GAAE,qBAA0B;IAuB/C,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAK1C,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKvC,aAAa,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,EAAE,SAAS,UAAwB,GAAG,IAAI;IAM/F,KAAK,IAAI,IAAI;IAMb,OAAO,IAAI,IAAI;IAOf,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAgBzB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB1E,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;IAU3D,QAAQ,IAAI,mBAAmB;IAI/B,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IASvC,OAAO,CAAC,KAAK;YAmBC,sBAAsB;IAmDpC,OAAO,CAAC,SAAS;YAuBH,cAAc;IA8D5B,OAAO,CAAC,oBAAoB;IAkB5B,OAAO,CAAC,aAAa;CAQtB"}
+{"version":3,"file":"ParticleSystem.d.ts","sourceRoot":"","sources":["../../../../../packages/rendering/src/effects/ParticleSystem.ts"],"names":[],"mappings":"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"}

package/dist/rendering/effects/ParticleSystem.js

@@ -1,6 +1,139 @@
 import { addScaledVector3, normalizedParticleAge, setVector3, } from "./Particle.js";
 import { ParticleEmitter } from "./ParticleEmitter.js";
+import { GPU_PARTICLE_CURVE_STOPS, } from "./GPUParticleBackend.js";
 import { applyParticleModules } from "./ParticleModule.js";
+import { CollisionModule } from "./CollisionModule.js";
+import { encodeColorGradientLUT, ColorModule } from "./ColorModule.js";
+import { encodeSizeCurveLUT, SizeModule } from "./SizeModule.js";
+import { WindModule } from "./ForceModule.js";
+import { TurbulenceModule } from "./TurbulenceModule.js";
+import { HeightfieldModule } from "./HeightfieldModule.js";
+import { LightingModule } from "./LightingModule.js";
+import { SubEmitterModule } from "./SubEmitterModule.js";
+import { decodeTrailRingBuffer, TrailModule } from "./TrailModule.js";
+/**
+ * Aggregate GPU-capable modules into one compute effects descriptor.
+ * Returns undefined when no module has a GPU implementation (legacy path).
+ * Overflow policy: the first N instances of a capped effect (3 planes,
+ * 2 sub-emitters) run on GPU; extras keep their exact CPU hooks.
+ */
+export function collectGPUParticleEffects(modules) {
+    const covered = new Set();
+    let wind;
+    let turbulence;
+    let heightfield;
+    let lighting;
+    let lifeCurves;
+    let trailPointsPerParticle;
+    const planes = [];
+    const subEmitters = [];
+    let colorModule;
+    let sizeModule;
+    for (const module of modules) {
+        if (module instanceof WindModule && !wind) {
+            const encoded = module.toGPUWind();
+            wind = {
+                direction: encoded.direction,
+                strength: encoded.strength,
+                gustAmplitude: encoded.gustAmplitude,
+                gustDirection: encoded.gustDirection,
+                gustFrequency: encoded.gustFrequency,
+                gustSpeed: encoded.gustSpeed,
+            };
+            covered.add(module);
+        }
+        else if (module instanceof TurbulenceModule && !turbulence) {
+            const encoded = module.toGPUTurbulence();
+            turbulence = {
+                strength: encoded.strength,
+                scale: encoded.scale,
+                flowSpeed: encoded.flowSpeed,
+                lut: module.getLUT(),
+                lutResolution: encoded.lutResolution,
+            };
+            covered.add(module);
+        }
+        else if (module instanceof CollisionModule && planes.length < 3) {
+            const encoded = module.toGPUPlane();
+            planes.push({
+                normal: encoded.normal,
+                constant: encoded.constant,
+                restitution: encoded.restitution,
+                killOnContact: encoded.killOnContact,
+            });
+            covered.add(module);
+        }
+        else if (module instanceof HeightfieldModule && !heightfield) {
+            const encoded = module.toGPUHeightfield();
+            heightfield = {
+                originX: encoded.originX,
+                originZ: encoded.originZ,
+                cellSize: encoded.cellSize,
+                columns: encoded.columns,
+                rows: encoded.rows,
+                heights: module.sampler.heights,
+                restitution: encoded.restitution,
+                killOnContact: encoded.killOnContact,
+            };
+            covered.add(module);
+        }
+        else if (module instanceof ColorModule && !colorModule) {
+            colorModule = module;
+        }
+        else if (module instanceof SizeModule && !sizeModule) {
+            sizeModule = module;
+        }
+        else if (module instanceof LightingModule && !lighting) {
+            const encoded = module.toGPULighting();
+            lighting = {
+                ambient: encoded.ambient,
+                keyDirection: encoded.keyDirection,
+                diffuseStrength: encoded.diffuseStrength,
+            };
+            covered.add(module);
+        }
+        else if (module instanceof SubEmitterModule && subEmitters.length < 2) {
+            const encoded = module.toGPUSubEmitter();
+            subEmitters.push({
+                triggerAge: encoded.triggerAge,
+                chance: encoded.chance,
+                childCount: encoded.childCount,
+            });
+            covered.add(module);
+        }
+        else if (module instanceof TrailModule && trailPointsPerParticle === undefined) {
+            trailPointsPerParticle = Math.min(module.maxPoints, 8);
+            covered.add(module);
+        }
+    }
+    if (colorModule || sizeModule) {
+        lifeCurves = {
+            stops: GPU_PARTICLE_CURVE_STOPS,
+            ...(colorModule ? { colors: encodeColorGradientLUT(colorModule.gradient, GPU_PARTICLE_CURVE_STOPS) } : {}),
+            ...(sizeModule ? { sizes: encodeSizeCurveLUT(sizeModule.curve, GPU_PARTICLE_CURVE_STOPS) } : {}),
+        };
+        if (colorModule)
+            covered.add(colorModule);
+        if (sizeModule)
+            covered.add(sizeModule);
+    }
+    if (covered.size === 0) {
+        return undefined;
+    }
+    return {
+        effects: {
+            wind,
+            turbulence,
+            planes,
+            heightfield,
+            subEmitters,
+            lifeCurves,
+            lighting,
+            trailPointsPerParticle,
+        },
+        gpuCovered: covered,
+    };
+}
 export class ParticleSystem {
     particles = [];
     emitters = [];
@@ -11,6 +144,11 @@ export class ParticleSystem {
     stats;
     gpuBackend;
     preferGPU;
+    lastSpawnRequests = [];
+    lastIntegratedParticles = [];
+    lastEffectsCovered;
+    /** GPU trail ring rows by particle id, fed back so history accumulates across calls. */
+    trailRingById = new Map();
     constructor(options = {}) {
         this.maxParticles = options.maxParticles ?? 1000;
         if (!Number.isInteger(this.maxParticles) || this.maxParticles <= 0) {
@@ -30,6 +168,7 @@ export class ParticleSystem {
             uploadedBytes: 0,
             gpuSpawns: 0,
             gpuUpdates: 0,
+            overBudget: false,
         };
     }
     addEmitter(emitter) {
@@ -49,6 +188,10 @@ export class ParticleSystem {
         this.stats.killedCount += this.particles.length;
         this.particles.length = 0;
         this.stats.liveCount = 0;
+        this.trailRingById.clear();
+        this.lastSpawnRequests = [];
+        this.lastIntegratedParticles = [];
+        this.lastEffectsCovered = undefined;
     }
     dispose() {
         this.clear();
@@ -65,6 +208,7 @@ export class ParticleSystem {
         }
         this.spawn(deltaTime);
         this.integrate(deltaTime);
+        this.drainSubEmitterSpawns();
         this.compactDeadParticles();
         this.elapsedTime += deltaTime;
         this.stats.liveCount = this.particles.length;
@@ -79,6 +223,7 @@ export class ParticleSystem {
         const spawnedParticles = this.spawn(deltaTime);
         await this.initializeSpawnedOnGPU(spawnedParticles, backend);
         await this.integrateOnGPU(deltaTime, backend);
+        await this.drainSubEmitterSpawnsOnGPU(backend);
         this.compactDeadParticles();
         this.elapsedTime += deltaTime;
         this.stats.liveCount = this.particles.length;
@@ -106,7 +251,11 @@ export class ParticleSystem {
         for (const emitter of this.emitters) {
             const capacity = this.maxParticles - this.particles.length;
             const result = emitter.emit(deltaTime, capacity);
-            this.stats.droppedCount += Math.max(0, result.requested - result.emitted);
+            const dropped = Math.max(0, result.requested - result.emitted);
+            this.stats.droppedCount += dropped;
+            if (dropped > 0) {
+                this.stats.overBudget = true;
+            }
             this.stats.spawnedCount += result.emitted;
             for (const particle of result.particles) {
                 const context = this.createContext(deltaTime, particle);
@@ -185,14 +334,26 @@ export class ParticleSystem {
         if (liveParticles.length === 0) {
             return;
         }
+        const collected = collectGPUParticleEffects(this.modules);
+        const useEffects = collected !== undefined && backend.supportsEffects === true;
+        const covered = useEffects ? collected.gpuCovered : undefined;
         for (const particle of liveParticles) {
             const context = this.createContext(deltaTime, particle);
-            applyParticleModules(this.modules, "update", particle, context);
+            for (const module of this.modules) {
+                if (covered?.has(module)) {
+                    continue;
+                }
+                module.update?.(particle, context);
+            }
             setVector3(particle.previousPosition, particle.position);
         }
         const positions = new Float32Array(liveParticles.length * 4);
         const velocities = new Float32Array(liveParticles.length * 4);
         const accelerations = new Float32Array(liveParticles.length * 4);
+        const needsBaseAttributes = Boolean(useEffects && (collected.effects.lifeCurves || collected.effects.lighting));
+        const baseAttributes = needsBaseAttributes ? new Float32Array(liveParticles.length * 8) : undefined;
+        const trailDepth = useEffects ? (collected.effects.trailPointsPerParticle ?? 0) : 0;
+        const trailHistory = trailDepth > 0 ? this.assembleTrailHistory(liveParticles, trailDepth) : undefined;
         for (let index = 0; index < liveParticles.length; index += 1) {
             const particle = liveParticles[index];
             const offset = index * 4;
@@ -203,9 +364,19 @@ export class ParticleSystem {
             velocities[offset] = particle.velocity.x;
             velocities[offset + 1] = particle.velocity.y;
             velocities[offset + 2] = particle.velocity.z;
+            // velocities.w carries per-particle lifetime for the effects kernel.
+            velocities[offset + 3] = useEffects ? particle.lifetime : 0;
             accelerations[offset] = particle.acceleration.x;
             accelerations[offset + 1] = particle.acceleration.y;
             accelerations[offset + 2] = particle.acceleration.z;
+            if (baseAttributes) {
+                const attributeOffset = index * 8;
+                baseAttributes[attributeOffset] = particle.color.r;
+                baseAttributes[attributeOffset + 1] = particle.color.g;
+                baseAttributes[attributeOffset + 2] = particle.color.b;
+                baseAttributes[attributeOffset + 3] = particle.color.a;
+                baseAttributes[attributeOffset + 4] = particle.size;
+            }
         }
         const result = await backend.update({
             positions,
@@ -213,26 +384,224 @@ export class ParticleSystem {
             accelerations,
             deltaTime,
             count: liveParticles.length,
+            ...(useEffects
+                ? {
+                    effects: {
+                        ...collected.effects,
+                        time: this.elapsedTime,
+                    },
+                    baseAttributes,
+                    trailHistory,
+                }
+                : {}),
         });
+        if (useEffects) {
+            this.lastSpawnRequests = result.spawnRequests ? Array.from(result.spawnRequests) : [];
+            this.lastIntegratedParticles = liveParticles;
+            this.lastEffectsCovered = covered;
+        }
+        else {
+            this.lastSpawnRequests = [];
+            this.lastIntegratedParticles = [];
+            this.lastEffectsCovered = undefined;
+        }
         for (let index = 0; index < liveParticles.length; index += 1) {
             const particle = liveParticles[index];
             const offset = index * 4;
             particle.position.x = result.positions[offset];
             particle.position.y = result.positions[offset + 1];
             particle.position.z = result.positions[offset + 2];
-            particle.age = result.positions[offset + 3];
+            const rawAge = result.positions[offset + 3];
+            if (useEffects && (!Number.isFinite(rawAge) || rawAge < 0)) {
+                // Compute-side kill (analytic plane or heightfield in kill mode).
+                particle.alive = false;
+                particle.age = particle.lifetime;
+                continue;
+            }
+            particle.age = rawAge;
             particle.velocity.x = result.velocities[offset];
             particle.velocity.y = result.velocities[offset + 1];
             particle.velocity.z = result.velocities[offset + 2];
+            if (result.attributes) {
+                const attributeOffset = index * 8;
+                particle.color.r = result.attributes[attributeOffset] ?? particle.color.r;
+                particle.color.g = result.attributes[attributeOffset + 1] ?? particle.color.g;
+                particle.color.b = result.attributes[attributeOffset + 2] ?? particle.color.b;
+                particle.color.a = result.attributes[attributeOffset + 3] ?? particle.color.a;
+                particle.size = result.attributes[attributeOffset + 4] ?? particle.size;
+            }
             particle.rotation += particle.angularVelocity * deltaTime;
-            applyParticleModules(this.modules, "afterIntegrate", particle, this.createContext(deltaTime, particle));
+            const context = this.createContext(deltaTime, particle);
+            for (const module of this.modules) {
+                if (covered?.has(module)) {
+                    continue;
+                }
+                module.afterIntegrate?.(particle, context);
+            }
             if (particle.age >= particle.lifetime) {
                 particle.alive = false;
             }
         }
+        if (useEffects && result.trailPositions) {
+            this.applyGPUTrailHistories(liveParticles, collected.effects, result.trailPositions);
+            this.storeTrailRings(liveParticles, collected.effects, result.trailPositions);
+        }
         this.stats.gpuUpdates += 1;
         this.recordBufferUpload(positions.byteLength + velocities.byteLength + accelerations.byteLength + 16);
     }
+    /**
+     * Assemble the previous trail ring in live-particle order from per-id rows
+     * so compute history survives spawn/death reordering. Unknown ids start
+     * fresh (head = live position/age, older slots expired).
+     */
+    assembleTrailHistory(liveParticles, depth) {
+        const history = new Float32Array(liveParticles.length * depth * 4);
+        for (let index = 0; index < liveParticles.length; index += 1) {
+            const particle = liveParticles[index];
+            const target = index * depth * 4;
+            const row = this.trailRingById.get(particle.id);
+            if (row && row.length >= depth * 4) {
+                history.set(row.subarray(0, depth * 4), target);
+                continue;
+            }
+            history[target] = particle.position.x;
+            history[target + 1] = particle.position.y;
+            history[target + 2] = particle.position.z;
+            history[target + 3] = particle.age;
+            for (let slot = 1; slot < depth; slot += 1) {
+                const slotOffset = target + slot * 4;
+                history[slotOffset] = particle.position.x;
+                history[slotOffset + 1] = particle.position.y;
+                history[slotOffset + 2] = particle.position.z;
+                history[slotOffset + 3] = Number.POSITIVE_INFINITY;
+            }
+        }
+        return history;
+    }
+    storeTrailRings(liveParticles, effects, trailPositions) {
+        const depth = effects.trailPointsPerParticle ?? 1;
+        for (let index = 0; index < liveParticles.length; index += 1) {
+            const particle = liveParticles[index];
+            if (!particle) {
+                continue;
+            }
+            this.trailRingById.set(particle.id, trailPositions.slice(index * depth * 4, (index + 1) * depth * 4));
+        }
+        if (this.trailRingById.size > this.particles.length * 2 + 16) {
+            const liveIds = new Set(this.particles.map((particle) => particle.id));
+            for (const id of this.trailRingById.keys()) {
+                if (!liveIds.has(id)) {
+                    this.trailRingById.delete(id);
+                }
+            }
+        }
+    }
+    /** CPU path: turn queued sub-emitter requests into live child particles. */
+    drainSubEmitterSpawns() {
+        for (const module of this.modules) {
+            if (!(module instanceof SubEmitterModule)) {
+                continue;
+            }
+            const capacity = this.maxParticles - this.particles.length;
+            const { children, dropped } = module.drainPendingSpawns(capacity);
+            this.stats.droppedCount += dropped;
+            if (dropped > 0) {
+                this.stats.overBudget = true;
+            }
+            for (const child of children) {
+                const context = this.createContext(0, child);
+                applyParticleModules(this.modules, "onSpawn", child, context);
+                this.particles.push(child);
+                this.stats.spawnedCount += 1;
+            }
+        }
+    }
+    /**
+     * GPU path: covered sub-emitters report per-particle spawn requests from
+     * the compute kernel; uncovered ones queue CPU requests as usual. Children
+     * initialize through the GPU spawn pipeline when the backend offers one.
+     */
+    async drainSubEmitterSpawnsOnGPU(backend) {
+        const spawned = [];
+        let slot = 0;
+        for (const module of this.modules) {
+            if (!(module instanceof SubEmitterModule)) {
+                continue;
+            }
+            const capacity = this.maxParticles - this.particles.length - spawned.length;
+            if (this.lastEffectsCovered?.has(module) ?? false) {
+                const { children, dropped } = module.createChildren(this.requestsForSubEmitter(slot), capacity);
+                slot += 1;
+                this.stats.droppedCount += dropped;
+                if (dropped > 0) {
+                    this.stats.overBudget = true;
+                }
+                spawned.push(...children);
+            }
+            else {
+                const { children, dropped } = module.drainPendingSpawns(capacity);
+                this.stats.droppedCount += dropped;
+                if (dropped > 0) {
+                    this.stats.overBudget = true;
+                }
+                spawned.push(...children);
+            }
+        }
+        if (spawned.length === 0) {
+            return;
+        }
+        for (const child of spawned) {
+            const context = this.createContext(0, child);
+            applyParticleModules(this.modules, "onSpawn", child, context);
+            this.particles.push(child);
+            this.stats.spawnedCount += 1;
+        }
+        await this.initializeSpawnedOnGPU(spawned, backend);
+    }
+    /**
+     * Decode one covered sub-emitter slot from the packed kernel flags
+     * (low 16 bits = slot 0, high 16 bits = slot 1).
+     */
+    requestsForSubEmitter(slot) {
+        const requests = [];
+        if (this.lastSpawnRequests.length === 0) {
+            return requests;
+        }
+        for (let index = 0; index < this.lastSpawnRequests.length; index += 1) {
+            const flag = this.lastSpawnRequests[index] ?? 0;
+            const count = slot === 0 ? flag & 0xffff : flag >>> 16;
+            if (count <= 0) {
+                continue;
+            }
+            // Death triggers intentionally reference particles that just died; the
+            // kernel only records requests for triggers crossed while alive.
+            const particle = this.lastIntegratedParticles[index];
+            if (!particle) {
+                continue;
+            }
+            requests.push({
+                position: { ...particle.position },
+                velocity: { ...particle.velocity },
+                count,
+            });
+        }
+        return requests;
+    }
+    applyGPUTrailHistories(liveParticles, effects, trailPositions) {
+        const trailModule = this.modules.find((module) => module instanceof TrailModule);
+        if (!(trailModule instanceof TrailModule)) {
+            return;
+        }
+        const depth = effects.trailPointsPerParticle ?? 1;
+        const histories = decodeTrailRingBuffer(trailPositions, liveParticles.length, depth, trailModule.lifetime);
+        for (let index = 0; index < liveParticles.length; index += 1) {
+            const particle = liveParticles[index];
+            if (!particle || !particle.alive) {
+                continue;
+            }
+            particle.userData.trail = histories[index] ?? [];
+        }
+    }
     compactDeadParticles() {
         let write = 0;
         let killed = 0;