What is VoxelBench?

VoxelBench is a comprehensive benchmarking plugin that measures your Minecraft server's real-world performance through 20+ hardware and gameplay tests. It produces a single VoxelScore that lets you compare your server against others on a global leaderboard.

Whether you're a hosting provider evaluating hardware, a server admin optimizing configurations, or a player curious about your server's capabilities — VoxelBench gives you the numbers to back up your decisions.




Benchmark Tests

The built-in benchmark runs tests in three phases, ordered for JVM warm-up accuracy. Custom profiles can re-order or subset these freely.

Phase 1 — Hardware

• Single-Core CPU — Raw single-thread ops/sec on the main thread (the factor that limits
  Minecraft)
  
• Multi-Core CPU — Parallel computation across all CPU cores
  
• Memory — RAM bandwidth, latency, sequential & random access
  
• Disk I/O — Sequential read/write + random 4K operations
  
• Network — NBT serialization/deserialization throughput
  

Phase 2 — Gameplay

• Chunk Loading — Parallel chunk generation across multiple dispersed zones
  
• Mob AI — Villager trading + hostile invasion with pathfinding (250 villagers, 200
  hostiles)
  
• Hopper Transfer — Item pipeline throughput with parallel hopper chains
  
• TNT Explosions — Chain reactions and block destruction across zones
  
• Redstone Circuits — 1,600 piston clocks with slime block pushing
  
• Block Physics — 24,000 falling blocks (sand, gravel, anvils) with water/lava
  
• Chunk Ticking — Random tick processing (crops, saplings, grass spread)
  
• Lighting Updates — Light propagation engine across corridors and multi-level structures
  
• Tile Entities — 40,000 furnaces, hoppers, and spawners ticking simultaneously
  
• Bone Meal Growth — Tree generation and crop acceleration
  

Extra Tests (standalone)

• Projectile Storm — Continuous barrage of arrows, snowballs, and eggs (PvP simulation)
  
• Entity Cramming — Hundreds of entities in confined cells (mob farm simulation)
  
• Multi-Zone Chunk Load — Chunk load stress across N independent zones
  

VoxelScore & Global Leaderboard

All test results are combined into a single VoxelScore computed by the backend. Weighted
scoring:

• Single-Core CPU (45%) — The most important factor for Minecraft
  
• Gameplay (35%) — Real-world server workloads
  
• Hardware (20%) — Raw system capabilities
  

Compare your server against others on voxelbench.com with detailed breakdowns, history, and rankings.



Benchmark World Selection

Pick exactly which world your benchmarks run in — perfect for hosting providers and admins who want to keep tests isolated from their main map.

• Pin any loaded world — set it once with /bench world set <name>, every future /bench start, /bench stresslimit and /bench test use it.
  
• Create flat benchmark worlds in one command — auto-prefixed voxelbench_, fixed seed for repeatable terrain across hardware.
  
• Multiverse-Core integration — created worlds appear in /mv list; deletion cleans up MV's registry. Works on MV 4.x and 5.x; falls back to native Bukkit when MV is not installed.
  
• Crash-proof player rescue — disconnecting or restarting the server mid-benchmark no longer strands you inside the bench world. Your pre-test position and gamemode are persisted to disk and restored
  automatically the next time you log in.
  
• Safe by default — only voxelbench_* worlds can be deleted (never your survival map), the pin is auto-cleared if its world is deleted, and a delete is refused while a benchmark is
  running in that world.
• Worlds survive restarts — voxelbench_* worlds created via /bench world create auto-reload on every server start, even without Multiverse-Core.
• Stale folder protection — recreating a world over an existing one used to produce mixed-terrain chunks; the command now refuses cleanly.
  
  

Stress Limit Mode

Go beyond benchmarking — find your server's breaking point.

• Progressively increases load with exponential tiers (x1.2 multiplier) until TPS drops
  below 18
  
• 6 stress categories: Mobs, Chunks, Hoppers, Explosions, Redstone, Entity Collisions
  
• Binary refinement after detecting the breaking point (2 bisections for precise results)
  
• Early skip for ultra-stable tiers (skips after 5s if server is clearly not stressed)
  
• Per-tier hover tooltips in chat with full metrics (percentiles, StdDev, samples, GC)
  
• Results sent to backend for scoring and online viewing
  

Custom Benchmark Profiles

Compose your own benchmark recipes from YAML — no code required. Drop a file in plugins/VoxelBench/custom_benchmarks/, pick which tests run, in what order, with what parameters.

• /bench custom run <name> — execute a profile
• /bench custom list — see what's loaded
• /bench custom info <name> — view steps and parameters
• /bench custom reload — re-scan the folder without restart

Ships with three preset profiles out of the box: standard.yml (mirrors the
built-in benchmark), showcase.yml (every test + every parameter, fully
commented — use as a reference), and example.yml (minimal starter).

Profiles carry their own name, description, author, version and tags.
Sharing a profile = sharing one YAML file. The backend uses a normalized
profile hash to recognize the same recipe across different servers, so
community-shared profiles get their own comparable leaderboards.

Real-Time Monitoring Dashboard

Built-in HTTP/HTTPS web server for live performance monitoring — no external tools required.

Web Dashboard

• Live graphs: TPS, MSPT, memory usage, player count
  
• Configurable port and bind address
  
• JSON API at /api/metrics for external tools integration
  
• Toggle dashboard mode (full HTML) or API-only mode
  

HTTPS & Security

• Auto-generate self-signed SSL certificates (/bench monitor https generate)
  
• Custom keystore support
  
• Password authentication with SHA-256 hashed credentials + session timeout
  
• API key system for programmatic access (separate keys for pull and push)
  
• IP whitelist with per-endpoint filtering (dashboard only, API only, or both)
  

Boss Bar Monitoring

• In-game boss bars showing live metrics above the hotbar
  
• Available metrics: TPS, MSPT, RAM, CPU, entities, chunks, players
  
• Toggle all at once with /bench monitor bars all or individual metrics
  

Push Mode

• Automatically send metrics to Grafana, Prometheus, or any HTTP endpoint
  
• Configurable interval, API key authentication, SSL support
  
• Test connection with /bench monitor push test
  

Report System

• Three report types: Standard Benchmark, Unit Test, Stress Limit
  
• Local JSON storage with configurable retention (max age, max per type, auto-cleanup)
  
• Side-by-side comparison between any two reports
  
• Automatic display after test completion
  
• Online viewing and sharing via voxelbench.com
  
• Multi-run mode: run 5+ benchmarks with delays for statistical variance reduction
  
• Account linking with /bench link for permanent report history
  

Example : https://voxelbench.com/en/report/vxb_vz8e3gw2



Plugin Integrations

Auto-detected — zero configuration required. Just install the plugin and VoxelBench hooks in
automatically.

• Multiverse-Core — Auto-detected (4.x and 5.x). Benchmark worlds created via /bench world create are imported into MV automatically; deletion cleans up MV's registry. Falls back to
  native Bukkit when MV is not installed.
  
• PlaceholderAPI — %voxelbench_tps%,
  %voxelbench_score%, %voxelbench_mspt%,
  %voxelbench_rank%
  
• Dynmap — Entity density heatmap (color-coded), performance alert markers, active test zone
  markers
  
• Spark — TPS averages (10s, 1m, 5m, 15m), MSPT statistics (mean, median, P95), GC metrics
  
• DiscordSRV — Benchmark completion notifications, TPS drop alerts to configurable channel
  
• LiteBans — Ban/mute/kick event detection for backend monitoring
  

Inventory GUI

Every feature accessible through clean inventory menus — no commands to memorize.

• Main dashboard with all sections
  
• Test category browsers (Hardware, Gameplay, Single-Core)
  
• Report list with pagination, detail view, and side-by-side comparison
  
• Server info panel (CPU, RAM, Disk, Network, Java, plugins list)
  
• Monitoring control panel (web server, boss bars, push mode, auth, whitelist, HTTPS)
  
• Settings and configuration
  
• Score dashboard with rank display
  

Commands

Benchmarking
Information & Reports
Custom Profiles
Monitoring
World Management
Account & Configuration

Permissions


Privacy & Security

• Three anonymization levels:
  
  • NONE — Full data (not recommended for public servers)
    
  • PARTIAL — IP and MAC hashed, CPU and disk models visible (default)
    
  • FULL — Maximum privacy, generic hardware types, hidden plugin list
    
• All reports signed with HMAC-SHA256 for tamper-proof results
  
• Backend communication via HTTPS exclusively
  
• Automatic update checker (opt-out via config)

• Reports from extension-API tests carry an extra "provider" field so the backend can distinguish first-party vs third-party tests in leaderboards. Extension test results may be excluded from public rankings depending on backend policy.

Coming soon — Extension API

A new public API will let third-party plugin developers register their own benchmark tests against VoxelBench: typed parameters, declared output metrics, automatic Bukkit event hooks, JUnit test-doubles.

Installation

1. Download VoxelBench.jar and place it in your server's plugins/ folder.
   
2. Start (or restart) your server. VoxelBench generates its default configuration.
   
3. Use /bench gui to open the main menu, or /bench start to launch a benchmark.
   
4. (Optional) Link your account with /bench link for online leaderboards.
   
5. (Optional) Start the monitoring dashboard with /bench monitor web start.
6. (Optional) Customize your benchmarks — drop a YAML file in plugins/VoxelBench/custom_benchmarks/ and use /bench custom run <name>. The bundled showcase.yml shows every test + every parameter.
   
   

Requirements: Java 16+ (Java 21 recommended) • Minecraft 1.17+ • Spigot, Paper, Folia, Arclight, Purpur, or Pufferfish


Supported Languages

• English (en_US) — Complete
  
• French (fr_FR) — Complete
  
• Auto-detects player language from Minecraft client
  
• Server-wide override option in config

Links

• Website & Leaderboard
  
• Discord
  
• Twitter/X