unlit3dx_examples/scene/

shared.rs

//! The scene's assets, built once in the render world.
//!
//! The render world allocates the meshes and materials in one job and
//! publishes them. Every shape a drop needs is its own render instance, asked
//! for when the drop happens; an instance the camera can no longer see is
//! despawned by the render world, so nothing is kept hidden for reuse.

use unlit_ecs::bundle;
use unlit_ecs::{Bundle, DynamicBundle, World};
use unlit3d::components::Transform;
use unlit3dx::prelude::*;

use super::HIDDEN_POSITION;
use super::Scene;
use super::shapes::{BALL_COLORS, PATTERN_SIZE, SHAPE_KINDS, pattern_texture, shape_mesh};
use super::tick::advancing;
use crate::render::{
    RenderEntity, allocate_mesh, allocate_rgba_material, hidden_instance_of, linear_sampler,
};

/// The render entities a shape is built from, in kind-major order.
///
/// The build job allocates them in the render world and publishes them here;
/// the gameplay world names them when it asks for an instance. They are
/// [`RenderEntity`]s: the world that built them and the world that names
/// them are two, so a bare entity is not enough to say which.
#[derive(Clone, Debug)]
pub struct SceneAssets {
    /// One mesh per [`SHAPE_KINDS`] entry, in that order.
    pub meshes: Vec<RenderEntity>,
    /// One material per shape kind and color, kind-major:
    /// `kind * BALL_COLORS.len() + color`.
    pub materials: Vec<RenderEntity>,
}

/// The scene's assets, on their own entity in the gameplay world.
///
/// It owns the render entities every shape is built from, and whether the
/// build has landed. It does not own instances: a drop asks the render world
/// for one, and the render world despawns it once the camera loses sight of
/// it.
pub struct SceneState {
    /// The build the render world owes, and its answer once it comes.
    ///
    /// The whole build is one request, so it is asked under no key at all:
    /// what it names is nothing but itself.
    build: Pending<(), SceneAssets>,
    /// Where the answer lands, reused across ticks.
    settled: Vec<((), Settled<SceneAssets>)>,
    /// The assets once the build landed, for the jobs that name them.
    pub loaded: Option<SceneAssets>,
    /// Whether the build landed and the scene is live.
    pub ready: bool,
    /// Whether the wait is over: the build landed, or the render world ended
    /// before it answered.
    given_up: bool,
}

impl SceneState {
    /// Ask the render world for the scene's assets.
    ///
    /// The whole build is one question there: it allocates the meshes and the
    /// materials, and the answer is their entities. Until it lands the scene
    /// is empty, and every object that needs a shape stays unspawned.
    #[must_use]
    pub fn new(scene: &Scene) -> Self {
        log::info!("the gameplay world started; asking the render world for the scene");
        let mut build = Pending::new(scene.render_state.clone(), None);
        // A build that never lands is never retried: the scene is the whole
        // of it, so the wait runs until the render world answers or ends.
        let given_up = match build.request(&scene.render, (), build_assets) {
            Ok(()) => false,
            Err(error) => {
                log::error!(
                    "the render world refused the scene build ({error:?}); the scene stays empty"
                );
                // The request was never accepted, so no answer is coming:
                // the wait is over before it starts.
                true
            }
        };
        Self {
            build,
            settled: Vec::new(),
            loaded: None,
            ready: false,
            given_up,
        }
    }
}

/// The scene's assets and the tick that collects them.
///
/// The build is asked once, when the state is built, but its answer is folded
/// on a tick: a state spawned without its tick would wait for an answer
/// nobody collects, and a tick without its state has nothing to advance.
pub(super) struct SceneBuild {
    /// The state the tick advances.
    state: SceneState,
}

impl SceneBuild {
    /// The build of `scene`, ready to spawn.
    #[must_use]
    pub(super) fn new(scene: &Scene) -> Self {
        Self {
            state: SceneState::new(scene),
        }
    }

    /// Collect the assets once the build job has published them.
    ///
    /// The scene stays empty if the render world refused the job, and it stops
    /// waiting if the world that owed the answer is gone: a job that panicked
    /// takes its answer with it, and no reader will ever see one.
    fn tick(state: &mut SceneState) {
        if state.given_up {
            return;
        }
        let mut settled = core::mem::take(&mut state.settled);
        state.build.advance(0.0, &mut settled);
        for (_, settled) in settled.drain(..) {
            match settled {
                Settled::Answered(assets) => {
                    log::info!(
                        "the scene is live: {} meshes, {} materials",
                        assets.meshes.len(),
                        assets.materials.len()
                    );
                    state.loaded = Some(assets);
                    state.ready = true;
                    state.given_up = true;
                }
                // The wait runs until the world answers or ends, so this is
                // the world ending: a job a panic took never builds a scene.
                Settled::Expired => {
                    log::error!(
                        "the render world ended before it built the scene; the scene stays empty"
                    );
                    state.given_up = true;
                }
            }
        }
        state.settled = settled;
    }
}

impl Bundle for SceneBuild {
    fn into_bundle(self) -> DynamicBundle {
        let Self { state } = self;
        bundle![
            state,
            advancing(move |state, _world, _frame| Self::tick(state)),
        ]
    }
}

/// Allocate the scene's meshes and materials, and answer their entities.
///
/// One step, so nothing waits for an answer in between.
fn build_assets(world: &mut World) -> SceneAssets {
    let mut meshes = Vec::with_capacity(SHAPE_KINDS.len());
    for kind in SHAPE_KINDS {
        meshes.push(allocate_mesh(world, &shape_mesh(kind)));
    }
    // One patterned material per shape kind and color, kind-major.
    let mut materials = Vec::with_capacity(SHAPE_KINDS.len() * BALL_COLORS.len());
    for kind in SHAPE_KINDS {
        for color in BALL_COLORS {
            materials.push(allocate_rgba_material(
                world,
                (PATTERN_SIZE, PATTERN_SIZE),
                &pattern_texture(kind, color),
                linear_sampler(),
            ));
        }
    }
    SceneAssets { meshes, materials }
}

/// Spawn one hidden instance wearing the assets it names, and answer it.
///
/// It stays hidden until its body is ready and the show puts it in place.
pub fn create_instance(
    mesh: RenderEntity,
    material: RenderEntity,
) -> impl FnOnce(&mut World) -> RenderEntity {
    move |world: &mut World| {
        hidden_instance_of(
            world,
            mesh,
            material,
            Transform {
                translation: HIDDEN_POSITION,
                ..Default::default()
            },
        )
    }
}

/// The kind and color a drop wears, as indices into [`SceneAssets`].
///
/// The palette of every shape kind and color runs from its last entry down,
/// so a drop picks the last look first and cycles through the rest.
#[must_use]
pub fn look(index: usize) -> (usize, usize) {
    let looks = SHAPE_KINDS.len() * BALL_COLORS.len();
    let palette = looks - 1 - index % looks;
    (
        palette % SHAPE_KINDS.len(),
        (palette + palette / SHAPE_KINDS.len()) % BALL_COLORS.len(),
    )
}

#[cfg(test)]
mod tests {
    use super::*;

    /// One cycle of the palette covers every shape and color exactly once, so
    /// a scene that keeps dropping shapes never runs out of looks.
    #[test]
    fn looks_cover_the_palette() {
        let looks = SHAPE_KINDS.len() * BALL_COLORS.len();
        let mut seen = vec![false; looks];
        for index in 0..looks {
            let (kind, color) = look(index);
            assert!(kind < SHAPE_KINDS.len());
            assert!(color < BALL_COLORS.len());
            let at = kind * BALL_COLORS.len() + color;
            assert!(!seen[at], "look {at} repeats at index {index}");
            seen[at] = true;
        }
        assert!(seen.iter().all(|seen| *seen));
    }
}