Integrations
VoxelBench integrates with popular plugins to extend its functionality. All integrations are optional: they activate automatically when the corresponding plugin is detected at startup (LiteBans must also be turned on), and a failing integration never stops VoxelBench.
The startup log lists which hooks were attached.
PlaceholderAPI
PlaceholderAPI placeholders can be used in scoreboards, tab lists, holograms and other plugins. A placeholder with no value to show returns N/A.
The TPS and MSPT placeholders under Server Metrics read VoxelBench's own tick monitor, which only runs once something has started it: the web dashboard, push mode, boss bars, remote monitoring or a test. Until then they return
N/A(the color, status and bar variants returnGRAY,UNKNOWNand[??????????]). The tick duration placeholders below are always available.
Server Metrics
| Placeholder | Description |
|---|---|
%voxelbench_tps% | Current TPS |
%voxelbench_tps_avg%, %voxelbench_tps_min%, %voxelbench_tps_max% | Average, minimum and maximum TPS |
%voxelbench_tps_color% | GREEN, YELLOW, RED (or GRAY when not measured) |
%voxelbench_tps_colored% | Current TPS prefixed with a color code |
%voxelbench_tps_status% | GOOD, WARNING, CRITICAL (or UNKNOWN) |
%voxelbench_tps_bar% | Text bar from 0 to 20 TPS |
%voxelbench_mspt% | Current MSPT |
%voxelbench_mspt_avg%, %voxelbench_mspt_min%, %voxelbench_mspt_max% | Average, minimum and maximum MSPT |
%voxelbench_mspt_color%, %voxelbench_mspt_colored%, %voxelbench_mspt_status% | Same as the TPS variants, for MSPT |
%voxelbench_ram_used%, %voxelbench_ram_free%, %voxelbench_ram_max% | JVM heap used, free and maximum, in MB |
%voxelbench_ram_percent% | Heap usage in percent |
%voxelbench_ram_color%, %voxelbench_ram_colored%, %voxelbench_ram_status%, %voxelbench_ram_bar% | Color, colored value, status and bar for heap usage |
%voxelbench_cpu% (or cpu_percent) | CPU usage of the server process, in percent |
%voxelbench_cpu_color%, %voxelbench_cpu_colored%, %voxelbench_cpu_status%, %voxelbench_cpu_bar% | Color, colored value, status and bar for CPU usage |
%voxelbench_entities% (or entities_total) | Entities in all worlds |
%voxelbench_entities_hostile%, %voxelbench_entities_passive%, %voxelbench_entities_items% | Hostile mobs, animals and dropped items |
%voxelbench_entities_color%, %voxelbench_entities_status% | Color and status for the entity count |
%voxelbench_chunks% (or chunks_loaded) | Loaded chunks in all worlds |
%voxelbench_chunks_color%, %voxelbench_chunks_status% | Color and status for the chunk count |
%voxelbench_players% (or players_online) | Online players |
%voxelbench_players_max% | Maximum players |
Tick Duration Placeholders
These read the tick metrics VoxelBench measures from startup (see Tick, GC and CPU Metrics), so nothing needs to be started first. Without a window suffix they cover the last minute; add _10s, _1m, _5m or _15m for another window (for example %voxelbench_mspt_p95_10s%). They return N/A for about a second after the first request, and whenever the value is not measured on the server.
| Placeholder | Description |
|---|---|
%voxelbench_tick_source% | Where tick durations come from: paper_tick_event (Paper), main_thread_cpu (Spigot) or folia_region_tick_event (Folia) |
%voxelbench_mspt_p50%, %voxelbench_mspt_p95%, %voxelbench_mspt_p99% | Median, 95th and 99th percentile tick duration, in ms. On Spigot, the main thread's CPU time per tick; on Folia, region ticks, all regions together |
%voxelbench_mspt_peak% | Longest tick, in ms. %voxelbench_mspt_max% above is a different value: the highest reading of the tick monitor |
%voxelbench_tps_10s%, %voxelbench_tps_1m%, %voxelbench_tps_5m%, %voxelbench_tps_15m% | Ticks per second over the window, capped at 20 (Paper and Spigot; N/A on Folia) |
Benchmark
| Placeholder | Description |
|---|---|
%voxelbench_score% | Total VoxelScore of the last benchmark |
%voxelbench_score_cpu% | Single-core sub-score of the last benchmark |
%voxelbench_score_gameplay% | Gameplay sub-score of the last benchmark |
%voxelbench_score_memory%, %voxelbench_score_disk% | Legacy placeholders; the current VoxelScore has no memory or disk sub-score |
%voxelbench_score_grade% | Letter grade (S, A, B, C, D or F) derived from the last VoxelScore |
%voxelbench_benchmark_running% | true while a test or benchmark is running |
%voxelbench_benchmark_status% | RUNNING or IDLE |
Score placeholders only have a value after a full benchmark has completed and received its score since the last server start.
Spark Placeholders
When Spark is available (see Spark). They return N/A otherwise, except spark_available, which returns false.
| Placeholder | Description |
|---|---|
%voxelbench_spark_available% | Whether Spark is available (true/false) |
%voxelbench_spark_tps% (or spark_tps_10s) | Spark TPS (10 seconds) |
%voxelbench_spark_tps_1m% | Spark TPS (1 minute) |
%voxelbench_spark_tps_5m% | Spark TPS (5 minutes) |
%voxelbench_spark_tps_15m% | Spark TPS (15 minutes) |
%voxelbench_spark_mspt% (or spark_mspt_10s) | Spark mean MSPT (10 seconds) |
%voxelbench_spark_mspt_1m% | Spark mean MSPT (1 minute) |
%voxelbench_spark_mspt_95% | Spark MSPT 95th percentile (10 seconds) |
%voxelbench_spark_mspt_median% | Spark median MSPT (10 seconds) |
%voxelbench_spark_cpu_system% | System CPU usage (1 minute) |
%voxelbench_spark_cpu_process% | JVM process CPU usage (1 minute) |
%voxelbench_spark_gc% | GC summary |
DiscordSRV Placeholder
| Placeholder | Description |
|---|---|
%voxelbench_discordsrv_available% | Whether DiscordSRV is available (true/false) |
Dynmap
Dynmap integration adds visual layers to your live map.
Configuration
integrations:
dynmap:
enabled: true
update-interval-seconds: 30
layers:
entity-heatmap:
enabled: true
thresholds:
low: 50 # Below: not drawn; above: yellow
medium: 150 # Yellow → Orange
high: 300 # Orange → Red
performance-markers:
enabled: true
entity-threshold: 200
test-zones:
enabled: true
Layers
The layers are refreshed every update-interval-seconds from the entities in loaded chunks.
Entity Density Heatmap
Layer "VoxelBench - Entity Density". Displays entity density per chunk with color-coded areas (chunks below the low threshold are not drawn):
- Yellow: between
lowandmedium(moderate) - Orange: between
mediumandhigh(high) - Red: above
high(critical)
Performance Alert Markers
Layer "VoxelBench - Performance Alerts". Places a marker on chunks whose entity count reaches entity-threshold. Useful for identifying lag-causing areas.
Test Zone Markers
Layer "VoxelBench - Active Tests". The layer is created, but the current version does not draw test zones on it yet.
Permissions
The Dynmap API does not let plugins set layer permissions. To restrict access to VoxelBench layers, edit plugins/dynmap/markers.yml and add a permission to each marker set:
sets:
voxelbench.heatmap:
perm: voxelbench.dynmap.heatmap
voxelbench.performance:
perm: voxelbench.dynmap.alerts
voxelbench.testzones:
perm: voxelbench.dynmap.testzones
| Permission | Layer |
|---|---|
voxelbench.dynmap | All the layers: it grants the nodes below |
voxelbench.dynmap.heatmap | Entity density heatmap |
voxelbench.dynmap.alerts | Performance alert markers |
voxelbench.dynmap.testzones | Active test zones |
voxelbench.dynmap.view is also declared, but no marker set of this example uses it: on its own, it shows no layer.
Players must be logged into Dynmap AND have the appropriate permission.
Spark
Spark integration exposes Spark's metrics through PlaceholderAPI (see Spark Placeholders), so you can display Spark-quality TPS, MSPT, CPU and GC figures in any plugin that supports PlaceholderAPI.
VoxelBench detects both the Spark plugin and the Spark build bundled into Paper 1.21+. Because the bundled Spark loads after plugins, VoxelBench retries the detection 5 seconds after startup.
Configuration
integrations:
spark:
enabled: true
DiscordSRV
DiscordSRV integration is meant to post benchmark results and performance alerts to a Discord channel.
Current status: VoxelBench detects DiscordSRV and reads the settings below, but the current version does not post any notification yet: no message is sent when a benchmark or a test ends, or when TPS drops. Only the
%voxelbench_discordsrv_available%placeholder is functional.
Configuration
integrations:
discordsrv:
enabled: true
channel-id: "" # Discord channel ID (empty = main DiscordSRV channel)
notifications:
benchmark-results: true # Benchmark completion results
test-results: false # Individual test results
tps-alerts: true # TPS drop alerts
tps-alert-threshold: 18.0 # TPS threshold for alerts
If channel-id is empty, the main channel configured in DiscordSRV is used. To get a channel ID, enable Developer Mode in Discord (User Settings → Advanced), right-click the channel and click Copy Channel ID.
LiteBans
When LiteBans is installed, VoxelBench listens to LiteBans' event API and forwards each punishment LiteBans records (ban, temporary ban, mute, temporary mute, kick, and the removal of a ban or mute) with the player and the operator, as a moderation event to VoxelBench remote monitoring, the dashboard on voxelbench.com for linked servers. Commands typed in chat are not read: a command LiteBans refuses, or one handled by another plugin, sends nothing. Warnings are not forwarded. A LiteBans version too old to provide the event API sends no moderation events.
It is off by default on a new installation, since it sends the names of players who did not agree to anything: set remote-monitoring.events.litebans.enabled: true and restart the server. The reason typed by the staff member is sent only with include-reason: true. It only has an effect when remote monitoring is enabled for a linked server. Bans, mutes and kicks can be tracked separately with remote-monitoring.events.litebans (see Configuration).
Multiverse-Core
When Multiverse-Core is installed, the flat worlds VoxelBench creates (with /bench world create, or temporary benchmark worlds) are imported into Multiverse with /mv import, so they appear in /mv list.
Without Multiverse, VoxelBench creates and deletes these worlds with the standard Bukkit API. The integration only relies on Multiverse's commands, not on its internal API, and there is nothing to configure.
Adding More Integrations
VoxelBench's hook system is designed for graceful degradation:
- Hooks are loaded only when the corresponding plugin is present
- If an integration fails, VoxelBench continues working normally
- Detected integrations are enabled by default, except LiteBans (see LiteBans); Dynmap, Spark and DiscordSRV can be disabled in
config.yml
To add your own benchmark tests from another plugin, see Extending VoxelBench.