@bornengine/engine 0.4.16

package/native/shared/Cargo.toml

@@ -0,0 +1,62 @@
+[package]
+name = "bloom-shared"
+version = "0.1.0"
+edition = "2021"
+
+[features]
+default = ["mp3", "jolt", "hot-reload", "models3d", "image-extras"]
+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"]
+# EN-014 — 3D model loading (glTF + DDS) and the ModelManager. Pure-2D
+# games disable this via Perry's `[native-library."<pkg>"]` feature
+# forwarding to drop gltf/gltf_json/image_dds from the binary entirely.
+# Default-on so existing 3D games are unaffected.
+models3d = ["dep:gltf", "dep:image_dds"]
+# EN-014 — image codecs beyond PNG. `image::load_from_memory` is
+# format-agnostic, so disabling this only changes which file formats
+# decode at runtime; PNG always works.
+# image_dds rides along: cooked BC7 .dds textures are "image formats
+# beyond PNG" in the same sense as jpeg/bmp/tga (decode-only here; the
+# encoder lives in tools/bloom-cook).
+image-extras = ["image/jpeg", "image/bmp", "image/tga", "image/hdr", "dep:image_dds"]
+
+[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"] }
+image_dds = { version = "0.7", default-features = false, features = ["ddsfile", "image"], optional = true }
+gltf = { version = "1", features = ["KHR_materials_pbrSpecularGlossiness", "KHR_materials_transmission"], optional = true }
+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 }
+
+# EN-063 — the engine's error channel on web. `log_error`'s eprintln! is a
+# black hole in a browser (no stderr), so every engine warning and error —
+# missing texture-array layers, surface-acquire failures, feature-off
+# warnings — was silently dropped on the one platform whose users can't
+# attach a debugger. Route them to console.error instead.
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+web-sys = { version = "0.3", features = ["console"] }
+
+[dev-dependencies]
+pollster = "0.4"

package/native/shared/build.rs

@@ -0,0 +1,270 @@
+//! 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");
+
+    let target_os = std::env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
+    let target_arch = std::env::var("CARGO_CFG_TARGET_ARCH").unwrap_or_default();
+
+    println!("cargo:rerun-if-env-changed=BLOOM_JOLT_PREBUILT_DIR");
+    println!("cargo:rerun-if-env-changed=BLOOM_JOLT_FROM_SOURCE");
+
+    // Prebuilt fast path — if `@bornengine/jolt-prebuilt` is available
+    // (via env var or a node_modules sibling), link its archives and
+    // skip the multi-minute cmake build of JoltPhysics entirely. The
+    // env var BLOOM_JOLT_FROM_SOURCE=1 forces the cmake fallback even
+    // when prebuilts are present, useful for hacking on the C++ shim.
+    let from_source = std::env::var_os("BLOOM_JOLT_FROM_SOURCE").is_some();
+    if !from_source {
+        if let Some(prebuilt_dir) = find_prebuilt_dir(&manifest_dir, &target_os, &target_arch) {
+            link_prebuilt(&prebuilt_dir, &target_os);
+            emit_cxx_runtime_link(&target_os);
+            return;
+        }
+    }
+
+    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()
+    );
+
+    // Build into a stable, short path next to the shim itself rather than the
+    // per-build OUT_DIR. Two reasons:
+    //   1. Cargo wraps OUT_DIR with the `\\?\` long-path prefix on Windows
+    //      whenever the absolute path approaches MAX_PATH; MSBuild and cl.exe
+    //      both choke on `\\?\`-prefixed paths in subtle ways (echo'd build
+    //      events fail with MSB3073, cl.exe rewrites the file to `\\testfile`
+    //      and reports C1083).
+    //   2. The Jolt build is expensive and identical across every cargo target
+    //      hash — caching it once per profile lets `cargo clean` not nuke a
+    //      multi-minute compile.
+    let dst = shim_dir
+        .join("build")
+        .join(format!("{}-{}", target_os, target_arch));
+
+    let lib_ext = if target_os == "windows" { "lib" } else { "a" };
+    let lib_prefix = if target_os == "windows" { "" } else { "lib" };
+    let bloom_jolt_lib = dst
+        .join("lib")
+        .join(format!("{}bloom_jolt.{}", lib_prefix, lib_ext));
+    let jolt_lib = dst
+        .join("lib")
+        .join(format!("{}Jolt.{}", lib_prefix, lib_ext));
+
+    if !(bloom_jolt_lib.exists() && jolt_lib.exists()) {
+        let mut cfg = cmake::Config::new(&shim_dir);
+        cfg.out_dir(&dst)
+            .profile("Release")
+            .define("CMAKE_BUILD_TYPE", "Release");
+        if target_os == "windows" {
+            // perry links the prebuilt Jolt archive with lld-link, which
+            // cannot read MSVC `/GL` (whole-program-optimization) object
+            // files — they're LTCG intermediates, not native COFF, and the
+            // link fails with "is not a native COFF file. Recompile without
+            // /GL?". Turn off Jolt's interprocedural optimization so the
+            // archive holds ordinary COFF objects perry can consume. (Costs
+            // a little Jolt codegen perf; physics is not the bottleneck.)
+            cfg.define("INTERPROCEDURAL_OPTIMIZATION", "OFF")
+                .define("CMAKE_INTERPROCEDURAL_OPTIMIZATION", "OFF");
+        }
+        let _ = cfg.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");
+
+    emit_cxx_runtime_link(&target_os);
+}
+
+/// Locate a BornEngine or legacy Bloom Engine Jolt prebuilt package's lib dir for the
+/// active build target. Returns `Some(dir)` only when both expected
+/// archives are present — a half-shipped package falls through to the
+/// cmake build instead of producing a confusing linker error.
+///
+/// Resolution order:
+///   1. `BLOOM_JOLT_PREBUILT_DIR` env var — points at a directory
+///      containing per-target subdirs (`<dir>/<os>-<arch>/lib*.a`).
+///      Used for local spike testing and for CI matrix jobs that
+///      stage archives outside `node_modules`.
+///   2. Walk up from `CARGO_MANIFEST_DIR` looking for either
+///      `node_modules/@bornengine/jolt-prebuilt/lib/<os>-<arch>/` or
+///      its legacy `@bloomengine/jolt-prebuilt` equivalent. The BornEngine
+///      scope is preferred, while existing Bloom Engine installs keep working.
+#[cfg(feature = "jolt")]
+fn find_prebuilt_dir(
+    manifest_dir: &std::path::Path,
+    target_os: &str,
+    target_arch: &str,
+) -> Option<std::path::PathBuf> {
+    // Map Rust's target_arch to the npm/Node convention used in this
+    // package's directory layout. Keep this in sync with the matrix in
+    // npm/jolt-prebuilt/README.md.
+    let arch_token = match target_arch {
+        "aarch64" => "arm64",
+        "x86_64" => "x64",
+        "arm" => "armv7",
+        other => other,
+    };
+    // Apple simulator targets share `target_os`/`target_arch` with their
+    // device counterpart (e.g. aarch64-apple-tvos-sim vs -tvos both report
+    // os=tvos arch=aarch64) and are only distinguished by the "sim" ABI.
+    // jolt-prebuilt ships a separate `<os>-<arch>-sim` archive built for the
+    // simulator platform; without this suffix we'd link the device archive
+    // into a simulator build and ld would reject the platform mismatch.
+    let sim_suffix = if std::env::var("CARGO_CFG_TARGET_ABI").as_deref() == Ok("sim") {
+        "-sim"
+    } else {
+        ""
+    };
+    let target_token = format!("{}-{}{}", target_os, arch_token, sim_suffix);
+
+    let candidates = std::iter::empty::<std::path::PathBuf>()
+        .chain(
+            std::env::var_os("BLOOM_JOLT_PREBUILT_DIR")
+                .map(|v| std::path::PathBuf::from(v).join(&target_token)),
+        )
+        .chain(walk_up_for_node_modules(manifest_dir).flat_map(|nm| {
+            ["@bornengine", "@bloomengine"].map(|scope| {
+                nm.join(scope)
+                    .join("jolt-prebuilt")
+                    .join("lib")
+                    .join(&target_token)
+            })
+        }));
+
+    let (lib_prefix, lib_ext) = if target_os == "windows" {
+        ("", "lib")
+    } else {
+        ("lib", "a")
+    };
+
+    for dir in candidates {
+        let bloom_jolt = dir.join(format!("{}bloom_jolt.{}", lib_prefix, lib_ext));
+        let jolt = dir.join(format!("{}Jolt.{}", lib_prefix, lib_ext));
+        if bloom_jolt.exists() && jolt.exists() {
+            return Some(dir);
+        }
+    }
+    None
+}
+
+/// Iterator over every ancestor `node_modules/` reachable from
+/// `start`. Yields each directory once, parent-first, so a closer
+/// prebuilt installation wins over a higher one (matching node's
+/// resolution algorithm).
+#[cfg(feature = "jolt")]
+fn walk_up_for_node_modules(
+    start: &std::path::Path,
+) -> impl Iterator<Item = std::path::PathBuf> + '_ {
+    let mut next: Option<&std::path::Path> = Some(start);
+    std::iter::from_fn(move || {
+        while let Some(cur) = next {
+            next = cur.parent();
+            let candidate = cur.join("node_modules");
+            if candidate.is_dir() {
+                return Some(candidate);
+            }
+        }
+        None
+    })
+}
+
+#[cfg(feature = "jolt")]
+fn link_prebuilt(dir: &std::path::Path, target_os: &str) {
+    // Rerun if any archive in the prebuilt dir changes — covers the
+    // case where a new release of jolt-prebuilt drops in new bytes.
+    let (lib_prefix, lib_ext) = if target_os == "windows" {
+        ("", "lib")
+    } else {
+        ("lib", "a")
+    };
+    println!(
+        "cargo:rerun-if-changed={}",
+        dir.join(format!("{}bloom_jolt.{}", lib_prefix, lib_ext))
+            .display()
+    );
+    println!(
+        "cargo:rerun-if-changed={}",
+        dir.join(format!("{}Jolt.{}", lib_prefix, lib_ext))
+            .display()
+    );
+
+    println!("cargo:rustc-link-search=native={}", dir.display());
+    println!("cargo:rustc-link-lib=static=bloom_jolt");
+    println!("cargo:rustc-link-lib=static=Jolt");
+}
+
+/// Emit the C++ standard library link directive that matches the
+/// archives we just linked. Required because the static archives pull
+/// in libc++ / libstdc++ symbols that the Rust toolchain doesn't
+/// resolve on its own.
+#[cfg(feature = "jolt")]
+fn emit_cxx_runtime_link(target_os: &str) {
+    match target_os {
+        "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/clouds.wgsl

@@ -0,0 +1,122 @@
+// One cloud deck — shared by the sky that draws the clouds and the ground that
+// takes their shadow.
+//
+// WHY THIS IS ONE FILE. These used to be two unrelated noise fields that had
+// never been reconciled, and the result did not survive looking at:
+//
+//   - The sky's puffs were fBm over a plane pinned to the CAMERA, so they slid
+//     along with the player instead of hanging over the world.
+//   - The ground's "cloud shadow" was a *different*, much finer field on a
+//     different noise, drifting ~80x faster (20 m/s against the sky's 0.25).
+//
+// So the shadow racing across the grass had no cloud above it, and the cloud
+// overhead cast nothing. Worse, only the materials that happened to carry a copy
+// of the ground function darkened at all: in the shooter that was the grass, but
+// not the terrain under it, nor the trees standing in it — a cloud shadow that
+// crosses the field and ignores the forest in the middle of it.
+//
+// Now there is ONE field, in WORLD space, and the shadow you are standing in
+// belongs to the cloud you can look up and see.
+//
+// THE MODEL. The deck is a horizontal plane at `p.y` metres. A view ray and a
+// sun ray are both intersected with it; whatever they hit is the same cloud.
+// That is the entire trick, and it is why the apparent size of a cloud in the
+// sky and the size of its shadow on the ground are no longer independently
+// tunable — they are the same number seen from two directions, which is the
+// point.
+
+fn cloud_hash(p: vec2<f32>) -> f32 {
+    return fract(sin(dot(p, vec2<f32>(127.1, 311.7))) * 43758.5453);
+}
+
+fn cloud_noise(p: vec2<f32>) -> f32 {
+    let i = floor(p);
+    let f = fract(p);
+    let uu = f * f * (3.0 - 2.0 * f);
+    let a = cloud_hash(i);
+    let b = cloud_hash(i + vec2<f32>(1.0, 0.0));
+    let c = cloud_hash(i + vec2<f32>(0.0, 1.0));
+    let d = cloud_hash(i + vec2<f32>(1.0, 1.0));
+    return mix(mix(a, b, uu.x), mix(c, d, uu.x), uu.y);
+}
+
+fn cloud_fbm(p0: vec2<f32>) -> f32 {
+    var s = 0.0;
+    var amp = 0.5;
+    var q = p0;
+    for (var i = 0; i < 5; i = i + 1) {
+        s = s + amp * cloud_noise(q);
+        q = q * 2.03;
+        amp = amp * 0.5;
+    }
+    return s;
+}
+
+// Cloud params, passed by each caller from whichever uniform block it happens to
+// have (the sky pass and the material ABI do not share one, so this file takes
+// them explicitly rather than reaching for a global):
+//
+//   x = shadow strength   0 = the world ignores the clouds entirely (default)
+//   y = deck height       world metres
+//   z = feature scale     noise units per metre — 1/z is the cloud size
+//   w = drift speed       metres/second
+//
+// The drift DIRECTION is the wind vector — the same one that bends the grass —
+// so the clouds travel the way the foliage under them is leaning. A game that
+// never set a wind still gets a slow default heading rather than a frozen sky.
+fn cloud_drift(wind_xy: vec2<f32>, t: f32, speed: f32) -> vec2<f32> {
+    var d = wind_xy;
+    if (dot(d, d) < 1e-6) { d = vec2<f32>(1.0, 0.25); }
+    return normalize(d) * speed * t;
+}
+
+// Coverage of the deck at a point ON the deck. 0 = clear sky, 1 = solid cloud.
+fn cloud_density(deck_xz: vec2<f32>, wind_xy: vec2<f32>, t: f32, cp: vec4<f32>) -> f32 {
+    let p = (deck_xz - cloud_drift(wind_xy, t, cp.w)) * cp.z;
+    // The threshold is high on purpose: it buys mostly-open sky with the
+    // occasional real cloud, instead of a permanent grey smear. A low threshold
+    // here is what makes a procedural deck read as fog.
+    return smoothstep(0.56, 1.04, cloud_fbm(p));
+}
+
+// Where a ray from `origin` along `dir` pierces the deck.
+fn cloud_deck_hit(origin: vec3<f32>, dir: vec3<f32>, deck_y: f32) -> vec2<f32> {
+    let t = (deck_y - origin.y) / dir.y;
+    return origin.xz + dir.xz * t;
+}
+
+// --- the two consumers -------------------------------------------------------
+
+// SKY: coverage along a view ray. Returns (coverage, sun-alignment) — the caller
+// colours the cloud from the second component so puffs facing the sun burn white
+// and the ones facing away stay cool grey.
+fn cloud_cover_view(cam: vec3<f32>, dir: vec3<f32>, sun_dir: vec3<f32>,
+                    wind_xy: vec2<f32>, t: f32, cp: vec4<f32>) -> vec2<f32> {
+    if (dir.y <= 0.02) { return vec2<f32>(0.0, 0.0); }
+    var cov = cloud_density(cloud_deck_hit(cam, dir, cp.y), wind_xy, t, cp);
+    // Toward the horizon a view ray runs so far through the deck that modelling
+    // it as an infinitely thin plane stops being defensible — fade out instead
+    // of drawing the smear the maths would give.
+    let horizon_fade = smoothstep(0.03, 0.24, dir.y);
+    // Thin the deck right around the sun so the disk still burns through.
+    let near_sun = smoothstep(0.90, 0.999, dot(dir, sun_dir));
+    cov = cov * horizon_fade * (1.0 - near_sun * 0.8) * 0.9;
+    let sun_amt = clamp(dot(dir, sun_dir) * 0.5 + 0.5, 0.0, 1.0);
+    return vec2<f32>(cov, sun_amt);
+}
+
+// GROUND: how much sun a world point keeps. 1.0 = full sun, lower = under cloud.
+// Multiply this into direct sunlight only — a cloud blocks the sun, it does not
+// stop the sky from being blue, and folding it into ambient too is what makes
+// cloud shadows read as flat grey paint rather than as shade.
+fn cloud_shadow_at(world_pos: vec3<f32>, sun_dir: vec3<f32>,
+                   wind_xy: vec2<f32>, t: f32, cp: vec4<f32>) -> f32 {
+    if (cp.x <= 0.0) { return 1.0; }
+    // Sun on the horizon: the shadow ray runs nearly parallel to the deck and
+    // the intersection shoots off to infinity, so the noise lookup lands a
+    // kilometre away and swims. Fade the whole effect out as the sun sets.
+    let up = sun_dir.y;
+    if (up <= 0.02) { return 1.0; }
+    let cov = cloud_density(cloud_deck_hit(world_pos, sun_dir, cp.y), wind_xy, t, cp);
+    return 1.0 - cov * cp.x * smoothstep(0.02, 0.20, up);
+}

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/foliage_wind.wgsl

@@ -0,0 +1,98 @@
+// Hierarchical foliage wind — one field, shared by the scene pass that draws the
+// tree and the shadow pass that casts it.
+//
+// WHY THREE LAYERS. A tree does not move as one thing. The trunk leans slowly
+// under the whole wind load, the branches swing at their own rate, and the
+// leaves flutter fast at the tips. Driving all of it from a single sine is what
+// makes procedural foliage read as rippling cloth instead of wood.
+//
+// What was here before did less than that: the engine swayed *alpha-cut
+// materials only*, so leaf cards fluttered and every trunk in every game was
+// perfectly rigid — and the shadow shaders applied no wind at all, so the leaves
+// moved while their shadows stayed nailed to the ground.
+//
+// WHERE THE WEIGHTS COME FROM. SH-013 planned to author them into vertex colours
+// (R = bend, G = branch, B = flutter). That is the right answer for hand-modelled
+// trees, but ours are procedurally generated, so the regions are known exactly and
+// can simply be derived from where the vertex sits relative to the tree's base:
+//
+//   trunk bend   proportional to height^2   -- a cantilever: the crown travels, the roots do not
+//   branch sway  proportional to reach out from the trunk axis
+//   leaf flutter cutout cards only, small and fast
+//
+// So: no new vertex attribute, no GLB re-bake, no COLOR_0 (which the scene shader
+// already spends on albedo tint), and it works on any foliage model the game flags.
+//
+// The offset is returned in WORLD space and added after the model transform.
+// Displacing in local space would let each tree's per-instance yaw rotate the
+// wind with it, and a stand of trees would bend in a dozen different directions.
+
+// `rel` is the vertex's WORLD-space offset from its model origin (so it is
+// already scaled and rotated -- the coefficients below are in metres and mean the
+// same thing for a sapling and a giant).
+// `wind` is the global wind vec4: xy = direction in the XZ plane, z = amplitude,
+// w = elapsed seconds.
+// `amount` scales the whole effect per draw; 0 = this is not foliage, don't move
+// it. `is_leaf` is 1.0 for cutout cards, 0.0 for wood.
+fn foliage_wind_world(rel: vec3<f32>, model_origin: vec3<f32>,
+                      wind: vec4<f32>, amount: f32, is_leaf: f32) -> vec3<f32> {
+    if (amount <= 0.0 || wind.z <= 0.0) { return vec3<f32>(0.0, 0.0, 0.0); }
+
+    let dir = vec3<f32>(wind.x, 0.0, wind.y);
+    let amp = wind.z * amount;
+    let t   = wind.w;
+
+    // Per-tree phase from the model's world origin. Without it a stand of trees
+    // sways in lockstep, which is the single most obvious tell of fake foliage.
+    let ph = model_origin.x * 0.137 + model_origin.z * 0.241;
+
+    let h     = max(rel.y, 0.0);
+    let reach = length(rel.xz);
+
+    // 1. TRUNK BEND — cantilever, so travel grows with the SQUARE of height: the
+    //    base is planted, the crown swings. Slow (~0.15 Hz). This is the motion
+    //    you read from 30 m away, and it is the one that did not exist at all.
+    // Coefficients are tuned so amount = 1.0 is a real tree in a lazy breeze:
+    // with the shooter's wind amplitude (0.10) a 4 m crown travels ~35 cm.
+    let bend = amp * 0.22 * h * h * sin(t * 0.95 + ph);
+
+    // 2. BRANCH SWAY — how far the vertex reaches out from the trunk axis. Medium
+    //    (~0.4 Hz), phase-offset by azimuth so opposite limbs do not swing together.
+    let azim  = atan2(rel.z, rel.x);
+    // Gated by height as well as reach: without it the flare at the base of the
+    // trunk has some reach and would shuffle its own roots.
+    let swing = amp * 0.70 * reach * clamp(h * 0.5, 0.0, 1.0)
+              * sin(t * 2.4 + ph + azim * 1.7);
+
+    // 3. LEAF FLUTTER — cutout cards only. Fast (~1 Hz), small, and keyed on the
+    //    vertex's own position so neighbouring cards break up rather than shimmer
+    //    as a sheet.
+    let fl = amp * 0.60 * is_leaf * sin(t * 6.0 + ph + h * 3.1 + reach * 5.0);
+
+    var o = dir * (bend + swing + fl);
+    // Leaves twist rather than only sliding downwind; and a leaning crown dips a
+    // little, because the tip is swinging on an arc, not a rail.
+    o.y = o.y + fl * 0.45 - bend * 0.15;
+    return o;
+}
+
+// Convenience wrapper: local-space vertex in, wind-displaced local-space vertex
+// out. Both the scene pass and the shadow pass want exactly this, and they must
+// agree exactly or a tree detaches from its own shadow.
+//
+// The offset is computed in WORLD space (see above) and then brought back into
+// local space by inverting the model's linear part. That inverse is exact for the
+// transforms these draws use -- rotation plus UNIFORM scale -- because then
+// M^-1 = M^T / s^2.
+fn foliage_wind_local(local_pos: vec3<f32>, model: mat4x4<f32>,
+                      wind: vec4<f32>, amount: f32, is_leaf: f32) -> vec3<f32> {
+    if (amount <= 0.0 || wind.z <= 0.0) { return local_pos; }
+    let origin = model[3].xyz;
+    let rel    = (model * vec4<f32>(local_pos, 1.0)).xyz - origin;
+    let wo     = foliage_wind_world(rel, origin, wind, amount, is_leaf);
+    let c0 = model[0].xyz;
+    let s2 = max(dot(c0, c0), 1e-8);
+    return local_pos + vec3<f32>(dot(model[0].xyz, wo),
+                                 dot(model[1].xyz, wo),
+                                 dot(model[2].xyz, wo)) / s2;
+}