Non-Fragmenting Relations and a Better Spawning API

[cart]

I've largely wrapped up my "non fragmenting relations" implementation and ported Bevy to it. One choice that remains is to pick a new spawn pattern. There are lots of options and tradeoffs here. I'll try to paint the full picture so we can make an informed decision.

First some quick terminology (not set in stone ... I just need to call these things something so we can talk about them):

1. Relationship: a new trait implemented for components that relate to another entity. This would be Parent(Entity) in our current Parent/Children implementation.
2. RelationshipSources: a new trait implemented for components that collect sources of relationships that relate to the current entity. This would be Children(Vec<Entity>) in our current Parent/Children implementation.

My immediate goals are to create the following relationships: ChildOf/Children, ObserverOf/Observers, ReactionOf/Reactions.

The purpose of this post is to share where my head is currently at and solicit feedback on these ideas. If you have opinions on what is currently stated, or you have other ideas please comment below!

Motivation

Relationships are coming! We need to decide how we will spawn them. Ideally in a way that prevents unnecessary archetype moves and re-allocations.

This is not a competing proposal with things like BSN + Next Generation Scene / UI. It is instead choosing how relationships will be spawned under the hood. There is a focus on ergonomics in this post (even if BSN also solves that problem), as we can also take this as an opportunity to improve our baseline spawn experience (giving us wins pre-BSN and making scenarios that don't use BSN better). And in this case, ergonomics and performance go hand in hand as they both involve statically defining hierarchies!

Category A: RelationshipSources (ex: Children) Bundles

This category relies on a few key pieces:

1. Adding support to Bundles to queue arbitrary commands on insertion
2. The addition of a Spawnable trait, which is implemented for all tuples of Spawn<B: Bundle>. This is what enables tuples of spawned children. This is unfortunately necessary as Bundles of bundles are ambiguous with tuples of child bundles. This is inherent to the concepts we have defined and not really a Rust limitation.
3. The addition of a RelationshipSources::spawn(spawnable: impl Spawnable) function, which returns a RelatedEntitiesBundle
4. RelatedEntitiesBundle<R: Relationship, S: Spawnable>, which both inserts the RelationshipSources component on the parent (with Vec<Entity> storage perfectly pre-allocated for the relationships) and spawns all entities in Spawnable with the Relationship component.

Note that for the sake of comparison, I am not formatting these code blocks with rustfmt and instead I use the same layout for each variant. At the end of this post I use rustfmt in one final comparison.

Variant 1: Raw RelationshipSources::spawn / spawn_one calls

world.spawn((
    Foo,
    Children::spawn((
        Spawn((Bar, OhHiMark)),
        Spawn((
            Bar,
            Children::spawn_one(Baz),
        )),
    )),
    Observers::spawn_one(Observer::new(system)),
));

Variant 2: Hard-coded shorthand functions over RelationshipSources::spawn calls

Ex: children() is Children::spawn(), child() is Children::spawn_one

world.spawn((
    Foo,
    children((
        Spawn((Bar, OhHiMark)),
        Spawn((
            Bar,
            child(Baz),
        )),
    )),
    observer(Observer::new(system)),
));

Variant 3: General purpose related! macro

This hacks around the bundle vs spawned ambiguity by treating spawned entities as "varargs" instead of a single tuple. This still produces Spawn wrappers under the hood.

world.spawn((
    Foo,
    related!(
        Children,
        (Bar, OhHiMark),
        (
            Bar,
            related!(Children, Baz),
        ),
    ),
    related!(Observers, Observer::new(system)),
));

Variant 4: Hard-coded wrappers over related!

Same as Variant 3, but with convenience wrappers for common relationships.

world.spawn((
    Foo,
    children![
        (Bar, OhHiMark),
        (
            Bar,
            children![Baz],
        ),
    ],
    observers![Observer::new(system)],
));

Variant 5: General purpose entities! macro

world.spawn((
    Foo,
    Children::spawn(entities!(
        (Bar, OhHiMark),
        (
            Bar,
            Children::spawn(entities!(Baz)),
        ),
    )),
    Observers::spawn(entities!(Observer::new(system))),
));

General Category A Thoughts

Allowing Bundles to queue arbitrary commands inherently muddies the conceptual waters a bit, which could easily produce weird or unintuitive results. I don't love opening those floodgates. However Category A manages to retain the general "Each item in a Bundle is a component" concept. Ex: (Foo, Children::spawn_one(Bar)) still inserts Foo and Children on the parent. It just also spawns Bar as a child. And unlike i_cant_believe_its_not_bsn, it doesn't require archetype changes.

Being able to count relationships and preallocate space in RelationshipSources prior to insertion is very nice, as is preventing the need for archetype moves.

There are also some significant negative performance implications: because the Spawnable children are queued as commands, in each step down the tree we are copying the entire remaining tree onto the command queue. This is essentially inherent to the approach and is frankly probably a showstopper, as this is non-linear copying behavior.

There is also currently some weirdness, as every Children::spawn() insertion overwrites the previous entries. I don't think this is an intractable problem, but we'd need to develop a "merge" concept into bundles, which I'm also extremely hesitant to do.

A1 has some extremely valuable benefits:

1. It has no special casing (Children::spawn behaves the same way as CustomThings::spawn), and the author of CustomThings::spawn doesn't need to do any legwork to get that experience. There is "one way" to do things.
2. There is no "conceptual erasure" (Children is the component being inserted in the bundle).
3. It is still "raw rust". No macros.

The relatively meager ergonomic benefits of A2 don't feel "worth it" relative to the cost of losing (1) and (2).

However the ergonomic cost of Spawn() and RelationshipSources::spawn() is high. We're paying a pretty high clarity cost.

The related! macro in A3 is still "generic", removes both Spawn() and RelationshipSources::spawn(), and allows us to remove the spawn vs spawn_one distinction. But it introduces macros (inherently something we try to avoid) and weirdly co-locates the RelationshipSources type with children (it kind of looks like the "first child").

The special cased macros in A4 solve the co-location weirdness and improve ergonomics at the cost of completely erasing the RelationshipSources collection type.

A5 is not as ergonomically pleasant, but it does have the benefit of requiring no special casing. Ideally we could merge them into Children::spawn!(Foo, Bar), but this style of macro isn't supported in rust to my knowledge.

Category B: Effects

Effects allow the expression of the same general patterns as Category A, but they are expressed statically in such a way that does not require adding commands to bundles.

Effects are implemented for components and tuples of Effects (which means they look like Bundles, but they aren't!).

This resolves a couple of problems with Category A:

1. It improves the performance. We're no longer writing to the command queue. Instead, Effect statically split into a Bundle and an AfterEffect (essentially an EntityCommand). The AfterEffect is applied directly onto the resulting EntityWorldMut after spawning the Bundle. This will still write data to split out bundles to insert from after effects, but it happens on the stack (and I suspect we could actually hack out the stack writes entirely with some targeted unsafe code).
2. By introducing the Effect vs Bundle separation, we allow effects to operate directly on the entity.
3. It opens the doors to effects being "spawn only" (aka spawn takes Effect, insert takes Bundle). This would resolve the "inserting Children overwrites old children problem" (by nature of disallowing the Children spawn effect on insert).

Fundamentally, this suffers from the same ergonomic and conceptual problems a Category A, but it resolves some of the performance concerns.

One major downside is that non-component Bundles require a wrapper. Ex: world.spawn(BundleEffect(MyBundle { a: A(0), ..default()} )), or alternatively world.spawn_bundle(MyBundle {a: A(0), ..default()}). Given the massive reduction of custom bundle prominence and the benefits of Category B, this seems reasonable to me.

If we adopt this pattern, I think we should discourage effects that "appear like components but do not produce the component they appear to produce".

I'm omitting the variants as they are the same as Category A.

As an aside, I'll note that @viridia has campaigned for something in this category before.

Category C: Single-Relationship Bundles

This is essentially the same approach as Category B, but applied to the Relationship instead of the RelationshipSources

Variant 1: Raw Relationship::spawn calls

world.spawn((
    Foo,
    ChildOf::spawn((Bar, OhHiMark)),
    ChildOf::spawn((
        Bar,
        ChildOf::spawn(Baz),
    )),
    ObserverOf::spawn(Observer::new(system)),
));

Variant 2: Hard-coded shorthand functions over RelationshipSources::spawn calls

world.spawn((
    Foo,
    child((Bar, OhHiMark)),
    child(
        Bar,
        child(Baz),
    ),
    observer(Observer::new(system)),
));

Variant 3: related! macro

    world.spawn((
        Foo,
        related!(ChildOf, Bar, OhHiMark),
        related!(
            ChildOf,
            Bar,
            related!(ChildOf, Baz),
        ),
        related!(ObserverOf, Observer::new(system)),
    ));

Variant 4: Hard coded wrappers over related!

Roughly the same as Variant 2 ergonomically, but it enables tuple flattening.

    world.spawn((
        Foo,
        child!(Bar, OhHiMark),
        child!(
            Bar
            child!(Baz),
        ),
        observer!(Observer::new(system)),
    ));

Variant 5: related function

    world.spawn((
        Foo,
        related(ChildOf, (Bar, OhHiMark)),
        related(ChildOf,
            (
                Bar,
                related(ChildOf, Baz),
            )
        ),
        related(ObserverOf, Observer::new(system)),
    ));

General Category C Thoughts

This whole category has the downside of no-longer preserving the "bundle is just components inserted on the entity" concept. (Foo, ChildOf::spawn(Bar)) looks like we're inserting ChildOf on the parent, which is not the case. And when specifying ChildOf (like we do in V1 and V3), it reads like Foo is a ChildOf Bar. The weirdness factor on this is higher. Spawning children under Children makes much more sense in this context.

However this does have the benefit of removing the need for Spawn without needing macros, which is very nice. Unlike the best options in B, C1, C3, and C5 still expose one of the relationship symbols. C3 and C5 help protect against the confusion in C1, as the Relationship is inside the related scope instead of adjacent to other components.

The special cased child syntax in V2 reads very nicely and is very ergonomic (even without the macros in V4). However it requires special casing to be nice and it completely erases both the Relationship and the RelationshipSource symbols. Both of these feel like huge losses to me.

This whole category makes it more challenging to pre-allocate space in the RelationshipSource collection and naively prevents inserting the RelationshipSource alongside the bundle (as each Effect would try to produce a RelationshipSource, which would result in duplicate components, which is invalid), meaning it will need to cause a table move on the first insert, barring a solution to the problem that I haven't fully conceptualized yet (ex: a "mergable" relationship source bundle that is lazy and joins duplicates, producing a count, which is used to allocate a single RelationshipSource with capacity for all of the children).

Category D: Builders like we have today

Variant 1: Generic related / related_one calls

world
    .spawn((Name::new("Hello"), Transform::from_xyz(1.0, 2.0, 3.0)))
    .related::<Children>(|p| {
        p.spawn((Transform::from_xyz(0.5, 0.5, 0.5), OhHiMark));
        p.spawn(Transform::from_xyz(0.5, 0.5, 0.5))
            .related::<Children>(|p| {
                p.spawn(Transform::from_xyz(0.1, 0.1, 0.1));
            });
    })
    .related_one::<Observers>(Observer::new(system));

Variant 2: Hard-coded wrappers over generics for common relationships

world
    .spawn((Name::new("Hello"), Transform::from_xyz(1.0, 2.0, 3.0)))
    .children(|p| {
        p.spawn((Transform::from_xyz(0.5, 0.5, 0.5), OhHiMark));
        p.spawn(Transform::from_xyz(0.5, 0.5, 0.5))
            .child(Transform::from_xyz(0.1, 0.1, 0.1));
    })
    .observer(Observer::new(system));

General Category D Thoughts

This doesn't rock the boat too much. Pretty much everyone dislikes writing closures. V1 is general purpose but even worse than the current status quo ergonomically. Special cased builder functions for common relationships is essential for ergonomics.

We can / should support these APIs no matter what. But I think we can do better for our go-to spawn API.

Category E

Same as Category B, but instead of the Effect/AfterEffect split, you just always spawn with a (Bundle, AfterEffect) pair:

world.spawn(
    (Name::new("Hello"), Transform::from_xyz(1.0, 2.0, 3.0)),
    (
        Children::spawn((
            Spawn((Transform::from_xyz(0.5, 0.5, 0.5), OhHiMark), ()),
            Spawn((
                Transform::from_xyz(0.5, 0.5, 0.5),
                Children::spawn_one(Transform::from_xyz(0.1, 0.1, 0.1), ()),
            )),
        )),
        Observers::spawn_one(Observer::new(system), ()),
    ),
);

This would (maybe) have better memory access patterns as we're not fully building rebuilding tuples (but this would require that effects dont produce bundles that are added alongside the main bundle ... in which case we go right back to Category B performance). And it has a clearer separation between "bundles" and "effects". The biggest downside is that () now shows up everywhere (or requires the addition of variants for "has effects" vs "doesn't have effects").

Conclusion

I'm obviously biased toward Category B or C. It seems like the best tradeoff between performance and ergonomics. Within Category B, I'm still a bit undecided on the ideal variant. I've ruled out B2 as its a worst of all worlds situation. B3 feels like a necessary evil for custom relations, but also feels nonviable as the default. Here are the remainders again (this time formatted by rustfmt):

I think the children/children! approach is objectively better than individual child/child! macros, so I have excluded C2 and C4. I have also omitted C1 as I think it is too easy to mistake ChildOf as a component on the parent and not the child.

// B1: Hard-coded shorthand functions over RelationshipSources::spawn calls
world.spawn((
    Foo,
    Children::spawn((
        Spawn((Bar, OhHiMark)),
        Spawn((Bar, Children::spawn_one(Baz))),
    )),
    Observers::spawn_one(Observer::new(system)),
));

// B4: Hard-coded wrappers over related!
world.spawn((
    Foo,
    children![(Bar, OhHiMark), (Bar, children![Baz])],
    observers![Observer::new(system)],
));

// B5: General purpose entities! macro
world.spawn((
    Foo,
    Children::spawn(entities!(
        (Bar, OhHiMark),
        (Bar, Children::spawn(entities!(Baz))),
    )),
    Observers::spawn(entities!(Observer::new(system))),
));

// C3: related! macro
world.spawn((
    Foo,
    related!(ChildOf, Bar, OhHiMark),
    related!(ChildOf, Bar, related!(ChildOf, Baz),),
    related!(ObserverOf, Observer::new(system)),
));

// C5: related function
world.spawn((
    Foo,
    related(ChildOf, (Bar, OhHiMark)),
    related(ChildOf, (Bar, related(ChildOf, Baz))),
    related(ObserverOf, Observer::new(system)),
));

Pretty hard to deny how nice B4 is to work with and read. Maximally ergonomic, it fits the "just another component in the bundle" mental model nicely, no archetype moves necessary, and it trivially enables pre-allocating space in the collection. The manual per-relation macros reduce the generic-ness of the system, and fully erasing the Relation (ChildOf) and RelationSource (Children) symbols makes me sad. But I'm leaning toward it being worth it, given how common these operations are. Fundamentally the B options all build on each other, so we could support them all. I really would like a Children::spawn!() macro as that feels like the ideal balance, but alas Rust does not support this.

C5 also feels really nice to me: no macro weirdness, not too confusing, and consistent across relationship types. Sadly it also comes with the downside of being less ergonomic / lots of repeated symbols for each child.

For one-off / custom relations, C5 feels ideal. For common / high frequency relations, B4 feels ideal. We could consider supporting both, but I think that would benefit from solving the "coordination problem" (allow related(ChildOf) and children! to both contribute their counts to a single preallocated Children component). This would also solve the current problem of consecutive children! stepping on each other (not good!).

Curious what you all think!

[alice-i-cecile]

First impressions, subject to change! Overall very excited to have anything resembling relations and a way to represent entity groupings in the engine though. I'll split my thoughts into a few messages though: one per category, to keep threading sensible.

Category i-cant-believe-its-not-bsn

I prototyped something in this space, built entirely out of bundles. I liked it for simple applications a lot, but the abuse of the type system had limitations (mulitple children of the same type clashed) and the performance characteristics are not good (so many archetype moves).

It was also a bit magic, as the added component didn't hang around!

[alice-i-cecile]

Category A

Adding support to Bundles to queue arbitrary commands on insertion

I don't like this :( This feels dangerous, and overlaps in confusing ways with hooks and observers.

A1 is my favorite syntax here: I don't like the magic of the others. It should be immediately clear how to implement your own relations.

[cart]

I don't like this :(

Agreed. Category A is non-viable imo.

[alice-i-cecile]

Category B

I much prefer the clear separation between concepts in this approach. I think this will be easier to extend, refine and teach.

You could add the as_effect() method to Bundle, which I think would look nicer and be more discoverable. More code gen than a function / newtype though 🤔

[cart]

I agree. B feels the best to me for the general purpose API. The ergonomics of B1 are pretty painful though. I think most people would prefer special cased macros for things like children, even if it means erasing concepts.

Formats like BSN would just generate the B1 form though.

[alice-i-cecile]

I prefer clear verbosity and would probably write B1 / D in my own projects! No opposition to well-documented and consistent macros / helpers though: I know that my preferences are in the minority here.

[MiniaczQ]

B seems like the best choice to me, I like the verbosity and how it expands on the idea of Bundles.
There are few odd points though.

world.spawn((
    // Root entity spread across multiple tuple entries.
    Foo1,
    Foo2,
    Children::spawn((
        Spawn((Bar, OhHiMark)),
        Spawn((Bar, Children::spawn_one(Baz))),
    )),
    Observers::spawn_one(Observer::new(system)),
    Foo3, // why not here too?
));

it may make more sense to always start with a Bundle and then have only Effects, even if it costs us an extra trait.

The other issue is the Effect/EntityCommand separation, do we actually need a new trait for this?

[alice-i-cecile]

Category C

I find this quite confusing to read. We're mixing our perspective throughout: the root level components are part of the parent, but the ChildOf is from the perspective of the child. I prefer B!

[cart]

Yeah C1 / C2 / C4 are all unworkable imo (see my conclusions at the very end). I think C5 is a reasonable tradeoff though, as related() creates a better conceptual separation. I still prefer B for common scenarios though.

[jobstijl]

I think C2 would be workable if build on top of C5, child(a) = related(ChildOf, a) seems conceptual quit clear and explainable to me.

[alice-i-cecile]

Category D

Very useful for weird procedurally generated stuff. I agree that this flavor of API is essential for flexibility, but I would also like to do better.

With a push towards the singular closure-free forms I think this could be nice TBH. Nested scenarios are hard, but I think that a cursor-style builder API feels pretty good as a closure-alternative.

You would need to preprocess this to avoid excessive archetype moves.

    world.spawn(Foo)
        // The cursor is on the root entity by default
        .related::<Child>(Bar, OhHiMark),
        .related::<Child>(Bar)
        // Move the cursor to the last added entity
        .previous()
        // Now we're nested
        .related::<ChildOf>(Baz)
       // Back to the root
        .root()
        .related::<Observer>(Observer::new(system)),
    ));

[cart]

This is reasonable (if a bit more verbose). Sadly it requires building an internal dynamic API to make it workable. Which is possible but has its own performance considerations (internal scratch space allocations).

I think it shouldn't be kicked off via normal spawn() flows, but instead should be something like world.build_entity().

[alice-i-cecile]

The cursor style API has another niche benefit: you can call other methods like .id() on non-root elements of the assemblage.

[alice-i-cecile]

I'm down to try and get a cursor-based assemblage-builder approach working at some point :) I think it's quite nice for hand-authored hierarchies, but I agree with your complaints about slowing down the hot path.

[alice-i-cecile]

A way of easily referencing parent/sibling entities when constructing children

I think that this is likely to be very hard with any of the other approaches. A stateful / incremental builder that produces an Effect seems like the right choice for building elaborately interrelated hierarchies like you often see in widgets.

[alice-i-cecile]

Category E

I don't like the mysterious () everywhere! I think this will worsen the experience for beginners and simple code substantially.

[cart]

Agreed

[iiYese]

• Builders are the most versatile & easy to extend with DSLs & shorthand functions.
• You can have a special generic bundle Pair(First, Second) that sets the relation to get around 2 item tuples already being bundles.

[iiYese]

Might require changes to Bundle but this assumes components as entities. When an Entity is passed as the second item that would be the target of the relation. Component values can be passed as either half.

#[derive(Component)]
struct Apples;

#[derive(Component)]
struct Eats { amount: usize }

#[derive(Component)]
struct GivesApples;

let apple_eater = world.spawn(Pair(Eats { amount: 3 }, Apples)).id();
world.spawn(Pair(GivesApples, apple_eater));

[iiYese]

but generating the tuples directly has also been very reasonable in my experience

My experience especially developing aery has been the exact opposite. It used to allow holding edge data which was removed because maintaining the type hackery that dynamically created the tuples based on join operations was an absolute nightmare. Tuples are the biggest hindrance to bevy API progress.

[iiYese]

How would you use this to spawn the hierarchy from the OP

You could spawn Pair(Parent, e)s manually or have a builder API (which is my preference) & do it like in category D. Much like how aery already does builders https://docs.rs/aery/latest/aery/scope/struct.CommandScope.html.

[cart]

First: I'm not discounting the value of builder APIs. But tuples are the one way to produce very nice up front data descriptions in raw Rust.

Nobody would prefer to write:

world.spawn(Bundle(A, Bundle(B, Bundle(C, Bundle(D, ())))));

Of course that would be the "output" of a non-tuple builder. But the builder pattern also doesn't compare favorably to tuples:

// builder
world.spawn(A.with(B).with(C).with(D));
// tuples
world.spawn((A, B, C, D));

Again, not saying theres no value in builders or that we shouldn't support them. But I hope you understand why I'm focusing on tuples. We can do builders if there is demand for them, and they can use the same traits defined above.

[iiYese]

It's much easier to go from builders to tuples than it is to go the other way around. Which is why the only new tuple API I would introduce is a Pair construct or something similar to set a single relation. They're better when the thing you're trying to do is short & sweet.

[alice-i-cecile]

To expand on motivation, one of my key requirements from this work is a single composable trait that captures a "collection of objects tied together by relations". This is very useful for gameplay (and things like leafwing_manifest).

I also think that it's the primary blocker on adding more complex widgets (which require multiple entities) to bevy_ui at this stage. With a foundational trait defined, we can have clear APIs / guidelines for what fn generate_slider(params: SliderParams) -> ??? returns, and finally start fleshing out the essential widgets.

[shanecelis]

Thank you for the write up. I suppose B1 is my preferred but spawn_one() definitely feels inelegant. Can you describe or link to what the entities! macro does exactly? It looked like an "out-of-band" spawn to me.

The B's are legible and describe this set of entities and relationships to my mind:

The C's I had a hard time convincing myself they described the same set of entities and relationships. I understand that they're intended to describe the same thing as above, but to me they read like this:

Dot files are here.

[cart]

entities! would (naively) just take an arbitrary length comma-separated list of token trees, wrap them in Spawn(), and then wrap everything in () to make it a single Effect.

In practice it would be a proc macro that wraps tuples at the appropriate times to get past tuple length limits (or use builders in macro_rules macro to work around the limits in a different way).

[omaskery]

Out of curiosity, can I ask how the design space around this conversation would change if we hypothetically had a way to efficiently defer structural changes so we end up with one archetype move per entity when we "flush" those deferred changes?

I ask because I've had a conversation lately with a colleague around ideas for achieving this in Bevy, and I wonder if it would alleviate some of the design pressures you're under.

[SanderMertens]

That's command batching, which has been implemented in flecs and can indeed significantly speed up flushing queues that have multiple commands for the same entity.

[cart]

I think it might alleviate the "preallocation challenge". However I'm also pretty bullish on having an efficient static API like this one. Deferring and intelligently merging changes is more flexible, but it also has overhead that we don't need to pay in many cases. Most "upfront spawns" are fully static.

[cart]

However the cost:benefit starts to get pretty interesting if you're doing conditional inserts!

[omaskery]

Ah I see, I think I understand what you're saying. Let me see if I have I understood correctly:

• We're specifically focused on the spawn situation, and in that situation:

  • Most entities are described by a single spawn command, which results in only one archetype insert, which is already maximally efficient
  • This is only not the case with conditional insertions, or insertions otherwise not specified in the initial bundle for some reason
  • Relations are presumably one of the leading causes of "insertions not in the initial bundle for some reason", therefore:
    • All the proposed designs ensure that relationships are described in the initial bundle, meaning no archetype moves

• Whilst batching (and such) would help in the general case of consolidating structural changes it has an overhead, so:

  • The proposals above presumably mitigate most of the archetype moves during spawning without paying the overhead
  • All of the proposals are entirely compatible with batching being introduced later, which can address any remaining optimization opportunities (e.g. across multiple spawns, or with conditional inserts, etc.).

Effectively these proposals are a way of manually authoring a "batched" spawn operation that augments a bundle with any relationship components known about at spawn time.

[vultix]

I feel we should at least consider changing the definition of bundle from impl<B: Bundle> Bundle for (B1, ...) to impl<C: Component> Bundle for (C1, ...). In other words, simplifying Bundle to just a list of Components

It seems to me that now that we have required components, spawning bundles (e.g. Camera2dBundle) is becoming mostly a thing of the past. On the other hand, spawning children and other relations is so common that we should prioritize ergonomics around that.

For the rare cases where you have more than 15 components, or want to extend a struct that derives Bundle with more components, we could introduce a bundles!() macro that combines multiple bundles, or a .chain() extension method on Bundle.

Doing this removes the ambiguity with bundles of bundles and lists of child bundles, opening us up to options like this:

world.spawn((
    Foo,
    Children::spawn(((Bar, OhHiMark), (Bar, Children::spawn(Baz)))),
    Observers::spawn(Observer::new(system)),
));

I love that this doesn't require any macros, and I feel it's still very simple conceptually. A Bundle is a list of components, you can combine bundles using bundles!, and you spawn relations using tuples of bundles.

[cart]

I feel we should at least consider changing the definition of bundle from impl<B: Bundle> Bundle for (B1, ...) to impl<C: Component> Bundle for (C1, ...). In other words, simplifying Bundle to just a list of Components

This is actually non-trivial to implement, as we get the "nested tuples of components" behavior via implementing Bundle for tuples of bundles. If we remove that, we lose the ability to support more than 15 components in a bundle..

Doing this removes the ambiguity with bundles of bundles and lists of child bundles, opening us up to options like this:

Lets consider this example:

(((Bar, OhHiMark), (Bar, Children::spawn(Baz))))

In the proposed impl Children::spawn is "more than just a Component", it is an Effect that produces the Children component and an AfterEffect. Therefore the tuple is not a tuple of Components, it is a tuple of Effects (and that propagates all the way up the tuple tree). This results in the same ambiguity problem.

Pretty sure variadics would solve this problem by nature of allowing us to remove nesting from the equation. We could have a Bundle trait and a BundleList trait.

[cart]

Yes @iiYese ... builders would also solve this problem 😄

[vultix]

@cart What about something like this? It's basically a combination of you Category B and my proposal. In your Category B proposal, Components and Effects both implement Effect. We could make Bundle a list of Effects instead of a list of components. I took the suggestion from @ecoskey and called this trait Spawn.

/// An `Effect` or a `Component`, something that can be "spawned" on a given entity
trait Spawn {}

/// A bundle is a list of things that can be spawned on an entity
trait Bundle {}
impl<S: Spawn> Bundle for (S1, S2, ..., Sn) {}

/// A list of bundles, each bundle representing a separate entity. Used for relations such as `Children::spawn`
trait BundleList {}
impl<B: Bundle> BundleList for (B1, B2, ..., Bn) {}


/// `Children::spawn` returns a type that implements `Spawn` that isn't a component, but an Effect
impl Children {
    fn spawn(entities: impl BundleList) -> impl Spawn {}
}

[vultix]

I even believe we could make it so that the derive macro for Bundle also implements Spawn, removing one of the primary drawbacks I had above. The only remaining drawback I can think of is spawning entities with more than 15 components still requiring something like a bundle!() macro or a .chain() method

[vultix]

In this example:

Children::spawn(((Bar, OhHiMark), (Bar, Children::spawn(Baz))))

We'd be spawning a BundleList containing two Bundles, each bundle containing two types that implement Spawn.

[ecoskey]

copied from discord thread:

Could B4 expand to C5/C1? I really like that the c variants don't need an extra Spawn wrapper-- having a "magic" newtype that's only required in certain positions for the trait to resolve feels like a massive footgun to me, even if we have a dsl macro on top. I'm imagining B4 and C5 as separate syntax styles that both produce C1

Also naming nitpick, Effect as the main trait here feels a bit ambiguous to me? I like the sound of Spawn as a trait name, if not a wrapper.

[cart]

Could B4 expand to C5/C1?

It definitely could. Biggest reason not to is that currently C5/C1 has no way of counting the number of relationships and pre allocating space in Children, and no way of pre-inserting Children to avoid archetype moves. If we can solve that problem, then they would be equivalent.

[cart]

Also naming nitpick, Effect as the main trait here feels a bit ambiguous to me? I like the sound of Spawn as a trait name, if not a wrapper.

Yup Spawn is reasonable!

[ecoskey]

Could B4 expand to C5/C1?

It definitely could. Biggest reason not to is that currently C5/C1 has no way of counting the number of relationships and pre allocating space in Children,

How's that problem avoided in the original B representation? Would there be a panic on duplicate Children::spawn()?

[cart]

I touched on this in the conclusion section:

For one-off / custom relations, C5 feels ideal. For common / high frequency relations, B4 feels ideal. We could consider supporting both, but I think that would benefit from solving the "coordination problem" (allow related(ChildOf) and children! to both contribute their counts to a single preallocated Children component). This would also solve the current problem of consecutive children! stepping on each other (not good!).

The second instance would step on the first instance.

[cart]

My opinion is that ideally we sort out a way to merge all these cases together.

[wilberg]

I really like the feel of B4.

Just like the bsn! macro will convert BSN syntax to one of these spawners, I assume some will want to utilize this API for their own representations if necessary.

Not entirely sure how beneficial this would be, but I think that in addition to the children! and observers! macros, we should allow the use of more "painful" syntax, purely to expose the underlying "pure" rust code (Edit: By exposing, I mean properly documenting their use as an alternative to the macro).

I'm also wondering how this would be handled:

world.spawn(
    Foo,
    children![Bar],
    children![Baz]
);

Should a merge happen, adding them both? Should the compiler yell at us? What if each children! contains the same component? Might not be a problem at all, but thought I'd share my immediate thoughts.

[cart]

I'm also wondering how this would be handled:

See this conversation.

#16920 (reply in thread)

[cart]

I also agree that the raw rust syntax should be supported and documented.

[viridia]

If I understand correctly, Relationships are a way to define (Entity => Entity) relations. However, for observers and reactions, the use of an entity is really a workaround to get around the limitation of not being able to have multiple components of the same type. Fundamentally, observers and reactions are little more than a component containing a closure, of which there may be several of the same type - we are forced to spawn a separate entity for each instance to keep them from stomping over each other.

We could have modeled these concepts as a single component containing a Vec, except that it would require spawning to be a read-modify-write action (pushing new instances onto the vector). Removing or deleting instances also becomes non-trivial in this model. Spawning a new entity per instance was seen as the simpler approach...for now.

My question is, do we anticipate a future relations framework that would allow observers/reactions to be attached to an entity, without the need to spawn a separate satellite entity to hang them off of? I'm not really sure what's the plan for relations generally.

In my own work, I decided to move away from the word "effect". I think your use of the word "effect" here means the effect upon the target entity during setup. By contrast, I defined the Effect trait as a being some active agent whose job it is to modify the entity's components dynamically in response to changes in the world, and "children" did not fit this definition. Instead, I renamed the trait used to initially set up the entity Attachment, thinking that adding effects and children both fit into the category of "attaching things" to the entity. Other terms, like "Annex" could also serve here.

There was a question earlier about siblings referencing each other by entity id. There are also cases where an entity needs to refer to itself: that is, an entity contains a component which contains a closure, such that the closure has captured the entity id (because otherwise there's no way for the closure to deduce which entity it is attached to). However, to capture the id you can't insert the closure until the entity exists. In all these cases, the way I typically structure this is to generate the entity ids first, using spawn_empty; then I spawn the hierarchy, inserting in those entity ids where needed. This means that in addition to a "create child" primitive, we also need "create child with this predefined id".

[viridia]

A few more thoughts on this: I think that we should prepare for a possible future migration in which observers and reactions no longer require a satellite entity to hold them, but are instead stored directly on the relation. To ease the pain of this migration, I would prefer that the syntax for spawning not mandate that observers and reactions be entities. So for example, A2/B2/C2 would all permit the definition of observer to change in this way.

[alice-i-cecile]

Long term, I think that the "use relations to bypass the one-component-of-a-type" rule is viable. This was called out in our very first Relations RFC :) I'd prefer to keep them as simple entities and relations to improve consistency for learning and tooling.

[marcelchampagne]

I've built my UI framework on top of @alice-i-cecile's i-cant-believe-its-not-bsn and here's a brief summary of how I currently handle spawning ergonomics.

Note that I haven't read enough to comment about the approaches beyond ergonomics, so apologies in advance if this isn't relevant.

My framework uses a builder pattern and ends up with the following syntax (note that I don't actually have the observe functionality implemented, but in terms of ergonomics that's how I would implement it):

Foo
.spawn_child((Bar, OhHiMark))
.spawn_child(Bar.spawn_child(Baz))
.observe(Observer::new(system));

I also have the equivalent spawn_children that takes any IntoIterator<Item = Bundle>, which is nice for spawning multiple children of the same type. However, for a small number of children, I generally prefer spawn_child as it slightly reduces the boilerplate and provides clearer separation between different children, especially when the structure of the children is different.

Under the hood, my builder pattern just boils down to tuples, i.e.:

pub trait HierarchyBuilder {
    fn spawn_child<B: Bundle>(self, bundle: B) -> (Self, WithChild<B>)
    where
        Self: Sized,
    {
        (self, WithChild(bundle))
    }
}
impl<T> HierarchyBuilder for T where T: Bundle {}

With internal access to Bevy, this could be moved up one level and become:

world
    .spawn(Foo)
    .spawn_child((Bar, OhHiMark))
    .spawn_child(Bar.spawn_child(Baz))
    .observe(Observer::new(system));

I like this for a couple of reasons:

1. One less level of nesting compared to B1/B4/B5/C3/C5
2. Reads closer to English, which makes it easier for me to read when the UI templates I'm defining are very large. With tuples, my eyes sometimes were glazing over as it was harder to tell which tuple was a child of which entity in large nested hierarchies.
3. Slightly better autocomplete. I found raw tuples slightly more annoying to work with. Typing .s in my editor and getting spawn_child is nice.
4. It's more in-line with the existing APIs for spawning children. This has the same main advantage of 4, but without the need for closures

That said, moving it up one level would mean having 2 APIs since Bar.spawn_child(Baz) would need to use the HierarchyBuilder approach, which doesn't feel ideal.

As such, I would probably actually prefer:

world
    .spawn(
        Foo
        .spawn_child((Bar, OhHiMark))
        .spawn_child(Bar.spawn_child(Baz))
        .observe(Observer::new(system))
    );

This avoids fragmenting the number of APIs too much and all the advantages of points 2-4 still apply.

Anyways, my main comment would be that I would greatly appreciate if the raw API would keep in mind being able to support something like this on top of it. And, with that in mind, for the base API, I'd probably lean towards B1. I do think there is a lot of value in giving users a builder pattern similar to the one described above that encapsulates the verbosity of B1. That would get rid of the need for macros and allow users to easily 'Jump to Definition' in their editor and immediately see what spawn_child or spawn_children is doing, but greatly reduce boilerplate.

[marcelchampagne]

Note -- I made some major edits to my comment after realizing my initial comment was conflating two different APIs.

[alice-i-cecile]

The first option feels closest to D, and I think we have consensus that this needs to be supported in some way. I like it too! We'll need to be smart with batching work.

Fascinating: your proposal (category F) would best be implemented via methods / blanket impl of a new trait on Bundle. @cart this is a new idea! I think cargo fmt is going to play badly with it, but I kind of like the discoverability 🤔

[wilberg]

I read through some of the comments, and feel like there have been some really nice ideas. After some thought, I feel like a builder API which yields something which can be passed to world.spawn, would be most beneficial.

The only other approaches with good enough DevX seem to use macros, which begs the question of why we wouldn't just use BSN (obviously there are differences, I'm sure, but this was the impression I got).

Keeping the to-be-spawned hierarchy separate from the world, makes it easier for third party developers to interact (and create DSLs as another commenter mentioned).

As for the benefits with a builder API, it would give developers a lot of flexibility when creating UIs without BSN, before spawning.

Take a look at the following example:

let mut button_wrapper = (
    Name("Main Menu Button"),
    Button
); 

let start_button = button_wrapper
    .add_child(Text::new("Start")); 

let exit_button = button_wrapper
    .add_child(Text::new("Exit")); 

world.spawn(start_button);
world.spawn(exit_button);

We could create two different buttons based on the same wrapper/core bundle. I feel this could be difficult without using a builder API.

Some of these thoughts have probably already been discussed here, if so - apologies for the duplication.

[viridia]

This is a really good point: if we assume the existence of BSN, then we don't need the perfect ergonomics - we only need something that works well enough to use as a fallback mechanism in cases where BSN is not appropriate.

[ItsDoot]

Relations implementation

I understand this discussion thread is mostly concerning the ergonomics of spawning APIs with regards to generic relationships, but I would also like to spend some time discussing the actual implementation of a basic relationships system, given it will have some influence on how the spawning APIs are implemented.

evergreen_relations

I've been working on an evolution of @bushrat011899's hook-based relationships PR (which actually began a few days prior to @cart mentioning he's working on the same thing), and I aim to avoid some of the flaws in the PR's original approach:

• Accidentally using the wrong component type for a certain kind of relationship (i.e. using the 1:1 component for a 1:N relationship)
• Duplication of code per kind of relationship (mostly regarding hook implementations)

It's now in a good enough state for publishing and can be found here: https://github.com/EvergreenNest/evergreen_relations

It is implemented as a standalone crate which depends on a post-immutable-components bevy version. It supports 1:1, 1:N, and N:M relationship kinds, as well as directed and undirected relationships. More on that later.

Key concepts

I'll explain the key conceptual parts of this crate, but please do look through the repository for more in depth learning once you've read through these bits (or do so while reading through).

Related: How the entity references are stored in the ECS

All of the actual data (the Entity references from one entity to another) is stored in a single (generic) component:

#[derive(Component)]
#[component(immutable, on_insert = associate::<N>, on_replace = disassociate::<N>, on_remove = disassociate::<N>)]
pub struct Related<N: Relatable> {
    container: N::Container,
}

This is an immutable component, with hooks that handle adding/removing components and their data from the entities on either side of a relationship.

The N type parameter specifies the side of the relationship that's being stored for, such as the children of an entity or the parent of one. The N::Container field is where the references to other entities are stored; this can be a single Entity, or multiple entities stored in a Vec<Entity>, SmallVec<[Entity; N]>, or EntityHashSet; whatever is specified by that side of the relationship. Only those implementations are currently provided, but the idea is to support pluggable storage.

Relatable: The sides of a relationship

All relationships have two sides, so that any entity can be related to any other entity (regardless of how many entities one can be related to).
The Relatable trait is implemented to specify one side of a relationship. It defines how many entities it can point to, and also links to the opposite side of the relationship, which is used by the hook implementations of Related.

pub trait Relatable: 'static {
    /// The relation type that this node is part of.
    type Relation: Relation;
    /// The opposite side of this node's [`Relation`].
    type Opposite: Relatable<Relation = Self::Relation, Opposite = Self>;
    /// The container type that holds the related entities.
    type Container: EntityContainer;
}

Relation: The all-encompassing trait

We need this trait for when we don't care about a particular side of the relationship, like when we're pushing out RelationEvents. Since
relationships have two sides, we name them Source and Target. Neither side has any inherent special handling, but I wanted better naming than "Side A" and "Side B". There's not much else to this trait, besides bounding the sides to make sure they point to each other.

pub trait Relation {
    type Source: Relatable<Relation = Self, Opposite = Self::Target>;
    type Target: Relatable<Relation = Self, Opposite = Self::Source>;
}

Directed vs Undirected

You might have noticed that directedness is not specified explicitly by either of the Relatable or Relation trait. I used to have a Symmetry associated type on Relation to specify this, but realized that it can be handled semantically instead by specifying that both sides of a relationship refer to the same type.

For example, let's say we have a Friendship relationship, and one of the sides is a FriendOf Relatable that stores some Entitys. If we have one entity (entity A) befriend another (entity B), then we give entity A the Related<FriendOf> component that points to entity B. When the component is inserted on entity A, the hooks will insert the Related<FriendOf::Opposite> component on entity B, and point back to entity A. Thus, if we define the other side of the relationship to also be FriendOf (i.e. reuse the same type), then we now have FriendOf::Opposite == FriendOf. Therefore, entity B will also receive a Related<FriendOf> component that points back to entity A, effectively becoming an undirected relationship because we don't know or care about which specific side we're on (they're the same type on either side).

Example

Here's what our current Parent/Child components would look like with evergreen_relations. I've written derive macros for both Relation and Relatable, but am showing the manual implementations instead for clarity. You can find this example in the repository under tests/family.

pub struct Family;

impl Relation for Family {
    type Source = ChildOf;
    type Target = ParentOf;
}

pub struct ChildOf;

impl Relatable for ChildOf {
    type Relation = Family;
    type Opposite = ParentOf;
    type Container = Entity;
}

pub struct ParentOf;

impl Relatable for ParentOf {
    type Relation = Family;
    type Opposite = ChildOf;
    type Container = SmallVec<[Entity; 8]>;
}

// Use it the same as you would bevy's current `Parent` component
pub type Parent = Related<ChildOf>;

// Use it the same as you would bevy's current `Children` component
pub type Children = Related<ParentOf>;

// Same as bevy's current `HierarchyEvent` event type
pub type HierarchyEvent = RelationEvent<Family>;

[ItsDoot]

Could Related, Relatable, and Relation have a better set of names? Yea probably. I initially went with RelationNode instead of Relatable, but thought that might get conflated with UI Nodes.

[Diddykonga]

Relation -> RelationKind
Relatable -> RelationEdge
Related<T> -> Relation<T>
Maybe