@downdraft/engine 0.1.1 → 0.1.2-alpha.5

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

@@ -0,0 +1,294 @@
+// ============================================================================
+// CloudSystem — renders continuous cloud layers as low-poly marching cubes meshes
+// Each layer is a single large voxel field sampled from world-space Perlin noise.
+// Layers scroll with the player and drift with wind.
+// ============================================================================
+import { calculateViewProj, createLogger, createValidatedShaderModule, DEPTH_FORMAT, MSAA_SAMPLE_COUNT } from "@downdraft/engine";
+import { wgsl } from "@downdraft/engine/shader-graph";
+const CLOUD_WGSL = "struct CloudUniforms {\n  viewProj: mat4x4<f32>,\n  cameraPos: vec3<f32>,\n  timeOfDay: f32,\n  weatherType: u32,\n  sunDir: vec3<f32>,\n  sunIntensity: f32,\n  moonDir: vec3<f32>,\n  moonIntensity: f32,\n  time: f32,\n  weatherBlend: f32,\n  fogColor: vec3<f32>,\n  fogDensity: f32,\n};\n\n@group(0) @binding(0) var<uniform> uniforms: CloudUniforms;\n\nstruct PerLayerUniforms {\n  layerPos: vec3<f32>,\n  _pad: f32,\n};\n\n@group(0) @binding(1) var<uniform> perLayer: PerLayerUniforms;\n\nstruct VertexInput {\n  @location(0) position: vec3<f32>,\n  @location(1) normal: vec3<f32>,\n  @location(2) color: vec3<f32>,\n};\n\nstruct VertexOutput {\n  @builtin(position) clipPos: vec4<f32>,\n  @location(0) worldPos: vec3<f32>,\n  @location(1) normal: vec3<f32>,\n  @location(2) color: vec3<f32>,\n  @location(3) viewDist: f32,\n};\n\n@vertex\nfn vs_main(input: VertexInput) -> VertexOutput {\n  var output: VertexOutput;\n  let worldPos = input.position + perLayer.layerPos;\n  output.worldPos = worldPos;\n  output.clipPos = uniforms.viewProj * vec4<f32>(worldPos, 1.0);\n  output.normal = input.normal;\n  output.color = input.color;\n  output.viewDist = length(uniforms.cameraPos - worldPos);\n  return output;\n}\n\nfn weatherTint(weather: u32) -> vec3<f32> {\n  if (weather == 0u) { return vec3<f32>(1.0, 1.0, 1.0); }\n  if (weather == 1u) { return vec3<f32>(1.0, 1.0, 1.0); }\n  if (weather == 2u) { return vec3<f32>(0.7, 0.7, 0.72); }\n  if (weather == 3u) { return vec3<f32>(0.55, 0.55, 0.58); }\n  if (weather == 4u) { return vec3<f32>(0.25, 0.25, 0.30); }\n  if (weather == 5u) { return vec3<f32>(0.6, 0.6, 0.62); }\n  if (weather == 8u) { return vec3<f32>(0.4, 0.15, 0.08); }\n  if (weather == 9u) { return vec3<f32>(0.85, 0.88, 0.92); }\n  return vec3<f32>(1.0, 1.0, 1.0);\n}\n\n@fragment\nfn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {\n  let N = normalize(input.normal);\n  let baseColor = input.color;\n\n  let sunDir = normalize(uniforms.sunDir);\n  let moonDir = normalize(uniforms.moonDir);\n  let sunNdotL = max(dot(N, sunDir), 0.0);\n  let moonNdotL = max(dot(N, moonDir), 0.0);\n\n  let dayFactor = smoothstep(0.2, 0.4, uniforms.timeOfDay) * (1.0 - smoothstep(0.65, 0.8, uniforms.timeOfDay));\n  let sunsetFactor = smoothstep(0.15, 0.25, uniforms.timeOfDay) * (1.0 - smoothstep(0.25, 0.35, uniforms.timeOfDay))\n    + smoothstep(0.65, 0.75, uniforms.timeOfDay) * (1.0 - smoothstep(0.75, 0.85, uniforms.timeOfDay));\n\n  let sunColor = mix(vec3<f32>(1.0, 0.6, 0.3), vec3<f32>(1.0, 0.97, 0.9), dayFactor);\n  let moonColor = vec3<f32>(0.7, 0.7, 0.75);\n\n  let sunLight = sunColor * sunNdotL * uniforms.sunIntensity;\n  let moonLight = moonColor * moonNdotL * uniforms.moonIntensity;\n  let ambient = vec3<f32>(0.45, 0.45, 0.47) * (0.4 + dayFactor * 0.4);\n\n  // Bounce light for underside\n  let bottomFactor = max(-N.y, 0.0);\n  let bounceColor = mix(vec3<f32>(0.8, 0.82, 0.85), vec3<f32>(1.0, 0.9, 0.75), dayFactor);\n  let bounce = bounceColor * bottomFactor * (0.3 + dayFactor * 0.3);\n\n  var litColor = baseColor * (sunLight + moonLight + ambient + bounce);\n\n  // Sunset tint\n  litColor = mix(litColor, litColor * vec3<f32>(1.0, 0.6, 0.4), sunsetFactor * 0.4);\n\n  // Weather tinting\n  let tint = weatherTint(uniforms.weatherType);\n  litColor = mix(litColor, litColor * tint, 0.5);\n\n  // Soft alpha\n  let V = normalize(uniforms.cameraPos - input.worldPos);\n  let NdotV = max(dot(N, V), 0.0);\n  let edgeAlpha = smoothstep(0.0, 0.15, NdotV);\n  let distFade = 1.0 - smoothstep(2000.0, 4000.0, input.viewDist);\n  let baseAlpha = 0.65 + 0.3 * NdotV;\n  let alpha = baseAlpha * edgeAlpha * distFade;\n\n  // Distance fog\n  let fogFactor = 1.0 - exp(-uniforms.fogDensity * input.viewDist);\n  litColor = mix(litColor, uniforms.fogColor, fogFactor * 0.5);\n\n  return vec4<f32>(litColor, alpha);\n}\n";
+const log = createLogger();
+// --- Typed uniform structs (validate against cloud.wgsl) ---
+export const CloudUniformsStruct = wgsl.struct("CloudUniforms", {
+    viewProj: wgsl.mat4x4f,
+    cameraPos: wgsl.vec3f,
+    timeOfDay: wgsl.f32,
+    weatherType: wgsl.u32,
+    sunDir: wgsl.vec3f,
+    sunIntensity: wgsl.f32,
+    moonDir: wgsl.vec3f,
+    moonIntensity: wgsl.f32,
+    time: wgsl.f32,
+    weatherBlend: wgsl.f32,
+    fogColor: wgsl.vec3f,
+    fogDensity: wgsl.f32,
+});
+export const PerLayerUniformsStruct = wgsl.struct("PerLayerUniforms", {
+    layerPos: wgsl.vec3f,
+    _pad: wgsl.f32,
+});
+export class CloudSystem {
+    device;
+    format;
+    provider;
+    pipeline = null;
+    bindGroupLayout = null;
+    uniformBuffer = null;
+    layers = [];
+    genThisFrame = 0;
+    _uniformView = null;
+    _uniformBuf = null;
+    _perLayerView = null;
+    _perLayerBuf = null;
+    constructor(device, format, provider) {
+        this.device = device;
+        this.format = format;
+        this.provider = provider;
+    }
+    async init() {
+        this._uniformBuf = new Float32Array(CloudUniformsStruct.floatCount);
+        this._uniformView = CloudUniformsStruct.view(this._uniformBuf);
+        this._perLayerBuf = new Float32Array(PerLayerUniformsStruct.floatCount);
+        this._perLayerView = PerLayerUniformsStruct.view(this._perLayerBuf);
+        this.uniformBuffer = this.device.createBuffer({
+            size: 256,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.bindGroupLayout = this.device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+                { binding: 1, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform", hasDynamicOffset: true } },
+            ],
+        });
+        const pipelineLayout = this.device.createPipelineLayout({
+            bindGroupLayouts: [this.bindGroupLayout],
+        });
+        const shaderModule = createValidatedShaderModule(this.device, { code: CLOUD_WGSL, label: "WeatherFx.cloud" });
+        this.pipeline = this.device.createRenderPipeline({
+            layout: pipelineLayout,
+            vertex: {
+                module: shaderModule,
+                entryPoint: "vs_main",
+                buffers: [{
+                        arrayStride: 36,
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: "float32x3" },
+                            { shaderLocation: 1, offset: 12, format: "float32x3" },
+                            { shaderLocation: 2, offset: 24, format: "float32x3" },
+                        ],
+                    }],
+            },
+            fragment: {
+                module: shaderModule,
+                entryPoint: "fs_main",
+                targets: [{
+                        format: this.format,
+                        blend: {
+                            color: { srcFactor: "src-alpha", dstFactor: "one-minus-src-alpha", operation: "add" },
+                            alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+                        },
+                    }],
+            },
+            primitive: { topology: "triangle-list" },
+            multisample: { count: MSAA_SAMPLE_COUNT },
+            depthStencil: {
+                format: DEPTH_FORMAT,
+                depthWriteEnabled: false,
+                depthCompare: "less-equal",
+            },
+        });
+        // Initialize cloud layers from provider
+        const layerTypes = this.provider.getLayerTypes();
+        layerTypes.forEach((layerType) => {
+            const cfg = this.provider.getLayerConfig(layerType);
+            this.layers.push({
+                layerType,
+                vertexBuffer: null,
+                indexBuffer: null,
+                indexCount: 0,
+                useUint32: false,
+                perLayerUniform: this.device.createBuffer({
+                    size: 16,
+                    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+                }),
+                bindGroup: null,
+                centerX: 0,
+                centerZ: 0,
+                altitude: cfg.altitude,
+                windOffsetX: 0,
+                windOffsetZ: 0,
+                generated: false,
+                genCenterX: 0,
+                genCenterZ: 0,
+                pendingRegen: true,
+            });
+        });
+        log.info("cloud-system", `Initialized with ${this.layers.length} layers`);
+    }
+    update(dt, playerPos, windDirX, windDirZ, windSpeed, weatherType) {
+        this.genThisFrame = 0;
+        this.layers.forEach((layer) => {
+            // Accumulate wind drift
+            layer.windOffsetX += windDirX * windSpeed * dt;
+            layer.windOffsetZ += windDirZ * windSpeed * dt;
+            // Update center to follow player
+            layer.centerX = playerPos.x;
+            layer.centerZ = playerPos.z;
+            // Check if we need to regenerate (player moved too far from last gen center)
+            const dx = layer.centerX - layer.genCenterX;
+            const dz = layer.centerZ - layer.genCenterZ;
+            const distSq = dx * dx + dz * dz;
+            const regenDist = this.provider.getRegenDistance();
+            if (!layer.generated || distSq > regenDist * regenDist) {
+                layer.pendingRegen = true;
+            }
+        });
+        // Process pending layer generation (one at a time for performance)
+        this.processPendingGen(weatherType);
+    }
+    processPendingGen(weatherType) {
+        const maxPerFrame = this.provider.getMaxLayerGenPerFrame();
+        const budgetMs = this.provider.getLayerGenTimeBudgetMs();
+        const startTime = performance.now();
+        for (let _i = 0, _it = this.layers, _n = _it.length; _i < _n; _i++) {
+            const layer = _it[_i];
+            if (!layer.pendingRegen)
+                continue;
+            if (this.genThisFrame >= maxPerFrame)
+                break;
+            if (performance.now() - startTime > budgetMs)
+                break;
+            this.generateLayerMesh(layer, weatherType);
+            layer.pendingRegen = false;
+            layer.generated = true;
+            layer.genCenterX = layer.centerX;
+            layer.genCenterZ = layer.centerZ;
+            this.genThisFrame++;
+        }
+    }
+    generateLayerMesh(layer, weatherType) {
+        const field = this.provider.generateLayerField(layer.layerType, layer.centerX, layer.centerZ, weatherType, layer.windOffsetX, layer.windOffsetZ);
+        const extracted = this.provider.extractMesh(field);
+        if (extracted.verts.length === 0 || extracted.indices.length === 0) {
+            let minD = Infinity, maxD = -Infinity, solidCount = 0;
+            for (let i = 0; i < field.data.length; i++) {
+                const v = field.data[i];
+                if (v < minD)
+                    minD = v;
+                if (v > maxD)
+                    maxD = v;
+                if (v < field.isoLevel)
+                    solidCount++;
+            }
+            log.warn("cloud-system", `Empty mesh for layer=${layer.layerType} iso=${field.isoLevel} densityRange=[${minD.toFixed(3)}, ${maxD.toFixed(3)}] solidVoxels=${solidCount}/${field.data.length} (${(solidCount / field.data.length * 100).toFixed(1)}%)`);
+            return;
+        }
+        log.info("cloud-system", `Generated layer ${layer.layerType}: ${extracted.verts.length / 9} verts, ${extracted.indices.length} indices`);
+        // Vertices are in world space relative to field origin (centered at 0,0,0)
+        const verts = extracted.verts;
+        // Dispose old buffers
+        if (layer.vertexBuffer) {
+            layer.vertexBuffer.destroy();
+            layer.vertexBuffer = null;
+        }
+        if (layer.indexBuffer) {
+            layer.indexBuffer.destroy();
+            layer.indexBuffer = null;
+        }
+        // Create vertex buffer
+        layer.vertexBuffer = this.device.createBuffer({
+            size: verts.byteLength,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        this.device.queue.writeBuffer(layer.vertexBuffer, 0, verts);
+        // Create index buffer
+        const indexBuf = extracted.indices;
+        let indexData;
+        if (!extracted.useUint32 && indexBuf instanceof Uint16Array && indexBuf.length % 2 !== 0) {
+            indexData = new Uint16Array(indexBuf.length + 1);
+            indexData.set(indexBuf);
+        }
+        else {
+            indexData = indexBuf;
+        }
+        layer.indexBuffer = this.device.createBuffer({
+            size: indexData.byteLength,
+            usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+        });
+        this.device.queue.writeBuffer(layer.indexBuffer, 0, indexData);
+        layer.indexCount = indexBuf.length;
+        layer.useUint32 = extracted.useUint32;
+        // Create bind group
+        layer.bindGroup = this.device.createBindGroup({
+            layout: this.bindGroupLayout,
+            entries: [
+                { binding: 0, resource: { buffer: this.uniformBuffer } },
+                { binding: 1, resource: { buffer: layer.perLayerUniform, size: 16 } },
+            ],
+        });
+    }
+    render(passEncoder, camera, timeOfDay, weatherType, _windSpeed, _windDirX, _windDirZ, elapsedTime, _playerPos, sunDir, sunIntensity, moonDir, moonIntensity, fogColor, fogDensity) {
+        if (!this.pipeline || !this.uniformBuffer || !this._uniformView || !this._uniformBuf)
+            return;
+        const viewProj = calculateViewProj(camera);
+        const v = this._uniformView;
+        // Write main uniforms via typed view
+        v.set("viewProj", viewProj);
+        v.set("cameraPos", camera.position);
+        v.set("timeOfDay", timeOfDay);
+        v.setU32("weatherType", weatherType);
+        v.set("sunDir", sunDir);
+        v.set("sunIntensity", sunIntensity);
+        v.set("moonDir", moonDir);
+        v.set("moonIntensity", moonIntensity);
+        v.set("time", elapsedTime);
+        v.set("weatherBlend", 1.0);
+        v.set("fogColor", fogColor);
+        v.set("fogDensity", fogDensity);
+        this.device.queue.writeBuffer(this.uniformBuffer, 0, this._uniformBuf);
+        passEncoder.setPipeline(this.pipeline);
+        for (let _i = 0, _it = this.layers, _n = _it.length; _i < _n; _i++) {
+            const layer = _it[_i];
+            if (!layer.generated || !layer.vertexBuffer || !layer.indexBuffer || !layer.bindGroup)
+                continue;
+            if (layer.indexCount === 0)
+                continue;
+            if (!this._perLayerView || !this._perLayerBuf)
+                continue;
+            const pv = this._perLayerView;
+            pv.set("layerPos", [layer.genCenterX - layer.windOffsetX, layer.altitude, layer.genCenterZ - layer.windOffsetZ]);
+            pv.set("_pad", 0);
+            this.device.queue.writeBuffer(layer.perLayerUniform, 0, this._perLayerBuf);
+            passEncoder.setBindGroup(0, layer.bindGroup, [0]);
+            passEncoder.setVertexBuffer(0, layer.vertexBuffer);
+            passEncoder.setIndexBuffer(layer.indexBuffer, layer.useUint32 ? "uint32" : "uint16");
+            passEncoder.drawIndexed(layer.indexCount);
+        }
+    }
+    destroy() {
+        this.layers.forEach((layer) => {
+            if (layer.vertexBuffer) {
+                layer.vertexBuffer.destroy();
+                layer.vertexBuffer = null;
+            }
+            if (layer.indexBuffer) {
+                layer.indexBuffer.destroy();
+                layer.indexBuffer = null;
+            }
+            layer.perLayerUniform.destroy();
+            // GPUBindGroup has no destroy() — just null it.
+            layer.bindGroup = null;
+        });
+        if (this.uniformBuffer) {
+            this.uniformBuffer.destroy();
+            this.uniformBuffer = null;
+        }
+        this.pipeline?.destroy();
+        this.pipeline = null;
+        // GPUBindGroupLayout has no destroy() — just null it.
+        this.bindGroupLayout = null;
+        this._uniformView = null;
+        this._uniformBuf = null;
+        this._perLayerView = null;
+        this._perLayerBuf = null;
+    }
+}

package/dist/libraries/weatherfx/src/index.js

@@ -0,0 +1,4 @@
+export { CloudSystem, CloudUniformsStruct, PerLayerUniformsStruct } from "./cloud-system.js";
+export { COLLISION_RADIUS, MAX_VOXEL_FLOATS, ParticleSystem, RenderUniformsStruct, SimParamsStruct } from "./particle-system.js";
+// Engine library descriptor (declarative GameModule wiring)
+export { WeatherFxLib, WeatherFxTok } from "./library.js";

package/dist/libraries/weatherfx/src/library.js

@@ -0,0 +1,41 @@
+// ============================================================================
+// WeatherFxLib — declarative engine library descriptor for @downdraft/engine/libraries/weatherfx
+//
+// Games declare `libraries: [WeatherFxLib]` (or with config override) in their
+// GameModule. The host creates the ParticleSystem (renderer-side only — weather
+// visual effects are GPU compute + render passes) and exposes it via the
+// WeatherFxTok typed token.
+//
+// CloudSystem requires a game-specific CloudMeshProvider, so games create it in
+// onReady (injecting the GPU device from the renderer context). Games that need
+// full control can still import CloudSystem / ParticleSystem directly (escape
+// hatch).
+// ============================================================================
+import { resourceToken } from "@downdraft/engine";
+import { ParticleSystem } from "./particle-system.js";
+// ── Typed tokens (DI) ──
+/** Token for the renderer-side weather particle system. Inject in renderer passes. */
+export const WeatherFxTok = resourceToken("weatherfx:particles");
+// ── Descriptor ──
+export const WeatherFxLib = {
+    name: "weatherfx",
+    version: "1.0.0",
+    // No SAB channels — weather FX are renderer-only GPU compute/render passes.
+    sabChannels: [],
+    provides: [WeatherFxTok],
+    // No sim setup — weather visual effects are entirely renderer-side.
+    renderer: {
+        async init(_config, ctx) {
+            const particles = new ParticleSystem(ctx.device, ctx.format);
+            await particles.init();
+            ctx.provide(WeatherFxTok, particles);
+            return particles;
+        },
+        dispose(particles) {
+            particles.destroy();
+        },
+    },
+    defaultConfig: {
+        maxParticles: 20000,
+    },
+};