steel_core/chunk_saver/mod.rs
1//! Chunk persistence module.
2//!
3//! This module handles saving and loading chunks to/from disk using a sector-based
4//! region file format. Each region file contains a 32×32 grid of chunks.
5//!
6//! ## Format Overview
7//!
8//! Region files use a fixed 8KB header containing chunk locations, followed by
9//! 4KB-aligned sectors for chunk data. Only the header is kept in memory; chunk
10//! data is read on-demand via file seeking.
11//!
12//! ```text
13//! ┌─────────────────────────────────────────────────────┐
14//! │ Magic (4 bytes): "STLR" │
15//! │ Version (2 bytes) + Padding (2 bytes) │
16//! ├─────────────────────────────────────────────────────┤
17//! │ Header: 1024 entries × 8 bytes = 8KB │
18//! │ Each entry: offset (u32) + size (u24) + flags (u8)│
19//! ├─────────────────────────────────────────────────────┤
20//! │ Chunk data in 4KB sectors (zstd compressed) │
21//! └─────────────────────────────────────────────────────┘
22//! ```
23//!
24//! ### Key Features
25//! - **No memory duplication**: chunks are loaded directly to runtime format
26//! - **Lazy loading**: only reads chunks when needed, not entire regions
27//! - **Fast existence checks**: just read 8 bytes from header
28//! - **Per-chunk block state and biome palettes** for self-contained chunks
29//! - **Power-of-2 bit packing** for efficient storage (1, 2, 4, 8, 16 bits)
30//! - **Homogeneous section optimization** (single block type = no bit array)
31//! - **zstd compression** per-chunk for good compression ratios
32
33mod bit_pack;
34mod format;
35mod ram_only;
36mod region_manager;
37pub mod registry;
38mod storage;
39
40pub use format::*;
41pub use ram_only::*;
42pub use region_manager::*;
43pub use storage::*;