khora_data/ecs/

world.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.

//! The heart of the CRPECS: the `World` struct.

use std::{
    any::TypeId,
    collections::{HashMap, HashSet},
};

use bincode::config;
use khora_core::{
    ecs::entity::EntityId,
    renderer::api::scene::{GpuMesh, Mesh},
};

use crate::ecs::{
    components::HandleComponent,
    entity_store::EntityStore,
    page::{ComponentPage, PageIndex},
    planner::QueryPlanner,
    query::{Query, WorldQuery},
    registry::ComponentRegistry,
    serialization::SceneMemoryLayout,
    storage::StorageManager,
    AudioListener, AudioSource, Camera, Children, Collider, Component, ComponentBundle,
    DomainBitset, GlobalTransform, MaterialComponent, Parent, QueryMut, QueryPlan, RigidBody,
    SemanticDomain, SerializedPage, Transform, TypeRegistry,
};

/// Errors that can occur when adding a component to an entity.
#[derive(Debug, PartialEq, Eq)]
pub enum AddComponentError {
    /// The specified entity does not exist or is not alive.
    EntityNotFound,
    /// The specified component type is not registered in the ECS.
    ComponentNotRegistered,
    /// The entity already has a component of the specified type.
    ComponentAlreadyExists,
}

/// Simple statistics for a semantic domain.
#[derive(Debug, Default, Clone, Copy)]
pub struct DomainStats {
    /// Total number of entities in this domain.
    pub entity_count: u32,
    /// Total number of pages allocated for this domain.
    pub page_count: u32,
}

/// A trait providing low-level access to the World for maintenance tasks.
pub trait WorldMaintenance {
    /// Cleans up an orphaned data slot in a page.
    fn cleanup_orphan_at(&mut self, location: PageIndex, domain: SemanticDomain);

    /// Vacuums a hole in a page by moving the last entity into it.
    ///
    /// # Arguments
    /// * `page_index` - The index of the page containing the hole.
    /// * `hole_row_index` - The row index of the hole to be filled.
    fn vacuum_hole_at(&mut self, page_index: u32, hole_row_index: u32);
}

/// The central container for the entire ECS, holding all entities, components, and metadata.
pub struct World {
    /// Manages entity IDs and metadata.
    pub(crate) entities: EntityStore,
    /// Manages component storage and pages.
    pub(crate) storage: StorageManager,
    /// Manages query planning and caching.
    pub(crate) planner: QueryPlanner,
    /// The type registry for serialization purposes.
    type_registry: TypeRegistry,
}

impl World {
    /// (Internal) Allocates a new or recycled `EntityId` and reserves its metadata slot.
    fn create_entity(&mut self) -> EntityId {
        self.entities.create_entity()
    }

    /// (Internal) Finds a page suitable for the given `ComponentBundle`, or creates one if none exists.
    fn find_or_create_page_for_bundle<B: ComponentBundle>(&mut self) -> u32 {
        self.storage.find_or_create_page_for_bundle::<B>()
    }

    /// (Internal) A helper function to handle the `swap_remove` logic for a single component group.
    fn remove_from_page(
        &mut self,
        entity_to_despawn: EntityId,
        location: PageIndex,
        domain: SemanticDomain,
    ) {
        let page = &mut self.storage.pages[location.page_id as usize];
        if page.entities.is_empty() {
            return;
        }

        let last_entity_in_page = *page.entities.last().unwrap();
        page.swap_remove_row(location.row_index);

        if last_entity_in_page != entity_to_despawn {
            let metadata = self.entities.get_metadata_mut(last_entity_in_page).unwrap();
            metadata.locations.insert(domain, location);
        }
    }

    /// Finds or creates a page for the given signature of component `TypeId`s.
    fn find_or_create_page_for_signature(&mut self, signature: &[TypeId]) -> u32 {
        self.storage.find_or_create_page_for_signature(signature)
    }

    /// Creates a new, empty `World` with pre-registered internal component types.
    pub fn new() -> Self {
        let mut world = Self {
            entities: EntityStore::new(),
            storage: StorageManager::new(ComponentRegistry::default()),
            planner: QueryPlanner::new(),
            type_registry: TypeRegistry::default(),
        };
        // Registration of built-in components
        world.register_component::<Transform>(SemanticDomain::Spatial);
        world.register_component::<GlobalTransform>(SemanticDomain::Spatial);
        world.register_component::<Parent>(SemanticDomain::Spatial);
        world.register_component::<Children>(SemanticDomain::Spatial);

        // Registration of render components
        world.register_component::<HandleComponent<Mesh>>(SemanticDomain::Render);
        world.register_component::<HandleComponent<GpuMesh>>(SemanticDomain::Render);
        world.register_component::<MaterialComponent>(SemanticDomain::Render);
        world.register_component::<Camera>(SemanticDomain::Render);

        // Registration of audio components
        world.register_component::<AudioSource>(SemanticDomain::Audio);
        world.register_component::<AudioListener>(SemanticDomain::Audio);

        // Registration of physics components
        world.register_component::<RigidBody>(SemanticDomain::Physics);
        world.register_component::<Collider>(SemanticDomain::Physics);
        world.register_component::<crate::ecs::KinematicCharacterController>(
            SemanticDomain::Physics,
        );

        world
    }

    /// Spawns a new entity with the given bundle of components.
    ///
    /// This is the primary method for creating entities. It orchestrates the entire process:
    /// 1. Allocates a new `EntityId`.
    /// 2. Finds or creates a suitable `ComponentPage` for the component bundle.
    /// 3. Pushes the component data into the page's columns.
    /// 4. Updates the entity's metadata to point to the new data's location.
    /// 5. Updates domain bitsets and stats for the newly created entity components.
    ///
    /// Returns the `EntityId` of the newly created entity.
    pub fn spawn<B: ComponentBundle>(&mut self, bundle: B) -> EntityId {
        // Step 1: Allocate a new EntityId.
        let entity_id = self.create_entity();

        // Step 2: Find or create a page for this bundle.
        let page_id = self.find_or_create_page_for_bundle::<B>();

        // --- Step 3: Push component data into the page. ---
        let row_index;
        {
            let page = &mut self.storage.pages[page_id as usize];
            row_index = page.entities.len() as u32;
            unsafe {
                bundle.add_to_page(page);
            }
            page.add_entity(entity_id);
        }

        // --- Step 4: Update the entity's metadata. ---
        let location = PageIndex { page_id, row_index };
        let metadata = self.entities.get_metadata_mut(entity_id).unwrap();
        B::update_metadata(metadata, location, &self.storage.registry);

        // --- Step 5: Update domain bitsets and stats for the newly created entity components. ---
        for domain in metadata.locations.keys() {
            self.storage
                .domain_bitsets
                .entry(*domain)
                .or_default()
                .set(entity_id.index);

            self.storage
                .domain_stats
                .entry(*domain)
                .or_default()
                .entity_count += 1;
        }

        entity_id
    }

    /// Despawns an entity, removing all its components and freeing its ID for recycling.
    ///
    /// This method performs the following steps:
    /// 1. Verifies that the `EntityId` is valid by checking its index and generation.
    /// 2. Removes the entity's component data from all pages where it is stored.
    /// 3. Marks the entity's metadata slot as vacant and adds its index to the free list.
    ///
    /// Returns `true` if the entity was valid and despawned, `false` otherwise.
    pub fn despawn(&mut self, entity_id: EntityId) -> bool {
        // Step 1: Validate the EntityId.
        // First, check if the index is even valid for our entities Vec.
        if entity_id.index as usize >= self.entities.len() {
            return false;
        }

        // Get the data at the slot.
        let (id_in_world, metadata_slot) = self.entities.get(entity_id.index as usize).unwrap();

        // An ID is valid if its generation matches the one in the world,
        // AND if the metadata slot is currently occupied (`is_some`).
        if id_in_world.generation != entity_id.generation || metadata_slot.is_none() {
            return false;
        }

        // --- At this point, the ID is valid. ---

        // Step 2: Take the metadata out of the slot, leaving it `None`.
        // This is what officially "kills" the entity.
        let metadata = self
            .entities
            .get_mut(entity_id.index as usize)
            .unwrap()
            .1
            .take()
            .unwrap();
        self.entities.freed_entities.push(entity_id.index);

        // --- Step 3: Iterate over the entity's component locations and remove them ---
        for (domain, location) in metadata.locations {
            self.remove_from_page(entity_id, location, domain);

            // Clear the entity's bit in the domain bitset and update stats.
            if let Some(bitset) = self.storage.domain_bitsets.get_mut(&domain) {
                bitset.clear(entity_id.index);
            }
            if let Some(stats) = self.storage.domain_stats.get_mut(&domain) {
                stats.entity_count = stats.entity_count.saturating_sub(1);
            }
        }
        true
    }

    /// Creates an iterator that queries the world for entities matching a set of components and filters.
    ///
    /// This is the primary method for reading and writing data in the ECS. The query `Q`
    /// is specified as a tuple via turbofish syntax. It can include component references
    /// (e.g., `&Position`, `&mut Velocity`) and filters (e.g., `Without<Parent>`).
    ///
    /// This method is very cheap to call. It performs an efficient search to identify all
    /// `ComponentPage`s that satisfy the query's criteria. The returned iterator then
    /// efficiently iterates over the data in only those pages.
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// // Find all entities with a `Transform` and `GlobalTransform`.
    /// for (transform, global) in world.query::<(&Transform, &GlobalTransform)>() {
    ///     // ...
    /// }
    ///
    /// // Find all root entities (those with a `Transform` but without a `Parent`).
    /// for (transform,) in world.query::<(&Transform, Without<Parent>)>() {
    ///     // ...
    /// }
    /// ```
    pub fn query<'a, Q: WorldQuery>(&'a self) -> Query<'a, Q> {
        let type_ids = Q::type_ids();

        // 1. Try to fetch the strategy plan from the cache.
        // We cache the execution logic (Native vs Transversal), not the page indices.
        let plan = {
            let cache = self.planner.query_cache.read().unwrap();
            if let Some(plan) = cache.get(&type_ids) {
                plan.clone()
            } else {
                drop(cache);
                let new_plan = self.analyze_query(&type_ids);
                let mut cache = self.planner.query_cache.write().unwrap();
                cache.insert(type_ids, new_plan.clone());
                new_plan
            }
        };

        // 2. Dynamically find matching pages for this call.
        // This ensures the query is correct even if new archetypes were created
        // in a different domain since the last call.
        let matching_page_indices =
            self.find_matching_pages(&plan.driver_signature, &Q::without_type_ids());

        // 3. Return the query with the plan and the current matching pages.
        Query::new(self, plan, matching_page_indices)
    }

    /// Creates a mutable iterator that queries the world for entities matching a set of components and filters.
    ///
    /// This method is similar to `query`, but it allows mutable access to the components.
    /// It uses the same dynamic plan re-finding to ensure thread-safe consistency.
    pub fn query_mut<'a, Q: WorldQuery>(&'a mut self) -> QueryMut<'a, Q> {
        let type_ids = Q::type_ids();

        // 1. Get strategy from cache
        let plan = {
            let cache = self.planner.query_cache.read().unwrap();
            if let Some(plan) = cache.get(&type_ids) {
                plan.clone()
            } else {
                drop(cache);
                let new_plan = self.analyze_query(&type_ids);
                let mut cache = self.planner.query_cache.write().unwrap();
                cache.insert(type_ids, new_plan.clone());
                new_plan
            }
        };

        // 2. Dynamically find pages
        let matching_page_indices =
            self.find_matching_pages(&plan.driver_signature, &Q::without_type_ids());

        // 3. Construct the iterator
        QueryMut::new(self, plan, matching_page_indices)
    }

    /// Registers a component type with a specific semantic domain.
    ///
    /// This is a crucial setup step. Before a component of type `T` can be used
    /// in a bundle, it must be registered with the world to define which semantic
    /// page group its data will be stored in.
    pub fn register_component<T: Component>(&mut self, domain: SemanticDomain) {
        self.storage.registry.register::<T>(domain);
        self.type_registry.register::<T>();
    }

    /// Analyzes a query's component signature to create an optimized execution plan.
    ///
    /// This method identifies if a query is transversal (spanning multiple domains)
    /// and selects the most efficient "Driver Domain" based on entity density.
    pub(crate) fn analyze_query(&self, type_ids: &[TypeId]) -> QueryPlan {
        let mut domains = HashSet::new();
        for type_id in type_ids {
            if let Some(domain) = self.storage.registry.get_domain(*type_id) {
                domains.insert(domain);
            }
        }

        if domains.len() <= 1 {
            // NATIVE MODE: All components belong to the same semantic domain (or none).
            // This is the fastest execution path as it avoids any cross-domain joins.
            let first_domain = domains.into_iter().next();
            let plan = QueryPlan::new(false, first_domain, HashSet::new(), type_ids.to_vec());
            return plan;
        }

        // TRANSVERSAL MODE
        // Select the domain with the highest density of entities as the driver domain.
        // Highest density = most entities per page => page_A_count * entity_B_count < page_B_count * entity_A_count
        let driver_domain = domains
            .iter()
            .min_by(|&&a, &&b| {
                let stats_a = self
                    .storage
                    .domain_stats
                    .get(&a)
                    .copied()
                    .unwrap_or_default();
                let stats_b = self
                    .storage
                    .domain_stats
                    .get(&b)
                    .copied()
                    .unwrap_or_default();
                let score_a = (stats_a.page_count as u64) * (stats_b.entity_count as u64);
                let score_b = (stats_b.page_count as u64) * (stats_a.entity_count as u64);
                score_a.cmp(&score_b)
            })
            .copied()
            .unwrap(); // Should always be Some if domains.len() > 1

        let mut peer_domains = domains;
        peer_domains.remove(&driver_domain);

        // Calculate driver signature (subset of type_ids in the driver domain)
        let mut driver_signature = Vec::new();
        for type_id in type_ids {
            if self.storage.registry.get_domain(*type_id) == Some(driver_domain) {
                driver_signature.push(*type_id);
            }
        }
        driver_signature.sort();

        // Initialize the final plan.
        // In transversal mode, the driver signature is the subset of components
        // that belong to the driver domain.
        QueryPlan::new(true, Some(driver_domain), peer_domains, driver_signature)
    }

    /// Internal helper to find pages matching a signature and filter.
    fn find_matching_pages(&self, type_ids: &[TypeId], without_type_ids: &[TypeId]) -> Vec<u32> {
        let mut matching_page_indices = Vec::new();
        'page_loop: for (page_id, page) in self.storage.pages.iter().enumerate() {
            for required_type in type_ids {
                if page.type_ids.binary_search(required_type).is_err() {
                    continue 'page_loop;
                }
            }
            for excluded_type in without_type_ids {
                if page.type_ids.binary_search(excluded_type).is_ok() {
                    continue 'page_loop;
                }
            }
            matching_page_indices.push(page_id as u32);
        }
        matching_page_indices
    }

    /// (Internal) Computes a bitset that represents the intersection of all domains
    /// involved in a transversal query. This is used to speed up joins by skipping
    /// metadata lookups for entities that are guaranteed to not satisfy the query.
    pub(crate) fn compute_query_bitset(&self, plan: &QueryPlan) -> Option<DomainBitset> {
        if plan.mode == crate::ecs::QueryMode::Native {
            return None;
        }

        let driver_domain = plan.driver_domain?;

        // Start with the driver domain's bitset.
        let mut bitset = self.storage.domain_bitsets.get(&driver_domain)?.clone();

        // Intersect with all peer domains.
        for peer_domain in &plan.peer_domains {
            if let Some(peer_bitset) = self.storage.domain_bitsets.get(peer_domain) {
                bitset.intersect(peer_bitset);
            } else {
                // If a required peer domain has NO components at all, the intersection is empty.
                return Some(DomainBitset::new());
            }
        }

        Some(bitset)
    }

    /// This operation is designed to be fast. It performs the necessary data
    /// migration to move the entity's components for the given `SemanticDomain`
    /// to a new `ComponentPage` that matches the new layout.
    ///
    /// Crucially, it does NOT clean up the "hole" left in the old page. Instead,
    /// it returns the location of the orphaned data, delegating the cleanup task
    /// to an asynchronous garbage collection system.
    ///
    /// # Returns
    ///
    /// - `Ok(Option<PageIndex>)`: On success. The `Option` contains the location of
    ///   orphaned data if a migration occurred, which should be sent to a garbage collector.
    ///   It is `None` if no migration was needed (e.g., adding to a new domain).
    /// - `Err(AddComponentError)`: If the operation failed (e.g., entity not alive,
    ///   component not registered, or component already present).
    pub fn add_component<C: Component>(
        &mut self,
        entity_id: EntityId,
        component: C,
    ) -> Result<Option<PageIndex>, AddComponentError> {
        // 1. Validate EntityId and get metadata
        let Some((id_in_world, Some(_))) = self.entities.get(entity_id.index as usize) else {
            return Err(AddComponentError::EntityNotFound);
        };

        if id_in_world.generation != entity_id.generation {
            return Err(AddComponentError::EntityNotFound);
        }

        let Some(domain) = self.storage.registry.get_domain(TypeId::of::<C>()) else {
            return Err(AddComponentError::ComponentNotRegistered);
        };

        let mut metadata = self
            .entities
            .get_mut(entity_id.index as usize)
            .unwrap()
            .1
            .take()
            .unwrap();
        let old_location_opt = metadata.locations.get(&domain).copied();

        // 2. Determine old and new page signatures
        let old_type_ids = old_location_opt.map_or(Vec::new(), |loc| {
            self.storage.pages[loc.page_id as usize].type_ids.clone()
        });
        let mut new_type_ids = old_type_ids.clone();
        new_type_ids.push(TypeId::of::<C>());
        new_type_ids.sort();
        new_type_ids.dedup();

        if new_type_ids == old_type_ids {
            self.entities.get_mut(entity_id.index as usize).unwrap().1 = Some(metadata); // Put it back
            return Err(AddComponentError::ComponentAlreadyExists);
        }

        // 3. Find or create the destination page
        let dest_page_id = self.find_or_create_page_for_signature(&new_type_ids);

        // 4. Perform the migration
        let dest_row_index;
        unsafe {
            let (src_page_opt, dest_page) = if let Some(loc) = old_location_opt {
                if loc.page_id == dest_page_id {
                    unreachable!(); // Should be caught by signature check above
                } else {
                    // This unsafe block is needed to get mutable access to two different pages
                    let all_pages_ptr = self.storage.pages.as_mut_ptr();
                    let dest_page = &mut *all_pages_ptr.add(dest_page_id as usize);
                    let src_page = &*all_pages_ptr.add(loc.page_id as usize);
                    (Some(src_page), dest_page)
                }
            } else {
                (None, &mut self.storage.pages[dest_page_id as usize])
            };

            dest_row_index = dest_page.entities.len() as u32;

            if let Some(src_page) = src_page_opt {
                let src_row = old_location_opt.unwrap().row_index as usize;
                for type_id in &old_type_ids {
                    let copier = self.storage.registry.get_row_copier(type_id).unwrap();
                    let src_col = src_page.columns.get(type_id).unwrap();
                    let dest_col = dest_page.columns.get_mut(type_id).unwrap();
                    copier(src_col.as_ref(), src_row, dest_col.as_mut());
                }
            }

            dest_page
                .columns
                .get_mut(&TypeId::of::<C>())
                .unwrap()
                .as_any_mut()
                .downcast_mut::<Vec<C>>()
                .unwrap()
                .push(component);

            dest_page.add_entity(entity_id);
        }

        // 5. Update metadata and put it back
        metadata.locations.insert(
            domain,
            PageIndex {
                page_id: dest_page_id,
                row_index: dest_row_index,
            },
        );

        // Update the domain bitset for the entity.
        self.storage
            .domain_bitsets
            .entry(domain)
            .or_default()
            .set(entity_id.index);

        self.entities.get_mut(entity_id.index as usize).unwrap().1 = Some(metadata);

        // 6. Return the old location for cleanup, without performing swap_remove
        Ok(old_location_opt)
    }

    /// Logically removes all components belonging to a specific `SemanticDomain` from an entity.
    ///
    /// This is an extremely fast, O(1) operation that only modifies the entity's
    /// metadata. It does not immediately deallocate or move any component data.
    /// The component data is "orphaned" and will be cleaned up later by a
    /// garbage collection process.
    ///
    /// This method is generic over a component `C` to determine which domain to remove.
    ///
    /// # Returns
    ///
    /// - `Some(PageIndex)`: Contains the location of the orphaned data if the
    ///   components were successfully removed. This can be sent to a garbage collector.
    /// - `None`: If the entity is not alive or did not have any components in the
    ///   specified `SemanticDomain`.
    pub fn remove_component_domain<C: Component>(
        &mut self,
        entity_id: EntityId,
    ) -> Option<PageIndex> {
        // 1. Validate the entity ID to ensure we're acting on a live entity.
        let (id_in_world, metadata_slot) = self.entities.get_mut(entity_id.index as usize)?;
        if id_in_world.generation != entity_id.generation || metadata_slot.is_none() {
            return None;
        }

        // 2. Use the registry to find the component's domain.
        let domain = self.storage.registry.get_domain(TypeId::of::<C>())?;

        // 3. Remove the location entry from the entity's metadata.
        //    `HashMap::remove` returns the value that was at that key, which is exactly what we need.
        let metadata = metadata_slot.as_mut().unwrap();
        let location = metadata.locations.remove(&domain);

        // Clear the domain bitset if a component was removed.
        if location.is_some() {
            if let Some(bitset) = self.storage.domain_bitsets.get_mut(&domain) {
                bitset.clear(entity_id.index);
            }
        }

        location
    }

    /// Gets a mutable reference to a single component `T` for a given entity.
    ///
    /// This provides direct, "random" access to a component, which can be less
    /// performant than querying but is useful for targeted modifications.
    ///
    /// # Returns
    ///
    /// `None` if the entity is not alive or does not have the requested component.
    pub fn get_mut<T: Component>(&mut self, entity_id: EntityId) -> Option<&mut T> {
        // 1. Validate the entity ID.
        let (id_in_world, metadata_opt) = self.entities.get(entity_id.index as usize).unwrap();
        if id_in_world.generation != entity_id.generation || metadata_opt.is_none() {
            return None;
        }
        let metadata = metadata_opt.as_ref().unwrap();

        // 2. Use the registry to find the component's domain and its location.
        let domain = self.storage.registry.get_domain(TypeId::of::<T>())?;
        let location = metadata.locations.get(&domain)?;

        // 3. Get the component data from the page.
        let type_id = TypeId::of::<T>();
        let page = self.storage.pages.get_mut(location.page_id as usize)?;
        let column = page.columns.get_mut(&type_id)?;
        let vec = column.as_any_mut().downcast_mut::<Vec<T>>()?;

        vec.get_mut(location.row_index as usize)
    }

    /// Gets mutable references to components of type `T` for multiple entities simultaneously.
    ///
    /// This is safer than `get_mut` in a loop because it allows retrieving multiple
    /// disjoint mutable references to components of the same type.
    ///
    /// # Returns
    ///
    /// An array of `Option<&mut T>`. If any entity is not found, does not have the component,
    /// or if there are duplicate requests for the same component instance, that entry will be `None`.
    pub fn get_many_mut<T: Component, const N: usize>(
        &mut self,
        ids: [EntityId; N],
    ) -> [Option<&mut T>; N] {
        let mut results: [Option<&mut T>; N] = std::array::from_fn(|_| None);

        let type_id = TypeId::of::<T>();
        let domain = match self.storage.registry.get_domain(type_id) {
            Some(d) => d,
            None => return results,
        };

        // 1. Collect locations and check for duplicates
        let mut locations = [(0u32, 0u32); N];
        let mut found_mask = [false; N];

        for i in 0..N {
            if let Some((stored_id, Some(metadata))) = self.entities.get(ids[i].index as usize) {
                // Ensure the EntityId matches (including generation)
                if *stored_id == ids[i] {
                    if let Some(loc) = metadata.locations.get(&domain) {
                        locations[i] = (loc.page_id, loc.row_index);
                        found_mask[i] = true;
                    }
                }
            }
        }

        // 2. Check for collisions in (page, row) to prevent aliasing
        for i in 0..N {
            if !found_mask[i] {
                continue;
            }
            for j in (i + 1)..N {
                if found_mask[j] && locations[i] == locations[j] {
                    // Collision detected: return all None for safety
                    return std::array::from_fn(|_| None);
                }
            }
        }

        // 3. Retrieve references using unsafe to bypass split_at_mut complexity.
        // SAFETY: We have verified that all (page, row) pairs are unique,
        // so we are not creating multiple mutable references to the same data.
        for i in 0..N {
            if found_mask[i] {
                let (page_id, row_index) = locations[i];
                unsafe {
                    // We can't borrow self.pages multiple times mutably in the loop,
                    // but we know the indices are disjoint or the data is disjoint.
                    let world_ptr = self as *mut Self;
                    if let Some(page) = (&mut *world_ptr).storage.pages.get_mut(page_id as usize) {
                        if let Some(column) = page.columns.get_mut(&type_id) {
                            if let Some(vec) = column.as_any_mut().downcast_mut::<Vec<T>>() {
                                results[i] = Some(vec.get_unchecked_mut(row_index as usize));
                            }
                        }
                    }
                }
            }
        }

        results
    }

    /// Gets an immutable reference to a single component `T` for a given entity.
    ///
    /// This provides direct, "random" access to a component.
    ///
    /// # Returns
    ///
    /// `None` if the entity is not alive or does not have the requested component.
    pub fn get<T: Component>(&self, entity_id: EntityId) -> Option<&T> {
        // 1. Validate the entity ID.
        let (id_in_world, metadata_opt) = self.entities.get(entity_id.index as usize).unwrap();
        if id_in_world.generation != entity_id.generation || metadata_opt.is_none() {
            return None;
        }
        let metadata = metadata_opt.as_ref().unwrap();

        // 2. Use the registry to find the component's domain and its location.
        let domain = self.storage.registry.get_domain(TypeId::of::<T>())?;
        let location = metadata.locations.get(&domain)?;

        // 3. Get the component data from the page.
        let type_id = TypeId::of::<T>();
        let page = self.storage.pages.get(location.page_id as usize)?;

        // 4. Return the immutable reference.
        let vec = page
            .columns
            .get(&type_id)?
            .as_any()
            .downcast_ref::<Vec<T>>()?;
        vec.get(location.row_index as usize)
    }

    /// Returns an iterator over all currently living `EntityId`s in the world.
    pub fn iter_entities(&self) -> impl Iterator<Item = EntityId> + '_ {
        self.entities
            .iter()
            .filter_map(|(id, metadata_opt)| metadata_opt.as_ref().map(|_| *id))
    }

    /// Serializes the entire World state using a direct memory layout strategy.
    ///
    /// This method is highly unsafe as it reads raw component memory.
    pub fn serialize_archetype(&self) -> Result<Vec<u8>, bincode::error::EncodeError> {
        let mut serialized_pages = Vec::with_capacity(self.storage.pages.len());
        for page in &self.storage.pages {
            let mut serialized_columns = HashMap::new();

            // Use the TypeRegistry to get the stable string name for each TypeId.
            let type_names: Vec<String> = page
                .type_ids
                .iter()
                .map(|id| self.type_registry.get_name_of(id).unwrap().to_string())
                .collect();

            for type_id in &page.type_ids {
                let type_name = self.type_registry.get_name_of(type_id).unwrap();
                let column = &page.columns[type_id];
                // UNSAFE: Copying raw bytes from the component vector.
                let bytes = unsafe { column.as_bytes() };
                serialized_columns.insert(type_name.to_string(), bytes.to_vec());
            }

            serialized_pages.push(SerializedPage {
                type_names,
                entities: page.entities.clone(),
                columns: serialized_columns,
            });
        }
        let layout = SceneMemoryLayout {
            entities: self.entities.entities.clone(),
            freed_entities: self.entities.freed_entities.clone(),
            pages: serialized_pages,
        };
        bincode::encode_to_vec(layout, config::standard())
    }

    /// Deserializes and completely replaces the World state from a memory layout.
    ///
    /// This method is highly unsafe as it writes raw bytes into component vectors.
    pub fn deserialize_archetype(
        &mut self,
        data: &[u8],
    ) -> Result<(), bincode::error::DecodeError> {
        let (layout, _): (SceneMemoryLayout, _) =
            bincode::decode_from_slice(data, config::standard())?;

        self.entities.entities = layout.entities;
        self.entities.freed_entities = layout.freed_entities;
        self.storage.pages.clear();

        for serialized_page in layout.pages {
            // Use the TypeRegistry to convert string names back to TypeIds.
            let type_ids: Vec<TypeId> = serialized_page
                .type_names
                .iter()
                .map(|name| {
                    self.type_registry
                        .get_id_of(name)
                        .expect("Serialized component type not registered")
                })
                .collect();

            let mut new_page = ComponentPage {
                type_ids,
                entities: serialized_page.entities,
                columns: HashMap::new(),
            };

            for (type_name, bytes) in &serialized_page.columns {
                let type_id = self.type_registry.get_id_of(type_name).unwrap();
                let constructor = self
                    .storage
                    .registry
                    .get_column_constructor(&type_id)
                    .unwrap();
                let mut column = constructor();
                // UNSAFE: Writing raw bytes into the newly created component vector.
                unsafe {
                    column.set_from_bytes(bytes);
                }
                new_page.columns.insert(type_id, column);
            }
            self.storage.pages.push(new_page);
        }

        Ok(())
    }
}

impl WorldMaintenance for World {
    fn cleanup_orphan_at(&mut self, location: PageIndex, domain: SemanticDomain) {
        let page = &mut self.storage.pages[location.page_id as usize];
        if page.entities.is_empty() || location.row_index as usize >= page.entities.len() {
            return;
        }

        let last_entity_in_page = *page.entities.last().unwrap();
        page.swap_remove_row(location.row_index);

        if let Some((_id, metadata_opt)) = self.entities.get_mut(last_entity_in_page.index as usize)
        {
            if let Some(metadata) = metadata_opt.as_mut() {
                if let Some(loc) = metadata.locations.get_mut(&domain) {
                    *loc = location;
                }
            }
        }
    }

    fn vacuum_hole_at(&mut self, page_index: u32, hole_row_index: u32) {
        // Find the domain for this page.
        // We can infer the domain from the first component type in the page.
        let domain = {
            let page = &self.storage.pages[page_index as usize];
            if let Some(first_type) = page.type_ids.first() {
                self.storage.registry.get_domain(*first_type)
            } else {
                None
            }
        };

        if let Some(domain) = domain {
            // Reuse cleanup logic, constructing a transient PageIndex.
            let location = PageIndex {
                page_id: page_index,
                row_index: hole_row_index,
            };
            self.cleanup_orphan_at(location, domain);
        }
    }
}

impl Default for World {
    /// Creates a new, empty `World` via `World::new()`.
    fn default() -> Self {
        Self::new()
    }
}