Configuration

Language

language:
  default: en_US    # Default language (en_US, fr_FR)
  force: false      # Force language for all players

• When force: false (default), VoxelBench automatically detects each player's Minecraft client language
• When force: true, all players see messages in the default language
• Supported languages: en_US (English), fr_FR (French)

Operating Mode

mode: anonymous    # anonymous or authenticated

Use /bench link to switch to authenticated mode. See Account Linking.

Notifications

notifications:
  sounds:
    enabled: true    # Play sounds on test/benchmark completion

Anonymization

Controls what data is included when reports are sent to voxelbench.com.

anonymous:
  anonymization-level: PARTIAL    # NONE, PARTIAL, or FULL

All levels always send: CPU name, RAM amount, Java version, OS name, and all benchmark metrics.

See Privacy & Security for more details.

Rate Limiting

rate-limiting:
  local-cooldown-minutes: 30    # Minutes between benchmarks

Prevents running benchmarks too frequently. Players with voxelbench.start.force permission can bypass this cooldown.

Benchmark Mode

benchmark-mode: standard    # standard or custom

Custom Test Parameters

These values are only used when benchmark-mode: custom:

tests:
  single-core:
    duration-seconds: 10
    entities-per-spawn: 10
  multi-core:
    threads: 100
    iterations: 100000
  disk:
    threads: 4
    queue-depth: 8
    file-size-mb: 512
  memory:
    size-mb: 512
    iterations: 75000
    runs: 3
  network:
    test-servers:
      - "ping.online.net"
      - "8.8.8.8"

benchmark-tests:
  chunk-loading:
    chunks-to-load: 200
    radius: 16
  mob-spawn:
    mob-count: 300
    duration-seconds: 30
  hopper:
    hopper-chain-length: 50
    items: 1000
    parallel-lines: 1
  explosion:
    tnt-count: 30
  mob-pathfinding:
    mob-count: 100
    duration-seconds: 30
  redstone:
    circuit-count: 50
    duration-seconds: 30
  block-physics:
    block-count: 200
    duration-seconds: 20
  dispersed-zones:
    default: 1

Confirmation

confirmation:
  require-confirmation: true    # Require /bench confirm before benchmarks

When enabled, running /bench start will prompt for confirmation before beginning. This prevents accidental benchmark launches.

Logging

logging:
  test-verbosity: NORMAL    # MINIMAL, NORMAL, VERBOSE, DEBUG
  log-test-results: true    # Log result summary for each test
  log-benchmark-progress: true    # Log which test is running

Monitoring

See Monitoring for the complete monitoring configuration reference.

monitor:
  web-port: 8080
  bind-address: "0.0.0.0"
  https:
    enabled: false
    port: 8443
  auto-start:
    web-server: false
    push-service: false
    boss-bars: false
  dashboard:
    enabled: true
  auth:
    enabled: false
    username: "admin"
  whitelist:
    enabled: false
  push:
    enabled: false
    url: ""
    interval-seconds: 1

Reports

reports:
  enabled: true
  folder: "reports"
  backend:
    unit-tests: false    # Send unit test results to backend (requires /bench link)
  retention:
    max-age-days: 90     # Auto-delete reports older than 90 days
    max-per-type: 100    # Max reports per type
    max-total: 500       # Max total reports
    cleanup-on-startup: true
  storage:
    unit-tests: true
    benchmarks: true
    stresslimit: true
  auto-show-report: true    # Auto-display report after test completion

Integrations

See Integrations for the complete integrations configuration reference.

integrations:
  dynmap:
    enabled: true
  spark:
    enabled: true
  discordsrv:
    enabled: true
    channel-id: ""

Benchmark world settings

benchmark:
  # If set, every benchmark uses this exact world. Must be a world
  # created via /bench world create (the voxelbench_ prefix is enforced).
  # Leave empty / commented to use the auto-temp world strategy below.
  target-world: ""

  # When target-world is empty, each run spawns a fresh disposable
  # flat world named voxelbench_temp_<timestamp>, then deletes it on
  # completion. Set to false to refuse running without a pinned world —
  # useful on hosts where world creation is expensive (large
  # pre-generated regions, datapack-driven worlds, etc).
  auto-temp-world: true

The two settings interact:

• target-world is set → that world is always used. auto-temp-world is ignored.
• target-world empty + auto-temp-world: true → fresh world per run.
• target-world empty + auto-temp-world: false → benchmarks refuse to start until you pin a world.

You can manage the pinned world from in-game via /bench world set / unset (see Commands). The config file is the source of truth on restart.

Custom benchmark profiles directory

VoxelBench scans plugins/VoxelBench/custom_benchmarks/ for *.yml profiles on enable and on /bench custom reload. Three preset profiles are written on first run:

See Custom Profiles for the full schema.

Java and Minecraft compatibility