blender-weather-fx

Weather FX

执行模型位于 blender-core。天空、太阳／月亮、雾和氛围来自 blender-time-of-day，因此先运行 scene_mood.py，再添加天气效果。渲染设置位于 blender-rendering。

每项调用一次

scripts/precipitation.py -- --type rain --intensity heavy --ground Street Roofs --wind 2 0
scripts/surface_weather.py -- --objects Street Car Walls --wetness 0.7 --puddles 0.4 --ripples 1 --streaks 0.5
scripts/lightning.py -- --flashes 2 --strokes 3
scripts/precipitation.py -- --type snow --intensity moderate --ground Terrain
scripts/surface_weather.py -- --objects Terrain Roofs --snow 0.8 --snow-depth 0.06
scripts/surface_weather.py -- --objects Street Car Walls --remove     # exact restore

雨夜：scene_mood.py --time night --fog-visibility 250 → 降雨 → 湿润表面 + 积水 → 闪电。夜间的降雨和积水最能营造湿润场景：湿润表面会反射所有实景灯光。

precipitation.py（雨、雪、尘土、灰烬、余烬）

• 在 ENV_Weather_<Type> 上构建 GN 修改器。其范围覆盖摄像机在整个帧范围内看到的区域：固定于世界空间，因此移动摄像机不会拖动雨滴。没有摄像机时，覆盖 18 m 的范围。地面高度取 --ground 中最低物体的顶部。
• 无模拟的无缝循环：每个粒子在每次循环中存活 N 个完整周期（Lives），因此最后一帧 + 1 与第一帧完全一致。可独立渲染任意帧，也支持无头模式。
• 真实速度：雨为 7 m/s（强降雨／暴风雨时为 9），雪为 1，灰烬为 0.6，尘土为 0.15，余烬以 1.5 的速度上升，并与 --wind X Y（m/s）组合。
• 地面：对 --ground 对象进行射线检测，粒子在首次命中处停止（屋顶、遮阳篷、街道）。雨滴会在每个命中点生成持续 80 ms 的飞溅冠，并与表面法线对齐。
• 条纹，而非运动模糊：雨滴是三边形条纹，长度 = 速度 × 半帧（180° 快门），并与运动方向对齐。关闭运动模糊更省资源，效果也相同。
• 距摄像机小于 1.5 m 的粒子会被隐藏（Near Clear），因为巨大的雨滴会毁掉画面。视口显示 10%（Viewport Fraction），渲染显示 100%。
• 按强度设置密度（粒子数/m³）：雨为 5/15/40/80，雪为 10/30/80/160。使用 --density 覆盖。数量上限由 --max-count（400k）控制，达到上限时会发出警告。
• 所有值仍是修改器输入项（Count、Speed、Wind、Lives、Particle Size、Streak Length、Sway、Ground、Splash...），可直接在其中调整，无需重新运行。

surface_weather.py（湿润、积水、涟漪、条纹、积雪）

• 在每个 Principled BSDF 前插入一个 ENV_Weather 着色器组，并在材质上记录原始设置。--remove 会精确恢复连接和数值。
• 湿润效果（Lagarde 模型）：多孔表面的反照率最多降低 55% × --porosity，粗糙度降低，并以 Coat 添加水膜。沥青、混凝土、木材和织物使用 0.6–0.9 的孔隙率；金属、玻璃和塑料使用 0.1–0.2。
• 积水：在朝上的面上应用域扭曲的世界空间噪声。覆盖率 ≈ --puddles，特征尺寸为 --scale（m，默认 3）。积水区域内：完整涂层、镜面涂层粗糙度为 0.02，且基础法线会被压平，因为水会填满裂缝。
• 涟漪：扩散的环形波纹，每个约 17 cm 的网格单元生成一个，由 frame 驱动器控制（简单表达式，因此无需自动运行脚本也能工作）。涟漪只会在积水中显示。
• 条纹：墙面上的垂直噪声会形成涂层流痕。
• 积雪：朝上的表面会出现带噪声边缘的覆盖层，反照率为 0.9、粗糙度为 0.6，并带有细微凹凸。--snow-depth 会通过 ENV_SnowCover GN 修改器添加实际厚度：朝上的面会被细分并向上挤出，挤出高度由永不为零的噪声决定，因此不会发生 z-fighting。使用带次表面效果的 ENV_M_Snow 材质。
• --vertex-mask 会写入 ENV_Weather 颜色属性（R 表示积水，G 表示积雪，B 表示墙面），供引擎着色器使用。

lightning.py

• 一次闪电包含 3 次回击，间隔约 50 ms（至少相隔 2 帧，因此在 24 fps 下闪烁效果清晰），每次回击先达到峰值，再衰减 2 帧。--strokes、--flashes 或 --frames 可设置时间安排。闪光由冷色的 ENV_Storm_Flash 太阳光产生（12° 柔光），并以场景主光 ×2.5 的强度进行关键帧设置。
• ENV_Storm_Bolt 是带分支的自发光曲线（中点位移加 4 个分支），与闪光同步设置关键帧。默认位于 300 m 外、画面内且偏离中心。世界背景强度也会随闪光变化（使用 --no-sky 跳过）。
• 关键帧使用 LINEAR 插值（闪光必须瞬间切换，不能渐变）。

规则

• 只有在深色背景前受到背光或侧光照射时，雨才看得见：在雨后方放置实景光源或明亮的天空。正面照亮的雨会消失。
• 组合多个层次：雾气（氛围）+ 雨丝（中景）+ 飞溅/涟漪（地面）+ 潮湿反光。单独使用任何一种效果都会显得虚假。
• 必须采用真实比例：速度、密度和水坑大小都以米为单位（blender-scene-setup）。
• 使用最终分辨率进行渲染检查。视口中看不到雨的密度和雨丝的可见度（数量为 10%，且没有雾气）。
• 如果要导出雪的几何体，请对其运行 blender-asset-qa。

游戏和实时渲染

天气是引擎系统（Unreal Niagara、Unity VFX Graph、Roblox ParticleEmitter）。从 Blender 导出遮罩：顶点颜色属性（--vertex-mask）或烘焙纹理（使用 blender-texture-baking 自行烘焙潮湿材质），以及积雪覆盖网格。详情见 references/realtime-engines.md。物理数值和外观库见 references/weather-values.md。

注意事项

• GN 粒子是实例，因此 object.data 为空。请通过求值后的依赖图（depsgraph.object_instances）读取结果。
• 后台（-b）求值会被 Is Viewport 节点视为视口，因此无头测试只会显示 10% 的数量。渲染时则为 100%。
• 地面对象会链接到 ENV_Weather_<Type>_Ground 集合中（仅链接，不移动）。
• surface_weather 会更改共享材质：所有使用该材质的对象都会变湿。请先复制材质以限制影响范围。
• 两种引擎都会显示涂层。EEVEE 需要启用光线追踪（eevee.use_raytracing），才能获得良好的水坑反射。