Skip to content

Changelog

All notable changes to LeafAnvil are documented in this file.

[Unreleased]

Changed

  • Crash-durable .lca region close, migration, and conversion writes (anvil-api-ADR-002, anvil-api-ADR-003, leafanvil-ADR-001, REQ-RTP-S-005): Explicit LcaRegionFileStorage#close() and closeRegion(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 heal stage writes through LcaRegionWriter.writeBytesAtomicallyDurable (FileChannel#force(true) prior to ATOMIC_MOVE, offloaded via AnvilIoPool on 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 overwrote r.x.z.lca onto itself and moved it to .lca.bak or deleted it (leafanvil-ADR-001): Split legacy (.mca, .linear, .b_linear) and .lca filename patterns in LeafAnvilWorldConverter, deduplicated per-region conversion candidates, and skipped legacy files when a valid live r.x.z.lca archive already exists on disk.
  • Concurrent createIfAbsent region opens joining an in-flight read-only miss could truncate each other's newly created .lca archive, and invalidateRegionCacheState retained stale LcaRegionReader file headers (anvil-api-ADR-003): Retried single-flight openingRegions registration before creating empty archives in LcaRegionFileStorage#getOrOpenRegion and evicted LcaRegionReader CachedFileHeader entries during invalidateRegionCacheState.
  • 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#onDoesChunkExist now logs WARNING and throws UncheckedIOException instead of reporting chunks missing on I/O or corruption errors, LcaRegionFileStorage.decodeAnvilChunkPayload decodes mode 4 (LZ4Block) payloads via Lz4BlockDecoder and rejects unknown codecs or < 5-byte stream headers with IOException, and interceptWorldStorages / detachWorld restore original regionCache maps on partial attachment failure or world detach.
  • Inline # comments in config.yml silently altered parsed values and scheduler-less batch tasks ran on the calling thread (REQ-RTP-S-005): LeafAnvilConfig now strips unquoted inline # comments before parsing scalars, and LeafAnvilRuntime#runBatchTaskAsync dispatches fallback batch tasks off-thread when executed on primary or region threads.

[0.2.0] - 2026-11-11

Changed

  • Breaking Beta Format Bump to .lca Format Version 2 (0x0002) & 100% Pure-Java Packaging (anvil-api-ADR-003, LCA-ICD-1.0): Standardized on .lca format version 2 (0x0002) without legacy 0x0001 upconversion and removed shaded com.github.luben:zstd-jni native binaries from LeafAnvil and LeafAnvil-Net so both deliverables are 100% pure Java with zero JNI/native library payloads.

Added

  • .lca Format Version 2 (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 over octreeOccupancyMask64 (01:H_3 octant compaction and 00:YZX/10:Y+H_2 horizontal slab compaction), expanded TAG_SINGLETON (subTag 0..3), TAG_DELTA_RUN (4|4, 5|3, 6|2, 7|1), Word-Masked TAG_BITMAP, and Gray light planeModes8 mode 01, and implemented a pure-Java 0x4C44 (LCD2) Continuous Atomic Layer 2 Region Dictionary protected by downward-growing Extended Hamming (72, 64) SEC-DED syndromes (shrinks 1_21_R1 64-chunk regions to 272,648 B / 51.2% of .mca in Mode A, -8.9% smaller than .linear, with 25.28 us cold / 24.80 us warm Mode A 1-chunk reads).
  • In-memory .lca section coordination (LcaSectionBacking, LcaInMemoryChunkCoordinator, leafanvil-ADR-002), free MIT-licensed LeafAnvil-Net wire-only server TX + client RX artifact (:resource:LeafAnvil:leafanvil-net, LcaClientWireReceiver), and negotiated client / inter-server LCAS (0x4C434153) & LCAB (0x4C434142) wire streaming (LcaWireStreamProtocol, LcaRemoteStreamCodec, LcaBoundedSlabPool, leafanvil-ADR-003): Compact (baseFrame, dirtyOverlay) section backing with ZeroBitStorage heap eviction (MixinLevelChunkSection, MixinPalettedContainer), negotiated leafanvil:chunk_stream_handshake (LCA_NET_V1), client revisit slab cache (ClientChunkSlabCache), two-tier bounded hot/warm slab pool (LcaBoundedSlabPool), 2-byte EntryCleanAck, 4-byte/voxel EntryPatchDelta, stored-Zlib proxy framing (MixinCompressionEncoder), and full multi-loader wire-only server TX + client RX packaging in LeafAnvil-Net-<version>.jar (with on-disk NmsRegionStorageInterceptor, LeafAnvilWorldConverter, and /lca commands isolated to commercial LeafAnvil-<version>.jar).
  • Sub-chunk .lca block patching (ChunkPatchTail, HAS_CHUNK_PATCH_TAIL = 0x4000, LCA-ICD-1.0 Section 8.3) and unified RegionFileResolver#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 during readChunkView, readColumnProbe, and readTerrainProbe without 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 stale cachedParsedDict snapshot (CorruptRegionEntryException: CBIT T7: Slab-local globalStateId ... out of range): Synchronized LcaRegionWriter.LcaLiveArchive#getOrBuildParsedHeaderAndDict snapshot construction/publication and invalidated cachedParsedDict in registerNewBlockStateId, registerNewBiomeId, and rollbackDictionaryToBookmark before publishing new block-state or biome IDs.
  • Out-of-cache .lca region opens on large (16k+) world borders issued 2,050 syscalls per 1,024-chunk region and eagerly built the TreeMap free-slab allocator on read-only opens: Clean LcaLiveArchive opens now trust verified SEC-DED pointer syndromes + trailing LCA1_END canary (2 pread syscalls, 0 ch.size() calls - 8.5x-16.3x faster region open), and ensureFreeSlabPoolInitialized() defers free-slab TreeMap construction 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) and LcaRegionReader (FILE_HEADER_CACHE, raised to 4,096 headers) with lock-free Second-Chance Clock LRU promotion, coalesced headerOnlyChannelMode compact() into a single pread/pwrite pass completed prior to regionCache removal, routed removeChunk through the 4-epoch CoW grace ring, and added .lca support to AnvilRegionOccupancyCache#isOccupied.
  • ClassCastException on RegionFileStorage.regionCache implementations storing Optional<RegionFile> values: NmsRegionStorageInterceptor now inspects generic regionCache type parameters (usesOptionalCacheValues) and wraps $$LeafAnvilRfBridge instances in Optional.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 RegionFileStorage and Moonrise bytecode interceptor (NmsRegionStorageInterceptor) generating $$LeafAnvilCacheBridge (Long2ObjectLinkedOpenHashMap) and $$LeafAnvilRfBridge (RegionFile) subclasses at runtime to route region/ (STORAGE_KIND_REGION_VOXEL = 0), entities/ (STORAGE_KIND_ENTITIES = 1), and poi/ (STORAGE_KIND_POI = 2) reads, stream writes, Moonrise write(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 RegionFile cache flush/close, Moonrise nonExistingRegionFiles (LongLinkedOpenHashSet) clearing, Moonrise RegionFile field initialization (version = VERSION_NONE, info, recalculateCount, oversized, path), and live RegionFileStorage.folder dimension directory resolution supporting classic (world/, DIM-1/, DIM1/) and Minecraft 26.1+ unified dimensions/<namespace>/<dimension>/ layouts.
  • Lazy on-open .mca / .linear / .b_linear (BufferedLinear) -> .lca atomic migration (tryMigrateLegacyRegion preserving .bak backups), configurable Mode B (LCD2 0x4C44 Continuous Atomic Region Dictionary with Extended Hamming (72, 64) header parity) vs Mode A (0-LZ direct walk), reversible batch world conversion (LeafAnvilWorldConverter#convertWorldToLca and convertWorldToMca), 256B Copy-on-Write (CoW) free-slab compaction (compactOpenRegions), and 4-tier Extended Hamming (72, 64) SEC-DED + 256B slab reverse-scan + section octreeOccupancyMask64 quarantine + CoW rollback bit-rot recovery (healAndVerifyWorld).
  • Platform-neutral /leafanvil (alias /lca) CommandsAPI command 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), configurable config.yml / messages.yml feedback (REQ-RTP-S-007), and automatic extraction of the open-source MIT .lca Interface Control Document (ICD.md).
  • Continuous 8-platform statistical A/B/C benchmark and cold-restart persistence verification driver (scripts/bench_lca_multiplatform.py, 120 completed runs across Paper 26.2, Folia 26.2, Leaf 26.2 .linear, Leaf 26.2 .b_linear, Fabric 26.1.2 + C2ME, and NeoForge 26.1.2 + C2ME, plus --verify-persistence).