Module format 

Data structures for the chunk persistence format.

Format Overview

Region files use a sector-based format with a fixed header for fast random access:

┌─────────────────────────────────────────────────────┐
│ Magic (4 bytes): "STLR"                             │
│ Version (2 bytes): u16                              │
│ Padding (2 bytes): reserved                         │
├─────────────────────────────────────────────────────┤
│ Header: 1024 entries × 8 bytes = 8KB                │
│   Each entry: offset (u32) + size (u24) + flags (u8)│
├─────────────────────────────────────────────────────┤
│ Chunk data in 4KB sectors                           │
│   [chunk data padded to 4KB boundary]               │
│   [chunk data padded to 4KB boundary]               │
│   ...                                               │
└─────────────────────────────────────────────────────┘

Design

Each chunk stores its own block state and biome palettes, making chunks self-contained and avoiding expensive region-wide table rebuilds.

Block data uses power-of-2 bit packing (1, 2, 4, 8, 16 bits) to avoid entries spanning u64 boundaries.

Structs

ChunkEntry

Entry in the chunk location table.

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.

RegionHeader

Region header containing chunk location table.

RegionPos

Position of a region in region coordinates.

Enums

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