bsn: improve docs and add tests by laundmo · Pull Request #24464 · bevyengine/bevy

laundmo · 2026-05-27T22:23:50Z

Objective

Improve documentation of bevy_scene/bsn.

Rendered: https://share.yadamiel.com/docs/doc/bevy/scene/index.html

Closes: #24299
Closes: #24540
Closes: #24541

Solution

This PR depends on/includes changes from

bsn: fix accidental scene entity deduplication due to name references #24402

Docs changes (approx)

removing confusing Inheritance concept in favour of caching
- BSN: changing prefixes for Template and SceneComponent to allow removing confusing "inheritance" concept #24367
fix now-changed syntax
- BSN: changing prefixes for Template and SceneComponent to allow removing confusing "inheritance" concept #24367
cleaning up the duplication between macro docs and module docs
clean up the syntax snippet to be a single table
a bunch of smaller fixes

Testing

cargo doc -Zrustdoc-mergeable-info -p bevy_scene --lib locally works fine
the other cargo doc command also works fine (see cargo.toml diff for full command, its ugh)

Todo

show how scenes actually get evaluated, not a full expansion but a rough idea of it
come up with something better for the macro inline docs than a complex example macro call
probably remove the bsn: fix accidental scene entity deduplication due to name references #24402 commits again, they're annoying to have in the history

laundmo · 2026-05-29T01:11:57Z

~~Note to self: Document #24469~~ done

Co-authored-by: Carter Anderson <mcanders1@gmail.com>

alice-i-cecile · 2026-06-03T20:27:13Z

-//! both would supply a [`FromTemplate`] impl and conflict.
-//! You still have access to a default constructor of sorts though: the derive generates a companion
-//! `YourTypeTemplate` struct that implements `Default`, so `YourTypeTemplate::default()` serves the same purpose.
+//! For this reason, there is a custom "derive" which isn't actually a Trait, called [`VariantDefaults`](bevy_ecs::VariantDefaults)


This is very confusing to read; I think we're leaking implementation details here.

Perhaps, tho it feels like it needs to, otherwise people will go looking for the VariantDefaults trait which is just not a thing. I've tried re-wording it a bit.

alice-i-cecile · 2026-06-03T20:29:15Z

-//!
-//! For a quick rundown on how to read and write BSN syntax,
-//! see the docs for [`bsn!`].
+//! We plan on making "conditional scenes" easier to define in future releases.


Issue link would be nice, but I don't think one currently exists?

alice-i-cecile

A fair bit of clean up to do, but a marked improvement.

Moving from "inheritance" to "caching" has clarified a tremendous number of things for me.

Co-authored-by: Carter Anderson <mcanders1@gmail.com>

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

…r-docs

laundmo · 2026-06-06T16:27:39Z

Note: This PR does not include docs for any of the new features and syntax @cart made PRs for after I un-Draft-ed this.

alice-i-cecile

Fixed a failing test in the last commit: I stared at it for quite a bit and came to the conclusion that it was simply asserting the wrong thing. That should be passing CI soon. IMO we should merge this in ASAP, and refine further in follow-up (such as for those new features).

Trashtalk217

Some notes, take what you need.

Trashtalk217 · 2026-06-07T21:50:18Z

+//! Enums are special-cased to allow for better implicit defaults: [`bsn!`] requires that enums have defaults for all variant arms, not just the type as a whole.
+//!
+//! When [`bsn!`] encounters a Enum, it will try to get the default value for the variant using static methods like `default_{variant_lower}`.
+//! To help with setting up these methods, theres a pseudod-`derive` called [`VariantDefaults`](bevy_ecs::VariantDefaults).


Suggested change

//! To help with setting up these methods, theres a pseudod-`derive` called [`VariantDefaults`](bevy_ecs::VariantDefaults).

//! To help with setting up these methods, theres a pseudo-`derive` called [`VariantDefaults`](bevy_ecs::VariantDefaults).

Trashtalk217 · 2026-06-07T21:51:23Z

 //! [`Scene`], so patches from multiple sources merge into a single [`ResolvedScene`].
 //!
-//! For programmatic patching outside of [`bsn!`], see the [`PatchFromTemplate`] and
+//!  For programmatic patching outside of [`bsn!`], see the [`PatchFromTemplate`] and


Suggested change

//! For programmatic patching outside of [`bsn!`], see the [`PatchFromTemplate`] and

//! For programmatic patching outside of [`bsn!`], see the [`PatchFromTemplate`] and

Trashtalk217 · 2026-06-07T22:07:55Z

+/// | `@MySceneComp { @prop: val }`              | Include a [`SceneComponent`] with a `prop` field, passed to this components scene function                     |
+/// | `@MySceneComp { name: val }`               | Include a [`SceneComponent`] with a normal field, works the same as it does for normal components              |
+/// | `@MySceneComp { @prop: val1, name: val2 }` | Include a [`SceneComponent`] with both a `prop` and a field                                                    |
+/// | `:"scene.bsn"`                             | <div class="warning">Asset format no yet implemented!</div> Include a cached scene asset file                  |


Trashtalk217 · 2026-06-07T22:08:58Z

+/// | `on(my_observer)`                          | Attaches an entity [`observer`] for the [`EntityEvent`] `Ev` to this entity. In this example, using a function |
+/// | **Relationships**                          |                                                                                                                |
+/// | `Children []`                              | Spawns each entry as a child of this entity, see **Scene Lists** below for details                             |
+/// | `ChildOf(entity)`                          | Makes **this** entity a child of `entity`, accepts a [`Entity`] or a `#Name` reference ([`EntityTemplate`])    |


Suggested change

/// | `ChildOf(entity)` | Makes **this** entity a child of `entity`, accepts a [`Entity`] or a `#Name` reference ([`EntityTemplate`]) |

/// | `ChildOf(entity)` | Makes **this** entity a child of `entity`, accepts an [`Entity`] or a `#Name` reference ([`EntityTemplate`]) |

Trashtalk217 · 2026-06-07T22:10:34Z

+/// | `1.1` or `-0.1` or `1.` or `-2.` | Float         | Floating point number, common types: `f32`, `f64`                                       |
+/// | `true` or `false`                | Bool          | Boolean, type: [`bool`]                                                                 |
+/// | `"somename"`                     | String        | Text, types: `String` or `&'static str`                                                 |
+/// | `"mypicture.png"`                | Asset path    | Asset, when used in a field which expects a [`Handle`] to the matching `Asset` type     |


I saw another import that just used "goblin" instead of "goblin.png" which is correct?

Trashtalk217 · 2026-06-07T22:11:21Z

+/// | `true` or `false`                | Bool          | Boolean, type: [`bool`]                                                                 |
+/// | `"somename"`                     | String        | Text, types: `String` or `&'static str`                                                 |
+/// | `"mypicture.png"`                | Asset path    | Asset, when used in a field which expects a [`Handle`] to the matching `Asset` type     |
+/// | `some(1)`                        | Function call | Calls a function with the provided arguments                                            |


Because some(1) might be confused with Some.

laundmo added 4 commits May 19, 2026 15:15

progress on docs

006bb16

further docs filing

81431d2

Merge branch 'main' of github.com:bevyengine/bevy

d8b539b

Merge branch 'main' into bsn-better-docs

085adda

laundmo changed the title ~~progress on docs~~ bsn: improve docs and add tests May 27, 2026

alice-i-cecile added this to the 0.19 milestone May 27, 2026

laundmo commented May 28, 2026

View reviewed changes

Comment thread crates/bevy_scene/src/lib.rs

laundmo added 4 commits May 28, 2026 14:47

Finish initial pass on both lib.rs

fd755c5

update and add trait tags for scenes

753395a

fix typos

85564b6

Merge remote-tracking branch 'origin/main' into bsn-better-docs

afba143

laundmo force-pushed the bsn-better-docs branch from 6c84495 to afba143 Compare May 28, 2026 12:54

alice-i-cecile added C-Docs An addition or correction to our documentation C-Code-Quality A section of code that is hard to understand or change A-Scenes Composing and serializing ECS objects labels May 31, 2026

alice-i-cecile self-requested a review May 31, 2026 16:37

alice-i-cecile added the S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged label May 31, 2026

alice-i-cecile requested a review from cart May 31, 2026 16:37

laundmo added 4 commits June 1, 2026 16:57

Merge remote-tracking branch 'origin/main' into bsn-better-docs

8f49183

Document bsn asset format can be implemented externally

b053e2f

fix macro docs

e93c154

a lot more docs improvements

462c533

laundmo marked this pull request as ready for review June 1, 2026 17:59

alice-i-cecile added S-Needs-Review Needs reviewer attention (from anyone!) to move forward and removed S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged labels Jun 1, 2026

cart reviewed Jun 2, 2026

View reviewed changes

cart and others added 3 commits June 1, 2026 17:13

Editorial pass 1

a4c7768

Update crates/bevy_scene/macros/src/lib.rs

87c3297

Co-authored-by: Carter Anderson <mcanders1@gmail.com>

Update crates/bevy_scene/macros/src/lib.rs

5eed7a1

Co-authored-by: Carter Anderson <mcanders1@gmail.com>