bevy_exponential_height_fog 0.1.0

Standalone exponential height fog extension for Bevy volumetric fog.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

# bevy_exponential_height_fog

Standalone Bevy extension crate that renders Unreal-style exponential height fog as a dedicated post-process pipeline.

## Bevy Version

This crate requires Bevy 0.18.1 or higher.

## Quick start

Add the crate and plugin:

```toml
[dependencies]
bevy_exponential_height_fog = { path = "crates/bevy_exponential_height_fog" }
```

```rust
use bevy::prelude::*;
use bevy_exponential_height_fog::ExponentialHeightFogPlugin;

App::new()
    .add_plugins((DefaultPlugins, ExponentialHeightFogPlugin))
    .run();
```

Add `ExponentialHeightFog` to a `Camera3d`:

```rust
use bevy::prelude::*;
use bevy_exponential_height_fog::{
    ExponentialHeightFog,
    ExponentialHeightFogDistanceMode,
    ExponentialHeightFogLayer,
};

commands.spawn((
    Camera3d::default(),
    Transform::from_xyz(0.0, 20.0, 20.0).looking_at(Vec3::ZERO, Vec3::Z),
    ExponentialHeightFog {
        enabled: true,
        fog_color: LinearRgba::new(0.5, 0.6, 0.7, 1.0),
        primary: ExponentialHeightFogLayer {
            enabled: true,
            density: 0.03,
            height_falloff: 0.55,
            height_offset: 0.0,
        },
        secondary: ExponentialHeightFogLayer {
            enabled: true,
            density: 0.01,
            height_falloff: 0.25,
            height_offset: 1.0,
        },
        distance_mode: ExponentialHeightFogDistanceMode::Camera,
        distance_reference_world_position: Vec3::ZERO,
        start_distance: 0.0,
        cutoff_distance: 30.0,
        distance_fade: 20.0,
        max_opacity: 0.9,
        min_density_weight: 0.0,
        min_fog_alpha: 0.001,
        sky_depth_threshold: 0.999999,
    },
));
```

No fog-volume entities and no shader patching are required.

## Distance modes

The distance terms (`start_distance`, `cutoff_distance`, `distance_fade`) can be evaluated from:

- `ExponentialHeightFogDistanceMode::Camera`: world point to camera position.
- `ExponentialHeightFogDistanceMode::SuppliedWorldCoordinates`: world point to `distance_reference_world_position`.

For camera-target based gameplay fog, set `distance_mode` to `SuppliedWorldCoordinates` and update `distance_reference_world_position` every frame:

```rust
fn update_fog_reference(
    mut fog_q: Query<&mut ExponentialHeightFog, With<Camera3d>>,
    target: Res<MyCameraTargetWorldPos>,
) {
    for mut fog in &mut fog_q {
        fog.distance_mode = ExponentialHeightFogDistanceMode::SuppliedWorldCoordinates;
        fog.distance_reference_world_position = target.0;
    }
}
```

## Features

- Separate render pipeline and render graph node (no Bevy shader overrides).
- Per-camera fog settings via `ExponentialHeightFog` component.
- Primary and secondary exponential height layers.
- Start/cutoff distance shaping.
- Max opacity and small-cost early-out optimization parameters.
- Automatic camera requirements:
  - `DepthPrepass` is required by the fog component.
  - depth texture usage is configured by the plugin.

## Public API

- `ExponentialHeightFogPlugin`
- `ExponentialHeightFog`
- `ExponentialHeightFogDistanceMode`
- `ExponentialHeightFogLayer`

## License

MIT License