Module chunk_saver 

Chunk persistence module.

This module handles saving and loading chunks to/from disk using a sector-based region file format. Each region file contains a 32×32 grid of chunks.

Format Overview

Region files use a fixed 8KB header containing chunk locations, followed by 4KB-aligned sectors for chunk data. Only the header is kept in memory; chunk data is read on-demand via file seeking.

┌─────────────────────────────────────────────────────┐
│ Magic (4 bytes): "STLR"                             │
│ Version (2 bytes) + Padding (2 bytes)               │
├─────────────────────────────────────────────────────┤
│ Header: 1024 entries × 8 bytes = 8KB                │
│   Each entry: offset (u32) + size (u24) + flags (u8)│
├─────────────────────────────────────────────────────┤
│ Chunk data in 4KB sectors (zstd compressed)         │
└─────────────────────────────────────────────────────┘

Key Features

• No memory duplication: chunks are loaded directly to runtime format
• Lazy loading: only reads chunks when needed, not entire regions
• Fast existence checks: just read 8 bytes from header
• Per-chunk block state and biome palettes for self-contained chunks
• Power-of-2 bit packing for efficient storage (1, 2, 4, 8, 16 bits)
• Homogeneous section optimization (single block type = no bit array)
• zstd compression per-chunk for good compression ratios

Modules

bit_pack 🔒

Bit packing utilities for chunk persistence.

format 🔒

Data structures for the chunk persistence format.

ram_only 🔒

region_manager 🔒

Region file manager with seek-based chunk access.

registry

Runtime registry for world storage backends.

storage 🔒

Structs

ChunkEntry

Entry in the chunk location table.

LoadedChunk

Runtime chunk data loaded from persistence.

PersistentBlockEntity

A block entity (tile entity) stored with a chunk.

PersistentBlockState

A block state with its identifier and properties.

PersistentBoundingBox

A structure bounding box stored as six scalar coordinates.

PersistentChunk

A persistent chunk containing sections and metadata.

PersistentDesertPyramidPieceData

Persisted desert pyramid piece payload.

PersistentEntity

An entity stored with a chunk.

PersistentHeightmap

A heightmap stored with a chunk.

PersistentJigsawJunction

A persisted jigsaw junction used by Beardifier terrain adaptation.

PersistentJigsawPieceData

Steel-native persistent state for a jigsaw pool piece.

PersistentJungleTemplePieceData

Persisted jungle temple piece payload.

PersistentLightData

Chunk-owned light data stored with a chunk.

PersistentMineshaftPieceData

Persisted mineshaft piece payload.

PersistentOceanMonumentChildPiece

Persisted internal ocean monument child piece.

PersistentOceanMonumentPieceData

Persisted ocean monument building payload.

PersistentOceanMonumentRoomData

Persisted ocean monument room snapshot.

PersistentPoi

A point of interest’s occupancy state stored with a chunk.

PersistentStructurePiece

A structure piece stored with a chunk.

PersistentStructureReference

A structure reference entry stored with a chunk.

PersistentStructureStart

A structure start stored with a chunk.

PersistentSwampHutPieceData

Persisted swamp hut piece payload.

PersistentTemplatePieceData

Persisted template-backed non-jigsaw piece data.

PersistentTick

A scheduled tick stored with a chunk.

PreparedChunkSave

Prepared chunk data ready to be saved asynchronously. Created by prepare_chunk_save during the holder’s snapshot-preparation phase.

RamOnlyStorage

In-memory chunk storage.

RegionHeader

Region header containing chunk location table.

RegionManager

Manages region files with seek-based chunk access.

RegionPos

Position of a region in region coordinates.

SimpleRAMChunk

Represents a simple in-memory prepared chunk save.

Enums

ChunkStorage

Chunk storage backend.

PersistentBiomeData

Biome data for a section (4×4×4 = 64 cells).

PersistentLightSection

One persisted chunk-owned light section.

PersistentMineshaftPieceKind

Persisted piece-specific mineshaft data.

PersistentNetherFortressPieceData

Persisted piece-specific nether fortress data.

PersistentOceanMonumentChildPieceKind

Persisted ocean monument child piece variant.

PersistentPoolElement

Persisted pool element selected during jigsaw assembly.

PersistentProceduralPieceData

Persisted procedural piece data.

PersistentProcessorList

Persisted processor list holder for single pool elements.

PersistentSection

A 16×16×16 section of a chunk.

PersistentStrongholdPieceData

Persisted piece-specific stronghold data.

PersistentStrongholdSmallDoorType

Persisted stronghold door variant.

PersistentStructurePiecePayload

Persisted type-specific structure piece placement data.

PersistentTemplatePlacementAdjustment

Persisted template position adjustment.

PersistentTemplateProcessorList

Persisted processors for template-backed non-jigsaw pieces.

Constants

BIOMES_PER_SECTION

Total biome cells in a section.

BIOME_SIZE

Number of biome cells per section side (4×4×4 = 64 biomes per section).

BLOCKS_PER_SECTION

Total blocks in a section.

CHUNKS_PER_REGION

Total chunks in a region.

CHUNK_TABLE_SIZE

Size of the chunk location table (1024 entries × 8 bytes).

FILE_HEADER_SIZE

Size of the file header (magic + version + padding).

FIRST_DATA_SECTOR

First sector where chunk data can be stored. Header takes ceil(TOTAL_HEADER_SIZE / SECTOR_SIZE) = 3 sectors (8 + 8192 = 8200 bytes).

FORMAT_VERSION

Current format version. Increment when making breaking changes. v3: Added entity persistence (PersistentEntity). v4: Added scheduled tick persistence (PersistentTick). v5: Added heightmap persistence (PersistentHeightmap). v6: Added structure start and structure reference persistence. v7: Added POI persistence (PersistentPoi). v8: Added typed jigsaw piece-state persistence. v9: Added proto chunk carving mask persistence and typed packed chunk references. v10: Added template piece clip and postprocess persistence. v11: Added template piece placement adjustment persistence. v12: Added igloo template marker, placement adjustment, and postprocess persistence. v13: Split template processor persistence and added ruined-portal processors. v14: Added buried treasure procedural piece persistence. v15: Added procedural structure-piece payload persistence. v16: Added entity fall distance persistence. v17: Added entity NoGravity persistence. v18: Added entity Invulnerable persistence. v19: Added shared entity save-data persistence. v20: Added chunk-owned light section persistence. v21: Matched vanilla scheduled-tick persistence by rebuilding sub-tick order on load. v22: Preserve Vanilla pending DUMMY block entities across chunk stages.

MAX_CHUNK_SIZE

Maximum chunk size in bytes (16MB - should be plenty).

REGION_MAGIC

Magic bytes for region file identification: “STLR” (Steel Region)

REGION_SIZE

Number of chunks per region side (32×32 = 1024 chunks per region).

SECTION_SIZE

Number of blocks per section side (16×16×16 = 4096 blocks per section).

SECTOR_SIZE

Sector size in bytes (4KB, matches modern disk physical sectors).

TOTAL_HEADER_SIZE

Total header size (file header + chunk table).