khora_data/ecs/

bundle.rs

// Copyright 2025 eraflo
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

use std::any::TypeId;
use std::collections::HashMap;

use crate::ecs::component::Component;
use crate::ecs::entity::EntityMetadata;
use crate::ecs::page::{AnyVec, ComponentPage, PageIndex};
use crate::ecs::registry::ComponentRegistry;

/// A trait for any collection of components that can be spawned together as a single unit.
///
/// This is a key part of the ECS's public API. It is typically implemented on tuples
/// of components, like `(Position, Velocity)`. It provides the logic for identifying
/// its component types and safely writing its data into a `ComponentPage`.
pub trait ComponentBundle {
    /// Returns the sorted list of `TypeId`s for the components in this bundle.
    ///
    /// This provides a canonical "signature" for the bundle, which is used to find
    /// a matching `ComponentPage` in the `World`. Sorting is crucial to ensure that
    /// tuples with the same components but in a different order (e.g., (A, B) vs (B, A))
    /// are treated as identical.
    fn type_ids() -> Vec<TypeId>;

    /// Creates the set of empty, type-erased `Vec<T>` columns required to store
    /// this bundle's components.
    ///
    /// This is called by the `World` when a new `ComponentPage` needs to be
    /// created for a specific bundle layout.
    fn create_columns() -> HashMap<TypeId, Box<dyn AnyVec>>;

    /// Updates the appropriate fields in an `EntityMetadata` struct to point
    /// to the location of this bundle's data.
    ///
    /// This method is called by `World::spawn` to link an entity to its newly
    /// created component data.
    fn update_metadata(
        metadata: &mut EntityMetadata,
        location: PageIndex,
        registry: &ComponentRegistry,
    );

    /// Adds the components from this bundle into the specified `ComponentPage`.
    ///
    /// # Safety
    /// This function is unsafe because it relies on the caller to guarantee that
    /// the `ComponentPage` is the correct one for this bundle's exact component layout.
    /// It performs unsafe downcasting to write to the type-erased `Vec<T>`s.
    unsafe fn add_to_page(self, page: &mut ComponentPage);
}

/// Implementation for the empty tuple, allowing spawning of empty entities.
impl ComponentBundle for () {
    fn type_ids() -> Vec<TypeId> {
        Vec::new()
    }

    fn create_columns() -> HashMap<TypeId, Box<dyn AnyVec>> {
        HashMap::new()
    }

    fn update_metadata(
        _metadata: &mut EntityMetadata,
        _location: PageIndex,
        _registry: &ComponentRegistry,
    ) {
        // No components, so no location information to update.
    }

    unsafe fn add_to_page(self, _page: &mut ComponentPage) {
        // No components to add, so this is a no-op.
    }
}

// Implementation for a single component.
impl<C1: Component> ComponentBundle for C1 {
    fn type_ids() -> Vec<TypeId> {
        // The signature is just the TypeId of the single component.
        vec![TypeId::of::<C1>()]
    }

    fn create_columns() -> HashMap<TypeId, Box<dyn AnyVec>> {
        let mut columns: HashMap<TypeId, Box<dyn AnyVec>> = HashMap::new();
        // Route through the component's layout hook (AoS by default, field-SoA
        // when opted in) — the column type is the component's choice.
        columns.insert(TypeId::of::<C1>(), C1::make_column());
        columns
    }

    fn update_metadata(
        metadata: &mut EntityMetadata,
        location: PageIndex,
        registry: &ComponentRegistry,
    ) {
        // Find the domain for this component type in the registry.
        if let Some(domain) = registry.get_domain(TypeId::of::<Self>()) {
            // Insert or update the location for that domain.
            metadata.locations.insert(domain, location);
        }
        // Note: We might want to log a warning here if a component is not registered.
    }

    unsafe fn add_to_page(self, page: &mut ComponentPage) {
        let column = page.columns.get_mut(&TypeId::of::<C1>()).unwrap().as_mut();
        self.push_into_column(column);
    }
}

// Implementation for tuples of components.
// We use a macro to handle various tuple sizes efficienty, following the
// same architectural patterns as `WorldQuery`.
macro_rules! impl_bundle_tuple {
    ($(($C:ident, $idx:tt)),*) => {
        impl<$($C: Component),*> ComponentBundle for ($($C,)*) {
            fn type_ids() -> Vec<TypeId> {
                let mut ids = vec![$(TypeId::of::<$C>()),*];
                ids.sort();
                ids.dedup();
                ids
            }

            fn create_columns() -> HashMap<TypeId, Box<dyn AnyVec>> {
                let mut columns: HashMap<TypeId, Box<dyn AnyVec>> = HashMap::new();
                $(
                    columns.insert(TypeId::of::<$C>(), $C::make_column());
                )*
                columns
            }

            fn update_metadata(
                metadata: &mut EntityMetadata,
                location: PageIndex,
                registry: &ComponentRegistry,
            ) {
                $(
                    if let Some(domain) = registry.get_domain(TypeId::of::<$C>()) {
                        metadata.locations.insert(domain, location);
                    }
                )*
            }

            unsafe fn add_to_page(self, page: &mut ComponentPage) {
                $(
                    let column = page.columns.get_mut(&TypeId::of::<$C>()).unwrap().as_mut();
                    self.$idx.push_into_column(column);
                )*
            }
        }
    };
}

impl_bundle_tuple!((C1, 0), (C2, 1));
impl_bundle_tuple!((C1, 0), (C2, 1), (C3, 2));
impl_bundle_tuple!((C1, 0), (C2, 1), (C3, 2), (C4, 3));
impl_bundle_tuple!((C1, 0), (C2, 1), (C3, 2), (C4, 3), (C5, 4));
impl_bundle_tuple!((C1, 0), (C2, 1), (C3, 2), (C4, 3), (C5, 4), (C6, 5));
impl_bundle_tuple!(
    (C1, 0),
    (C2, 1),
    (C3, 2),
    (C4, 3),
    (C5, 4),
    (C6, 5),
    (C7, 6)
);
impl_bundle_tuple!(
    (C1, 0),
    (C2, 1),
    (C3, 2),
    (C4, 3),
    (C5, 4),
    (C6, 5),
    (C7, 6),
    (C8, 7)
);
impl_bundle_tuple!(
    (C1, 0),
    (C2, 1),
    (C3, 2),
    (C4, 3),
    (C5, 4),
    (C6, 5),
    (C7, 6),
    (C8, 7),
    (C9, 8)
);
impl_bundle_tuple!(
    (C1, 0),
    (C2, 1),
    (C3, 2),
    (C4, 3),
    (C5, 4),
    (C6, 5),
    (C7, 6),
    (C8, 7),
    (C9, 8),
    (C10, 9)
);
impl_bundle_tuple!(
    (C1, 0),
    (C2, 1),
    (C3, 2),
    (C4, 3),
    (C5, 4),
    (C6, 5),
    (C7, 6),
    (C8, 7),
    (C9, 8),
    (C10, 9),
    (C11, 10)
);
impl_bundle_tuple!(
    (C1, 0),
    (C2, 1),
    (C3, 2),
    (C4, 3),
    (C5, 4),
    (C6, 5),
    (C7, 6),
    (C8, 7),
    (C9, 8),
    (C10, 9),
    (C11, 10),
    (C12, 11)
);