bevy_render/
sync_world.rs

1use bevy_app::Plugin;
2use bevy_derive::{Deref, DerefMut};
3use bevy_ecs::{
4    component::Component,
5    entity::{ContainsEntity, Entity, EntityEquivalent, EntityHash},
6    lifecycle::{Add, Remove},
7    observer::On,
8    query::With,
9    reflect::ReflectComponent,
10    resource::Resource,
11    system::{Local, Query, ResMut, SystemState},
12    world::{EntityWorldMut, Mut, World},
13};
14use bevy_platform::collections::{HashMap, HashSet};
15use bevy_reflect::{std_traits::ReflectDefault, Reflect};
16
17/// A plugin that synchronizes entities with [`SyncToRenderWorld`] between the main world and the render world.
18///
19/// All entities with the [`SyncToRenderWorld`] component are kept in sync. It
20/// is automatically added as a required component by [`ExtractComponentPlugin`]
21/// and [`SyncComponentPlugin`], so it doesn't need to be added manually when
22/// spawning or as a required component when either of these plugins are used.
23///
24/// # Implementation
25///
26/// Bevy's renderer is architected independently from the main app.
27/// It operates in its own separate ECS [`World`], so the renderer logic can run in parallel with the main world logic.
28/// This is called "Pipelined Rendering", see [`PipelinedRenderingPlugin`] for more information.
29///
30/// [`SyncWorldPlugin`] is the first thing that runs every frame and it maintains an entity-to-entity mapping
31/// between the main world and the render world.
32/// It does so by spawning and despawning entities in the render world, to match spawned and despawned entities in the main world.
33/// The link between synced entities is maintained by the [`RenderEntity`] and [`MainEntity`] components.
34///
35/// The [`RenderEntity`] contains the corresponding render world entity of a main world entity, while [`MainEntity`] contains
36/// the corresponding main world entity of a render world entity.
37/// For convenience, [`QueryData`](bevy_ecs::query::QueryData) implementations are provided for both components:
38/// adding [`MainEntity`] to a query (without a `&`) will return the corresponding main world [`Entity`],
39/// and adding [`RenderEntity`] will return the corresponding render world [`Entity`].
40/// If you have access to the component itself, the underlying entities can be accessed by calling `.id()`.
41///
42/// Synchronization is necessary preparation for extraction ([`ExtractSchedule`](crate::ExtractSchedule)), which copies over component data from the main
43/// to the render world for these entities.
44///
45/// ```text
46/// |--------------------------------------------------------------------|
47/// |      |         |          Main world update                        |
48/// | sync | extract |---------------------------------------------------|
49/// |      |         |         Render world update                       |
50/// |--------------------------------------------------------------------|
51/// ```
52///
53/// An example for synchronized main entities 1v1 and 18v1
54///
55/// ```text
56/// |---------------------------Main World------------------------------|
57/// |  Entity  |                    Component                           |
58/// |-------------------------------------------------------------------|
59/// | ID: 1v1  | PointLight | RenderEntity(ID: 3V1) | SyncToRenderWorld |
60/// | ID: 18v1 | PointLight | RenderEntity(ID: 5V1) | SyncToRenderWorld |
61/// |-------------------------------------------------------------------|
62///
63/// |----------Render World-----------|
64/// |  Entity  |       Component      |
65/// |---------------------------------|
66/// | ID: 3v1  | MainEntity(ID: 1V1)  |
67/// | ID: 5v1  | MainEntity(ID: 18V1) |
68/// |---------------------------------|
69///
70/// ```
71///
72/// Note that this effectively establishes a link between the main world entity and the render world entity.
73/// Not every entity needs to be synchronized, however; only entities with the [`SyncToRenderWorld`] component are synced.
74/// Adding [`SyncToRenderWorld`] to a main world component will establish such a link.
75/// Once a synchronized main entity is despawned, its corresponding render entity will be automatically
76/// despawned in the next `sync`.
77///
78/// The sync step does not copy any of component data between worlds, since its often not necessary to transfer over all
79/// the components of a main world entity.
80/// The render world probably cares about a `Position` component, but not a `Velocity` component.
81/// The extraction happens in its own step, independently from, and after synchronization.
82///
83/// Moreover, [`SyncWorldPlugin`] only synchronizes *entities*. [`RenderAsset`](crate::render_asset::RenderAsset)s like meshes and textures are handled
84/// differently.
85///
86/// [`PipelinedRenderingPlugin`]: crate::pipelined_rendering::PipelinedRenderingPlugin
87/// [`ExtractComponentPlugin`]: crate::extract_component::ExtractComponentPlugin
88/// [`SyncComponentPlugin`]: crate::sync_component::SyncComponentPlugin
89#[derive(Default)]
90pub struct SyncWorldPlugin;
91
92impl Plugin for SyncWorldPlugin {
93    fn build(&self, app: &mut bevy_app::App) {
94        app.init_resource::<PendingSyncEntity>();
95        app.add_observer(
96            |add: On<Add, SyncToRenderWorld>, mut pending: ResMut<PendingSyncEntity>| {
97                pending.push(EntityRecord::Added(add.entity));
98            },
99        );
100        app.add_observer(
101            |remove: On<Remove, SyncToRenderWorld>,
102             mut pending: ResMut<PendingSyncEntity>,
103             query: Query<&RenderEntity>| {
104                if let Ok(e) = query.get(remove.entity) {
105                    pending.push(EntityRecord::Removed(*e));
106                };
107            },
108        );
109    }
110}
111/// Marker component that indicates that its entity needs to be synchronized to the render world.
112///
113/// This component is automatically added as a required component by [`ExtractComponentPlugin`] and [`SyncComponentPlugin`].
114/// For more information see [`SyncWorldPlugin`].
115///
116/// NOTE: This component should persist throughout the entity's entire lifecycle.
117/// If this component is removed from its entity, the entity will be despawned.
118///
119/// [`ExtractComponentPlugin`]: crate::extract_component::ExtractComponentPlugin
120/// [`SyncComponentPlugin`]: crate::sync_component::SyncComponentPlugin
121#[derive(Component, Copy, Clone, Debug, Default, Reflect)]
122#[reflect(Component, Default, Clone)]
123#[component(storage = "SparseSet")]
124pub struct SyncToRenderWorld;
125
126/// Component added on the main world entities that are synced to the Render World in order to keep track of the corresponding render world entity.
127///
128/// Can also be used as a newtype wrapper for render world entities.
129#[derive(Component, Deref, Copy, Clone, Debug, Eq, Hash, PartialEq, Reflect)]
130#[component(clone_behavior = Ignore)]
131#[reflect(Component, Clone)]
132pub struct RenderEntity(Entity);
133impl RenderEntity {
134    #[inline]
135    pub fn id(&self) -> Entity {
136        self.0
137    }
138}
139
140impl From<Entity> for RenderEntity {
141    fn from(entity: Entity) -> Self {
142        RenderEntity(entity)
143    }
144}
145
146impl ContainsEntity for RenderEntity {
147    fn entity(&self) -> Entity {
148        self.id()
149    }
150}
151
152// SAFETY: RenderEntity is a newtype around Entity that derives its comparison traits.
153unsafe impl EntityEquivalent for RenderEntity {}
154
155/// Component added on the render world entities to keep track of the corresponding main world entity.
156///
157/// Can also be used as a newtype wrapper for main world entities.
158#[derive(Component, Deref, Copy, Clone, Debug, Eq, Hash, PartialEq, PartialOrd, Ord, Reflect)]
159#[reflect(Component, Clone)]
160pub struct MainEntity(Entity);
161impl MainEntity {
162    #[inline]
163    pub fn id(&self) -> Entity {
164        self.0
165    }
166}
167
168impl From<Entity> for MainEntity {
169    fn from(entity: Entity) -> Self {
170        MainEntity(entity)
171    }
172}
173
174impl ContainsEntity for MainEntity {
175    fn entity(&self) -> Entity {
176        self.id()
177    }
178}
179
180// SAFETY: RenderEntity is a newtype around Entity that derives its comparison traits.
181unsafe impl EntityEquivalent for MainEntity {}
182
183/// A [`HashMap`] pre-configured to use [`EntityHash`] hashing with a [`MainEntity`].
184pub type MainEntityHashMap<V> = HashMap<MainEntity, V, EntityHash>;
185
186/// A [`HashSet`] pre-configured to use [`EntityHash`] hashing with a [`MainEntity`]..
187pub type MainEntityHashSet = HashSet<MainEntity, EntityHash>;
188
189/// Marker component that indicates that its entity needs to be despawned at the end of the frame.
190#[derive(Component, Copy, Clone, Debug, Default, Reflect)]
191#[reflect(Component, Default, Clone)]
192pub struct TemporaryRenderEntity;
193
194/// A record enum to what entities with [`SyncToRenderWorld`] have been added or removed.
195#[derive(Debug)]
196pub(crate) enum EntityRecord {
197    /// When an entity is spawned on the main world, notify the render world so that it can spawn a corresponding
198    /// entity. This contains the main world entity.
199    Added(Entity),
200    /// When an entity is despawned on the main world, notify the render world so that the corresponding entity can be
201    /// despawned. This contains the render world entity.
202    Removed(RenderEntity),
203    /// When a component is removed from an entity, notify the render world so that the corresponding component can be
204    /// removed. This contains the main world entity.
205    ComponentRemoved(Entity, fn(EntityWorldMut<'_>)),
206}
207
208// Entity Record in MainWorld pending to Sync
209#[derive(Resource, Default, Deref, DerefMut)]
210pub(crate) struct PendingSyncEntity {
211    records: Vec<EntityRecord>,
212}
213
214pub(crate) fn entity_sync_system(main_world: &mut World, render_world: &mut World) {
215    main_world.resource_scope(|world, mut pending: Mut<PendingSyncEntity>| {
216        // TODO : batching record
217        for record in pending.drain(..) {
218            match record {
219                EntityRecord::Added(e) => {
220                    if let Ok(mut main_entity) = world.get_entity_mut(e) {
221                        match main_entity.entry::<RenderEntity>() {
222                            bevy_ecs::world::ComponentEntry::Occupied(_) => {
223                                panic!("Attempting to synchronize an entity that has already been synchronized!");
224                            }
225                            bevy_ecs::world::ComponentEntry::Vacant(entry) => {
226                                let id = render_world.spawn(MainEntity(e)).id();
227
228                                entry.insert(RenderEntity(id));
229                            }
230                        };
231                    }
232                }
233                EntityRecord::Removed(render_entity) => {
234                    if let Ok(ec) = render_world.get_entity_mut(render_entity.id()) {
235                        ec.despawn();
236                    };
237                }
238                EntityRecord::ComponentRemoved(main_entity, removal_function) => {
239                    let Some(render_entity) = world.get::<RenderEntity>(main_entity) else {
240                        continue;
241                    };
242                    if let Ok(render_world_entity) = render_world.get_entity_mut(render_entity.id()) {
243                        removal_function(render_world_entity);
244                    }
245                },
246            }
247        }
248    });
249}
250
251pub(crate) fn despawn_temporary_render_entities(
252    world: &mut World,
253    state: &mut SystemState<Query<Entity, With<TemporaryRenderEntity>>>,
254    mut local: Local<Vec<Entity>>,
255) {
256    let query = state.get(world).unwrap();
257
258    local.extend(query.iter());
259
260    // Ensure next frame allocation keeps order
261    local.sort_unstable_by_key(|e| e.index());
262    for e in local.drain(..).rev() {
263        world.despawn(e);
264    }
265}
266
267/// This module exists to keep the complex unsafe code out of the main module.
268///
269/// The implementations for both [`MainEntity`] and [`RenderEntity`] should stay in sync,
270/// and are based off of the `&T` implementation in `bevy_ecs`.
271mod render_entities_world_query_impls {
272    use super::{MainEntity, RenderEntity};
273
274    use bevy_ecs::{
275        archetype::Archetype,
276        change_detection::Tick,
277        component::{ComponentId, Components},
278        entity::Entity,
279        query::{
280            ArchetypeQueryData, FilteredAccess, IterQueryData, QueryData, ReadOnlyQueryData,
281            ReleaseStateQueryData, SingleEntityQueryData, WorldQuery,
282        },
283        storage::{Table, TableRow},
284        world::{unsafe_world_cell::UnsafeWorldCell, World},
285    };
286
287    // SAFETY: defers completely to `&RenderEntity` implementation,
288    // and then only modifies the output safely.
289    unsafe impl WorldQuery for RenderEntity {
290        type Fetch<'w> = <&'static RenderEntity as WorldQuery>::Fetch<'w>;
291        type State = <&'static RenderEntity as WorldQuery>::State;
292
293        fn shrink_fetch<'wlong: 'wshort, 'wshort>(
294            fetch: Self::Fetch<'wlong>,
295        ) -> Self::Fetch<'wshort> {
296            fetch
297        }
298
299        #[inline]
300        unsafe fn init_fetch<'w, 's>(
301            world: UnsafeWorldCell<'w>,
302            component_id: &'s ComponentId,
303            last_run: Tick,
304            this_run: Tick,
305        ) -> Self::Fetch<'w> {
306            // SAFETY: defers to the `&T` implementation, with T set to `RenderEntity`.
307            unsafe {
308                <&RenderEntity as WorldQuery>::init_fetch(world, component_id, last_run, this_run)
309            }
310        }
311
312        const IS_DENSE: bool = <&'static RenderEntity as WorldQuery>::IS_DENSE;
313
314        #[inline]
315        unsafe fn set_archetype<'w, 's>(
316            fetch: &mut Self::Fetch<'w>,
317            component_id: &'s ComponentId,
318            archetype: &'w Archetype,
319            table: &'w Table,
320        ) {
321            // SAFETY: defers to the `&T` implementation, with T set to `RenderEntity`.
322            unsafe {
323                <&RenderEntity as WorldQuery>::set_archetype(fetch, component_id, archetype, table);
324            }
325        }
326
327        #[inline]
328        unsafe fn set_table<'w, 's>(
329            fetch: &mut Self::Fetch<'w>,
330            &component_id: &'s ComponentId,
331            table: &'w Table,
332        ) {
333            // SAFETY: defers to the `&T` implementation, with T set to `RenderEntity`.
334            unsafe { <&RenderEntity as WorldQuery>::set_table(fetch, &component_id, table) }
335        }
336
337        fn update_component_access(&component_id: &ComponentId, access: &mut FilteredAccess) {
338            <&RenderEntity as WorldQuery>::update_component_access(&component_id, access);
339        }
340
341        fn init_state(world: &mut World) -> ComponentId {
342            <&RenderEntity as WorldQuery>::init_state(world)
343        }
344
345        fn get_state(components: &Components) -> Option<Self::State> {
346            <&RenderEntity as WorldQuery>::get_state(components)
347        }
348
349        fn matches_component_set(
350            &state: &ComponentId,
351            set_contains_id: &impl Fn(ComponentId) -> bool,
352        ) -> bool {
353            <&RenderEntity as WorldQuery>::matches_component_set(&state, set_contains_id)
354        }
355    }
356
357    // SAFETY: Component access of Self::ReadOnly is a subset of Self.
358    // Self::ReadOnly matches exactly the same archetypes/tables as Self.
359    unsafe impl QueryData for RenderEntity {
360        const IS_READ_ONLY: bool = true;
361        const IS_ARCHETYPAL: bool = <&MainEntity as QueryData>::IS_ARCHETYPAL;
362        type ReadOnly = RenderEntity;
363        type Item<'w, 's> = Entity;
364
365        fn shrink<'wlong: 'wshort, 'wshort, 's>(
366            item: Self::Item<'wlong, 's>,
367        ) -> Self::Item<'wshort, 's> {
368            item
369        }
370
371        #[inline(always)]
372        unsafe fn fetch<'w, 's>(
373            state: &'s Self::State,
374            fetch: &mut Self::Fetch<'w>,
375            entity: Entity,
376            table_row: TableRow,
377        ) -> Option<Self::Item<'w, 's>> {
378            // SAFETY: defers to the `&T` implementation, with T set to `RenderEntity`.
379            let component =
380                unsafe { <&RenderEntity as QueryData>::fetch(state, fetch, entity, table_row) };
381            component.map(RenderEntity::id)
382        }
383
384        fn iter_access(
385            state: &Self::State,
386        ) -> impl Iterator<Item = bevy_ecs::query::EcsAccessType<'_>> {
387            <&RenderEntity as QueryData>::iter_access(state)
388        }
389    }
390
391    /// SAFETY: access is read only and only on the current entity
392    unsafe impl IterQueryData for RenderEntity {}
393
394    /// SAFETY: access is read only
395    unsafe impl ReadOnlyQueryData for RenderEntity {}
396
397    /// SAFETY: access is only on the current entity
398    unsafe impl SingleEntityQueryData for RenderEntity {}
399
400    impl ArchetypeQueryData for RenderEntity {}
401
402    impl ReleaseStateQueryData for RenderEntity {
403        fn release_state<'w>(item: Self::Item<'w, '_>) -> Self::Item<'w, 'static> {
404            item
405        }
406    }
407
408    // SAFETY: defers completely to `&RenderEntity` implementation,
409    // and then only modifies the output safely.
410    unsafe impl WorldQuery for MainEntity {
411        type Fetch<'w> = <&'static MainEntity as WorldQuery>::Fetch<'w>;
412        type State = <&'static MainEntity as WorldQuery>::State;
413
414        fn shrink_fetch<'wlong: 'wshort, 'wshort>(
415            fetch: Self::Fetch<'wlong>,
416        ) -> Self::Fetch<'wshort> {
417            fetch
418        }
419
420        #[inline]
421        unsafe fn init_fetch<'w, 's>(
422            world: UnsafeWorldCell<'w>,
423            component_id: &'s ComponentId,
424            last_run: Tick,
425            this_run: Tick,
426        ) -> Self::Fetch<'w> {
427            // SAFETY: defers to the `&T` implementation, with T set to `MainEntity`.
428            unsafe {
429                <&MainEntity as WorldQuery>::init_fetch(world, component_id, last_run, this_run)
430            }
431        }
432
433        const IS_DENSE: bool = <&'static MainEntity as WorldQuery>::IS_DENSE;
434
435        #[inline]
436        unsafe fn set_archetype<'w, 's>(
437            fetch: &mut Self::Fetch<'w>,
438            component_id: &ComponentId,
439            archetype: &'w Archetype,
440            table: &'w Table,
441        ) {
442            // SAFETY: defers to the `&T` implementation, with T set to `MainEntity`.
443            unsafe {
444                <&MainEntity as WorldQuery>::set_archetype(fetch, component_id, archetype, table);
445            }
446        }
447
448        #[inline]
449        unsafe fn set_table<'w, 's>(
450            fetch: &mut Self::Fetch<'w>,
451            &component_id: &'s ComponentId,
452            table: &'w Table,
453        ) {
454            // SAFETY: defers to the `&T` implementation, with T set to `MainEntity`.
455            unsafe { <&MainEntity as WorldQuery>::set_table(fetch, &component_id, table) }
456        }
457
458        fn update_component_access(&component_id: &ComponentId, access: &mut FilteredAccess) {
459            <&MainEntity as WorldQuery>::update_component_access(&component_id, access);
460        }
461
462        fn init_state(world: &mut World) -> ComponentId {
463            <&MainEntity as WorldQuery>::init_state(world)
464        }
465
466        fn get_state(components: &Components) -> Option<Self::State> {
467            <&MainEntity as WorldQuery>::get_state(components)
468        }
469
470        fn matches_component_set(
471            &state: &ComponentId,
472            set_contains_id: &impl Fn(ComponentId) -> bool,
473        ) -> bool {
474            <&MainEntity as WorldQuery>::matches_component_set(&state, set_contains_id)
475        }
476    }
477
478    // SAFETY: Component access of Self::ReadOnly is a subset of Self.
479    // Self::ReadOnly matches exactly the same archetypes/tables as Self.
480    unsafe impl QueryData for MainEntity {
481        const IS_READ_ONLY: bool = true;
482        const IS_ARCHETYPAL: bool = <&MainEntity as QueryData>::IS_ARCHETYPAL;
483        type ReadOnly = MainEntity;
484        type Item<'w, 's> = Entity;
485
486        fn shrink<'wlong: 'wshort, 'wshort, 's>(
487            item: Self::Item<'wlong, 's>,
488        ) -> Self::Item<'wshort, 's> {
489            item
490        }
491
492        #[inline(always)]
493        unsafe fn fetch<'w, 's>(
494            state: &'s Self::State,
495            fetch: &mut Self::Fetch<'w>,
496            entity: Entity,
497            table_row: TableRow,
498        ) -> Option<Self::Item<'w, 's>> {
499            // SAFETY: defers to the `&T` implementation, with T set to `MainEntity`.
500            let component =
501                unsafe { <&MainEntity as QueryData>::fetch(state, fetch, entity, table_row) };
502            component.map(MainEntity::id)
503        }
504
505        fn iter_access(
506            state: &Self::State,
507        ) -> impl Iterator<Item = bevy_ecs::query::EcsAccessType<'_>> {
508            <&MainEntity as QueryData>::iter_access(state)
509        }
510    }
511
512    /// SAFETY: access is read only and only on the current entity
513    unsafe impl IterQueryData for MainEntity {}
514
515    /// SAFETY: access is read only
516    unsafe impl ReadOnlyQueryData for MainEntity {}
517
518    /// SAFETY: access is only on the current entity
519    unsafe impl SingleEntityQueryData for MainEntity {}
520
521    impl ArchetypeQueryData for MainEntity {}
522
523    impl ReleaseStateQueryData for MainEntity {
524        fn release_state<'w>(item: Self::Item<'w, '_>) -> Self::Item<'w, 'static> {
525            item
526        }
527    }
528}
529
530#[cfg(test)]
531mod tests {
532    use bevy_ecs::{
533        component::Component,
534        entity::Entity,
535        lifecycle::{Add, Remove},
536        observer::On,
537        query::With,
538        system::{Query, ResMut},
539        world::World,
540    };
541
542    use super::{
543        entity_sync_system, EntityRecord, MainEntity, PendingSyncEntity, RenderEntity,
544        SyncToRenderWorld,
545    };
546
547    #[derive(Component)]
548    struct RenderDataComponent;
549
550    #[test]
551    fn sync_world() {
552        let mut main_world = World::new();
553        let mut render_world = World::new();
554        main_world.init_resource::<PendingSyncEntity>();
555
556        main_world.add_observer(
557            |add: On<Add, SyncToRenderWorld>, mut pending: ResMut<PendingSyncEntity>| {
558                pending.push(EntityRecord::Added(add.entity));
559            },
560        );
561        main_world.add_observer(
562            |remove: On<Remove, SyncToRenderWorld>,
563             mut pending: ResMut<PendingSyncEntity>,
564             query: Query<&RenderEntity>| {
565                if let Ok(e) = query.get(remove.entity) {
566                    pending.push(EntityRecord::Removed(*e));
567                };
568            },
569        );
570
571        // spawn some empty entities for test
572        for _ in 0..99 {
573            main_world.spawn_empty();
574        }
575
576        // spawn
577        let main_entity = main_world
578            .spawn(RenderDataComponent)
579            // indicates that its entity needs to be synchronized to the render world
580            .insert(SyncToRenderWorld)
581            .id();
582
583        entity_sync_system(&mut main_world, &mut render_world);
584
585        let mut q = render_world.query_filtered::<Entity, With<MainEntity>>();
586
587        // Only one synchronized entity
588        assert!(q.iter(&render_world).count() == 1);
589
590        let render_entity = q.single(&render_world).unwrap();
591        let render_entity_component = main_world.get::<RenderEntity>(main_entity).unwrap();
592
593        assert!(render_entity_component.id() == render_entity);
594
595        let main_entity_component = render_world
596            .get::<MainEntity>(render_entity_component.id())
597            .unwrap();
598
599        assert!(main_entity_component.id() == main_entity);
600
601        // despawn
602        main_world.despawn(main_entity);
603
604        entity_sync_system(&mut main_world, &mut render_world);
605
606        // Only one synchronized entity
607        assert!(q.iter(&render_world).count() == 0);
608    }
609}
bevy_render/sync_world.rs

bevy_render/
sync_world.rs
