leafanvil-ADR-001: Multi-Loader .lca World Storage Carrier, Runtime RegionFileStorage Bytecode Interception & Reversible Migration (LeafAnvil)¶
- Status: Accepted
- Date: 2026-10-31
- Extends:
anvil-api-ADR-002,anvil-api-ADR-003,ADR-115,ADR-126
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:
- Runtime Interception Without Server Binary Patching: Standard Paper, Folia, Spigot, Fabric, and NeoForge distributions instantiate
RegionFileStorageinternally during world initialization. Supporting.lcaas a plugin/mod requires interceptingRegionFileStorageinstances in memory rather than distributing a modified server JAR. - Moonrise & Multi-Folder Storage Divergence: Each dimension maintains three separate
RegionFileStorageinstances (region/for voxel chunks,entities/for entity sections, andpoi/for points of interest). On Paper and Folia (Moonrise), chunk I/O usesRegionFile#write(ChunkPos, ByteBuffer),RegionStorageInfo,RegionFileVersion, and a cachednonExistingRegionFiles(LongLinkedOpenHashSet) miss set, whereas vanilla Fabric and NeoForge route throughIOWorkerandSimpleRegionStorageusingRegionFile#getChunkDataInputStream(ChunkPos)andgetChunkDataOutputStream(ChunkPos). Furthermore, Minecraft26.1+unifies dimension folders underdimensions/<namespace>/<dimension>/alongside classicworld/,DIM-1/, andDIM1/layouts. - Migration & Rollback Safety: Existing worlds require on-open migration from
.mca/.linearto.lca(with.bakbackups), explicit reversible batch conversion (/leafanvil convert format=mca),256BCopy-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:
- Multi-Module Carrier Layout (
ADR-126): :resource:LeafAnvil:leafanvil-common- Java 17 core (LeafAnvilConfig,LeafAnvilRuntime,LeafAnvilWorldConverter,NmsRegionStorageInterceptor,LeafAnvilCommand) depending on:server-api,:commands-api, and:anvil-api.:resource:LeafAnvil:leafanvil-paper-PaperLeafAnvilPlugin(load: STARTUP,folia-supported: true) attaching worlds onWorldInitEvent(LOWEST),WorldLoadEvent(LOWEST), andonEnable(), flushing onWorldSaveEventandonDisable(), and detaching onWorldUnloadEvent.:resource:LeafAnvil:leafanvil-fabric-FabricLeafAnvilMod(ModInitializer) attachingServerLevelinstances onServerLifecycleEvents.SERVER_STARTING,ServerLifecycleEvents.SERVER_STARTED, andServerTickEvents.START_SERVER_TICK(for dynamically created dimensions), and flushing/closing onSERVER_STOPPING/SERVER_STOPPED.:resource:LeafAnvil:leafanvil-neoforge-NeoForgeLeafAnvilMod(@Mod("leafanvil")) attaching onLevelEvent.LoadandServerStartedEvent, flushing onLevelEvent.SaveandServerStoppingEvent, and detaching/closing onLevelEvent.UnloadandServerStoppedEvent.-
:resource:LeafAnvil:leafanvil-plugin- Shaded single-JAR assembly (LeafAnvil-<version>.jar) relocatingio.github.dailystruggleundernet.leaf.anvil.shaded.io.github.dailystruggle. -
Runtime
RegionFileStorageDiscovery, Bytecode Bridge &C2ME/ Moonrise Supplier Interception (NmsRegionStorageInterceptor): - Recursive Storage Discovery & Live Folder Resolution:
NmsRegionStorageInterceptor#discoverRegionFileStoragestraversesCraftWorld/ServerLevelfield graphs up to depth 7 across vanilla (ChunkMap,ChunkSource,PersistentEntitySectionManager,EntityPersistentStorage,EntityStorage,PoiManager,SectionStorage,SimpleRegionStorage,IOWorker), Moonrise (RegionFileIO,DataController,ChunkTaskScheduler), andC2ME(C2MEStorageVanillaInterface -> C2MEStorageThreadextendingjava.lang.Thread) holders with JPMSUnsafe#getObjectfallback.resolveDimensionDirectoryinspects the liveRegionFileStorage.folderparent path so both classic (world/,DIM-1/,DIM1/) and26.1+dimensions/<namespace>/<dimension>/paths bind to their on-disk directories. - Runtime JVM Classfile Generation (
ClassFileBuilder, Java 17 bytecode version61):$$LeafAnvilCacheBridgesubclasses the server'sLong2ObjectLinkedOpenHashMap(regionCache) and overridesgetAndMoveToFirst(long)andget(long)to return per-region$$LeafAnvilRfBridgeinstances managed byCacheController(guarded bycreated[0]to prevent recursiveput()cycles underC2ME'sMixinRegionFileStorage).$$LeafAnvilRfBridgesubclassesnet.minecraft.world.level.chunk.storage.RegionFile(or implements Linear-forkIRegionFileinterfaces such asorg.leavesmc.leaves.region.IRegionFileandabomination.IRegionFile) and delegatesgetChunkDataInputStream,getChunkDataOutputStream, Moonrisewrite(ChunkPos, ByteBuffer)andC2ME@Invoker("write")invokeWriteChunk(ChunkPos, ByteBuffer)(onWriteByteBuffer),doesChunkExist/hasChunk,clear,flush,close,getPath,isOversized,setOversized,getOversizedData,recalculateHeader, andgetRecalculateCounttoLcaRegionFileStorage.
C2ME/ Moonrise Worker-Pool Supplier & Stream Interception:- Read Path (
LazyChunkNbtInputStream):LcaRegionFileStorage#getChunkDataInputStreamandLcaLiveArchive#getChunkDataInputStreamperform an $O(1)$ chunk-occupancy check on the I/O coordinator (C2MEStorageThread/ MoonriseRegionFileIOWorker) and return aDataInputStreamwrappingLazyChunkNbtInputStream, deferring.lca -> Mojang NBTdecoding until the first stream read onC2ME'sGlobalExecutors/ Moonrise's decompression worker pool. - Write Path (
RegionFileVersion$StreamWrapper,LCA_PREENCODED_VERSION_ID = 0x4C): Each$$LeafAnvilRfBridgeis initialized with a per-handleRegionFileVersion(id = 0x4C, returned byIRegionFile#getCompressionFormat()) whoseoutputWrapper(RegionFileVersion$StreamWrapper<OutputStream>) wrapsC2ME'sRawByteArrayOutputStreaminLcaPreEncodingOutputStream. WhenC2MEStorageThread#writeChunkscheduleslambda$writeChunk$1onC2ME'sGlobalExecutors.prioritizedScheduler.executor(16)worker pool,LcaPreEncodingOutputStream#close()parses the uncompressed Mojang NBT and executes.lcaChunkFrameencoding (encodeChunkNbtForRegionSlab) onC2ME's worker thread. Whenlambda$writeChunk$2subsequently invokesIRegionFile#invokeWriteChunk(ChunkPos, ByteBuffer)onC2MEStorageThread,onWriteByteBufferdetectscompressionId == 0x4Cand executes the $O(1)$commitPreEncodedChunkSlabCoW slab write (< 3 us), preservingC2ME'swriteFuturescompletion contract.
- Read Path (
-
Atomic Cache Swap, Pre-Open Cache Flush & Miss-Set Reset:
installOnRegionFileStorageatomically swapsregionCachebefore flushing and closing any pre-cached vanilla/LinearRegionFilehandles and clears Moonrise'snonExistingRegionFiles(LongLinkedOpenHashSet) so existing or migrated.lcafiles are visible on lookup. -
Header-Only
LcaLiveArchiveResidency & Bounded LRU Eviction (LcaRegionFileStorage&LcaLiveArchive): - Disk-backed
LcaLiveArchiveinstances (openLiveArchive(Path)) retain the10,304 B(~10.1 KiB,0x0000..0x283F) default on-disk region header prefix (64 BSuperblock,8,192 BPointer Directory,1,024 BdefaultRoot Shared Dictionary, and1,024 BSEC-DEDtable;~25.6 KiBtotal per-handle heap residency includingprevChunkPointers[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 openFileChanneland updatingLcaRegionReader.FILE_HEADER_CACHEpointers in-place (updateCachedPointer) on save. - Each
LcaRegionFileStorage(region/,entities/,poi/) maintains an access-ordered LRU cache of up to512open header-onlyLcaLiveArchivehandles (~5.15 MiBraw header prefix bytes, or~12.8 MiBtotal heap including decoded lookup arrays and handle state) plus aknownMissingRegionsnegative-lookup set. -
Evicting a region from the LRU cache calls
LcaLiveArchive#closeWithoutForce(), writing the"LCA1_END"footer canary and closing theFileChannelwithout issuing a blockingchannel.force(false)(fsync) syscall on tick/IO worker threads. Explicitfsynconflush()can be enabled via-Dleafanvil.fsync=true. -
Reversible Batch Conversion, Compaction & 4-Tier Self-Healing (
LeafAnvilWorldConverter,LeafAnvilCommand): -
/leafanvil(alias/lca) exposesstatus,convert [world=<name|all>] [format=<lca|mca>],compact [world=<name|all>],heal [world=<name|all>], andreloadviaCommandsAPI(commands-api-ADR-001), executing batch disk tasks asynchronously off the main thread (REQ-RTP-S-005) behind anAtomicBooleansingle-flight guard (REQ-RTP-S-007). -
Commercial Carrier Licensing with Open
.lcaFormat &anvil-apiCarve-Out: - The
LeafAnvilruntime carrier (resource/LeafAnvil,net.leaf.anvil.*, andLeafAnvil-<version>.jar) is a commercial product governed byresource/LeafAnvil/LICENSE(LicenseRef-LeafCraft-Commercial, packaged atMETA-INF/leafanvil/LICENSE) and guarded as a private path inscripts/pre_push_guard.py. - The
.lcabinary format Interface Control Document (api/anvil-api/docs/ICD.md, routed fromresource/LeafAnvil/docs/ICD.mdand packaged directly intoLeafAnvil-<version>.jar,LCA-ICD-1.0) and theio.github.dailystruggle.anvilcodec library (api/anvil-api) remain licensed under the MIT License soLeafRTP, world generators, server forks, map renderers, and third-party tools can freely read, write, or reverse-engineer.lcafor ecosystem interoperability.
Consequences¶
- Positive:
- Paper, Folia, Spigot, Fabric, and NeoForge servers can read and write
.lcaarchives via a plugin/mod carrier, with reversible batch conversion back to.mca. LeafRTP(AnvilPrefilter,LcaRegionReader) andWorldBlockFeeddetect.lcaregions on disk viaRegionFormatDetector(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 viaATOMIC_MOVE, preserving.bakbackups whenbackup-migrated-legacy-files: true. - Batch commands execute off the server tick thread and report configurable feedback via
messages.yml.