Struct SyncWorldPlugin 

pub struct SyncWorldPlugin<L>(/* private fields */)
where
    L: AppLabel;

A plugin that synchronizes entities with SyncToSubWorld between the main world and the sub world.

All entities with the SyncToSubWorld 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

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

The SubEntity contains the corresponding sub world entity of a main world entity, while MainEntity contains the corresponding main world entity of a sub 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 SubEntity will return the corresponding sub 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 sub world for these entities.

|--------------------------------------------------------------------|
|      |         |          Main world update                        |
| sync | extract |---------------------------------------------------|
|      |         |         Sub world update                       |
|--------------------------------------------------------------------|

An example for synchronized main entities 1v1 and 18v1

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

|----------Sub 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 sub world entity. Not every entity needs to be synchronized, however; only entities with the SyncToSubWorld component are synced. Adding SyncToSubWorld to a main world component will establish such a link. Once a synchronized main entity is despawned, its corresponding sub 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. A sub world may care about a Position component, but may not care about a Velocity component. The extraction happens in its own step, independently from, and after synchronization.

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

Trait Implementations

impl<L> Default for SyncWorldPlugin<L>

where L: Default + AppLabel,

fn default() -> SyncWorldPlugin<L>

Returns the “default value” for a type.

impl<L> Plugin for SyncWorldPlugin<L>

where L: AppLabel + Default + Clone + Copy + Eq,

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.