Rain and wetness

a GPU downpour over a rain-slicked courtyard.

▶ Run in browser

Tags: 3d rain wetness weather particles

Two cooperating halves of the weather system, both driven by one WorldEnvironment. A Rain3D emitter (a camera-relative GPU particle volume that reuses the particle simulation) fills the view with wind-slanted droplets. The same WorldEnvironment publishes wetness / rain_intensity / ripple_strength into the FrameGlobals block, so every material flagged wetness_affected darkens, turns glossy (roughness drops), and grows an animated ripple normal on its up-facing faces. Turn the weather off (all three back to zero, no Rain3D) and the scene renders exactly as a dry one: the wet path is feature-bit + wetness gated, so it costs nothing when unused.

The wide floor and the low blocks are wetness_affected; the sun rakes across them so the wet gloss and the puddle ripples catch the light, while the drops slant with the wind.

Usage: uv run python examples/features/3d/rain.py

Source

"""Rain and wetness: a GPU downpour over a rain-slicked courtyard.

Two cooperating halves of the weather system, both driven by one
WorldEnvironment. A Rain3D emitter (a camera-relative GPU particle volume that
reuses the particle simulation) fills the view with wind-slanted droplets. The
same WorldEnvironment publishes ``wetness`` / ``rain_intensity`` /
``ripple_strength`` into the FrameGlobals block, so every material flagged
``wetness_affected`` darkens, turns glossy (roughness drops), and grows an
animated ripple normal on its up-facing faces. Turn the weather off (all three
back to zero, no Rain3D) and the scene renders exactly as a dry one: the wet path
is feature-bit + wetness gated, so it costs nothing when unused.

The wide floor and the low blocks are ``wetness_affected``; the sun rakes across
them so the wet gloss and the puddle ripples catch the light, while the drops
slant with the wind.

# /// simvx
# tags = ["3d", "rain", "wetness", "weather", "particles"]
# screenshot_frame = 40
# ///

Usage:
    uv run python examples/features/3d/rain.py
"""

import numpy as np

from simvx.core import (
    Camera3D,
    DirectionalLight3D,
    Input,
    InputMap,
    Key,
    Material,
    Mesh,
    MeshInstance3D,
    Node,
    Rain3D,
    WorldEnvironment,
)
from simvx.graphics import App

WIDTH, HEIGHT = 1280, 720


def _flagstone_maps(size: int = 512, cells: int = 6, seed: int = 7) -> tuple[np.ndarray, np.ndarray]:
    """Procedural wet-flagstone albedo + matching normal map (no asset files).

    A grid of stone tiles separated by recessed mortar grooves; each tile is
    tinted and shaded a little differently and carries a fine grain, so the wet
    floor reads as real paving rather than a flat sheet. The normal map lifts the
    grooves into relief so the rain gloss and ripples catch the raked sun.
    Deterministic (fixed seed) so the golden frame stays stable. The tile grid is
    an integer lattice, so tiling the texture with ``uv_scale`` stays seamless
    (the wrap seam lands on a mortar line). Returns ``(albedo_rgba, normal_rgb)``.
    """
    rng = np.random.default_rng(seed)
    # Cell coordinates: 0..cells across the texture; integer part = tile id,
    # fractional part = position within the tile.
    axis = np.linspace(0.0, cells, size, endpoint=False, dtype=np.float32)
    vv, uu = np.meshgrid(axis, axis, indexing="ij")
    ci = np.floor(uu).astype(np.int32)
    cj = np.floor(vv).astype(np.int32)
    fu, fv = uu - ci, vv - cj

    # Mortar grooves: ramp from 0 inside the groove to 1 on the stone top.
    edge = np.minimum(np.minimum(fu, 1.0 - fu), np.minimum(fv, 1.0 - fv))
    mortar_w = 0.05
    stone = np.clip((edge - mortar_w) / mortar_w, 0.0, 1.0)

    # Per-tile variation: mostly brightness with a slight warm/cool shift, so the
    # stones stay a natural grey rather than a saturated patchwork. Plus fine grain.
    bright = rng.uniform(0.72, 1.08, size=(cells, cells)).astype(np.float32)
    warm = rng.uniform(-0.03, 0.03, size=(cells, cells)).astype(np.float32)
    grain = rng.uniform(-0.045, 0.045, size=(size, size)).astype(np.float32)

    base = np.array([0.5, 0.49, 0.48], dtype=np.float32)
    col = base[None, None, :] * bright[ci, cj][..., None]
    col[..., 0] += warm[ci, cj]  # warm tiles lean red
    col[..., 2] -= warm[ci, cj]  # ...and away from blue
    col += grain[..., None]
    col *= (0.5 + 0.5 * stone)[..., None]  # darken the grooves
    albedo = np.empty((size, size, 4), dtype=np.uint8)
    albedo[..., :3] = (np.clip(col, 0.0, 1.0) * 255.0 + 0.5).astype(np.uint8)
    albedo[..., 3] = 255

    # Height = raised stone tops, recessed grooves; normal from its gradient.
    # Wrapped central differences keep the map seamless so no bright seam line
    # shows up where ``uv_scale`` tiles the texture.
    height = stone.astype(np.float32)
    gx = (np.roll(height, -1, axis=1) - np.roll(height, 1, axis=1)) * 0.5
    gy = (np.roll(height, -1, axis=0) - np.roll(height, 1, axis=0)) * 0.5
    n = np.stack([-gx * 3.5, -gy * 3.5, np.ones_like(height)], axis=-1)
    n /= np.linalg.norm(n, axis=-1, keepdims=True)
    normal = np.empty((size, size, 4), dtype=np.uint8)
    normal[..., :3] = ((n * 0.5 + 0.5) * 255.0 + 0.5).astype(np.uint8)
    normal[..., 3] = 255
    return albedo, normal


class RainScene(Node):
    def on_ready(self):
        InputMap.add_action("quit", [Key.ESCAPE])

        # One WorldEnvironment drives both halves: it enables the HDR chain, sets
        # the wind that slants the rain, and publishes the wetness/rain/ripple
        # weather values into FrameGlobals that the wet materials read.
        env = self.add_child(WorldEnvironment())
        env.wind_direction = (0.6, 0.8)
        env.wind_strength = 0.5
        env.wetness = 0.9
        env.rain_intensity = 0.85
        env.ripple_strength = 0.7

        self.add_child(Camera3D(position=(0, 3.4, 9.5), look_at=(0, 0.3, -1.0), up=(0, 1, 0)))
        sun = self.add_child(DirectionalLight3D(intensity=3.2))
        sun.direction = (-0.55, -0.85, -0.3)

        # Rain-slicked flagstone courtyard: a procedural paving albedo + normal
        # map give the floor real stone detail, and the wetness_affected material
        # darkens it, turns it glossy, and rings its up-facing top with rain.
        floor_albedo, floor_normal = _flagstone_maps()
        self.add_child(
            MeshInstance3D(
                mesh=Mesh.cube(1.0),
                material=Material(
                    colour=(1.0, 1.0, 1.0, 1.0),
                    roughness=0.8,
                    albedo_map=floor_albedo,
                    normal_map=floor_normal,
                    uv_scale=(7.0, 6.5),
                    wetness_affected=True,
                ),
                position=(0, -0.5, -4.0),
                scale=(28.0, 1.0, 26.0),
            )
        )

        # Low blocks scattered across the floor: also wet, so their tops gloss and
        # ripple while their sides just darken (the ripple is up-facing only).
        for x, z, colour in [
            (-3.2, -2.0, (0.70, 0.30, 0.28)),
            (2.8, -3.5, (0.30, 0.55, 0.72)),
            (0.2, -5.5, (0.60, 0.58, 0.35)),
            (-1.6, -6.5, (0.40, 0.62, 0.42)),
        ]:
            self.add_child(
                MeshInstance3D(
                    mesh=Mesh.cube(1.0),
                    material=Material(colour=(*colour, 1.0), roughness=0.75, wetness_affected=True),
                    position=(x, 0.4, z),
                    scale=(1.6, 0.8, 1.6),
                )
            )

        # The downpour: a camera-relative GPU particle volume, wind-slanted.
        self.add_child(Rain3D(radius=16.0, height=10.0, fall_speed=24.0, amount=8000))

    def on_update(self, dt):
        if Input.is_action_pressed("quit"):
            self.app.quit()


def main():
    App(width=WIDTH, height=HEIGHT, title="SimVX - Rain").run(RainScene())


if __name__ == "__main__":
    main()