Skip to content

leafanvil-ADR-001: Multi-Loader .lca World Storage Carrier, Runtime RegionFileStorage Bytecode Interception & Reversible Migration (LeafAnvil)

Context

anvil-api-ADR-003 defines the .lca (LeafCraft Anvil) binary format and provides LcaRegionReader, LcaRegionWriter, LcaSectionCodec, and LcaRegionFileStorage inside api/anvil-api. Integrating .lca into Minecraft's persistence layer (net.minecraft.world.level.chunk.storage.RegionFileStorage) across server distributions presents three technical requirements:

  1. Runtime Interception Without Server Binary Patching: Standard Paper, Folia, Spigot, Fabric, and NeoForge distributions instantiate RegionFileStorage internally during world initialization. Supporting .lca as a plugin/mod requires intercepting RegionFileStorage instances in memory rather than distributing a modified server JAR.
  2. Moonrise & Multi-Folder Storage Divergence: Each dimension maintains three separate RegionFileStorage instances (region/ for voxel chunks, entities/ for entity sections, and poi/ for points of interest). On Paper and Folia (Moonrise), chunk I/O uses RegionFile#write(ChunkPos, ByteBuffer), RegionStorageInfo, RegionFileVersion, and a cached nonExistingRegionFiles (LongLinkedOpenHashSet) miss set, whereas vanilla Fabric and NeoForge route through IOWorker and SimpleRegionStorage using RegionFile#getChunkDataInputStream(ChunkPos) and getChunkDataOutputStream(ChunkPos). Furthermore, Minecraft 26.1+ unifies dimension folders under dimensions/<namespace>/<dimension>/ alongside classic world/, DIM-1/, and DIM1/ layouts.
  3. Migration & Rollback Safety: Existing worlds require on-open migration from .mca / .linear to .lca (with .bak backups), explicit reversible batch conversion (/leafanvil convert format=mca), 256B Copy-on-Write (CoW) slab compaction (/leafanvil compact), and 4-tier Extended Hamming (72, 64) SEC-DED bit-rot recovery (/leafanvil heal) executing off the main tick thread (REQ-RTP-S-005).

Decision

Provide LeafAnvil (resource/LeafAnvil) as a multi-loader plugin and mod (LeafAnvil-<version>.jar) that binds the server's world storage (region/, entities/, poi/) to .lca (LcaRegionFileStorage) at runtime:

  1. Multi-Module Carrier Layout (ADR-126):
  2. :resource:LeafAnvil:leafanvil-common - Java 17 core (LeafAnvilConfig, LeafAnvilRuntime, LeafAnvilWorldConverter, NmsRegionStorageInterceptor, LeafAnvilCommand) depending on :server-api, :commands-api, and :anvil-api.
  3. :resource:LeafAnvil:leafanvil-paper - PaperLeafAnvilPlugin (load: STARTUP, folia-supported: true) attaching worlds on WorldInitEvent (LOWEST), WorldLoadEvent (LOWEST), and onEnable(), flushing on WorldSaveEvent and onDisable(), and detaching on WorldUnloadEvent.
  4. :resource:LeafAnvil:leafanvil-fabric - FabricLeafAnvilMod (ModInitializer) attaching ServerLevel instances on ServerLifecycleEvents.SERVER_STARTING, ServerLifecycleEvents.SERVER_STARTED, and ServerTickEvents.START_SERVER_TICK (for dynamically created dimensions), and flushing/closing on SERVER_STOPPING / SERVER_STOPPED.
  5. :resource:LeafAnvil:leafanvil-neoforge - NeoForgeLeafAnvilMod (@Mod("leafanvil")) attaching on LevelEvent.Load and ServerStartedEvent, flushing on LevelEvent.Save and ServerStoppingEvent, and detaching/closing on LevelEvent.Unload and ServerStoppedEvent.
  6. :resource:LeafAnvil:leafanvil-plugin - Shaded single-JAR assembly (LeafAnvil-<version>.jar) relocating io.github.dailystruggle under net.leaf.anvil.shaded.io.github.dailystruggle.

  7. Runtime RegionFileStorage Discovery, Bytecode Bridge & C2ME / Moonrise Supplier Interception (NmsRegionStorageInterceptor):

  8. Recursive Storage Discovery & Live Folder Resolution: NmsRegionStorageInterceptor#discoverRegionFileStorages traverses CraftWorld / ServerLevel field graphs up to depth 7 across vanilla (ChunkMap, ChunkSource, PersistentEntitySectionManager, EntityPersistentStorage, EntityStorage, PoiManager, SectionStorage, SimpleRegionStorage, IOWorker), Moonrise (RegionFileIO, DataController, ChunkTaskScheduler), and C2ME (C2MEStorageVanillaInterface -> C2MEStorageThread extending java.lang.Thread) holders with JPMS Unsafe#getObject fallback. resolveDimensionDirectory inspects the live RegionFileStorage.folder parent path so both classic (world/, DIM-1/, DIM1/) and 26.1+ dimensions/<namespace>/<dimension>/ paths bind to their on-disk directories.
  9. Runtime JVM Classfile Generation (ClassFileBuilder, Java 17 bytecode version 61):
    • $$LeafAnvilCacheBridge subclasses the server's Long2ObjectLinkedOpenHashMap (regionCache) and overrides getAndMoveToFirst(long) and get(long) to return per-region $$LeafAnvilRfBridge instances managed by CacheController (guarded by created[0] to prevent recursive put() cycles under C2ME's MixinRegionFileStorage).
    • $$LeafAnvilRfBridge subclasses net.minecraft.world.level.chunk.storage.RegionFile (or implements Linear-fork IRegionFile interfaces such as org.leavesmc.leaves.region.IRegionFile and abomination.IRegionFile) and delegates getChunkDataInputStream, getChunkDataOutputStream, Moonrise write(ChunkPos, ByteBuffer) and C2ME @Invoker("write") invokeWriteChunk(ChunkPos, ByteBuffer) (onWriteByteBuffer), doesChunkExist / hasChunk, clear, flush, close, getPath, isOversized, setOversized, getOversizedData, recalculateHeader, and getRecalculateCount to LcaRegionFileStorage.
  10. C2ME / Moonrise Worker-Pool Supplier & Stream Interception:
    • Read Path (LazyChunkNbtInputStream): LcaRegionFileStorage#getChunkDataInputStream and LcaLiveArchive#getChunkDataInputStream perform an $O(1)$ chunk-occupancy check on the I/O coordinator (C2MEStorageThread / Moonrise RegionFileIOWorker) and return a DataInputStream wrapping LazyChunkNbtInputStream, deferring .lca -> Mojang NBT decoding until the first stream read on C2ME's GlobalExecutors / Moonrise's decompression worker pool.
    • Write Path (RegionFileVersion$StreamWrapper, LCA_PREENCODED_VERSION_ID = 0x4C): Each $$LeafAnvilRfBridge is initialized with a per-handle RegionFileVersion (id = 0x4C, returned by IRegionFile#getCompressionFormat()) whose outputWrapper (RegionFileVersion$StreamWrapper<OutputStream>) wraps C2ME's RawByteArrayOutputStream in LcaPreEncodingOutputStream. When C2MEStorageThread#writeChunk schedules lambda$writeChunk$1 on C2ME's GlobalExecutors.prioritizedScheduler.executor(16) worker pool, LcaPreEncodingOutputStream#close() parses the uncompressed Mojang NBT and executes .lca ChunkFrame encoding (encodeChunkNbtForRegionSlab) on C2ME's worker thread. When lambda$writeChunk$2 subsequently invokes IRegionFile#invokeWriteChunk(ChunkPos, ByteBuffer) on C2MEStorageThread, onWriteByteBuffer detects compressionId == 0x4C and executes the $O(1)$ commitPreEncodedChunkSlab CoW slab write (< 3 us), preserving C2ME's writeFutures completion contract.
  11. Atomic Cache Swap, Pre-Open Cache Flush & Miss-Set Reset: installOnRegionFileStorage atomically swaps regionCache before flushing and closing any pre-cached vanilla/Linear RegionFile handles and clears Moonrise's nonExistingRegionFiles (LongLinkedOpenHashSet) so existing or migrated .lca files are visible on lookup.

  12. Header-Only LcaLiveArchive Residency & Bounded LRU Eviction (LcaRegionFileStorage & LcaLiveArchive):

  13. Disk-backed LcaLiveArchive instances (openLiveArchive(Path)) retain the 10,304 B (~10.1 KiB, 0x0000..0x283F) default on-disk region header prefix (64 B Superblock, 8,192 B Pointer Directory, 1,024 B default Root Shared Dictionary, and 1,024 B SEC-DED table; ~25.6 KiB total per-handle heap residency including prevChunkPointers[1024], per-chunk cache arrays, and decoded dictionary/allocator lookup structures) in heap memory (headerOnlyChannelMode = true), serving chunk reads and CoW slab writes positionally over the open FileChannel and updating LcaRegionReader.FILE_HEADER_CACHE pointers in-place (updateCachedPointer) on save.
  14. Each LcaRegionFileStorage (region/, entities/, poi/) maintains an access-ordered LRU cache of up to 512 open header-only LcaLiveArchive handles (~5.15 MiB raw header prefix bytes, or ~12.8 MiB total heap including decoded lookup arrays and handle state) plus a knownMissingRegions negative-lookup set.
  15. Evicting a region from the LRU cache calls LcaLiveArchive#closeWithoutForce(), writing the "LCA1_END" footer canary and closing the FileChannel without issuing a blocking channel.force(false) (fsync) syscall on tick/IO worker threads. Explicit fsync on flush() can be enabled via -Dleafanvil.fsync=true.

  16. Reversible Batch Conversion, Compaction & 4-Tier Self-Healing (LeafAnvilWorldConverter, LeafAnvilCommand):

  17. /leafanvil (alias /lca) exposes status, convert [world=<name|all>] [format=<lca|mca>], compact [world=<name|all>], heal [world=<name|all>], and reload via CommandsAPI (commands-api-ADR-001), executing batch disk tasks asynchronously off the main thread (REQ-RTP-S-005) behind an AtomicBoolean single-flight guard (REQ-RTP-S-007).

  18. Commercial Carrier Licensing with Open .lca Format & anvil-api Carve-Out:

  19. The LeafAnvil runtime carrier (resource/LeafAnvil, net.leaf.anvil.*, and LeafAnvil-<version>.jar) is a commercial product governed by resource/LeafAnvil/LICENSE (LicenseRef-LeafCraft-Commercial, packaged at META-INF/leafanvil/LICENSE) and guarded as a private path in scripts/pre_push_guard.py.
  20. The .lca binary format Interface Control Document (api/anvil-api/docs/ICD.md, routed from resource/LeafAnvil/docs/ICD.md and packaged directly into LeafAnvil-<version>.jar, LCA-ICD-1.0) and the io.github.dailystruggle.anvil codec library (api/anvil-api) remain licensed under the MIT License so LeafRTP, world generators, server forks, map renderers, and third-party tools can freely read, write, or reverse-engineer .lca for ecosystem interoperability.

Consequences

  • Positive:
  • Paper, Folia, Spigot, Fabric, and NeoForge servers can read and write .lca archives via a plugin/mod carrier, with reversible batch conversion back to .mca.
  • LeafRTP (AnvilPrefilter, LcaRegionReader) and WorldBlockFeed detect .lca regions on disk via RegionFormatDetector (PrimaryFormat.LCA).
  • Safety (REQ-RTP-S-004, REQ-RTP-S-005, REQ-RTP-S-007):
  • All lazy migrations and batch conversions write to a temporary file (.lca.tmp / .mca.tmp) and commit via ATOMIC_MOVE, preserving .bak backups when backup-migrated-legacy-files: true.
  • Batch commands execute off the server tick thread and report configurable feedback via messages.yml.