Commands Reference

Type /bench or /bench help to list the commands in-game. An unknown sub-command prints an error followed by the same list.

Player or console? /bench start, /bench stresslimit, /bench tier, /bench custom run, /bench gui and the tests marked "No" in the test tables must be run by a player connected to the server: they rely on chunk activation, entity ticking and player state save/restore. /bench zones tp, /bench reports and /bench reports gui, /bench lang auto, /bench monitor gui and /bench monitor bars <metric> also need a player. The other commands also work from the console.

Every command requires voxelbench.use. The Permission column shows what a command needs on top of it (voxelbench.use = nothing more); see Permissions for the details.

General Commands

Benchmark Commands

/bench zones shows the zones of the last run that laid some out since the server started (a benchmark, stress limit, tier, custom profile or auto-bench run; /bench test records none) and names the world that run used. A temporary world is deleted at the end of its run, and its zones with it: the command then says that the world no longer exists, and points at no other world. With no run recorded, it shows the default zone of the pinned world, if there is one. clean removes every entity except players, paintings and item frames within 200 blocks of each zone, and only in a voxelbench_* world: in any other world, the main world or a pinned world with another name, it removes nothing and says why. Each test already removes what it spawned, including when /bench stop interrupts it; the extra sweep of the fixed test spots that follows /bench stop also only happens in a voxelbench_* world.

VoxelBench 2.0.2 and earlier: on Paper and Spigot, /bench start, /bench stresslimit, /bench tier and /bench custom run removed villagers, animals (tamed and named ones included), golems, dropped items, minecarts and boats from every loaded world as the run started; /bench stop removed villagers, cats, golems and dropped items around fixed spots of the test's world, whatever it was; and without a pinned world, /bench zones clean swept a zone of the main world. Update before running them on a server whose worlds matter. See Safety Guards.

Full Benchmark

/bench start

Runs the test suite in three phases: hardware, then gameplay, then CPU (see Benchmarks). Results are submitted to voxelbench.com.

The arguments can be given in any order:

Examples:

/bench start 5
/bench start warmup 3
/bench start force warmup 3

When confirmation.require-confirmation is true (the default), VoxelBench runs pre-flight checks before starting. If nothing is found, the benchmark starts immediately. Otherwise an inventory screen lists the findings and you click to start or cancel. Critical findings, such as targeting a world that is not a voxelbench_* world, can only be overridden by a player with voxelbench.start.force.

Multi-Run Mode

With more than one run (or with warmup), VoxelBench pre-loads the chunks around the test zones, reuses the same zones and world for every run, and waits 10 seconds before the next run. In a voxelbench_* world (the temporary world, or one made with /bench world create) it also resets the test regions between runs, so that each run starts from freshly generated terrain; in any other world it forces nothing and deletes nothing, says so, and the runs reuse the chunks already generated. Each run produces its own report. See Benchmark Worlds.

VoxelBench 2.0.2 and earlier: without a pinned world, a multi-run session reset regions of the server's main world between runs. Update before running one, or pin a voxelbench_* world.

Benchmark Worlds

Individual Test Commands

Test IDs are case-insensitive, and - or _ are ignored: chunkLoading, chunkloading and chunk_loading are the same test. Positional values (below) only work with the names of the positional table, in any case; with another spelling, such as chunk_loading, the test takes key=value pairs.

Available Tests

VoxelBench ships 26 built-in tests. The "Console" column tells whether the test can be started from the console. When a player-only test is launched from the console, the error message names a few examples and points to /bench test list; the tables below are the full list.

Every gameplay test except worldSave writes to the world, so /bench test runs it in the pinned world or in a temporary world, never in the world you are in, and refuses it when neither is available (always the case on Folia without a pinned world). See Benchmarks.

Hardware

Single-Core CPU

Gameplay

Test Parameters

Most tests run with their default values when no parameter is given. Two syntaxes exist, depending on the name you type.

Positional values. These names take plain values in a fixed order:

Named values. Every other test ID (lightingUpdate, entityCollision, tickingTileEntity, villagerTrading, projectileStorm, entityCramming, playerWorldLoad, singleCoreBenchmark, and tests added by extensions) takes key=value pairs:

/bench test projectileStorm projectilesPerWave=250 durationSeconds=20
/bench test singleCoreBenchmark durationSeconds=15 kernel=float

The parameter names are the ones used in custom profiles; the bundled custom_benchmarks/showcase.yml documents them for every test. Out-of-range key=value values are clamped, with a warning. An out-of-range positional value is refused in most cases, with an error that gives the allowed range.

Stress Limit Commands

See Stress Limit for the stress types and the /bench tier options.

Custom Profile Commands

/bench custom run also accepts warmup and a run count, but profiles currently always run a single iteration. Without voxelbench.stresslimit, stress limit profiles are left out of the tab completion of run, of the profiles screen of the GUI and of the list of available profiles printed after an unknown name; list and info still show them. See Benchmarks - Custom Profiles.

Monitoring Commands

See Monitoring for details.

Profiling Commands (experimental)

Sample the tick threads with Java Flight Recorder and show which plugins and methods run on them. Nothing leaves the server unless you upload a profile yourself with /bench profile upload, or share one by public link with /bench profile share. Captures are refused while a benchmark, stress limit, tier or auto-bench run is in progress, or a /bench test whose result is sent to voxelbench.com, and for 30 s after it.

See Profiling for how to read the results and how automatic dumps on lag work.

Memory Inspection Commands (experimental)

See what fills the server's memory, per plugin, write a full heap dump — the equivalent of spark's heapsummary and heapdump — and analyse it in a separate process to see which plugin retains the memory. A summary or an analysis leaves the server only when you upload it with /bench memory upload or share it by public link with /bench memory share; a heap dump never leaves it, by any command. Refused while a benchmark, stress limit, tier or auto-bench run is in progress, or a /bench test whose result is sent to voxelbench.com, and for 30 s after it.

<id|#|last> names a summary or an analysis: its id, a unique prefix, last (the newest of both) or #N (rank among summaries and analyses together, newest first). See Memory Inspection for how to read a summary or an analysis, what a dump costs and how to open it, and what leaves when you send or share a report.

Forms for Commands Typed Without Options

Typed alone by a player, /bench profile, /bench memory summary, /bench memory dump and /bench memory analyze open a form with their options instead of running with the defaults: a native dialog on Paper 1.21.6 and later, an inventory screen elsewhere (click: next value, shift-click: previous). It offers the duration and sampling interval, live or all objects, gzip, the analysis mode, which dump to analyse, and whether to keep, share or upload the result — only what your permissions and config.yml allow.

The form only builds the command and runs it as if you had typed it: its permissions and refusals apply, and a dump still shows its preview and waits for its confirmation. The console, and any command typed with options, work as before (from the console, /bench profile alone still captures 30 s).

Each form reopens on your last choices (per player, kept across restarts in plugins/VoxelBench/form-choices.json): duration, interval, live or all objects, gzip, analysis mode, target plugin. A choice that is no longer offered (a permission removed, a setting changed) falls back to its default. Three choices always start from their default and are never carried over: keeping, sharing or uploading the result, forcing a dump past the watchdog, and which dump to analyse (the newest one).

Confirming a Preview

A heap dump, and upload/share … preview for profiles and memory reports, show a preview first and wait for confirm. There are three ways to give it, and all of them run that same … confirm command, with the same checks: same player or console, within 60 s, same options, file unchanged, permissions.

• /bench confirm (or /b confirm) confirms the last preview of whoever types it — the console included — so /bench memory dump live gzip analyze full share is followed by /bench confirm instead of the whole line again;
• a click on the confirmation line in chat;
• for a player, Yes in the window that opens with the preview: a native dialog on Paper 1.21.6 and later, an inventory screen elsewhere. No (or Escape) does nothing. confirmation.popup: false in config.yml turns the window off.

Report Commands

Server Verification Commands

Account Linking Commands

Internal Commands

/bench autobot and /vbautobot are used only by the VoxelBench auto-bench agent. They do nothing unless the one-time code they carry is validated by the backend. You never need to type them.