ZeroSeek

# ZeroSeek v1.4.0 — Modular Architecture, Hybrid MMap Storage, Integrated StarLight & Hardware GPU Acceleration ZeroSeek v1.4.0 is a milestone release delivering a modularized engine architecture, complete stabilization of the Anvil storage layer, integration of the StarLight lighting engine, natural mountain height restoration, and optional hardware GPU acceleration via the NVIDIA CUDA Driver API on Minecraft 1.21.11 (Fabric). --- ## What's New ### 1. Modular Subproject Architecture ZeroSeek has been decoupled into four specialized, maintainable submodules: * **`zeroseek-base`**: Core server engine containing low-level Java 22 Foreign Function & Memory (FFM) MMap I/O, native OS kernel memory hints (`posix_madvise` / `PrefetchVirtualMemory`), CPU thread affinity isolation, and the Non-Destructive TPS Governor. * **`zeroseek-worldgen`**: Multi-threaded terrain generator with 2D Chebyshev Spatial Locking ($3 \times 3$), `ChunkMap` & `ChunkStep` interceptors, 3D biome caching, SIMD density interpolation, and memory-compact palettes. * **`zeroseek-cuda`**: Optional GPU compute module communicating directly with `nvcuda.dll` / `libcuda.so` via Java 22 FFM downcalls for asynchronous preliminary surface noise prefetching and NVRTC runtime kernel compilation. * **`zeroseek-light`**: High-performance deferred lighting engine embedding the StarLight lighting algorithm directly into ZeroSeek. ### 2. Hybrid MMap Storage Engine (Zero Corruption Guarantee) The delta persistence subsystem (`ExternalDeltaManager` and `RebaseWorker`) has been completely removed in favor of a clean, robust hybrid storage model: * **Zero-Copy MMap Reads**: Chunk reads continue to utilize ultra-fast zero-copy memory mapping via Java 22 `MemorySegment` and `Arena.ofShared()`, bypassing JVM Heap allocations. * **Vanilla Async Sector Writes**: Chunk writes are delegated to vanilla Minecraft's battle-tested asynchronous `StorageWorker` pipeline, guaranteeing 100% Anvil sector table integrity. * **Targeted Cache Invalidation**: `RegionFileMixin` hooks directly into sector write operations to instantly evict dirty region mappings from the bounded `MmapLruCache` (default 2 GB), eliminating stale cache reads without introducing thread races. ### 3. Integrated StarLight Lighting Engine (`zeroseek-light`) * Replaced Vanilla's recursive, single-threaded `LightEngine` with StarLight's lock-free, bitwise SWMR (Single Writer Multi Reader) algorithm. * Lighting propagation tasks are fully decoupled from critical chunk generation threads and processed through a non-blocking deferred queue. * Eliminates lighting stalls during rapid world generation and high-speed player travel. ### 4. Hardware GPU Acceleration (`zeroseek-cuda`, Optional) * **Pure FFM Driver API Binding**: Direct low-overhead invocation of NVIDIA CUDA Driver API without intermediate JNI or external native libraries. * **2D Preliminary Surface Grid Prefetching**: Asynchronously computes a $24 \times 24$ column grid with a $-48$ block offset on NVIDIA RTX GPUs, achieving 100% cache hit rates during Aquifer water and lava level evaluations. * **Runtime NVRTC Compilation**: Dynamically compiles Minecraft density function compute kernels at server startup tailored to the host GPU architecture. ### 5. Micro-Architectural WorldGen Optimizations * **3D Biome Caching (`Biome3DCache` & `ClimateColumnCache`)**: Thread-local spatial hash maps cache multi-octave climate samplings and climate search tree traversals, dramatically cutting redundant biome queries. * **SIMD Trilinear Density Interpolation (`DensityInterpolatorSimd`)**: Accelerates 3D density grid interpolation across chunk cell boundaries using vectorized float primitives and precomputed trigonometric lookup tables (`CompactSineLUT`). * **ZeroSeek Compact Hash Palette**: Memory-compact palette replacement for `PalettedContainer`, significantly reducing memory allocations during block state storage. --- ## Bug Fixes & Critical Stability ### 1. Elimination of Region File Corruption * **Issue**: In prior builds (v1.2.0–v1.3.0), the asynchronous `RebaseWorker` thread merged `.raw` delta files back into `.mca` files concurrently with active game writes. Under high write concurrency, this caused sector allocation table collisions and region file corruption. * **Fix**: Complete removal of delta layer files and background rebase threads. Writes now flow through vanilla storage workers, while reads utilize the fast MMap path with strict sector invalidation. ### 2. Restoration of Natural Mountain Heights (Removal of `NoiseHeightCuller`) * **Issue**: An experimental height-culling optimization (`NoiseHeightCuller`) prematurely skipped noise evaluations above Y=264, causing artificial flat plateaus on high mountain peaks (Jagged Peaks, Frozen Peaks, Stony Peaks). * **Fix**: Completely excised `NoiseHeightCuller`. Mountain peaks now generate authentically up to the full vanilla build ceiling (Y=320) with natural slopes and cliffs. Terrain generation speed is maintained through SIMD interpolation and GPU prefetching instead of destructive culling. ### 3. Elimination of Lighting Thread Stalls * **Issue**: Vanilla lighting calculations during concurrent chunk generation frequently blocked worker threads waiting for neighbor chunk light propagation. * **Fix**: Integration of the lock-free StarLight engine resolves neighbor lighting dependencies asynchronously without thread contention. --- ## ⚠️ Compatibility & Incompatibilities Because ZeroSeek deeply modifies low-level Minecraft server subsystems (Region I/O, WorldGen chunk scheduling, Noise evaluation, and Lighting), running other mods that modify the same systems will cause startup crashes or fatal conflicts. ### ❌ Incompatible Mods (Do NOT install alongside ZeroSeek) * **C2ME (Concurrent Chunk Management Engine)**: **Hard conflict.** Both mods replace chunk task scheduling, `ChunkStep` hooks, and region I/O. Will cause startup crashes and deadlocks. * **StarLight / ScalableLux**: **Hard conflict.** ZeroSeek v1.4.0 already integrates StarLight 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 the same density function and noise evaluation pipelines. * **Krypton**: May cause packet race conditions with async chunk serialization. ### ✅ Fully Compatible & Recommended Mods * **Performance**: FerriteCore, ModernFix, MemoryLeakFix, FastSuite. * **Gameplay & Entities**: Lithium (compatible with entity and AI optimizations; ZeroSeek handles chunk I/O and worldgen). * **Client Visuals**: Sodium, Iris, Nvidium, Voxy (ZeroSeek is strictly server-side). * **WorldGen Datapacks**: Terralith, Biomes O' Plenty, Nullscape. * **Dynmap / Map Viewers**: BlueMap, Dynmap, Pl3xMap. --- ## Configuration Changes (`config/zeroseek.json`) New configuration options available in v1.4.0: * `cudaAccelerationEnabled` (default: `false`): Enables NVIDIA GPU acceleration via CUDA Driver API. Requires an NVIDIA RTX GPU and modern NVIDIA display drivers. * `cudaPrefetchEnabled` (default: `true`): Asynchronous 2D grid prefetching for surface noise. * `cudaPrefetchRadius` (default: `5`): Chunk radius for GPU prefetch dispatch. * `biomeOptimizationEnabled` (default: `true`): Enables 3D biome caching and climate column acceleration. *Legacy delta settings (`rebaseIntervalSeconds`, `rebaseBatchSize`, `deltaStoragePath`) have been deprecated and removed.* --- ## Target Platform & Requirements * **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) * **Operating System**: Windows (x64) and Linux (x64) * **Side**: Dedicated Server (Server-side only) * **Output Jar**: `zeroseek-1.4.0.jar`

# ZeroSeek v1.3.0 — Concurrent World Generation Engine & Safe Adaptive Backpressure ## What's New ### 1. Concurrent World Generation Engine - **Dedicated Generator Worker Pool**: Complete architectural overhaul offloading world generation pipelines from `ServerThread` onto a dedicated multi-threaded worker pool (`zeroseek-generator`, default 8 threads). - **2D Spatial Locking (`SpatialLockManager`)**: Fine-grained Chebyshev neighborhood locking ($3 \times 3$ grid for the `FEATURES` stage with write radius 1) using non-blocking `CompletableFuture` dependency chaining. Strict canonical coordinate sorting (`Arrays.sort(positions)` by `Long::compare`) mathematically guarantees deadlock-freedom across all concurrent chunk generation tasks. - **Hardware CPU Affinity Isolation**: Dedicated generation worker threads are bound to logical CPU cores 2–7 via native Java 22 FFM API downcalls (`SetThreadAffinityMask` on Windows, `sched_setaffinity` on Linux), isolating `ServerThread` on cores 0–1 with zero context-switching interference. - **1.21.11 Pipeline Interceptors**: - `ChunkMap`: Redirects background worldgen dispatcher tasks to the dedicated affinity generator pool. - `ChunkStep.apply`: Intercepts `ChunkStatusTask.doWork` to enforce non-blocking 2D spatial locking for stages with write radius > 0. - `NoiseBasedChunkGenerator`: Eliminates `backgroundExecutor bouncing` in `fillFromNoise` and `createBiomes` by routing executions directly into the dedicated generator worker pool. ### 2. WorldGen Thread-Safety Hardening - **`StructureStart`**: Replaced non-atomic reference counter with `AtomicInteger`. - **`Stronghold` & `Nether Fortress`**: Isolated piece weight counters (`placeCount`) into `ThreadLocal<Integer>`. - **`SimplifiedAtomicSimpleRandom`**: High-throughput thread-local PRNG eliminating atomic CAS loops in hot noise sampling. - **`TheEndBiomeSource`**: Per-thread LRU cache (1024 entries) for 2D End biomes, skipping redundant erosion noise evaluations. ### 3. Pipeline Stability & Resilience - **Caller-Runs Queue Backpressure**: Replaced legacy queue-drop policies in `HardenedWorkerPool` with `CallerRunsPolicy` backpressure and expanded queues to 4096 tasks, ensuring zero lost `CompletableFuture` instances during burst chunk generation. - **Empty-Server Pause Guard (`MinecraftServerMixin`)**: Eliminates the vanilla 1.21.11 `pause-when-empty-seconds` deadlock where players connecting during the `CONFIGURATION` phase were blocked indefinitely by a paused server. - **Safe TPS Governor Adaptive Backpressure**: - When server drops to `CRITICAL` TPS (<= 10.0), concurrent heavy boundary tasks (`FEATURES`) are dynamically constricted to a maximum of 2 operations via an asynchronous permit queue. - Permits are acquired prior to claiming spatial chunk locks, preventing circular lock-permit deadlocks. - Instantaneous permit reset and throughput recovery when TPS returns to `NORMAL`/`STRESS`. ## Configuration (`config/zeroseek.json`) - `concurrentWorldGenEnabled`: Toggle multi-threaded world generation (default: `true`). - `chunkGeneratorThreads`: Thread count for world generation pool (default: `8`). - `chunkGeneratorMaxQueue`: Work queue capacity for world generation tasks (default: `4096`). - `worldGenAffinityCores`: Assigned logical CPU cores (default: `[2, 3, 4, 5, 6, 7]`).

# ZeroSeek v1.2.0: Batch Region Rebase & Non-Destructive TPS Governor ZeroSeek v1.2.0 delivers an architectural overhaul of the delta persistence subsystem, complete multi-dimension isolation, a non-destructive rewrite of the TPS Governor using MixinExtras, and full alignment with Java 22 Foreign Function & Memory (FFM) APIs on Minecraft 1.21.11 (Fabric). --- ## What's New ### 1. Batch Rebase Pattern for Delta Chunk Storage The asynchronous delta persistence subsystem has been redesigned to eliminate file descriptor thrashing and off-heap memory churn during delta merges: * **Region-Grouped Batch Writes**: Modified chunk delta files (`world/**/region_delta/r.X.Z/c.x.z.raw`) are now aggregated and grouped by destination region before executing rebase tasks. * **Single Descriptor Allocation**: ZeroSeek opens the target `RegionFile` handle exactly once per batch, writes all pending chunk deltas sequentially, and closes the handle in a single atomic cycle. * **Single Cache Invalidation**: Native off-heap `MmapLruCache` handles are invalidated exactly once per region file prior to write injection, eliminating cache eviction loops and stale virtual memory pages. * **Full Multi-Dimension Architecture**: Added automatic dimension hierarchy resolution supporting: * Overworld (`world/region/r.X.Z.mca`) * The Nether (`world/DIM-1/region/r.X.Z.mca`) * The End (`world/DIM1/region/r.X.Z.mca`) * Custom & Modded Dimensions (`world/dimensions/<namespace>/<dimension_path>/region/r.X.Z.mca`) * **High-Throughput Delta Discovery**: `ExternalDeltaManager.getAllDeltaFiles()` uses a pruned directory scanner that explicitly skips heavy vanilla trees (`region/`, `poi/`, `entities/`, `playerdata/`, `stats/`, `advancements/`), dropping filesystem traversal overhead on servers with large worlds. --- ## Bug Fixes & Safety (Non-Destructive TPS Governor) Prior releases throttled server load by aggressively suppressing core entity and network ticking, which caused physics desyncs and rubberbanding. Version 1.2.0 replaces all destructive hooks with a non-destructive governor architecture: ### 1. Complete Restoration of Vanilla `LivingEntity.aiStep()` * **Root Cause Fixed**: Cancelling `aiStep()` previously bypassed gravity integration, suffocation checks, fall damage counters, fluid drag, status effect updates, and vehicle/mount synchronization. * **Invariant**: `LivingEntity.aiStep()` is now executed unconditionally without interception. ### 2. Surgical Mob AI Decimation via `@WrapOperation` * **Safe Goal Throttling**: Implemented `MobMixin` using `@WrapOperation` on `serverAiStep()` targeting `GoalSelector.tick()` and `GoalSelector.tickRunningGoals(boolean)`. * **Player Proximity Immunity**: Mobs within **48 blocks** of any alive player (`level.hasNearbyAlivePlayer(x, y, z, 48.0)`) are strictly immune to AI skipping. * **Adaptive Load Throttling**: Distant mobs only experience probabilistic AI decimation under verified server degradation: * `NORMAL` state (TPS >= 15.0): **0% skip** (Vanilla execution). * `STRESS` state (10.0 <= TPS < 15.0): **25% skip** (`stressSkipAiChance = 0.25`). * `CRITICAL` state (TPS < 10.0): **75% skip** (`criticalSkipAiChance = 0.75`). ### 3. Removal of Movement Packet Drops * **Fix**: Removed destructive mixins on `ServerGamePacketListenerImpl` (`ServerboundMovePlayerPacket`). * **Result**: Complete elimination of client rubberbanding, server-client coordinate divergence, and false-positive anticheat kicks during low TPS conditions. ### 4. Removal of Chunk Ticket Interference * **Fix**: Removed throttling hooks on `DistanceManager.addPlayer()` and `DistanceManager.updatePlayerTickets()`. * **Result**: Players will no longer fall through unloaded chunks or get stranded in void boundaries when server load spikes. --- ## Technical Improvements & Architecture ### Platform & Toolchain Upgrades * **Minecraft Target**: Standardized on **Minecraft 1.21.11**. * **Loader Target**: Fabric Loader **>=0.16.0** (tested on 0.18.2) and Fabric API **0.139.4+1.21.11**. * **Java 22 FFM API**: Memory segment management fully integrated with `java.lang.foreign.MemorySegment` and `java.lang.foreign.Arena.ofShared()`. * **Bytecode Compliance**: Set `"compatibilityLevel": "JAVA_22"` in `zeroseek.mixins.json`. ### Test Suite Integration * Added unit test coverage via JUnit 5 in `RebaseWorkerTest`: * `testComputeBaseFilePath`: Validates `.mca` path derivation across Overworld, Nether, End, and custom dimensions. * `testDetectDimension`: Asserts exact `ResourceKey<Level>` parsing from path structures. * `testGroupingDeltaFiles`: Verifies batch partition counts per region file. * `testExternalDeltaManagerScan`: Validates directory exclusion rules and `.raw` file filtering under temporary filesystems.

# Changelog ## What's new in this build ### Added - **Windows MMap prefetch** via `PrefetchVirtualMemory` (FFM) in `MadviseHelper`. - Linux continues using `posix_madvise` (`WILLNEED` / `DONTNEED`). - Windows `DONTNEED` is intentionally a no-op; the OS manages page lifetime. ### Changed - Status now lists MMap prefetch on both Windows and Linux. - Removed the old "Windows PrefetchVirtualMemory fallback" backlog item. - Corrected output jar name to `zeroseek-1.0.0.jar`. - `MmapRegionIo` debug log messages now use generic "MMap prefetch" wording. - `ZeroSeekConfig`: added `FUTURE` comments for `maxMappedBytes` and `chunkLoaderThreads`. - `AsyncChunkService`: added a `FUTURE` comment for the reserved `loaderPool`. ### Removed - Dead `AsyncChunkService.prefetchChunk(ServerLevel, ChunkPos)` method. - Unused `RegionFileVersion` import in `RegionFileMixin`. - Unused `WeakReference` import in `EntityHibernation`. ### Fixed - `MadviseHelper`: corrected Linux advice constants and separated platform logic into clean Linux / Windows / no-op paths. - `MadviseHelper`: Windows `PrefetchVirtualMemory` binding now works correctly with `MemorySegment.ofAddress(...)` for the `WIN32_MEMORY_RANGE_ENTRY` layout. ### Infrastructure - Added this changelog file.

mode release