Synchronize removed components with the render world

[kristoff3r]

Objective

Fixes #15560
Fixes (most of) #15570

Currently a lot of examples (and presumably some user code) depend on toggling certain render features by adding/removing a single component to an entity, e.g. SpotLight to toggle a light. Because of the retained render world this no longer works: Extract will add any new components, but when it is removed the entity persists unchanged in the render world.

Solution

Add SyncComponentPlugin<C: Component> that registers SyncToRenderWorld as a required component for C, and adds a component hook that will clear all components from the render world entity when C is removed. We add this plugin to ExtractComponentPlugin which fixes most instances of the problem. For custom extraction logic we can manually add SyncComponentPlugin for that component.

We also rename WorldSyncPlugin to SyncWorldPlugin so we start a naming convention like all the Extract plugins.

In this PR I also fixed a bunch of breakage related to the retained render world, stemming from old code that assumed that Entity would be the same in both worlds.

I found that using the RenderEntity wrapper instead of Entity in data structures when referring to render world entities makes intent much clearer, so I propose we make this an official pattern.

Testing

Run examples like

cargo run --features pbr_multi_layer_material_textures --example clearcoat
cargo run --example volumetric_fog

and see that they work, and that toggles work correctly. But really we should test every single example, as we might not even have caught all the breakage yet.

---

Migration Guide

The retained render world notes should be updated to explain this edge case and SyncComponentPlugin

[kristoff3r]

I'll add and update documentation if we decide this is the solution we want

[Trashtalk217]

Broadly in favour of this, but there's one big exception that would break this system. This is exceedingly rare, but it does need to be documented.

Say that we have two synced and extracted components A and B. That are located on the same entity.

| Main World                   | Render World               |
| -----------------------------|----------------------------|
| e1: (A, B, RenderEntity(e2)) | e2: (A, B, MainEntity(e1)) |

If you now remove A from e1, this will remove both A and B in the render world.

| Main World                   | Render World              |
| -----------------------------|---------------------------|
| e1: (B, RenderEntity(e2))    | e2: (MainEntity(e1))      |

This may not be what the user expects. And while this scenario may be very rare, it should be documented. You could solve this by counting the number of synced components a entity has (and storing it with SyncToRenderWorld), but that might be a step to far.

Also some documentation is still required for the sync_component plugin.

[Trashtalk217]

Last couple nits, after this it's ready to go.

[kristoff3r]

There are still a few open questions:

• Do we do the WorldSync to SyncWorld rename?
• Do we want the SyncComponentPlugin to add the required component registration for SyncToRenderWorld component? If yes we should remove all the ones that have been added in the required components migrations. If no we should re-add the ones removed here. In any case we should find some place to document it.

Also it looks like some of the examples broke when I merged main, I'll have to debug that later.

[alice-i-cecile]

Do we do the WorldSync to SyncWorld rename?

Yes.

Do we want the SyncComponentPlugin to add the required component registration for SyncToRenderWorld component? If yes we should remove all the ones that have been added in the required components migrations. If no we should re-add the ones removed here. In any case we should find some place to document it.

Yes. Document this on SyncComponentPlugin, and also on the SyncToRenderWorld component please :)

[kristoff3r]

@alice-i-cecile seems to work now, tested with a bunch of different examples. It has a tendency to break because of the required component migrations, so I hope we can get it in soon.