@bloomengine/engine 0.3.1

package/native/shared/Cargo.toml

@@ -0,0 +1,42 @@
+[package]
+name = "bloom-shared"
+version = "0.1.0"
+edition = "2021"
+
+[features]
+default = ["mp3", "jolt", "hot-reload"]
+mp3 = ["dep:minimp3"]
+jolt = []
+# EN-008 — gate the `notify` filesystem watcher behind a compile-time
+# feature. Default-on for the dev workflow; ship game binaries with
+# --no-default-features (or --features mp3,jolt) to drop notify from
+# the dep tree entirely.
+hot-reload = ["dep:notify"]
+web = ["dep:web-time"]
+
+[build-dependencies]
+cmake = "0.1"
+
+[dependencies]
+wgpu = "29"
+raw-window-handle = "0.6"
+fontdue = "0.9"
+libc = "0.2"
+bytemuck = { version = "1", features = ["derive"] }
+half = "2"
+image = { version = "0.25", default-features = false, features = ["png", "jpeg", "bmp", "tga", "hdr"] }
+image_dds = { version = "0.7", default-features = false, features = ["ddsfile", "image"] }
+gltf = { version = "1", features = ["KHR_materials_pbrSpecularGlossiness", "KHR_materials_transmission"] }
+lewton = "0.10"
+minimp3 = { version = "0.5", optional = true }
+earcutr = "0.4"
+web-time = { version = "0.2", optional = true }
+# Phase 6 — hot-reload watcher for material WGSL files. Native only;
+# wasm doesn't have a filesystem to watch (gated in code via
+# cfg(not(target_arch = "wasm32"))). EN-008 made it opt-in via the
+# `hot-reload` cargo feature so shipped game builds can drop notify.
+[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
+notify = { version = "6", optional = true }
+
+[dev-dependencies]
+pollster = "0.4"

package/native/shared/build.rs

@@ -0,0 +1,77 @@
+//! Build script for bloom-shared.
+//!
+//! Only does work when the `jolt` feature is enabled. In that case it builds
+//! the `bloom_jolt` C++ shim (and JoltPhysics, via its own CMakeLists) via the
+//! `cmake` crate and emits link directives so rustc picks up both archives.
+
+fn main() {
+    // Always re-run when these change.
+    println!("cargo:rerun-if-changed=build.rs");
+    println!("cargo:rerun-if-env-changed=CARGO_FEATURE_JOLT");
+
+    if std::env::var_os("CARGO_FEATURE_JOLT").is_none() {
+        return;
+    }
+
+    // The Jolt C++ shim cannot target WebAssembly via the normal cmake path —
+    // Emscripten + Jolt is a separate build pipeline (see JoltPhysics.js).
+    // On wasm32 the web crate routes bloom_physics_* FFI to JoltPhysics.js
+    // directly via wasm_bindgen; no static library is needed here.
+    if std::env::var("CARGO_CFG_TARGET_ARCH").as_deref() == Ok("wasm32") {
+        return;
+    }
+
+    build_jolt();
+}
+
+#[cfg(not(feature = "jolt"))]
+fn build_jolt() {}
+
+#[cfg(feature = "jolt")]
+fn build_jolt() {
+    use std::path::PathBuf;
+
+    // Locate native/third_party/bloom_jolt relative to this crate.
+    let manifest_dir = PathBuf::from(std::env::var("CARGO_MANIFEST_DIR").unwrap());
+    let shim_dir = manifest_dir
+        .parent()
+        .unwrap()
+        .join("third_party")
+        .join("bloom_jolt");
+
+    if !shim_dir.join("CMakeLists.txt").exists() {
+        panic!(
+            "bloom_jolt shim not found at {}; did the third_party submodules init?",
+            shim_dir.display()
+        );
+    }
+
+    println!("cargo:rerun-if-changed={}", shim_dir.join("CMakeLists.txt").display());
+    println!("cargo:rerun-if-changed={}", shim_dir.join("include/bloom_jolt.h").display());
+    println!("cargo:rerun-if-changed={}", shim_dir.join("src/bloom_jolt.cpp").display());
+
+    let dst = cmake::Config::new(&shim_dir)
+        .profile("Release")
+        .define("CMAKE_BUILD_TYPE", "Release")
+        .build();
+
+    println!("cargo:rustc-link-search=native={}", dst.join("lib").display());
+    println!("cargo:rustc-link-lib=static=bloom_jolt");
+    println!("cargo:rustc-link-lib=static=Jolt");
+
+    // C++ standard library — required because we're linking static archives
+    // that pull in libc++ / libstdc++ symbols.
+    let target = std::env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
+    match target.as_str() {
+        "macos" | "ios" | "tvos" | "watchos" => {
+            println!("cargo:rustc-link-lib=dylib=c++");
+        }
+        "linux" | "android" => {
+            println!("cargo:rustc-link-lib=dylib=stdc++");
+        }
+        "windows" => {
+            // MSVC toolchain handles libc++ automatically; MinGW would need stdc++.
+        }
+        _ => {}
+    }
+}

package/native/shared/shaders/common/fog.wgsl

@@ -0,0 +1,16 @@
+// Distance fog — standard exponential-squared falloff.
+//
+// Depends on material_abi.wgsl for view.fog (rgb + density).
+
+// Apply fog to a lit fragment. `view_distance` is the world-space
+// distance from the camera to the fragment. `color` is the lit HDR
+// colour before fog.
+fn apply_fog(color: vec3<f32>, view_distance: f32) -> vec3<f32> {
+  let density = view.fog.w;
+  if (density <= 0.0) { return color; }
+  // exp² is tighter near the camera and softer at distance than a plain
+  // exp — matches what most atmospherics use.
+  let f = exp(-density * view_distance * density * view_distance);
+  let factor = clamp(f, 0.0, 1.0);
+  return mix(view.fog.rgb, color, factor);
+}

package/native/shared/shaders/common/imposter.wgsl

@@ -0,0 +1,112 @@
+// Octahedral imposter helpers.
+//
+// The standard "octahedral imposter" technique encodes a hemisphere of
+// view directions into a 2D atlas. A model is pre-rendered from N²
+// directions on an octahedron (V1 expects N = 8 → 64 views in an 8×8
+// grid). At runtime, the fragment shader picks the right grid cell
+// based on the camera's direction relative to the imposter's position.
+//
+// Atlas convention:
+//   - 8×8 grid (V1 fixed). 256 to 512 px per cell.
+//   - RGBA8 (color + alpha). Future: split into albedo / normal / depth.
+//   - Each cell renders the model facing in the encoded direction.
+//
+// Bake tooling: V1 expects games to use Blender's ScreenSpace
+// imposter add-on, Unity's Tree Creator imposter mode, or any
+// equivalent external tool. The engine bake tool ships in a follow-up.
+
+const IMPOSTER_GRID: u32 = 8u;
+const IMPOSTER_GRID_F: f32 = 8.0;
+
+// Spherical → octahedron: unfold a unit sphere onto the [-1, 1] square.
+fn octahedral_encode(dir: vec3<f32>) -> vec2<f32> {
+  let n = dir / (abs(dir.x) + abs(dir.y) + abs(dir.z));
+  if (n.y >= 0.0) {
+    return vec2<f32>(n.x, n.z);
+  }
+  // Lower hemisphere: fold around.
+  return vec2<f32>(
+    (1.0 - abs(n.z)) * select(-1.0, 1.0, n.x >= 0.0),
+    (1.0 - abs(n.x)) * select(-1.0, 1.0, n.z >= 0.0),
+  );
+}
+
+// Octahedron → spherical (inverse of octahedral_encode).
+fn octahedral_decode(uv: vec2<f32>) -> vec3<f32> {
+  let abs_uv = abs(uv);
+  let y = 1.0 - abs_uv.x - abs_uv.y;
+  if (y >= 0.0) {
+    return normalize(vec3<f32>(uv.x, y, uv.y));
+  }
+  let signed_uv = sign(uv);
+  return normalize(vec3<f32>(
+    signed_uv.x * (1.0 - abs_uv.y),
+    y,
+    signed_uv.y * (1.0 - abs_uv.x),
+  ));
+}
+
+// Pick the grid cell + sub-cell UV for sampling an octahedral imposter
+// atlas. `view_dir` is the direction from the imposter to the camera
+// (world space, normalized). `local_uv` is the per-cell UV
+// (0..1, the billboard quad's UV).
+//
+// Returns the atlas UV in [0, 1] mapping to the right cell + sub-cell.
+fn imposter_atlas_uv(view_dir: vec3<f32>, local_uv: vec2<f32>) -> vec2<f32> {
+  // Encode direction → octahedral UV in [-1, 1], remap to [0, 1].
+  let oct = octahedral_encode(view_dir) * 0.5 + 0.5;
+  // Snap to the nearest cell in the 8×8 grid.
+  let cell = floor(oct * IMPOSTER_GRID_F);
+  let cell_uv = (cell + clamp(local_uv, vec2<f32>(0.0), vec2<f32>(1.0))) / IMPOSTER_GRID_F;
+  return cell_uv;
+}
+
+// Convenience: pick the UV cell directly from a view direction (ignoring
+// per-cell sub-UV). Useful when sampling a pre-baked atlas where each
+// cell is a flat texture and the billboard quad's per-vertex UV is
+// already in [0, 1].
+fn imposter_uv_for_view(view_dir: vec3<f32>) -> vec2<f32> {
+  return imposter_atlas_uv(view_dir, vec2<f32>(0.5, 0.5));
+}
+
+// Standard billboard: build a screen-aligned quad facing the camera.
+// `world_center` is the imposter's world-space anchor.
+// `vertex_idx` is the @builtin(vertex_index) (0..3 for two triangles
+// in a TriangleStrip, or 0..6 for a TriangleList).
+// Returns the world-space vertex position + the per-vertex UV.
+struct BillboardVertex {
+  world_pos: vec3<f32>,
+  uv:        vec2<f32>,
+};
+
+fn billboard_quad(
+  world_center: vec3<f32>, scale: f32,
+  camera_pos: vec3<f32>, camera_up: vec3<f32>,
+  vertex_idx: u32,
+) -> BillboardVertex {
+  // 4 corners of a unit quad: (-,-), (+,-), (-,+), (+,+).
+  // TriangleStrip indexing: 0,1,2,3 → 0=BL, 1=BR, 2=TL, 3=TR.
+  let bl = vec2<f32>(-0.5, -0.5);
+  let br = vec2<f32>( 0.5, -0.5);
+  let tl = vec2<f32>(-0.5,  0.5);
+  let tr = vec2<f32>( 0.5,  0.5);
+  var corner: vec2<f32>;
+  switch (vertex_idx) {
+    case 0u: { corner = bl; }
+    case 1u: { corner = br; }
+    case 2u: { corner = tl; }
+    default: { corner = tr; }
+  }
+
+  // View basis: forward = imposter → camera, right = up × forward, up = forward × right.
+  let forward = normalize(camera_pos - world_center);
+  let right   = normalize(cross(camera_up, forward));
+  let up      = normalize(cross(forward, right));
+
+  let world_pos = world_center + scale * (right * corner.x + up * corner.y);
+  let uv        = corner + vec2<f32>(0.5, 0.5);   // 0..1
+  var out: BillboardVertex;
+  out.world_pos = world_pos;
+  out.uv        = uv;
+  return out;
+}

package/native/shared/shaders/common/pbr.wgsl

@@ -0,0 +1,186 @@
+// PBR common — GGX specular, Lambert diffuse, split-sum IBL.
+//
+// Depends on material_abi.wgsl (requires group 1 env + brdf_lut, group 2
+// base/normal/mr/em/occ textures + material factors).
+
+const PI: f32 = 3.14159265358979;
+
+// =====================================================================
+// Microfacet BRDF components
+// =====================================================================
+
+// Trowbridge-Reitz / GGX normal distribution.
+fn d_ggx(n_dot_h: f32, roughness: f32) -> f32 {
+  let a  = roughness * roughness;
+  let a2 = a * a;
+  let nh2 = n_dot_h * n_dot_h;
+  let denom = nh2 * (a2 - 1.0) + 1.0;
+  return a2 / (PI * denom * denom);
+}
+
+// Schlick-GGX geometry term with combined view + light masking.
+fn g_smith(n_dot_v: f32, n_dot_l: f32, roughness: f32) -> f32 {
+  let r = roughness + 1.0;
+  let k = (r * r) * 0.125;
+  let gv = n_dot_v / (n_dot_v * (1.0 - k) + k);
+  let gl = n_dot_l / (n_dot_l * (1.0 - k) + k);
+  return gv * gl;
+}
+
+// Schlick's Fresnel approximation.
+fn f_schlick(cos_theta: f32, f0: vec3<f32>) -> vec3<f32> {
+  return f0 + (vec3<f32>(1.0) - f0) * pow(1.0 - cos_theta, 5.0);
+}
+
+// Fresnel with a roughness term for IBL — fades the specular boost at
+// grazing angles on rough surfaces, avoiding the "everything reflects"
+// artifact.
+fn f_schlick_roughness(cos_theta: f32, f0: vec3<f32>, roughness: f32) -> vec3<f32> {
+  let inv_rough = vec3<f32>(1.0 - roughness);
+  return f0 + (max(inv_rough, f0) - f0) * pow(1.0 - cos_theta, 5.0);
+}
+
+// =====================================================================
+// Direct lighting — one directional or point light contribution
+// =====================================================================
+
+fn brdf_direct(
+  n: vec3<f32>, v: vec3<f32>, l: vec3<f32>,
+  albedo: vec3<f32>, metallic: f32, roughness: f32,
+) -> vec3<f32> {
+  let h = normalize(v + l);
+  let n_dot_v = max(dot(n, v), 0.0001);
+  let n_dot_l = max(dot(n, l), 0.0);
+  let n_dot_h = max(dot(n, h), 0.0);
+  let v_dot_h = max(dot(v, h), 0.0);
+
+  // Dielectrics get F0 = 0.04; metals tint the reflection by the albedo.
+  let f0 = mix(vec3<f32>(0.04), albedo, metallic);
+
+  let d = d_ggx(n_dot_h, roughness);
+  let g = g_smith(n_dot_v, n_dot_l, roughness);
+  let f = f_schlick(v_dot_h, f0);
+
+  let specular = (d * g * f) / max(4.0 * n_dot_v * n_dot_l, 0.0001);
+  let kd = (vec3<f32>(1.0) - f) * (1.0 - metallic);
+  let diffuse = kd * albedo / PI;
+
+  return (diffuse + specular) * n_dot_l;
+}
+
+// =====================================================================
+// IBL — split-sum approximation
+// =====================================================================
+//
+// env_diffuse_tex is a pre-convolved irradiance map sampled with the
+// surface normal. env_tex is the original equirect HDR, sampled with a
+// reflection vector and a roughness-derived mip bias. brdf_lut_tex is
+// the pre-computed 2D LUT keyed on (n·v, roughness).
+//
+// Helper sampling functions assume equirectangular layout, matching the
+// existing engine convention.
+
+fn dir_to_equirect_uv(dir: vec3<f32>) -> vec2<f32> {
+  let d = normalize(dir);
+  let theta = acos(clamp(d.y, -1.0, 1.0));
+  let phi   = atan2(d.z, d.x);
+  let u     = phi / (2.0 * PI);
+  return vec2<f32>(u - floor(u), theta / PI);
+}
+
+fn seamless_equirect_uv(uv: vec2<f32>) -> vec2<f32> {
+  let tex_w = f32(textureDimensions(env_tex, 0).x);
+  let half_texel = 0.5 / tex_w;
+  return vec2<f32>(clamp(uv.x, half_texel, 1.0 - half_texel), uv.y);
+}
+
+fn sample_env(dir: vec3<f32>, lod: f32) -> vec3<f32> {
+  return textureSampleLevel(env_tex, env_samp,
+                            seamless_equirect_uv(dir_to_equirect_uv(dir)),
+                            lod).rgb * view.camera_pos.w;
+}
+
+fn sample_env_diffuse(normal: vec3<f32>) -> vec3<f32> {
+  return textureSample(env_diffuse_tex, env_samp,
+                       dir_to_equirect_uv(normal)).rgb * view.camera_pos.w;
+}
+
+fn ibl(
+  n: vec3<f32>, v: vec3<f32>,
+  albedo: vec3<f32>, metallic: f32, roughness: f32, occlusion: f32,
+) -> vec3<f32> {
+  let r = reflect(-v, n);
+  let n_dot_v = max(dot(n, v), 0.0001);
+  let f0 = mix(vec3<f32>(0.04), albedo, metallic);
+  let f  = f_schlick_roughness(n_dot_v, f0, roughness);
+
+  // Diffuse IBL — convolved irradiance.
+  let kd = (vec3<f32>(1.0) - f) * (1.0 - metallic);
+  let irr = sample_env_diffuse(n);
+  let diffuse = kd * albedo * irr;
+
+  // Specular IBL — roughness-weighted mip (approximation).
+  // Real split-sum pre-filters per mip; we use a simple lod bias for
+  // now. The engine can swap in a proper pre-filtered chain later.
+  let lod = roughness * 6.0;
+  let env = sample_env(r, lod);
+  let brdf = textureSample(brdf_lut_tex, brdf_lut_samp,
+                           vec2<f32>(n_dot_v, roughness)).rg;
+  let specular = env * (f * brdf.x + brdf.y);
+
+  return (diffuse + specular) * occlusion;
+}
+
+// =====================================================================
+// EN-012 — Foliage shading model
+// =====================================================================
+//
+// Wrap-lambert diffuse + sun-behind-leaf transmission. Use from custom
+// material shaders that declare the foliage shading model
+// (MaterialFactors.shading_model.x == 1.0). The standard pattern is:
+//
+//   if (material.shading_model.x > 0.5) {
+//     out_color = shade_foliage(N, L, V, lit, sun_color, albedo);
+//   } else {
+//     out_color = shade_pbr_standard(...);
+//   }
+//
+// Inputs:
+//   N_world        = surface normal in world space
+//   L_world        = direction TO the sun (normalized)
+//   V_world        = direction TO the camera (normalized)
+//   base_color_lit = the standard lit colour (sun_color * direct_lambert)
+//                    — V1 doesn't actually consume this; reserved for V2
+//                    when foliage gets to layer over the standard term
+//   sun_color      = sun radiance entering this fragment
+//   base_albedo    = surface albedo (used for both lit + transmitted terms)
+//
+// Returns the final shaded colour. Reads MaterialFactors:
+//   shading_model.yzw = transmission_color
+//   foliage_params.x  = transmission_amount
+//   foliage_params.y  = wrap_factor
+//
+// V1 limitation: ambient / IBL / specular are NOT included — materials
+// that want IBL ambient on foliage add it themselves outside this
+// helper. shade_foliage is just the directional terms.
+fn shade_foliage(
+  N_world: vec3<f32>, L_world: vec3<f32>, V_world: vec3<f32>,
+  base_color_lit: vec3<f32>, sun_color: vec3<f32>, base_albedo: vec3<f32>,
+) -> vec3<f32> {
+  // Wrap-lambert: back-faces don't go pure black. wrap=0 reproduces
+  // standard lambert; wrap=1 wraps light fully around the back.
+  let wrap         = material.foliage_params.y;
+  let n_dot_l      = dot(N_world, L_world);
+  let wrap_diffuse = max((n_dot_l + wrap) / (1.0 + wrap), 0.0);
+  let lit          = base_albedo * sun_color * wrap_diffuse;
+
+  // Transmission: sun behind the leaf → warm tint into the camera.
+  // V . -L is high when the camera is looking toward the sun through
+  // the leaf. The pow(., 4) gives a tight halo around the sun.
+  let v_dot_neg_l   = max(dot(V_world, -L_world), 0.0);
+  let trans_strength = pow(v_dot_neg_l, 4.0) * material.foliage_params.x;
+  let trans_color    = material.shading_model.yzw;
+  let transmitted    = base_albedo * sun_color * trans_color * trans_strength;
+
+  return lit + transmitted;
+}

package/native/shared/shaders/common/shadows.wgsl

@@ -0,0 +1,77 @@
+// Cascaded shadow maps — 3-cascade PCF sampling.
+//
+// Depends on material_abi.wgsl for PerView.shadow_cascades,
+// shadow_splits, and the three shadow_tex_N depth samplers.
+
+// Pick a cascade by comparing world-space depth to the configured splits.
+// Returns 0, 1, or 2.
+fn select_cascade(view_space_depth: f32) -> u32 {
+  let d = abs(view_space_depth);
+  if (d < view.shadow_splits.x) { return 0u; }
+  if (d < view.shadow_splits.y) { return 1u; }
+  return 2u;
+}
+
+// Sample a single cascade with 2×2 PCF.
+fn sample_shadow_cascade(
+  cascade_idx: u32, world_pos: vec3<f32>,
+) -> f32 {
+  let light_clip = view.shadow_cascades[cascade_idx]
+                 * vec4<f32>(world_pos, 1.0);
+  let light_ndc = light_clip.xyz / light_clip.w;
+
+  // Outside the cascade's frustum → not shadowed.
+  if (abs(light_ndc.x) > 1.0 || abs(light_ndc.y) > 1.0
+      || light_ndc.z < 0.0  || light_ndc.z > 1.0) {
+    return 1.0;
+  }
+
+  let uv = vec2<f32>(
+    light_ndc.x * 0.5 + 0.5,
+    1.0 - (light_ndc.y * 0.5 + 0.5),
+  );
+  // Slight depth bias to avoid surface acne.
+  let ref_depth = light_ndc.z - 0.001;
+
+  // wgpu doesn't let us index texture_depth_2d arrays yet — branch.
+  var result: f32 = 1.0;
+  switch (cascade_idx) {
+    case 0u: {
+      result = textureSampleCompareLevel(shadow_tex_0, shadow_samp,
+                                         uv, ref_depth);
+      break;
+    }
+    case 1u: {
+      result = textureSampleCompareLevel(shadow_tex_1, shadow_samp,
+                                         uv, ref_depth);
+      break;
+    }
+    default: {
+      result = textureSampleCompareLevel(shadow_tex_2, shadow_samp,
+                                         uv, ref_depth);
+      break;
+    }
+  }
+  return result;
+}
+
+// Full cascaded-shadow query. Pass in world position and the world-space
+// depth from the camera's view (positive is "in front of camera").
+// Returns a shadow factor in [0, 1]; 1 = lit, 0 = fully shadowed.
+fn shadow(world_pos: vec3<f32>, view_space_depth: f32) -> f32 {
+  let cascade = select_cascade(view_space_depth);
+  return sample_shadow_cascade(cascade, world_pos);
+}
+
+// Game-shader entry point. Picks a cascade automatically using the
+// active view matrix and returns a shadow factor in [0, 1]
+// (1 = fully lit, 0 = fully shadowed). Use this from custom materials
+// (grass, tree, terrain, water) that want to receive the directional
+// sun shadow with one line. Requires `view` (PerView) to be in scope —
+// any shader that includes material_abi.wgsl already has it.
+fn sample_sun_shadow(world_pos: vec3<f32>) -> f32 {
+  let view_pos = view.view * vec4<f32>(world_pos, 1.0);
+  // The engine convention is camera-looks-down-minus-Z; flip so callers
+  // get a positive "in front of camera" depth into select_cascade.
+  return shadow(world_pos, -view_pos.z);
+}

package/native/shared/shaders/common/sky.wgsl

@@ -0,0 +1,8 @@
+// Sky sampling helpers — thin wrappers over pbr.wgsl's env sampler so
+// the dedicated sky pipeline can stay short.
+
+// Sample the HDR equirect env map along a world-space direction with
+// no mip bias (sky pass doesn't want the roughness-based blur).
+fn sample_sky(dir: vec3<f32>) -> vec3<f32> {
+  return sample_env(dir, 0.0);
+}

package/native/shared/shaders/common/tonemap.wgsl

@@ -0,0 +1,25 @@
+// ACES filmic tonemapping — the Narkowicz fit, same one the composite
+// pass uses today. Kept here as a shared helper so any future custom
+// shader that wants its output already tonemapped (rare, usually
+// post-FX territory) can reuse the same curve.
+
+fn aces_tonemap(x: vec3<f32>) -> vec3<f32> {
+  let a = 2.51;
+  let b = 0.03;
+  let c = 2.43;
+  let d = 0.59;
+  let e = 0.14;
+  return clamp((x * (a * x + b)) / (x * (c * x + d) + e),
+               vec3<f32>(0.0), vec3<f32>(1.0));
+}
+
+// Linear-to-sRGB for the rare case a shader needs to sample a texture
+// stored as linear and output sRGB directly. The engine's composite
+// pass already does this at display time, so most materials never call
+// it.
+fn linear_to_srgb(x: vec3<f32>) -> vec3<f32> {
+  let cutoff = step(vec3<f32>(0.0031308), x);
+  let low    = x * 12.92;
+  let high   = 1.055 * pow(x, vec3<f32>(1.0 / 2.4)) - 0.055;
+  return mix(low, high, cutoff);
+}

package/native/shared/shaders/impulse_field.wgsl

@@ -0,0 +1,53 @@
+// Phase 7 — impulse field update compute shader.
+//
+// Input:  `src` — last frame's R32Float field (world-space top-down).
+//         `info` — world bounds, decay factor, queued splats.
+// Output: `dst` — this frame's field.
+//
+// Per texel: value = previous * decay + sum(splat strength × 1-d/r).
+
+struct Splat {
+  pos:      vec2<f32>,  // world xz
+  radius:   f32,
+  strength: f32,
+};
+
+struct Info {
+  world_min:   vec2<f32>,
+  world_size:  vec2<f32>,
+  decay:       f32,
+  _pad0:       f32,
+  splat_count: u32,
+  _pad1:       u32,
+  splats:      array<Splat, 16>,
+};
+
+@group(0) @binding(0) var src: texture_2d<f32>;
+@group(0) @binding(1) var dst: texture_storage_2d<r32float, write>;
+@group(0) @binding(2) var<uniform> info: Info;
+
+@compute @workgroup_size(8, 8)
+fn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let dims = textureDimensions(src);
+  if (gid.x >= dims.x || gid.y >= dims.y) { return; }
+
+  // Decay the previous field.
+  let prev = textureLoad(src, vec2<i32>(gid.xy), 0).r;
+  var value = prev * info.decay;
+
+  // Convert the texel's world position.
+  let uv    = (vec2<f32>(gid.xy) + vec2<f32>(0.5)) / vec2<f32>(dims);
+  let world = info.world_min + uv * info.world_size;
+
+  // Additively accumulate every queued splat.
+  for (var i: u32 = 0u; i < info.splat_count; i = i + 1u) {
+    let s = info.splats[i];
+    let d = distance(world, s.pos);
+    if (d < s.radius) {
+      let falloff = 1.0 - d / s.radius;
+      value = value + s.strength * falloff * falloff;
+    }
+  }
+
+  textureStore(dst, vec2<i32>(gid.xy), vec4<f32>(value, 0.0, 0.0, 0.0));
+}