From cbc276b1f7fd4b2e4929d9ef189a7a9960f7113c Mon Sep 17 00:00:00 2001 From: pkuzic Date: Fri, 25 Sep 2026 10:20:40 +0100 Subject: [PATCH] MONKEY (wet): weather/wetness.rs -> MonkeyFrame wet row + wet_hook.wgsl library Wetness ramps up while it rains (~90 s to soaked) and dries over ~4 min; ripple clock; rainSurfaces resource; env WOW_RAIN_SURFACES / WOW_WETNESS / WOW_WET_T capture overrides. Co-Authored-By: Claude Opus 5.5 --- crates/benilla-assets/src/materials.rs | 2 + .../benilla-assets/src/shaders/wet_hook.wgsl | 93 ++++++++++ crates/benilla-world/src/weather/mod.rs | 3 + crates/benilla-world/src/weather/wetness.rs | 168 ++++++++++++++++++ 4 files changed, 266 insertions(+) create mode 100644 crates/benilla-assets/src/shaders/wet_hook.wgsl create mode 100644 crates/benilla-world/src/weather/wetness.rs diff --git a/crates/benilla-assets/src/materials.rs b/crates/benilla-assets/src/materials.rs index a2254aa8..0e7b04d8 100644 --- a/crates/benilla-assets/src/materials.rs +++ b/crates/benilla-assets/src/materials.rs @@ -34,6 +34,8 @@ pub fn register_shaders(app: &mut App) { load_shader_library!(app, "shaders/monkey_frame.wgsl"); // MONKEY (p0 fog hook): `benilla::fog_hook`, the one distance-fog law all seven receivers call. load_shader_library!(app, "shaders/fog_hook.wgsl"); + // MONKEY (wet): `benilla::wet_hook`, the rain-on-surfaces look terrain/model/static_gx call. + load_shader_library!(app, "shaders/wet_hook.wgsl"); // MONKEY (enhanced water): the optional water module, `benilla::enhanced_water` (WATER.md). load_shader_library!(app, "shaders/enhanced_water.wgsl"); } diff --git a/crates/benilla-assets/src/shaders/wet_hook.wgsl b/crates/benilla-assets/src/shaders/wet_hook.wgsl new file mode 100644 index 00000000..9a4032b2 --- /dev/null +++ b/crates/benilla-assets/src/shaders/wet_hook.wgsl @@ -0,0 +1,93 @@ +#define_import_path benilla::wet_hook + +// MONKEY (wet): rain on surfaces — the ONE place the wet look is computed (the `shadow_hook.wgsl` +// pattern). Receivers (terrain, static_gx, wow_model) call it with one-line hooks and pass the +// MonkeyFrame (its `wet_a` row: `rain_rate, wetness, ripple_time_s, snow`, written by +// `benilla-world/src/weather/wetness.rs`). A zero wetness (dry weather, or `rainSurfaces 0`) returns +// the inputs untouched, so the dry image is bit-identical. +// +// Sky exposure, phase 1: the receiver passes `exposure` = 0 for interior-class / unlit / emissive +// surfaces and 1 otherwise; the normal then takes undersides out (dry), walls half wet, tops fully +// wet and glossy. There is no rain-occlusion map yet, so an exterior surface under a porch or a +// bridge still reads wet. + +#import benilla::monkey_frame::MonkeyFrame + +struct WetSurface { + albedo: vec3, + // Gloss weight for `wet_sheen`: 0 dry, ~1 a soaked top face, up to ~1.6 in a terrain puddle. + boost: f32, +} + +// How wet a surface is from its facing: none below, half on walls, full on tops. +fn wet_amount(n: vec3, exposure: f32, wetness: f32) -> f32 { + let facing = smoothstep(-0.2, 0.25, n.y); + return clamp(wetness, 0.0, 1.0) * clamp(exposure, 0.0, 1.0) * facing + * mix(0.5, 1.0, smoothstep(0.3, 0.8, n.y)); +} + +// Wet albedo: darker (water fills the micro-pores) and a touch more saturated; the gloss weight +// is kept for up-facing faces only. +fn wet_surface(albedo: vec3, n: vec3, world_pos: vec3, exposure: f32, + mf: MonkeyFrame) -> WetSurface { + let wet0 = mf.wet_a; + var o: WetSurface; + o.albedo = albedo; + o.boost = 0.0; + if (wet0.y <= 0.0 || exposure <= 0.0) { + return o; + } + let w = wet_amount(n, exposure, wet0.y); + let luma = dot(albedo, vec3(0.299, 0.587, 0.114)); + let sat = max(mix(vec3(luma), albedo, 1.0 + 0.3 * w), vec3(0.0)); + o.albedo = sat * (1.0 - 0.36 * w); + o.boost = w * smoothstep(0.35, 0.9, n.y); + return o; +} + +fn wet_hash(p: vec2) -> f32 { + let q = fract(p * vec2(0.1031, 0.1030)); + let r = q + dot(q, q.yx + 33.33); + return fract((r.x + r.y) * r.x); +} + +fn wet_noise(p: vec2) -> f32 { + let i = floor(p); + let f = fract(p); + let u = f * f * (3.0 - 2.0 * f); + return mix(mix(wet_hash(i), wet_hash(i + vec2(1.0, 0.0)), u.x), + mix(wet_hash(i + vec2(0.0, 1.0)), wet_hash(i + vec2(1.0, 1.0)), u.x), u.y); +} + +// Terrain bonus: puddle patches on flat ground once it is well soaked — darker, and a stronger +// gloss weight so they read as standing water catching the sky. +fn wet_puddles(s: WetSurface, n: vec3, world_pos: vec3, mf: MonkeyFrame) -> WetSurface { + let wet0 = mf.wet_a; + var o = s; + if (wet0.y <= 0.0) { + return o; + } + let xz = world_pos.xz; + let field = 0.65 * wet_noise(xz * 0.11) + 0.35 * wet_noise(xz * 0.43 + 17.0); + let level = smoothstep(0.94, 0.99, n.y); + // Puddles grow with the wetness: the threshold falls as the ground soaks. + let edge = mix(0.8, 0.6, smoothstep(0.4, 1.0, wet0.y)); + let puddle = smoothstep(edge, edge + 0.06, field) * level * smoothstep(0.35, 0.8, wet0.y); + o.albedo = o.albedo * (1.0 - 0.4 * puddle); + o.boost = max(o.boost, 1.6 * puddle); + return o; +} + +// The wet sheen, added to the lit gamma colour: a tight sun highlight (shadowed) and a Fresnel +// reflection of the sky/fog colour. Zero when `boost` is zero. +fn wet_sheen(boost: f32, n: vec3, to_view: vec3, to_light: vec3, + sun_rgb: vec3, sky_rgb: vec3, shadow: f32) -> vec3 { + if (boost <= 0.0) { + return vec3(0.0); + } + let h = normalize(to_light + to_view); + let nl = max(dot(n, to_light), 0.0); + let spec = pow(max(dot(n, h), 0.0), 80.0) * smoothstep(0.0, 0.15, nl); + let fres = 0.03 + 0.97 * pow(1.0 - clamp(dot(n, to_view), 0.0, 1.0), 5.0); + return boost * (sun_rgb * (0.9 * spec * shadow) + sky_rgb * (0.28 * fres)); +} diff --git a/crates/benilla-world/src/weather/mod.rs b/crates/benilla-world/src/weather/mod.rs index d2a1e144..09548546 100644 --- a/crates/benilla-world/src/weather/mod.rs +++ b/crates/benilla-world/src/weather/mod.rs @@ -16,6 +16,8 @@ use bevy::prelude::*; use crate::dev_state::DebugState; mod precip; +mod wetness; // MONKEY (wet): surface wetness + the rain-ripple clock -> MonkeyFrame wet0 +pub use wetness::{RainSurfaces, Wetness}; /// Rain's forced-fog window, read by the effect lane's `EffectFog::Rain` row. pub(crate) use precip::{RAIN_FOG_END, RAIN_FOG_START}; @@ -309,6 +311,7 @@ impl Plugin for WeatherPlugin { .add_message::() .add_systems(Update, weather_tick.in_set(WeatherTick)); precip::register(app); + wetness::register(app); // MONKEY (wet) } } diff --git a/crates/benilla-world/src/weather/wetness.rs b/crates/benilla-world/src/weather/wetness.rs new file mode 100644 index 00000000..caa9c4e2 --- /dev/null +++ b/crates/benilla-world/src/weather/wetness.rs @@ -0,0 +1,168 @@ +//! MONKEY (wet): surface wetness from the zone weather, published in the MonkeyFrame `wet_a` row +//! (`rain_rate, wetness, ripple_time_s, snow`). +//! +//! - `rain_rate` is channel A's effect density while the effect is rain (already ramped ~10 s by +//! the weather channel), else 0. +//! - `wetness` rises while it rains (full in about 90 s at full rain, slower in a drizzle) and +//! dries after it stops (about 4 min from soaked). It runs on real time, like the channels. +//! - `ripple_time_s` is the rain-ripple clock (wraps every [`RIPPLE_WRAP_S`] s; the shader's ring +//! rates are chosen so the wrap is seamless). +//! - `snow` is reserved (0). +//! +//! The `rainSurfaces` cvar ([`RainSurfaces`]) gates the whole row: off writes zeros, and every +//! shader reader treats a zero row as "dry", so the image is unchanged. +//! +//! Capture knobs: `WOW_RAIN_SURFACES=0|1` overrides the cvar; `WOW_WETNESS=<0..1>` pins the +//! wetness (a capture cannot wait minutes for the ramp); `WOW_WET_T=` pins the ripple clock. + +use bevy::prelude::*; + +use super::{WeatherKind, WeatherState, WeatherTick}; +use crate::lighting::MonkeyFrame; + +/// The `rainSurfaces` cvar: 0 Off (no wet surfaces, no rain ripples), 1 On. benilla-app's +/// settings bridge (`monkey_gfx.rs`) writes it. +#[derive(Resource, Clone, Copy, Debug, PartialEq, Eq)] +pub struct RainSurfaces(pub bool); + +impl Default for RainSurfaces { + fn default() -> Self { + Self(true) + } +} + +/// Seconds from dry to soaked under full rain. +const WET_UP_S: f32 = 90.0; +/// Seconds from soaked to dry once the rain stops. +const DRY_S: f32 = 240.0; +/// The ripple clock's wrap. The shader's ring rates are multiples of 1/`RIPPLE_WRAP_S`, so every +/// ring's phase is continuous across the wrap. +pub const RIPPLE_WRAP_S: f32 = 1000.0; + +/// The wetness integrator's state. +#[derive(Resource, Default, Debug, Clone, Copy)] +pub struct Wetness { + pub wetness: f32, + pub ripple_time_s: f32, +} + +impl Wetness { + /// One real-time step. `rain` is the rain rate 0..1 (0 when not raining). + fn step(&mut self, rain: f32, dt: f32) { + if rain > 0.0 { + // A drizzle wets slower and never quite soaks. + let target = 0.55 + 0.45 * rain.min(1.0); + let rate = (0.35 + 0.65 * rain.min(1.0)) / WET_UP_S; + if self.wetness < target { + self.wetness = (self.wetness + rate * dt).min(target); + } else { + self.wetness = (self.wetness - dt / DRY_S).max(target); + } + } else { + self.wetness = (self.wetness - dt / DRY_S).max(0.0); + } + self.ripple_time_s = (self.ripple_time_s + dt) % RIPPLE_WRAP_S; + } +} + +fn env_f32(key: &str) -> Option { + std::env::var(key).ok()?.trim().parse().ok() +} + +/// The session-only overrides, read once. +struct EnvOverrides { + on: Option, + wetness: Option, + ripple_t: Option, +} + +fn env_overrides() -> &'static EnvOverrides { + static ENV: std::sync::OnceLock = std::sync::OnceLock::new(); + ENV.get_or_init(|| EnvOverrides { + on: env_f32("WOW_RAIN_SURFACES").map(|v| v >= 0.5), + wetness: env_f32("WOW_WETNESS").map(|v| v.clamp(0.0, 1.0)), + ripple_t: env_f32("WOW_WET_T"), + }) +} + +fn wetness_tick( + time: Res>, + state: Res, + cvar: Res, + mut wet: ResMut, + mut frame: ResMut, +) { + let env = env_overrides(); + let rain = if state.effect_kind == WeatherKind::Rain { + state.effect_density.clamp(0.0, 1.0) + } else { + 0.0 + }; + wet.step(rain, time.delta_secs()); + let on = env.on.unwrap_or(cvar.0); + let (rate, wetness, ripple) = if on { + ( + rain, + env.wetness.unwrap_or(wet.wetness), + env.ripple_t.unwrap_or(wet.ripple_time_s), + ) + } else { + (0.0, 0.0, 0.0) + }; + // Write only on change, so change detection on the frame stays meaningful. + if frame.rain_rate != rate || frame.wetness != wetness || frame.ripple_time_s != ripple { + frame.rain_rate = rate; + frame.wetness = wetness; + frame.ripple_time_s = ripple; + frame.snow = 0.0; + } +} + +pub(super) fn register(app: &mut App) { + app.init_resource::() + .init_resource::() + .add_systems(Update, wetness_tick.after(WeatherTick)); +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn full_rain_soaks_in_about_ninety_seconds_and_dries_in_four_minutes() { + let mut w = Wetness::default(); + for _ in 0..(89 * 10) { + w.step(1.0, 0.1); + } + assert!(w.wetness > 0.95 && w.wetness < 1.0, "{}", w.wetness); + for _ in 0..(20 * 10) { + w.step(1.0, 0.1); + } + assert_eq!(w.wetness, 1.0); + for _ in 0..(120 * 10) { + w.step(0.0, 0.1); + } + assert!((w.wetness - 0.5).abs() < 0.01, "half dry at 2 min: {}", w.wetness); + for _ in 0..(121 * 10) { + w.step(0.0, 0.1); + } + assert_eq!(w.wetness, 0.0); + } + + #[test] + fn a_drizzle_never_quite_soaks() { + let mut w = Wetness::default(); + for _ in 0..(600 * 10) { + w.step(0.2, 0.1); + } + assert!((w.wetness - 0.64).abs() < 1e-4, "{}", w.wetness); + } + + #[test] + fn the_ripple_clock_wraps() { + let mut w = Wetness::default(); + w.ripple_time_s = RIPPLE_WRAP_S - 0.05; + w.step(0.0, 0.1); + assert!(w.ripple_time_s < 0.1); + } +}