unlit_ecs/

bundle.rs

//! Bundles: the set of components an entity is spawned with.
//!
//! A bundle is either a [`DynamicBundle`], which the [`crate::bundle!`] macro writes,
//! or a type of the caller's own that implements [`Bundle`] over its components. It
//! is not a tuple: every `'static` type is a component, tuples included, so a bare
//! `(a, b)` handed to `spawn` names one component rather than two. Writing
//! `bundle![a, b]` is what names two.
//!
//! The macro takes its items one at a time and each item is one component, so a
//! parenthesised item is a tuple component rather than a list to unpack: a
//! bundle only spreads when it is written as `..value`.
//!
//! The same component cannot appear twice in a bundle; spawning with duplicates
//! panics.

use core::any::{Any, TypeId};

use crate::column::{AnyColumn, Column};

/// One component of a bundle: its type, the name and column constructor the
/// world registers it under, and the value box the archetype takes.
///
/// The type-keyed facts sit in one entry rather than in parallel arrays, so a
/// component's type is written once and the arrays cannot fall out of step
/// when they are sorted.
pub(crate) struct BundleComponent {
    pub(crate) type_id: TypeId,
    pub(crate) name: &'static str,
    pub(crate) column: fn() -> Box<dyn AnyColumn>,
    pub(crate) value: Box<dyn Any>,
}

/// The components of one bundle, sorted by type.
pub(crate) type Components = Vec<BundleComponent>;

/// A bundle assembled at runtime.
///
/// This is what [`crate::bundle!`] writes and what a [`Bundle`] implementation
/// builds its components into. A type of the caller's own is the usual way to
/// spawn an object; reach for this one when the components are only known once
/// the program runs.
///
/// It also carries the name of the entity it will spawn, which by default is the
/// source position of the [`crate::bundle!`] that built it.
pub struct DynamicBundle {
    components: Components,
    name: &'static str,
}

impl Default for DynamicBundle {
    fn default() -> Self {
        Self::new()
    }
}

impl DynamicBundle {
    /// An empty bundle with no name, for one built by hand.
    ///
    /// [`crate::bundle!`] is what supplies a name, so a bundle filled in by
    /// hand names its entity after nothing: give it one with
    /// [`DynamicBundle::named`], or spawn it with
    /// [`ScopeMut::spawn_named`](crate::ScopeMut::spawn_named).
    pub fn new() -> Self {
        Self {
            components: Vec::new(),
            name: "",
        }
    }

    /// Name the bundle, replacing the one [`crate::bundle!`] gave it.
    ///
    /// [`crate::bundle!`] names every bundle it builds after the source
    /// position that wrote it, and a spawn gives that name to the entity. A
    /// bundle assembled at runtime has no such position to speak of, so it
    /// names itself here instead.
    #[must_use]
    pub fn named(self, name: &'static str) -> Self {
        Self {
            components: self.components,
            name,
        }
    }

    /// Add one component.
    ///
    /// The value is stored under its own type, so a tuple pushed here stays one
    /// component.
    pub fn push_component<C: 'static>(&mut self, value: C) {
        self.components.push(BundleComponent {
            type_id: TypeId::of::<C>(),
            name: core::any::type_name::<C>(),
            column: Column::<C>::eraser(),
            value: Box::new(value),
        });
    }

    /// Add every component of `bundle` to this one.
    ///
    /// This is how a caller gathers several bundles into one spawn: the
    /// components keep their own types, so a bundle that holds a tuple
    /// contributes that tuple as a single component, exactly as spawning it
    /// alone would.
    pub fn push_bundle<B: Bundle>(&mut self, bundle: B) {
        self.components.extend(bundle.into_bundle().components);
    }

    /// The components in type order.
    ///
    /// # Panics
    ///
    /// When the same component appears twice. The duplicate is caught here
    /// rather than at spawn so that every path into an archetype, queued or
    /// immediate, reports it from the call that wrote the bundle.
    #[track_caller]
    pub(crate) fn finish(self) -> Components {
        let mut components = self.components;
        sort_components(&mut components);
        components
    }
}

/// Put a bundle's components in type order, which is the order an archetype
/// stores its columns in.
///
/// # Panics
///
/// When the same component appears twice.
#[track_caller]
fn sort_components(components: &mut [BundleComponent]) {
    components.sort_unstable_by_key(|component| component.type_id);
    for pair in components.windows(2) {
        assert_ne!(
            pair[0].type_id, pair[1].type_id,
            "a bundle cannot contain the same component twice",
        );
    }
}

/// A set of components to spawn an entity with.
///
/// Implemented for a [`DynamicBundle`], which is what the [`crate::bundle!`] macro
/// produces, and for any type of a caller's own that can say what its
/// components are. It is deliberately not implemented for tuples: every
/// `'static` type is a component, so a tuple impl would make `(a, b)` mean two
/// components in one place and one component in another.
///
/// A caller's own type is the usual way to spawn an object: give it the fields
/// it is built from, and build its components in [`Bundle::into_bundle`].
///
/// ````rust
/// # use unlit_ecs::{Bundle, DynamicBundle, World, bundle};
/// struct Cube {
///     size: f32,
/// }
///
/// impl Bundle for Cube {
///     fn into_bundle(self) -> DynamicBundle {
///         bundle![self.size]
///     }
/// }
///
/// let mut world = World::new();
/// let cube = world.root_scope_mut().spawn(Cube { size: 1.0 });
/// assert!(cube.name().ends_with("::Cube"), "the entity is named after the object");
/// ````
#[diagnostic::on_unimplemented(
    message = "`{Self}` is not a bundle",
    label = "implement `Bundle` for it, or build it with `bundle!`",
    note = "`(a, b)` is a single component here: every `'static` type is one, tuples included. Write `bundle![a, b]` for two components."
)]
pub trait Bundle {
    /// The name the spawned entity takes: the bundle's own type by default.
    ///
    /// A [`DynamicBundle`] has a name of its own — the source position of the
    /// [`crate::bundle!`] that wrote it, or the label [`DynamicBundle::named`]
    /// gave it — and answers with that. A type of the caller's own has no such
    /// label to speak of, so it names the entity after itself, which is the
    /// object the entity is. A bundle that names itself after something else
    /// overrides this.
    fn name(&self) -> &'static str {
        core::any::type_name::<Self>()
    }

    /// The dynamic bundle holding exactly this bundle's components.
    ///
    /// The bundle supplies the whole bundle, so there is no target to append to
    /// or overwrite. A caller gathering several bundles into one spawn pushes
    /// each onto a [`DynamicBundle`] with [`DynamicBundle::push_bundle`].
    fn into_bundle(self) -> DynamicBundle;
}

impl Bundle for DynamicBundle {
    fn name(&self) -> &'static str {
        self.name
    }

    fn into_bundle(self) -> DynamicBundle {
        self
    }
}

/// Builds a bundle from the components written between the brackets.
///
/// The items are components, separated by commas: `bundle![a, b]` is two
/// components. A list of one needs no comma, so `bundle![a]` is the single
/// component `a`. An item is one component however it is written, because every
/// `'static` type is one: `bundle![(a, b)]` names a single tuple component, and
/// `bundle![()]` a single empty-tuple one.
///
/// The macro is written with brackets, `bundle![a, b]`, throughout this crate
/// and its dependents. Rust accepts any of the three delimiters after the `!`,
/// so the brackets are a convention that keeps a bundle's items, which are not
/// call arguments, visibly distinct.
///
/// ````rust
/// # use unlit_ecs::{Has, World, bundle};
/// let mut world = World::new();
/// let entity = world.root_scope_mut().spawn(bundle![1u32, 2.0f32, true]);
/// assert!(world.root_scope().query_one::<Has<u32>>(entity).unwrap().get());
/// assert!(world.root_scope().query_one::<Has<f32>>(entity).unwrap().get());
/// assert!(world.root_scope().query_one::<Has<bool>>(entity).unwrap().get());
///
/// // A tuple is one component.
/// let entity = world.root_scope_mut().spawn(bundle![(1u8, 2u8)]);
/// assert!(world.root_scope().query_one::<Has<(u8, u8)>>(entity).unwrap().get());
/// assert!(!world.root_scope().query_one::<Has<u8>>(entity).unwrap().get());
/// ````
///
/// A bundle written as `..value` is unwrapped into its own components, the way
/// spawning it alone would. The syntax is needed because the macro walks the
/// source and cannot tell a bundle from a component; written plainly, a bundle
/// is one component.
///
/// ````rust
/// # use unlit_ecs::{DynamicBundle, Has, World, bundle};
/// let mut gathered = DynamicBundle::new();
/// gathered.push_component(1u32);
/// let mut world = World::new();
/// let entity = world.root_scope_mut().spawn(bundle![..gathered, true]);
/// assert!(world.root_scope().query_one::<Has<u32>>(entity).unwrap().get());
/// assert!(world.root_scope().query_one::<Has<bool>>(entity).unwrap().get());
/// ````
///
/// The width is bounded by the compiler's recursion limit rather than by a
/// fixed count: each item costs a level of macro recursion, so roughly a
/// hundred components fit at the default limit of 128. A wider bundle is built
/// by raising `#![recursion_limit]` in the calling crate, or by pushing onto
/// a [`DynamicBundle`] directly.
///
/// A type that appears twice panics when the bundle is spawned.
#[macro_export]
macro_rules! bundle {
    [] => { $crate::DynamicBundle::new().named(concat!(file!(), ":", line!())) };
    // A bundle written as `..value`, unwrapped into its own components. It is
    // matched before the `$leaf:expr` arms because `..value` is not an
    // expression.
    [@list $bundle:ident, ..$spread:expr, $($rest:tt)*] => {
        $bundle.push_bundle($spread);
        $crate::bundle![@list $bundle, $($rest)*];
    };
    [@list $bundle:ident, ..$spread:expr] => { $bundle.push_bundle($spread) };
    // One component. It is matched opaquely, so a tuple is one component and a
    // group is never taken apart.
    [@list $bundle:ident, $leaf:expr, $($rest:tt)*] => {
        $bundle.push_component($leaf);
        $crate::bundle![@list $bundle, $($rest)*];
    };
    [@list $bundle:ident,] => {};
    [@list $bundle:ident, $leaf:expr] => { $bundle.push_component($leaf) };
    [$($item:tt)+] => {{
        let mut bundle = $crate::DynamicBundle::new().named(concat!(file!(), ":", line!()));
        $crate::bundle![@list bundle, $($item)+];
        bundle
    }};
}

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

    /// Gathering bundles keeps each one's own components: a bundle's leaves are
    /// its own, and a component pushed whole that is itself a tuple stays one
    /// component.
    #[test]
    fn push_bundle_gathers_bundles() {
        let mut world = World::new();
        let mut bundle = DynamicBundle::new();
        bundle.push_component(1u32);
        bundle.push_bundle(crate::bundle![2.0f32, true]);
        bundle.push_component((7u8, 8u8));
        let entity = world.root_scope_mut().spawn(bundle);
        assert_eq!(
            world
                .root_scope()
                .query_one::<&u32>(entity)
                .map(|mut value| *value.get()),
            Ok(1)
        );
        assert_eq!(
            world
                .root_scope()
                .query_one::<&f32>(entity)
                .map(|mut value| *value.get()),
            Ok(2.0)
        );
        assert_eq!(
            world
                .root_scope()
                .query_one::<&bool>(entity)
                .map(|mut value| *value.get()),
            Ok(true)
        );
        // The pair went in as one component, the way spawning it alone would
        // have.
        assert_eq!(
            world
                .root_scope()
                .query_one::<&(u8, u8)>(entity)
                .map(|mut value| *value.get()),
            Ok((7, 8))
        );
    }

    /// A duplicate is reported by the call that finishes the bundle, whether it
    /// was written twice in one list or gathered from a spread.
    #[test]
    #[should_panic(expected = "same component twice")]
    fn a_duplicate_panics_when_the_bundle_is_finished() {
        let mut bundle = DynamicBundle::new();
        bundle.push_component(1u32);
        bundle.push_bundle(crate::bundle![2u32]);
        bundle.finish();
    }

    /// A wide bundle still finishes in type order, each component whole.
    #[test]
    fn a_wide_bundle_finishes_in_type_order() {
        let mut bundle = DynamicBundle::new();
        bundle.push_component(1u8);
        bundle.push_component(2u16);
        bundle.push_component(3u32);
        bundle.push_component(4u64);
        bundle.push_component(5i8);
        bundle.push_component(6i16);
        bundle.push_component(7i32);
        bundle.push_component(8i64);
        bundle.push_component(9.0f32);
        bundle.push_component(10.0f64);
        let finished = bundle.finish();
        assert_eq!(finished.len(), 10);
        assert!(
            finished
                .windows(2)
                .all(|pair| pair[0].type_id < pair[1].type_id),
            "the components come out in type order",
        );
    }
}