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.

I haven't done so here, but I propose we 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 can split these out into a separate PR if needed.

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]

This is fun and has consequences, but we're gonna figure that out.

[kristoff3r]

After thinking more I think it's what we need to do in any case. Components like SpotLight aren't extracted directly but generate derived values, e.g. ExtractedPointLight. The only reason SyncComponentPlugin works in this case is because we clear everything. Because extract has to work when there's nothing present in the render world the first time it runs, I cannot think of any cases where this would break?

[Trashtalk217]

I'm deferring on your judgement on this as I don't have much insight in rendering internals. As long as it's correctly documented (and maybe also include I reason why we have to do this, besides it being difficult, because it's strictly not impossible), this should be good.

[kristoff3r]

@IceSentry or another SME should perhaps sanity check this logic, I'm not an expert in the internals either but it makes sense to me :D

[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 :)

[IceSentry]

For now this is probably fine since we don't really take advantage of the retained render world yet, but that feels like a major footgun for when we start to do that.

[kristoff3r]

With the current extract system it's mostly a (minor) performance footgun. The extract system needs to handle extracting to an empty entity when it first gets created. Unless that's very performance heavy (which it shouldn't be during extract) or you insert/remove components very often it shouldn't be a problem.

When we use the retained world more we can probably come up with something smarter, but that will probably involve reworking extraction as well to do diffs and having a way to track derived state. If we just removed the same component it wouldn't solve the issue, as e.g. PointLight becomes ExtractedPointLight.

This at least is a much better stopgap than just saying "you're not allowed to remove render components after spawning".