Documentation

Getting Started

Install VoxelBench, run a first benchmark or a single test and read the results, then choose where benchmarks run, link and verify the server, and turn on monitoring.

Requirements

  • Minecraft Server: Spigot, Paper (and Paper forks such as Purpur), Folia, or a Bukkit hybrid server. See Compatibility.
  • Minecraft Version: 1.17 or newer, including the 26.x releases
  • Java: the version your Minecraft server requires (Java 16 at minimum; 21 for 1.20.5+, 25 for 26.x)
  • Permissions: Operator (OP), or voxelbench.use plus the permission of each command (for example voxelbench.start for /bench start; see Permissions)

Installation

  1. Download the latest VoxelBench JAR from voxelbench.com or GitHub Releases
  2. Place the JAR file in your server's plugins/ folder
  3. Restart (or start) your server
  4. VoxelBench will generate its configuration files in plugins/VoxelBench/

First Run

After installing VoxelBench, you can start using it immediately:

Open the GUI

/bench gui

This opens the main inventory interface where you can access all features visually: tests, stress limit, monitoring, reports and settings.

Run Your First Benchmark

Join the server and run, in-game:

/bench start

A full benchmark needs a connected player, so it cannot be started from the console. It runs in three phases:

  • Hardware: disk, network and memory
  • Gameplay: chunk loading, hoppers, world save, explosions, redstone, block physics, chunk ticking, lighting, tile entities, mob AI and bone meal growth
  • CPU: single-core and multi-core, run last so the JVM is fully warmed up

Before starting, VoxelBench runs pre-flight checks (a pinned world that is not flat or not a benchmark world, other players online, current server load, free hosting, plugins that may interfere). If something is found, an inventory screen lists it and you confirm or cancel. The full benchmark takes several minutes depending on your server's hardware.

View Results

When the benchmark ends, the report is saved locally in plugins/VoxelBench/reports/benchmark/, then submitted to voxelbench.com, which computes the VoxelScore. When the score comes back, it is displayed in chat with a summary and a link to the online report, and written into the local report. If the submission fails, the local report is kept without a score and chat says why.

Run a Single Test

If you want to test a specific aspect of your server:

/bench test chunkLoading
/bench test mobSpawn
/bench test disk 4 8 512M 3

Use /bench test without arguments to see all available tests. See Commands for the parameters each test accepts.

Optional Setup

Choose Where Benchmarks Run

Benchmarks spawn entities and place blocks in their test zones. By default, a run with no pinned world uses a temporary flat world, deleted at the end (on Folia, which cannot create one, it uses the main world). To reuse the same world every time, create a dedicated flat world and pin it:

/bench world create bench
/bench world set voxelbench_bench

See Benchmark Worlds and Commands - Benchmark Worlds.

Link your server to your VoxelBench account to keep its reports in your account (private, kept 30 days on Free and 1 year on Pro, instead of 30 minutes):

/bench link

See Account Linking for details.

Verify Server Ownership

Once the server is linked, prove that you control it at its public address (auto-bench needs it): generate a code on the server's page on voxelbench.com, then run:

/bench verify VOXEL-XXXXX

See Server Verification for details.

Set Up Monitoring

Start the real-time performance dashboard:

/bench monitor web start

By default it only listens on the server machine: open http://localhost:8080 there. To reach it from another machine, the dashboard needs a password first (see Monitoring). See Monitoring for full configuration.

Change Language

VoxelBench automatically detects each player's Minecraft client language. To override:

/bench lang en_US
/bench lang fr_FR
/bench lang auto

What's Next?