Retain Rendering World (adopted)

[Trashtalk217]

• Adopted from Retain Rendering World #14449
• Still fixes Render world blocking certain ecs developments #12144.

Migration Guide

The retained render world is a complex change: migrating might take one of a few different forms depending on the patterns you're using.

For every example, we specify in which world the code is run. Most of the changes affect render world code, so for the average Bevy user who's using Bevy's high-level rendering APIs, these changes are unlikely to affect your code.

Spawning entities in the render world

Previously, if you spawned an entity with world.spawn(...), commands.spawn(...) or some other method in the rendering world, it would be despawned at the end of each frame. In 0.15, this is no longer the case and so your old code could leak entities. This can be mitigated by either re-architecting your code to no longer continuously spawn entities (like you're used to in the main world), or by adding the bevy_render::world_sync::TemporaryRenderEntity component to the entity you're spawning. Entities tagged with TemporaryRenderEntity will be removed at the end of each frame (like before).

Extract components with ExtractComponentPlugin

// main world
app.add_plugins(ExtractComponentPlugin::<ComponentToExtract>::default());

ExtractComponentPlugin has been changed to only work with synced entities. Entities are automatically synced if ComponentToExtract is added to them. However, entities are not "unsynced" if any given ComponentToExtract is removed, because an entity may have multiple components to extract. This would cause the other components to no longer get extracted because the entity is not synced.

So be careful when only removing extracted components from entities in the render world, because it might leave an entity behind in the render world. The solution here is to avoid only removing extracted components and instead despawn the entire entity.

Manual extraction using Extract<Query<(Entity, ...)>>

// in render world, inspired by bevy_pbr/src/cluster/mod.rs
pub fn extract_clusters(
    mut commands: Commands,
    views: Extract<Query<(Entity, &Clusters, &Camera)>>,
) {
    for (entity, clusters, camera) in &views {
        // some code
        commands.get_or_spawn(entity).insert(...);
    }
}

One of the primary consequences of the retained rendering world is that there's no longer a one-to-one mapping from entity IDs in the main world to entity IDs in the render world. Unlike in Bevy 0.14, Entity 42 in the main world doesn't necessarily map to entity 42 in the render world.

Previous code which called get_or_spawn(main_world_entity) in the render world (Extract<Query<(Entity, ...)>> returns main world entities). Instead, you should use &RenderEntity and render_entity.id() to get the correct entity in the render world. Note that this entity does need to be synced first in order to have a RenderEntity.

When performing manual abstraction, this won't happen automatically (like with ExtractComponentPlugin) so add a SyncToRenderWorld marker component to the entities you want to extract.

This results in the following code:

// in render world, inspired by bevy_pbr/src/cluster/mod.rs
pub fn extract_clusters(
    mut commands: Commands,
    views: Extract<Query<(&RenderEntity, &Clusters, &Camera)>>,
) {
    for (render_entity, clusters, camera) in &views {
        // some code
        commands.get_or_spawn(render_entity.id()).insert(...);
    }
}

// in main world, when spawning
world.spawn(Clusters::default(), Camera::default(), SyncToRenderWorld)

Looking up Entity ids in the render world

As previously stated, there's now no correspondence between main world and render world Entity identifiers.

Querying for Entity in the render world will return the Entity id in the render world: query for MainEntity (and use its id() method) to get the corresponding entity in the main world.

This is also a good way to tell the difference between synced and unsynced entities in the render world, because unsynced entities won't have a MainEntity component.

[Trashtalk217]

Last thank you to @re0312, I couldn't have done it without you.

[alice-i-cecile]

I'll tackle the release notes for this. I think that getting something in place for this ASAP is important to help communicate these changes to the rendering devs and ease initial migration during the release candidate.