chunky_bevy/

lib.rs

//! A simple and efficient chunk management system for Bevy.
//!
//! # Quick Start
//!
//! ```no_run
//! use bevy::prelude::*;
//! use chunky_bevy::prelude::*;
//!
//! fn main() {
//!     App::new()
//!         .add_plugins(DefaultPlugins)
//!         .add_plugins(ChunkyPlugin::default())
//!         .add_systems(Startup, setup)
//!         .run();
//! }
//!
//! fn setup(mut commands: Commands) {
//!     // Spawn a chunk loader that generates chunks around it
//!     commands.spawn((
//!         Transform::default(),
//!         ChunkLoader(IVec3::new(2, 1, 2)), // Load 5x3x5 chunks
//!     ));
//! }
//! ```
//!
//! # Features
//!
//! - `chunk_visualizer` (default) - Enables debug visualization of chunk boundaries
//! - `chunk_loader` (default) - Enables automatic chunk loading around ChunkLoader entities
//! - `chunk_info` - Logs chunk spawn/despawn events

#[cfg(feature = "chunk_loader")]
mod chunk_loader;
#[cfg(feature = "chunk_saver")]
mod chunk_saver;
#[cfg(feature = "chunk_unloader")]
mod chunk_unloader;
#[cfg(feature = "chunk_visualizer")]
mod chunk_visualizer;

/// Utility functions for spawning chunks in bulk
pub mod helpers;

use bevy::{
    ecs::{lifecycle::HookContext, world::DeferredWorld},
    prelude::*,
};
use std::collections::HashMap;

/// Re-exports of commonly used types
pub mod prelude {
    #[cfg(feature = "chunk_loader")]
    pub use crate::chunk_loader::ChunkLoader;
    #[cfg(feature = "chunk_saver")]
    pub use crate::chunk_saver::{
        ChunkDataRegistry, ChunkSaveConfig, ChunkSavingPlugin, RegisterChunkData, SaveError,
        SaveStyle,
    };
    #[cfg(all(feature = "chunk_unloader", feature = "chunk_loader"))]
    pub use crate::chunk_unloader::ChunkUnloadRadius;
    #[cfg(feature = "chunk_unloader")]
    pub use crate::chunk_unloader::{
        ChunkLastAccess, ChunkPinned, ChunkUnloadByDistance, ChunkUnloadEvent, ChunkUnloadLimit,
        ChunkUnloadReason,
    };
    #[cfg(feature = "chunk_visualizer")]
    pub use crate::chunk_visualizer::ChunkBoundryVisualizer;
    pub use crate::{Chunk, ChunkManager, ChunkPos, ChunkyPlugin};
}

/// The main plugin for chunk management.
///
/// # Example
///
/// ```no_run
/// use bevy::prelude::*;
/// use chunky_bevy::ChunkyPlugin;
///
/// App::new()
///     .add_plugins(ChunkyPlugin::default()) // 10x10x10 chunks
///     .run();
/// ```
pub struct ChunkyPlugin {
    pub chunk_size: Vec3,
}

impl Plugin for ChunkyPlugin {
    fn build(&self, app: &mut App) {
        app.insert_resource(ChunkManager::new(self.chunk_size));
        #[cfg(feature = "chunk_loader")]
        app.add_plugins(chunk_loader::ChunkLoaderPlugin);
        #[cfg(feature = "chunk_visualizer")]
        app.add_plugins(chunk_visualizer::ChunkBoundryVisualizerPlugin);
        #[cfg(feature = "chunk_unloader")]
        app.add_plugins(chunk_unloader::ChunkUnloaderPlugin);
        #[cfg(feature = "reflect")]
        app.register_type::<ChunkPos>()
            .register_type::<ChunkManager>();
    }
}

impl ChunkyPlugin {
    pub fn new(chunk_size: Vec3) -> Self {
        Self { chunk_size }
    }

    /// Standard 3D chunk configuration with 10x10x10 sized chunks
    pub const THREE_DIMETION: Self = Self {
        chunk_size: vec3(10.0, 10.0, 10.0),
    };
}

impl Default for ChunkyPlugin {
    fn default() -> Self {
        Self::THREE_DIMETION
    }
}

/// Marks an entity as a chunk.
///
/// This component automatically:
/// - Registers the chunk with the [`ChunkManager`] when added
/// - Unregisters the chunk when removed
/// - Requires [`ChunkPos`] and [`Visibility`] components
///
/// # Example
///
/// ```no_run
/// use bevy::prelude::*;
/// use chunky_bevy::prelude::*;
///
/// fn spawn_chunk(mut commands: Commands) {
///     commands.spawn((
///         Chunk,
///         ChunkPos(IVec3::new(0, 0, 0)),
///     ));
/// }
/// ```
#[derive(Component)]
#[require(ChunkPos, Visibility)]
#[component(
    immutable,
    on_add= on_add_chunk,
    on_remove = on_remove_chunk
)]
pub struct Chunk;

/// Registers the chunk with [`ChunkManager`] when added.
fn on_add_chunk(mut world: DeferredWorld, HookContext { entity, .. }: HookContext) {
    let chunk_pos = world.get::<ChunkPos>(entity).unwrap().0;
    let mut chunk_manager = world.get_resource_mut::<ChunkManager>().unwrap();
    if chunk_manager.is_loaded(&chunk_pos) {
        warn!(
            "New chunk at pos:{} was not spawned there was already a chunk there",
            chunk_pos
        );
        return;
    }

    chunk_manager.insert(chunk_pos, entity);

    #[cfg(feature = "chunk_info")]
    info!("[ChunkInfo]ChunkPos: {chunk_pos:?}");
}

/// Unregisters the chunk from [`ChunkManager`] when removed.
fn on_remove_chunk(mut world: DeferredWorld, HookContext { entity, .. }: HookContext) {
    let chunk_pos = world.get::<ChunkPos>(entity).unwrap().0;
    world
        .get_resource_mut::<ChunkManager>()
        .unwrap()
        .remove(&chunk_pos);
}

/// The position of a chunk in chunk-space coordinates.
///
/// When added to an entity, automatically updates the entity's [`Transform`]
/// to match the chunk's world position.
///
/// # Example
///
/// ```no_run
/// use bevy::prelude::*;
/// use chunky_bevy::prelude::*;
///
/// fn spawn_chunk(mut commands: Commands) {
///     // Spawns a chunk at chunk position (5, 0, 3)
///     // With default 10x10x10 chunks, this will be at world position (50, 0, 30)
///     commands.spawn((
///         Chunk,
///         ChunkPos(IVec3::new(5, 0, 3)),
///     ));
/// }
/// ```
#[derive(Component, Default, Deref, DerefMut)]
#[cfg_attr(feature = "reflect", derive(Reflect))]
#[cfg_attr(feature = "reflect", reflect(Component))]
#[require(Transform)]
#[component(
    immutable,
    on_add= on_add_chunk_pos,
)]
pub struct ChunkPos(pub IVec3);

/// Sets the entity's [`Transform`] translation based on chunk position and size.
fn on_add_chunk_pos(mut world: DeferredWorld, HookContext { entity, .. }: HookContext) {
    let chunk_pos = world.get::<ChunkPos>(entity).unwrap();
    let chunk_size = world.get_resource::<ChunkManager>().unwrap().chunk_size;
    let translation = chunk_pos.as_vec3() * chunk_size;
    world.get_mut::<Transform>(entity).unwrap().translation = translation;
}

/// Resource for managing all chunks in the world.
///
/// Provides methods to query chunks by position and convert between
/// world positions and chunk positions.
///
/// # Example
///
/// ```no_run
/// use bevy::prelude::*;
/// use chunky_bevy::prelude::*;
///
/// fn check_chunk(
///     chunk_manager: Res<ChunkManager>,
///     player_pos: Vec3,
/// ) {
///     // Get the chunk position the player is in
///     let chunk_pos = chunk_manager.get_chunk_pos(&player_pos);
///     
///     // Check if that chunk is loaded
///     if chunk_manager.is_loaded(&chunk_pos) {
///         println!("Player is in a loaded chunk!");
///     }
/// }
/// ```
#[derive(Resource, Default)]
#[cfg_attr(feature = "reflect", derive(Reflect))]
#[cfg_attr(feature = "reflect", reflect(Resource))]
pub struct ChunkManager {
    chunk_size: Vec3,
    chunks: HashMap<IVec3, Entity>,
}

impl ChunkManager {
    /// Creates a new chunk manager with the specified chunk size.
    pub fn new(chunk_size: Vec3) -> Self {
        Self {
            chunk_size,
            chunks: default(),
        }
    }

    /// Returns the size of chunks in world units.
    pub fn get_size(&self) -> Vec3 {
        self.chunk_size
    }

    /// Inserts a new chunk into the manager.
    ///
    /// Returns the previous chunk entity if one already existed at this position.
    ///
    /// Note: Called automatically when a [`Chunk`] component is added.
    pub fn insert(&mut self, pos: IVec3, id: Entity) -> Option<Entity> {
        self.chunks.insert(pos, id)
    }

    /// Removes a chunk from the manager.
    ///
    /// Returns the chunk's entity if it existed.
    ///
    /// Note: Called automatically when a [`Chunk`] component is removed.
    pub fn remove(&mut self, pos: &IVec3) -> Option<Entity> {
        self.chunks.remove(pos)
    }

    /// Converts world coordinates into chunk position.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use bevy::prelude::*;
    /// use chunky_bevy::prelude::*;
    ///
    /// fn example(chunk_manager: Res<ChunkManager>) {
    ///     let world_pos = Vec3::new(15.0, 5.0, 23.0);
    ///     let chunk_pos = chunk_manager.get_chunk_pos(&world_pos);
    ///     // With default 10x10x10 chunks, this returns IVec3(1, 0, 2)
    /// }
    /// ```
    pub fn get_chunk_pos(&self, pos: &Vec3) -> IVec3 {
        (*pos / self.chunk_size).floor().as_ivec3()
    }

    /// Gets the chunk entity at the specified chunk position if it exists.
    pub fn get_chunk(&self, chunk_pos: &IVec3) -> Option<Entity> {
        self.chunks.get(chunk_pos).copied()
    }

    /// Gets the chunk entity at the specified world position if it exists.
    pub fn get_chunk_form_pos(&self, pos: &Vec3) -> Option<Entity> {
        self.get_chunk(&self.get_chunk_pos(pos))
    }

    /// Checks if a chunk is loaded at the specified chunk position.
    pub fn is_loaded(&self, chunk_pos: &IVec3) -> bool {
        self.chunks.contains_key(chunk_pos)
    }
}