ZeroSeek

What is ZeroSeek?

ZeroSeek is an all-in-one low-level performance engine for Minecraft servers. It addresses the core architectural bottlenecks of Minecraft's world pipeline by replacing standard synchronous chunk I/O with native zero-copy memory-mapping, parallelizing terrain generation with 2D spatial locking, integrating a dedicated StarLight lighting engine, and optionally offloading noise evaluation to NVIDIA GPUs via the CUDA Driver API.

The goal is deterministic server tick-rate (20.0 TPS) under demanding gameplay scenarios, including high-speed elytra flight, multi-player teleports, and rapid chunk generation.

---

Current Status

Production-ready (v1.4.0) for Minecraft 1.21.11 (Fabric). Features included:

• Modular subproject architecture (zeroseek-base, zeroseek-worldgen, zeroseek-cuda, zeroseek-light).
• Native Java 22 FFM Memory-Mapped I/O (MemorySegment, Arena.ofShared()).
• Concurrent World Generation Pipeline with 2D Chebyshev Spatial Locking ($3 \times 3$).
• Integrated StarLight Deferred Lighting Engine (zero-allocation bitwise light propagation).
• Native CPU Core Affinity (sched_setaffinity on Linux / SetThreadAffinityMask on Windows).
• Non-Destructive TPS Governor with player-immune mob AI decimation.
• Optional NVIDIA GPU Acceleration (CUDA Driver API + NVRTC runtime kernel compilation).
• Advanced WorldGen optimizations: SIMD density interpolation, 3D biome caching, and memory-compact palettes.

---

⚠️ Incompatibilities & Mod Conflicts

ZeroSeek deeply modifies low-level Minecraft subsystems (Region I/O, WorldGen chunk scheduling, Noise generation, and Light engines). Installing other mods that modify these exact systems will cause server crashes on startup, severe deadlocks, or world corruption.

❌ Strictly Incompatible (Will not launch or will crash/corrupt world)

• C2ME (Concurrent Chunk Management Engine): Hard conflict. Both mods replace the chunk task dispatcher, ChunkStep scheduling, and region file I/O. Running both causes instant server startup deadlocks and file corruption.
• StarLight / ScalableLux: Hard conflict. ZeroSeek v1.4.0 already includes its own optimized StarLight lighting engine directly inside zeroseek-light. Adding external StarLight or ScalableLux will cause duplicate Mixin injection crashes on LevelLightEngine and ThreadedLevelLightEngine.
• Noisium: Hard conflict. Both mods hook into density function noise caching and chunk noise evaluation loops.
• Krypton / Alternate Network/Chunk Packet Rewriters: Potential race condition with ZeroSeek's async chunk serialization.

✅ Fully Compatible & Tested

• Optimization Mods: FerriteCore, ModernFix, MemoryLeakFix, FastSuite.
• Lithium: Compatible with standard entity, AI, and block ticking optimizations.
• Client Renderers: Sodium, Iris, Nvidium, Voxy (ZeroSeek is server-side and fully compatible with client mods).
• Map Tools & Markers: BlueMap, Dynmap, Pl3xMap.
• WorldGen Datapacks / Biome Mods: Terralith, Biomes O' Plenty, Nullscape.

---

Features

1. Zero-Copy MMap I/O Engine (zeroseek-base)

• Direct Memory Access: Region files (.mca) are read directly through native virtual memory (MemorySegment) via Java 22 Foreign Function & Memory (FFM) API, completely bypassing intermediate JVM Heap allocations.
• Synchronized Hybrid Storage: Writes are handled by vanilla asynchronous StorageWorker threads with automatic MmapLruCache invalidation on sector writes, guaranteeing 100% Anvil sector integrity and zero file corruption.
• MMap LRU Cache: Off-heap memory is strictly bounded by maxMappedBytes (default: 2 GB), automatically evicting cold region mappings down to 90% budget.
• Kernel Memory Hints: Issues native page prefetch advisories via PrefetchVirtualMemory on Windows and posix_madvise (WILLNEED / DONTNEED) on Linux.

2. Concurrent World Generation Engine (zeroseek-worldgen)

• 2D Spatial Locking: Fine-grained Chebyshev $3 \times 3$ grid locking for boundary-writing generation stages (FEATURES), ordered canonically to mathematically eliminate lock-ordering deadlocks.
• Dedicated Generator Pool: Independent worker pool with CallerRunsPolicy backpressure and hardware CPU affinity bound to isolated processor cores (e.g., Cores 2–7).
• Zero-Bouncing Dispatch: Direct execution in worker threads eliminates thread hopping in fillFromNoise and createBiomes.
• 3D Biome & Column Caching: Multi-octave climate sampling and search tree traversals are cached per-thread (Biome3DCache, ClimateColumnCache).
• SIMD Density Interpolation: Accelerates 3D trilinear density interpolation using vector math primitives (DensityInterpolatorSimd, CompactSineLUT).
• Compact Hash Palette: High-efficiency palette implementation reducing memory footprint in PalettedContainer.

3. Integrated StarLight Lighting Engine (zeroseek-light)

• StarLight Architecture: Fully replaces vanilla's heavy, recursive LightEngine with StarLight's lock-free, bitwise SWMR propagation algorithm.
• Deferred Lighting Execution: Light tasks are batched and scheduled independently, removing light updates from the critical chunk generation path.

4. GPU Hardware Acceleration (zeroseek-cuda, Optional)

• NVIDIA CUDA Compute: Offloads heavy 2D preliminary surface noise calculation to dedicated NVIDIA GPUs (RTX series) using the CUDA Driver API (nvcuda.dll / libcuda.so).
• Async 2D Grid Prefetching: Prefetches a $24 \times 24$ column grid with a $-48$ block offset to provide 100% cache hits for Aquifer water/lava level calculations.
• Runtime NVRTC Compilation: Dynamically translates Minecraft density function ASTs into optimized PTX/CUBIN machine code at server startup.

5. Non-Destructive TPS Governor

• Vanilla Physics Invariant: Never cancels LivingEntity.aiStep(), never drops player movement packets, and never freezes player chunk tickets. Gravity, fall damage, status effects, and vehicle alignment remain 100% vanilla.
• Distant Mob AI Decimation: Probabilistically decimates GoalSelector AI execution only for mobs farther than 48 blocks away from living players during STRESS or CRITICAL TPS states.
• Adaptive Simulation Scaling: Dynamically contracts and expands simulation distance between normal and degraded states.

---

Target Platform

• Minecraft: 1.21.11 (Official Mojang Mappings)
• Fabric Loader: 0.18.2+
• Fabric API: 0.139.4+1.21.11
• Java Toolchain: Java 22 (release = 22 required for FFM API)
• Environment: Dedicated Server (Server-side only)
• Operating System: Windows (x64) and Linux (x64)

---

Installation

1. Verify that your server runtime is running Java 22 (java -version).
2. Remove any conflicting mods (C2ME, StarLight, ScalableLux, Noisium).
3. Place zeroseek-1.4.0.jar into your server's mods/ directory.
4. Start the server to generate config/zeroseek.json.
5. Adjust thread pools and CPU affinity cores in config/zeroseek.json to match your CPU topology.

---