ViewDistanceTweaks

Your server. Your performance.

Sets view and simulation distance per world, on its own, based on what the server can actually carry at that moment.

Pick a view distance in server.properties and you are picking it for the worst minute your server will ever have. Ten players online at 3am and you are throwing away distance nobody asked you to save. Sixty players at an event and that same number is why the TPS meter is on the floor.

This plugin moves that number for you. It watches MSPT and how many chunks your players are really loading, gives distance back while there is headroom, and takes it away before anyone notices. Each world keeps its own floor and ceiling, so the Nether can sit at 6 while the main world runs at 16.

There is nothing to wire up. Drop the jar in, restart, and the defaults already do something reasonable.

📦 Requirements

🔧 How it decides

MSPT is sampled every tick. Every ticks-per-check (30 seconds out of the box) each world gets looked at once and the answer is up, down, or leave it alone.

Three modes. proactive works from a chunk budget: you say how many ticking and non-ticking chunks the server should carry in total, and it solves for the distance that fits. reactive ignores chunk counts and only watches MSPT against two thresholds. mixed runs both and lets the more pessimistic one win, which is the right answer on most servers.

It does not repeat mistakes. A linear regression over the last 30 minutes of chunk-count and MSPT pairs predicts what the next step up would cost. If that prediction lands above the decrease threshold, the increase simply never happens. This is what breaks the usual raise, lag, drop, raise again loop.

Averages lie, so the spread gets watched too. A server can average a comfortable 30ms while single ticks bounce between 8 and 55, and nobody enjoys playing on it. Standard deviation across Paper's last 100 tick samples catches that. Above variance-threshold, once the average is high enough for the number to mean anything, the server counts as overloaded even though the average looked fine.

Down is allowed to be faster than up. max-increase-step and max-decrease-step are separate values. A common pair is 1 and 4: climb one notch at a time, bail out in one go. On top of that, revert-increase-if-overloaded re-checks right after an increase and rolls it back immediately if it hurt, instead of crawling back down over the next ten cycles.

Simulation first, view second. With prioritize-simulation-distance on, view distance is not touched until simulation distance already sits at the world minimum. Simulation distance is the one that costs TPS. View distance is the one players see. Spend the cheap one first.

🛡️ Safety nets

MSPT is not the only thing worth reacting to, so a handful of subsystems watch other signals. Everything here except the memory safeguard is off by default.

👤 Per-player distances

Two permission families set a distance for one player without touching the world:

viewdistancetweaks.fixed.<n>      view distance for that player
viewdistancetweaks.simfixed.<n>   simulation distance for that player

Values from 2 to 32, highest one wins if a player holds several, and taking the permission away hands them back to the world value with no relog. Both features have to be switched on in the config first, and they need different permission prefixes or one node would set both at once.

The view distance one is client-side and costs the server nothing extra. The simulation distance one genuinely does cost, so keep it for staff rather than selling it as a donor perk.

/vdt status --fixed shows who currently holds what, and whether the value came from a permission or from the AFK throttle.

🎛️ Presets and profiles

Two different things with annoyingly similar names.

/vdt preset <small-server|large-network|performance-first> writes into your config.yml. It is a starting point for people who do not want to tune forty values by hand, not a final answer.

/vdt profile <name> lays a temporary overlay over whatever is configured, defined under profiles: in the config. Nothing is written to disk and normal puts it all back. It exists so you can move to event settings for two hours without editing the config in the middle of the event. max-view-distance-cap and max-simulation-distance-cap are hard ceilings applied after every other rule, so a cap of 8 really is 8 and never-reduce-below-players cannot talk it out of that.

⚙️ Configuration

The complete config.yml is at the bottom of this page, and in the repo under src/main/resources/config.yml.

messages.yml holds every player- and staff-facing string, with colours via & and {placeholder} substitution. It is copied into the data folder on first start. Every key also has a hardcoded fallback inside the jar, so a messages.yml left over from an older version keeps working instead of rendering blank lines, and anything missing is listed in the console once at load.

Distances are counted in chunks and timings in ticks, so ticks-per-check: 600 is 30 seconds. The --duration flag on the two override commands is the one exception, that one takes minutes.

🔑 Commands

Permissions

Everything below defaults to OP, except the two numeric families which are never granted by default.

📋 Placeholders

Needs PlaceholderAPI. All of them are prefixed %viewdistancetweaks_.

Server-wide

Per world, append the world name:

👥 Credits

Questions, bug reports and feature ideas: dc.gg/paperstream

📄 License

Copyright (C) 2026 LucasTHCR

ViewDistanceTweaks is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for details.

In short: use it, study it, change it, pass it on. Anything you distribute that is built on it has to be GPLv3 as well and has to ship its source.

Releases up to and including 2.6-RELEASE were published under the MIT License; copies obtained under those terms stay governed by them.

📄 Full config.yml

Every option with its comment, exactly as shipped.

# ============================================================
#   ViewDistanceTweaks – LucasTHCR Edition
#   Compatible with Paper 1.21.* - 26.*+
# ============================================================

# Plugin version – DO NOT CHANGE
version: 1

# Master switch. The plugin manages sim/view distance out of the box with the
# defaults below; set this to false if you want to configure everything first
# (or use /vdt disable in-game).
enabled: true

# Adjustment mode:
#   proactive – Adjusts distances before performance suffers
#               (based on chunk count targets)
#   reactive  – Reacts to MSPT changes
#   mixed     – Combines both; prioritises reduction when overloaded (recommended)
adjustment-mode: mixed

# How many ticks after plugin start should be waited before the first check runs?
# 2400 = 2 minutes – useful to let the server stabilise after a restart.
start-delay: 2400

# How many ticks between checks for whether distances need to be adjusted?
# 600 = every 30 seconds
ticks-per-check: 600

# How many consecutive checks must confirm an increase before it is applied?
# Higher value = more conservative (recommended: 8–15)
passed-checks-for-increase: 10

# How many consecutive checks must confirm a decrease?
# 1 = immediate reaction when overloaded (recommended)
passed-checks-for-decrease: 1

# Should a line be logged to the console when distances are changed?
log-changes: true

# Should a message be sent to players with the permission viewdistancetweaks.notify?
# Useful for admins who want to follow changes live.
announce-changes-in-chat: false

# Format of the announce message. Placeholders:
#   {world}   – world name
#   {oldSim}  – old simulation distance
#   {newSim}  – new simulation distance
#   {oldView} – old view distance
#   {newView} – new view distance
# Colours with & are supported.
announce-format: "&7[VDT] &f{world}: Sim &e{oldSim}&7→&a{newSim} &f| View &e{oldView}&7→&a{newView}"

# Check Modrinth for a newer release on startup? The check is a single async
# request and never blocks the server. Turn it off if the machine has no
# outbound internet access. /vdt update always checks on demand regardless.
update-checker: true

# ============================================================
#   PROACTIVE MODE
# ============================================================
proactive-mode-settings:

  # Maximum number of ticking chunks globally (across all worlds).
  # Formula: (2*sim+1)^2 * number of players
  # Example: 20 players, Sim 8 → (17)^2 * 20 = 5780
  global-ticking-chunk-count-target: 5780

  # Maximum number of non-ticking chunks globally (View minus Sim).
  # Formula: ((2*view+1)^2 - (2*sim+1)^2) * number of players
  # Example: 20 players, View 12, Sim 8 → (625 - 289) * 20 = 6720
  global-non-ticking-chunk-count-target: 6720

  # NEW in 2.6: what a world with ZERO players should be driven to.
  #   min  – drop it to its configured minimum (recommended, default)
  #   max  – drive it to its configured maximum (behaviour before 2.6)
  #   keep – leave whatever it currently has
  # No chunks tick while a world is empty, so "max" costs nothing right up until
  # someone walks in — at which point they land on a fully maxed-out world and
  # max-decrease-step can only walk it back down one notch per check. That is the
  # exact load spike startup-grace exists to prevent, hence "min" as the default.
  empty-world-target: min

  # NEW in 2.7: weigh chunks by what is actually IN them instead of counting
  # them all the same. An ocean chunk costs almost nothing; a chunk holding a
  # 500-hopper sorting system can dominate a tick on its own — yet the plain
  # (2*d+1)^2 formula treats both as one unit, so a redstone-heavy world gets
  # the same budget as a world full of water.
  #
  # Inspecting chunks is itself work, so this SAMPLES a bounded number of
  # loaded chunks per world (round-robin) and derives an average multiplier,
  # refreshed once per ticks-per-check. It never scans every chunk.
  use-complexity-weighting: false

  # How many loaded chunks to sample per world per refresh. Higher = more
  # accurate but more work. 40 is plenty for a stable average.
  complexity-sample-chunks: 40

  # Base cost of an ordinary chunk before any tile entities are counted.
  complexity-default-weight: 1.0

  # Surcharge per tile entity of that material. Names are Bukkit Material
  # names. Anything not listed adds nothing.
  complexity-weights:
    HOPPER: 0.5
    SPAWNER: 2.0
    CHEST: 0.05
    TRAPPED_CHEST: 0.05
    BARREL: 0.05
    FURNACE: 0.1
    BLAST_FURNACE: 0.1
    SMOKER: 0.1
    BREWING_STAND: 0.1
    BEACON: 0.5
    CONDUIT: 0.5
    PISTON: 0.1
    STICKY_PISTON: 0.1

# ============================================================
#   REACTIVE MODE
# ============================================================
reactive-mode-settings:

  # Below which MSPT should an increase of the distance be considered?
  increase-mspt-threshold: 40.0

  # Above which MSPT should a decrease of the distance be considered?
  # A tick lasts at most 50ms (= 20 TPS); players notice lag from ~47ms.
  decrease-mspt-threshold: 47.0

  # If true: when the server is overloaded, simulation distance is reduced FIRST.
  # View distance is only reduced once simulation distance has already hit its
  # configured minimum for that world. Simulation distance has a bigger impact
  # on TPS, while reducing view distance causes visible chunk flicker for
  # players — so this avoids touching view distance unless it's really needed.
  # If false: simulation and view distance are reduced together (old behavior).
  # Default: false
  prioritize-simulation-distance: false

  # Maximum number of steps simulation/view distance may change by in a single
  # check cycle, in EACH direction. Setting these to 1 gives the old behavior
  # (always +/-1 per check). Higher values let the plugin react faster to big
  # swings in server load, at the cost of bigger visible/perf jumps per step.
  #   max-increase-step – limits how much distance can grow in one check
  #   max-decrease-step – limits how much distance can shrink in one check
  # Default: 1 for both (safe, gradual behavior)
  max-increase-step: 1
  max-decrease-step: 1

  # After increasing simulation/view distance, re-check MSPT shortly after
  # (see below). If the server is immediately overloaded as a result, the
  # increase is rolled back on the next check instead of waiting through the
  # normal passed-checks-for-decrease delay. This prevents the "jump straight
  # to max, then crawl back down one step at a time" problem.
  revert-increase-if-overloaded: true

  mspt-tracker-settings:

    # Over how many ticks is the MSPT average calculated?
    # 1200 = 1 minute. Higher = more stable but slower to react.
    collection-period: 1200

    # MSPT prediction: Prevents increasing distances
    # even though we know from history that this would cause lag.
    mspt-prediction:
      enabled: true

      # How many minutes of history should be stored for the prediction?
      history-length: 30

      # Minimum number of data points before the prediction takes effect.
      # Prevents wrong decisions immediately after server start.
      min-samples: 5

    # MSPT VARIANCE: a server can have a perfectly fine *average* MSPT while
    # still spiking badly tick-to-tick (e.g. redstone clocks, chunk generation
    # bursts, plugin schedulers). Average-only checks miss this. This tracks
    # how spread out the recent tick times are (standard deviation) and can
    # treat a high-variance server as if it were overloaded, even if the
    # average MSPT is still below decrease-mspt-threshold.
    mspt-variance:
      enabled: true

      # How many of the most recent tick samples (from Paper's getTickTimes())
      # are used to compute the standard deviation. getTickTimes() holds up to
      # 100 samples (~5s at 20 TPS); this just controls how many of those are used.
      sample-window: 100

      # Standard deviation (in ms) above which the server is considered
      # "unstable" and treated as overloaded for decrease purposes, even if
      # average MSPT is fine. Typical stable servers sit around 1-4ms stddev;
      # noticeable stutter usually starts around 8-10ms+.
      variance-threshold: 8.0

      # Minimum number of samples required before variance is evaluated at all.
      # Prevents false positives right after server start.
      min-samples: 20

      # If true, high variance ALSO blocks increases (in addition to forcing
      # decreases), even if average MSPT looks fine. Recommended: true.
      block-increase-on-high-variance: true

      # Standard deviation is symmetric — it measures how spread out recent ticks
      # are around the average, regardless of direction. A server bouncing between
      # 4ms and 18ms (avg ~10ms, still totally fine) can trip the same stddev
      # threshold as one bouncing between 40ms and 55ms (avg ~47ms, actually
      # struggling). Variance is only treated as overload once the average MSPT
      # is at least this high — below it, variance is ignored even if it exceeds
      # variance-threshold above.
      min-avg-mspt-to-trigger: 25.0

# ============================================================
#   PER-PLAYER FIXED VIEW DISTANCE (optional)
# ============================================================
# Lets specific players (e.g. mods, streamers) keep a fixed CLIENT-SIDE view
# distance regardless of what the plugin sets for the world. This only affects
# what that individual player receives — it does NOT change the world's
# server-side view distance or the chunk budget the rest of this plugin manages.
#
# Grant a permission "<permission-prefix><value>" to set that player's fixed
# view distance, e.g. with permission-prefix "viewdistancetweaks.fixed." :
#   viewdistancetweaks.fixed.20   -> that player always gets view distance 20
# If a player has multiple such permissions, the highest value is used.
# Valid values are 2-32; anything higher is clamped to 32. Note that a player
# never sees more chunks than their own client render-distance setting allows.
# Taking the permission away again hands the player back to their world's
# normal, plugin-managed view distance — no relog needed.
per-player-fixed-view-distance:
  # Must be true for the viewdistancetweaks.fixed.<value> permissions to do
  # anything. Works independently of the "enabled" master switch at the top.
  enabled: false
  # Must be lowercase-safe; a trailing "." is added automatically if missing.
  permission-prefix: "viewdistancetweaks.fixed."

# ============================================================
#   PER-PLAYER FIXED SIMULATION DISTANCE (optional, NEW in 2.6)
# ============================================================
# Exactly the same idea as the fixed view distance above, but for simulation
# distance (Paper's Player#setSimulationDistance). Simulation distance controls
# how far around that player the world actually TICKS — mobs, redstone, crops.
#
# Careful: unlike view distance this genuinely costs server performance, so
# handing it out widely will hurt. It is meant for a handful of staff members,
# not for a donor rank.
#
#   viewdistancetweaks.simfixed.8   -> that player always gets simulation distance 8
#
# Valid values are 2-32; anything higher is clamped to 32. If a player holds
# several such permissions, the highest value is used. Taking the permission
# away hands the player back to their world's normal distance — no relog needed.
# Use a DIFFERENT permission-prefix than the view-distance feature above,
# otherwise a single permission would set both values at once.
per-player-fixed-simulation-distance:
  enabled: false
  permission-prefix: "viewdistancetweaks.simfixed."

# ============================================================
#   AFK PLAYER THROTTLING (optional, NEW in 2.7)
# ============================================================
# A player standing still at spawn does not need the same distances as one
# flying an elytra. When they go AFK their personal distances drop to the
# values below, and the chunks they free up go straight back into the global
# budget for players who are actually playing.
#
# AFK state comes from Paper's own idle timer. If EssentialsX is installed its
# AFK state is used instead, so someone who typed /afk counts immediately
# instead of having to wait out afk-time-minutes.
#
# Note: an explicit viewdistancetweaks.fixed.<n> permission WINS over this
# throttle. If you want staff throttled while AFK too, don't give them that
# permission.
afk-player-throttling:
  enabled: false
  afk-time-minutes: 5
  afk-simulation-distance: 4
  afk-view-distance: 6
  use-essentials-if-present: true

# ============================================================
#   CHUNK GENERATION SAFEGUARD (optional, NEW in 2.7)
# ============================================================
# mspt-variance notices the stutter that terrain generation causes, but not the
# cause. This counts chunks that are genuinely being GENERATED (not merely read
# from disk) and reacts to the cause directly.
#
# Generating a chunk runs the whole terrain pipeline and is what actually
# freezes the main thread when someone crosses unexplored terrain at speed.
chunk-generation-safeguard:
  enabled: false

  # Newly generated chunks per second, per world, above which the safeguard trips.
  chunks-per-second-threshold: 15

  # Block distance increases while generation is running. Growing view distance
  # mid-generation feeds the exact thing that is stalling the server and causes
  # the rubber-banding this is meant to avoid.
  lock-increase-during-gen: true

  # Additionally clamp view distance to this value while generating.
  # -1 disables the hard clamp and only uses lock-increase-during-gen above.
  emergency-view-distance: -1

# ============================================================
#   DENSITY-BASED SCALING (optional, NEW in 2.7)
# ============================================================
# 20 players scattered across a world load 20 separate rings of chunks.
# 20 players standing around the same community farm load almost the SAME
# chunks. The proactive formula assumes the first case and therefore starves a
# clustered world of view distance it could easily afford.
#
# When enough players sit within cluster-radius chunks of each other, this
# grants bonus distance proportional to how much of the world's population is
# in that cluster.
density-based-scaling:
  enabled: false
  # Radius in chunks within which players count as "together"
  cluster-radius: 8
  # Minimum players in one cluster before any bonus is granted
  cluster-player-threshold: 5
  # Maximum bonus distance, reached when everybody is in the same cluster
  max-bonus: 4

# ============================================================
#   EMERGENCY RELIEF (optional, NEW in 2.7)
# ============================================================
# Last resort. When a world already sits at its MINIMUM simulation and view
# distance and the server is STILL over decrease-mspt-threshold, there is
# nothing left to take away from distances. Rather than let the server keep
# sinking, shed two cheaper-to-lose sources of load instead: thunderstorms
# (extra light and weather updates) and the day/night cycle.
#
# Both are restored automatically once MSPT drops below recover-below-mspt,
# and on plugin disable. The world's ORIGINAL weather and doDaylightCycle
# setting are remembered, so a world that deliberately had the cycle off
# keeps it off afterwards.
emergency-relief:
  enabled: false
  clear-weather: true
  freeze-time: true
  # Deliberately lower than decrease-mspt-threshold, otherwise relief would
  # flap on and off around the same value that triggered it.
  recover-below-mspt: 40.0

# ============================================================
#   MEMORY SAFEGUARD (NEW in 2.7)
# ============================================================
# Distances don't only cost CPU — every extra ring of chunks stays resident in
# the heap. A server can sit at a perfect 20ms MSPT and still be one increase
# away from spending every tick in garbage collection, at which point MSPT
# reacts far too late to be useful as the only signal.
#
# While free heap is below min-free-percent, ALL increases are blocked
# regardless of MSPT. Decreases always stay allowed.
# Measured against the -Xmx ceiling, not the currently allocated heap.
memory-safeguard:
  enabled: true
  min-free-percent: 15.0

# ============================================================
#   PROFILES (optional, NEW in 2.7)
# ============================================================
# Named overlays for a handful of tuning values, switchable in-game with
# /vdt profile <name> — no config editing mid-event. "normal" is always
# available and means "the values configured above".
#
# Supported keys inside a profile:
#   decrease-mspt-threshold, increase-mspt-threshold,
#   max-increase-step, max-decrease-step,
#   passed-checks-for-increase, passed-checks-for-decrease,
#   global-ticking-chunk-count-target, global-non-ticking-chunk-count-target,
#   max-view-distance-cap, max-simulation-distance-cap
#
# The two *-cap keys are hard caps applied AFTER every other rule, so a cap of
# 8 genuinely means 8 and cannot be undone by never-reduce-below-players.
profiles:
  event-mode:
    decrease-mspt-threshold: 42.0   # react to load much earlier
    max-view-distance-cap: 8        # hard ceiling for the duration of the event
    passed-checks-for-increase: 20  # and be very reluctant to grow again

  night-mode:
    increase-mspt-threshold: 45.0   # be generous while the server is quiet
    max-increase-step: 2

# ============================================================
#   STARTUP GRACE PERIOD (optional)
# ============================================================
# If enabled, the plugin forces a low, fixed sim/view distance immediately when
# the plugin starts (before start-delay/ticks-per-check even apply), instead of
# whatever distance the world already had (which could be near max after a
# config change or a manual override, and cause instant overload/crash on a
# cold-started server). Once duration-ticks has passed, normal proactive/
# reactive/mixed adjustment takes back over as usual — and max-increase-step
# still limits how fast it's then allowed to climb back up.
startup-grace:
  enabled: false
  simulation-distance: 4
  view-distance: 6
  # 6000 ticks = 5 minutes
  duration-ticks: 6000

# ============================================================
#   WORLD SETTINGS
# ============================================================
# Any worlds not listed here inherit the "default" settings.
# You can override each world with its exact name.

world-settings:

  default:
    simulation-distance:
      # Exclude the world completely from management?
      # Chunks are still counted for global calculations (unless chunk-weight: 0).
      exclude: false
      min-simulation-distance: 4
      max-simulation-distance: 12

    view-distance:
      exclude: false
      min-view-distance: 6
      max-view-distance: 16

    # How much chunk "budget" does this world weigh?
    # 1.0 = normal. 0.5 = half as heavy (e.g. End, many empty chunks).
    # 0.0 = world has no influence on global calculations.
    chunk-weight: 1.0

    # NEW: Override how often THIS world is checked, independent of the global
    # ticks-per-check above. Leave unset (or <= 0) to inherit the global value.
    # Useful for a busy overworld that needs quick reactions vs. a quiet, mostly
    # empty nether/end that doesn't need checking every 30 seconds.
    # ticks-per-check: 200

    # NEW: Never lower the distance below the current player count in this world.
    # Useful for small servers with few players.
    never-reduce-below-players: false

    # NEW: This world gets 50% more chunk budget in proactive calculations.
    # Useful for the main world on servers with multiple dimensions.
    priority-world: false

  # Example: Nether world
  # world_nether:
  #   simulation-distance:
  #     min-simulation-distance: 4
  #     max-simulation-distance: 8
  #   view-distance:
  #     min-view-distance: 4
  #     max-view-distance: 10
  #   chunk-weight: 0.8
  #   priority-world: false

  # Example: End world (many empty chunks → lower weight)
  # world_the_end:
  #   simulation-distance:
  #     min-simulation-distance: 4
  #     max-simulation-distance: 10
  #   view-distance:
  #     min-view-distance: 6
  #     max-view-distance: 14
  #   chunk-weight: 0.5

  # Example: Main world with priority
  # world:
  #   simulation-distance:
  #     min-simulation-distance: 6
  #     max-simulation-distance: 12
  #   view-distance:
  #     min-view-distance: 8
  #     max-view-distance: 16
  #   chunk-weight: 1.0
  #   priority-world: true