Atmosphere as entity migration guide (#23675)

# Objective

- Once PR #23651 is merged we need a migration guide for breaking
changes to Bevy's atmosphere.
- Post the release note changes as a new PR to review grammar/writing
separately

## Solution

- Write a migration guide detailing the breaking changes
- Adhere to a friendly non-technical tone 
- Explain the new way of scaling the atmosphere with `Transform`

## Out of scope
- Explain how to customize the apparent up axis (i.e. horizon's
orientation) -> this should follow intuitively but maybe I should add
this too? or maybe this belongs in a release note instead?
This commit is contained in:
Máté Homolya
2026-04-06 16:38:14 -07:00
committed by GitHub
parent a026ab9b84
commit 437d982e1d
@@ -0,0 +1,48 @@
---
title: "`Atmosphere` is now an entity"
pull_requests: [23651]
---
Previously, the `Atmosphere` component was added on the camera. Instead,
spawn an `Atmosphere` as an entity. The nearest atmosphere will be chosen for rendering.
`AtmosphereSettings` still belongs on the camera. It is the component that enables atmosphere rendering for that view.
The `scene_units_to_m` field has been removed from `AtmosphereSettings`. Use `Transform` on the `Atmosphere` entity for scale. It is inversely proportional to the old `scene_units_to_m` factor. For example, to treat one unit as 1 km (as with `scene_units_to_m: 1000.0`), set scale to `0.001`.
```rust
// 0.18
commands.spawn((
Camera3d::default(),
Atmosphere::earth(earth_medium),
AtmosphereSettings {
scene_units_to_m: 1000.0,
..default()
},
));
```
```rust
// 0.19
let earth = Atmosphere::earth(earth_medium);
let scale = 0.001;
commands.spawn((
earth,
Transform::from_scale(Vec3::splat(scale)).with_translation(-Vec3::Y * earth.inner_radius * scale),
));
commands.spawn((
Camera3d::default(),
AtmosphereSettings::default(),
));
```
If you don't need to customize the scale, a default `Transform` component is added that positions the atmosphere such that the horizon lines up with the camera's default Y-up direction.
```rust
commands.spawn(Atmosphere::earth(earth_medium));
```
The `bottom_radius` and `top_radius` fields on the `Atmosphere` component have been renamed to `inner_radius` and `outer_radius` respectively to reflect their new meaning.
See the updated atmosphere example and documentation for details.