Struct SyncWorldPlugin

pub struct SyncWorldPlugin;

A plugin that synchronizes entities with SyncToRenderWorld between the main world and the render world.

All entities with the SyncToRenderWorld component are kept in sync. It is automatically added as a required component by ExtractComponentPlugin and SyncComponentPlugin, so it doesn’t need to be added manually when spawning or as a required component when either of these plugins are used.

Implementation

Bevy’s renderer is architected independently from the main app. It operates in its own separate ECS World, so the renderer logic can run in parallel with the main world logic. This is called “Pipelined Rendering”, see PipelinedRenderingPlugin for more information.

SyncWorldPlugin is the first thing that runs every frame and it maintains an entity-to-entity mapping between the main world and the render world. It does so by spawning and despawning entities in the render world, to match spawned and despawned entities in the main world. The link between synced entities is maintained by the RenderEntity and MainEntity components.

The RenderEntity contains the corresponding render world entity of a main world entity, while MainEntity contains the corresponding main world entity of a render world entity. For convenience, QueryData implementations are provided for both components: adding MainEntity to a query (without a &) will return the corresponding main world Entity, and adding RenderEntity will return the corresponding render world Entity. If you have access to the component itself, the underlying entities can be accessed by calling .id().

Synchronization is necessary preparation for extraction (ExtractSchedule), which copies over component data from the main to the render world for these entities.

|--------------------------------------------------------------------|
|      |         |          Main world update                        |
| sync | extract |---------------------------------------------------|
|      |         |         Render world update                       |
|--------------------------------------------------------------------|

An example for synchronized main entities 1v1 and 18v1

|---------------------------Main World------------------------------|
|  Entity  |                    Component                           |
|-------------------------------------------------------------------|
| ID: 1v1  | PointLight | RenderEntity(ID: 3V1) | SyncToRenderWorld |
| ID: 18v1 | PointLight | RenderEntity(ID: 5V1) | SyncToRenderWorld |
|-------------------------------------------------------------------|

|----------Render World-----------|
|  Entity  |       Component      |
|---------------------------------|
| ID: 3v1  | MainEntity(ID: 1V1)  |
| ID: 5v1  | MainEntity(ID: 18V1) |
|---------------------------------|

Note that this effectively establishes a link between the main world entity and the render world entity. Not every entity needs to be synchronized, however; only entities with the SyncToRenderWorld component are synced. Adding SyncToRenderWorld to a main world component will establish such a link. Once a synchronized main entity is despawned, its corresponding render entity will be automatically despawned in the next sync.

The sync step does not copy any of component data between worlds, since its often not necessary to transfer over all the components of a main world entity. The render world probably cares about a Position component, but not a Velocity component. The extraction happens in its own step, independently from, and after synchronization.

Moreover, SyncWorldPlugin only synchronizes entities. RenderAssets like meshes and textures are handled differently.

Trait Implementations

impl Default for SyncWorldPlugin

fn default() -> SyncWorldPlugin

Returns the “default value” for a type.

impl Plugin for SyncWorldPlugin

fn build(&self, app: &mut App)

Configures the App to which this plugin is added.

fn ready(&self, _app: &App) -> bool

Has the plugin finished its setup? This can be useful for plugins that need something asynchronous to happen before they can finish their setup, like the initialization of a renderer. Once the plugin is ready, finish should be called.

fn finish(&self, _app: &mut App)

Finish adding this plugin to the App, once all plugins registered are ready. This can be useful for plugins that depends on another plugin asynchronous setup, like the renderer.

fn cleanup(&self, _app: &mut App)

Runs after all plugins are built and finished, but before the app schedule is executed. This can be useful if you have some resource that other plugins need during their build step, but after build you want to remove it and send it to another thread.

fn name(&self) -> &str

Configures a name for the Plugin which is primarily used for checking plugin uniqueness and debugging.

fn is_unique(&self) -> bool

If the plugin can be meaningfully instantiated several times in an App, override this method to return false.