Bevy's Next Generation Scene/UI System

[cart]

Preamble

My vision for Bevy UI is largely a vision for better Bevy Scenes and an improved Bevy data model. The general angle is:

Embrace the "Bevy data model" for both Scenes and UI. Fill in functionality and UX gaps where necessary.

This document serves as an introduction to my plan, a description of how it should be implemented, and an outline of what I have already built.

It also serves as a kickoff for the Next Generation Scene/UI System Working Group. This is still just a proposal. I want everyone interested to read, discuss, and iterate on it with me. That being said, I'm confident enough with it (and far enough into the implementation of it), that I am biased toward moving forward quickly (and iterating), especially on the fundamental pieces, rather than dragging on for months.

Unifying Scenes and UI yields significant fruit:

1. Bevy users will learn exactly one data model for everything, making it easier to "learn Bevy". Cognitive load will be reduced across the board. Context switching between UI and "the rest of Bevy" will not be required.
2. Improvements to the core Bevy data model will directly (and immediately) benefit Bevy UI (ex: ECS relations, reactive ECS, "observer style event handlers", etc). The reverse is also true.
3. Tooling built for Bevy Scenes will work equally well with Bevy UI. (ex: live inspectors, hot reloaders, formatters, debuggers, visual editors, Rust macros, scripting integration). Once again, the reverse is also true.

From my research, I feel strongly that at their core, the requirements for UI are not fundamentally different from the requirements for scenes. The fact that historically unified UI is uncommon (or poorly implemented) in the industry is because building UI frameworks is hard and building scene systems is hard. Very few organizations / individuals have ever embarked on doing both at the same time. The few orgs I'm aware of that have done both have either (1) built a Scene system first and then built a UI system on top of it (Godot, the "older" Unity UI system) or (2) built a UI system first and then tried building a scene system in it (look into React.js gamedev if you're interested).

I say "at their core" because I fully acknowledge that UI and Scenes do have requirements for some features that may not perfectly overlap (ex: styles and accessibility should probably be optimized for UI use cases over scene use cases and might justify context-specific systems). At least in the short term, things like "reactive scenes" outside of a UI scope will probably be a more niche concept than "reactive UI", which is currently commonplace. That being said, sharing a common core allows us to explore where (and how) these intersections should be shared. For example: styling 3D scenes in the same way you style UI is an interesting concept worth exploring. I suspect that reactive scenes in the context of "2D and 3D game scenes" will grow in popularity (given the capabilities I've seen in Flecs)

Bevy is uniquely positioned to build the first popular, high quality, delightful to use unified general purpose Scene / UI system that seamlessly crosses the boundary between code-driven scenes and asset-driven scenes. This has me very excited, and I think I can find others to share in my excitement.

This is a followup to my older Bevy UI and Scene Evolution kickoff discussion.

Here are the pillars of my strategy:

• Required Components: Components can define what components they need, and how to construct them. This replaces Bundles as the primary form of initializing entities.
• Construct: Support initializing Components that need additional context (ex: World access, the current entity, input data, etc), in a way that encapsulates that behavior.
• Scenes and Patches: A format-agnostic way to define layers of changes to Construct-ed entities. This has "static" highly efficient code-driven represenations and more flexible dynamic representations
• BSN: A bsn! macro and accompanying asset format that enable ergonomically composing Bevy Scenes. This builds on the previous pillars.

Note that many of these pillars are standalone features that can be reviewed and merged independently. The rest are built in layers. Most of them can (and should) be merged on their own individual merits, even outside of the context of the scene system. I'm listing the pillars in "proposed merge order". Most of these pillars are already implemented.

Required Components

Bevy's current Bundles as the "unit of construction" hamstring the UI user experience and have been a pain point in the Bevy ecosystem generally when composing scenes:

• They are an additional object defining concept, which must be learned separately from components. Notably, Bundles are not present at runtime, which is confusing and limiting.
• They can completely erase the defining component during Bundle init. For example, ButtonBundle { style: Style::default(), ..default() } makes no mention of the Button component symbol, which is what makes the Entity a "button"!
• They are not capable of representing "dependency inheritance" without completely non-viable / ergonomically crushing nested bundles. This limitation is especially painful in UI scenarios, but it applies to everything across the board.
• They introduce a bunch of additional nesting when defining scenes, making them ugly to look at
• They introduce component name "stutter": SomeBundle { component_name: ComponentName::new() }
• They require copious sprinklings of ..default() when spawning them in Rust code, due to the additional layer of nesting

Required Components (which I have fully implemented) solve this by allowing you to define which components a given component needs, and how to construct those components when they aren't explicitly provided.

This is what a ButtonBundle looks like with Bundles (the current approach):

#[derive(Component, Default)]
struct Button;

#[derive(Bundle, Default)]
struct ButtonBundle {
    pub button: Button,
    pub node: Node,
    pub style: Style,
    pub interaction: Interaction,
    pub focus_policy: FocusPolicy,
    pub border_color: BorderColor,
    pub border_radius: BorderRadius,
    pub image: UiImage,
    pub transform: Transform,
    pub global_transform: GlobalTransform,
    pub visibility: Visibility,
    pub inherited_visibility: InheritedVisibility,
    pub view_visibility: ViewVisibility,
    pub z_index: ZIndex,
}

commands.spawn(ButtonBundle {
    style: Style {
        width: Val::Px(100.0),
        height: Val::Px(50.0),
        ..default()
    },
    focus_policy: FocusPolicy::Block,
    ..default()
})

And this is what it looks like with Required Components:

#[derive(Component)]
#[require(Node, UiImage)]
struct Button;

commands.spawn((
    Button,
    Style { 
        width: Val::Px(100.0),
        height: Val::Px(50.0),
        ..default()
    },
    FocusPolicy::Block,
));

With Required Components, we mention only the most relevant components. Every component required by Node (ex: Style, FocusPolicy, etc) is automatically brought in!

Efficiency

1. At insertion/spawn time, Required Components (including recursive required components) are initialized and inserted as if they were manually inserted alongside the given components. This means that this is maximally efficient: there are no archetype or table moves.
2. Required components are only initialized and inserted if they were not manually provided by the developer. For the code example in the previous section, because Style and FocusPolicy are inserted manually, they will not be initialized and inserted as part of the required components system. Efficient!
3. The "missing required components and constructors needed for an insertion" are cached in the "archetype graph edge", meaning they aren't computed per-insertion. When a component is inserted, the "missing required components" list is iterated (and that graph edge (AddBundle) is actually already looked up for us during insertion, because we need that for "normal" insert logic too).

IDE Integration

The #[require(SomeComponent)] macro has been written in such a way that Rust Analyzer can provide type-inspection-on-hover and F12 / go-to-definition for required components.

Custom Constructors

The require syntax expects a Default constructor by default, but it can be overridden with a custom constructor:

#[derive(Component)]
#[require(
    Node,
    Style(button_style),
    UiImage
)]
struct Button;

fn button_style() -> Style {
    Style {
        width: Val::Px(100.0),
        ..default()
    }
}

Multiple Inheritance

You may have noticed by now that this behaves a bit like "multiple inheritance". One of the problems that this presents is that it is possible to have duplicate requires for a given type at different levels of the inheritance tree:

#[derive(Component)
struct X(usize);

#[derive(Component)]
#[require(X(x1))
struct Y;

fn x1() -> X {
    X(1)
}

#[derive(Component)]
#[require(
    Y,
    X(x2),
)]
struct Z;

fn x2() -> X {
    X(2)
}

// What version of X is inserted for Z?
commands.spawn(Z);

This is allowed (and encouraged), although this doesn't appear to occur much in practice. First: only one version of X is initialized and inserted for Z. In the case above, I think we can all probably agree that it makes the most sense to use the x2 constructor for X, because Y's x1 constructor exists "beneath" Z in the inheritance hierarchy; Z's constructor is "more specific".

The algorithm is simple and predictable:

1. Use all of the constructors (including default constructors) directly defined in the spawned component's require list
2. In the order the requires are defined in #[require()], recursively visit the require list of each of the components in the list (this is a depth Depth First Search). When a constructor is found, it will only be used if one has not already been found.

From a user perspective, just think about this as the following:

1. Specifying a required component constructor for Foo directly on a spawned component Bar will result in that constructor being used (and overriding existing constructors lower in the inheritance tree). This is the classic "inheritance override" behavior people expect.
2. For cases where "multiple inheritance" results in constructor clashes, Components should be listed in "importance order". List a component earlier in the requirement list to initialize its inheritance tree earlier.

Required Components does generally result in a model where component values are decoupled from each other at construction time. Notably, some existing Bundle patterns use bundle constructors to initialize multiple components with shared state. I think (in general) moving away from this is necessary:

1. It allows Required Components (and the Scene system more generally) to operate according to simple rules
2. The "do arbitrary init value sharing in Bundle constructors" approach already causes data consistency problems, and those problems would be exacerbated in the context of a Scene/UI system. For cases where shared state is truly necessary, I think we are better served by observers / hooks.
3. If a situation truly needs shared state constructors (which should be rare / generally discouraged), Bundles are still there if they are needed.

Construct

Some components require World state to be constructed, which prevents them from being initialized using parameterless constructors like Default. Some examples:

• Strong Asset Handles: require AssetServer to kick off a load and assign an efficient runtime id. They also require an input AssetPath to query for the handle
• Entity References: require the ability to query World for the Entity id using some criteria (ex: an EntityPath that queries the hierarchy using the Name component)
• Custom IDs / Indices: require the ability to retrieve an ID on construction (maybe using some input as a key). They might also want to register the entity with the ID in an index resource.

Critically, by abstracting over these "world requirements" for a given type, we relieve the conceptual and ergonomic pressure to manually retrieve these requirements from World and pass in their parameters to construct the final type during initialization. Bevy users are tired of needing to pull in AssetServer, Assets<StandardMaterial>, Assets<Mesh>, etc to construct and orchestrate everything manually. And in the context of scenes, doing this manually is not justifiable. This is an important missing piece of the puzzle, both in the Bevy Scene space and in manual/direct entity initialization.

Therefore, Bevy is missing an abstraction that defines a "constructor" for a given type that:

1. Accepts input data of another type (ex: the AssetPath for a Handle).
2. Provides access to World and the data inside of it (ex: the AssetServer for a Handle)
3. Provides access to the current insertion context (ex: the current Entity being inserted into)

Construct is a trait that does exactly that:

pub trait Construct: Sized {
    type Props: Default + Clone;
    fn construct(context: &mut ConstructContext, props: Self::Props) -> Result<Self, ConstructError>;
}

Where ConstructContext is (currently) just:

pub struct ConstructContext<'a> {
    pub id: Entity,
    pub world: &'a mut World,
}

This is what the implementation for asset Handle<T> looks like:

impl<T: Asset> Construct for Handle<T> {
    type Props = AssetPath<'static>;

    fn construct(
        context: &mut ConstructContext,
        path: Self::Props,
    ) -> Result<Self, ConstructError> {
        if let Err(err) = path.validate() {
            return Err(ConstructError::InvalidProps {
                message: format!("Invalid Asset Path: {err}"),
            });
        }
        Ok(context.world.resource::<AssetServer>().load(path))
    }
}

Note that Construct is fallible, allowing users to recover from errors (when using it directly), and Scene systems to report errors when they occur.

Deriving Construct

Construct can be manually implemented. For some types, such as Handle<T>, this makes sense because it requires very specific inputs and internal logic. However for types that use those types, Construct can (and should) be derived:

#[derive(Component, Construct)]
struct Player {
   #[construct]
   config: Handle<Config>,
   name: String, 
   team: Team,
}

An astute reader might notice a potential problem: we know Handle<Config> required a Construct impl. Does that mean Team and String also need Construct impls? What if we can't implement Construct for these types (ex: String) due to Rust's orphan rule?

Fortunately, this problem is easily solved: we just implement Construct for every type that implements Default and Clone (note that Props require Clone because we need new prop instances for each spawned instance of a scene ... we can discuss this, but I currently think this constraint + data pattern is the right call).

impl<T: Default + Clone> Construct for T {
    type Props = T;

    #[inline]
    fn construct(context: &mut ConstructContext, props: Self::Props) -> Result<Self, ConstructError> {
        Ok(props)
    }
}

Notice that Construct doesn't really "construct" anything for Default types. The constructed type is the prop type, so it just passes it through. Put another way, a Default type is both the Props and the Constructed type. It is a no-op.

That means Team (from the example above) can just look like this:

#[derive(Default, Clone)]
enum Team {
    #[default]
    Red,
    Blue,
}

And we can still "construct" Team (or use it as a field on a derived Construct type).

Usage

Construct can be used manually like this:

let image: Handle<Image> = Construct::construct(context, "sprite.png".into())?;

Additionally, context can call construct directly. Note the removal of the manual .into() and the removal of the Construct::construct stutter:

let image: Handle<Image> = context.construct("sprite.png")?;

Or alternatively:

let image = context.construct::<Handle<Image>>("sprite.png")?;

Construct Required Components

Required Components support Construct:

#[derive(Component)]
#[require(
    Node,
    construct(UiImage),
)]
struct MyImage;

When construct is specified, the component will be queued for construction and inserted at the next command flush (this uses the same underlying mechanism as component hooks / observers).

Builders

A builder syntax is also possible (but not yet implemented ... API to be determined). Here is one idea:

fn sprite(mut commands: Commands) {
    commands
        .construct::<Handle<Image>>("sprite.png")
        .construct::<SpawnTime>(())
        .add((Sprite::default(), Transform::from_xyz(1.0, 0.0, 0.0)))
        .spawn()
}

Compare that to the "manual way":

fn spawn_sprite(
    mut commands: Commands,
    asset_server: AssetServer,
    time: Res<Time>
) {
    commands.spawn((
        asset_server.load::<Handle<Image>>("sprite.png"),
        SpawnTime::from(&time),
        Sprite::default(),
        Transform::from_xyz(1.0, 0.0, 0.0),
    ))
}

Alternatively (or in addition to) the builder pattern, we could probably also implement a Bundle-style api like this:

commands.construct((
    Handle::<Image>::prop("sprite.png"),
    SpawnTime::prop(()),
    Sprite::default(),
    Transform::from_xyz(1.0, 0.0, 0.0)))
))

That being said, I think bsn! will be preferred over all of these styles. I don't think we need to prioritize them in the short term (or until it becomes clear that there is demand for them).

Encapsulation

Notably, Construct-driven initialization, in addition to being more ergonomic, especially as it scales, is also fully encapsulated ... no dependencies required. This allows us to build APIs like:

fn player(entity: impl EntityBuilder) -> impl EntityBuilder {
    entity
        .construct::<Handle<Image>>("player.png")
        .construct::<SpawnTime>(())
        .add((Player, Sprite::default(), Transform::from_xyz(1.0, 0.0, 0.0)))
}

fn red_player(entity: impl EntityBuilder) -> impl EntityBuilder {
    entity
        .build(player)
        .add(Red)
}

fn blue_player(entity: impl EntityBuilder) -> impl EntityBuilder {
    entity
        .build(player)
        .add(Blue)
}


fn spawn_system(mut commands: Commands) {
    commands.build(blue_player);
    commands.build(red_player);
}

We can now spawn these player entities "anywhere" from any system without needing to know whatever complex initialization dependencies / logic they require.

We now have the makings of something resembling a scene system, but we haven't really even built one yet! Also take note of how Construct and Required Components feed into each other. Imagine how much worse this would look with bundles everywhere!

Construct Derive Codegen

The Construct derive assumes that every field also implements Construct.

For this input:

#[derive(Component, Construct)]
struct Player {
   #[construct]
   config: Handle<Config>,
   name: String, 
   team: Team,
}

It produces code that looks like this:

#[allow(missing_docs)]
#[derive(Clone, Reflect)]
pub struct PlayerProps {
    config: ConstructProp<Handle<Config>>,
    name: String,
    team: Team,
}

impl Default for PlayerProps {
    fn default() -> Self {
        Self {
            config: ConstructProp::Prop(Default::default()),
            name: Default::default(),
            team: Default::default(),
        }
    }
}
impl Construct for Player {
    type Props = PlayerProps;
    fn construct(context: &mut ConstructContext, props: Self::Props) -> Result<Self, ConstructError> {
        Ok(Self {
            config: match props.config {
                ConstructProp::Prop(p) => {
                    Construct::construct(p, context)?
                }
                ConstructProp::Value(v) => v,
            },
            name: props.name,
            team: props.team,
        })
    }
}

The ConstructProp enum allows the type to be constructed either with the Construct::Prop type or an actual instance of the value:

let mut player_props = PlayerProps::default();
// Construct using the actual value
player_props.config = ConstructProp::Value(asset_server.load("player.config"));
// _Or_ Construct using the props
player_props.config = ConstructProp::Prop("player.config".into());

let player: Player = context.construct(player_props)?;

This flexibility is critical for entities constructed in code, as it allows for passing manually constructed "actual values" into scenes, alongside their "props".

An astute reader may notice that in theory, we could remove the need to manually specify #[construct], given that all fields do actually implement Construct.

There are two good reasons:

1. If all fields are wrapped in ConstructProp (and not just the ones that need props), that blocks our ability to do the blanket Construct impl for Default types, as the fields on those types won't have ConstructProp wrappers.
2. Efficiency: doing so ensures that when setting fields in Construct::construct, we only branch on fields that actually need props. In practice, the Rust compiler does optimize these branches out when they aren't needed, but only at higher optimization levels. By removing the enum entirely for these fields, we ensure it is optimal at all optimization levels.

Scenes and Patches

In order to support scenarios like inheritance and styles, sets of changes must be able to apply on top of each other. In other words, we need scenes to be defined as "patches on data", not the data itself.

The new Patch system gives the Bevy scene system these capabilities.

Using the Patch Trait

First, lets look at the new Patch trait:

pub trait Patch: Send + Sync + 'static {
    type Construct: Construct + Bundle;
    fn patch(&mut self, props: &mut <Self::Construct as Construct>::Props);
}

This allows a type to use its context to modify the value of a Construct type's Props. In practice, Patch is implemented for functions that modify Construct::Props, while also retaining the context of the original Construct type. Aka, the ConstructPatch type:

pub struct ConstructPatch<C: Construct, F> {
    func: F,
    _marker: PhantomData<C>,
}

All types that implement Construct have a patch helper function, which allows developers to ergonomically define a patch for a type:

let mut blue_patch = Player::patch(|props| {
    props.team = Team::Blue;
});

let mut props = PlayerProps::default();
blue_patch.patch(&mut props);

// props.team is now Blue!

Importantly, blue_patch still encodes the original Construct context (aka, that it is for the Player type). This means that you can use the construct_from_patch method on ConstructContext to construct the "actual type" from a Patch that patches the "props type":

let player: Player = context.construct_from_patch(&mut blue_patch)?;

Patch is also implemented for tuples of patches:

let patch = (
    Player::patch(|props| {
        props.config = "path_to_config.ron".into(),
        props.team = Team::Blue;
    }),
    Transform::patch(|props| {
        props.translation.x = 10.0;
    }),
);

EntityPatch

When Patch is combined with the new EntityPatch type, things start to get very interesting:

let entity_patch = EntityPatch {
    inherit: AssetPath::from("other_patch.bsn"),
    patch: (
        Player::patch(|props| {
            props.config = ConstructProp::Prop("path_to_config.ron".into()),
            props.team = Team::Blue;
        }),
        Transform::patch(|props| {
            props.translation.x = 10.0;
        }),
    ),
    children: (
        EntityPatch {
            inherit: (),
            patch: (
                Name::patch(|props| {
                    props.0 = "ChildA".to_string();
                }),
                Transform::patch(|props| {
                    props.scale.x = 2.0;
                })
            ),
            children: (),
        },
        EntityPatch {
            inherit: (),
            patch: (
                Name::patch(|props| {
                    props.0 = "ChildB".to_string();
                }),
                Transform::patch(|props| {
                    props.translation.y = 8.0;
                })
            ),
            children: (),
        },
    ),
};

This defines a "patch tree" for an entity. This is essentially what amounts to an in-code scene system, which requires no special DSL. You can define whatever DSL you want (this proposal will outline BSN in a bit, but anything that translates to EntityPatch will work). You can also just define the EntityPatch type directly.

EntityPatch encodes inheritance information for each entity in the tree. Notably inheritance is statically encoded. This means for an EntityPatch with no inheritance, we can cheaply spawn it immediately without needing to do the comparatively expensive inheritance resolution logic (which requires hash maps, potentially waiting on the asset system to finish loading assets, etc):

construct_context.spawn_entity_patch(patch)?;

This will recursively construct and insert all components in the patch tree. Importantly, this approach means we can use entity patches to cheaply and immediately spawn patches (aka scene definitions), making them a suitable replacement for manually spawning entities in Bevy using the traditional commands.spawn(). This may not feel particularly compelling, given the ergonomics of EntityPatch. However, with the introduction of a DSL like BSN, this becomes desirable!

DynamicScene and DynamicPatch

Patch and EntityPatch provide nice static trees of patches. But to resolve inheritance, and to support scenes loaded from asset files, we need to support more dynamic scenarios.

DynamicPatch and DynamicScene are the equivalents for these scenarios:

pub trait DynamicPatch: Downcast + Send + Sync + 'static {
    fn dynamic_patch(&mut self, scene: &mut DynamicScene);
}

#[derive(Default)]
pub struct DynamicScene {
    component_props: TypeIdMap<Box<dyn DynamicPatch>>,
    children: Vec<DynamicScene>,
}

Notably ConstructPatch implements both DynamicPatch and Patch. Therefore EntityPatch is fully compatible with the dynamic system. Scenes loaded from files are responsible for implementing DynamicPatch. This means patches can be combined across contexts (a BSN asset file, BSN defined in bsn! macro, a directly defined EntityPatch, a JSON asset file, a json! scene macro, etc).

Scene Trait

The Scene trait serves as a destination trait for EntityPatch. In general, it exists because the generics for EntityPatch are hard to specify. Additionally, it is Box-able. It allows you to write code like this:

fn player() -> impl Scene {
    EntityPatch {
        inherit: (),
        patch: (
            Player::patch(|props| {
                props.config = ConstructProp::Prop("path_to_config.ron".into()),
                props.team = Team::Blue;
            }),
            Transform::patch(|props| {
                props.translation.x = 10.0;
            }),
        ),
        children: ()
    }
}

Additionally, for DSLs like BSN, it allows you to write code like this:

fn player() -> impl Scene {
    bsn! {
        (
            Player {
                config: @"path_to_config.ron",
                team: Team::Blue,
            },
            Transform { translation { x: 10.0 } },
        )
    }
}

BSN

BSN is a new syntax / file format / scene system that makes it easy to define nested hierarchies of entities and their components. It builds on the existing pillars listed above.BSN exists to:

1. Support scenes defined in files (as assets) and in code (as macros), all using the same syntax. Scenes defined in BSN embedded in Rust should perform as well as they would if they were manually constructed in code.
2. Support inheritance in a more complete and useful way than calling Construct manually (ex: inherited field overrides, asset system integration)
3. Provide top-tier ergonomics, allowing users to focus fully on the data and how it composes.
4. Support the scenarios above, while still feeling "at home" alongside normal Rust code. This includes playing nicely with Rust Analyzer for autocomplete, go-to-definition, documentation-on-hover, etc.

Overview

BSN can be thought of as a "simplified Rusty syntax that supports hierarchy, scene inheritance, and overrides". It ties directly to existing Bevy and Rust concepts.

The bsn! macro returns an EntityPatch tree. This makes it interoperable with the Patch / DynamicPatch / DynamicScene system (defined in the previous section). It also means that you can embed the results of bsn! inside of another bsn!!

Likewise, it relies on Construct and Required Components to improve its capabilities and usability. If you haven't yet, read those sections above to understand how those concepts relate.

Disclaimer: these examples use essentially a 1:1 port of the existing Bevy UI types. I have a strong desire to rework the boundaries and terminology of these components to better fit the new scene system.

Entities and Components

You can define a new top-level entity in BSN by specifying a Component:

Node

You can add more than one Component to the entity like this:

(Node, Style)

Notice that this uses tuple syntax, just like it would if you were inserting a group of components in normal rust:

world
    .entity_mut(e1)
    .insert((Node::default(), Style::default())

As an aside, note that you can use bsn! as a direct replacement for that if you want!

world
    .entity_mut(e1)
    .construct_patch(bsn! {
        (Node, Style)
    });

Fields

You can define fields on a component like this:

(Node, Style { width: Val::Px(100.) })

Notice that unlike raw Rust, there is no need to specify ..default(). Nice!

Components for an entity can / should be broken up into multiple lines when there isn't enough room:

(
    Node,
    Style { 
        width: Val::Px(100.),
        height: Val::Px(100.),
        display: Display::Flex,
    },
)

Values vs Props

Now lets consider the following Component:

#[derive(Component, Construct)]
struct Img(Handle<Image>);

When specifying fields in BSN, by default they are assumed to be "actual values" (either literals or identifiers available in the current scope). For example:

// `handle` is assumed to be a Handle<Image>
Img(handle)

So far, we haven't really taken advantage of the power of Construct (see the `Construct section above if you haven't already). You can use the following syntax to specify a construct prop instead of a normal field:

Img(@"logo.png")

This expects an AssetPath (or something that converts into one, such as a string) because Handle's Construct::Props type is AssetPath. When this BSN is spawned, it will use that AssetPath to retrieve a strong handle to the logo.png image asset. Fantastic!

This also works for other types of fields (such as named fields). You can mix and match "prop fields" and "value fields":

MyWidget {
    top_texture: @"cat.png",
    bottom_texture: some_handle,
    size: 10, 
}

Expressions

The bsn! macro supports expressions, which are just snippets of Rust code:

MyWidget {
    size: {value + 10}
}

Functions

You can call functions in scope like this:

SomeWidget {
    size: px(10.),
    color: rgb8(255, 10, 10),
}

This is a great way to cut down on boilerplate and abstract out things like unit/type conversions. This is what it looks like without the helpers:

SomeWidget {
    size: Val::Px(10.0),
    color: Color::Srgba(Srgba { red: 1.0, green: 0.039, blue: 0.039 }),
}

Nice and explicit, but much less ergonomic!

Children

BSN entities can define children like this:

Node [
    // Child 1
    (Node, Style { width: px(100.), height: px(100.) }, Other),
    // Child 2
    MyWidget { color: rgb8(255, 10, 10) },
]

Inheritance

BSN entities can inherit from other BSNs. This will spawn the inherited scene with the changes specified for the current entity written on top:

fn special_button() -> impl Scene {
    bsn! {
        (SpecialButton :button)
    }
}

fn button() -> impl Scene {
    bsn! {
        Button
    }
}

Note that this "direct in-code inheritance" pattern hasn't yet been proven out. I think it is possible, but we may need to do this instead:

fn special_button() -> impl Scene {
    bsn! {
        (SpecialButton :"button_scene.bsn")
    }
}

In that case, the results of the button() function would be assigned to the "button_scene.bsn" path, and normal asset scene resolution would be used.

Values are always "patched on top":

fn override() -> impl Scene {
    bsn! {
        (Transform { translation: Vec3 { y: 2. } } :base)
    }
}

fn base() -> impl Scene {
    bsn! {
        Transform { translation: Vec3 { x: 1. } }
    }
}

Transform's default translation is { x: 0.0, y: 0.0, z: 0.0 }. The final value in the example above is { x: 1.0, y: 2.0, z: 0.0 } because the values are "patched" on top of the original (in this case default) Transform value.

#[derive(Component, Construct)]
struct Player {
    name: String,
    color: Color,
}


fn player() -> impl Scene {
    bsn! {
        (
            Player {
                name: "Hello"
            },
            Sprite {
                texture: @"player.png"
            },
        ) 
    }
}

fn red_player() -> impl Scene {
    bsn! {
        (
            Player {
                color: rgb8(255, 0, 0),
            },
            Red,
            Transform {
                translation: Vec3 { y: 10. },
            },
            :player
        ) 
    }
}

fn blue_player() -> impl Scene {
    bsn! {
        (
            Player {
                color: rgb8(255, 0, 0),
            },
            Blue,
            Transform {
                translation: Vec3 { y: 10. },
            },
            :player
        )
    }
}

Multiple inheritance is supported. In all cases, inheritance is applied from right to left, where left is applied "on top" of the result of the right hand side.

bsn! {
    (
        Transform { translation: Vec3 { y: 10. }  },
        // player is applied first, then joystick_controlled, then the local Transform
        : joystick_controlled, player
    ) 
}

The Case Against Bundles

All of the BSN examples so far look the way they do because they have avoided Bundles. Lets compare "BSN + Bundles" against "BSN + Required Components":

// Required Components
Node [
    (
        Node,
        Style {
            width: px(100.),
            height: px(100.),
        },
        Other,
    ),
    MyWidget { color: rgb8(255, 10, 10) },
]

// Bundles
NodeBundle [
    (
        NodeBundle { 
            style: Style { 
                width: px(100.), 
                height: px(100.),
            }
        },
        Other
    ),
    MyWidgetBundle {
        my_widget: MyWidget {
            color: rgba8(255, 100, 100),
        }
    },
]

Look at all of that extra nesting and extra characters! Not to mention the other issues mentioned in the Required Components section. Existing UI frameworks set a high bar for ergonomics and Bundles will not clear that bar. And non-UI Bevy developers also deserve high legibility and ergonomics!

bsn! Code Expansion

BSN relies on the Construct trait at its core to initialize types. Lets explore the Rust expansion of this simple case:

bsn! {
    Node
}

This expands to:

EntityPatch {
    inherit: (),
    patch: (Node::patch(|props| {}), ),
    children: (),
}

Now lets take a look at setting fields:

bsn! {
    (Node, Style { width: Val::Px(100.) })
}

This expands to:

EntityPatch {
    inherit: (),
    patch: (
        Node::patch(|props| {}),
        Style::patch(|props| {
            props.width: Val::Px(100.).into();
        }),
    ),
    children: (),
}

Notice the into() which allows us to pass in any value that converts into the desired type.

Now lets consider a hierarchical example:

bsn! {
    Node [
        Node
    ]
}

This expands to:

EntityPatch {
    inherit: (),
    patch: (Node::patch(|props| {}), ),
    children: (
        EntityPatch {
            inherit: (),
            patch: (Node::patch(|props| {}), ),
            children: (),
        }
    ),
}

And finally, lets look at how Construct::Props syntax expands:

bsn! {
    Player {
        config: @"config.ron",
        team: Team::Blue,
    }
}

The expansion:

EntityPatch {
    inherit: (),
    patch: (
        Player::patch(|props| {
            props.config = ConstructProp::Prop("logo.png".into());
            team = Team::Blue.into();
        }),
    ),
    children: (),
}

BSN Assets

BSN is also an "asset format", meaning it can be composed in files and loaded by the Bevy Asset system:

let player: Handle<Scene> = asset_server.load("player.bsn");
commands.spawn(player);

bsn! macros in code can inherit from BSN Assets:

// Inherits from BSN Asset
fn blue_player() -> impl Scene {
    bsn! {
        (Blue :@"player.bsn")
    }
}

// Inherits from in-code bsn!
fn blue_player() -> impl Scene {
    bsn! {
        (Blue :player)
    }
}

BSN Asset Imports

Imagine we have the following scene:

Sprite {
    image: @"player.png",
}

This has a problem! Unlike bsn! in code, which uses the current Rust import context to decide how to resolve the Sprite type (ex: use bevy:prelude::*), the scene asset doesn't have that context!

We could specify the full type path manually:

bevy::sprite::Sprite {
    image: @"player.png",
}

However this gets repetitive if you have multiple sprites:

bevy::sprite::Sprite {
    image: @"player.png",
} [
    bevy::sprite::Sprite {
        image: @"hat.png",
    }
]

This is where BSN Asset Imports come into play:

use bevy::sprite::Sprite;

Sprite {
    image: @"player.png",
} [
    Sprite {
        image: @"hat.png",
    }
]

Notice that this looks exactly like Rust import syntax!

However this still has a problem!

Import Versioning

Unlike Rust code, which is compiled against a specific crate versions, BSN asset files have no direct tie to the version of a crate defining a type. This can easily cause compatibility issues if a type changes across versions. For example, pretend that in an older Bevy version, Sprite::image was called Sprite::texture:

// Bevy 0.13
use bevy::sprite::Sprite;

Sprite {
    texture: @"player.png"
}

// Bevy 0.14
use bevy::sprite::Sprite;

Sprite {
    image: @"player.png"
}

If our app is running Bevy 0.14 and we see Sprite::texture in a BSN asset file, we need to know whether or not it was authored with the intent to be used in the current Bevy version, or a previous Bevy version (so we can properly migrate it).

Therefore, BSN Assets require version numbers in their imports:

use bevy@0.13::sprite::Sprite;

Sprite {
    texture: @"player.png"
}

If we load this in Bevy 0.13, it will work as expected. If we load it in Bevy 0.14, it will attempt to migrate the scene from 0.13 to 0.14.

This same approach is used for non-Bevy types:

use bevy@0.14::sprite::Sprite;
use my_cool_game@1.1::{Player, Team};

Player { team: Team::Red } [
    Sprite {
        image: @"player.png"
    }
]

For rapid development workflows, we will build editor tooling that does not require incrementing an app's version number for every change, and instead detects schema changes as they occur and runs the migrations when relevant (asking for user input whenever a change could be destructive).

Preludes

Importing every type manually would make BSN hard to compose manually, hard to read, and noisier in version control as things change:

use bevy@0.13::{sprite::Sprite, transform::Transform};

(
    Sprite { texture: @"player.png" },
    Transform { translation: Vec3 { x: 1.0 } },
)

Therefore, much like Rust, BSN supports (and encourages) the use of wildcard imports (and the prelude pattern):

use bevy@0.13::prelude::*;

(
    Sprite { texture: @"player.png" },
    Transform { translation: Vec3 { x: 1.0 } },
)

BSN Event Handlers

UI is event-driven by nature. As such BSN needs to support handlers natively. This has not been implemented, but I think we have a few paths forward (and we can implement more than one if we want, although we should try to have "one way" to do this sort of thing):

Path 1: Special Observer Syntax

We could extend EntityPatch with the ability to define observers:

EntityPatch {
    inherit: (),
    patch: Text::patch(|props| props.0 = "Click Me".into()),
    observers: (
        Observer::new(|trigger: Trigger<Click>, mut texts: Query<&mut Text>| {
            texts.get_mut(trigger.entity()).unwrap().0 = format!("Clicked at {:?}", click.position);
        }),
    ),
    children: ()
}

This would then allow us to add "special observer syntax" to BSN. For example, something like this:

bsn! {
    (
        MyButton,
        Text("Click Me"),
        observe(|trigger: Trigger<Click>, mut texts: Query<&mut Text>| {
            texts.get_mut(trigger.entity()).unwrap().0 = format!("Clicked at {:?}", click.position);
        })
    ) 
}

Note that this cannot be phrased as a component on the MyButton entity because each Observer needs to be its own entity.

I do believe we need something like this to make observers usable within the context of BSN. Sadly directly spawning Observers using BSN (as independent entities) isn't ergonomically viable (although it is possible!).

Path 2: Component Driven Event Handlers

Event handlers are explicitly defined on components. This is a very similar idea to Observers (and would build on the same underlying infrastructure), but the Component-driven approach plays naturally with the current scene system without the need for additions:

#[derive(Component, Default)]
#[require(Node, OnClick)]
struct MyButton {
    text: String,
    #[event_handler]
    on_click: EntityEventHandler<Click>

}

// The Component derive feeds on `#[event_handler]` and expands to
impl Component for MyButton {
    fn register_component_hooks(hooks: &mut ComponentHooks) {
        hooks.on_add(|world, entity, _| {
            world
                .resource_mut::<EntityEvent<Click>>()
                .register_handler::<MyButton>(entity, |button| &mut button.on_click)
        });
        hooks.on_remove(|world, entity, _| {
            world
                .resource_mut::<EntityEvent<Click>>()
                .unregister_handler::<MyButton>(entity)
        });
    }
}



bsn! {
    (
        MyButton {
            on_click: |context, click| {
                context.get_mut::<Text>().0 = format!("Clicked at {:?}", click.position);
            }
        },
        Text("Click Me"),
    )
}

#[derive(EntityEvent)]
struct Click {
    #[entity]
    entity: Entity,
    position: Vec2,
}

app.init_resource::<EntityEvent<Click>>();

// later in app code
fn system(mut click_event: ResMut<EntityEvent<Click>>) {
    click_event.send(Click {
        entity: SOME_ENTITY,
        position: Vec2::new(100.0, 200.0),
    });
}

Path 3: Construct Observer

We could implement Construct for Observer, allowing us to define entity targets:

(
    MyButton,
    Text("Click Me"),
    Name("MyButton"),
)
Observer {
    target: @"./MyButton",
    func: |trigger: Trigger<Click>, mut texts: Query<&mut Text>| {
        texts.get_mut(trigger.entity()).unwrap().0 = format!("Clicked at {:?}", click.position);
    },
}

Obviously not ideal ergonomically, as it would require defining an EntityPath manually, which also requires naming the target entity.

However we could also default target to ../, which would allow for this:

(
    MyButton,
    Text("Click Me"),
) [
    Observer {
        func: |trigger: Trigger<Click>, mut texts: Query<&mut Text>| {
            texts.get_mut(trigger.entity()).unwrap().0 = format!("Clicked at {:?}", click.position);
        },
    }
]

Or this, if we're willing to rework Observer to be a tuple with the function as the first field:

(
    MyButton,
    Text("Click Me"),
) [
    Observer(|trigger: Trigger<Click>, mut texts: Query<&mut Text>| {
        texts.get_mut(trigger.entity()).unwrap().0 = format!("Clicked at {:?}", click.position);
    })
]

Styles

First, to avoid confusion, I will pretend that Bevy's current Style component has been broken up into smaller pieces and no longer exists. Given that Node is essentially the "core UI element type", I think there is a strong argument to move most existing Style fields to Node:

struct Node {
    width: Val,
    height: Val,
    /* other "universal" fields here */
}

With that out of the way, lets discuss BSN styles. Lets consider the following hierarchy of entities in BSN:

Node [
    Text("hello"),
    Img { image: @"logo.png" },
    (CoolWidget, Node { width: px(10.) }),
]

First, lets notice that we could simply "style" this by using the BSN inheritance feature:

fn ui() -> impl Scene {
    bsn! {
        (Node :rounded) [
            Text("hello"),
            Img { image: @"logo.png" } ,
            (CoolWidget, Node { width: px(10.) }),
        ]
    }
}

fn rounded() -> impl Scene {
    bsn! {
        BorderRadius::all(px(2.))
    }
}

However this would only round the top level Node. To apply to the others, we must manually apply the style to everything:

(Node :rounded) [
    (Text("hello") :rounded),
    (Img { image: @"logo.png" } :rounded), 
    (CoolWidget, Node { width: px(10.) } :rounded),
]

"Inheritance as styles" is surprisingly effective (and notably "free" given that we already have inheritance for other reasons). However it does have significant downsides:

1. Using inheritance will create components if they are missing. Generally users of style systems expect mismatched types to be ignored, not created.
2. There is no way to define rules like "apply this style to all Nodes", "apply this style to all children of a given type", and "apply this style to all descendants of a given type".

Therefore, I strongly suspect that we will want a style system that supports these scenarios effectively. However I believe this type of style system:

• Deserves its own design document
• Is not a blocking feature for an initial BSN release, especially given that inheritance does provide workable (albeit limited) "style reuse" patterns.

That being said, I strongly believe that a BSN style system should look like BSN. I think any style system that (1) decouples Styles from strongly typed Components (2) does not look like BSN or (3) does not have the flexibility of styling arbitrary Components, should be off the table.

I believe that the proposed Patch / DynamicPatch system, in combination with DynamicScene and Scene provide the baseline tools to build some new DynamicStyle system on top.

This is not a prescriptive (or fully thought out) design, but I think styles can/should look something like this:

// Applies to any entity with Node in the current scope
Node {
    width: px(10.),
}

// Applies to the child Image of any Node in the current scope 
Node [
    Img {
        width: px(10.)
    }
]

// If we choose to support "any descendants", we'd need a new syntax.
// Something like the following would apply the style to any Img that is a descendant
// of a Node in the current scope
Node [[
    Img {
        width: px(10.)
    }
]]

// BSN-multi-component-entity-syntax serves as selectors.
// This style is only applied to entities that have _both_ MyNode and Node
(
    MyNode {
        x: 10.
    },
    Node {
        width: px(10.),
    }
)

// "Named" styles would need to be possible, this should probably use
// whatever naming syntax we land on for "BSN Sets" (see the next section)
// These would fill a role similar to classes in CSS
style BlueButton (
    Button,
    Node {
        width: px(200.),
        height: px(100.),
    },
    BackgroundColor(rgb8(0, 0, 255))
)

A "scope" (as mentioned in the comments above) could be:

• A "global" style sheet (we should be careful about these though, as implementing truly global styles would require trying to apply them to all entities, which in the context of a large app won't be cheap)
• The root entity of a hierarchy (ex: the "root" UI node)
• A specific entity somewhere in the hierarchy

Applying a style to a specific entity in BSN would likely need its own syntax/keyword too (although we might be able to use relations or work out a "component merging" scheme to use components).

bsn! {
    (Button style(BlueButton)) 
}

We might also want to consider "untyped" styles:

style CanApplyToAnythingSupportingPixelWidth {
    width: px(100.),
}

However in practice I'm not yet convinced "untyped styles" are desirable. Most of these "generic" cases are resolved by having "standard" components (ex: anyone wanting to set width this way should probably just use Node { width: px(100.) }, and if they are setting it on an entity with a component containing a width field that is not Node, then width means a completely different thing ... applying the style across contexts would be risky and/or nonsensical).

BSN Sets

So far in this proposal, BSN is assumed to be a single hierarchy:

Node [
    Img
    Node [
        Node
    ]
]

However there are cases where defining multiple scenes in a given declaration makes sense. For example, defining a "child" scene and spawning it multiple times at the root. This concept is handled by BSN Sets. Note that they have not been implemented yet, the design is still a bit rough, and I don't think they should be implemented as part of the MVP:

// This is a definition for a scene. It must be
// manually spawned or it will just be ignored.  
scene Player (
    Health,
    Transform,
    Sprite { image = @"player.png") }
)

// Using the "normal" unnamed syntax indicates that the scene should be spawned
Transform [
    (Name("Player 1") :Player)
    (Name("Player 2") :Player)
]

In addition to facilitating code reuse, it also provides a tool for flattening out deeply nested scenes:

A [
    B [
        C [
            D
        ]
    ]
]

Could become:

scene B (
    B [
        C [
            D
        ]
    ]
)

A [
    :B
]

It also provides a tool for modules / code organization:

fn actors() -> BsnSet {
    bsn_set! {
        scene Player (
            Health,
            Transform,
            Sprite { image = @"player.png") }
        )

        scene Enemy (
            Health,
            Transform,
            Sprite { image = @"enemy.png") }
        )
    }
}

fn setup() -> impl Scene {
    bsn! {
        Transform [
            (Player1 :actors::Player)
            (Player2 :actors::Player)
            (Enemy1 :actors::Enemy)
        ]
    }
}

This approach also opens the doors to other relevant scenarios, such as Inline Assets:

asset CircleMesh (
    Mesh::new(Circle::new(4.0))
)

Also Styles (as mentioned in a previous section):

style Blue (
    BackgroundColor(rgb8(0, 0, 255))
)

In general, I think we should discuss how we might go about expressing these types of patterns.

Reactive BSN

Reactive BSN is still largely an open question, however aspects of this scenario have already been proven out in the context of BSN. Specifically, in an older version of this proposal, I built "simple" top-level reactivity for component fields. Here is what defining a "reactive component" looked like in that proposal:

#[derive(Component, Clone, Reflect, Default, Debug)]
#[require(React(counter))]
struct Counter {
    count: u32,
}

fn counter() -> Bsn<Counter> {
    bsn! {
        (
            Node
            // .count here refers to Counter.count
            Other { value: .count }
        )
    }
}

#[derive(Component, Default, Debug)]
struct Other {
    value: u32,
}

Some things to note:

1. Counter is made reactive simply by require-ing React with the counter constructor. This works because require allows into() conversion, and React implements From<Bsn<T>>. The "reactive system" queries for entities with a React component, so require-ing it makes the entity visible to the reactive system. Neat!
2. The reactive system is driven by ECS change detection. When Counter is mutated, it re-runs the "reactive" parts of the BSN. This is done by topologically sorting the hierarchy and manually walking down it to check if any reactive components have changed

I think the strategy for Reactive BSN should use fine grained observer-style reactivity. I think this is the only viable strategy for a general purpose reactive system in the context of Bevy:

1. It plays nicely (and can build on top of) Bevy's built in change detection
2. It allows us to do operations directly on ECS values without needing a separate data structure
3. It can benefit from features like ECS hooks + observers.
4. It generally acts as an "additive layer" to Bevy ECS rather than an entirely separate system.

Anyone familiar with reactive systems will probably remark that top-level reactivity is the "easy part". Things get much more interesting when branching / looping / adding removing children gets involved. Examples like this are easy to write, but hard to implement:

#[derive(Component, Default)]
#[reflect(React(items))]
struct Items {
    items: List<Item>,
    blue: bool,
}


fn items() -> Bsn<Items> {
    bsn! {
        (Node, if .blue { BackgroundColor(rgb8(0, 0, 255)) }) [
            for item in .items {
                Text(format!("Item {}", item.number))
            }
        ]
    }
}

That being said, I strongly believe that reactive Bevy UI can look and behave similar to this.

There are also open questions about how to expose ECS data to reactive BSN in ways it can react. I'm partial to something similar to system syntax. For example, we could make it possible to react to changes to resources like this:

Node [
    |counter: Res<Counter>| {
        Text({format!("Count: {}", counter.count)})
    }
]

This is a "hard problem" (and possibly not viable in practice), but we could also consider reacting to Queries like this:

Node [
    // Creates a Text child for every Thing in the Query
    |things: Query<&Thing>| {
        for thing in &things {
            Text({format!("Thing: {}", thing.id)})
        }
    }
]

Talin (@viridia on github and DreamerTalin on Discord) has been investigating the "reactive Bevy" space for a awhile now. They have built:

1. bevy_reactor: a general purpose fine-grained reactive framework for Bevy ECS
2. obsidian_ui: a reactive UI framework on top of bevy_reactor
3. quill: a general purpose coarse-grained reactive framework for Bevy ECS

I think we should give these a serious review and consider how they would fit into the BSN picture. At the very least, we should view them as a "proven path" that we should learn from.

Adapting Bevy UI to the New APIs

• Remove all UI bundles and port them to Required Components
• Move all "core element style properties" from Style to Node. Ex: width, height, min_width, min_height, left, right, etc. Move properties that don't make sense on Node to other new components where relevant.
• Rework Text to use hierarchy for text sections instead of nesting them inside of a Text. The current approach is too cumbersome when defining scenes.
• Rename UiImage to Img
• Remove existing Button implementation
• Implement some core widgets using the new framework: button / slider / etc (we might want to wait until reactivity lands for this)

Ultimately it could end up looking something like this:

bsn! {
    Node { width: px(200.), height: px(100.) } [
        Img { image: @"logo.png" },
        (Button { on_click: click_button }, BorderRadius::all(px(5.0))) [
            Text("Click Me")
        ]
    ]
}

MVP Remaining Work

My goal is to get a baseline feature-set for BSN released soon so we can review, discuss, iterate, and (ideally) merge in the near future. BSN unlocks significantly improved workflows. The sooner we get it in peoples' hands the better ... even if it is missing features.

I would like to land the following in the BSN MVP:

1. Required Components
2. Construct trait and derive
3. The Patch / DynamicPatch / Scene / DynamicScene system
4. bsn! macro (without BSN Set features)
5. BSN asset format (likely missing some parity features with bsn macro, such as calling functions)
6. Inheritance

And here is list of my biggest remaining TODO items:

• Finish rewriting the bsn! macro to work with the new Patch / Construct system
• Finish implementing inheritance in the new Patch / Construct system (the old impl is not compatible)
• Constructing enums is currently broken with the latest Construct derive
• BSN assets need to be updated to use Construct / DynamicPatch / DynamicScene and synchronized with latest syntax changes
• Implement function support in BSN (ex: BorderRadius::all() and px(10.0))
• Switch to using comma separators instead of spaces
• Support inline identifier syntax: UiImage(handle) (currently only "expression style" UiImage({handle}) is supported)
• To support "spawn when all assets are loaded", Construct needs to be able to register asset dependencies without actually constructing the components. This will require adding a Construct::visit_dependencies(&self, visitor: impl DependencyVisitor) function.

And some stretch goals for the MVP:

• Implement one or more of the "BSN entity event handler" proposals

Post MVP Work

• Reactive BSN
• Styles
• Port relevant engine features to Required Components / Construct / BSN
• Start evolving Bevy UI to take advantage of BSN
• BSN Asset Import Versioning
• BSN Asset Version Migrations
• BSN Sets
• bsn! macro auto-formatter (command line tool + editor extensions)
• "BSN asset file" auto-formatter and syntax highlighting
• Implement function support in the BSN asset format
• Inline Assets (possibly as part of Assets as Entities)

Where is the code?

As mentioned above, a solid chunk of this proposal is implemented. But it is currently in a weird "middle ground" state between the old proposal impl and new proposal impl. It'll need about a week or two of work to get it into a state that isn't confusing for the reader.

I'm going on a week long trip starting today, so I should have some code ready for consumption in 2-3 weeks. Until then, use this time to review and discuss this proposal.

Some Additional Open Questions

Unify Required Components and BSN Inheritance?

Can we (and should we) unify Required Components and BSN Inheritance? There is conceptual overlap, and BSN's "layered patching" approach works better for some initialization scenarios (ex: granular inherited field "overrides" instead of fully overwriting on init). The biggest concerns here are UX and performance (Component Requires can be maximally efficient and maximally ergonomic because their scope is smaller than BSN).

#[derive(Component, Construct)]
#[require(camera_3d)]
struct Camera3d;


fn camera_3d() -> Bsn {
    bsn! {
        Camera,
        Projection,
        Frustum,
        ColorGrading,
        Exposure,
        Tonemapping,
        CameraRenderGraph::new(Core3d),
        DebandDither::Enabled
    }
}

Should we tie Scene Inheritance to Components?

"Reactive scenes" are naturally driven by and tied to a specific component. The question then becomes: should we embrace this for non-reactive scenes too?

For example:

#[derive(Component, Construct)]
#[scene(player)]
struct Player;

fn player() -> impl Scene {
    bsn! {
        (
            Player,
            Transform { translation: Vec3 { x: 1.0 }  } ,
        )
    }
}

// later 
bsn! {
   // this spawns the player() scene ... aka it implicitly inherits from player()
   (Player, Name("Player1"))
}

Put another way: "should we support / encourage developers to tie their scenes to specific components, or we should require that they reference those scenes directly".

If we embrace this pattern, we might want to ensure that "scene tied" components like Player can only be spawned via the scene system to ensure that everything is spawned "at once".

Should we use <> instead of () for entities in BSN?

// <>
<Node BorderRadius::new(px(2.)> [
    Node,
    <Node> [
        Node
    ],
]

// ()
(Node BorderRadius::new(px(2.)) [
    Node,
    (Node) [
        Node
    ],
]

() is nice because it matches the raw Rust Bevy component bundle syntax. It also plays nicer with syn, which doesn't have easy support for parsing <> groups.

<> is nice because it reads more like an "element" for those familiar with HTML.

Should () or <> always be required? (in the interest of consistency / alignment)

Currently for single-component entities, they are allowed to omit the ():

(Node, BorderRadius::new(px(2.)) [
    Node,
    (Node, Name("Foo")) [
        Node
    ],
]

However to ensure everything is aligned and consistent, we could force () everywhere:

// ()
(Node, BorderRadius::new(px(2.)) [
    (Node),
    (Node, Name("Foo")) [
        (Node)
    ],
]

Or force <> if we roll with that syntax:

// <>
<Node, BorderRadius::new(px(2.)> [
    <Node>,
    <Node, Name("Foo")> [
        <Node>
    ],
]

[DasLixou]

Really nice to see progress here, I am really excited for this.
Here are some things I wrote down while reading:

• You mentioned at the beginning that the ButtonBundle would never force a mention of a Button, but with hidden initialization of required components, this problem still remains
• What about Components that can't/shouldn't be defaulted and need explicit data? I don't know if I am alone with my opinion but I think it would be neat to declare a non-defaultable/non-constructable Component as required which forces the developer to also initialize that component on spawn. Problem here would be that the user would have to declare the required component on insert even it could already be on that entity.
• Going from bundles to required components also eliminates the problem of multiple bundles having the same component, e.g. Transform, nice 👍
• When the construction/inserting of required components who aren't directly specified in the creation don't get inserted at the same time but shortly after, couldn't that lead to problems? E.g. Mesh would require standard material but I only insert a mesh. (I'm not sure if a mesh renders without a material, but we just assume it does) Wouldn't that then render a white nothing for the mesh for one or two frames before the material gets added and the color correction, shadow, etc. also renders? Expanding this to not just visual bugs, I could think that this could lead to some minor errors.
• You said that the importance of constructors for required components are depth-sorted. Wouldn't that mean it's Breadth-first instead of Depth-first?
• Why have ConstructContext behind a mutable borrow? It's so short, clonable and may also be faster to have it directly because it can maybe be stored in registers? (Ok I kinda answered that myself just now, it may grow larger, but still having it here because why not)
• I'm a little confused with the example for the Player, why would I have a Handle, which is a Component by itself, inside a component? The examples below show that constructs can also be required, so why like this?
• What about values in components, or even whole components who can't/shouldn't be defaulted? Should every non-defaultable value be Option-wrapped? And can non-defaultable components not be described in bsn or do they just have do be fully described with every field?

[cart]

You mentioned at the beginning that the ButtonBundle would never force a mention of a Button, but with hidden initialization of required components, this problem still remains

I don't see this as the same problem. Unlike Bundles, you are always forced to specify the most specific component if you want it.

In the case of the ButtonBundle example, if you cease to specify the Button component, then it will not add Button or its dependencies. If you define a more specific Button type, such as BigButton, then it is possible to avoid specifying Button, but from my perspective that is good / desirable because you have already specified BigButton:

#[derive(Component, Default)]
#[require(Button)]
struct BigButton;


bsn! {
    (BigButton Node { width: px(100.) }) 
}

What about Components that can't/shouldn't be defaulted and need explicit data?

In theory we could support this, but it would need to be enforced at runtime. Worth exploring, but I don't see it as fully necessary for an MVP, given that Bundles can still fill this niche role. In general I think we should be encouraging default-able contextless components because they play nicely with editor scenarios (can't really call arbitrary constructors in the context of a scene editor).

When the construction/inserting of required components who aren't directly specified in the creation don't get inserted at the same time but shortly after, couldn't that lead to problems? E.g. Mesh would require standard material but I only insert a mesh. (I'm not sure if a mesh renders without a material, but we just assume it does) Wouldn't that then render a white nothing for the mesh for one or two frames before the material gets added and the color correction, shadow, etc. also renders? Expanding this to not just visual bugs, I could think that this could lead to some minor errors.

Meshes without a Material would not render as they wouldn't have a driver system to render them. But for the sake of argument, I think that this class of problem should generally be solved like:

#[derive(Component)]
#[require(construct(Handle<Mesh>))]
struct MaterialHandle<M: Material>(Handle<M);

(Note: there are ways to support this without the wrapper over the Handle component, but for simplicity I've done it this way)

A MaterialHandle component without a Mesh doesn't make sense (or at least, we can define it that way), so there is a clear hierarchy here (you can have a Mesh without a Material, but not a Material without a Mesh).

You said that the importance of constructors for required components are depth-sorted. Wouldn't that mean it's Breadth-first instead of Depth-first?

Not quite. The specified algorithm for visiting each dependency is:

1. Register all of the constructors for the currently visited item
2. Visit all of the required components in order.

We register all of the constructors for a given visit before recursing.

Why have ConstructContext behind a mutable borrow? It's so short, clonable and may also be faster to have it directly because it can maybe be stored in registers? (Ok I kinda answered that myself just now, it may grow larger, but still having it here because why not)

Yup you're on the same track I was on. Originally ConstructContext had cached pointers to common types like AssetServer to avoid lookups. We may also cache current hierarchy context on it.

I'm a little confused with the example for the Player, why would I have a Handle, which is a Component by itself, inside a component? The examples below show that constructs can also be required, so why like this?

For the same reasons we don't break off every field on every component into a separate component:

1. Cuts down on query complexity / makes the fields accessible on every Player query
2. Simpler init
3. Logically groups fields together

It is an arbitrary design choice of course. Depending on the context, you could easily make the argument to split off the Handle<Config>. No hard and fast rules here!

What about values in components, or even whole components who can't/shouldn't be defaulted? Should every non-defaultable value be Option-wrapped? And can non-defaultable components not be described in bsn or do they just have do be fully described with every field?

In the context of BSN files we must rely on the default / props / construct flow unless we're willing to enter into the realm of unsafe in those cases. Combine that with the preference for require-style init (which relies on being able to construct without specifying fields) and in general this is a rule that should be followed.

In the context of BSN macros, I'd like to support the following syntax:

bsn! {
    (
        SomeConstructedComponent,
        // the {} syntax allows us to define an arbitrary rust expression
        // that returns a component
        {ComponentThatCantBeDefaulted(100)}
    )
}

[alice-i-cecile]

For those who'd like to help out (or follow along), ongoing work will be done in concert with the Next Generation Scene working group on Discord.

[NotAFile]

I really like this proposal! I had some concerns when I started reading it, but by the end I just wished I could use it as is today.

I'll still list the thoughts I had for discussion:

Documentation of bundles/required components

One of the nice things about Bundles being structs, despite the verbosity, is that they are somewhat self-documenting. If you wanted to add a SpriteBundle, you could see what that entailed in the docs and via autocomplete, making it easy to see what components you might want to modify. I thought this was a pretty elegant way around how opaque ECS functionality can often be.

It definitely also has it's issues, like not being able to distinguish between components that will be used to configure the functionality (e.g. Material) and components that will be used to store state (e.g. GlobalTransform), or even both depending on where it's used (e.g. Transform).

In an ideal world this would all be meticulously manually documented, but in practice it of course rarely is, both in Bevy itself and external projects.

The case of editors is also worth considering there: If you want to add a Sprite, you probably want the Transform to show up in the Editor, but having the GlobalTransform there would cause confusion. If you save a scene to disk, you probably don't want to save whatever GlobalTransform it had at the time of saving either.

I don't have an answer there (perhaps some way to mark a required component as computed in a way that works via the inheritance system? Generate doc comments?) and it's not really much worse than before with this design anyway.

Marker Components

UIs (and scenes) often have a lot of singleton items. Many UI and scene systems have ways of assigning unique labels to those items, like Godot scene unique names and HTML element IDs. In bevy, this is currently done with marker components, which have to be defined in Rust, or Name components, which are not unique and can not be queried. Reactivity gets around the need for this somewhat, but I don't think it can be completely eliminated and will probably need some sort of solution.

Interaction with dynamic components/scripting

With imports in bsn, it raises the question of how to deal with scenarios where components are defined or added later, possibly via scripts which might themselves be part of scenes. This is probably too far out to start worrying about, but it feels easy to paint oneself into a corner there.

---

All in all, I think this proposal would be a huge step in the ergonomics of bevy and I'm definitely in favor of it even as-is!

[alice-i-cecile]

For documentation, we've explored that a bit in the past :) You can automatically generate docs on the trait implementation via the derive macro!

[cart]

Documentation of bundles/required components

As Alice mentioned, we have found a way to auto-generate docs for required components as part of the derive macro. In the context of the editor, we can also build the required component graph and then give boosted priority / prominence to them in component search widgets.

Marker Components

I agree that we need a solid "identity" story. I think something akin to a Name component (maybe combined with indexing) is the right path forward.

With imports in bsn, it raises the question of how to deal with scenarios where components are defined or added later, possibly via scripts which might themselves be part of scenes.

If they are added later (aka by script/game logic), then the imports are already handled by the game logic context. I don't personally see any unique issues with this pattern in terms of how it relates to BSN. Just the standard "make sure you don't invalidate valid state" problems associated with normal component addition / removal.

[MrGVSV]

I really like this proposal! Here are just some initial thoughts reading through it for the first time:

Blanket Construct Impl

Will the blanket Construct impl not be problematic for types that want to be Default + Clone but also define a custom Construct impl? For example:

#[derive(Clone, Construct)]
struct Zombie {
  #[construct]
  sprite: Handle<Image>
}

impl Default for Zombie {
  fn default() -> Self {
    Self {
      // We want a default value for non-BSN usage
      // but BSN should accept either
      sprite: MY_DEFAULT_HANDLE,
    }
  }
}

Or can props not wrapped in ConstructProp still be constructed from props?

Removing Required Components

The section on Required Components doesn't seem to mention anything about what happens to such components after spawning. For example, what happens when a required component is removed? Does this system play into hooks to ensure that required components always exist? Does it only apply to entity construction and so does nothing after that?

Glob Imports

How do the globstar imports like use [email protected]::prelude::*; work? Does this involve searching through all possible matches when visiting an identifier? Are there performance concerns or optimizations already being taken into account?

Callbacks

Defining callbacks inline within the bsn! macro is definitely great for ergonomics! It does come with a couple concerns.

The first is super minor: how does autocomplete work in such scenarios? My experience with Dioxus seems to indicate that it might be a bit of a pain, with autocomplete just not working while in between valid syntax. Has there been any experiments done there yet?

The second concern is how this starts to create a harsher distinction between bsn! and .bsn. There's already some differences like using in-scope functions or defining Rust expressions inline. But this seems like a potentially major line being drawn between the two.

How are we planning to allow callbacks to be used in the asset form of BSN? Would we use something like function reflection? But even then that still relies on defining the function in code. Are we just disallowing callbacks to be defined in .bsn files?

Nested Inheritance

How does the scene system resolve inheriting scenes with children? Do the children exist on their own? Do they overwrite existing children? Can the user choose between the two?

Scene Input

Do we plan on supporting scenes that take input? Or is this solved by inheriting another scene and overwriting its root component?

Entity References

In bevy_proto, we allowed you to reference entities within the tree as a prop like EntityPath("../../MyEntity"). Are there plans to adopt something like this in BSN?

More generally, how will users define relation ships between entities defined in a scene (or from other scenes even)? Is this something that can only be done through the component's Construct impl?

Entity Syntax

My opinion on the () vs <> thing is to just stick with (). It feels the most "Rusty" and it already has ties to how we currently define bundles.

As far as whether or not they should be required, I think they should be optional. But I do think it's a lot more readable with all entities using () than to have a mix (at the cost of additional characters/noise).

This is especially true when entities span dozens of lines since you don't need the additional context of "is this in a () or a []?" to tell if it's a new entity or a new component.

// Is the following a list of children 
// or a list of components on a single entity?
// ...
Foo,
Bar,
Baz,
// ...

// vs

// The following is obviously a list of children.
// ...
(Foo),
(Bar),
(Baz),
// ...

Additional Syntax

While it wasn't explicitly mentioned in the proposal, will the .bsn file format support comments? Will it also support things like trailing commas and multiline strings?

[cart]

Will the blanket Construct impl not be problematic for types that want to be Default + Clone but also define a custom Construct impl? For example:

The blanket Construct impl for T: Default would block custom Construct impls in those cases. That was an intentional choice I made. I think the pros of the blanket impl from a conceptual / ergonomics perspective far outweigh the loss of what will likely be a niche use case. If this comes up enough, we can devise a special syntax / introduce a new trait for these cases. But I suspect that the vast majority of cases will fit this system / mindset:

1. In general, derive/implement Default
2. If you need World state / rely on a type that does, derive/implement Construct

Think of Construct as an opt-in expanded-powers Default.

Removing Required Components

Required Components currently apply only to construction. This does mean that removing is left as an exercise for the user (at least in the proposed MVP). The reason I haven't included it here (especially in the MVP proposal) largely comes down to:

1. Naively, we treat this as a "garbage collection" situation where we remove Components that have no dependencies (and weren't manually specified).
2. However, there is an ambiguity here because how do we distinguish between "manually specified and explicitly needed" and "just setting a value of a required component that should be removed when its dependents are removed". This could easily result in confusing / hard to debug behavior
3. Implementing (1) does involve additional non-trivial-in-the-context-of-ECS work. Construction seems like the highest value / most focus-worthy problem, whereas automatic removal seems more "optional". Flecs has also punted this problem (at least last time I checked in with @SanderMertens).

How do the globstar imports like use [email protected]::prelude::*; work? Does this involve searching through all possible matches when visiting an identifier? Are there performance concerns or optimizations already being taken into account?

My thought is we would build an index at type-registration, then search the index during scene load, caching results for a given symbol name as we find them. Given that the end-game for scene assets is processed assets, we could also in theory resolve these to hard-coded paths as part of the processor.

The first is super minor: how does autocomplete work in such scenarios? My experience with Dioxus seems to indicate that it might be a bit of a pain, with autocomplete just not working while in between valid syntax. Has there been any experiments done there yet?

I haven't yet wired up the closure syntax to the bsn! macro so I can't say with certainty. If we hit issues in that area we may want to heavily encourage the pattern of referencing function names of functions defined outside of the macro.

The second concern is how this starts to create a harsher distinction between bsn! and .bsn. There's already some differences like using in-scope functions or defining Rust expressions inline. But this seems like a potentially major line being drawn between the two.

Yup. I don't see much of a way around this problem, other than closing feature gaps where we can and having solid documentation and error messages explaining the limitations.

How are we planning to allow callbacks to be used in the asset form of BSN? Would we use something like function reflection? But even then that still relies on defining the function in code. Are we just disallowing callbacks to be defined in .bsn files?

My personal vision for this is function reflection / allowing callbacks defined in code to be referenced in .bsn files.

How does the scene system resolve inheriting scenes with children? Do the children exist on their own? Do they overwrite existing children? Can the user choose between the two?

Currently it just concatenates the children, but I would like to explore both specific-child-override scenarios and ways to insert inheritor children into spots defined by the base scene.

Do we plan on supporting scenes that take input? Or is this solved by inheriting another scene and overwriting its root component?

In the short term for scope reasons I'd like to rely on overwriting / writing on top of root components. In the context of code-driven scenes I think this is the best approach. However I can ultimately see the desire for bsn files to define their own top level overridable parameters/variables without needing to define a new component in code. I'm open to that, but as a "post-MVP" sort of thing.

In bevy_proto, we allowed you to reference entities within the tree as a prop like EntityPath("../../MyEntity"). Are there plans to adopt something like this in BSN?

Yes. The plan is to implement Construct for Entity with EntityPath as a prop. The current implementation spawns entities top-down, meaning that you can only look "up" the hierarchy and "in front" in a children list. That being said, we can decide if we want to introduce a "pre-insert" phase that initializes the entity hierarchy first to allow referencing arbitrary places in the tree. To support resolving EntityPaths with Names, that would also mean inserting Name components first. For that reason, to avoid archetype moves, we may want to make Name sparse.

My opinion on the () vs <> thing is to just stick with (). It feels the most "Rusty" and it already has ties to how we currently define bundles.

Agreed.

While it wasn't explicitly mentioned in the proposal, will the .bsn file format support comments? Will it also support things like trailing commas and multiline strings?

Yup! The macro already supports full rust comment syntax + multi-line strings. The file format doesn't currently support those, but it can / should / will. Trailing commas are supported.

[BD103]

From a single pass, there are two things I really want to stress work this:

1. Please split up this work into multiple PRs. I can easily see the same thing happening as did with Asset v2, where such large changes were made that people could not easily grasp it immediately.
2. On more of the implementation side, defining Rust code within BSN could be really difficult for .bsn files, since you need to run them through the Rust compiler. They would probably have to be precompiled into functions, or directly include!d at compile time.

[cart]

Please split up this work into multiple PRs.

Absolutely. I've already stated that intent in the post, as well as a general plan of how to do so.

On more of the implementation side, defining Rust code within BSN could be really difficult for .bsn files, since you need to run them through the Rust compiler. They would probably have to be precompiled into functions, or directly include!d at compile time.

For sure. Rust code in bsn files is out of scope for the MVP and will likely be unsupported for a long time. Not impossible to support (either by invoking the compiler during processing + dynamic linking, or by introducing a scripting language), but that is a Hard Problem we should not be tackling at this phase.

[UkoeHB]

Promising work, there are unambiguous wins here for sure (require components at minimum is great). The scene redesign you propose moves in a similar direction to what I ended up with in bevy_cobweb_ui, which seems like a case of convergent evolution.

Questions

• What if you want to add an instruction to a Patch (essentially an EntityCommand) that doesn't insert itself as a component? Construct requires returning Self on success.
• How to patch an inner entity of an EntityPatch? In other words, how do you 'drill into' an existing patch or spawned scene (for example, to add custom logic in-code to a specific node of a bsn scene loaded from file)? Current inheritance examples all appear to be 1-entity-deep.
• DynamicScene needs to be fleshed out, possibly with an example. How will it be used?
• What is the asset management story of inheritance?
• Does bsn have a separation between node name and node contents? The syntax is a little ambiguous, you have one example with nodes called Player1, Player2, are those different components?

Styles

My experience is style inheritance is confusing and clumsy. A better approach is to parameterize. In bevy_cobweb_ui I use constants where I want things to have the same value defined globally/external to the scene, and I use params in specs where I want to configure different nodes to the same value.

Reactive BSN

bevy_cobweb is also a mature reactive library with a style much closer to hooks/observers. In my experience using bevy_cobweb_ui, having proper systems as UI reactors that are decoupled from 'figuring out what to react to' is quite helpful. For example, I use a TextEditor system param to write text in reactors, which does zero-alloc writes and integrates localization.

[cart]

What if you want to add an instruction to a Patch (essentially an EntityCommand) that doesn't insert itself as a component? Construct requires returning Self on success.

I consider that out of scope for the current design. Patch (currently) exists for the explicit purpose of setting fields on components (initializing them if they don't exist) and defining hierarchy. Not arbitrary logic. If you have specific scenarios that you think need to be covered here, let me know.

I do definitely want to explore extending the Patch system to support specific things like selecting and overriding children by name.

How to patch an inner entity of an EntityPatch? In other words, how do you 'drill into' an existing patch or spawned scene (for example, to add custom logic in-code to a specific node of a bsn scene loaded from file)? Current inheritance examples all appear to be 1-entity-deep.

Currently undefined, but see my response above for a specific scenario I'd like to explore. Note that patches are designed to be applied in layers opaquely. A patch doesn't interact with other patches directly. It only interacts with the current state produced by other patches.

DynamicScene needs to be fleshed out, possibly with an example. How will it be used?

It is already explicitly specified in terms of its schema. It is used as the "final" baked version of a scene. It is:

1. What inheritance is resolved to.
2. What is ultimately used when spawning a scene (at least, in cases that need the dynamic system / can't be directly efficiently spawned)

The code for Patch -> DynamicScene -> spawn currently looks like this:

let mut inherits = HashSet::new();

let mut resolved_patch = entity_patch.resolve_inherits(&mut inherits);
let mut resolved_patch2 = entity_patch2.resolve_inherits(&mut inherits);

let mut scene = DynamicScene::default();
resolved_patch.recursive_patch(&mut scene);
resolved_patch2.recursive_patch(&mut scene);
scene.spawn(&mut context).unwrap();

What is the asset management story of inheritance?

1. Register a new DynamicPatch asset with the asset system (which is capable of enumerating its dependencies ... see the above code example)
2. Use the asset system to track recursive dependency load state
3. When the load has finished, bake the patch tree down to a DynamicScene
4. Spawn the DynamicScene as necessary

Does bsn have a separation between node name and node contents? The syntax is a little ambiguous, you have one example with nodes called Player1, Player2, are those different components?

Yes. Name("SomeName") is currently how you define a name component (although we may introduce special syntax for that ... but the current proposal does not include that). The Player1, Player2, etc in the code examples are defined as normal components, and are therefore components.

My experience is style inheritance is confusing and clumsy. A better approach is to parameterize. In bevy_cobweb_ui I use constants where I want things to have the same value defined globally/external to the scene, and I use params in specs where I want to configure different nodes to the same value.

I don't have strong opinions on style inheritance atm. The proposed short-term / already implemented "inheritance as styles" approach does imply that a style could inherit from another style. But for the more complete "final" style system I consider this an open question worth resolving on its own time.

bevy_cobweb is also a mature reactive library with a style much closer to hooks/observers. In my experience using bevy_cobweb_ui, having proper systems as UI reactors that are decoupled from 'figuring out what to react to' is quite helpful. For example, I use a TextEditor system param to write text in reactors, which does zero-alloc writes and integrates localization.

I'll look into it!

[bushrat011899]

Reading over this proposal I'm generally in favour of everything presented, and largely how it's presented too. I do have some concerns around the Construct trait, in particular the concrete nature of ConstructContext. Having the fields of this context public is good since it allows sharding mutable access to its fields (e.g., reading Entity while holding mutable access to the World). Further, there is precedent for this in Jai. So to be clear, I do like this mechanism.

What I'm concerned about is creating a very rigid type effectively at the core of the ECS, whose internals are fully public, making breaking changes quite likely (and potentially painful!). As an example, this Construct trait seems useful for Resources, yet they will not have an Entity available for their Context.

It will require some type-shenanigans to setup, but I believe we want to be generic over the Context-type, similar to the unstable Allocator API.

impl<CX: Provides<Entity> + Provides<World>> Construct<CX> for Foo {
    type Props = Bar;
    
    fn construct(context: CX, props: Self::Props) -> Result<Self, ConstructError> {
        let entity = context.take::<Entity>();
        let world = context.take::<World>();

        // ...
    }
}

Within Bevy, there is a similar system built up with the FromWorld trait, effectively treating the World as the context that provides the required information for constructing a type. As such, I think there is room to replace FromWorld with a slightly more general form of Construct:

// Before...
impl FromWorld for Foo { ... }

// After...
impl<CX: Provides<World>> Construct<CX> for Foo { ... }

From an order of implementation perspective, I think the Construct trait should be tackled first out of all the proposed items here, as it's foundational to the rest of the proposal while also providing strong functionality to Bevy in its own right.

[cart]

I do see the appeal of a "generic context / provider API", but in practice World largely serves to be a "universal context" already, in that it provides the context.take::<X>() API in the form of world.resource::<X>() etc. In practice, the Provides trait would be a direct World shim 99% of the time. The only mismatch I anticipate encountering for the current Construct API is the "resources don't need entities" problem, and that could be resolved with either Option<Entity> or Entity::INVALID.

From a usability / readability perspective, this seems like a pretty massive downgrade for resource init:

// Before...
impl FromWorld for Foo { ... }

// After...
impl<CX: Provides<World>> Construct<CX> for Foo { ... }

I have a pretty strong inclination to keep it simple here. I think a "generic context" API verges on over-engineering.

[JMS55]

Initial very ill-defined thoughts:

1. Required components make me a bit scared about discoverability. Bundles are nice because they're self-documenting about what they contain. How does rustdoc/RA support work for required components? Also I forsee a lot of ugly long list of vertical attributes if rustfmt formats it poorly 😅
2. You lost me at the patch section. The APIs shown feel kinda alien. The existing spawn/insert/etc entity components APIs are super simple. The patch APIs kinda completely lost me. Now there's construct, and construct patch, and these entity patch things? And you have both props, and values? I don't really understand the EntityPatch API, I could use some more info on its fields
3. DynamicPatch is very vague. There's not much text written about it, I don't understand how it compares to EntityPatch. Is EntityPatch type-system level compile time patches? And DynamicPatch is for runtime-constructed queries?
4. How does patch fit in with BRP? BRP essentially already describes how to patch worlds (add component, replace component, spawn entity, delete child, etc). Beyv_dioxus has a very very similar system as well https://github.com/JMS55/bevy_dioxus/blob/main/src/apply_mutations.rs#L60-L289
5. For dynamic patch, have you looked into existing patching systems from stuff like dioxus or phoenix liveview, and how they efficiently encode tree diffs?
6. Do you support relative entity paths? E.g. take an entity/scene, go down 3 children, right 1 sibling, modify component Y? Some kind of EntityPath?
7. The BSN inheritance example didn't show it, but I assume that Transform has more than one field? I expect/hope that you can override part of a component, and not only the whole thing all or nothing
8. What is @ in BSN specifically? It's shown as some kind of construct shortcut thing, but not really defined as what it compiles to I don't think
9. I don't know how I feel about the observer/event handler stuff. I haven't yet used observers or hooks in bevy 0.14 to be able to comment. Seems a bit boilerplate-y to define new events though, despite usage being fairly ergonomic.
10. Please no cascading styles / components. I'd rather just specify it manually on every node, or have some kind of global defaults via defining my own Node<S: Style> wrappers and then type aliasing Node = Node<MyStyle> or something. That said "scoped context" is a very important kind of node in UI systems, and I expect maybe game logic too. Although you can kind of mimic it via traversing the tree up from the current entity during construct until you get to the context node. Think <Animated/> HTML divs where you wrap some child divs and they all share the same animation timer.
11. I'd rather rename UiImage to Image over Img.
12. What does Reflect look like in a post-BSN world?
13. RE: Syntax - Take a look at GTK blueprints https://jwestman.pages.gitlab.gnome.org/blueprint-compiler, a replacement for GTK's old XML-based declarative system
14. What replaces bundles of things that aren't required together, but are often used together, as hints for what kind of components you commonly want together? E.g., MeshMaterialBundle.
15. It seems like there's no way to insert a raw Handle<T> component on an entity with BSN? I don't see how you would do bsn! { @foo.my_asset }. It seems like you need a wrapper type to provide the expected asset type via the field type. Does that mean we're going to remove the component impl for handles?

[cart]

Required components make me a bit scared about discoverability. Bundles are nice because they're self-documenting about what they contain. How does rustdoc/RA support work for required components?

From a documentation perspective, we've found a way to auto-generate Rust doc entries for the components in the require list (via the derive macro). From an RA perspective we do lose strong suggestions for "sibling" components as you type. However you can always press F12 on a given type to go-to-definition, which will have the top-level list of required components. And because of how the macro is implemented, you can then press F12 on any of those components to navigate to their definition. So the tree is explore-able.

I do concede that having a flat list is better from a discovery perspective. But as mentioned in the post, that introduces its own large set of issues. From my perspective, required components more than justify this tradeoff.

Also I forsee a lot of ugly long list of vertical attributes if rustfmt formats it poorly 😅

For long lists of attributes, this is how it formats it:

#[derive(Component)]
#[require(
    Style,
    BackgroundColor,
    BorderColor,
    BorderRadius,
    FocusPolicy,
    Transform,
    Visibility,
    ZIndex
)]
pub struct Node {
}

In this case, it stops formatting as one line with the addition of Transform. I don't see this as being particularly heinous, especially given that the equivalent Bundle struct would always be a vertical list. At least with attributes it stays flat and short for components with ~5 or fewer requires.

You lost me at the patch section. The APIs shown feel kinda alien. The existing spawn/insert/etc entity components APIs are super simple. The patch APIs kinda completely lost me. Now there's construct, and construct patch, and these entity patch things? And you have both props, and values? I don't really understand the EntityPatch API, I could use some more info on its fields

I'm going to assume you understand the main Construct API (and how Props relates to it), as that is covered pretty extensively.

The Patch API exists to encode setters of specific Props fields in a repeatable way. An actual instance of a Construct::Props type (ex: PlayerProps) is not suitable for encoding a path, as we have no way of distinguishing between a field that has been set explicitly and a default value. In order to support "layers of patches" that apply on top of each other, we need a way to encode only the fields for a given type set on a given layer.

Because a Patch does ultimately need to become a spawned scene, we also need to encode the actual Construct type (not just the Construct::Props type). This is what ConstructPatch<C: Construct, F> exists to do:

1. It holds the F function, which takes &mut Construct::Props and sets fields on it. This is the "patch logic".
2. It holds the C type, ensuring we can call C::construct(context, props) to construct the final C component.

EntityPatch is a "patch tree". It contains a set of patches for a given entity's components (EntityPatch::patch), plus patches for all of its descendants (EntityPatch::children). To allow it to encode inheritance information, it also holds inherited asset paths (EntityPatch::inherit).

Pretty straightforward. From an applied perspective, EntityPatch exists to be "the thing that the bsn! macro produces". From a user facing perspective, most people will never need to look at it or understand it.

DynamicPatch is very vague. There's not much text written about it, I don't understand how it compares to EntityPatch. Is EntityPatch type-system level compile time patches? And DynamicPatch is for runtime-constructed queries?

Yup I definitely waved my hands a bit here as I haven't yet implemented DynamicPatch. Yes, EntityPatch is for type-system-level compile time patches. DynamicPatch is the equivalent for dynamic scenes. Rather than setting Construct::Props fields directly, it will set Reflect fields instead. And rather than rely on static type information, it will be populated using TypeRegistry information.

How does patch fit in with BRP? BRP essentially already describes how to patch worlds (add component, replace component, spawn entity, delete child, etc). Beyv_dioxus has a very very similar system as well https://github.com/JMS55/bevy_dioxus/blob/main/src/apply_mutations.rs#L60-L289

I haven't personally thought much about whether or not it makes sense to unify BRP (which has full CRUD ops) with the scene patch system. Obviously EntityPatch would be incompatible because BRP is a dynamic protocol. We might be able to unify DynamicPatch with BRP, but I haven't really explored the implications of that yet. I suspect that it wouldn't yield significant fruit given the different use cases (ex: BRP patches dont need to support inheritance / that could be confusing), but thats just a hunch.

For dynamic patch, have you looked into existing patching systems from stuff like dioxus or phoenix liveview, and how they efficiently encode tree diffs?

I haven't! I'd like to stress that the current system doesn't exist to be a full reactive tree-diff system, but rather a scene-layering system. Ex: I'm not sure we can/should support removals in this patch system. In general, whether or not we can/should use this as a mechanism for reactivity is an open question. In terms of the MVP, I'm personally biased toward keeping this simple and direct-needs-driven. But we can discuss.

Do you support relative entity paths? E.g. take an entity/scene, go down 3 children, right 1 sibling, modify component Y? Some kind of EntityPath?

This is a part of the plan / I've experimented with it. I very briefly called it out in the post, but I go into a bit more functional detail in this comment.

The BSN inheritance example didn't show it, but I assume that Transform has more than one field? I expect/hope that you can override part of a component, and not only the whole thing all or nothing

Correct. Transform has more than one field, and overrides are per-field. This is the purpose of the Patch system. Given that you're asking this question, I suspect thats where the "patches are confusing" question came from.

What is @ in BSN specifically? It's shown as some kind of construct shortcut thing, but not really defined as what it compiles to I don't think

@thing expands to ConstructProp::Prop(thing.into()). I cover BSN syntax code expansion in depth in the "bsn! Code Expansion" section.

I don't know how I feel about the observer/event handler stuff. I haven't yet used observers or hooks in bevy 0.14 to be able to comment. Seems a bit boilerplate-y to define new events though, despite usage being fairly ergonomic.

Depends on the path we take. If we roll with observers directly, then the event declaration boilerplate is essentially nothing. If we roll with Component-driven event handlers, that does require some boilerplate. Open question in general, but I'm optimistic. I think we should start with direct-observers as we'll want to support that no matter what.

Please no cascading styles / components. I'd rather just specify it manually on every node, or have some kind of global defaults via defining my own Node<S: Style> wrappers and then type aliasing Node = Node<MyStyle> or something.

Definitely a discussion worth having (later imo). Fortunately the MVP (as proposed) will rely solely on the "free" styling we get from direct inheritance of styles. Which is roughly what you're calling out here.

That said "scoped context" is a very important kind of node in UI systems, and I expect maybe game logic too. Although you can kind of mimic it via traversing the tree up from the current entity during construct until you get to the context node. Think <Animated/> HTML divs where you wrap some child divs and they all share the same animation timer.

Yup this is definitely something we'll need to discuss and design.

I'd rather rename UiImage to Image over Img.

Image is already taken by the Asset. Open to renaming that though. Barring that, I strongly prefer Img over UiImage for reasons that I hope are obvious.

What does Reflect look like in a post-BSN world?

Same as it did before. BSN assets still rely heavily on Reflect. BSN also relies on Reflected Functions, which @MrGVSV has already implemented.

RE: Syntax - Take a look at GTK blueprints https://jwestman.pages.gitlab.gnome.org/blueprint-compiler, a replacement for GTK's old XML-based declarative system

I took a look! I do like it in general, although I'm not so sure about the [attribute] syntax. I definitely see the overlap in our needs though.

What replaces bundles of things that aren't required together, but are often used together, as hints for what kind of components you commonly want together? E.g., MeshMaterialBundle.

Bundles can still fill that role. They can also implement/derive Construct and can be used in BSN. I personally think we should embrace the "tree style with something primary at the top driving the requirements" spawning mindset in general. Ex: MeshMaterialBundle should probably be replaced by something like SomeMaterial->Mesh->Transform. In practice we could have a non-generic MaterialMesh marker component that pulls in all dependencies required. But for cases that really need them, Bundles are the break-glass solution to that problem.

It seems like there's no way to insert a raw Handle component on an entity with BSN? I don't see how you would do bsn! { @foo.my_asset }. It seems like you need a wrapper type to provide the expected asset type via the field type. Does that mean we're going to remove the component impl for handles?

I do want to entertain the idea of not using Handles directly as components (and instead defining context-specific wrapper components). That being said, I do think we need top-level type-only Construct syntax regardless of where that conversation goes. In my personal notes I've used this, which feels like a natural extension of the @ syntax:

Handle<Mesh>@"mesh.obj"

I think it pretty clearly reads as a "type hint for @"mesh.obj"".

This is notably unambiguous with tuple-struct syntax:

Handle<Mesh>(@"mesh.obj")

[JMS55]

Bundles can still fill that role. They can also implement/derive Construct and can be used in BSN. I personally think we should embrace the "tree style with something primary at the top driving the requirements" spawning mindset in general. Ex: MeshMaterialBundle should probably be replaced by something like SomeMaterial->Mesh->Transform. In practice we could have a non-generic MaterialMesh marker component that pulls in all dependencies required. But for cases that really need them, Bundles are the break-glass solution to that problem.

Oh ok, didn't realize Bundles were staying. The thing I wanted to bring up specifically is that Material can be used with Mesh, but also e.g. MeshletMesh, and so it would be nice to have something like a bundle to group them.

[extrawurst]

I am very excited about this proposal and the impression that an MVP of this is not far, as I do agree that it only will get proper feedback once all have their hands on it and can give it the reality-test, there is only so much we can anticipate based on theory, at least I (being a non core bevy dev, and more of a user) can't.

That being said I am missing a section about the way backwards or serializing back down into a bsn asset file. Looking at existing editors concepts like space_editor it seems so far one has to invent their own serialization format to make this a two-way-street where stuff can be loaded from an asset file, edited and then save back to one. The new scene/patch bsn format should obviously standardize this. will the MVP contain a simple serialize for anything in the hierarchy to drop it into an asset file (including all dependencies)? What is your vision here?

My other big concern is how we want to pull of the asset versioning in practice? My assumption is that we can leave everything out of a bsn-descriuption that we assume default so what if that default changes from one version to another? a field might need to suddenly be explicit where in the asset file it is not. for the version resolve that means it would need to know the entire assets defaults at each version, correct?

[cart]

That being said I am missing a section about the way backwards or serializing back down into a bsn asset file

I agree that turning runtime state into BSN is desirable, but I'd also like to call out a number of challenges:

1. Construct::Props -> Construct -> Construct::Props does not necessarily round-trip. Ex: up until Asset V2 AssetPath -> Handle<Mesh> would lose the AssetPath, as Handle didn't store it. Fortunately in Asset V2 we do now store the AssetPath on Handles, so this is trivially round-trippable. But the point remains: this conversion can be lossy. I suspect that all built-in Bevy Construct impls will be able to round trip (either via reading data on the type, or by reading data from the current World context). But we'd need to design the system in such a way that fails in the event that a conversion from Construct -> Construct::Props is impossible. For impl Construct for T: Default, we can trivially round trip.
2. We drop "patch layer" / inheritance information, as we spawn a "flattened" entity. We can't really know if the current value of a Component's field came from something at runtime, from the top-level scene, or from an inherited scene. In general, I think trying to tie back to the scene context and define values relative to it is a hard / maybe impossible challenge. Better to just serialize the world as it exists.

In general I think direct whole-world serialization is an anti-pattern. I think its wrong to assume that all runtime state can be losslessly serialized and then deserialized. Most people want to do this in the context of save games, which is alluring, but I think its generally better to define a driver format / types for save games (or at the very least, define an opinionated slice of the world to serialize).

In general my take is "I think this is possible, it will require some elbow grease, and it isn't a first priority". Godot gets by just fine with a one-directional format. Its worth trying to make this work, but lets do it on its own time. I suspect making it bulletproof will take a good chunk of time. The general shape of it will be "add support for opting-in to defining a Construct -> Construct::Props conversion edge, which behaves like Construct but in reverse. Fail or warn when it doesn't exist."

My other big concern is how we want to pull of the asset versioning in practice? My assumption is that we can leave everything out of a bsn-descriuption that we assume default so what if that default changes from one version to another? a field might need to suddenly be explicit where in the asset file it is not. for the version resolve that means it would need to know the entire assets defaults at each version, correct?

Yup. This hinges on being able to diff schemas (including defaults) across Bevy versions to determine how to migrate a given version of an asset file. In general if a default changes and the value wasn't explicitly set by the user, then we should just let it transparently change without any changes to the scene. For example: a user manually checking a bool checkbox in the editor would record the value in the scene. This is effectively saying "I care about this value and I want it to be explicitly preserved across bevy versions". However if they don't check it manually and then later the default changes, it will automatically / implicitly be checked after the migration (without any changes to the scene file).

[notmd]

Thanks for your work, really like this proposal. Question about EntityPatch children with inheritance. With the following patch.

let entity_patch = EntityPatch {
    inherit: AssetPath::from("other_patch.bsn"),
    patch: (),
    children: (
        EntityPatch {..},  // let call this NewChild
    ),
};

And the other_patch tree is something like this

EntityPatch {
    inherit: (),
    patch: (),
    children: (
        EntityPatch {..}, // Let call this OldChild
        EntityPatch {..}, // This as well
    ),
 }

What will the final tree? It will be Parent > (OldChild, OldChild, NewChild) or Parent > (NewChild)? The second behavior is more expected I think.
However both results are not what I want if I want to patch the second OldChild only. Maybe we need special patch component eg:

patch: (
  Child(1, SomeComponent {..})) // patch the second child
)

And nesting

patch: (
  Child(1, Child(0, SomeComponent {..}))) // patch the first child of the second child 
)

But what if the patch child does not exist? Runtime panic or warning or something? And what if I want to inheritance without any children leaving the tree only Parent?
This basically is the 6th point of JMS555 comment.

[hymm]

Feels like we might need something like React keys to disambiguate which children you're working with.

[notmd]

After thinking I think we should merge the children into patch instead since Children already is a component. And ignore partial patching for MVP.

patch: Children((Child, Child)) // overwrite all parent's children with 2 children
patch: Children(()) // override with no children
patch: () // doesn't patch the `Children` component means fully inherit them

For partial patching maybe we can come up with this API:

patch: Children(|old_children| {
  ...
})

This API is similar to Render Props Pattern in React where you pass data and let the children decide how to render them.

[cart]

Currently it concatenates children (so the first option in your examples). I do think we'll want to have the ability to define insertion points in parents so they can do something with children provided by an inheritor. Also worth exploring being able to query for + insert at specific locations. In general I consider this an Open Question.

[mintlu8]

The main thing I'm concerned about is what is bsn going to be based on? If serde it would be easy to use most third party libraries with it with out of the box. Additionally serde is much more expressive at doing slightly weirder things than Reflect or most other approaches current is. Granted the average rust users probably will avoid a manual Deserialize implementation if possible. If not using serde and not providing good ergonomics for manual implementation like Reflect current is, it might fracture bevy from the rust ecosystem if not done carefully.

See my crate bevy_serde_lens as an example of using entirely serde to construct an entity hierarchy, as there is some overlap here.

[BD103]

I could definitely see a custom parser and serializer, but I don't think it would be based on serde since that is too generic over the data that can be used.

In this case, I'm thinking a parser built from scratch using logos and chumsky. logos has fast tokenization using LUTs, while chumsky has fantastic error handling and a nice combinator API. (Then again, I could see multiple competing implementations of bsn.)

[ncthbrt]

I would like to advocate for two animation related features when it comes to reactive bsn.

The first feature is programmable transitions. I think it's an important function of crafting highly dynamic ui and animations ergonomically.

In principle how is I'd envision that it'd work would be that entity removal and addition logic would be handled by the parent container instead of automatically sending commands to immediately remove/add the child entities from the tree. The container for example could add a component to the relevant children that would use a system to animate in or out the child elements.

This is better than the alternatives seen in frameworks like react where both old and new subtrees have to be kept untidily around in the markup in order to animate transitions.

The second feature would likely be easier to add later but think would be a huge boon for continuous animations (think health bars, sliders, or graphs). Here the functionality would extend the proposed React macro to allow one to specify an interpolator that would apply to the reactive component. This could for example be a spring interpolator or a tween. This functionality is directly inspired by SwiftUIs implicit animations which have seen a lot of success in practise.

[cart]

Currently my impl uses a custom parser in combination with Reflect for deserialization. Given how Reflect-driven Bevy is generally, I think this is the way to go for BSN as well. I do think we will want opt-in serde support for specific values, in order to support ecosystem types (although remote reflect can also handle that). I'm also open to including a full BSN serde impl, but I suspect some aspects of BSN will be hard to encapsulate in the serde data model. It may also be possible to be fully serde driven + drop the custom parser, but I wanted to take the clearest least questionable path first.

[josfeenstra]

Thank you for the extensive write up Cart, this looks amazing. As @extrawurst says, for me as a bevy user, its too early to judge anything, it will have to be played with to truly understand what the consequences are. I'm mostly just super grateful for your continued effort on improving ergonomics! 🙏

[CooCooCaCha]

Overall, I'm excited for the direction this is taking. I have some concerns but I think we definitely need something "construct, patch, and bsn shaped". My main concerns are around entity identifiers, partial patching, and being able to remove children/components via patches.

Partial Patches

Are patches meant to be a complete description of the entity hierarchy? Or do you intend to support patches that only affect some of the entities?

Patch Removal

It looks like patches are purely for adding/modifying, what are your thoughts on allowing patches to remove entities/components? Is that an anti-pattern?

Entity Identifiers

After some discussion in discord it seems very useful to have a way to uniquely identify entities. Here are some use-cases:

1. Re-ordering children without destroying and recreating them.
2. Using patches to add components to specific objects in GLTF files.
3. Removing specific entities via patches while keeping references intact. For example, if I have a base scene with 10 children and I remove the 5th child, any patches I made on-top of the base scene should still reference the same children. Without identifiers the 6th child becomes the 5th child so it would (incorrectly) inherit the previous 5th child's components.

[viridia]

Also, the approach of assigning unique names to entities breaks down when you have dynamic lists of children. Again, the example of a for-loop: you might produce 0, 1 or 10 children. Do you give each child a unique name? How will you know which children need to be replaced if the list grows or shrinks? (I suppose you could do some kind of prefix/pattern match, but this seems like an egregious hack).

The slot-based approach is much more robust: you know in advance exactly which child elements are part of dynamic list and which aren't, because that's built in to the structure of the template. So replacing them becomes trivial.

[CooCooCaCha]

I wouldn’t say unique names “break down” since efficiently handling dynamic children is one of the major use-cases of unique names. I also don’t see how slots replaces the need for unique names.

Do you give each child a unique name?

What I’m suggesting is similar to keys in react, so yes you would give each child a key/id/name if you want that child to be stable across updates.

Without unique names, how do you efficiently handle cases like children being re-ordered? Ideally you’d just change the Children array for the given parent and be done.

Also, what if I wanted to animate children being re-ordered? I need some way to know that Child A went from position X -> Y, and I don’t see how you do that without identity. I could see this being useful for things like scene transitions, and visually pleasing animated lists where players can drag and drop to reorder a list.

[viridia]

Look at how Solid.js handles re-ordering of children in it's <For> directive. For maps an array of data elements into a template which is invoked for each child; the data elements are compared (either directly or using a custom comparator function which you pass in), allowing it to compute a diff from the previous output. Computing a "key" value is one way that the comparator fn can work, but it's not the only way; if the data item is simple enough or comparisons are cheap it can skip that and just compare the array items directly. There's no need for an explicit "key" attribute on the element like in React. This is how I've implemented it in Quill.

While giving each child a unique name can help matching individual children (old version vs. new), it doesn't help with operating on the entire set of generated children. Suppose the data changes in a way such that none of the names match, meaning that you want to delete all of the old children and replace them with new children - you still need some method to know which child elements are produced by the for-loop, so that you can delete the old ones without touching any other elements that were generated by other parts of the template. In this case, names won't help you.

My argument, then, is that it's dangerous for any outside code to reach inside the template and start messing around with the structure of the hierarchy it generates. Instead, the template should be a kind of "formula" consisting of constants and variables, and the output of that formula should be encapsulated - treated as a black box. If we want to compose different templates together or layer content, that should be done by manipulating the inputs to the template, not the outputs.

[CooCooCaCha]

Right, which gets to my point about identity. Whether it’s a key or an equality function, you need some way to say “this thing is the same thing as before”, and slots don’t solve that by themselves.

If we want to compose different templates together or layer content, that should be done by manipulating the inputs to the template, not the outputs.

That doesn’t always work though, for example, if you want to import a GLTF file and patch components onto pieces of the GLTF. That seems like something that should be possible, and easy. In that case there are no “inputs” to manipulate, it’s just a GLTF.

Instead, the template should be a kind of "formula" consisting of constants and variables, and the output of that formula should be encapsulated - treated as a black box.

I think we have different visions of how this system should work 🙂. One thing I like about what Cart has proposed is nobody “owns” the entities. Once you’ve processed constructs and patches you’re left with plain old entities and components. After that I should be able to use normal systems with queries instead of relying on encapsulated logic like a react/solidjs component.

Reactivity is out of scope for this proposal so it’s unclear how Cart imagines this will be used when updating entity trees but I hope I can just apply a patch and still be left with plain old entities.

[cart]

@CooCooCaCha

Once you’ve processed constructs and patches you’re left with plain old entities and components. After that I should be able to use normal systems with queries instead of relying on encapsulated logic like a react/solidjs component.

I think it should be allowed to edit entities the "normal way", but I also think it should be discouraged in the context of reactive scenes. Essentially, the same model as react/solidjs + how it relates to the DOM. Aka do-it-at-your-own-risk / you-probably-shouldnt-ever-do-it.

It looks like patches are purely for adding/modifying, what are your thoughts on allowing patches to remove entities/components? Is that an anti-pattern?

I think this is an anti-pattern. I don't think when A inherits from B that it should go in and arbitrarily invalidate assumptions that the designer of B made.

Whether we actually disallow this is an open question I think. I do see the value of this in the context of, say, replacing a Material in an imported GLTF with a different Material.

After some discussion in discord it seems very useful to have a way to uniquely identify entities.

I do like the idea of being able to use patches to apply changes to scenes defined elsewhere (ex: adding / overriding values in imported GLTF file).

Godot also supports this in the context of inherited scenes and I've personally found it pretty valuable. We should investigate the implications of supporting removes in this context though. I'm not yet fully convinced its a good idea.

@viridia

The slot-based approach is much more robust: you know in advance exactly which child elements are part of dynamic list and which aren't, because that's built in to the structure of the template. So replacing them becomes trivial.

I agree with your arguments / I think slots are probably the right path forward, especially in the context of reactivity.

My argument, then, is that it's dangerous for any outside code to reach inside the template and start messing around with the structure of the hierarchy it generates. Instead, the template should be a kind of "formula" consisting of constants and variables, and the output of that formula should be encapsulated - treated as a black box. If we want to compose different templates together or layer content, that should be done by manipulating the inputs to the template, not the outputs.

Agreed. This does seem a bit at odds with the "arbitrary changes to GLTF scene on import" scenario. We should discuss if / how EntityPatch relates to that class of thing. We may want to scope EntityPatch down in the interest of "API design cleanliness", and then have a second "full/arbitrary CRUD" patch API for the more arbitrary scenarios. It seems like BRP (which also wants these arbitrary patches) might be the right solve for that category of thing. I'm thinking we could design these systems with some overlap (BSN format, still uses some Patch types, etc) and compatibility (ex: BRP patches can be applied during spawn).

Worth discussing this to find the right balance.

[musjj]

A bit of a bikeshed, but is there a reason why the syntax to describe attributes and hierarchy is separated like this:

bsn! {
    Node { width: px(200.), height: px(100.) } [
        Img { image: @"logo.png" }
    ]
}

Instead of like:

bsn! {
    Node {
        width: px(200.),
        height: px(100.),
        Img { image: @"logo.png" }
    }
}

Which is more readable IMO. Dioxus's rsx macro also uses this kind of pattern:

rsx! {
    div {
        class: "foo",
        div { class: "bar" }
    }
}

I initially assumed that this is done to make RA happy, but it looks like that Dioxus managed to solve the problem here: DioxusLabs/dioxus#2421. So were there any other reasons behind this syntax decision?

[viridia]

@cart @SanderMertens Actually, it would be helpful for me to get some degree of certainty around these issues. Quill and bevy_reactor have both been designed around the assumption that Bevy isn't going to make major changes to accommodate my needs; if that assumption is false, then it impacts my design in a big way.

There are a bunch of different design choices that I could bring up, here's a few:

• Whether or not Bevy will ever support the "hidden parents" feature discussed previously. This is the ability to annotate certain entities such that the layout/extraction/rendering code treats them as if they were replaced by their children. Without this, the reactive framework cannot insert housekeeping entities into the tree, because such entities would impact the appearance of flexboxes and grids. Simply using Visibility::Hidden won't work because the children of these entities do need to be displayed. This means, in turn, that the only robust solution is to maintain these entities in a separate tree, which means keeping two trees. The proposal here is that we'd add a new type of component, let's call it Fragment, which tells the layout system to pass over the entity when recursing downward.
• Trait Queries - both of my frameworks make extensive use of generic components, such as ReactionCell<T: Reaction> and MutableCell<T: Value>. To facilitate querying, I use a system of "thunks", where a thunk consists of a non-generic Component that contains a stateless, static, dyn trait adapter object. So for example ReactionThunk(pub(crate) &'static dyn AnyAdapter) is used to monomorphize the call to .react(). Because the thunk is non-generic, it can be queried and its methods called; because it's a static reference it can be copied. However, I'm curious as to whether Bevy will have a more officially-blessed method of querying trait objects.

[alice-i-cecile]

No strong feelings on the first question.

However, I'd really like to get trait queries in to Bevy itself at some point, assuming I can convince cart and the other ECS SMEs. I'm not sure if we should use the existing third-party implementation, or wait for a components-as-entities world and use components for each registered trait impl. Probably the former :)

[cart]

Hidden Parents

I'm not particularly opposed to this. I see the value in it ... I'm very in favor of not maintaining a fully separate hierarchy. My biggest questions are around API design: is this something that specific areas of the engine / app code need to explicitly add support for, or do we want to support it transparently? Like when something queries for its parent, does it "skip" up the hierarchy in the event of a "hidden parent", or do we return the "hidden parent". If a system needs to opt-in to this behavior, I can see how this would all fit together. If we want this to be a global / automatic thing, building that API becomes more of a challenge.

Trait Queries

First a clarifying question: in your code, does ReactionCell<T: Reaction> also implement the Reaction trait or does it just use it? I view a generic "trait query system" to be a solve for writing Query<&dyn SomeTrait>.

In a way, I think Required Components (with a marker) is very similar conceptually to a trait query system. In both cases, the author would need to manually register a given type as an "implementor" of a trait:

// Trait Queries
#[derive(Component)]
#[trait(Reaction)] // assumes MyReaction derefs into &dyn Reaction
struct MyReaction;

impl Reaction for MyReaction {}

fn system(query: Query<&dyn Reaction>) {}


// Required Components
#[derive(Component)]
#[require(ReactionMarker)]
struct MyReaction;

impl Reaction for MyReaction {}

fn system(query: Query<Entity, With<ReactionMarker>) {}

In fact, we might actually be able to use Required Components for this:

#[derive(Component)]
#[require(Trait<dyn Reaction>(make_trait::<MyReaction, dyn Reaction>)]
struct MyReaction;

// Not yet sure if this is possible
fn make_trait<C: Deref<Target = T>, T>() -> Trait<T> {
    todo!()
}

From there, we could make derive macro sugar for it (trait(Reaction) desugars to the require line above). And then Query<TraitRef<dyn Reaction>> could query for Trait<dyn Reaction> and use the internal method (and type info) stored on it to retrieve the relevant component and deref into it.

I'm not yet fully sold on upstream support for this (and/or encouraging people to use the pattern). I'm open to it though. And given that this might be possible to implement in userspace on top of required components, maybe its a conversation we can defer.

Currently trying to put this together now as an experiment.

[cart]

make_trait as written doesn't work because Deref isn't implemented for C -> T in this case. We'd need to do something closer to the bevy-trait-query approach I think.

[viridia]

I've gone ahead and file a ticket for the hidden parents feature, which goes into more detail: #14826 - this would actually be a huge win for me, it would mean an overall code reduction of something like 30-50% in bevy_reactor's core crate.

To answer the question: I suppose I could make it work either way. Currently Reaction looks like this:

pub trait Reaction {
    fn react(&mut self, owner: Entity, world: &mut World, tracking: &mut TrackingScope);
}

#[derive(Component)]
pub struct ReactionCell<R: Reaction>(pub Arc<Mutex<R>>);

The main reason for the Arc/Mutex is because the reaction gets passed a world. That is, to avoid borrowing issues, I call .clone() on the Arc before calling react - this means that the reaction reference is no longer borrowing the world, so world can be passed in.

However, nothing prevents me from having ReactionCell implement Reaction, and taking the lock internally.

All this being said, the thunk technique works, so it's not an absolute priority.

[viridia]

Let's assume for a moment that BSN would integrate some kind of reactive framework. This requires a set of reactive primitives which would exist below the level of BSN, and which can be developed in advance of BSN, just as required components have been.

There are a lot of different ways this can be designed, but the way I have done it is to define the most fundamental reactive elements as two ECS components which I call Reaction and TrackingScope:

• TrackingScope is a Component which tracks the dependencies of a computation. It also handles ownership.
• Reaction is a Component that defines what happens when those dependencies change. You can think of a Reaction as a kind of Command which re-runs whenever its inputs change.

Everything else - mutables, signals, memos, callbacks, views, templates and so on - are built on top of these two primitives. Both Quill and bevy_reactor have these primitives, despite the fact that their approach to reactivity is very different.

There is considerable leeway in the design - nothing prevents you from splitting TrackingScope into multiple components for example if that's what you prefer. But the basic functionality needs to be there, however it is represented.

Similarly, there is a lot of design choice in how the tracking scope gets populated. Currently I use an explicitly passed cx context parameter, but other options can be explored. The most important requirement is that any time the reaction reaches out to access some non-local data, that access is tracked.

So the very first step, if I wanted to incorporate this into BSN, would be to get convergence on the specific design of these two primitives, plus the ECS system used to drive them.

[benfrankel]

I read the Construct section of the proposal. It looks great, and reminds me of a few smaller things I've wanted before. I just want to note a couple IMO desirable properties that I didn't see explicitly mentioned for entity-spawning functions.

fn red_player(entity: impl EntityBuilder) -> impl EntityBuilder {
    entity
        .build(player)
        .add(Red)
}

There should be an easy path to convert a "pure" entity-spawning function that doesn't accept input data to one that does (allowing e.g. entity.build(Player { color: Color::Red, speed: 100, .. })). This is already possible for plugins and commands.

It should also be possible to spawn related entities such as children within the entity-spawning function, and probably to access &mut World (deferred via Commands or whatever). It's true that Construct gives &mut World access, but that's specifically in the scope of constructing components, not entities.

[benfrankel]

Oh also, in an ideal world there's an ergonomic way to access system parameters in both Construct (aka component-level world access) and in the entity-spawning function itself (aka entity-level world access). world.resource is only sufficient until you have more complex needs, which can happen very quickly for a real game.

[ncthbrt]

Realised I accidentally put my top level comment in an unrelated thread. Copied it here for visibility:

I would like to advocate for two animation related features when it comes to reactive bsn.

The first feature is programmable transitions. I think it's an important function of crafting highly dynamic ui and animations ergonomically.

In principle how is I'd envision that it'd work would be that entity removal and addition logic would be handled by the parent container instead of automatically sending commands to immediately remove/add the child entities from the tree. The container for example could add a component to the relevant children that would use a system to animate in or out the child elements.

This is better than the alternatives seen in frameworks like react where both old and new subtrees have to be kept untidily around in the markup in order to animate transitions.

The second feature would likely be easier to add later but think would be a huge boon for continuous animations (think health bars, sliders, or graphs). Here the functionality would extend the proposed React macro to allow one to specify an interpolator that would apply to the reactive component. This could for example be a spring interpolator or a tween. This functionality is directly inspired by SwiftUIs implicit animations which have seen a lot of success in practise.

[peterkennard]

Hello somewhat new around here, new to rust and to bevy :)

So how would one define the "Bevy Data Model". ?

"Bevy users will learn exactly one data model for everything, making it easier to "learn Bevy". Cognitive load will be reduced across the board. Context switching between UI and "the rest of Bevy" will not be required."

[peterkennard]

On Scene Saving/Loading

Yes we are a bit new to rust and bevy but have a long experience at building shared scenes, and our test app we are building is a sort of "shared whiteboard", really a general scene that in a sense, IS a multi-player game ( a multi participant/player collaboration tool) It is mostly a UI with a renderer to make it all visible.

In the past, over the years, we have set up these scenes as a "scene root" and basically blank, default camera, etc, until ones loads a scene (ie: connects to a running scene on a server).

Our entities are the parts of the scene that are loaded or saved and are basically bags of identified properties.

When one opens a scene from a server, the server starts sending a set of "commands" to the empty space, spawn entity, set position, set ( xxx named property) etc.
The first being create scene root ...

The messages can contain a collapsed set of these commands ( as a list to be potentially executed in order on the receiving entity ), so a new entity can be defined in one large message and be complete enough before making it "renderable", when a new entity is created it is created with an ID passed in from the server and all subsequent update commands are sent/routed to those IDs. The scene root is also an Entity. Entities can refer to other resources and other entities. Ie might spawn a load/get of a resource it refers to, after it is spawned and starts constructing itself.

I say updates because the same commands are used later to send updates from the server to the client's shared scene when it is "running" (ie: any entity in the scene mirror on the server ) is altered.
( why have two message sets for initialize and update ? )

Has any thought gone into what you guys are thinking to implement such a thing ?

Some of the older work we have done for complex UIs can be seen here:

https://didi.co/docs/BradPaley_June2021.pdf

An image of our fledgeling shared whiteboard app written in rust+bevy

[crvarner]

This is awesome! I'm on board with nearly everything presented. A few questions/comments/concerns:

1. Nitpick: the : parent1, parentN syntax for inheritance feels pretty foreign when included at the bottom of the tuple. It took me a few minutes to realize that this was likely inspired by the syntax for Rust supertraits (but then uses comma seperation instead of +). The fact that it is applied right to left is also strange at first glance. In cases of a single component, the proposal also does away with needing a comma, resulting in (Component :parent). This reads as if Component inherits from parent rather than the entity inheriting from parent, which feels incorrect.

Keeping in the spirit of the whole "patches are applied one by one," I think it would make more sense apply all patches left to right, top to bottom, while encouraging a convention of putting inheritance at the top:

bsn! {
    (
        :button,
        :thing,
        SpecialButton
    )
}

or

bsn! {
    (
        :button + thing,
        SpecialButton
    )
}

These both read "first apply the button patch, then the thing patch, then the individual component patches."

2. I don't love the idea of callbacks in BSN. One big reason is what @MrGVSV pointed out regarding the split between bsn! and .bsn. Can't things like OnClick already be handled in a component driven way like so?

trait Action: Debug + Send + Sync {
    fn exec(&self) {
        println!("noop");
    }
}

impl Default for Box<dyn Action> {
    fn default() -> Self {
        Box::new(Noop)
    }
}

#[derive(Debug)]
struct Noop;
impl Action for Noop {}

#[derive(Debug)]
struct StartNewGame;
impl Action for StartNewGame {
    fn exec(&self) {
        println!("start a new game");
    }
}

#[derive(Component, Debug, Default)]
struct OnClick(Box<dyn Action>);

#[derive(Component)]
#[require(OnClick)]
struct Button;

In the example above if the user does not specify an OnClick component with a Button, the default OnClick(Box<Noop>) should be constructed. The bsn could look something like this:

bsn! {
    (
        Button,
        OnClick(StartNewGame),    <- ideally we can sugar away the box
    )
}

This would play into the editor nicely. A programmer could implement a bunch of different Actions, the editor could display them as options for the required OnClick component, and the non-technical designer could wire the UI up without ever seeing a line of code.

I don't see how a designer would ever be able to create the BSN outlined in the callback examples solely via the editor GUI without significant understanding of bevy code.

[viridia]

What I think is more practical in the medium term is integration with scripting languages. That is, the BSN asset can contain a reference to some module that is an asset that contains interpretable code in Lua or Rhai or some such.

[crvarner]

In general for BSN assets, the thought is that you would reference a callback defined in code. I think it can be as simple as referencing a reflected function name.

That sounds good. I just want to avoid a future mess of huge deeply nested inline callbacks with no limit (potentially with nested bsn! macros inside). In BSN asset files I think inline callbacks are a non-starter due to the editor flow described above, but even the bsn! macro supporting inline callbacks scares me a bit. Obviously they can be used responsibly, but I don't think there is anything preventing the user from turning a single bsn! macro into a thousand line monstrosity.

[cart]

On the topic of inheritance: I do agree that the current approach doesn't feel great. Inverting the order does seem like a reasonable solve, although I don't love that you can't put the "most important" components first. I'll try to mull this one over.

Short term my priority is to get everything functional and review-ready so people can start digging into this. Once thats out we can close out the open questions (such as final inheritance syntax and behavior).

[crvarner]

What I think is more practical in the medium term is integration with scripting languages.

That definitely sounds like a cool idea. You could probably build something like this using this proposal's Construct::Prop @ syntax.

#[derive(Component)]
struct ScriptRunner(Handle<Script>);

bsn! {
    (
        ScriptRunner(@"my_script.lua")
    )
}

I don't know anything about rust/lua bindings though as far as making function calls the cross the script/rust boundary

[Fidius-jko]

Maybe:

fn parse_bsn() {
      let patch = bsn::from_text_builder("
           (
                Button,
                OnClick(@RustRef("func_a")),
           )
      ").bind_rust_ref("func_a", on_click).build();
}
fn on_click(...) {...}

[viridia]

@cart @SanderMertens I've been experimenting with the ghost nodes PR #15341 and it's working beautifully. I'm in the process of refactoring bevy_reactor to use the new feature, and so far I have ported Cond, TextComputed, ViewTemplate and view roots over to the new system. Still a lot of work to go, however.

With ghost nodes, there's no longer a need to keep around two separate trees (one for the "DOM" and a different tree for the reactive component hierarchy). Instead, the special control-flow nodes can be interleaved within the "DOM" as ghost nodes, as was discussed previously in this topic.

Take for example, the Cond (conditional) view, which implements reactive conditional statements. Cond is now a stateless builder which creates a ghost node with several components:

• A tracking scope, to keep track of the reactive dependencies of the test condition.
• A ReactionCell component which contains an &dyn CondReaction. The CondReaction is a trait object that contains three closures and a boolean. The closures are:
  • The test condition.
  • The generator for the "true" branch sub-tree of the template.
  • The generator for the "false" branch sub-tree of the template.

The test condition is re-evaluated when needed. In a non-reactive design, it would be executed every frame; in a reactive system, it's only executed when one or more of it's dependencies change. If the result of the test changes from previously, then the children of the ghost node are despawned (using despawn_descendants), and the other branch is constructed new.

In addition to avoiding the need for two hierarchies, there are other advantages:

• There's no longer a need for complex logic attaching children to parents - each ghost node is responsible for managing only its direct children.
• There's no need for complex teardown logic, you can just call despawn_recursive. This means that UIs can also be state-scoped.
• There's no need to separately track the "parent" entity from the "owner" entity.
• And here's the surprising one: you can mix frameworks!

This last point deserves some explanation: the ghost node's reactive logic is entirely self-contained, and does not require anything special in the way of parents or children - it's just components and systems driving the control-flow logic. Because of this, nothing prevents you from having children that use a different reactive framework - so it's theoretically possible to have an entity hierarchy where different parts of the tree are generated by BSN, bevy_reactor, sickle_ui, bevy_cobweb and so on. Obviously, these different frameworks are going to require different support mechanisms, so it might not be that simple, but it's not impossible.

This has resulted in the removal of a lot of code from bevy_reactor, but I suspect that even more can be removed, which is something I am working on. One puzzle I am ruminating over is that I'd like to make the View::build() method take an immutable self. Currently, the only remaining reason for mutable self is so that I can take closures. Closures are used in a lot of places in bevy_reactor, and some of those closures need to be stored into Components; but I don't want to add the Copy trait bound to closures since that makes them harder to write. Instead I want to be able to move the closure from the view into the Component. Currently the only way I know to do that is wrap the closure in an Option and make the surrounding type mutable. (I can't consume the view because it's a dyn trait object). Ah Rust...

[cart]

Extremely promising work! I know I'm perpetually just a few days away from switching back to scene/ui mode, but I swear I'm very close now :)