HerculiPaper is a high-performance Minecraft server implementation designed to support 1000+ players while maintaining 20 TPS and preserving vanilla-like gameplay. Built on top of Purpur 1.21.8, it brings ShreddedPaper-style regionization, advanced threading optimizations, and targeted performance improvements.
- 🏗️ Regionized Threading: Advanced region-based task scheduling for true parallelism
- ⚡ Optimized Hot Paths: Thread-safe entity tracking, collision detection, and packet broadcasting
- 🔄 Async Operations: Non-blocking chunk I/O, player saves, and portal teleportation
- 📊 Smart Caching: WeakSeqLock-based entity snapshots and packet caching
- 🎯 Allocation Reduction: Thread-local pools and optimized data structures
- 📈 Real-time Monitoring: Built-in performance profiling and diagnostics
Target: 1000+ concurrent players at stable 20 TPS
Approach: Performance-first with vanilla gameplay preservation
Philosophy: Enable through configuration, disable for compatibility
- Region Scheduler: Parallel processing of world regions
- Thread-Safe Collections: Concurrent entity maps, player tracking, and scoreboards
- Async Chunk Pipeline: Non-blocking chunk loading and generation
- Safe Event Dispatch: Bukkit events properly synchronized to main thread
- PerThreadNeighborUpdater: Thread-local wrapper for
NeighborUpdaterto avoid cross-thread races during redstone/shape updates
- Threaded Broadcasting: Parallel packet sending with recipient queues
- Packet Caching: Reuse common packets across players
- Lazy Network Writes: Batch and merge network operations
- Ping Deferral: Reduce network overhead during high load
- Fast Viewer Membership Map: O(1) membership checks to cut CHM churn in tracking
- WeakSeqLock Integration: Lock-free entity tracking snapshots
- Collision Pooling: Thread-local allocation pools for collision detection
- Tracking Caps: Configurable limits to prevent performance degradation
- Optimized Pathfinding: Async pathfinding recalculation
- NaturalSpawner Hot Path Optimizations: Early exits and reduced per-attempt work
- Hoisted per-group
NearbyPlayerslookup and reused player array - Per-invocation
mobsAt()cache keyed by(ChunkPos, category) - Capped initial random attempts by remaining capacity and attempt cap
- Early-return when
maxSpawns <= 0and break when no players in view-distance
- Hoisted per-group
- AI Nearest-Player Fast Path:
EntityGetter.getNearestPlayer(...)and related queries backed by regionizedNearbyPlayerswhere safe - AI Tick Throttling: Config-gated goal selector throttling for far entities (tick every 4th tick beyond threshold)
- Tracker Optimization Suite:
- Replaced
ConcurrentHashMapvanish cache with fastutilObject2LongOpenHashMap - Batched viewer array rebuilds (immediate on ≥8 changes, deferred otherwise)
- Eliminated redundant map lookups in tracking hot path
- Skip tracking updates for stationary entities (moved <1.0 blocks)
- Skip tracking every other tick for far entities (>64 blocks from players)
- Replaced
- AI Query Caching: 4-tick cache for nearest player lookups to reduce pathfinding overhead
- Used by TemptGoal and other AI goals that query for nearby players
- Player Block Check Optimization: Skip expensive block intersection checks for stationary players (moved <0.1 blocks)
- Async Join Protocol Changes: Eliminate main thread blocking during player joins (4ms/join → ~0ms)
- Built-in Profiler: JFR integration and custom metrics
- Real-time Commands:
/herculicommand suite for live monitoring - Visual Chunk Maps:
/herculi mpmapfor region visualization - Performance Probes: Detailed metrics for all optimizations
Initial setup:
./gradlew applyAllPatchesBuild server jar:
./gradlew createMojmapBundlerJarJars are produced under purpur-server/build/libs.
- Download or build the HerculiPaper jar
- Replace your existing server jar
- Start the server -
config/herculi.ymlwill be created automatically - Configuration is pre-optimized for 1000+ players - no changes needed!
- Use
/herculicommands to monitor performance
HerculiPaper comes pre-configured for 1000+ players. The default config/herculi.yml enables all performance optimizations while maintaining vanilla compatibility.
threading.enabled: true # Enable regionized threading
threading.region_pool_size: 0 # Auto-detect CPU cores
threading.region_shift: 4 # 16x16 chunk regionsnetworking.parallel_flush_enabled: true # Parallel network flushing
broadcasting.threaded.enabled: true # Threaded packet broadcasting
broadcasting.threaded.maxQueuesTotal: 50000 # Support 1000+ players
broadcasting.threaded.perTickDrainBudget: 4 # Drain batches per tick
broadcasting.threaded.dropPolicy: coalesce # Drop/coalesce policy
broadcasting.threaded.drainIntervalMs: 2 # Drain cadence (ms)fairness.enabled: true # Resource fairness system
portals.routing_enabled: true # Async portal teleports
async.player_save.enabled: true # Non-blocking player saves
async.player_save.pool_size: 2 # Worker threads
threading.chunk_io_enable: true # Async chunk I/O pipeline
threading.chunk_io_max_inflight: 32 # Max parallel I/O
# Entity tracking & AI optimizations
entities.tracker.coalesce.enabled: true # Coalesce packets for far viewers
entities.tracker.coalesce.farDistance: 96 # Distance threshold (blocks)
entities.tracker.coalesce.interval: 3 # Send to far viewers every N ticks
entities.ai.throttle.enabled: true # Throttle AI for far entities
entities.ai.throttle.distanceSq: 4096 # Distance² threshold (64²)profiling.enabled: true # Built-in performance monitoring
guardrails.enabled: true # Safety checks and warnings- Performance First: All optimizations enabled by default
- Vanilla Preservation: Gameplay mechanics unchanged
- Safety Nets: Guardrails prevent threading issues
- Monitoring Ready: Diagnostics enabled for production use
/herculi profile start [jfr] # Start performance profiling
/herculi profile stop # Stop profiling and save results
/herculi locks # Show region lock statistics
/herculi queues # Display executor queue status
/herculi probe [reset] # Detailed performance metrics
/herculi mpmap [player] # Visual chunk/region map
/herculi reload # Reload configuration
- Real-time TPS: Use
/tpsfor server performance - Memory Usage: Use
/memoryfor heap statistics - Region Status: Use
/herculi locksfor threading info - Network Load: Use
/herculi probefor packet metrics
config/herculi.yml- Main performance configurationconfig/paper-global.yml- Paper settings (inherited)config/purpur.yml- Purpur features (inherited)
HERCULI.md- Detailed feature documentationtodo-tasks.txt- Development progress trackingdocs/- Additional technical documentation
| Metric | Target | Achieved Through |
|---|---|---|
| Players | 1000+ concurrent | Regionized threading + optimized broadcasting |
| TPS | Stable 20 TPS | Async operations + allocation reduction |
| MSPT | <50ms average | Parallel processing + smart caching |
| Memory | Reduced allocation | Thread-local pools + object reuse |
| Network | High throughput | Packet batching + lazy writes |
- Lock-free snapshots for entity tracking
- Reduced contention in high-concurrency scenarios
- Stable iteration over volatile collections
- Resource budgets prevent any single operation from monopolizing CPU
- Balanced processing across regions and players
- Configurable limits for different workload types
- Non-blocking chunk I/O with configurable parallelism
- Async player saves with batching
- Portal teleportation without main thread blocking
✅ Thread Safety: All optimizations include proper synchronization
✅ Bukkit Compatibility: Events fire on correct threads
✅ Plugin Support: Full compatibility with existing plugins
✅ Monitoring: Built-in diagnostics and performance tracking
✅ Graceful Degradation: Features can be disabled if needed
# Check overall performance
/herculi probe
# Monitor region threading
/herculi locks
# View network performance
/herculi queues
# Visual chunk status
/herculi mpmap- Region task balance - Should be evenly distributed
- Broadcast queue depth - Should stay low under normal load
- Cache hit rates - Higher is better for network performance
- Async operation counts - Indicates offloaded work
HerculiPaper builds on Purpur and Paper. All upstream licenses apply to original material.
Performance patches are licensed under MIT. Upstream code retains original licensing.
Traditional servers struggle with 200+ players due to single-threaded limitations.
HerculiPaper breaks these barriers through:
- Parallel Processing: Multiple CPU cores working simultaneously
- Smart Optimization: Target bottlenecks with surgical precision
- Vanilla Preservation: No gameplay changes, just pure performance
- Production Ready: Built for real-world high-load scenarios
Result: Servers that scale linearly with hardware instead of hitting artificial limits.
Below is the upstream Purpur README kept for reference.
Purpur is a drop-in replacement for Paper servers designed for configurability, new fun and exciting gameplay features, and performance built on top of Paper.
Join us on Discord:
Downloads can be obtained from the downloads page or the downloads API.
Downloads API endpoints:
- List versions of Minecraft with builds available:
https://api.purpurmc.org/v2/purpur - List builds for a version of Minecraft:
https://api.purpurmc.org/v2/purpur/<version> - Download a specific build of a specific version:
https://api.purpurmc.org/v2/purpur/<version>/<build>/download - Download the latest build for a version of Minecraft:
https://api.purpurmc.org/v2/purpur/<version>/latest/download
All patches are licensed under the MIT license, unless otherwise noted in the patch headers.
See PaperMC/Paper, and PaperMC/Paperweight for the license of material used by this project.
Maven
<repository>
<id>purpur</id>
<url>https://repo.purpurmc.org/snapshots</url>
</repository><dependency>
<groupId>org.purpurmc.purpur</groupId>
<artifactId>purpur-api</artifactId>
<version>1.21.8-R0.1-SNAPSHOT</version>
<scope>provided</scope>
</dependency>Gradle
repositories {
maven("https://repo.purpurmc.org/snapshots")
}dependencies {
compileOnly("org.purpurmc.purpur:purpur-api:1.21.8-R0.1-SNAPSHOT")
}Yes, this also includes all API provided by Paper, Spigot, and Bukkit.
First, clone this repository. Do not download it.
Then run the following command in the root directory:
./gradlew applyAllPatches
The project is now ready for use in your IDE.
See CONTRIBUTING.md.
Use the command ./gradlew build to build the API and server. Compiled JARs
will be placed under purpur-api/build/libs and purpur-server/build/libs.
These JARs are not used to start a server.
To compile a server-ready purpurclip jar, run ./gradlew createMojmapBundlerJar.
To install the purpur-api and purpur dependencies to your local Maven repo, run ./gradlew publishToMavenLocal. The compiled purpurclip jar will be in purpur-server/build/libs.
|
YourKit, makers of the outstanding Java profiler, support open source projects of all kinds with their full-featured Java and .NET application profilers. We thank them for allowing us to use their software so we can make Purpur the best it can be. |
JetBrains, creators of the IntelliJ IDEA, supports Purpur with one of their Open Source Licenses. IntelliJ IDEA is the recommended IDE for working with Purpur, and most of the Purpur team uses it. |
