leafanvil-ADR-003: Negotiated Server-to-Client .lca Chunk Network Streaming, Batch LCD2 Framing & lastUpdateTick Delta Sync (Fabric & NeoForge)¶
- Status: Accepted
- Date: 2026-11-05 (Updated 2026-11-07)
- Scope:
:resource:LeafAnvil(leafanvil-common,leafanvil-paper,leafanvil-fabric,leafanvil-neoforge,leafanvil-net) &:anvil-api(io.github.dailystruggle.anvil) - Related ADRs & Specs:
leafanvil-ADR-001,leafanvil-ADR-002,leafanvil-ADR-005,leafshard-ADR-001,leafshard-ADR-002,anvil-api-ADR-002,anvil-api-ADR-003,leafrtp-ADR-072,LCA-ICD-1.0(api/anvil-api/docs/ICD.md)
Context¶
On Fabric (:resource:LeafAnvil:leafanvil-fabric, FabricLeafAnvilMod) and NeoForge (:resource:LeafAnvil:leafanvil-neoforge, NeoForgeLeafAnvilMod), LeafAnvil operates as a platform mod that can be installed on both the server and the client. While leafanvil-ADR-001 replaces on-disk .mca / .linear region storage with .lca (LcaRegionFileStorage) and leafanvil-ADR-002 keeps live server sections backed by compact .lca baseFrames plus $O(1)$ dirtyOverlay buffers, outbound chunk synchronization through vanilla's PlayerChunkSender and ClientboundLevelChunkWithLightPacket still suffers from three network-bandwidth and server-CPU bottlenecks:
1. Boundary A — Block & Biome PalettedContainer Minimum-Bit Floor & Step Jumps (ClientboundLevelChunkPacketData)¶
- When
PlayerChunkSenderserializes a chunk column ($24$ vertical sections of $16 \times 16 \times 16 = 4,096$ voxels), eachLevelChunkSection#write(FriendlyByteBuf)invokesPalettedContainer#write. - Vanilla's
SimpleBitStoragepacks all $4,096$ voxel indices inYZXscanline order with a minimum floor of $4\text{ bits/voxel}$ (long[256]=2,048 B) even when a section contains only $2\text{–}4$ distinct block states (such asstone+deepslateorwater+air), and steps the entire section to $5\text{ bits/voxel}$ (long[342]=2,736 B) as soon as a $17\text{th}$ block state enters the section palette. - Across a single Overworld chunk column, the uncompressed section payload alone reaches
~35–65 KiB.
2. Boundary B — Raw 2,048-Byte DataLayer Lighting Arrays & Binary Nibble Entropy (ClientboundLightUpdatePacketData)¶
- For every section carrying sky light or block light,
ClientboundLightUpdatePacketDatawrites a rawbyte[2048]DataLayernibble array. - Uniform open-sky sections (
SkyLight = 15across all $4,096$ voxels) and uniform underground sections (~75%+of all sections) still serialize2,048-bytearrays on the wire prior toZlibframing. - In non-uniform gradient sections, light decays by Manhattan distance ($15 \to 14 \to \dots \to 0$). Standard binary nibbles flip multiple bits at step boundaries (for example, $8 = 1000_2 \to 7 = 0111_2$ flips all $4$ bits), degrading downstream
DEFLATEcompression.
3. Boundary C — Server-Side baseFrame Re-Inflation, Stateless Per-Packet Zlib & Full Resends on Revisit¶
- Under
leafanvil-ADR-002Section5.B.2, cold sections remain in server memory as compact.lcaSectionFrames (~0–300 B). Unpacking those curves (00:XZY,01:H_3,10:Y+H_2,11:YZX) back into Mojang'sSimpleBitStorageYZXlong[256..342]on the server CPU solely to feed Netty's stateless per-packetZlibCompressionEncoder(~6–14 KiBcompressed per chunk, or~6–14 MBper $32 \times 32$ region) wastes server CPU when the receiving client also hasLeafAnvilinstalled. - Furthermore, when a player leaves a chunk's tracking range and later returns, vanilla re-transmits the entire
6–14 KiBClientboundLevelChunkWithLightPacketeven when0–2sections were modified since the client's previous visit.
Decision¶
Introduce a 4-layer negotiated server-to-client .lca chunk streaming and delta-synchronization protocol for Fabric (:resource:LeafAnvil:leafanvil-fabric) and NeoForge (:resource:LeafAnvil:leafanvil-neoforge), coordinated by :resource:LeafAnvil:leafanvil-common and backed by :anvil-api (LcaSectionCodec, LcaSectionBacking):
Vanilla Packet Path (unmodified client fallback):
LevelChunkSection (long[256..342] + DataLayer byte[2048])
-> FriendlyByteBuf (~45-85 KiB raw)
-> Per-packet Zlib Deflater (~6.0-14.0 KiB on wire)
LeafAnvil Negotiated .lca Stream Path (Fabric / NeoForge client with LeafAnvil):
Disk .lca Slab
-> Server RAM .lca (leafanvil-ADR-002 baseFrame + dirtyOverlay, O(1) slice)
-> Paced Chunk-Batch LCD2 Frame (~1.5-3.2 KiB on wire; 0.1-0.3 KiB on delta revisit)
-> Client RAM .lca (leafanvil-ADR-002 baseFrame + dirtyOverlay on ClientLevel, O(1) attach)
1. Optional Capability Handshake & Safe Mixed-Client Fallback (leafanvil:chunk_stream_handshake)¶
- Optional Channel Registration & Free
MITServer TX + Client RX Artifact (:resource:LeafAnvil:leafanvil-net): :resource:LeafAnvil:leafanvil-fabric(FabricLeafAnvilMod/FabricLeafAnvilClientMod) registers custom configuration/play payloads (leafanvil:chunk_stream_handshake,leafanvil:lca_region_dict_sync,leafanvil:lca_chunk_batch, andleafanvil:lca_chunk_digest) via Fabric'sPayloadTypeRegistryandServerPlayNetworking/ClientPlayNetworking, coordinated byLcaClientWireReceiver.:resource:LeafAnvil:leafanvil-neoforge(NeoForgeLeafAnvilMod/NeoForgeLeafAnvilClientMod) registers identical payload channels viaPayloadRegistrarmarked.optional()so connections never fail when either side lacksLeafAnvil, guarded byLcaClientWireReceiver#tryAcquireGlobalClientRegistrationandLeafAnvilRuntime#tryAcquireGlobalServerTxRegistrationso co-installed client and server jars never double-register handlers.:resource:LeafAnvil:leafanvil-netpackages a standalone, freeMIT-licensed multi-loader wire-only server TX + client RX mod/plugin (LeafAnvil-Net-<version>.jar, mod IDleafanvil_net) for Paper/Folia (plugins/), Fabric, and NeoForge (mods/) that bundlesLcaClientWireReceiver,LcaWireStreamProtocol,LcaInMemoryChunkCoordinator,LeafAnvilRuntime(in wire-only mode whereisDiskStorageAvailable() == false),PaperLeafAnvilPlugin,FabricLeafAnvilMod,NeoForgeLeafAnvilMod,MixinPlayerChunkSender, client/serverLevelChunkSection/PalettedContainerMixins, and:anvil-apiwhile strictly excluding the commercial on-disk.lcastorage interceptor, world converter, and/lcadisk commands (NmsRegionStorageInterceptor,LeafAnvilWorldConverter,LeafAnvilCommand). Server owners and modpack authors can dropLeafAnvil-Net-<version>.jaronto both servers and clients for immediate65%–78%initial and95%+revisit bandwidth reduction without converting their on-disk.mcaworlds, or pair it with the full commercialLeafAnvil-<version>.jaron the server for on-disk.lcastorage and zero-copy disk-to-wire slicing.- During connection setup, a
LeafAnvil-equipped client sendsLcaChunkStreamHandshakePayload(int protocolVersion, int capabilityFlags, int clientCacheBudgetKiB). capabilityFlagsnegotiates:CAP_LCA_SECTION_STREAM (1 << 0)—.lcaSectionFrame+ Gray-code light bitplane wire encoding;CAP_BATCH_LCD2 (1 << 1)— chunk-batch pure-JavaLCD2(0x4C44) intra-batch compression (LcaWireStreamProtocol);CAP_CLIENT_HEIGHTMAPS (1 << 2)— client-sideHeightmap.primeHeightmapsreconstruction (0 Bheightmap wire cost);CAP_DELTA_REVISIT_CACHE (1 << 3)—lastUpdateTick+ SEC-DED syndrome revisit delta patching.
- Mixed-Client Fallback Invariant:
- Connections that do not complete the
leafanvil:chunk_stream_handshakeremain on the unmodified vanillaClientboundLevelChunkWithLightPacketpipeline (still accelerated on the server byleafanvil-ADR-002Section5.B.2's zero-allocationScratchArenawriter). A single server shall simultaneously serve.lcabatch streams toLeafAnvilclients and vanilla packets to unmodified clients without shared-state contention.
2. Wire-Mode .lca SectionFrame Encoding & Network Registry ID Palette Substitution¶
Instead of serializing SimpleBitStorage long[256..342] arrays and byte[2048] DataLayer arrays, outbound chunks for negotiated clients use .lca SectionFrame representations (LCA-ICD-1.0 Sections 6–8):
- Implicit Majority State (
palette[0]) & Adaptive Delta-Roaring Containers: - Uniform sections (
|P| = 1, representing66.4%of natural sections) require0section body bytes and are encoded solely inside the2-bytesectionOffsets[i]directory word (with inlineskyLight2). - Non-uniform sections omit
palette[0](~90.8%of voxels) and encode minority states ($p = 1 \dots |P|-1$) along the section's selected 3D space-filling curve (00:XZY,01:H_33D Hilbert,10:Y+H_2horizontal 2D Hilbert,11:YZX) usingTAG_SINGLETON(2 B),TAG_DELTA_RUN(4|4or6|2gap/run bytes),TAG_DELTA_ARRAY(Bounded240gaps), orTAG_BITMAP(512 B), bounded by theleafrtp-ADR-072flat bit-packed ceiling (~150–300 Bper non-uniform section). 1-ByteConstant Light & 4-Bitplane Reflected Gray-Code Lighting (LCA-ICD-1.0Section 7.4):LIGHT_MODE_CONST(01): Sections with uniformSkyLightandBlockLightencode in1 byte(constLightNibbles = (blkConst4 << 4) | skyConst4), eliminating2,048–4,096 Bof constantDataLayerarrays.LIGHT_MODE_GRAY_PLANES(10): Non-uniform light arrays apply the Reflected Binary Gray Code bijection $G = L \oplus (L \gg 1)$ so unit-step Manhattan decay flips exactly 1 bit, then decompose into 4 bitplanes (g0..g3) along10:Y+H_2forSkyLight(~89 B/chunkaverage) and01:H_3forBlockLight.- Numeric Network Registry ID Palette Substitution (
IdMapper<BlockState>& Biome Registry): - On disk,
.lcastores string dictionaries (STATIC_CORE_STATES+ property suffixes) for cross-version durability. Over a live Fabric or NeoForge session, server and client share identical numericBlock.BLOCK_STATE_REGISTRY(IdMapper<BlockState>) and biome registry IDs. - When a negotiated player enters region
(rx, rz), the server either:- Synchronizes a compact
LcaRegionDictSyncPayloadmapping the region's local dictionary IDs to delta-VarIntnetworkBlockStateand biome registry IDs (int[] dictIdToBlockStateRegistryId, cached per activeLcaLiveArchive), or - Emits delta-
VarIntsorted globalBlockStateregistry IDs directly in each chunk's micro-palette header (Part A/Part B), eliminating string palette overhead on the wire.
- Synchronizes a compact
- Client-Side Heightmap Reconstruction (
CAP_CLIENT_HEIGHTMAPS): - When
CAP_CLIENT_HEIGHTMAPSis active, the server omits the~600 BrawMOTION_BLOCKINGandWORLD_SURFACElong[37]bit-packed arrays from the chunk payload (or optionally sends.lcaSection 8.1 compact heightmap deltas in~96–160 B), and the client decode worker reconstructs heightmaps locally viaHeightmap.primeHeightmaps(chunk, ...)in< 15 µs.
3. End-to-End Zero-Transcode Pipeline with leafanvil-ADR-002 ((baseFrame, dirtyOverlay)) & Chunk-Batch LCD2 Framing¶
- Simpler In-Memory
leafanvil-ADR-002Swap on Fabric & NeoForge (Server and Client): - Unlike Paper/Folia (
MoonriseBlockCountingBitStorage, which pins bitset-indexed ticking queues to rawlong[]BitStorage#getRaw()), vanilla Fabric and NeoForgeLevelChunkSection/PalettedContainertrack only three scalar counters (nonEmptyBlockCount,tickingBlockCount,tickingFluidCount) and support native Mixin / class-transform hooks on both the dedicated server and client. - As a result, swapping
LevelChunkSection's in-memory backing toleafanvil-ADR-002's(baseFrame, dirtyOverlay)representation applies cleanly on both the Fabric/NeoForge server and the Fabric/NeoForgeClientLevel. - Trivial End-to-End CPU Cost (
Disk .lca -> Server RAM .lca -> Wire .lca -> Client RAM .lca): - Combining
leafanvil-ADR-002(in-memory.lcarepresentation) withleafanvil-ADR-003(wire.lcastreaming) eliminates every intermediate voxel transcode between disk and client memory:- Disk $\to$ Server RAM (
O(1)slice):LcaRegionReadermaps the.lcaChunkFrameinto server memory without unpackingSectionFrames intoYZXlong[256..342]arrays (leafanvil-ADR-002). - Server RAM $\to$ Wire (
O(1)System.arraycopy): For cold sections (dirtyOverlay == null), the server slicesbaseFramebytes (~0–300 B) directly into the outbound batch buffer with zero voxel iteration, zero bit-repacking, and zero palette rebuild. For hot sections (dirtyOverlay != null), the server appends the compactdirtyOverlay(int[16..64]of packedentry32 = ((pos12 + 1) << 19) | (stateId19 & 0x7FFFF)at $\le 75\%$ load factor, typically64–256 B) alongsidebaseFrame. - Wire $\to$ Client RAM (
O(1)slab attachment): On the client, incoming.lcaSectionFrames (and anydirtyOverlay) attach directly to the clientLevelChunkSectionasleafanvil-ADR-002(baseFrame, dirtyOverlay)slabs without eager $O(4,096)$SimpleBitStorageinflation on packet receipt; subsequent single-block updates (ClientboundBlockUpdatePacket/ClientboundSectionBlocksUpdatePacket) write $O(1)$ entries into the client section'sdirtyOverlay.
- Disk $\to$ Server RAM (
- Paced Chunk-Batch
LCD2Framing (PlayerChunkSender#sendNextChunks) & NettyCompressionEncoderBypass: - Minecraft
1.20.2+/1.21.x/26.1+paces chunk delivery in per-tick batches bracketed byClientboundChunkBatchStartPacketandClientboundChunkBatchFinishedPacket. - For negotiated players,
PlayerChunkSender#sendNextChunkspacks the tick window's $N$ outbound.lcachunk frames ($N = 1 \dots 16$, together with block-entity NBT sidecars and initial light masks) into a singleClientboundLcaChunkBatchPayloadcompressed in one pass via pure-JavaLCD2(0x4C44) intra-batch framing, amortizing palette, biome, and block-entity NBT redundancy across adjacent chunks in the batch. - To prevent vanilla Netty's
CompressionEncoder(Zlib) from re-compressing theLCD2payload (and without fragmenting a16–32 KiBbatch into< 256 Bsub-slices), a lightweight Netty outbound handler before"compress"(or a 1-line Mixin inCompressionEncoder#encode) writes the uncompressed-lengthVarInt = 0header directly forClientboundLcaChunkBatchPayload, sending the entire batch in a single frame with zeroZlibCPU overhead.
4. Revisited-Chunk lastUpdateTick Digest & Sub-Chunk Delta Patch Streaming (ChunkPatchTail)¶
- Bounded Client
.lcaFrame LRU Cache: - Negotiated clients maintain a bounded off-heap/byte-slab LRU cache (configurable, default
32–64 MiB, sufficient for~10,000–20,000compressed.lcachunk frames) keyed by(dimension, chunkPos)and storing the chunk's 8-bytelastUpdateTickand 64-bit Extended Hamming(72, 64)SEC-DED header syndrome (LCA-ICD-1.0Section 6.1). - Digest Exchange & 3-Way Server Resolution:
- When a player moves across region boundaries or teleports back into a previously visited area, the client sends a compact
ServerboundLcaChunkDigestPayloadlisting(chunkPos, lastUpdateTick, secDedSyndrome64)for cached chunks in the target region:- Case A — Unmodified Chunk (
lastUpdateTick&secDedSyndrome64match): The server emits a2-byteclean-ack entry inClientboundLcaChunkBatchPayload, instructing the client to restore the chunk directly from its local.lcacache (> 99%bandwidth reduction). - Case B — Partially Mutated Chunk ($1\text{–}4$ sections dirty since cached
lastUpdateTick): The server transmits aChunkPatchTail(HAS_CHUNK_PATCH_TAIL = 0x4000,LCA-ICD-1.0Section 8.3) or section-delta frame (~100–300 B) containing only the replacedSectionFrameslices and updated block-entity NBT entries. - Case C — Cache Miss or Major Mutation: The server streams the full
.lcaChunkFrame(~1.5–3.2 KiB).
- Case A — Unmodified Chunk (
5. Client-Side Off-Thread Ingest, Lazy In-Memory Backing & Renderer Compatibility (Sodium / Embeddium / Bobby / Distant Horizons)¶
- Zero-Allocation Client Worker Ingest (
ScratchArena& Client-Sideleafanvil-ADR-002): - Upon receiving
ClientboundLcaChunkBatchPayload, the client decodes theLCD2batch frame off the render thread usingLcaSectionCodec's thread-localScratchArena(128 KiBpre-allocated scratch buffers, zero steady-state heap allocations). - When client-side
leafanvil-ADR-002in-memory section backing is enabled, eachClientLevelLevelChunkSectionattaches the compact.lca(baseFrame, dirtyOverlay)directly (0 Bbody for66.4%uniform sections;~150–300 Bfor non-uniform sections), making packet ingestion an $O(1)$ slice assignment;ScratchArenaonly expands a section when the chunk mesher (SectionCompiler/ SodiumChunkBuilderMeshingTask) actively builds a render mesh for a visible non-uniform section or when a Copy-on-Read caller requestsBitStorage#getRaw(). - Strict Netty Arrival-Order
ClientLevelCommit Boundary (ClientOrderedBatchCommitQueue): - While
LCD2batch decoding and Extended Hamming(72, 64)SEC-DED verification run off the render/main thread, the hydratedLcaSectionBackinginstances are committed ontoClientLevelon the client main thread in strict Netty arrival sequence order (ClientOrderedBatchCommitQueue) so any subsequentClientboundBlockUpdatePacketorClientboundSectionBlocksUpdatePacketthat arrived on Netty after the batch is never overwritten by an out-of-order background decode. - Because the client-side
LevelChunk(MixinLevelChunkSection),PalettedContainer(MixinPalettedContainerreturning non-pinning ephemeral snapshots oncopy()), andLevelLightEnginehonour the standard contracts, client rendering and LOD mods (Sodium, Embeddium, Lithium, Bobby, Distant Horizons) receive standard chunk-load and light-update events without custom compatibility patches, and Paper/Folia servers (PaperLeafAnvilPlugin) can streamLCA_NET_V1batches to Fabric/NeoForgeLeafAnvilclients over Bukkit plugin channels.
6. Inter-Server Zero-Translation Chunk & Section Delta Sync (LCAS 0x4C434153) Enabling LeafShard¶
While leafanvil-ADR-002 did not reduce overall server JVM heap in practice (because live NMS/Moonrise LevelChunkSection and PalettedContainer objects coexist with LcaInMemoryChunkCoordinator's tracked LcaSectionBacking columns), the network factor created by pairing leafanvil-ADR-002 with leafanvil-ADR-003 directly enabled LeafShard (leafshard-ADR-001..003):
- Zero-Translation Inter-Server Framing (
LcaWireStreamProtocol.InterServerChunkUpdatePayload, Magic0x4C434153/"LCAS"): LcaWireStreamProtocolexposes a peer-server batch envelope (INTER_SERVER_UPDATE_MAGIC = 0x4C434153) carrying(sourceServerId, dimension, regionX, regionZ, epochSequence, List<InterServerChunkDeltaEntry>).- Each
InterServerChunkDeltaEntry(int chunkX, int chunkZ, long previousBaselineSecDed64, BatchChunkEntry chunkEntry)reuses the exact wire primitives (SectionWireSlice,EntryPatchDelta,EntryFullChunk) negotiated with clients:- Delta Path (
EntryPatchDelta):LcaInMemoryChunkCoordinator#exportInterServerDeltaEntryinspectsdirtySectionBitmask32and exports only modifiedSectionWireSlices (4 bytesper mutated overlay voxel:entry32 = ((pos12 + 1) << 19) | (stateId19 & 0x7FFFF)) alongsidepreviousBaselineSecDed64and post-updatenewSecDedSyndrome64. - Full-Chunk Refill Path (
EntryFullChunk): When a peer shard joins a Halo ring or reportsNEEDS_FULL_CHUNK_REFILL/SYNDROME_MISMATCH,LcaInMemoryChunkCoordinator#exportChunkForInterServerTransferslices all 24SectionWireSlices (~1.5–3.2 KiBcompressed) without touching MojangCompoundTagorNbtIo.
- Delta Path (
- Enabling
LeafShard's10-ChunkCross-Border Halo Ring (leafshard-ADR-002): - In a distributed world partitioned along
32x32-chunk (.lcaregion,512x512-block) boundaries, neighboring shards must replicate a10-chunk(160-block) read-only Halo ring across region seams so players see live block edits and terrain across server borders. - Traditional Mojang NBT /
ClientboundLevelChunkWithLightPacketserialization (~45–85 KiBraw /~6–14 KiBZlibper chunk on the tick thread) would saturate inter-server links and main-thread CPU whenever blocks change near a border. - By wrapping
LeafAnvil'sLCAS(0x4C434153) delta payloads insideLeafShard's peer NettyLSHD(0x4C534844)FRAME_LCAS_CHUNK_DELTA (0x01)andFRAME_CHUNK_REFILL_REQ (0x02)frames,LeafShardCoordinatorsynchronizes cross-border Halo chunks off-thread in sub-kilobyte packets with strictSEC-DED-64syndrome verification.
7. 500 kbps (350 kbps Usable) Ultralight Upload Profile (CAP_ORDERLESS_DICT_AND_MULTICAST = 1 << 5)¶
For residential or upload-constrained hosts with a nominal 500 kbps uplink (~333–375 kbps / ~2,187 bytes/tick practical goodput at 20 TPS), LeafAnvil and LeafAnvil-Net provide three portable, reflection-free components in net.leaf.anvil.common.net (structured with flat records and fixed-size primitive arrays for 1:1 Rust lca-format and cross-language auto-translation):
- Packet & Layer-3/Layer-4 Framing Differential Profiler (
LcaPacketDifferentialProfiler): - Tracks logical packet counts, uncompressed Layer-7 bytes, compressed Layer-7 bytes, physical TCP flush segment counts, and
52 Bper-segment TCP/IPv4 framing tax across 6 fixed buckets (CHUNK_STREAM,ENTITY_KINEMATICS,ENTITY_METADATA_NBT,WORLD_BLOCK_DELTA,TRANSIENT_FX_UI,TCP_FRAMING_TAX). - Deducts current-tick non-chunk payloads and TCP headers from the global usable upload cap (
max-server-upload-kbps: 350) before allocating remaining tick bytes to chunk streaming. - Shared Atomically-Updated Orderless Dictionary Table (
LcaOrderlessDictTable, Magic0x4F444354/"ODCT"): - Maintains a
4,096-slot, 2-way associative content-addressed dictionary (slotId12+tag8/tag4verification hash) paired with a512-byte(long[64]) per-sessionKnownSlotBitSet. - Concurrent region workers atomically promote recurring chunk
SectionWireSlicemotifs, entity metadata archetypes, and registry/component strings via CAS without shifting slot indices or causing sequential epoch head-of-line blocking. - When
CAP_ORDERLESS_DICT_AND_MULTICAST(0x20) is negotiated,LcaWireStreamProtocolsetsHEADER_FLAG_ORDERLESS_DICT_SECTIONS(1 << 11) onEntryFullChunkandEntryPatchDeltaentries whose non-uniformSectionWireSlices are encoded viaLcaOrderlessDictTable#encodeSectionWireSlicesWithDict, physically replacing repeated section frames on the socket with2-byterefWord16((slotId12 << 4) | tag4) references (REQ-NET-ODCT-001) and expanding them insideLcaClientWireReceiver/LcaInMemoryChunkCoordinator#receiveClientChunkBatchOrderedprior toSEC-DED-64syndrome verification (REQ-NET-ODCT-002,REQ-RTP-S-004). - Multi-Target Spatial Group Consolidation,
1,000+Player Addressing & Edge Relay Fan-Out (LcaMultiTargetConsolidator, Magic0x4D544346/"MTCF"): - Computes
commonKnownSlots(bitwise ANDacross target players'KnownSlotBitSets in a shared spatial cell), encodes recurring slices once, updates all recipients' bitsets in a single tick, and packs moving entity updates into quantized4–6 BKinematicDeltaRowentries flushed once per tick (coalesce-tick-flushes: true). ConsolidatedMultiTargetFrame(MTCF) encodes an immutable, defensively cloned variable-lengthlong[] targetBitmapWords(1..64words = up to4,096concurrent player slots,REQ-NET-MTCF-001) and includesLcaMultiTargetConsolidator.MultiTargetTcpFanOutRelay(standalone TCP1-to-Mrelay shipped in bothLeafAnviland MITLeafAnvil-Net) alongsideLeafShardPeerFrameCodec.FRAME_CLIENT_MULTICAST_FANOUT(0x0C) inVelocityLeafShardPlugin(REQ-SHARD-FANOUT-001).- Verified across two physical machines (
scripts/bench_leafanvil_1000socket_bamboo.py,REQ-BENCH-1000-001) with the Origin Server on the local machine (350 kbpsusable cap, streaming60upstreamMTCFframes =192.95 kbpsLayer-7 /218.74 kbpsLayer-3/Layer-4 across $R = 3$ relay streams) and $R = 3$MultiTargetTcpFanOutRelayinstances +1,000live concurrent TCP client sockets on thebambooThreadripper (20,000 / 20,000client frames delivered,480,000.lcasections hydrated andSEC-DED-64-verified,720,000entity kinematic rows decoded,0errors). - Orders candidate chunks by Chebyshev spiral distance rings (
Ring 0r <= 2immediate25chunks first $\to$Ring 1r = 3..6$\to$Ring 2r >= 7) inLcaInMemoryChunkCoordinator#packLowBandwidth500kOutboundBatchesForPlayer.
Wire-Size & Server CPU Comparison¶
| Stream Component | Vanilla ClientboundLevelChunkWithLightPacket |
LeafAnvil .lca Wire Stream (Fabric / NeoForge) |
Architectural Mechanism |
|---|---|---|---|
Uniform / Air Sections (66.4% of sections) |
~12–24 B + 2,048 B light if sky-lit |
2 B (sectionOffsets[i] inline tag + skyLight2) |
Inline constant block & skyLight2 in directory word |
| Non-Uniform Voxel Sections | 2,048–2,736 B raw (SimpleBitStorage long[]) |
150–300 B (Delta-Roaring + 3D Hilbert) |
Implicit palette[0] (90.8% of voxels) + 1-pass curve selection |
Uniform Lighting (~75%+ of sections) |
2,048 B raw (DataLayer byte[2048]) |
1 B (LIGHT_MODE_CONST) |
Constant nibble folding (constLightNibbles) |
Gradient Lighting (SkyLight / BlockLight) |
2,048–4,096 B raw nibbles |
~89–210 B (LIGHT_MODE_GRAY_PLANES) |
4-bitplane Reflected Gray code along Y+H_2 / H_3 |
Heightmaps (MOTION_BLOCKING, WORLD_SURFACE) |
~600 B raw (long[37] $\times 2$) |
0 B (CAP_CLIENT_HEIGHTMAPS) or ~110 B (delta) |
Client worker Heightmap.primeHeightmaps or .lca Section 8.1 stream |
| Cold Section Server Serialization CPU | Full PalettedContainer#write + Zlib Deflater |
Zero-copy baseFrame slice (leafanvil-ADR-002) |
Direct slice from in-memory .lca baseFrame |
| Typical Initial Wire Size / Chunk | ~6.0 – 14.0 KiB (per-packet Zlib) |
~1.5 – 3.2 KiB (.lca + batch LCD2) |
~65%–78% bandwidth reduction on initial load |
| Revisited Chunk ($0\text{–}2$ Sections Edited) | ~6.0 – 14.0 KiB (full chunk resend) |
2 B (clean-ack) – 0.3 KiB (ChunkPatchTail) |
~95%–99% bandwidth reduction on revisit delta sync |
Consequences, Invariants & Risks¶
Positive Consequences¶
- 65%–78% Initial & 95%+ Revisit Bandwidth Reduction: Dramatically lowers server egress bandwidth and accelerates chunk loading during fast flight, Elytra travel, and
LeafRTPrandom teleports on Fabric and NeoForge servers. - Server CPU Offload (
leafanvil-ADR-002Synergy): Cold sections in server memory are sliced directly into the network batch without unpacking 3D Hilbert / Delta-Roaring containers on the server; client CPUs perform the $O(4,096)$ curve-to-YZXexpansion in parallel. - Foundation for
LeafShardDistributed World Sharding (LCAS0x4C434153$\to$LSHD0x4C534844): ReusingSectionWireSlice,EntryPatchDelta(4 bytesper modified voxel),EntryFullChunk, andSEC-DED-64baseline syndromes (InterServerChunkUpdatePayload) enablesLeafShard(leafshard-ADR-001..003) to maintain live10-chunkcross-border Halo replicas across multiple backend servers with zero main-thread NBT translation. - Full Chunk-Batch Pacing Compatibility: Preserves Minecraft's
PlayerChunkSenderRTT/bandwidth congestion window (ClientboundChunkBatchStartPacket/ServerboundChunkBatchReceivedPacket) so client frame rates and packet pacing remain smooth.
Required Safety Invariants¶
- Zero Main-Thread Blocking (
REQ-RTP-S-005): Neither server batchLCD2framing nor client.lcadecoding shall perform synchronous disk I/O on the server tick thread or client render thread. - Mixed-Client Coexistence: Unmodified vanilla clients and
LeafAnvil-enabled clients shall coexist on the same Fabric or NeoForge server without protocol errors or registry desynchronization. - SEC-DED & Registry Parity Verification: Before applying a
lastUpdateTickclean-ack orChunkPatchTaildelta from the client LRU cache, the client shall verify the 64-bit Extended Hamming(72, 64)SEC-DED header syndrome (LCA-ICD-1.0Section 4.3); on any mismatch, the client evicts the cached entry and requests a full.lcaChunkFrame.
Risks & Mitigations¶
- Double Compression in Netty
CompressionEncoder& Reverse Proxy Compatibility (VarInt = 0Frame Bypass vs.Deflater.NO_COMPRESSIONStored-Zlib Framing): BecauseClientboundLcaChunkBatchPayloadis already compressed withLCD2(0x4C44), passing a16–32 KiBbatch through Netty'sZlibCompressionEncoderwould waste CPU for zero size gain, while sub-slicing belownetwork-compression-threshold(commonly256 B, or64 Bbehind proxies) would fragment a single batch into64–128custom payload packets per tick window. Furthermore, reverse proxies (Velocity and BungeeCord) may reject uncompressed frames (dataLength == 0) exceedingnetwork-compression-thresholdas an anti-DoS heuristic. Mitigation: Support both directVarInt = 0(dataLength = 0) bypass (encodeNettyVarIntZeroBypassFrame/MixinCompressionEncoder) on direct connections and proxy-safe RFC 1950 / RFC 1951Deflater.NO_COMPRESSION(level = 0stored-block) Zlib framing (encodeProxySafeZlibStoredFrame,CAP_PROXY_SAFE_STORED_ZLIB), which adds only+11 Bper< 64 KiBbatch while producing a valid non-zerodataLengthheader that passes Velocity, BungeeCord, and vanillaCompressionDecoderwith zero LZ77/Huffman CPU overhead. - Dynamic Modded BlockState Registry Remaps: If a server and client have mismatched mod lists, connection fails during standard Fabric/NeoForge configuration negotiation before play-stage chunk streaming begins. As defense in depth,
LcaChunkStreamHandshakePayloadincludes a 64-bit hash ofBlock.BLOCK_STATE_REGISTRYsize and biome registry count; if mismatched, the connection falls back to string dictionary palettes or standard vanilla packets.