@downdraft/engine 0.1.1 → 0.2.0

package/dist/libraries/weatherfx/src/particle-system.js

@@ -0,0 +1,350 @@
+// ============================================================================
+// Weather Particle System — GPU compute with LOD voxel collision
+// Near-zone particles (within ~30m) collide with terrain voxel density fields.
+// Far-zone particles are gravity-only VFX with no collision cost.
+// ============================================================================
+import { createValidatedShaderModule } from "@downdraft/engine";
+import { calculateViewProj, DEPTH_FORMAT, MSAA_SAMPLE_COUNT } from "@downdraft/engine";
+import { WeatherType } from "@downdraft/engine/libraries/weather";
+import { wgsl } from "@downdraft/engine/shader-graph";
+const COMPUTE_WGSL = "struct Particle {\n  posX: f32, posY: f32, posZ: f32,\n  velX: f32, velY: f32, velZ: f32,\n  life: f32, size: f32,\n  colorR: f32, colorG: f32, colorB: f32,\n  alive: f32,\n};\n\nstruct SimParams {\n  deltaTime: f32,\n  time: f32,\n  spawnCount: f32,\n  maxParticles: f32,\n  cursor: f32,\n  weatherType: f32,\n  isSnow: f32,\n  _pad0: f32,\n  cameraPos: vec3<f32>,\n  collisionRadius: f32,\n  spawnSpread: f32,\n  spawnHeight: f32,\n  baseVelY: f32,\n  particleSize: f32,\n  lifetime: f32,\n  colorR: f32, colorG: f32, colorB: f32,\n  windX: f32, windZ: f32,\n  _pad1: f32, _pad2: f32,\n  voxelOrigin: vec3<f32>,\n  voxelSize: f32,\n  voxelDimX: f32, voxelDimY: f32, voxelDimZ: f32,\n  voxelCount: f32,\n  isoLevel: f32,\n  seed: f32,\n};\n\nstruct Counter {\n  cursor: atomic<u32>,\n  activeCount: atomic<u32>,\n};\n\n@group(0) @binding(0) var<storage, read_write> particles: array<Particle>;\n@group(0) @binding(1) var<uniform> params: SimParams;\n@group(0) @binding(2) var<storage, read_write> counter: Counter;\n@group(0) @binding(3) var<storage, read> voxelData: array<f32>;\n\nfn hash(seed: ptr<function, u32>) -> f32 {\n  *seed = *seed * 1103515245u + 12345u;\n  return f32(*seed) / 4294967296.0;\n}\n\nfn randRange(seed: ptr<function, u32>, min: f32, max: f32) -> f32 {\n  return min + hash(seed) * (max - min);\n}\n\nfn sampleVoxel(x: i32, y: i32, z: i32) -> f32 {\n  if (x < 0 || x >= i32(params.voxelDimX) ||\n      y < 0 || y >= i32(params.voxelDimY) ||\n      z < 0 || z >= i32(params.voxelDimZ)) {\n    return -1.0;\n  }\n  let idx = u32(x) * u32(params.voxelDimY) * u32(params.voxelDimZ) + u32(y) * u32(params.voxelDimZ) + u32(z);\n  if (idx >= u32(params.voxelCount)) { return -1.0; }\n  return voxelData[idx];\n}\n\nfn sampleVoxelGrad(p: vec3<f32>) -> vec3<f32> {\n  let vs = params.voxelSize;\n  let ox = params.voxelOrigin.x;\n  let oy = params.voxelOrigin.y;\n  let oz = params.voxelOrigin.z;\n  let vx = i32(floor((p.x - ox) / vs));\n  let vy = i32(floor((p.y - oy) / vs));\n  let vz = i32(floor((p.z - oz) / vs));\n  let dx = sampleVoxel(vx + 1, vy, vz) - sampleVoxel(vx - 1, vy, vz);\n  let dy = sampleVoxel(vx, vy + 1, vz) - sampleVoxel(vx, vy - 1, vz);\n  let dz = sampleVoxel(vx, vy, vz + 1) - sampleVoxel(vx, vy, vz - 1);\n  let n = vec3<f32>(dx, dy, dz);\n  let len = length(n);\n  if (len < 1e-6) { return vec3<f32>(0.0, 1.0, 0.0); }\n  return n / len;\n}\n\nfn voxelDensityAt(p: vec3<f32>) -> f32 {\n  let vs = params.voxelSize;\n  let ox = params.voxelOrigin.x;\n  let oy = params.voxelOrigin.y;\n  let oz = params.voxelOrigin.z;\n  let vx = i32(floor((p.x - ox) / vs));\n  let vy = i32(floor((p.y - oy) / vs));\n  let vz = i32(floor((p.z - oz) / vs));\n  return sampleVoxel(vx, vy, vz);\n}\n\n@compute @workgroup_size(64)\nfn cs_emit(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let idx = gid.x;\n  if (idx >= u32(params.spawnCount)) { return; }\n\n  let cursor = atomicAdd(&counter.cursor, 1u) % u32(params.maxParticles);\n  var seed = u32(params.seed) + idx * 7919u + u32(params.time * 1000.0);\n\n  let px = params.cameraPos.x + randRange(&seed, -params.spawnSpread, params.spawnSpread);\n  let py = params.cameraPos.y + params.spawnHeight + randRange(&seed, 0.0, params.spawnHeight * 0.3);\n  let pz = params.cameraPos.z + randRange(&seed, -params.spawnSpread, params.spawnSpread);\n\n  let vx = params.windX + randRange(&seed, -2.0, 2.0);\n  let vy = params.baseVelY + randRange(&seed, -3.0, 3.0);\n  let vz = params.windZ + randRange(&seed, -2.0, 2.0);\n\n  particles[cursor].posX = px;\n  particles[cursor].posY = py;\n  particles[cursor].posZ = pz;\n  particles[cursor].velX = vx;\n  particles[cursor].velY = vy;\n  particles[cursor].velZ = vz;\n  particles[cursor].life = params.lifetime + randRange(&seed, -0.5, 0.5);\n  particles[cursor].size = params.particleSize;\n  particles[cursor].colorR = params.colorR;\n  particles[cursor].colorG = params.colorG;\n  particles[cursor].colorB = params.colorB;\n  particles[cursor].alive = 1.0;\n}\n\n@compute @workgroup_size(64)\nfn cs_update(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let idx = gid.x;\n  if (idx >= u32(params.maxParticles)) { return; }\n\n  if (particles[idx].alive < 0.5) { return; }\n\n  var p = particles[idx];\n\n  // Apply gravity (snow has gentler fall)\n  let gravity = select(-30.0, -3.0, u32(params.isSnow) == 1u);\n  p.velY += gravity * params.deltaTime;\n\n  // Apply wind\n  p.velX += params.windX * params.deltaTime * 0.5;\n  p.velZ += params.windZ * params.deltaTime * 0.5;\n\n  // Snow: add gentle sway\n  if (u32(params.isSnow) == 1u) {\n    let swayPhase = params.time * 2.0 + f32(idx) * 0.1;\n    p.velX += sin(swayPhase) * 0.5 * params.deltaTime;\n    p.velZ += cos(swayPhase * 0.7) * 0.5 * params.deltaTime;\n  }\n\n  // Drag — frame-rate independent: pow(perFrameDrag, dt*60) = exp(log(drag)*dt*60)\n  let dragRate = select(log(0.99) * 60.0, log(0.98) * 60.0, u32(params.isSnow) == 1u);\n  let dragMul = exp(dragRate * params.deltaTime);\n  p.velX *= dragMul;\n  p.velY *= dragMul;\n  p.velZ *= dragMul;\n\n  // Compute new position\n  var newPos = vec3<f32>(p.posX, p.posY, p.posZ) + vec3<f32>(p.velX, p.velY, p.velZ) * params.deltaTime;\n\n  // Voxel collision is disabled: the 6-tap gradient sampling caused premature\n  // particle death due to inaccurate surface normal estimation at the voxel\n  // resolution used for weather LOD. Particles now fall through terrain and are\n  // killed by the life/distance checks below. Re-enable by restoring the\n  // density check + sampleVoxelGrad response when a higher-resolution collision\n  // field is available.\n\n  // Kill below water level or if dead\n  p.life -= params.deltaTime;\n  if (p.life <= 0.0 || newPos.y < -1.0) {\n    p.alive = 0.0;\n    particles[idx] = p;\n    return;\n  }\n\n  // Kill if too far from camera (squared distance)\n  let dx = newPos.x - params.cameraPos.x;\n  let dz = newPos.z - params.cameraPos.z;\n  if (dx * dx + dz * dz > 22500.0) {  // 150² — must be > spawnSpread²\n    p.alive = 0.0;\n    particles[idx] = p;\n    return;\n  }\n\n  p.posX = newPos.x;\n  p.posY = newPos.y;\n  p.posZ = newPos.z;\n\n  particles[idx] = p;\n}\n";
+const RENDER_WGSL = "struct RenderUniforms {\n  viewProj: mat4x4<f32>,\n  cameraPos: vec3<f32>,\n  time: f32,\n  particleCount: f32,\n  weatherType: f32,\n  aspect: f32,\n  focalLength: f32,\n  cullDistance: f32,\n};\n\n@group(0) @binding(0) var<uniform> uniforms: RenderUniforms;\n\nstruct VertexOutput {\n  @builtin(position) clipPos: vec4<f32>,\n  @location(0) color: vec3<f32>,\n  @location(1) uv: vec2<f32>,\n};\n\nstruct Particle {\n  posX: f32, posY: f32, posZ: f32,\n  velX: f32, velY: f32, velZ: f32,\n  life: f32, size: f32,\n  colorR: f32, colorG: f32, colorB: f32,\n  alive: f32,\n};\n\n@group(0) @binding(1) var<storage, read> particles: array<Particle>;\n\n@vertex\nfn vs_main(@builtin(vertex_index) vid: u32) -> VertexOutput {\n  var output: VertexOutput;\n\n  let particleIdx = vid / 6u;\n  if (particleIdx >= u32(uniforms.particleCount)) {\n    output.clipPos = vec4<f32>(0.0, 0.0, 2.0, 1.0);\n    output.color = vec3<f32>(0.0);\n    output.uv = vec2<f32>(0.0);\n    return output;\n  }\n\n  let p = particles[particleIdx];\n  if (p.alive < 0.5) {\n    output.clipPos = vec4<f32>(0.0, 0.0, 2.0, 1.0);\n    output.color = vec3<f32>(0.0);\n    output.uv = vec2<f32>(0.0);\n    return output;\n  }\n\n  // Quad corner offsets: 2 triangles (0,1,2) and (0,2,3)\n  var cornerX = array<f32, 6>(-1.0, 1.0, 1.0, -1.0, 1.0, -1.0);\n  var cornerY = array<f32, 6>(-1.0, -1.0, 1.0, -1.0, 1.0, 1.0);\n  let cx = cornerX[vid % 6u];\n  let cy = cornerY[vid % 6u];\n\n  // Project center to clip space\n  let center = uniforms.viewProj * vec4<f32>(vec3<f32>(p.posX, p.posY, p.posZ), 1.0);\n\n  // Cull if particle is too close in view space (center.w = distance along view dir)\n  if (center.w < uniforms.cullDistance) {\n    output.clipPos = vec4<f32>(0.0, 0.0, 2.0, 1.0);\n    output.color = vec3<f32>(0.0);\n    output.uv = vec2<f32>(0.0);\n    return output;\n  }\n\n  // Fade size based on life (full at start, shrinks near death)\n  let lifeRatio = clamp(p.life / 4.0, 0.0, 1.0);\n  let fadedSize = p.size * min(1.0, lifeRatio * 2.0);\n\n  // Rain: streak shape — thin horizontal, elongated vertical based on velocity\n  // Snow: round billboard\n  let isSnow = u32(uniforms.weatherType) == 9u;\n  let speed = length(vec3<f32>(p.velX, p.velY, p.velZ));\n\n  let halfW = select(fadedSize * 0.3, fadedSize * 0.5, isSnow);\n  let halfH = select(fadedSize * 0.5 + speed * 0.06, fadedSize * 0.5, isSnow);\n\n  let offsetX = cx * halfW * uniforms.focalLength / center.w / uniforms.aspect;\n  let offsetY = cy * halfH * uniforms.focalLength / center.w;\n\n  output.clipPos = vec4<f32>(center.x + offsetX, center.y + offsetY, center.z, center.w);\n  output.color = vec3<f32>(p.colorR, p.colorG, p.colorB);\n  output.uv = vec2<f32>(cx, cy);\n\n  return output;\n}\n\n@fragment\nfn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {\n  let dist = length(input.uv);\n  if (dist > 1.0) { discard; }\n  let alpha = (1.0 - dist * dist) * 0.8;\n  return vec4<f32>(input.color, alpha);\n}\n";
+// --- Typed uniform structs (validate against particle-compute.wgsl / particle-render.wgsl) ---
+export const SimParamsStruct = wgsl.struct("SimParams", {
+    deltaTime: wgsl.f32,
+    time: wgsl.f32,
+    spawnCount: wgsl.f32,
+    maxParticles: wgsl.f32,
+    cursor: wgsl.f32,
+    weatherType: wgsl.f32,
+    isSnow: wgsl.f32,
+    _pad0: wgsl.f32,
+    cameraPos: wgsl.vec3f,
+    collisionRadius: wgsl.f32,
+    spawnSpread: wgsl.f32,
+    spawnHeight: wgsl.f32,
+    baseVelY: wgsl.f32,
+    particleSize: wgsl.f32,
+    lifetime: wgsl.f32,
+    colorR: wgsl.f32,
+    colorG: wgsl.f32,
+    colorB: wgsl.f32,
+    windX: wgsl.f32,
+    windZ: wgsl.f32,
+    _pad1: wgsl.f32,
+    _pad2: wgsl.f32,
+    voxelOrigin: wgsl.vec3f,
+    voxelSize: wgsl.f32,
+    voxelDimX: wgsl.f32,
+    voxelDimY: wgsl.f32,
+    voxelDimZ: wgsl.f32,
+    voxelCount: wgsl.f32,
+    isoLevel: wgsl.f32,
+    seed: wgsl.f32,
+});
+export const RenderUniformsStruct = wgsl.struct("RenderUniforms", {
+    viewProj: wgsl.mat4x4f,
+    cameraPos: wgsl.vec3f,
+    time: wgsl.f32,
+    particleCount: wgsl.f32,
+    weatherType: wgsl.f32,
+    aspect: wgsl.f32,
+    focalLength: wgsl.f32,
+    cullDistance: wgsl.f32,
+});
+// --- Particle layout (12 floats = 48 bytes per particle) ---
+// posX, posY, posZ, velX, velY, velZ, life, size, colorR, colorG, colorB, alive
+const MAX_PARTICLES = 20000;
+const PARTICLE_FLOATS = 12;
+const PARTICLE_BYTES = PARTICLE_FLOATS * 4;
+// Voxel collision buffer: packed density values for nearby terrain
+export const MAX_VOXEL_FLOATS = 32768 * 4; // ~128KB — covers ~32³ voxels at 4 bytes each
+export const COLLISION_RADIUS = 30.0; // world units
+function getWeatherParams(weatherType) {
+    switch (weatherType) {
+        case WeatherType.Rain:
+            return { spawnRate: 4000, velY: -18, size: 0.3, color: [0.6, 0.7, 0.9], lifetime: 4, spread: 50, heightRange: 25, isSnow: false };
+        case WeatherType.Storm:
+            return { spawnRate: 8000, velY: -28, size: 0.4, color: [0.5, 0.6, 0.85], lifetime: 3, spread: 60, heightRange: 30, isSnow: false };
+        case WeatherType.HellStorm:
+            return { spawnRate: 2000, velY: -22, size: 0.5, color: [0.8, 0.2, 0.1], lifetime: 3, spread: 55, heightRange: 28, isSnow: false };
+        case WeatherType.Snow:
+            return { spawnRate: 4000, velY: -5, size: 0.4, color: [0.9, 0.9, 1.0], lifetime: 12, spread: 40, heightRange: 8, isSnow: true };
+        default:
+            return null;
+    }
+}
+// ============================================================================
+// WeatherParticleSystem — GPU compute particle system with LOD collision
+// ============================================================================
+export class ParticleSystem {
+    device;
+    format;
+    // Compute pipelines (one for emit, one for update — same bind group, different entry points)
+    computePipeline = null;
+    emitPipeline = null;
+    computeBindGroup = null;
+    computeBindGroupLayout = null;
+    // Render pipeline
+    renderPipeline = null;
+    renderBindGroup = null;
+    renderBindGroupLayout = null;
+    // Buffers
+    particleBuffer = null;
+    simParamBuffer = null;
+    counterBuffer = null;
+    voxelBuffer = null;
+    renderUniformBuffer = null;
+    // State
+    cursor = 0;
+    activeCount = 0;
+    seed = 12345;
+    currentVoxelCount = 0;
+    spawnAccumulator = 0;
+    particleDensityMultiplier = 1.0;
+    particleCullDistance = 5.0;
+    // Pooled CPU buffers
+    _simParamView = null;
+    _simParamBuf = null;
+    counterData;
+    _renderUniformView = null;
+    _renderUniformBuf = null;
+    constructor(device, format) {
+        this.device = device;
+        this.format = format;
+        this._simParamBuf = new Float32Array(64); // padded to 256 bytes
+        this._simParamView = SimParamsStruct.view(this._simParamBuf);
+        this.counterData = new Uint32Array(2);
+        this._renderUniformBuf = new Float32Array(RenderUniformsStruct.floatCount);
+        this._renderUniformView = RenderUniformsStruct.view(this._renderUniformBuf);
+    }
+    async init() {
+        const dev = this.device;
+        const computeModule = createValidatedShaderModule(dev, { code: COMPUTE_WGSL, label: "WeatherFx.particleCompute" });
+        const renderModule = createValidatedShaderModule(dev, { code: RENDER_WGSL, label: "WeatherFx.particleRender" });
+        // --- Buffers ---
+        this.particleBuffer = dev.createBuffer({
+            size: MAX_PARTICLES * PARTICLE_BYTES,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        this.simParamBuffer = dev.createBuffer({
+            size: 256,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.counterBuffer = dev.createBuffer({
+            size: 8,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+        });
+        this.voxelBuffer = dev.createBuffer({
+            size: MAX_VOXEL_FLOATS * 4,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        this.renderUniformBuffer = dev.createBuffer({
+            size: 256,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        // Zero out particle buffer and counter
+        dev.queue.writeBuffer(this.particleBuffer, 0, new Float32Array(MAX_PARTICLES * PARTICLE_FLOATS));
+        dev.queue.writeBuffer(this.counterBuffer, 0, new Uint32Array([0, 0]));
+        // --- Compute pipeline ---
+        this.computeBindGroupLayout = dev.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
+                { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: "uniform" } },
+                { binding: 2, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
+                { binding: 3, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage" } },
+            ],
+        });
+        this.computeBindGroup = dev.createBindGroup({
+            layout: this.computeBindGroupLayout,
+            entries: [
+                { binding: 0, resource: { buffer: this.particleBuffer } },
+                { binding: 1, resource: { buffer: this.simParamBuffer } },
+                { binding: 2, resource: { buffer: this.counterBuffer } },
+                { binding: 3, resource: { buffer: this.voxelBuffer } },
+            ],
+        });
+        this.computePipeline = dev.createComputePipeline({
+            layout: dev.createPipelineLayout({ bindGroupLayouts: [this.computeBindGroupLayout] }),
+            compute: { module: computeModule, entryPoint: "cs_update" },
+        });
+        this.emitPipeline = dev.createComputePipeline({
+            layout: dev.createPipelineLayout({ bindGroupLayouts: [this.computeBindGroupLayout] }),
+            compute: { module: computeModule, entryPoint: "cs_emit" },
+        });
+        // --- Render pipeline ---
+        this.renderBindGroupLayout = dev.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+                { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+            ],
+        });
+        this.renderBindGroup = dev.createBindGroup({
+            layout: this.renderBindGroupLayout,
+            entries: [
+                { binding: 0, resource: { buffer: this.renderUniformBuffer } },
+                { binding: 1, resource: { buffer: this.particleBuffer } },
+            ],
+        });
+        this.renderPipeline = dev.createRenderPipeline({
+            layout: dev.createPipelineLayout({ bindGroupLayouts: [this.renderBindGroupLayout] }),
+            vertex: { module: renderModule, entryPoint: "vs_main", buffers: [] },
+            fragment: {
+                module: renderModule,
+                entryPoint: "fs_main",
+                targets: [{
+                        format: this.format,
+                        blend: {
+                            color: { srcFactor: "src-alpha", dstFactor: "one-minus-src-alpha", operation: "add" },
+                            alpha: { srcFactor: "src-alpha", dstFactor: "one-minus-src-alpha", operation: "add" },
+                        },
+                    }],
+            },
+            primitive: { topology: "triangle-list" },
+            multisample: { count: MSAA_SAMPLE_COUNT },
+            depthStencil: {
+                format: DEPTH_FORMAT,
+                depthWriteEnabled: false,
+                depthCompare: "less",
+            },
+        });
+    }
+    // Called each frame to update + spawn particles via compute shader
+    tick(encoder, dt, camera, weatherType, windX, windZ, voxelData) {
+        if (!this.computePipeline || !this.computeBindGroup)
+            return;
+        const params = getWeatherParams(weatherType);
+        this.seed = (this.seed * 1103515245 + 12345) & 0x7fffffff;
+        // Spawn rate is per-second; accumulate fractional spawns across frames
+        const baseSpawnRate = params ? params.spawnRate : 0;
+        const effectiveSpawnRate = baseSpawnRate * this.particleDensityMultiplier;
+        this.spawnAccumulator += effectiveSpawnRate * dt;
+        const spawnCount = Math.min(MAX_PARTICLES, Math.floor(this.spawnAccumulator));
+        this.spawnAccumulator -= spawnCount;
+        // Write sim params via typed view
+        const sp = this._simParamView;
+        this._simParamBuf.fill(0);
+        sp.set("deltaTime", dt);
+        sp.set("time", performance.now() / 1000);
+        sp.set("spawnCount", spawnCount);
+        sp.set("maxParticles", MAX_PARTICLES);
+        sp.set("cursor", this.cursor);
+        sp.set("weatherType", weatherType);
+        sp.set("isSnow", params ? (params.isSnow ? 1 : 0) : 0);
+        sp.set("cameraPos", camera.position);
+        sp.set("collisionRadius", COLLISION_RADIUS);
+        sp.set("spawnSpread", params ? params.spread : 50);
+        sp.set("spawnHeight", params ? params.heightRange : 25);
+        sp.set("baseVelY", params ? params.velY : -15);
+        sp.set("particleSize", params ? params.size : 0.05);
+        sp.set("lifetime", params ? params.lifetime : 4);
+        sp.set("colorR", params ? params.color[0] : 0.6);
+        sp.set("colorG", params ? params.color[1] : 0.7);
+        sp.set("colorB", params ? params.color[2] : 0.9);
+        sp.set("windX", windX);
+        sp.set("windZ", windZ);
+        if (voxelData && voxelData.data.length > 0) {
+            sp.set("voxelOrigin", [voxelData.originX, voxelData.originY, voxelData.originZ]);
+            sp.set("voxelSize", voxelData.voxelSize);
+            sp.set("voxelDimX", voxelData.dimX);
+            sp.set("voxelDimY", voxelData.dimY);
+            sp.set("voxelDimZ", voxelData.dimZ);
+            sp.set("voxelCount", voxelData.data.length);
+            sp.set("isoLevel", voxelData.isoLevel);
+        }
+        else {
+            sp.set("voxelOrigin", [0, 0, 0]);
+            sp.set("voxelSize", 1);
+            sp.set("voxelDimX", 0);
+            sp.set("voxelDimY", 0);
+            sp.set("voxelDimZ", 0);
+            sp.set("voxelCount", 0);
+            sp.set("isoLevel", 0);
+        }
+        sp.set("seed", this.seed);
+        this.device.queue.writeBuffer(this.simParamBuffer, 0, this._simParamBuf);
+        // Upload voxel data if present
+        if (voxelData && voxelData.data.length > 0 && voxelData.data.length <= MAX_VOXEL_FLOATS) {
+            let hasInvalid = false;
+            for (let i = 0; i < voxelData.data.length; i++) {
+                if (!Number.isFinite(voxelData.data[i])) {
+                    hasInvalid = true;
+                    break;
+                }
+            }
+            if (!hasInvalid) {
+                this.device.queue.writeBuffer(this.voxelBuffer, 0, voxelData.data);
+                this.currentVoxelCount = voxelData.data.length;
+            }
+            else {
+                this.currentVoxelCount = 0;
+            }
+        }
+        else {
+            this.currentVoxelCount = 0;
+        }
+        // Counter buffer is managed entirely on GPU via atomicAdd — do NOT reset from CPU
+        // (resetting would overwrite the GPU's cursor and cause particles to be written at index 0 every frame)
+        const pass = encoder.beginComputePass();
+        pass.setBindGroup(0, this.computeBindGroup);
+        // Emit
+        if (spawnCount > 0 && this.emitPipeline) {
+            pass.setPipeline(this.emitPipeline);
+            const emitWorkgroups = Math.ceil(spawnCount / 64);
+            pass.dispatchWorkgroups(emitWorkgroups);
+        }
+        // Update all particles
+        pass.setPipeline(this.computePipeline);
+        const updateWorkgroups = Math.ceil(MAX_PARTICLES / 64);
+        pass.dispatchWorkgroups(updateWorkgroups);
+        pass.end();
+    }
+    // Called during render pass to draw particles
+    render(passEncoder, camera, weatherType, timeOfDay) {
+        if (!this.renderPipeline || !this.renderBindGroup || !this.renderUniformBuffer)
+            return;
+        // Write render uniforms
+        const viewProj = calculateViewProj(camera);
+        const u = this._renderUniformView;
+        u.set("viewProj", viewProj);
+        u.set("cameraPos", camera.position);
+        u.set("time", performance.now() / 1000);
+        u.set("particleCount", MAX_PARTICLES);
+        u.set("weatherType", weatherType);
+        u.set("aspect", camera.aspect);
+        u.set("focalLength", 1 / Math.tan((camera.fov * Math.PI / 180) / 2));
+        u.set("cullDistance", this.particleCullDistance);
+        this.device.queue.writeBuffer(this.renderUniformBuffer, 0, this._renderUniformBuf);
+        passEncoder.setPipeline(this.renderPipeline);
+        passEncoder.setBindGroup(0, this.renderBindGroup);
+        passEncoder.draw(MAX_PARTICLES * 6);
+    }
+    destroy() {
+        this.particleBuffer?.destroy();
+        this.simParamBuffer?.destroy();
+        this.counterBuffer?.destroy();
+        this.voxelBuffer?.destroy();
+        this.renderUniformBuffer?.destroy();
+        this.particleBuffer = null;
+        this.simParamBuffer = null;
+        this.counterBuffer = null;
+        this.voxelBuffer = null;
+        this.renderUniformBuffer = null;
+        // Pipelines have .destroy() — call it before nulling.
+        this.computePipeline?.destroy();
+        this.emitPipeline?.destroy();
+        this.renderPipeline?.destroy();
+        this.computePipeline = null;
+        this.emitPipeline = null;
+        this.renderPipeline = null;
+        // GPUBindGroup and GPUBindGroupLayout have no destroy() — just null them.
+        this.computeBindGroup = null;
+        this.renderBindGroup = null;
+        this.computeBindGroupLayout = null;
+        this.renderBindGroupLayout = null;
+        this._simParamView = null;
+        this._simParamBuf = null;
+        this._renderUniformView = null;
+        this._renderUniformBuf = null;
+    }
+}

package/dist/libraries/weatherfx/src/shaders/cloud.wgsl

@@ -0,0 +1,111 @@
+struct CloudUniforms {
+  viewProj: mat4x4<f32>,
+  cameraPos: vec3<f32>,
+  timeOfDay: f32,
+  weatherType: u32,
+  sunDir: vec3<f32>,
+  sunIntensity: f32,
+  moonDir: vec3<f32>,
+  moonIntensity: f32,
+  time: f32,
+  weatherBlend: f32,
+  fogColor: vec3<f32>,
+  fogDensity: f32,
+};
+
+@group(0) @binding(0) var<uniform> uniforms: CloudUniforms;
+
+struct PerLayerUniforms {
+  layerPos: vec3<f32>,
+  _pad: f32,
+};
+
+@group(0) @binding(1) var<uniform> perLayer: PerLayerUniforms;
+
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+  @location(1) normal: vec3<f32>,
+  @location(2) color: vec3<f32>,
+};
+
+struct VertexOutput {
+  @builtin(position) clipPos: vec4<f32>,
+  @location(0) worldPos: vec3<f32>,
+  @location(1) normal: vec3<f32>,
+  @location(2) color: vec3<f32>,
+  @location(3) viewDist: f32,
+};
+
+@vertex
+fn vs_main(input: VertexInput) -> VertexOutput {
+  var output: VertexOutput;
+  let worldPos = input.position + perLayer.layerPos;
+  output.worldPos = worldPos;
+  output.clipPos = uniforms.viewProj * vec4<f32>(worldPos, 1.0);
+  output.normal = input.normal;
+  output.color = input.color;
+  output.viewDist = length(uniforms.cameraPos - worldPos);
+  return output;
+}
+
+fn weatherTint(weather: u32) -> vec3<f32> {
+  if (weather == 0u) { return vec3<f32>(1.0, 1.0, 1.0); }
+  if (weather == 1u) { return vec3<f32>(1.0, 1.0, 1.0); }
+  if (weather == 2u) { return vec3<f32>(0.7, 0.7, 0.72); }
+  if (weather == 3u) { return vec3<f32>(0.55, 0.55, 0.58); }
+  if (weather == 4u) { return vec3<f32>(0.25, 0.25, 0.30); }
+  if (weather == 5u) { return vec3<f32>(0.6, 0.6, 0.62); }
+  if (weather == 8u) { return vec3<f32>(0.4, 0.15, 0.08); }
+  if (weather == 9u) { return vec3<f32>(0.85, 0.88, 0.92); }
+  return vec3<f32>(1.0, 1.0, 1.0);
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  let N = normalize(input.normal);
+  let baseColor = input.color;
+
+  let sunDir = normalize(uniforms.sunDir);
+  let moonDir = normalize(uniforms.moonDir);
+  let sunNdotL = max(dot(N, sunDir), 0.0);
+  let moonNdotL = max(dot(N, moonDir), 0.0);
+
+  let dayFactor = smoothstep(0.2, 0.4, uniforms.timeOfDay) * (1.0 - smoothstep(0.65, 0.8, uniforms.timeOfDay));
+  let sunsetFactor = smoothstep(0.15, 0.25, uniforms.timeOfDay) * (1.0 - smoothstep(0.25, 0.35, uniforms.timeOfDay))
+    + smoothstep(0.65, 0.75, uniforms.timeOfDay) * (1.0 - smoothstep(0.75, 0.85, uniforms.timeOfDay));
+
+  let sunColor = mix(vec3<f32>(1.0, 0.6, 0.3), vec3<f32>(1.0, 0.97, 0.9), dayFactor);
+  let moonColor = vec3<f32>(0.7, 0.7, 0.75);
+
+  let sunLight = sunColor * sunNdotL * uniforms.sunIntensity;
+  let moonLight = moonColor * moonNdotL * uniforms.moonIntensity;
+  let ambient = vec3<f32>(0.45, 0.45, 0.47) * (0.4 + dayFactor * 0.4);
+
+  // Bounce light for underside
+  let bottomFactor = max(-N.y, 0.0);
+  let bounceColor = mix(vec3<f32>(0.8, 0.82, 0.85), vec3<f32>(1.0, 0.9, 0.75), dayFactor);
+  let bounce = bounceColor * bottomFactor * (0.3 + dayFactor * 0.3);
+
+  var litColor = baseColor * (sunLight + moonLight + ambient + bounce);
+
+  // Sunset tint
+  litColor = mix(litColor, litColor * vec3<f32>(1.0, 0.6, 0.4), sunsetFactor * 0.4);
+
+  // Weather tinting
+  let tint = weatherTint(uniforms.weatherType);
+  litColor = mix(litColor, litColor * tint, 0.5);
+
+  // Soft alpha
+  let V = normalize(uniforms.cameraPos - input.worldPos);
+  let NdotV = max(dot(N, V), 0.0);
+  let edgeAlpha = smoothstep(0.0, 0.15, NdotV);
+  let distFade = 1.0 - smoothstep(2000.0, 4000.0, input.viewDist);
+  let baseAlpha = 0.65 + 0.3 * NdotV;
+  let alpha = baseAlpha * edgeAlpha * distFade;
+
+  // Distance fog
+  let fogFactor = 1.0 - exp(-uniforms.fogDensity * input.viewDist);
+  litColor = mix(litColor, uniforms.fogColor, fogFactor * 0.5);
+
+  return vec4<f32>(litColor, alpha);
+}

package/dist/libraries/weatherfx/src/shaders/particle-compute.wgsl

@@ -0,0 +1,187 @@
+struct Particle {
+  posX: f32, posY: f32, posZ: f32,
+  velX: f32, velY: f32, velZ: f32,
+  life: f32, size: f32,
+  colorR: f32, colorG: f32, colorB: f32,
+  alive: f32,
+};
+
+struct SimParams {
+  deltaTime: f32,
+  time: f32,
+  spawnCount: f32,
+  maxParticles: f32,
+  cursor: f32,
+  weatherType: f32,
+  isSnow: f32,
+  _pad0: f32,
+  cameraPos: vec3<f32>,
+  collisionRadius: f32,
+  spawnSpread: f32,
+  spawnHeight: f32,
+  baseVelY: f32,
+  particleSize: f32,
+  lifetime: f32,
+  colorR: f32, colorG: f32, colorB: f32,
+  windX: f32, windZ: f32,
+  _pad1: f32, _pad2: f32,
+  voxelOrigin: vec3<f32>,
+  voxelSize: f32,
+  voxelDimX: f32, voxelDimY: f32, voxelDimZ: f32,
+  voxelCount: f32,
+  isoLevel: f32,
+  seed: f32,
+};
+
+struct Counter {
+  cursor: atomic<u32>,
+  activeCount: atomic<u32>,
+};
+
+@group(0) @binding(0) var<storage, read_write> particles: array<Particle>;
+@group(0) @binding(1) var<uniform> params: SimParams;
+@group(0) @binding(2) var<storage, read_write> counter: Counter;
+@group(0) @binding(3) var<storage, read> voxelData: array<f32>;
+
+fn hash(seed: ptr<function, u32>) -> f32 {
+  *seed = *seed * 1103515245u + 12345u;
+  return f32(*seed) / 4294967296.0;
+}
+
+fn randRange(seed: ptr<function, u32>, min: f32, max: f32) -> f32 {
+  return min + hash(seed) * (max - min);
+}
+
+fn sampleVoxel(x: i32, y: i32, z: i32) -> f32 {
+  if (x < 0 || x >= i32(params.voxelDimX) ||
+      y < 0 || y >= i32(params.voxelDimY) ||
+      z < 0 || z >= i32(params.voxelDimZ)) {
+    return -1.0;
+  }
+  let idx = u32(x) * u32(params.voxelDimY) * u32(params.voxelDimZ) + u32(y) * u32(params.voxelDimZ) + u32(z);
+  if (idx >= u32(params.voxelCount)) { return -1.0; }
+  return voxelData[idx];
+}
+
+fn sampleVoxelGrad(p: vec3<f32>) -> vec3<f32> {
+  let vs = params.voxelSize;
+  let ox = params.voxelOrigin.x;
+  let oy = params.voxelOrigin.y;
+  let oz = params.voxelOrigin.z;
+  let vx = i32(floor((p.x - ox) / vs));
+  let vy = i32(floor((p.y - oy) / vs));
+  let vz = i32(floor((p.z - oz) / vs));
+  let dx = sampleVoxel(vx + 1, vy, vz) - sampleVoxel(vx - 1, vy, vz);
+  let dy = sampleVoxel(vx, vy + 1, vz) - sampleVoxel(vx, vy - 1, vz);
+  let dz = sampleVoxel(vx, vy, vz + 1) - sampleVoxel(vx, vy, vz - 1);
+  let n = vec3<f32>(dx, dy, dz);
+  let len = length(n);
+  if (len < 1e-6) { return vec3<f32>(0.0, 1.0, 0.0); }
+  return n / len;
+}
+
+fn voxelDensityAt(p: vec3<f32>) -> f32 {
+  let vs = params.voxelSize;
+  let ox = params.voxelOrigin.x;
+  let oy = params.voxelOrigin.y;
+  let oz = params.voxelOrigin.z;
+  let vx = i32(floor((p.x - ox) / vs));
+  let vy = i32(floor((p.y - oy) / vs));
+  let vz = i32(floor((p.z - oz) / vs));
+  return sampleVoxel(vx, vy, vz);
+}
+
+@compute @workgroup_size(64)
+fn cs_emit(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let idx = gid.x;
+  if (idx >= u32(params.spawnCount)) { return; }
+
+  let cursor = atomicAdd(&counter.cursor, 1u) % u32(params.maxParticles);
+  var seed = u32(params.seed) + idx * 7919u + u32(params.time * 1000.0);
+
+  let px = params.cameraPos.x + randRange(&seed, -params.spawnSpread, params.spawnSpread);
+  let py = params.cameraPos.y + params.spawnHeight + randRange(&seed, 0.0, params.spawnHeight * 0.3);
+  let pz = params.cameraPos.z + randRange(&seed, -params.spawnSpread, params.spawnSpread);
+
+  let vx = params.windX + randRange(&seed, -2.0, 2.0);
+  let vy = params.baseVelY + randRange(&seed, -3.0, 3.0);
+  let vz = params.windZ + randRange(&seed, -2.0, 2.0);
+
+  particles[cursor].posX = px;
+  particles[cursor].posY = py;
+  particles[cursor].posZ = pz;
+  particles[cursor].velX = vx;
+  particles[cursor].velY = vy;
+  particles[cursor].velZ = vz;
+  particles[cursor].life = params.lifetime + randRange(&seed, -0.5, 0.5);
+  particles[cursor].size = params.particleSize;
+  particles[cursor].colorR = params.colorR;
+  particles[cursor].colorG = params.colorG;
+  particles[cursor].colorB = params.colorB;
+  particles[cursor].alive = 1.0;
+}
+
+@compute @workgroup_size(64)
+fn cs_update(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let idx = gid.x;
+  if (idx >= u32(params.maxParticles)) { return; }
+
+  if (particles[idx].alive < 0.5) { return; }
+
+  var p = particles[idx];
+
+  // Apply gravity (snow has gentler fall)
+  let gravity = select(-30.0, -3.0, u32(params.isSnow) == 1u);
+  p.velY += gravity * params.deltaTime;
+
+  // Apply wind
+  p.velX += params.windX * params.deltaTime * 0.5;
+  p.velZ += params.windZ * params.deltaTime * 0.5;
+
+  // Snow: add gentle sway
+  if (u32(params.isSnow) == 1u) {
+    let swayPhase = params.time * 2.0 + f32(idx) * 0.1;
+    p.velX += sin(swayPhase) * 0.5 * params.deltaTime;
+    p.velZ += cos(swayPhase * 0.7) * 0.5 * params.deltaTime;
+  }
+
+  // Drag — frame-rate independent: pow(perFrameDrag, dt*60) = exp(log(drag)*dt*60)
+  let dragRate = select(log(0.99) * 60.0, log(0.98) * 60.0, u32(params.isSnow) == 1u);
+  let dragMul = exp(dragRate * params.deltaTime);
+  p.velX *= dragMul;
+  p.velY *= dragMul;
+  p.velZ *= dragMul;
+
+  // Compute new position
+  var newPos = vec3<f32>(p.posX, p.posY, p.posZ) + vec3<f32>(p.velX, p.velY, p.velZ) * params.deltaTime;
+
+  // Voxel collision is disabled: the 6-tap gradient sampling caused premature
+  // particle death due to inaccurate surface normal estimation at the voxel
+  // resolution used for weather LOD. Particles now fall through terrain and are
+  // killed by the life/distance checks below. Re-enable by restoring the
+  // density check + sampleVoxelGrad response when a higher-resolution collision
+  // field is available.
+
+  // Kill below water level or if dead
+  p.life -= params.deltaTime;
+  if (p.life <= 0.0 || newPos.y < -1.0) {
+    p.alive = 0.0;
+    particles[idx] = p;
+    return;
+  }
+
+  // Kill if too far from camera (squared distance)
+  let dx = newPos.x - params.cameraPos.x;
+  let dz = newPos.z - params.cameraPos.z;
+  if (dx * dx + dz * dz > 22500.0) {  // 150² — must be > spawnSpread²
+    p.alive = 0.0;
+    particles[idx] = p;
+    return;
+  }
+
+  p.posX = newPos.x;
+  p.posY = newPos.y;
+  p.posZ = newPos.z;
+
+  particles[idx] = p;
+}