Parallel Core

Description

ParallelCore is a lightweight Fabric-based API and foundational layer designed to enable safe multithreading for Minecraft mods. It does not add parallel behavior itself but provides the essential building blocks for other mods to implement concurrent logic without corrupting the game world or crashing.

Core Features

Thread-Safe World Access
Vanilla Minecraft prohibits world access from any thread other than the main server thread. ParallelCore overcomes this limitation through a safe-zone mechanism. Mods can mark regions of code as a "parallel safe zone," which temporarily relaxes thread checks. While inside a safe zone, chunk and block lookups become thread-safe, allowing worker threads to read world state concurrently.

World Snapshot via Chunk Lookup
Rather than creating heavy full-world copies, ParallelCore provides a thread-safe chunk reader that bypasses the vanilla main-thread dispatcher. When worker threads request chunks, they receive direct read-only access to already-loaded chunks without blocking or deadlocking the main thread. This acts as a lightweight, on-demand snapshot system.

Isolated Thread Pools
The mod provides a thread-pool factory that creates independent, fixed-size executor services for different subsystems (such as physics, explosions, or hoppers). Each subsystem gets its own isolated pool, preventing task starvation and ensuring that one system's nested submissions do not block another.

Entity Snapshot Helpers
Mutable entities like item entities are not thread-safe. ParallelCore includes utility methods to collect and deep-copy entities on the main thread before parallel execution begins. Worker threads receive immutable snapshot records, eliminating data races.

Command System Integration
A /parallel command (with a /pc alias) is provided for administrators. Other mods can register their own subcommands under this root, allowing runtime configuration and status reporting for each parallelized subsystem.

Shared Configuration Base
A configuration base class helps mods persist their settings in a single shared JSON file, with each subsystem owning a dedicated section. This keeps all parallel-related configuration in one place.

Recommended Usage Pattern: Parallel Read, Serial Write

The core design follows a read-parallel, write-serial pattern to ensure thread safety without complex locking:

1. Collect on Main Thread – Before parallel execution, collect all necessary positions, entity references, or mutable data on the main thread where world access is naturally safe.

2. Enter Safe Zone – Call SafeLevelAccess.enterSafeZone() to mark the beginning of parallel read operations. This bypasses vanilla thread checks and enables thread-safe chunk lookups.

3. Execute Parallel Reads – Submit tasks to isolated thread pools. Worker threads can safely read block states, item entity snapshots, and chunk data concurrently from immutable or deep-copied sources. No writing to the world occurs during this phase.

4. Join and Merge – Wait for all parallel tasks to complete, collecting computed results (e.g., new block positions, item transfers, or state changes) from each worker.

5. Leave Safe Zone – Call SafeLevelAccess.leaveSafeZone() to restore vanilla thread-safety checks.

6. Apply Changes Serially – Back on the main thread, apply all accumulated modifications to the real world. This serial write-back prevents concurrent modification and keeps vanilla assumptions intact.