Crate suon_chunk 

Spatial chunk management for the Suon world.

This crate groups world positions into chunk entities and provides the runtime data needed to answer three core spatial questions:

• which chunk owns a given world-space suon_position::position::Position
• which chunk currently contains a given entity
• which floor-position pairs inside a chunk are occupied

Responsibilities

Chunks is the global registry that maps world positions to chunk entities. Chunk marks entities that act as chunk containers and automatically carries an Occupancy store. content::AtChunk is the relationship component that links an entity back to the chunk that currently contains it.

The crate treats suon_position::position::Position as the source of truth for chunk ownership. ChunkPlugin uses lifecycle observers on suon_position::position::Position to synchronize content::AtChunk and to resynchronize occupied tiles using suon_position::previous_position::PreviousPosition.

Runtime flow

A typical end-to-end flow looks like this:

1. Chunk entities are created with Chunk.
2. The world populates Chunks with the positions owned by each chunk.
3. Game entities receive a suon_position::position::Position and optionally an occupancy::occupied::Occupied marker.
4. ChunkPlugin derives content::AtChunk automatically from the current suon_position::position::Position.
5. Occupied entities register their current tile in the destination chunk’s Occupancy map.
6. When an occupied entity moves, the crate releases the previous tile and registers the new one.

Modules

• chunks: chunk registry and chunk-key derivation
• content: entity-to-chunk relationship components
• loader: placeholder resource for chunk loading orchestration
• occupancy: per-chunk blocked-tile tracking and synchronization
• terrain: per-chunk passability state synchronized from occupied tiles

At the moment, the end-to-end runtime flow is centered on Chunks, content::AtChunk, Occupancy, and terrain::Navigation.

Examples

use bevy::prelude::*;
use suon_chunk::{Chunk, ChunkPlugin, chunks::Chunks, content::AtChunk};
use suon_position::position::Position;

let mut app = App::new();
app.add_plugins(MinimalPlugins);
app.add_plugins(ChunkPlugin);

let chunk = app.world_mut().spawn(Chunk).id();
app.insert_resource(Chunks::from_iter([(Position { x: 4, y: 4 }, chunk)]));

let entity = app.world_mut().spawn(Position { x: 4, y: 4 }).id();
app.update();

let at_chunk = app.world().get::<AtChunk>(entity).unwrap();
assert_eq!(at_chunk.entity(), chunk);

Modules

chunks

Chunk registry and chunk-key utilities. Chunk ownership registry.

content

Entity relationship components that connect world content to chunks. Entity-to-chunk relationships.

loader

Chunk loading resources and future loading orchestration. Chunk loading placeholders.

occupancy

Occupancy state and synchronization systems for chunk-contained entities. Chunk-local occupancy tracking.

terrain

Terrain navigation data structures synchronized from occupied tiles. Chunk-local navigation passability tracking.

Structs

Active

Marker component for chunks or entities that are currently active.

Chunk

Marker component identifying an entity as a chunk container.

ChunkPlugin

Plugin responsible for chunk resources and chunk-local synchronization.

Inactive

Marker component for chunks or entities that are currently inactive.

Constants

CHUNK_AREA

The total number of tiles contained within the chunk.

CHUNK_EXP

The bit exponent used to define the power-of-two dimensions of a chunk.

CHUNK_MASK

A bitmask used to extract local coordinates from global positions.

CHUNK_SIZE

The number of units along a single axis of the chunk.