leafanvil-ADR-004: PumpkinMC Pure-Rust .lca Codec (lca-format), Direct SectionFrame Bridge, Cross-Language Golden Fixture Suite & Performance Proof Contract¶
- Status: Accepted
- Date: 2026-11-11
- Scope:
:resource:LeafAnvil(docs/adr/,docs/dev/SUPPORT_MATRIX.md),:anvil-api(io.github.dailystruggle.anvil.LcaGoldenFixtureExporter,LcaGoldenFixtureTest), & external Rust target (Pumpkin-MC/Pumpkincrates/pumpkin-world+lca-format) - Related ADRs & Specs:
leafanvil-ADR-001,leafanvil-ADR-002,leafanvil-ADR-003,anvil-api-ADR-002,anvil-api-ADR-003,leafrtp-ADR-072,LCA-ICD-1.0(api/anvil-api/docs/ICD.md)
Context¶
On JVM servers (Paper, Folia, Spigot, Fabric, and NeoForge), LeafAnvil (leafanvil-ADR-001) intercepts net.minecraft.world.level.chunk.storage.RegionFileStorage at runtime and pairs with leafanvil-ADR-002's in-memory (baseFrame, dirtyOverlay) representation to read and write .lca (LeafCraft Anvil, LCA-ICD-1.0) region archives without intermediate Anvil NBT translation on the hot voxel path.
PumpkinMC (Pumpkin-MC/Pumpkin) is a native Rust Minecraft server implementation with no JVM. Its world storage engine (crates/pumpkin-world) selects region storage formats via pumpkin.toml:
[world.chunk]
type = "lca" # alongside "pump", "anvil" (.mca), and "linear" (.linear)
PumpkinMC's existing storage backends exhibit three limitations when operating in multi-platform server ecosystems or under random-access chunk workloads:
- Zero Cross-Platform World Portability with
.pump: PumpkinMC's custom.pumpformat cannot be opened directly by Paper, Folia, Fabric, NeoForge, or external map/forensics tools (LeafMap,LeafShard,LeafRTP) without an offline full-world conversion pass. - Whole-Region / Multi-Chunk Bucket Write & Cold-Read Amplification in
.linearand.pump: Whole-regionZstdarchives (.linear) and multi-chunk bucketed stores must decompress and recompress entire region/bucket frames (200 KiB–5 MiB) to read a single cold chunk or flush a single modified chunk, causing severe tail-latency spikes during random teleports (REQ-RTP-S-005) and incremental saves. - Full-Chunk Anvil NBT Serialization Overhead in
.mca: Vanilla.mca(Zlib) forces every chunk load and save through full-chunk NBT compound allocation (sections,block_states.palette,block_states.dataLongArrayTagwith64-bitword-boundary padding rules,biomes,SkyLight,BlockLight), even when only terrain elevation or a single $16^3$ section is needed.
Because .lca (LCA-ICD-1.0, formatVersion = 0x0002) is a language-neutral, big-endian binary specification built on fixed-width bitfields, Extended Hamming (72, 64) SEC-DED codes, 256 B Copy-on-Write (CoW) slabs, 3D Hilbert/YZX curves, Delta-Roaring containers, and 4-bitplane Gray-code light, it maps directly to zero-copy Rust slices and SIMD-friendly integer primitives.
Decision¶
1. Pure-Rust lca-format Crate & Direct SectionFrame Bridge Architecture (REQ-RTP-S-005)¶
We standardize a Direct SectionFrame Bridge between a standalone, zero-JVM pure-Rust .lca codec crate (lca-format) and crates/pumpkin-world, matching the Tier 2 zero-NBT-round-trip architecture of leafanvil-ADR-002:
graph LR
subgraph Java Reference Codec [:anvil-api]
MCA[real 1_20..26_3 r.0.0.mca] --> EXP[LcaGoldenFixtureExporter]
SYN[Synthetic All-Modes Builder] --> EXP
EXP --> GA[Golden .lca Mode A / B]
EXP --> CBIT[CBIT T1..T8 & SEC-DED Vectors]
EXP --> MAN[lca-golden-manifest.json]
end
subgraph PumpkinMC Rust Target [crates/pumpkin-world + lca-format]
GA --> RC[lca-format Rust Crate]
CBIT --> RC
MAN --> RT[Cargo Golden & Criterion Suite]
RC <--> DSB[Direct SectionFrame Bridge]
RC <--> NBT[pumpkin-nbt Residual Tail]
DSB <--> PWC[Pumpkin Chunk Sections]
NBT <--> PWC
end
1.1 Rust Crate Module Layout (lca-format in resource/LeafAnvil/rust/lca-format)¶
lca_format::layer1:64 BSuperblock ("LCA_V001"magic0x4C43415F56303031at0x00..0x07,formatVersion = 0x0002at0x08..0x09,slabShift = 8at0x1A..0x1B,dictOffsetAndLenat0x20..0x27,lodHeaderOffsetAndLen/secDedTableByteOffsetat0x28..0x2F,slabPoolBaseOffsetat0x30..0x37, and 64-bit SplitMix/XXH64headerChecksumat0x38..0x3F),8 KiBu64[1024]Atomic Pointer Directory at0x0040..0x203F(35-bitslabOffset35in256 Bunits atbits 63..29,1-bitcodec1atbit 28,20-bitexactByteLen20atbits 27..8,8-bitgeneration8atbits 7..0),1 KiBSecDed64(secDedTableByteOffset, default0x2440following the1 KiBRoot Dictionary at0x2040) Extended Hamming(72, 64)pointer syndrome verifier/healer, in-memoryCoWfree-slab bitmap allocator reconstructed from pointer and dictionary occupancy on open, and"LCA1_END"(0x4C4341315F454E44) footer canary atfileLength - 8.lca_format::layer2: Append-only Chained SharedBlockState&BiomeDictionary rooted at0x2040(8 Bsegment header:u32 segmentStateCount,u16 segmentBiomeCount,u16 usedPayloadBytes;StateEntry[]andBiomeEntry[]; optional forward-indexedpatternArenaSlicestarting with384 Bof 4-bit Canonical Huffman code lengths forlit,cmd,offfollowed by cross-chunk LZ byte patterns; downward-growing(72, 64)secDedSyndromesatcap - 8 - 1 - w; and8 BforwardnextSegmentLinkTrailernextSegmentRelSlabs32 | nextSegmentCapSlabs24 | segmentFlags8at+cap - 8), pre-seeded static tables (STATIC_CORE_STATES[160],STATIC_CORE_BIOMES[65],STATIC_CORE_PROP_SUFFIXES[128]), canonical block-state string normalizer (DataVersion < 5006"Name"/"Properties"andDataVersion >= 5006"id"/"properties"), and Mode B (LCD20x4C44) Continuous Atomic Region Dictionary synthesis.lca_format::layer3: UncompressedChunkFrameHeader(headerLen = 24 + 2 * sectionCountbytes),selfTagAndDataVersion(rawDvWordat+0x00..0x03:0x5800_0000top-6-bitCBIT T3bself-describing canary +10-bit chunkIdxatbits 25..16+16-bit chunkDataVersionatbits 15..0),u16[sectionCount]verticalsectionOffsets(0x0000empty,0x8000 | stateId15inline uniform, or order-independent relative byte offsetsectionDirEnd + ((entry16 - 1) << unitShift)), Slab-Local Micro-Palette (Part Abase blocks/biomes/templates +Part Bproperty suffixes), Mode B (codec1 = 1) wrapper (headerWords = (headerLen + 7) >>> 3bytes of Hamming(72, 64)headerSEC-DEDsyndromes followed byLCD20x4C44"LD"9-byteheader + Canonical Huffman / intra-chunk &dictPatternArenaLZ streams), and Layer 3c Residual Tail (boilerplateFlags16,MOTION_BLOCKING_NO_LEAVESZigZag/zero-run delta stream, pre-sectionChunkPatchTail0x4000, and sparse Mojang NBT slice).lca_format::layer4: $16 \times 16 \times 16$ (4,096voxel)SectionFramecodec implementing all 4 traversal curves (00:CURVE_YZX,01:CURVE_H3,10:CURVE_Y_H2,11:CURVE_XZY), 1-pass directional gradient predictor, adaptive per-state Delta-Roaring containers (00:TAG_SINGLETON,01:TAG_DELTA_RUN4|4..7|1,10:TAG_DELTA_ARRAYwithBounded240,11:TAG_BITMAPcontiguous/word-masked),blockEncodingMode = 10flat bit-packed ceiling (leafrtp-ADR-072),octreeOccupancyMask64spatial occupancy bitmask, $4 \times 4 \times 4$ Hilbert biome cells, and 4-bitplane Gray-code (g = v ^ (v >> 1)) lighting (00:ABSENT,01:CONSTANT,10:GRAY_BITPLANES,11:RAW_2048).lca_format::cbit: Continuous Built-In Test (CBIT T1..T8) tripwire verifier and 4-tierSEC-DEDself-healing engine.lca_format::pumpkin_bridge: DirectSectionFrame<->crates/pumpkin-worldbridge (LcaPumpkinBridge,PumpkinChunkData,PumpkinSubChunk,PumpkinBlockPalette,PumpkinBiomePalette,PumpkinWorldChunkConfig).
1.2 Direct SectionFrame <-> crates/pumpkin-world Bridge Contract¶
Instead of serializing and deserializing full-chunk Anvil NBT compounds, crates/pumpkin-world bridges its in-memory chunk sections directly to lca-format SectionFrame views:
/// Zero-NBT-round-trip section view mapped directly to/from Layer 4 SectionFrame (LCA-ICD-1.0 Section 7).
pub struct LcaSectionSlice<'a> {
pub section_y: i8,
pub block_palette: &'a [u32], // Region/Chunk dictionary state IDs
pub yzx_states: &'a [u16; 4096], // Or inline uniform_state_id: Option<u32>
pub biome_palette: &'a [u16],
pub biome_cells: &'a [u8; 64],
pub sky_light: LightChannelSlice<'a>,
pub block_light: LightChannelSlice<'a>,
pub octree_occupancy_mask64: u64,
}
/// Direct SectionFrame Bridge into crates/pumpkin-world ChunkStorage
pub trait LcaChunkBridge {
fn decode_from_lca_frame(
header: &ChunkFrameHeader,
sections: &[SectionFrameView<'_>],
heightmap_mbnl: &[i16; 256],
residual_nbt_tail: Option<&[u8]>,
) -> Result<PumpkinChunk, LcaCbitError>;
fn encode_to_lca_frame(
chunk: &PumpkinChunk,
dict: &mut ChainedRegionDictionary,
mode: LcaCodecMode,
) -> Result<EncodedChunkSlab, LcaEncodeError>;
}
- Read Path (Load):
- Validate Superblock (
CBIT T1"LCA_V001"+"LCA1_END"footer canary,CBIT T264-bit SplitMixheaderChecksumat0x38..0x3F) and readpointerDirectory[idx]+secDedTable[idx], healing single-bit pointer flips (Tier 1) or reverse-scanning256 Bslabs forselfTagAndDataVersion(0x5800_0000top-6-bit canary +bits 25..16chunkIdx) (Tier 2/4) on multi-bitDEDcorruption. - Slice
ChunkFrameatslabOffset35 << 8, verifyCBIT T3..T5(selfTagAndDataVersion(word & 0xFC00_0000) == 0x5800_0000and((word >>> 16) & 0x03FF) == idx,exactByteLen20within file bounds, and disjoint in-bounds order-independentsectionOffsets), and ifcodec1 == 1(Mode B), verify/healCBIT T3c(headerWordsSEC-DEDbytes atfOff + headerLen) and verifyCBIT T8(LCD20x4C44"LD"magic) before unpacking theLCD2Continuous Atomic Region Dictionary frame. - Decode the initial Slab-Local Micro-Palette (
Part A+Part BatsectionDirEnd) and, whenhasResidualNbt == 1and(boilerplateFlags16 & 0x4000) != 0(HAS_CHUNK_PATCH_TAIL), resolveChunkPatchTailbefore iteratingsectionOffsets[]so appended local palette entriesK .. K + M - 1andhasReplacementSectionOffset(0x02) overrides are active. Then decode each activeSectionFramedirectly into PumpkinMC's section palette and voxel/biome/light buffers while cross-checkingoctreeOccupancyMask64(CBIT T6b) and applying anySectionPatchvoxel/light deltas. Uniform sections (0x8000 | stateId15) populate a single-entry PumpkinMC palette in $O(1)$ without allocating a4,096-entry voxel array. - Pass only the sparse Layer 3c
residual_nbt_tail(boilerplateFlags16bit10, bounded byresidualRelEnd) topumpkin-nbtto hydrate block entities, structures, Entities, and fluid/block ticks. - Write Path (Save):
- Intern any new block states or biomes into the region's
ChainedRegionDictionary(appending a256 B-aligned continuation segment linked vianextSegmentLinkTrailerat+cap - 8with downward-growing(72, 64)secDedSyndromesif the active segment is full). - Encode dirty PumpkinMC sections directly into Layer 4
SectionFrames (or copy clean retainedSectionWireSlices verbatim perleafanvil-ADR-002Section 2.2). - Encode
boilerplateFlags16,mbnlStream, anyChunkPatchTail, and non-empty block entities, structures, and scheduled ticks (pumpkin-nbt) into the Layer 3c Residual Tail. - Write the new
ChunkFrameto a256 B-aligned Copy-on-Write (CoW) slab, updatesecDedTable[idx]andpointerDirectory[idx]with an incrementedgeneration8 = (old + 1) & 0xFF, and refresh the 64-bit SuperblockheaderChecksumat0x38..0x3F. - Configuration & CLI World Converter:
pumpkin.toml:[world.chunk] type = "lca"with optionalmode = "mode_a"(default0-LZbit-domain random access) ormode = "mode_b"(LCD20x4C44Continuous Atomic Region Dictionary storage archiver).- Pumpkin CLI converter: bidirectional offline conversion between
.lca(r.<rx>.<rz>.lca) and.pump,.mca, and.linear.
2. Cross-Language Golden Test Fixture Suite & CBIT Vector Contract (REQ-RTP-S-004, REQ-RTP-S-005)¶
To guarantee bit-exact interoperability between Java (:anvil-api / LeafAnvil) and Rust (lca-format / crates/pumpkin-world), :anvil-api provides io.github.dailystruggle.anvil.LcaGoldenFixtureExporter and LcaGoldenFixtureTest.
2.1 Canonical Golden Bundles¶
LcaGoldenFixtureExporter#generateAllGoldenBundles() deterministically generates five self-contained fixture bundles in both Mode A (codec1 = 0, 0-LZ) and Mode B (codec1 = 1, LCD2 0x4C44 Continuous Atomic Region Dictionary):
| Fixture ID | Source / Scope | DataVersion |
Key Coverage |
|---|---|---|---|
real_1_20_R1 |
anvil/real/1_20_R1/r.0.0.mca |
3465 (< 5006) |
Real MC 1.20.1 overworld chunks, legacy "Name"/"Properties" NBT palette keys, residual block entities & ticks |
real_1_21_R1 |
anvil/real/1_21_R1/r.0.0.mca |
4671 (< 5006) |
Real MC 1.21.1 overworld chunks, multi-biome $4^3$ cells, sky & block light bitplanes |
real_26_1_R1 |
anvil/real/26_1_R1/r.0.0.mca |
4788 (< 5006) |
Real MC 26.1 early snapshot chunks, deep negative-$Y$ Deepslate sections |
real_26_3_R1 |
anvil/real/26_3_R1/r.0.0.mca |
5023 (>= 5006) |
Real MC 26.3 chunks using modern "id"/"properties" palette keys (ADR-113) |
synthetic_all_modes |
Programmatic matrix builder (2 chunks: < 5006 and >= 5006) |
3953 & 5023 |
Exercises all 4 traversal curves (00..11), all 4 Delta-Roaring tags (00:SINGLETON subTag 0..3, 01:DELTA_RUN 4\|4, 5\|3, 6\|2, 7\|1, 10:DELTA_ARRAY with Bounded240, 11:BITMAP contiguous & word-masked), blockEncodingMode = 10 flat bit-packed ceiling (> 96 states), inline uniform (0x8000 \| id), empty (0x0000), and all 4 lighting modes (00:ABSENT, 01:CONSTANT, 10:GRAY_BITPLANES, 11:RAW_2048) |
2.2 Canonical 64-Bit FNV-1a Voxel, Biome & Light Parity Digests¶
Every SectionManifestEntry in lca-golden-manifest.json records four deterministic 64-bit FNV-1a (offset_basis = 0xcbf29ce484222325L, prime = 0x100000001b3L) digests over the decoded section state so any Rust or C++ decoder can verify 100% parity without diffing gigabytes of text:
1. voxelFnv1a64: Iterates y in 0..15, z in 0..15, x in 0..15 (YZX order, 4,096 voxels), hashing the UTF-8 bytes of the canonical block-state string (e.g., minecraft:stone or minecraft:oak_stairs[facing=north,half=bottom,shape=straight,waterlogged=false] with lexicographically sorted properties) followed by separator byte 0x00.
2. biomeFnv1a64: Iterates by in 0..3, bz in 0..3, bx in 0..3 (64 biome cells), hashing the UTF-8 bytes of the canonical biome identifier (e.g., minecraft:plains) followed by 0x00.
3. skyLightFnv1a64: Iterates idx in 0..2047 (2,048 packed nibble bytes in YZX order; or 0 bytes when absent), hashing each unsigned byte b & 0xFF.
4. blockLightFnv1a64: Iterates idx in 0..2047 (2,048 packed nibble bytes in YZX order; or 0 bytes when absent), hashing each unsigned byte b & 0xFF.
2.3 Deterministic CBIT T1..T8 & 4-Tier SEC-DED Fault Vectors¶
Each golden bundle exports a deterministic list of CbitVectorEntry descriptors specifying exact byte offsets and bit mutations that a conforming .lca reader must either reject cleanly (expectRejected = true, zero panic/OOM) or self-heal transparently (expectSelfHealed = true, exact voxelFnv1a64 match):
| Vector ID | Rule / Tier | Target Offset & Mutation | Required Reader Outcome |
|---|---|---|---|
CBIT_T1_MAGIC |
CBIT T1 |
Byte 0x0000 ("LCA_V001" magic byte 0x4C XOR 0xFF $\to$ 0xB3) |
Reject (expectRejected = true) |
CBIT_T1_FOOTER |
CBIT T1 |
Byte fileLen - 1 ("LCA1_END" footer canary byte 0x44 XOR 0xFF) |
Reject (expectRejected = true) |
CBIT_T2_SUPERBLOCK_CRC |
CBIT T2 |
Byte 0x000C (superblock.regionX XOR 0x01, invalidating 64-bit headerChecksum at 0x0038..0x003F) |
Reject (expectRejected = true) |
CBIT_T3_SLAB_OOB |
CBIT T3 |
Byte ptrOff (pointerDirectory[idx] MSB set to 0x7F, placing slabOffset35 << 8 past EOF) |
Reject (expectRejected = true) |
CBIT_T3B_CHUNK_IDX_MISMATCH |
CBIT T3b |
Byte frameStartA + 1 (ChunkFrame selfTagAndDataVersion bits 25..16 chunkIdx XOR 0x01) |
Reject (expectRejected = true) |
CBIT_T3C_MODE_B_DOUBLE_BIT |
CBIT T3c |
Byte frameStartB (Mode B ChunkFrame uncompressed header word 0 XOR 0x03, DED uncorrectable) |
Reject (expectRejected = true) |
CBIT_T4_FRAME_LEN_OVER_16M |
CBIT T4 |
Byte ptrOff + 5 (Mode A pointerDirectory[idx] exactByteLen20 high byte set to 0xFF, exceeding file bounds) |
Reject (expectRejected = true) |
CBIT_T5_SECTION_OFFSET_OOB |
CBIT T5 |
Byte secEntryOff (Mode A non-uniform sectionOffsets[i] high byte set to 0x7F, past ChunkFrame end) |
Reject (expectRejected = true) |
CBIT_T6_RUN_CURSOR_OVERFLOW |
CBIT T6 |
Byte firstContainerOff (non-uniform SectionFrame container header set to 0xDF, invalid TAG_BITMAP > 512 B) |
Reject (expectRejected = true) |
CBIT_T6B_OCTREE_MASK_MISMATCH |
CBIT T6b |
Byte frameStartA + nonUniformRelStart + 1 (octreeOccupancyMask64 MSB XOR 0xFF) |
Reject (expectRejected = true) |
CBIT_T7_PALETTE_INDEX_OOB |
CBIT T7 |
Byte paletteLenOff (SectionFrame paletteLen mutated to 0x00, out of bounds) |
Reject (expectRejected = true) |
CBIT_T8_MODE_B_MAGIC |
CBIT T8 |
Byte compStartB (Mode B LCD2 0x4C44 "LD" frame magic MSB 0x4C $\to$ 0xFF) |
Reject (expectRejected = true) |
SECDED_TIER1_PTR_1BIT |
Tier 1 SEC-DED |
Byte ptrOff + 7 XOR 0x01 (1-bit flip in pointerDirectory[idx] generation8 LSB, healed via secDedTable[idx]) |
Self-heal (expectSelfHealed = true) |
SECDED_TIER2_DICT_1BIT |
Tier 2 SEC-DED |
Byte 0x2048 (DICT_ROOT_OFFSET + 8) XOR 0x01 (1-bit flip in Layer 2 Root Dictionary word 1, healed via downward-growing dictSecDed) |
Self-heal (expectSelfHealed = true) |
SECDED_TIER3_MODE_B_HDR_1BIT |
Tier 3 SEC-DED |
Byte frameStartB + 4 XOR 0x01 (1-bit flip in Mode B uncompressed ChunkFrame header word 0, healed via inline headerWords SEC-DED) |
Self-heal (expectSelfHealed = true) |
SECDED_TIER4_SLAB_SCAN |
Tier 4 Slab Scan |
Byte ptrOff XOR 0x03 (2-bit DED flip in pointerDirectory[idx]; recovered via 256 B slab-pool reverse-scan of 0x5800_0000 selfTagAndDataVersion canaries) |
Self-heal (expectSelfHealed = true) |
3. Five-Axis Performance Proof Goals & Benchmark Contract¶
Any .lca implementation (:anvil-api on JVM or lca-format in PumpkinMC) must satisfy the following five quantitative performance proof gates across the real multi-version corpus (1_20_R1, 1_21_R1, 26_1_R1, 26_3_R1):
| Axis | Metric / Workload | .lca Mode A (0-LZ) Target |
.lca Mode B (LCD2 0x4C44) Target |
Baseline Comparison (.mca, .linear, .pump) |
|---|---|---|---|---|
| 1. Disk Footprint | Aggregate region byte size across 1_20_R1..26_3_R1 |
< .linear (Zstd-1) and <= 62% of .mca |
<= 52% of .mca and <= 85% of .linear / .pump |
Beats .mca (Zlib) by 38%–50% and .linear (Zstd) by 15%–36% |
| 2. Cold Random 1-Chunk Read | Single-chunk readChunkView(cx, cz) from unparsed region bytes |
>= 1.3x faster than .mca and >= 10x faster than cold .linear |
>= 5x faster than cold .linear (single-chunk LCD2 vs whole-region decompression) |
Eliminates .linear / multi-chunk .pump bucket read amplification |
| 3. Warm Random & Region Sweep | Direct SectionFrame view decode vs NBT compound construction |
>= 1.2x faster than .mca with zero NBT tag/string map allocations on voxel arrays |
Full parity with Mode A after LCD2 frame unpack |
Zero intermediate CompoundTag / LongArrayTag allocation on SectionFrame path |
| 4. Sub-Chunk $Y$-Window Probe | readTerrainProbe(cx, cz, minY=48, maxY=112) surface finder |
>= 2.0x faster than .mca full-chunk decode |
>= 1.5x faster than .mca |
Jumps via u16[N] sectionOffsets; skips 0x0000 & 0x8000 \| id sections in $O(1)$ |
5. Single-Chunk CoW Save |
saveChunkCoW (1 modified chunk in 32x32 region) |
O(1) 256 B slab append (< 50x write amplification vs .linear) |
O(1) 256 B slab append |
.linear recompresses all 1,024 chunks (~250 KiB+); .lca writes only the ~2–4 KiB delta slab |
3.1 Empirical Head-to-Head Benchmark in PumpkinMC: .lca (LcaFile) vs. Native .pump (PumpFile)¶
Measured in crates/pumpkin-world (--release profile, seed = 8675309, 400 generated overworld chunks across r.-1.-1, r.-1.0, r.0.-1, r.0.0, and 100-chunk r.0.0 microbenchmark):
| Axis | PumpkinMC Native .pump (PumpFile + ruzstd) |
LeafAnvil .lca (LcaFile Mode B 0x4C44 LCD2 + 4-Curve Delta-Roaring) |
Relative Advantage (.lca vs. .pump) |
|---|---|---|---|
1a. 4-Region Overworld Storage (400 chunks) |
4,808,704 B (12,021.8 B/chunk) |
887,328 B (2,218.3 B/chunk) |
5.42x smaller (81.5% reduction) |
1b. r.0.0 Region Storage (100 chunks) |
1,128,704 B (11,287.0 B/chunk) |
263,944 B (2,639.4 B/chunk) |
4.28x smaller (76.6% reduction) |
2. Batch Save (Rayon Parallel Encode + flush) |
282.3 µs/chunk |
122.2 µs/chunk |
2.31x faster |
3. Batch Load (Rayon Parallel Decode + ChunkData) |
28.8 µs/chunk |
18.4 µs/chunk |
1.57x faster |
4. Single-Chunk CoW Flush (10 Overwrites) |
980.2 µs |
765.5 µs (0 B file growth; FreeSlabAllocator reclaims slabs) |
1.28x faster |
| 5. Sub-Chunk $Y$-Window Surface Probe ($Y \in [64..96]$) | 181.8 µs/chunk (full-chunk ruzstd + 24 sections) |
8.2 µs/chunk ($O(1)$ sectionOffsets window jump) |
22.2x faster |
Consequences¶
Positive¶
- Zero-Conversion Cross-Platform Worlds: Server operators can move
r.<rx>.<rz>.lcaregion files directly between Paper, Folia, Spigot, Fabric, NeoForge (LeafAnvil), and PumpkinMC without offline migration tools. - Zero-NBT Voxel Path in Rust: PumpkinMC decodes and encodes $16^3$ sections directly between Rust slice views and Layer 4
SectionFrames, confiningpumpkin-nbtto sparse block entities and scheduled ticks. - Falsifiable Cross-Language Verification: Rust contributors can run
LcaGoldenFixtureExporter(-Dlca.golden.exportDir=<path>) to emit deterministic.lcabinaries,CBIT T1..T8fault vectors, andlca-golden-manifest.json64-bit FNV-1a digests for automatedcargo testvalidation.
Trade-offs & Mitigations¶
- Dual NBT Palette Key Convention (
DataVersion < 5006vs>= 5006): Minecraft26.1+(DataVersion >= 5006) uses"id"and"properties"in block-state palette entries, whereas1.20.x–1.21.xuses"Name"and"Properties". BothLcaRegionReaderandlca-formatnormalize both forms to the canonicalname[k1=v1,k2=v2]dictionary string and emit version-appropriate NBT keys when reconstructing legacy/modern NBT views.