Refactor the Yoleck type handlers into components

[idanarye]

Yoleck's fundamental design concept is that rather than editing the components, we should edit new data types designed for easy editing and for serialization. The current implementation is that each such YoleckTypeHandler contains:

• All the data required to represent the entity.
• All the systems for editing that data.
• All the systems for building the Bevy entity with the required components from that data.

There are several problems with this design:

• Sharing behavior is hard. To share the most common behavior - dragging entities - I had to write vpeol_position_edit_adapter, which has both weird implementation and weird API.
• The semantics I had in mind for Multiple entity selection and editing #5, based on this design, are very weird and would require weird projection registration.
• Implementation-wise it made sense to store the data as Box<dyn Send + Sync + Any>, which is neither efficient nor easy to work with.

I want to migrate to a new design, a more ECSy one. The core principle of editing "proxy" data instead of the actual components will remain, but:

• It'll support multiple data structures for the same entity. These data structures will also be Bevy components, and the edit and populate system will access them as such.
• For convenience, we'll still have definitions of entities - but now they'll just be a collection of these components.
• Edit systems and populate systems will not be tied to a specific entity type or even to a specific data component type (though they'll usually operate on one). These systems will use queries to get the proxy components they need.

[idanarye]

Edit systems

Edit systems are currently defined something like this:

fn edit_foo(mut edit: YoleckEdit<Foo>, mut commands: Commands) {
    edit.edit(|ctx, data, ui| {
        // Edit with egui:
        ui.add(egui::Slider::new(&mut data.some_field, 0.0..=1.0).prefix("..."));

        // Edit with knobs:
        let mut knob = ctx.knob(&mut commands, "knob-name");
        knob.cmd.insert(...)
        if let Some(knob_drag) = knob.get_passed_data::<Vec3>() {
            // update data base on knob_drag
        }
    });
}

I want them to look more like this:

fn edit_foo(mut ui: YoleckUi, mut query: Query<&mut Foo, With<YoleckEdit>>) {
    let Ok(foo) = query.get_single_mut() else { return };

    // Edit with egui:
    ui.add(egui::Slider::new(&mut foo.some_field, 0.0..=1.0).prefix("..."));

    // I'll talk about knob semantics later
}

The YoleckEdit component will only be attached to the value being edited, so get_single_mut will give us the edited Foo iff an entity that has a Foo is currently being edited.

This style will allow editing multiple entities:

fn edit_foos(mut ui: YoleckUi, mut query: Query<&mut Foo, With<YoleckEdit>>) {
    if query.is_empty() {
        return;
    }

    // Gonna hide the details inside this type:
    let mut aggregator = Aggregator::new();

    for foo in query.iter() {
        aggregator.add(foo.some_field)
    }

    // Edit with egui:
    aggregator.edit_with(ui);

    for mut foo in query.iter() {
        aggregator.update(&mut foo.some_field);
    }
}

Knobs

I see two options for knobs:

1. As another component on the edited entity.
2. As a resource.

The first option sounds very natural, and I'm writing it because someone may convince me to use it, but for now I prefer the second option for the following reasons:

• When editing multiple entities, it makes more sense to use the same knobs for all of them. For example, a gizmo knob should affect the transform of all edited entities - there is no point in multi-edit if we give each entity its own gizmo.
• If, for whatever reason, an edit system needs to give each entity its own knob - it can always add the entity ID to the knob key.
• One of my instincts in suggesting the first option is to be able to automatically get rid of knobs when an entity is deselected - but it's easier to just remove all the knobs and rebuild them from scratch.
  • Not sure we'll even need that, if we use a remove-unless-touched mechanism.
• If the access to the knobs is done via a SystemParam, I can also put a Commands in there and avoid having to always pass it.

Overall, a simple edit system that includes a knob will look something like that:

fn edit_foo(
    mut ui: YoleckUi,
    mut query: Query<&mut Foo, With<YoleckEdit>>,
    mut knobs: YoleckKnobs,
) {
    let Ok(foo) = query.get_single_mut() else { return };

    // Edit with egui:
    ui.add(egui::Slider::new(&mut foo.some_field, 0.0..=1.0).prefix("..."));

    // Edit with knobs:
    let mut knob = knobs.knob("knob-name");
    knob.cmd.insert(...)
    if let Some(knob_drag) = knob.get_passed_data::<Vec3>() {
        // update data base on knob_drag
    }
}

[idanarye]

Actually... making it a regular query could be a problem for multiedit. If the user marks some items that have a compoennts and others that don't have it, it'll only iterate over the ones who do have it. Even worse - if only one item has the component, edit systems designed for single edit will show just it!

I'm thinking of something like this:

fn edit_foo(mut ui: YoleckUi, mut query: YoleckEdit<&mut Foo>) {
    let Ok(foo) = query.get_single_mut() else { return };

    // Edit with egui:
    ui.add(egui::Slider::new(&mut foo.some_field, 0.0..=1.0).prefix("..."));

    // I'll talk about knob semantics later
}

YoleckEdit will have some of the methods of Bevy's Query, but get_single_mut will check that only entities of the correct type are chosen.

To get passed data, one would use an explicit PassedData component.

[idanarye]

Populate Systems

The most straightforward way to do it in the new style is:

fn populate_foo(
    query: Query<(Entity, &Foo), With<YoleckPopulate>>,
    mut commands: Commands,
) {
    for (entity, foo) in query.iter() {
        let mut cmd = commands.entity(entity);
        // insert components to cmd based on foo
    }
}

I really wish I could do something like this though:

fn populate_foo(query: Query<(YoleckPopulate, &Foo)>) {
    for (populate, foo) in query.iter() {
        let mut cmd = populate.cmd();
        // ...
    }
}

But I may have to settle for:

fn populate_foo(
    query: Query<(YoleckPopulate, &Foo)>,
    mut commands: Commands,
) {
    for (populate, foo) in query.iter() {
        let mut cmd = populate.cmd(&mut commands);
        // ...
    }
}

[idanarye]

Populate Systems

The most straightforward way to do it in the new style is:

fn populate_foo(
    query: Query<(Entity, &Foo), With<YoleckPopulate>>,
    mut commands: Commands,
) {
    for (entity, foo) in query.iter() {
        let mut cmd = commands.entity(entity);
        // insert components to cmd based on foo
    }
}

I really wish I could do something like this though:

fn populate_foo(query: Query<(YoleckPopulate, &Foo)>) {
    for (populate, foo) in query.iter() {
        let mut cmd = populate.cmd();
        // ...
    }
}

But I may have to settle for:

fn populate_foo(
    query: Query<(YoleckPopulate, &Foo)>,
    mut commands: Commands,
) {
    for (populate, foo) in query.iter() {
        let mut cmd = populate.cmd(&mut commands);
        // ...
    }
}

Another option is to still use the lambda syntax:

fn populate_foo(mut populate: YoleckPopulate<&Foo>) {
    populate.populate(|_ctx, mut cmd, foo| {
        // ...
    });
}

This creates a difference between the edit systems and the populate systems though, so I'm not 100% sure I want it.

[idanarye]

I think I'll go with the closure, because:

1. A user will probably need more populate systems than edit systems, so they need the terseness more.
2. It allows me to store the entities that need to be populated in a resource, instead of adding and removing components all the time.
3. Unlike edit systems which can have different usecases (single edit, multi edit which may or may not need to aggregate data and to go over the list twice), populate systems are always straightforward - go over all the entities and apply the commands to them based on the data from the Yoleck components.
4. Edit systems may need special resources (like knobs), so a mix-and-match approach works better. Populate systems don't.
5. Populate systems will differ from edit systems anyways, because the user will have to register them via a schedule.

[idanarye]

The 2D example has this:

fn populate_fruit(mut populate: YoleckPopulate<Fruit>, assets: Res<GameAssets>) {
    populate.populate(|_ctx, data, mut cmd| {
        cmd.despawn_descendants();
        cmd.insert((
            // components of the parent
        ));
        cmd.with_children(|commands| {
            // add the actual sprite as a child entity
        });
    });
}

The despawn_descendants is a problem here, because there can now be multiple populate systems and if the despawn happens after another populate system that also adds children, it'll delete these children.

One solution is to split it to two systems:

fn despawn_fruit_children(mut populate: YoleckPopulate<Fruit>) {
    populate.populate(|_ctx, mut cmd, data| {
        cmd.despawn_descendants();
    });
}

fn populate_fruit(mut populate: YoleckPopulate<Fruit>, assets: Res<GameAssets>) {
    populate.populate(|_ctx, mut cmd, data| {
        cmd.insert((
            // components of the parent
        ));
        cmd.with_children(|commands| {
            // add the actual sprite as a child entity
        });
    });
}

And register it with:

app.yoleck_populate_schedule().add_system(despawn_fruit_children.in_base_set(YoleckPopulateSet::Despawn));
app.yoleck_populate_schedule().add_system(populate_fruit);

This is a bit verbose. I also think of something like this:

fn populate_fruit(mut populate: YoleckPopulate<Fruit>, assets: Res<GameAssets>) {
    populate.populate(|ctx, mut cmd, data| {
        ctx.when_changed_despawn_children();
        cmd.insert((
            // components of the parent
        ));
        cmd.with_children(|commands| {
            // add the actual sprite as a child entity
        });
    });
}

This will make it so that the before the next time populate systems run on this entity, it'd despawn all the descendants.

One final solution:

fn populate_fruit(mut populate: YoleckPopulate<Fruit>, assets: Res<GameAssets>) {
    populate.populate(|ctx, mut cmd, data| {
        ctx.despawn_marked(cmd.commands());
        cmd.insert((
            // components of the parent
        ));
        cmd.with_children(|commands| {
            let mut child = commands.spawn((
                    // ...
            ));
            ctx.mark(&mut child);
            // add the actual sprite as a child entity
        });
    });
}

If we explicitly mark each created child, we can just remove only these children. This is probably the most robust solution, since one system's despawns won't affect other populate systems.

[idanarye]

Alternative marking method: cmd.insert(ctx.marker()).

[idanarye]

Wait! I know!

fn populate_fruit(mut populate: YoleckPopulate<Fruit>, marking: YoleckMarking) {
    populate.populate(|ctx, mut cmd, data| {
        marking.despawn_marked(&mut cmd);
        cmd.insert((
            // components of the parent
        ));
        cmd.with_children(|commands| {
            let mut child = commands.spawn((
                    // ...
            ));
            child.insert(marking.marker());
            // add the actual sprite as a child entity
        });
    });
}

This is important implementation-wise, because only systems that request YoleckMarking will have a marker designated for them.

[idanarye]

Note to self: when implementing, take https://bevy-cheatbook.github.io/features/parent-child.html#despawning-child-entities into consideration and remember to call remove_children.

[idanarye]

Closing because I've implemented it all.