Changelog¶
All notable changes to LeafAnvil are documented in this file.
[Unreleased]¶
Changed¶
- Crash-durable
.lcaregion close, migration, and conversion writes (anvil-api-ADR-002,anvil-api-ADR-003,leafanvil-ADR-001,REQ-RTP-S-005): ExplicitLcaRegionFileStorage#close()andcloseRegion(rx, rz)calls now force dirty file channels to disk by default (-Dleafanvil.fsync.onClose=true) while keeping LRU cache eviction unforced (closeWithoutForce()), and lazy legacy migrations,/leafanvil convert, and/leafanvil healstage writes throughLcaRegionWriter.writeBytesAtomicallyDurable(FileChannel#force(true)prior toATOMIC_MOVE, offloaded viaAnvilIoPoolon primary/region threads) plus a JVM shutdown flush hook for archives reopened during post-disable server saves.
Fixed¶
- Re-running
/leafanvil convert(format=lca) on an already-converted world overwroter.x.z.lcaonto itself and moved it to.lca.bakor deleted it (leafanvil-ADR-001): Split legacy (.mca,.linear,.b_linear) and.lcafilename patterns inLeafAnvilWorldConverter, deduplicated per-region conversion candidates, and skipped legacy files when a valid liver.x.z.lcaarchive already exists on disk. - Concurrent
createIfAbsentregion opens joining an in-flight read-only miss could truncate each other's newly created.lcaarchive, andinvalidateRegionCacheStateretained staleLcaRegionReaderfile headers (anvil-api-ADR-003): Retried single-flightopeningRegionsregistration before creating empty archives inLcaRegionFileStorage#getOrOpenRegionand evictedLcaRegionReaderCachedFileHeaderentries duringinvalidateRegionCacheState. - Region existence I/O faults,
region-file-compression=lz4(compressionId=4) stream writes, and partial world-hook failures could lose or corrupt chunk data (anvil-api-ADR-001,leafanvil-ADR-001,REQ-RTP-S-004):NmsRegionStorageInterceptor#onDoesChunkExistnow logsWARNINGand throwsUncheckedIOExceptioninstead of reporting chunks missing on I/O or corruption errors,LcaRegionFileStorage.decodeAnvilChunkPayloaddecodes mode4(LZ4Block) payloads viaLz4BlockDecoderand rejects unknown codecs or< 5-byte stream headers withIOException, andinterceptWorldStorages/detachWorldrestore originalregionCachemaps on partial attachment failure or world detach. - Inline
#comments inconfig.ymlsilently altered parsed values and scheduler-less batch tasks ran on the calling thread (REQ-RTP-S-005):LeafAnvilConfignow strips unquoted inline#comments before parsing scalars, andLeafAnvilRuntime#runBatchTaskAsyncdispatches fallback batch tasks off-thread when executed on primary or region threads.
[0.2.0] - 2026-11-11¶
Changed¶
- Breaking Beta Format Bump to
.lcaFormat Version2(0x0002) & 100% Pure-Java Packaging (anvil-api-ADR-003,LCA-ICD-1.0): Standardized on.lcaformat version2(0x0002) without legacy0x0001upconversion and removed shadedcom.github.luben:zstd-jninative binaries fromLeafAnvilandLeafAnvil-Netso both deliverables are 100% pure Java with zero JNI/native library payloads.
Added¶
.lcaFormat Version2(0x0002) and Pure-Java Continuous Atomic Layer 2 Region Dictionary (LCD2,0x4C44) (anvil-api-ADR-003,LCA-ICD-1.0): Compacted section Delta-Roaring cursor domains overoctreeOccupancyMask64(01:H_3octant compaction and00:YZX/10:Y+H_2horizontal slab compaction), expandedTAG_SINGLETON(subTag 0..3),TAG_DELTA_RUN(4|4,5|3,6|2,7|1), Word-MaskedTAG_BITMAP, and Gray lightplaneModes8mode 01, and implemented a pure-Java0x4C44(LCD2) Continuous Atomic Layer 2 Region Dictionary protected by downward-growing Extended Hamming(72, 64)SEC-DEDsyndromes (shrinks1_21_R164-chunk regions to272,648 B/51.2%of.mcain Mode A,-8.9%smaller than.linear, with25.28 uscold /24.80 uswarm Mode A 1-chunk reads).- In-memory
.lcasection coordination (LcaSectionBacking,LcaInMemoryChunkCoordinator,leafanvil-ADR-002), freeMIT-licensedLeafAnvil-Netwire-only server TX + client RX artifact (:resource:LeafAnvil:leafanvil-net,LcaClientWireReceiver), and negotiated client / inter-serverLCAS(0x4C434153) &LCAB(0x4C434142) wire streaming (LcaWireStreamProtocol,LcaRemoteStreamCodec,LcaBoundedSlabPool,leafanvil-ADR-003): Compact(baseFrame, dirtyOverlay)section backing withZeroBitStorageheap eviction (MixinLevelChunkSection,MixinPalettedContainer), negotiatedleafanvil:chunk_stream_handshake(LCA_NET_V1), client revisit slab cache (ClientChunkSlabCache), two-tier bounded hot/warm slab pool (LcaBoundedSlabPool),2-byteEntryCleanAck,4-byte/voxelEntryPatchDelta, stored-Zlib proxy framing (MixinCompressionEncoder), and full multi-loader wire-only server TX + client RX packaging inLeafAnvil-Net-<version>.jar(with on-diskNmsRegionStorageInterceptor,LeafAnvilWorldConverter, and/lcacommands isolated to commercialLeafAnvil-<version>.jar). - Sub-chunk
.lcablock patching (ChunkPatchTail,HAS_CHUNK_PATCH_TAIL = 0x4000,LCA-ICD-1.0Section 8.3) and unifiedRegionFileResolver#patchChunkBlocks: Appends Slab-Local Micro-Palette extensions and per-section voxel, light, and heightmap patches (LcaRegionWriter#patchChunkBlocks,LcaSectionCodec#encodeChunkPatchTailBytes,AnvilReader#patchChunkInMcaBytes) with $O(1)$ residual-tail seek duringreadChunkView,readColumnProbe, andreadTerrainProbewithout full-chunk NBT decode/re-encode (leafanvil-ADR-002,leafanvil-ADR-003).
Fixed¶
- Concurrent Moonrise worker reads and dictionary growth during high-throughput generation (such as
Chunky) could publish a stalecachedParsedDictsnapshot (CorruptRegionEntryException: CBIT T7: Slab-local globalStateId ... out of range): SynchronizedLcaRegionWriter.LcaLiveArchive#getOrBuildParsedHeaderAndDictsnapshot construction/publication and invalidatedcachedParsedDictinregisterNewBlockStateId,registerNewBiomeId, androllbackDictionaryToBookmarkbefore publishing new block-state or biome IDs. - Out-of-cache
.lcaregion opens on large (16k+) world borders issued2,050syscalls per 1,024-chunk region and eagerly built theTreeMapfree-slab allocator on read-only opens: CleanLcaLiveArchiveopens now trust verifiedSEC-DEDpointer syndromes + trailingLCA1_ENDcanary (2preadsyscalls,0ch.size()calls -8.5x-16.3xfaster region open), andensureFreeSlabPoolInitialized()defers free-slabTreeMapconstruction until the first write. - Unpromoted FIFO cache eviction and concurrent read/compaction race on live region eviction: Replaced FIFO / hash-bucket eviction in
LcaRegionFileStorage(regionCache,readChannelCache) andLcaRegionReader(FILE_HEADER_CACHE, raised to4,096headers) with lock-free Second-Chance Clock LRU promotion, coalescedheaderOnlyChannelModecompact()into a singlepread/pwritepass completed prior toregionCacheremoval, routedremoveChunkthrough the 4-epochCoWgrace ring, and added.lcasupport toAnvilRegionOccupancyCache#isOccupied. ClassCastExceptiononRegionFileStorage.regionCacheimplementations storingOptional<RegionFile>values:NmsRegionStorageInterceptornow inspects genericregionCachetype parameters (usesOptionalCacheValues) and wraps$$LeafAnvilRfBridgeinstances inOptional.of(...)when required.
[0.1.0] - 2026-11-01¶
Added¶
- Unified multi-loader
.lca(LeafCraft Anvil) world save format plugin & mod (LeafAnvil-0.1.0.jar) for Paper, Folia, Spigot, Fabric, and NeoForge (leafanvil-ADR-001,anvil-api-ADR-002,anvil-api-ADR-003). - Zero-fork runtime
RegionFileStorageand Moonrise bytecode interceptor (NmsRegionStorageInterceptor) generating$$LeafAnvilCacheBridge(Long2ObjectLinkedOpenHashMap) and$$LeafAnvilRfBridge(RegionFile) subclasses at runtime to routeregion/(STORAGE_KIND_REGION_VOXEL = 0),entities/(STORAGE_KIND_ENTITIES = 1), andpoi/(STORAGE_KIND_POI = 2) reads, stream writes, Moonrisewrite(ChunkPos, ByteBuffer)writes, existence checks, clears, flushes, and closes through disk-backed.lca(LcaRegionFileStorage/LcaLiveArchive), plus startup class prewarming (prewarmAnvilClasses) for shutdown saves. - Pre-open vanilla
RegionFilecache flush/close, MoonrisenonExistingRegionFiles(LongLinkedOpenHashSet) clearing, MoonriseRegionFilefield initialization (version = VERSION_NONE,info,recalculateCount,oversized,path), and liveRegionFileStorage.folderdimension directory resolution supporting classic (world/,DIM-1/,DIM1/) and Minecraft26.1+unifieddimensions/<namespace>/<dimension>/layouts. - Lazy on-open
.mca/.linear/.b_linear(BufferedLinear) ->.lcaatomic migration (tryMigrateLegacyRegionpreserving.bakbackups), configurable Mode B (LCD20x4C44Continuous Atomic Region Dictionary with Extended Hamming(72, 64)header parity) vs Mode A (0-LZdirect walk), reversible batch world conversion (LeafAnvilWorldConverter#convertWorldToLcaandconvertWorldToMca),256BCopy-on-Write (CoW) free-slab compaction (compactOpenRegions), and 4-tier Extended Hamming(72, 64)SEC-DED +256Bslab reverse-scan + sectionoctreeOccupancyMask64quarantine +CoWrollback bit-rot recovery (healAndVerifyWorld). - Platform-neutral
/leafanvil(alias/lca)CommandsAPIcommand tree (status,convert [world=<name|all>] [format=<lca|mca>],compact [world=<name|all>],heal [world=<name|all>],reload) with single-flight async batch execution (REQ-RTP-S-005), configurableconfig.yml/messages.ymlfeedback (REQ-RTP-S-007), and automatic extraction of the open-source MIT.lcaInterface Control Document (ICD.md). - Continuous 8-platform statistical A/B/C benchmark and cold-restart persistence verification driver (
scripts/bench_lca_multiplatform.py,120completed runs across Paper26.2, Folia26.2, Leaf26.2.linear, Leaf26.2.b_linear, Fabric26.1.2+ C2ME, and NeoForge26.1.2+ C2ME, plus--verify-persistence).