jonahplusplus / bevy_atmosphere

A procedural sky plugin for bevy

A procedural sky plugin for the Bevy game engine.

"basic" Example

use bevy::prelude::*;
use bevy_atmosphere::prelude::*;

fn main() {
    App::new()
        .add_plugins((DefaultPlugins, AtmospherePlugin))
        .add_system(Startup, setup)
        .run();
}

fn setup(mut commands: Commands) {
    commands.spawn((Camera3dBundle::default(), AtmosphereCamera::default()));
}

"cycle" Example

Getting Started

To learn more, read the docs or check out the examples.

For more information on the technicalities, you can check out the technical docs or check out my blog.

Bevy compatibility

bevy	bevy_atmosphere
0.13	0.9
0.12	0.8
0.11	0.7
0.10	0.6
0.9	0.5
0.8	0.4
0.7	0.3
0.6	0.1

🚧 Warning: Incompatible with WebGL 🚧

Versions 0.4 and higher break compatibility with WebGL by using a compute shader for efficiency.

bevy_atmosphere's Issues

EnvironmentMapLight

Bevy now supports EnvironmentMapLight as of 0.11.

I don't know how possible it is, but being able to derive the environment map from from the bevy_atmosphere skybox would be handy.

Clarify how the system works

I've been looking at the repo, the docs, and some examples, and I'm still unsure how the system works overall.

In previous versions before the rewrite, the plugin recalculated a camera "background" each frame, unless auto-update was disabled in which case it was calculated only once. At least I think.

In this new version, which by the way looks a lot better from what I grasped, it also seems like this is still true? But there was also some mention of "update every 50ms" somewhere, so...?

Then there's the whole "skybox" thing. My two conflicting possible understandings here are:

1. The system calculates one cube map image every so often, then save it into a texture, which is sampled every frame from a giant inverted cube representing the sky. Efficient! But requires quite a big resolution...
2. The system directly writes the atmosphere calculated into the render target of the camera reach frame. Optionally, it can also save that data into a cube map for e.g. IBL, but that cube map is not consumed by the atmosphere system. Maybe less efficient, definitely less memory, more dynamic, forward-looking!

So, not sure which one it is?

I'd be also interested to understand, for optimization purpose, when that rendering to the camera render target happens. I suspect it's not cheap, so would be best done after all opaque rendering, to leverage the depth buffer and reject as much fragments as possible.

I'm really looking forward to integrate this new version in my project, but for now I'm unsure how. Thanks! 😊

Sky doesn't work

When I updated to the new 0.8 version, I get the error ERROR bevy_asset::server: path not found: bevy_atmosphere/shaders/skybox.wgsl Which is weird because this plugin used to work when I was testing it earlier on the PR fork and I dropped a comment saying that it worked fine.

Sky sphere has wrong render order

Sometimes the scene objects are rendered BEFORE the sky sphere, which makes them totally covered by it.
Posible solution: make the radius of sky sphere tunable.

Sun & directional light do not match-up.

Here is a patch to the examples/cycle.rs file to show the issue. Shadows are turned on to help see the different angle of the directional light and the rendered Sun.

diff --git a/examples/cycle.rs b/examples/cycle.rs
index e52a5f1..4ca88ce 100644
--- a/examples/cycle.rs
+++ b/examples/cycle.rs
@@ -56,6 +56,10 @@ fn setup_environment(
     // Our Sun
     commands
         .spawn_bundle(DirectionalLightBundle {
+            directional_light: DirectionalLight {
+                shadows_enabled: true,
+                ..default()
+            },
             ..Default::default()
         })
         .insert(Sun); // Marks the light as Sun
@@ -94,7 +98,7 @@ fn setup_environment(
     // Spawn our camera
     commands
         .spawn_bundle(Camera3dBundle {
-            transform: Transform::from_xyz(5., 0., 5.),
+            transform: Transform::from_xyz(5., 0., 5.).looking_at(Vec3::new(0., 1., 0.), Vec3::Y),
             ..default()
         })
         .insert(AtmosphereCamera(None)) // Marks camera as having an atmosphere that isn't on a specific render layer

External Perspective

Hey there! 👋

Does your implementation use constant atmospheric density? You've done a great deal of preceding work here and it would be very interesting to use the Nishita implementation to provide atmospheric scattering for a spherical planetary body, where the exponential drop-off in density is quite relevant.

Do you think it would be a lot of work to support spherical bodies and viewing from the outside?

Friendly regards
Moritz

Starry starry night

How can we go about adding a night full of (flickery?) stars that is completely visible at night and slightly visible during sunrise/sunset?

Crash with latest 0.9 update

With this code:

fn daylight_cycle(mut atmosphere: AtmosphereMut<Nishita>) {
    atmosphere.sun_position = Vec3::new(1., 0.5, 0.);
}

This results in a crash with the following error:

thread 'main' panicked at /home/virx/.cargo/registry/src/index.crates.io-6f17d22bba15001f/bevy_atmosphere-0.9.0/src/pipeline.rs:370:53:
prepare_changed_settings should have took care of making AtmosphereImage.array_value Some(TextureView)
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
Encountered a panic in system `bevy_atmosphere::pipeline::queue_atmosphere_bind_group`!

If I don't modify any settings then it doesn't crash.

Support 2+ cameras (including UI)

bevy_atmosphere grabs the first camera it finds instead of the main 3D camera. This prevents using the plugin with 2+ cameras, and in particular with a main 3D camera and a UI one, which I'd argue is a rather common case.

The problem is that the camera transform query just picks any Camera:

bevy_atmosphere/src/lib.rs

Lines 104 to 110 in f85f3a5

	fn atmosphere_sky_follow(camera_transform_query: Query<&GlobalTransform, (With<Camera>, Without<Handle<AtmosphereMat>>)>, mut sky_transform_query: Query<&mut GlobalTransform, With<Handle<AtmosphereMat>>>) {
	if let Some(camera_transform) = camera_transform_query.iter().next() {
	if let Some(mut sky_transform) = sky_transform_query.iter_mut().next() {
	sky_transform.translation = camera_transform.translation;
	}
	}
	}

Instead I believe it should query the active 3D one via ActiveCameras:

fn atmosphere_sky_follow(
    camera_transform_query: Query<
        (&GlobalTransform, Entity),
        (With<Camera>, Without<Handle<AtmosphereMat>>),
    >,
    mut sky_transform_query: Query<&mut GlobalTransform, With<Handle<AtmosphereMat>>>,
    active_cameras: Res<ActiveCameras>,
) {
    if let Some(camera_3d) = active_cameras.get(CameraPlugin::CAMERA_3D) {
        if let Some(camera_3d_entity) = camera_3d.entity {
            for (camera_transform, entity) in camera_transform_query.iter() {
                if entity == camera_3d_entity {
                    if let Some(mut sky_transform) = sky_transform_query.iter_mut().next() {
                        sky_transform.translation = camera_transform.translation;
                    }
                    break;
                }
            }
        }
    }
}

I tested the fix above and can render some UI on top of the atmosphere background and 3D scene.

Bevy 0.10

Looks like this plugin isn't compatible with the just-released bevy 0.10 yet

Dark side of the moon

Would be cool if we could create an example of lighting half the world but leaving the other half in darkness.

Support for `AtmosphereCamera` in child position

The following modification of examples/basic.rs seems to not work for me:

use bevy::prelude::*;
use bevy_atmosphere::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugin(AtmospherePlugin)
        .add_startup_system(setup)
        .run();
}

#[derive(Component)]
struct Player;

fn setup(mut commands: Commands) {
    commands.spawn(Player)
        .with_children(|p| {
            p.spawn((Camera3dBundle::default(), AtmosphereCamera::default()));
        });
}

Is it not supported to have AtmosphereCamera as a child? Having the Camera as a child is often useful because it inherits the transforms of the parent Player. I am open to suggestions on how to better structure this if not supporting this is intentional.

0.4 Tracking Issue (Bevy 0.8 Update)

Edit: Changed this to a tracking issue.

0.4 update changes:

• Update dependencies to bevy 0.8 compatible versions
• Rename AtmosphereMat to Atmosphere
• Rewrite material creation
• Rewrite shaders in WGSL
  • Create exports for shader module
  • Default feature gate plugin and material resource
  • Add noise via hash function to remove banding (been a while, but I think this was an issue)
• Use texture target and update texture when resource updates
• Update LICENSE to be dual-licensed under both MIT and Apache-2.0 (optional, needs consent from prior contributors)
• Update example
• Feature gate dynamic

Black skybox when using Nishita model with a ray origin with negative components

When using the Nishita model and setting ray_origin to Vec3::new(0., -6372e3, 0.), it causes the entire skybox to go black. This also occurs when any of the 3 components are negative, not just the Y component. The expected behaviour, I believe, is that the skybox should be upside-down (at least when using Bevy's default coordinate system).

Looking at the shader, I suspect it could be being caused by the sphere-intercept function failing, as that is the only place where there is a fallback path that returns black.

Return some computed values from the share for adjusting ambient and directional lighting

Currently I am adjusting the ambient light brightness based on the directional illuminance.

I would also like to adjust the color the directional and ambient lighting so sunsets for instance become more realistic in my scene.

Would this be possible?

0.5.0 Tracking Issue

Things to do when Bevy 0.9 is released.

• Update to be 0.9 compliant

QOL changes:

• Remove AtmosphereSkyBoxMaterial (unnecessary newtype) or make it an alias (Bevy 0.9 now requires impl Resource, so the Handle can't be used directly)
• Add default procedural feature (controls whether the AtmospherePlugin adds the AtmospherePipelinePlugin) (Fixes #29)
• Add removal detection to detection feature
• Remove dithering (Bevy 0.9 now adds dithering by default) (dithering is still necessary, it seems banding still occurs)
• Explore compile time vs run time discrepancy (see more below)
• Rename compute shader "time" variables to "depth" (to make it more accurate to the source literature)
• Add more images to README

Potential Features:

• Alternative sky models (Added Gradient model)
• Night sky model (Fixes #27)

Compile time vs run time discrepancy

As more features get added in, I should put more consideration into how things are organized. Sky models, for instance, can be organized into an enum and the variants can be feature-gated. In that case, the enum should be marked non-exhaustive, so changing the variant features won't cause a compile error. Besides that, it allows for adding new sky models in the future.

On that note, I should probably see if current features can receive the same treatment (allow for changing behavior at compile time and run time) to make them more flexible.

Resource Removal Edge Case

It just randomly occurred to me that I should probably define what happens in the cases in which the Atmosphere and AtmosphereSettings resources are removed. When the resources are removed from the main app, they still exist in the render sub-app with their last values.
I think that is bad behavior; unset resources should evaluate to their default. I'm busy with school starting rn, but next week I'll work on a patch fixing this and removing ATMOSPHERE_INIT in favor of having a dynamic skybox insertion system (a removal system would have to wait till Bevy supports Removed<T> queries).

Consider adding compatibility table/badge

It's a bit unclear which version of bevy_atmosphere is compatible with which version of Bevy. I would suggest following Bevy's own Plugin Guidelines and adding a badge and/or a compatibility table to help users pick the right version of bevy_atmosphere more easily 😊

Version 0.60 will not work with bevy 0.10

error[E0412]: cannot find type AppTypeRegistry in module bevy::ecs::reflect
--> /home/ /.cargo/registry/src/index.crates.io-6f17d22bba15001f/bevy_atmosphere-0.6.0/src/collection/nishita.rs:7:10
|
7 | #[derive(Atmospheric, ShaderType, Reflect, Debug, Clone)]
| ^^^^^^^^^^^ not found in bevy::ecs::reflect
|
= note: this error originates in the derive macro Atmospheric (in Nightly builds, run with -Z macro-backtrace for more info)
help: consider importing one of these items
|
1 + use bevy::app::AppTypeRegistry;
|
1 + use crate::collection::nishita::AppTypeRegistry;
|
help: if you import AppTypeRegistry, refer to it directly
|
7 | #[derive(Atmospheric, ShaderType, Reflect, Debug, Clone)]
|

Update for bevy main branch

I'd like to check this plugin out with the latest bevy main from git (almost 0.6 afaik), and especially I'd like to check the directional light with this plugin.

Can we have a branch that updates to the latest bevy main? I'd use that directly for now, and it can be merged when bevy 0.6 ships.

Current Wasm advice is misleading

The current advice about activating a feature flag in the browser for WebGPU is not sufficient to actually use WebGPU in Bevy, since Bevy forces wgpu to use WebGL. One actually needs to depend on a fork of Bevy to run WebGPU, sadly.
I'm reporting this because I happen to have lost time to this in the past for another crate and want others not to have to dig too deep :)

Custom skybox texture?

Looking in the docs I see https://docs.rs/bevy_atmosphere/0.4.1/bevy_atmosphere/skybox/struct.SkyBoxMaterial.html which has a public field for the skybox texture. So I naively tried to just replace that texture with one of my own (obviously not going to work).

Is it possible to have a custom skybox?

0.7.0 Tracking Issue

A tracking issue for things to do for the Bevy 0.10 release.

Bevy groundwork

Some of the changes I want require Bevy support.

• Optional/Resultful System Params (to support Option<Atmosphere>) (in progress)
• Custom Asset Loading (to support loading cube textures)
• Unsized AsBindGroup (to clean up Atmospheric trait) (merged)

QOL Changes

• Create way to disable auto-rotation (#39)
• Remove mesh bloat by instancing a single skybox mesh and scale it to fit the camera far plane? (Add a new system for auto-scaling the cube to respond to changes with the camera far plane?) (Ignoring for now, will use the new system for skyboxes in 0.11)
• Add an FAQ for common problems (notably #40)
• Rename models to have a -Model suffix (See ImageModel below, Image is already a Bevy type) for consistency
• Merge RegisterAtmosphericModel into Atmospheric via Self: Sized constraint

Features

• Layer System (#41)
• Add ImageModel
• Add PBL support (merged)
• Add more accurate sky model for PBL?

Feature: Layer System

I've been brainstorming ways to support stuff like night models, basic clouds (not volumetric) and far-away environments and I think supporting layers might be a good general solution.

The problem

I want to avoid hard-coding optional features as parameters directly into bevy_atmosphere.
For example, a hard coded solution to the aforementioned stuff would be to provide background, midground and foreground parameters for optional textures. To add a cloud texture, you would just set the midground to your texture and it would be overlaid on the sky texture. However, this is limiting, as it only allows for three textures and it wouldn't support animating them.

The solution

A layer system would support layering Atmospheric models on top of each other. A layer would comprise of the model and a color for controlling tint and transparency. (It could also have a mode for dictating how layers affect underlying layers, but since layers would be rendered top-down to avoid rendering hidden pixels, it would be complicated to implement).

For example, adding a cloud texture would be adding a image model on top of a sky model (like Nishita).

Implementation Strategy

The layer system could be another Atmospheric model that accepts other models. This means it would support sub-layers since it can accept itself.

It would look something like:

Layers::new()
    .add(Nishita::default(), Color::WHITE) // maybe I should rename models to have a -Model suffix?
    .add(ImageModel::new("clouds.png"), Color::rgba(1.0, 1.0, 1.0, 0.9))

It could also have a macro (layers![]) for quickly creating it (for instance, support just passing alpha instead of an entire color).

I've been thinking (I was going to do this anyways, even before the idea of layers) of revising the structure of atmosphere shaders to look like:

fn main(position: vec3<f32>) -> vec4<f32> {
    return vec4<f32>(0.5, 0.5, 0.5, 0.5);
}

This removes a lot of boilerplate from the shader. You might be wondering where that boilerplate went, since there is no #import statement. Well, since the layer model will need a custom preprocessor to load main functions from other models, it might as well handle adding the entry point code too.

This effectively separates the model logic from the runtime, which opens the doors for creating multiple runtimes. Currently, bevy_atmosphere pre-renders the sky texture using a compute shader. This technique is slow, since it has to render the entire sky texture instead of what is just on screen, but ultimately improves performance in games where atmospheric parameters change infrequently.

However, I have seen users who need to update parameters frequently, potentially every frame. In their cases, a realtime renderer is more performant, since it only needs to render what's on screen each frame. By separating the model logic from the runtime, it allows for supporting both a pre-renderer and realtime renderer. It would be a matter of moving the workload to and from the compute pipeline and skybox shader.

Bevy 0.12

As the title suggests, bevy_atmosphere doesn't have support for bevy 0.12 yet.

Fails on WASM

You may already be aware of this, but since WebGL 2.0 isn't standard yet, web builds fail at runtime because there isn't support for compute shaders. I know you just switched over to compute shaders, but is there a way to also support wasm?

Here is the error I get:

panicked at 'wgpu error: Validation Error

Caused by:
    In Device::create_bind_group_layout
      note: label = `bevy_atmosphere_associated_bind_group_layout`
    too many bindings of type StorageTextures in stage COMPUTE, limit is 0, count was 1

Not working in bevy 0.8 in browser

Using v0.4.1 (and prior 0.8 compatible releases), I get the following runing in firefox and chrome:

panicked at 'wgpu error: Validation Error

Caused by:
    In Device::create_bind_group_layout
      note: label = `bevy_atmosphere_associated_bind_group_layout`
    too many bindings of type StorageTextures in stage COMPUTE, limit is 0, count was 1

', /Users/bit/.cargo/registry/src/github.com-1ecc6299db9ec823/wgpu-0.13.1/src/backend/direct.rs:2391:5

Stack:

Error
    at imports.wbg.__wbg_new_693216e109162396 (http://127.0.0.1:8080/app-61cea4eed552c599.js:1698:21)
    at _ZN24console_error_panic_hook4hook17he2cc4c98d98c1779E (http://127.0.0.1:8080/app-61cea4eed552c599_bg.wasm:wasm-function[9391]:0xa00de7)
    at _ZN4core3ops8function2Fn4call17hca5dc860f7bd75e4E (http://127.0.0.1:8080/app-61cea4eed552c599_bg.wasm:wasm-function[37212]:0xd5d164)
    at _ZN3std9panicking20rust_panic_with_hook17h94d65730dd207ad3E (http://127.0.0.1:8080/app-61cea4eed552c599_bg.wasm:wasm-function[15942]:0xbd5eb6)
    at _ZN3std9panicking19begin_panic_handler28_$u7b$$u7b$closure$u7d$$u7d$17h411a2cda51c5c2f3E (http://127.0.0.1:8080/app-61cea4eed552c599_bg.wasm:wasm-function[17994]:0xc3786a)
    at _ZN3std10sys_common9backtrace26__rust_end_short_backtrace17h280a719b84229705E (http://127.0.0.1:8080/app-61cea4eed552c599_bg.wasm:wasm-function[27210]:0xd28ed8)
    at rust_begin_unwind (http://127.0.0.1:8080/app-61cea4eed552c599_bg.wasm:wasm-function[23275]:0xce5740)
    at _ZN4core9panicking9panic_fmt17h2b1709d02b4266aeE (http://127.0.0.1:8080/app-61cea4eed552c599_bg.wasm:wasm-function[26186]:0xd1b22b)
    at _ZN4core3ops8function2Fn4call17h920ef82c122a8bc9E (http://127.0.0.1:8080/app-61cea4eed552c599_bg.wasm:wasm-function[16625]:0xbf9110)
    at _ZN4wgpu7backend6direct7Context12handle_error17hdde4e76247cf4280E (http://127.0.0.1:8080/app-61cea4eed552c599_bg.wasm:wasm-function[1687]:0x4ed4aa)

Is this some browser related restriction? Happy to try things if there's any suggestions.

Add "up" direction in settings

I'm using Z-up in an application, so using this plugin results in everything being rotated 90 degrees. Being able to set the up vector would be handy.

Feature: Add moon support

The sun work here is really awesome! But it'd also be really cool if there was support for a moon lighting? Like you know how the moon has a particular glow in the night sky. Maybe there'd be a default moon texture which can be opted out of or something if you want a less earth-like moon. Adding it to the cycle example would be really slick!

Rendering is slow in dymanic mode

It seems the material buffer is re-created each frame, instead of being reused and only the new content re-uploaded if necessary:

bevy_atmosphere/src/material.rs

Lines 123 to 131 in f85f3a5

	fn prepare_asset(
	extracted_asset: Self,
	(render_device, material_pipeline): &mut SystemParamItem<Self::Param>,
	) -> Result<Self::PreparedAsset, PrepareAssetError<Self>> {
	let buffer = render_device.create_buffer_with_data(&BufferInitDescriptor {
	contents: extracted_asset.as_std140().as_bytes(),
	label: None,
	usage: BufferUsages::UNIFORM | BufferUsages::COPY_DST,
	});

On a beefy developer machine I see some ~22ms frame time with bevy_atmosphere, a single cube, and a single tiny UI text showing the FPS. On a more mid-range laptop config this climbs to >50ms. Not sure this create buffer is the cause but it likely doesn't help.

Doesn't work with bevy 0.6.0

This is my Cargo.toml:

[package]
name = "projectname"
version = "0.1.0"
edition = "2021"

[dependencies]
bevy = "0.6.0"
bevy_atmosphere = "0.1.3"

And this is the error I get when running cargo run:

$ cargo run
    Updating crates.io index
error: failed to select a version for `syn`.
    ... required by package `darling_core v0.13.0`
    ... which satisfies dependency `darling_core = "=0.13.0"` of package `darling v0.13.0`
    ... which satisfies dependency `darling = "^0.13"` of package `ndk-macro v0.3.0`
    ... which satisfies dependency `ndk-macro = "^0.3.0"` of package `ndk-glue v0.5.0`
    ... which satisfies dependency `ndk-glue = "^0.5"` of package `bevy_asset v0.6.0`
    ... which satisfies dependency `bevy_asset = "^0.6.0"` of package `bevy_audio v0.6.0`
    ... which satisfies dependency `bevy_audio = "^0.6.0"` of package `bevy_internal v0.6.0`
    ... which satisfies dependency `bevy_internal = "^0.6.0"` of package `bevy v0.6.0`
    ... which satisfies dependency `bevy = "^0.6.0"` of package `projectname v0.1.0 ([my project path])`
versions that meet the requirements `^1.0.69` are: 1.0.86, 1.0.85, 1.0.84, 1.0.83, 1.0.82, 1.0.81, 1.0.80, 1.0.79, 1.0.78, 1.0.77, 1.0.76, 1.0.75, 1.0.74, 1.0.73, 1.0.72, 1.0.71, 1.0.70, 1.0.69

all possible versions conflict with previously selected packages.

  previously selected package `syn v1.0.65`
    ... which satisfies dependency `syn = "=1.0.65"` of package `bevy v0.5.0`
    ... which satisfies dependency `bevy = "^0.5"` of package `bevy_atmosphere v0.1.3`
    ... which satisfies dependency `bevy_atmosphere = "^0.1.3"` of package `projectname v0.1.0 ([my project path])`

failed to select a version for `syn` which could resolve this conflict

Create a way to disable the automatic rotation.

There should be a feature-gate and perhaps a runtime option to disable the automatic rotation. Some games have special scenarios where the skybox rotation needs to be controlled.

The sun itself?

Aas far I can see, the models don't actually depict the disk of the sun itself — just, as the name suggests, its effect on the atmosphere.

What's the best way to do this? I can calculate the proper position in the sky (there are several rust crates that have the real-world algorithms already done) — should I put a literal sphere there, or... is there a better way?