@bornengine/engine 0.4.16

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,186 @@
+// Cascaded shadow maps — 3-cascade PCF sampling for the material path.
+//
+// Depends on material_abi.wgsl for PerView.shadow_cascades, shadow_splits,
+// camera_pos, and the three shadow_tex_N depth samplers.
+//
+// Cascade selection uses world-space DISTANCE from the camera (not view-space
+// depth) so that merely rotating the camera doesn't reshuffle which cascade a
+// surface falls in — that view-dependent reshuffle made terrain/foliage
+// shadows visibly swim as the camera turned. Cross-cascade blending at the
+// split boundaries removes the hard seam that otherwise slides across the
+// ground with the camera. This mirrors the deferred core path
+// (renderer/shaders/core.rs::sample_shadow), so the material-shaded surfaces
+// (terrain, grass, trees, water) match the rest of the scene.
+
+// Sample a single cascade with a 4-tap rotated-grid PCF kernel. The kernel
+// softens the edge a touch and hides per-texel crawl without the cost of a
+// full Poisson disk.
+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 → treat as lit.
+  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;
+
+  var dims: vec2<u32>;
+  switch (cascade_idx) {
+    case 0u: { dims = textureDimensions(shadow_tex_0); }
+    case 1u: { dims = textureDimensions(shadow_tex_1); }
+    default: { dims = textureDimensions(shadow_tex_2); }
+  }
+  let texel = vec2<f32>(1.0 / f32(dims.x), 1.0 / f32(dims.y));
+
+  var offs = array<vec2<f32>, 4>(
+    vec2<f32>(-0.5, -0.5), vec2<f32>( 0.5, -0.5),
+    vec2<f32>(-0.5,  0.5), vec2<f32>( 0.5,  0.5),
+  );
+  var result: f32 = 0.0;
+  for (var i: i32 = 0; i < 4; i = i + 1) {
+    let suv = uv + offs[i] * texel;
+    // wgpu doesn't let us index depth-texture arrays yet — branch.
+    switch (cascade_idx) {
+      case 0u: { result += textureSampleCompareLevel(shadow_tex_0, shadow_samp, suv, ref_depth); }
+      case 1u: { result += textureSampleCompareLevel(shadow_tex_1, shadow_samp, suv, ref_depth); }
+      default: { result += textureSampleCompareLevel(shadow_tex_2, shadow_samp, suv, ref_depth); }
+    }
+  }
+  return result * 0.25;
+}
+
+// Game-shader entry point. Picks a cascade by rotation-independent world-space
+// distance, blends across the boundary, 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 {
+  // dir_light_count.y carries the shadows-enabled flag (mirrors the core
+  // path's sample_shadow gate; shadow_splits.w is the TSR mip-LOD bias, so
+  // it can't double as a flag): disabled shadows must read fully lit, not
+  // project through stale cascade VPs whose garbage NDC reads as occluded.
+  if (view.dir_light_count.y < 0.5) {
+    return 1.0;
+  }
+  let cam = view.camera_pos.xyz;
+  let dist = length(world_pos - cam);
+
+  var cascade = 2u;
+  if (dist <= view.shadow_splits.x) {
+    cascade = 0u;
+  } else if (dist <= view.shadow_splits.y) {
+    cascade = 1u;
+  }
+
+  let shadow_val = sample_shadow_cascade(cascade, world_pos);
+
+  // Blend into the next cascade over the last 10% of this cascade's range so
+  // the transition is a soft gradient rather than a hard line that the camera
+  // drags across the scene.
+  var split_near = 0.0;
+  var split_far = view.shadow_splits.x;
+  if (cascade == 1u) {
+    split_near = view.shadow_splits.x;
+    split_far  = view.shadow_splits.y;
+  } else if (cascade == 2u) {
+    split_near = view.shadow_splits.y;
+    split_far  = view.shadow_splits.z;
+  }
+  let blend_zone = (split_far - split_near) * 0.1;
+  let dist_to_edge = split_far - dist;
+  if (cascade < 2u && dist_to_edge < blend_zone) {
+    let next_val = sample_shadow_cascade(cascade + 1u, world_pos);
+    let t = clamp(dist_to_edge / blend_zone, 0.0, 1.0);
+    return mix(next_val, shadow_val, t);
+  }
+  return shadow_val;
+}
+
+// Normal-offset variant — use this when the surface normal is available
+// (it always is in a lit material shader). Offsets the receiver position
+// along the geometric normal by ~1.5 cascade texels before projecting,
+// which kills the full-face acne a constant depth bias can't cover on
+// steep slopes and vertical walls (a wall at 40° sun incidence spans
+// several texels of depth across one shadow texel — the deferred core
+// path learned this the hard way; see core.rs::sample_shadow). Now that
+// material-path geometry (building, terrain, trees) casts into the
+// cascades, every material surface is a potential self-receiver and
+// needs the same treatment.
+fn sample_sun_shadow_n(world_pos: vec3<f32>, geo_n: vec3<f32>) -> f32 {
+  if (view.dir_light_count.y < 0.5) {
+    return 1.0;
+  }
+  let cam = view.camera_pos.xyz;
+  let dist = length(world_pos - cam);
+  var cascade = 2u;
+  if (dist <= view.shadow_splits.x) {
+    cascade = 0u;
+  } else if (dist <= view.shadow_splits.y) {
+    cascade = 1u;
+  }
+  // World-space size of one shadow texel in this cascade: the ortho span
+  // is ~2×split distance, mapped across the cascade map's width.
+  // textureDimensions keeps this honest if CASCADE_MAP_SIZE changes.
+  //
+  // Near a split boundary sample_sun_shadow blends in the NEXT cascade,
+  // whose texels are larger — an offset sized for this cascade
+  // under-biases that sample and paints acne bands exactly in the blend
+  // zones (the deferred core path hit the same thing). Size the offset
+  // by the next cascade's texel when inside its blend zone.
+  var split_far = view.shadow_splits.z;
+  if (cascade == 0u) { split_far = view.shadow_splits.x; }
+  else if (cascade == 1u) { split_far = view.shadow_splits.y; }
+  var split_near = 0.0;
+  if (cascade == 1u) { split_near = view.shadow_splits.x; }
+  else if (cascade == 2u) { split_near = view.shadow_splits.y; }
+  var eff_cascade = cascade;
+  if (cascade < 2u && (split_far - dist) < (split_far - split_near) * 0.1) {
+    eff_cascade = cascade + 1u;
+    if (eff_cascade == 1u) { split_far = view.shadow_splits.y; }
+    else { split_far = view.shadow_splits.z; }
+  }
+  var dims: vec2<u32>;
+  switch (eff_cascade) {
+    case 0u: { dims = textureDimensions(shadow_tex_0); }
+    case 1u: { dims = textureDimensions(shadow_tex_1); }
+    default: { dims = textureDimensions(shadow_tex_2); }
+  }
+  let texel_ws = (2.0 * split_far) / f32(dims.x);
+  // Slope-adaptive: at grazing sun incidence one shadow texel spans many
+  // times its footprint in receiver depth, so the fixed 1.5-texel offset
+  // still stripes walls that run nearly parallel to the light and distant
+  // hillsides in the coarse cascade. Grow the offset as n·l falls off
+  // (up to ~4.5 texels when fully grazing).
+  let ndl = clamp(dot(normalize(geo_n), normalize(view.sun_dir.xyz)), 0.0, 1.0);
+  let slope_boost = 1.0 + 2.0 * (1.0 - ndl);
+  let offset_pos = world_pos + normalize(geo_n) * texel_ws * 1.5 * slope_boost;
+  return sample_sun_shadow(offset_pos);
+}
+
+// ---- Back-compat shims -----------------------------------------------------
+// Older callers selected a cascade from view-space depth then sampled it.
+// Cascade selection now lives inside sample_sun_shadow (world-space distance),
+// so these just forward — kept so any shader still including the old names
+// keeps compiling.
+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;
+}
+
+fn shadow(world_pos: vec3<f32>, view_space_depth: f32) -> f32 {
+  return sample_sun_shadow(world_pos);
+}

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,57 @@
+// 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 = min(previous * decay + sum(splat strength × (1-d/r)²), 1).
+// The clamp keeps repeated splats at the same spot (a player wading
+// through water submits one every few frames) from accumulating far
+// past 1.0 — an unclamped field takes seconds of decay to drop back
+// under 1.0, which reads as a stuck full-strength splat.
+
+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>(min(value, 1.0), 0.0, 0.0, 0.0));
+}