pebble/assets/
singleton_asset.rs

1//! Lazy resources — singleton GPU resources that are constructed once,
2//! on-demand, as soon as their backend and dependencies become available,
3//! but (unlike [`Asset`]) are never tracked by a [`Handle`] or stored in a
4//! pool, because there is only ever one of them.
5//!
6//! Use this for things like: a shared bind group layout, a camera's GPU
7//! buffer, a depth texture — anything that (a) needs a device/backend and
8//! possibly other resources to exist before it can be built, and (b) has
9//! exactly one instance for the whole app, accessed directly via `Res<T>`
10//! rather than through a handle.
11//!
12//! If you find yourself wanting more than one instance of something (e.g.
13//! multiple cameras, multiple independently-loaded textures), that's a
14//! sign you actually want [`Asset`] + [`Handle`], not [`LazyResource`].
15
16use crate::{
17    app::SystemStage,
18    assets::deps::Dependencies,
19    ecs::plugin::Plugin,
20    ecs::resources::Resources,
21    ecs::system::{Commands, Res},
22};
23
24/// A resource that is constructed once, lazily, as soon as its device and
25/// dependencies are available — and never rebuilt or reconstructed after
26/// that (unless you explicitly remove it yourself).
27///
28/// Unlike [`Asset`], there is no `Source` and no `Handle` — a
29/// `LazyResource` has nothing authored to parse from; it's pure
30/// construction from a device plus whatever else it depends on.
31pub trait LazyResource<B>: 'static + Send + Sync + Sized {
32    /// Other resources this singleton needs before it can be built.
33    /// Use `()` if none are needed.
34    type Deps<'a>: Dependencies<'a>;
35
36    /// Attempt to construct this singleton. Return `None` if construction
37    /// can't succeed yet for a reason not already covered by `Deps`
38    /// readiness (e.g. a transient condition) — the plugin will retry
39    /// next tick.
40    fn construct<'a>(backend: &B, deps: &Self::Deps<'a>) -> Option<Self>;
41}
42
43/// Registers the system that lazily constructs `T` once `B` and `T::Deps`
44/// are available, and never again afterward.
45pub struct LazyResourcePlugin<B, T: LazyResource<B>> {
46    _marker: std::marker::PhantomData<(B, T)>,
47}
48
49impl<B, T: LazyResource<B>> LazyResourcePlugin<B, T> {
50    pub fn new() -> Self {
51        Self {
52            _marker: std::marker::PhantomData,
53        }
54    }
55}
56
57impl<B, T> Plugin for LazyResourcePlugin<B, T>
58where
59    B: 'static + Send + Sync,
60    T: LazyResource<B>,
61{
62    fn build(&self, app: &mut crate::prelude::App) {
63        app.add_system(SystemStage::AssetSyncDeps, construct_resource::<B, T>);
64    }
65}
66
67fn construct_resource<B, T>(
68    mut commands: Commands,
69    backend: Option<Res<B>>,
70    existing: Option<Res<T>>,
71    world: &hecs::World,
72    resources: &Resources,
73) where
74    B: 'static + Send + Sync,
75    T: LazyResource<B>,
76{
77    // Already built — nothing to do, forever.
78    if existing.is_some() {
79        return;
80    }
81
82    let Some(backend) = backend else {
83        tracing::trace!(
84            "{}: waiting on backend to construct resource",
85            std::any::type_name::<T>()
86        );
87        return;
88    };
89
90    let Some(deps) = T::Deps::try_gather(world, resources) else {
91        tracing::trace!(
92            "{}: waiting on dependencies to construct resource",
93            std::any::type_name::<T>()
94        );
95        return;
96    };
97
98    match T::construct(&backend, &deps) {
99        Some(value) => {
100            commands.insert_resource(value);
101        }
102        None => {
103            tracing::trace!(
104                "{}: construct() returned None, will retry next tick",
105                std::any::type_name::<T>()
106            );
107        }
108    }
109}
pebble/assets/singleton_asset.rs

pebble/assets/
singleton_asset.rs
