Benchmark Worlds

By default, benchmarks run in a flat world created for the run and deleted afterwards; you can instead pin a world that every run uses. Worlds created by VoxelBench are named voxelbench_<name>, and its safety guards rely on that prefix (see Safety Guards).

Two settings of config.yml control it (see Configuration):

benchmark:
  target-world: ""        # Pinned world, set with /bench world set
  auto-temp-world: true   # Temporary world when no world is pinned

Where Runs Take Place

Benchmarks, Stress Limit and Custom Profiles

/bench start, /bench stresslimit, /bench tier and /bench custom run pick their world in this order:

1. The pinned world (/bench world set), if it is loaded. A pinned world that is not loaded is ignored, with a warning in chat.
2. A temporary world, when benchmark.auto-temp-world is true (the default): a flat world created for the run and deleted at the end (see Temporary Worlds). A custom benchmark profile can override this setting with its own options.auto-temp-world.
3. The server's main world (the first world the server loads, not the world you are in), with auto-temp-world: false, or when the temporary world cannot be created. On Folia, this is always the case without a pinned world. A failed creation is only reported in the server log.

With auto-temp-world: false and no pinned world, the pre-flight check of /bench start reports a critical "No target world configured" finding, which only a player with voxelbench.start.force can override. The other commands start without this check, and so does /bench start when confirmation.require-confirmation is false (see Configuration).

Auto-bench jobs started from voxelbench.com follow the same rules as the command of their mode.

Individual Tests

/bench test (the command, the test GUI, and auto-bench jobs in test mode) is stricter with the tests that write to the world, that is every gameplay test except worldSave:

• they run in the pinned world, otherwise in a temporary world created for the test, even if you are standing in the main world;
• when neither is possible (auto-temp-world: false, failed creation, Folia without a pinned world), the test is refused instead of falling back to your world or to the main world.

Hardware and CPU tests, worldSave and tests added by extensions run in the pinned world, or in the world you are in (the main world from the console). See Benchmarks for the details, including how players are taken to the test zones and brought back.

Temporary Worlds

A temporary world is named voxelbench_temp_<timestamp>. It is a flat world (bedrock, two layers of dirt, grass) with the seed benchmark and no structures, so every run starts on the same terrain.

• Creation takes a few seconds at the start of the run. When Multiverse-Core is installed, the world is also imported into it (see Multiverse-Core).
• Deletion happens a few seconds after the run ends, including after a failure or /bench stop. Players still inside are first moved to another world.
• A multi-run session (/bench start <runs>, /bench start warmup) uses one temporary world for all its runs and deletes it after the last one.
• If the server stops during a run, the world cannot be deleted during the shutdown: it is deleted at the next start (see Restarts and Crashes).

Folia cannot create a world while the server runs, so no temporary world is ever created there (see Folia).

Pinning a World

/bench world set <world> pins a loaded world, named in full, for every run: benchmarks, stress limit, tiers, custom profiles and individual tests. The pin is saved in config.yml as benchmark.target-world and survives restarts. /bench world unset removes it, and so does deleting the pinned world with /bench world delete.

/bench world create arena
/bench world set voxelbench_arena

When to Pin a World

• You run tests one by one. Without a pin, each /bench test of a test that writes to the world creates and deletes its own temporary world, which takes a few seconds every time.
• Multi-run sessions. A session takes its world before preparing anything, prepares its test zones in it before the first run and, between runs, deletes the region files around them so that each run starts from freshly generated terrain — only in a voxelbench_* world. In any other world (a pinned world with another name, the main world after a fallback), it neither force-loads nor deletes anything, prints a message saying so, and the runs reuse the chunks already generated.
• Folia. Without a pinned world, /bench test refuses every test that writes to the world.
• Servers that refuse the temporary world, as some hybrid servers do. Runs then fall back to the main world and /bench test refuses. A world created once with /bench world create avoids that.

Choosing the World

• Pin a world that holds nothing you want to keep, ideally one made with /bench world create. Tests build their zones in it and clear them at the end without restoring the original terrain (only playerWorldLoad restores the blocks it changes), and multi-run sessions delete region files in it. Test zones sit between 1,000 and 10,000 blocks from the world's spawn, and at fixed spots between x = z = 50,000 and 100,000.
• Any loaded world can be pinned, your main world included: the voxelbench_ prefix is not required. /bench start then reports a critical "Non-benchmark world targeted" finding, which only a player with voxelbench.start.force can override; the other commands do not ask.
• Prefer a flat world. On other terrain, results depend on the map and cannot be compared with runs on flat terrain. /bench start, /bench stresslimit and /bench tier warn when the pinned world is not flat.

Commands

Every /bench world command needs voxelbench.world (default: op) on top of voxelbench.use, and works from the console. /bench worlds is an alias of /bench world. The same node also allows /bench zones tp and /bench zones clean, which only removes entities in a voxelbench_* world. See also Commands and Permissions.

/bench world create refuses a name already taken by a loaded world, and a voxelbench_<name> folder that already holds a world on disk (see Safety Guards).

/bench world delete refuses a world whose name does not start with voxelbench_, a world that is not loaded, and a world where a test is running (stop it first with /bench stop). Players inside are moved to the spawn of another world, then the world is unloaded and its folder deleted.

Folia

Folia cannot create or unload a world while the server runs. On Folia:

• no temporary world is ever created. Without a pinned world, /bench start, /bench stresslimit, /bench tier and custom profiles run in the main world, and the pre-flight check does not flag it; /bench test refuses every test that writes to the world, and says why;
• /bench world create and /bench world delete fail;
• only a world the server loads at startup can be pinned, in practice the main world. Tests then build and clear their zones in it; multi-run sessions do not reset its regions. If your map matters, benchmark a copy of the server.

See also Compatibility.

Restarts and Crashes

At every start, before any run can begin, VoxelBench:

• deletes the leftover temporary worlds, whether Multiverse-Core loaded them again or only their folder remains. The console lists them ("Cleaned up N orphan temporary benchmark world(s) from a previous session"). This covers a server stopped during a run as well as a crash.
• loads the worlds you created with /bench world create. Bukkit does not remember worlds created by a plugin, so VoxelBench loads each voxelbench_<name> folder that holds a world and that nothing else has loaded ("Auto-loaded N persistent benchmark world(s) from disk"). A pin on such a world keeps working after a restart.

A clean stop during a run (/stop, a restart from your panel) stops and cleans up the running test, as /bench stop does, and releases the chunks VoxelBench had force-loaded.

After a crash, the test that was running leaves a lock file behind. A few seconds after the next start, VoxelBench first releases the chunks that test had force-loaded, in whatever world it ran: releasing a chunk destroys nothing, while Minecraft saves force-loading with the world, so a chunk left force-loaded would stay so for good. It then removes what the test had recorded (its blocks, the entities of the fixed test spots) only if it ran in a voxelbench_* world that is loaded again, such as one made with /bench world create. For any other world, the main world or a pinned world with another name, it removes nothing, not even the test's blocks, and the console says so ("Leftover test lock for world '…': nothing removed there"). A temporary world is deleted anyway (see above).

Players left in a benchmark world. A player who joins inside a voxelbench_* world while no test is running is sent back, about a second later, to where they were before the test, in their game mode. Failing that, they go to their bed, or to the spawn of the first world that is not a benchmark world, in the server's default game mode. They see "You were rescued from benchmark world …". While a test is running, they are left where they are. /bench test also brings back, at their next login, a player it had moved and could not bring back itself (see Benchmarks).

This rescue only looks at voxelbench_* worlds. After a crash, a player who was in a test zone of a pinned world with another name, or of a temporary world (deleted at the next start), is not moved, and may still be in spectator mode. Their position and game mode from before the test are in plugins/VoxelBench/data/player-states/<UUID>.yml.

Multiverse-Core

VoxelBench does not need Multiverse-Core. When it is installed:

• VoxelBench still creates its worlds itself, then imports them with the console command mv import <world> normal, so they appear in /mv list. If the import fails, the world works anyway, outside Multiverse.
• To delete a world, VoxelBench first runs mv remove <world>, then unloads the world and deletes its folder if Multiverse left them.
• At startup, temporary worlds that Multiverse loaded again are deleted like the others.

There is nothing to configure. See also Integrations.

Safety Guards

• Only voxelbench_* worlds are deleted. /bench world delete refuses any other name. The startup cleanup only touches folders named voxelbench_temp_<digits> that contain a world (a level.dat file), and the startup loading only voxelbench_<name> folders. Do not give your own worlds a name of the form voxelbench_temp_<digits>, for example with /bench world create temp_1: the next start deletes them.
• No mixing with an old folder. /bench world create refuses a voxelbench_<name> folder that is not loaded but already holds a world, because its chunks would mix with the new flat terrain. Pick another name, or remove the folder while the server is stopped. You can also restart: the server then loads that folder as one of your worlds, and /bench world delete removes it.
• /bench test never writes to the world you are in (see Individual Tests).
• The pre-flight check of /bench start reports a critical finding when the pinned world is not a voxelbench_* world, or when auto-temp-world is false and no world is pinned, and a warning when the pinned world is not flat (see Configuration).
• Players left in a voxelbench_* world are rescued when they join (see Restarts and Crashes).
• Entities the tests did not spawn are only removed in voxelbench_* worlds. At the start of each benchmark, stress limit, tier or custom profile run, on Paper and Spigot, VoxelBench removes the mobs, animals, villagers, golems, dropped items, projectiles, minecarts and boats that could weigh on the measurement, in voxelbench_* worlds only (on Folia, it removes none). /bench zones clean refuses any other world, and the sweep of the fixed test spots that follows /bench stop, a clean server stop or a restart after a crash skips it. Everywhere else, each test removes only what it spawned itself.
• Force-loaded chunks are released in every world. VoxelBench records each chunk it force-loads. /bench stop, a clean server stop and the restart after a crash release those still force-loaded, whatever the world, without loading any. Releasing a chunk removes nothing from it, which is why this is not limited to voxelbench_* worlds.
• Weather and daylight cycle are given back. A run clears the weather and sets the time to noon with the day-night cycle stopped, in every loaded world. At the end, the weather and the day-night cycle come back as they were; the clock is not turned back, so the day goes on from noon.

What the prefix does not protect. The pinned world, whatever its name, and the main world when runs fall back to it (auto-temp-world: false, failed creation, Folia): tests build and clear their zones there as in any benchmark world. Region files, however, are only ever deleted, and entities the tests did not spawn only ever removed, in a voxelbench_* world.

VoxelBench 2.0.2 and earlier also acted outside voxelbench_* worlds: without a pinned world, a multi-run session reset regions of the server's main world between runs; on Paper and Spigot, the start of every benchmark, stress limit, tier or custom profile run removed villagers, animals (tamed and named ones included), golems, dropped items, minecarts and boats from every loaded world; /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 removed every entity but players, paintings and item frames around a zone of the main world. Update before running anything on a server whose worlds matter. These versions also never released, after a crash, the chunks VoxelBench had force-loaded: a crash during a test could leave some force-loaded for good (the vanilla /forceload query command lists those of a world).