Scene Components

[cart]

Objective

It is essentially a Bevy rite of passage to define a Player component and then ask "ok when I spawn Player, how do I spawn all of the other entities / components / scenes it needs to function with it?".

In Bevy, components are the "unit of behavior". The presence of a component indicates that the entity should behave a certain way. Scenes are inextricable from behaviors, yet currently there is no way to tie Components (bevy's unit of behavior) to scenes. This is a fundamental gap in the Bevy data model. It is a problem that developers expect their engine to solve for them.

It is high time that we had an official solution to this problem. BSN was built to be that solution, and it is now time to do the last-mile work to facilitate the Component <-> Scene relationship

Solution

It is now possible to define "scene components", where SceneComponent: Component:

#[derive(SceneComponent, Default, Clone)]
struct Player {
    score: usize
}

impl Player {
    fn scene() -> impl Scene {
        bsn! {
            Transform { translation: Vec3 { x: 10. } }
            Children [
                LeftHand,
                RightHand,
            ]
        }
    }
}

This enables inheriting from the Player component as a scene:

world.spawn_scene(bsn! {
    :Player { score: 0 }
})

After the inherited Player scene component is spawned, the entire scene is available. This means that you can Query<&Player> in your ECS systems, and trust that the entire scene is also present.

Inheritance Syntax vs Patch Syntax

Notice that this uses inheritance syntax in BSN (:), rather than normal "component patch" syntax (ex: bsn! { Player { score: 0 } }. Semantically these are different things:

• Scene inheritance syntax: constructs the full scene and inherits from it
• Component patch syntax: Just patches the component directly and creates it if it doesn't exist. This will not do any scene inheritance. You can still patch scene components this way as long as the scene component is inherited somewhere "earlier" in the inheritance hierarchy.

Attempting to spawn a scene component on its own without the scene (ex: commands.spawn(Player::default())) will log an error, as Scene Components should never exist without their scene.

Custom Scene Functions

When deriving SceneComponent, it defaults to using Self::scene as the "scene function". Scene functions can also be manually specified:

#[derive(SceneComponent, Default, Clone)]
#[scene(player)]
struct Player {
    score: usize
}

fn player() -> impl Scene {
   bsn! { /* scene here */}
}

Inherit BSN Asset Paths

Alternatively, a scene asset path can be specified:

#[derive(SceneComponent, Default, Clone)]
#[scene("player.bsn")]
struct Player {
    score: usize
}

Once we port the glTF loader to BSN, this will also be supported:

#[derive(SceneComponent, Default, Clone)]
#[scene("player.gltf")]
struct Player {
    score: usize
}

Scene Props

Sometimes it is desirable to "parameterize" a scene: pass in values to the scene which determine what the scene outputs are.

The answer to this in BSN is "scene props":

/// A UI widget that repeats "hello" text a given number of times.
#[derive(SceneComponent, Default, Clone)]
#[scene(HelloRepeaterProps)]
struct HelloRepeater;

#[derive(Default)]
struct HelloRepeaterProps {
    repeat: usize,
}

impl HelloRepeater {
    fn scene(props: HelloRepeaterProps) -> impl Scene {
        let hellos = (0..props.repeat)
            .map(|_| bsn!{ Text("hello") })
            .collect::<Vec<_>>();
        bsn! {
            Node
            Children [
                {hellos}
            ]
        }
    }
}

world.spawn_scene(bsn! {
   :HelloRepeater {
       @repeat: 5
   } 
});

Notice the @field syntax, which specifies that a prop is being set instead of a field. Props are evaluated "immediately" at the point of inheritance where the scene is constructed. This means that they are not "patchable".

You can set both props and normal fields at the same time:

#[derive(SceneComponent, Default, Clone)]
#[scene(WidgetProps)]
struct Widget {
    value: usize
}

#[derive(Default)]
struct WidgetProps {
    border: bool,
}

world.spawn_scene(bsn! {
   :Widget {
       @border: true,
       value: 10,
   } 
});

Scene props can be used with templates:

#[derive(SceneComponent, Default, Clone)]
#[scene(PlayerProps)]
struct Player;

#[derive(Default)]
struct PlayerProps {
    head: AssetPath<'static>,
    body: AssetPath<'static>,
}

impl Player {
    fn scene(props: PlayerProps) -> impl Scene {
        bsn! {
            Transform
            Visibility
            Children [
                (Head, Sprite { image: {props.head} }),
                (Body, Sprite { image: {props.body} }),
            ]
        }
    }
}

world.spawn_scene(bsn! {
   :Player {
       @head: "big_head.png"
       @body: "small_body.png"
   } 
});

Scene Components are Template-able

#[derive(SceneComponent, FromTemplate)]
struct Player {
    image: Handle<Image>,
}

impl Player {
    fn scene() -> impl Scene {
        bsn! { /* scene here */}
    }
}

world.spawn_scene(bsn! {
   :Player { image: "player.png" } 
});

The Scene Component is Always Added

Specifying the scene component manually in the scene function is not necessary. It will be added automatically:

#[derive(SceneComponent, Default, Clone)]
struct Player {
    score: usize
}

impl Player {
    fn scene() -> impl Scene {
        bsn! {
            // No need to specify a Player component here.
            // It is implied!
        }
    }
}

However you can patch the scene component in the scene if you would like. This comes in handy if you would like props to contribute to the scene component's value:

impl Player {
    fn scene(props: PlayerProps) -> impl Scene {
        bsn! {
            Player {
                size_in_meters: {props.size_in_millimeters / 1000. }
            }
        }
    }
}

SceneComponent Trait

This is what SceneComponent looks like under the hood:

pub trait SceneConstructor: FromTemplate<Template: Default>
where
    <Self::Template as Template>::Output: Component,
{
    type Props: Default;
    fn scene(props: Self::Props) -> impl Scene;
}

In general, developers should prefer #[derive(SceneComponent), which derives this trait automatically, ensures the Component is never spawned without its scene, and automatically initializes the Component even if it isn't specified explicitly in the user-defined scene function.

Reusable Component Derive Logic

This PR moves the component derive logic into a new bevy_ecs_macro_logic crate and refactors it to be reusable and extendable.

This enables the SceneComponent derive to reuse and configure the Component derive. I also took the liberty of porting the redundant Resource derive logic to this system, as it follows the same pattern.

PR Todo

• Port this PR description to docs on Scene.

Whats Next

• Scene Component scene caching: It might make sense to cache unparameterized scenes (like we do for scene assets) to cut down on spawn costs. We could even have an opt-in parameterized scene cache (ex: hash the props).
• Reactivity: It is important to note that props are not reactive. They do not exist post-spawn (aka "at runtime") and they cannot be changed. However they could easily be part of a reactivity story:
  • Props as components: insert props as components and re-run the scene constructor when they are mutated
  • Signal props: Reactive "signal" types could be passed down the init hierarchy via props.
• Simpler "prop patching" codegen: currently for simplicity props reuse the template-patching logic, but this introduces a few constraints and complexities that are unnecessary. We should consider writing specialized logic for them.

[NicoZweifel]

I like the idea of a SceneComponent and macro but I really don't like making it part of the ECS and feature gating it. To me a component and the ECS is and should not be aware of what a scene is.

In Bevy, components are the "unit of behavior".

Could you elaborate? Why is this in quotes? I was under the impression systems are the behavior in an ECS, operating on the data (components).

Ofc you can encapsulate logic onto components but that's opinionated and not inherently an ECS/Bevy thing the way I see it.

I would heavily recommend solving this through architecture and not using feature flags for this since it introduces circular dependency traps among other annoyances (editors can have all flags, depending on config). Personally I dont think this is what features should be used for and this is clearly a bandaid that affects devex negatively.

TL;DR: I think its a good idea overall but I dont think it belongs in the ecs.

[cart]

I believe this is "ready". I've opted not to implement the "static" enforcement of disallowing world.spawn(SomeSceneComponent) because it is just invasive / disruptive enough to existing generic spawning workflows that I'd like to do it on its own time / in the 0.20 cycle.

[alice-i-cecile]

I really like the improved API and the better separation of concerns. Much better; I'm glad we took the time to get this right.

However, I was promised docs!

/// See the "Scene Components" sections of the [Scene] docs to see how this is used in practice.

Three complaints here:

1. I think this should be in the crate docs: the rest of our high-level explanation and usage context goes here.
2. Those docs should go over the relation to required components, at least briefly.
3. I think you forgot to actually add those docs :) Checking Scene on this branch does not reveal any new docs.

[Diddykonga]

Excellent 👍
The Component Derive cleanup is nice, still might be able to add Resource as an attribute to the Component derive but that's future work.

[NicoZweifel]

Thanks for resolving 👍

[Trashtalk217]

I did a once over for the ECS stuff and it looks good. I like that it's sufficiently well seperated from the Scene stuff.

Attempting to spawn a scene component on its own without the scene (ex: commands.spawn(Player::default())) will log an error, as Scene Components should never exist without their scene.

This is definitely a good usecase for archetype invariants, which we should look into.