bevy_asset/
asset_changed.rs

1//! Defines the [`AssetChanged`] query filter.
2//!
3//! Like [`Changed`](bevy_ecs::prelude::Changed), but for [`Asset`]s,
4//! and triggers whenever the handle or the underlying asset changes.
5
6use crate::{AsAssetId, Asset, AssetId};
7use bevy_ecs::component::Components;
8use bevy_ecs::{
9    archetype::Archetype,
10    component::{ComponentId, Tick},
11    prelude::{Entity, Resource, World},
12    query::{FilteredAccess, QueryData, QueryFilter, ReadFetch, WorldQuery},
13    storage::{Table, TableRow},
14    world::unsafe_world_cell::UnsafeWorldCell,
15};
16use bevy_platform::collections::HashMap;
17use core::marker::PhantomData;
18use disqualified::ShortName;
19use tracing::error;
20
21/// A resource that stores the last tick an asset was changed. This is used by
22/// the [`AssetChanged`] filter to determine if an asset has changed since the last time
23/// a query ran.
24///
25/// This resource is automatically managed by the [`AssetEvents`](crate::AssetEvents) schedule and
26/// should not be exposed to the user in order to maintain safety guarantees. Any additional uses of
27/// this resource should be carefully audited to ensure that they do not introduce any safety
28/// issues.
29#[derive(Resource)]
30pub(crate) struct AssetChanges<A: Asset> {
31    change_ticks: HashMap<AssetId<A>, Tick>,
32    last_change_tick: Tick,
33}
34
35impl<A: Asset> AssetChanges<A> {
36    pub(crate) fn insert(&mut self, asset_id: AssetId<A>, tick: Tick) {
37        self.last_change_tick = tick;
38        self.change_ticks.insert(asset_id, tick);
39    }
40    pub(crate) fn remove(&mut self, asset_id: &AssetId<A>) {
41        self.change_ticks.remove(asset_id);
42    }
43}
44
45impl<A: Asset> Default for AssetChanges<A> {
46    fn default() -> Self {
47        Self {
48            change_ticks: Default::default(),
49            last_change_tick: Tick::new(0),
50        }
51    }
52}
53
54struct AssetChangeCheck<'w, A: AsAssetId> {
55    // This should never be `None` in practice, but we need to handle the case
56    // where the `AssetChanges` resource was removed.
57    change_ticks: Option<&'w HashMap<AssetId<A::Asset>, Tick>>,
58    last_run: Tick,
59    this_run: Tick,
60}
61
62impl<A: AsAssetId> Clone for AssetChangeCheck<'_, A> {
63    fn clone(&self) -> Self {
64        *self
65    }
66}
67
68impl<A: AsAssetId> Copy for AssetChangeCheck<'_, A> {}
69
70impl<'w, A: AsAssetId> AssetChangeCheck<'w, A> {
71    fn new(changes: &'w AssetChanges<A::Asset>, last_run: Tick, this_run: Tick) -> Self {
72        Self {
73            change_ticks: Some(&changes.change_ticks),
74            last_run,
75            this_run,
76        }
77    }
78    // TODO(perf): some sort of caching? Each check has two levels of indirection,
79    // which is not optimal.
80    fn has_changed(&self, handle: &A) -> bool {
81        let is_newer = |tick: &Tick| tick.is_newer_than(self.last_run, self.this_run);
82        let id = handle.as_asset_id();
83
84        self.change_ticks
85            .is_some_and(|change_ticks| change_ticks.get(&id).is_some_and(is_newer))
86    }
87}
88
89/// Filter that selects entities with an `A` for an asset that changed
90/// after the system last ran, where `A` is a component that implements
91/// [`AsAssetId`].
92///
93/// Unlike `Changed<A>`, this is true whenever the asset for the `A`
94/// in `ResMut<Assets<A>>` changed. For example, when a mesh changed through the
95/// [`Assets<Mesh>::get_mut`] method, `AssetChanged<Mesh>` will iterate over all
96/// entities with the `Handle<Mesh>` for that mesh. Meanwhile, `Changed<Handle<Mesh>>`
97/// will iterate over no entities.
98///
99/// Swapping the actual `A` component is a common pattern. So you
100/// should check for _both_ `AssetChanged<A>` and `Changed<A>` with
101/// `Or<(Changed<A>, AssetChanged<A>)>`.
102///
103/// # Quirks
104///
105/// - Asset changes are registered in the [`AssetEvents`] schedule.
106/// - Removed assets are not detected.
107///
108/// The list of changed assets only gets updated in the
109/// [`AssetEvents`] schedule which runs in `Last`. Therefore, `AssetChanged`
110/// will only pick up asset changes in schedules following `AssetEvents` or the
111/// next frame. Consider adding the system in the `Last` schedule after [`AssetEvents`] if you need
112/// to react without frame delay to asset changes.
113///
114/// # Performance
115///
116/// When at least one `A` is updated, this will
117/// read a hashmap once per entity with an `A` component. The
118/// runtime of the query is proportional to how many entities with an `A`
119/// it matches.
120///
121/// If no `A` asset updated since the last time the system ran, then no lookups occur.
122///
123/// [`AssetEvents`]: crate::AssetEvents
124/// [`Assets<Mesh>::get_mut`]: crate::Assets::get_mut
125pub struct AssetChanged<A: AsAssetId>(PhantomData<A>);
126
127/// [`WorldQuery`] fetch for [`AssetChanged`].
128#[doc(hidden)]
129pub struct AssetChangedFetch<'w, A: AsAssetId> {
130    inner: Option<ReadFetch<'w, A>>,
131    check: AssetChangeCheck<'w, A>,
132}
133
134impl<'w, A: AsAssetId> Clone for AssetChangedFetch<'w, A> {
135    fn clone(&self) -> Self {
136        Self {
137            inner: self.inner,
138            check: self.check,
139        }
140    }
141}
142
143/// [`WorldQuery`] state for [`AssetChanged`].
144#[doc(hidden)]
145pub struct AssetChangedState<A: AsAssetId> {
146    asset_id: ComponentId,
147    resource_id: ComponentId,
148    _asset: PhantomData<fn(A)>,
149}
150
151#[expect(unsafe_code, reason = "WorldQuery is an unsafe trait.")]
152/// SAFETY: `ROQueryFetch<Self>` is the same as `QueryFetch<Self>`
153unsafe impl<A: AsAssetId> WorldQuery for AssetChanged<A> {
154    type Fetch<'w> = AssetChangedFetch<'w, A>;
155
156    type State = AssetChangedState<A>;
157
158    fn shrink_fetch<'wlong: 'wshort, 'wshort>(fetch: Self::Fetch<'wlong>) -> Self::Fetch<'wshort> {
159        fetch
160    }
161
162    unsafe fn init_fetch<'w>(
163        world: UnsafeWorldCell<'w>,
164        state: &Self::State,
165        last_run: Tick,
166        this_run: Tick,
167    ) -> Self::Fetch<'w> {
168        // SAFETY:
169        // - `AssetChanges` is private and only accessed mutably in the `AssetEvents` schedule
170        // - `resource_id` was obtained from the type ID of `AssetChanges<A::Asset>`.
171        let Some(changes) = (unsafe {
172            world
173                .get_resource_by_id(state.resource_id)
174                .map(|ptr| ptr.deref::<AssetChanges<A::Asset>>())
175        }) else {
176            error!(
177                "AssetChanges<{ty}> resource was removed, please do not remove \
178                AssetChanges<{ty}> when using the AssetChanged<{ty}> world query",
179                ty = ShortName::of::<A>()
180            );
181
182            return AssetChangedFetch {
183                inner: None,
184                check: AssetChangeCheck {
185                    change_ticks: None,
186                    last_run,
187                    this_run,
188                },
189            };
190        };
191        let has_updates = changes.last_change_tick.is_newer_than(last_run, this_run);
192
193        AssetChangedFetch {
194            inner: has_updates.then(||
195                    // SAFETY: We delegate to the inner `init_fetch` for `A`
196                    unsafe {
197                        <&A>::init_fetch(world, &state.asset_id, last_run, this_run)
198                    }),
199            check: AssetChangeCheck::new(changes, last_run, this_run),
200        }
201    }
202
203    const IS_DENSE: bool = <&A>::IS_DENSE;
204
205    unsafe fn set_archetype<'w>(
206        fetch: &mut Self::Fetch<'w>,
207        state: &Self::State,
208        archetype: &'w Archetype,
209        table: &'w Table,
210    ) {
211        if let Some(inner) = &mut fetch.inner {
212            // SAFETY: We delegate to the inner `set_archetype` for `A`
213            unsafe {
214                <&A>::set_archetype(inner, &state.asset_id, archetype, table);
215            }
216        }
217    }
218
219    unsafe fn set_table<'w>(fetch: &mut Self::Fetch<'w>, state: &Self::State, table: &'w Table) {
220        if let Some(inner) = &mut fetch.inner {
221            // SAFETY: We delegate to the inner `set_table` for `A`
222            unsafe {
223                <&A>::set_table(inner, &state.asset_id, table);
224            }
225        }
226    }
227
228    #[inline]
229    fn update_component_access(state: &Self::State, access: &mut FilteredAccess<ComponentId>) {
230        <&A>::update_component_access(&state.asset_id, access);
231        access.add_resource_read(state.resource_id);
232    }
233
234    fn init_state(world: &mut World) -> AssetChangedState<A> {
235        let resource_id = world.init_resource::<AssetChanges<A::Asset>>();
236        let asset_id = world.register_component::<A>();
237        AssetChangedState {
238            asset_id,
239            resource_id,
240            _asset: PhantomData,
241        }
242    }
243
244    fn get_state(components: &Components) -> Option<Self::State> {
245        let resource_id = components.resource_id::<AssetChanges<A::Asset>>()?;
246        let asset_id = components.component_id::<A>()?;
247        Some(AssetChangedState {
248            asset_id,
249            resource_id,
250            _asset: PhantomData,
251        })
252    }
253
254    fn matches_component_set(
255        state: &Self::State,
256        set_contains_id: &impl Fn(ComponentId) -> bool,
257    ) -> bool {
258        set_contains_id(state.asset_id)
259    }
260}
261
262#[expect(unsafe_code, reason = "QueryFilter is an unsafe trait.")]
263/// SAFETY: read-only access
264unsafe impl<A: AsAssetId> QueryFilter for AssetChanged<A> {
265    const IS_ARCHETYPAL: bool = false;
266
267    #[inline]
268    unsafe fn filter_fetch(
269        fetch: &mut Self::Fetch<'_>,
270        entity: Entity,
271        table_row: TableRow,
272    ) -> bool {
273        fetch.inner.as_mut().is_some_and(|inner| {
274            // SAFETY: We delegate to the inner `fetch` for `A`
275            unsafe {
276                let handle = <&A>::fetch(inner, entity, table_row);
277                fetch.check.has_changed(handle)
278            }
279        })
280    }
281}
282
283#[cfg(test)]
284#[expect(clippy::print_stdout, reason = "Allowed in tests.")]
285mod tests {
286    use crate::{AssetEvents, AssetPlugin, Handle};
287    use alloc::{vec, vec::Vec};
288    use core::num::NonZero;
289    use std::println;
290
291    use crate::{AssetApp, Assets};
292    use bevy_app::{App, AppExit, PostUpdate, Startup, TaskPoolPlugin, Update};
293    use bevy_ecs::schedule::IntoScheduleConfigs;
294    use bevy_ecs::{
295        component::Component,
296        event::EventWriter,
297        resource::Resource,
298        system::{Commands, IntoSystem, Local, Query, Res, ResMut},
299    };
300    use bevy_reflect::TypePath;
301
302    use super::*;
303
304    #[derive(Asset, TypePath, Debug)]
305    struct MyAsset(usize, &'static str);
306
307    #[derive(Component)]
308    struct MyComponent(Handle<MyAsset>);
309
310    impl AsAssetId for MyComponent {
311        type Asset = MyAsset;
312
313        fn as_asset_id(&self) -> AssetId<Self::Asset> {
314            self.0.id()
315        }
316    }
317
318    fn run_app<Marker>(system: impl IntoSystem<(), (), Marker>) {
319        let mut app = App::new();
320        app.add_plugins((TaskPoolPlugin::default(), AssetPlugin::default()))
321            .init_asset::<MyAsset>()
322            .add_systems(Update, system);
323        app.update();
324    }
325
326    // According to a comment in QueryState::new in bevy_ecs, components on filter
327    // position shouldn't conflict with components on query position.
328    #[test]
329    fn handle_filter_pos_ok() {
330        fn compatible_filter(
331            _query: Query<&mut MyComponent, AssetChanged<MyComponent>>,
332            mut exit: EventWriter<AppExit>,
333        ) {
334            exit.write(AppExit::Error(NonZero::<u8>::MIN));
335        }
336        run_app(compatible_filter);
337    }
338
339    #[derive(Default, PartialEq, Debug, Resource)]
340    struct Counter(Vec<u32>);
341
342    fn count_update(
343        mut counter: ResMut<Counter>,
344        assets: Res<Assets<MyAsset>>,
345        query: Query<&MyComponent, AssetChanged<MyComponent>>,
346    ) {
347        for handle in query.iter() {
348            let asset = assets.get(&handle.0).unwrap();
349            counter.0[asset.0] += 1;
350        }
351    }
352
353    fn update_some(mut assets: ResMut<Assets<MyAsset>>, mut run_count: Local<u32>) {
354        let mut update_index = |i| {
355            let id = assets
356                .iter()
357                .find_map(|(h, a)| (a.0 == i).then_some(h))
358                .unwrap();
359            let asset = assets.get_mut(id).unwrap();
360            println!("setting new value for {}", asset.0);
361            asset.1 = "new_value";
362        };
363        match *run_count {
364            0 | 1 => update_index(0),
365            2 => {}
366            3 => {
367                update_index(0);
368                update_index(1);
369            }
370            4.. => update_index(1),
371        };
372        *run_count += 1;
373    }
374
375    fn add_some(
376        mut assets: ResMut<Assets<MyAsset>>,
377        mut cmds: Commands,
378        mut run_count: Local<u32>,
379    ) {
380        match *run_count {
381            1 => {
382                cmds.spawn(MyComponent(assets.add(MyAsset(0, "init"))));
383            }
384            0 | 2 => {}
385            3 => {
386                cmds.spawn(MyComponent(assets.add(MyAsset(1, "init"))));
387                cmds.spawn(MyComponent(assets.add(MyAsset(2, "init"))));
388            }
389            4.. => {
390                cmds.spawn(MyComponent(assets.add(MyAsset(3, "init"))));
391            }
392        };
393        *run_count += 1;
394    }
395
396    #[track_caller]
397    fn assert_counter(app: &App, assert: Counter) {
398        assert_eq!(&assert, app.world().resource::<Counter>());
399    }
400
401    #[test]
402    fn added() {
403        let mut app = App::new();
404
405        app.add_plugins((TaskPoolPlugin::default(), AssetPlugin::default()))
406            .init_asset::<MyAsset>()
407            .insert_resource(Counter(vec![0, 0, 0, 0]))
408            .add_systems(Update, add_some)
409            .add_systems(PostUpdate, count_update.after(AssetEvents));
410
411        // First run of the app, `add_systems(Startup…)` runs.
412        app.update(); // run_count == 0
413        assert_counter(&app, Counter(vec![0, 0, 0, 0]));
414        app.update(); // run_count == 1
415        assert_counter(&app, Counter(vec![1, 0, 0, 0]));
416        app.update(); // run_count == 2
417        assert_counter(&app, Counter(vec![1, 0, 0, 0]));
418        app.update(); // run_count == 3
419        assert_counter(&app, Counter(vec![1, 1, 1, 0]));
420        app.update(); // run_count == 4
421        assert_counter(&app, Counter(vec![1, 1, 1, 1]));
422    }
423
424    #[test]
425    fn changed() {
426        let mut app = App::new();
427
428        app.add_plugins((TaskPoolPlugin::default(), AssetPlugin::default()))
429            .init_asset::<MyAsset>()
430            .insert_resource(Counter(vec![0, 0]))
431            .add_systems(
432                Startup,
433                |mut cmds: Commands, mut assets: ResMut<Assets<MyAsset>>| {
434                    let asset0 = assets.add(MyAsset(0, "init"));
435                    let asset1 = assets.add(MyAsset(1, "init"));
436                    cmds.spawn(MyComponent(asset0.clone()));
437                    cmds.spawn(MyComponent(asset0));
438                    cmds.spawn(MyComponent(asset1.clone()));
439                    cmds.spawn(MyComponent(asset1.clone()));
440                    cmds.spawn(MyComponent(asset1));
441                },
442            )
443            .add_systems(Update, update_some)
444            .add_systems(PostUpdate, count_update.after(AssetEvents));
445
446        // First run of the app, `add_systems(Startup…)` runs.
447        app.update(); // run_count == 0
448
449        // First run: We count the entities that were added in the `Startup` schedule
450        assert_counter(&app, Counter(vec![2, 3]));
451
452        // Second run: `update_once` updates the first asset, which is
453        // associated with two entities, so `count_update` picks up two updates
454        app.update(); // run_count == 1
455        assert_counter(&app, Counter(vec![4, 3]));
456
457        // Third run: `update_once` doesn't update anything, same values as last
458        app.update(); // run_count == 2
459        assert_counter(&app, Counter(vec![4, 3]));
460
461        // Fourth run: We update the two assets (asset 0: 2 entities, asset 1: 3)
462        app.update(); // run_count == 3
463        assert_counter(&app, Counter(vec![6, 6]));
464
465        // Fifth run: only update second asset
466        app.update(); // run_count == 4
467        assert_counter(&app, Counter(vec![6, 9]));
468        // ibid
469        app.update(); // run_count == 5
470        assert_counter(&app, Counter(vec![6, 12]));
471    }
472}
bevy_asset/asset_changed.rs

bevy_asset/
asset_changed.rs
