[![bStats](https://bstats.org/signatures/bukkit/ViewDistance-Tweaks.svg)](https://bstats.org/plugin/bukkit/ViewDistance-Tweaks/32343) # ViewDistanceTweaks ### *Your server. Your performance.* > Dynamic view distance and simulation distance adjustment per world — lightweight, fully configurable, and built for performance-critical servers. --- ## ✨ Features | Feature | Description | |---|---| | **Dynamic Sim & View Distance** | Automatically adjusts per world based on server load. | | **3 Adjustment Modes** | Proactive, reactive, or mixed — your choice. | | **MSPT-based Prediction** | Linear regression model prevents bad increases before they happen. | | **MSPT Variance Detection** | Catches tick-to-tick instability (redstone, chunk gen bursts) even when the average MSPT looks fine. | | **Per-world Configuration** | Each world has its own min/max, weight, and exclusion settings. | | **Temporary Overrides** | Lock distances for a set duration via command. | | **PlaceholderAPI Support** | 20+ placeholders for scoreboards, tab lists and more. | | **In-game Announcements** | Notify staff on distance changes with a configurable format. | | **`/vdt` Command Suite** | Status, reload, enable/disable, manual override — all in one command. | --- ## 📦 Dependencies - **Paper 1.21.x / 26.x** — `required` — [papermc.io](https://papermc.io/) - **PlaceholderAPI** — `optional` — [Modrinth](https://modrinth.com/plugin/placeholderapi) --- ## 🔧 How It Works The plugin measures your server's **MSPT** (milliseconds per tick) every tick and uses it — along with the total number of player-loaded chunks — to decide whether simulation and view distances should be increased, kept, or reduced. **Proactive mode** targets a configured maximum chunk count and mathematically calculates the ideal distance. **Reactive mode** reacts to MSPT crossing configurable thresholds. **Mixed mode** combines both and always prioritizes reducing distance when the server is under load. A built-in **linear regression model** tracks historical MSPT vs. chunk-count pairs and blocks increases when it predicts the server would exceed the decrease threshold — preventing the classic increase → lag → decrease loop. On top of that, **`revert-increase-if-overloaded`** re-checks MSPT right after any increase and instantly rolls it back if the server is immediately overloaded, instead of crawling back down one step at a time — and `max-increase-step` / `max-decrease-step` let each direction move by a different number of steps per check, so decreases can react faster than increases. --- ## ⚙️ Configuration ```yaml # ============================================================ # ViewDistanceTweaks – LucasTHCR Edition # Compatible with Paper 1.21.* - 26.*+ # ============================================================ # Plugin version – DO NOT CHANGE version: 1 # Set to true to enable the plugin. # Leave it false until you have finished configuring the config! enabled: false # 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}" # ============================================================ # 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 # ============================================================ # 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). Setting max-decrease-step higher # than max-increase-step (e.g. 1 / 6) is a common combination: climb cautiously, # but be able to drop fast when the server suddenly gets overloaded. 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 # ============================================================ # 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 "" 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. per-player-fixed-view-distance: enabled: false permission-prefix: "viewdistancetweaks.fixed." # ============================================================ # 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 # Never lower the distance below the current player count in this world. # Useful for small servers with few players. never-reduce-below-players: false # This world gets 50% more chunk budget in proactive calculations. # Useful for the main world on servers with multiple dimensions. priority-world: false # 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 # 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 # 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 ``` --- ## 🔑 Commands | Command | Permission | Default | |---|---|---| | `/vdt reload` | `viewdistancetweaks.vdt.command.reload` | OP | | `/vdt status [--weight]` | `viewdistancetweaks.vdt.command.status` | OP | | `/vdt simulationdistance [world] [--duration ]` | `viewdistancetweaks.vdt.command.simulationdistance` | OP | | `/vdt viewdistance [world] [--duration ]` | `viewdistancetweaks.vdt.command.viewdistance` | OP | | `/vdt enable` | `viewdistancetweaks.vdt.command.reload` | OP | | `/vdt disable` | `viewdistancetweaks.vdt.command.reload` | OP | | `/vdt mspt` | `viewdistancetweaks.command.vdt` | OP | | — | `viewdistancetweaks.notify` | OP — receives announce messages | --- ## 📋 Placeholders Requires [PlaceholderAPI](https://modrinth.com/plugin/placeholderapi) to be installed. | Placeholder | Description | |---|---| | `%viewdistancetweaks_mspt%` | Current average MSPT | | `%viewdistancetweaks_tps%` | Current TPS | | `%viewdistancetweaks_mspt_color%` | `&a` / `&e` / `&c` based on MSPT | | `%viewdistancetweaks_tps_color%` | `&a` / `&e` / `&c` based on TPS | | `%viewdistancetweaks_mspt_stddev%` | Current MSPT standard deviation (tick-to-tick variance) | | `%viewdistancetweaks_mspt_stddev_color%` | `&a` / `&e` / `&c` based on MSPT stddev vs. `variance-threshold` | | `%viewdistancetweaks_mode%` | Active adjustment mode | | `%viewdistancetweaks_enabled%` | `true` or `false` | | `%viewdistancetweaks_sim_distance%` | Simulation distance (first world) | | `%viewdistancetweaks_sim_distance_%` | Simulation distance of a specific world | | `%viewdistancetweaks_view_distance_%` | View distance of a specific world | | `%viewdistancetweaks_min_sim_distance_%` | Configured minimum sim distance | | `%viewdistancetweaks_max_sim_distance_%` | Configured maximum sim distance | | `%viewdistancetweaks_min_view_distance_%` | Configured minimum view distance | | `%viewdistancetweaks_max_view_distance_%` | Configured maximum view distance | | `%viewdistancetweaks_chunk_count%` | Total chunks loaded globally | | `%viewdistancetweaks_chunk_count_%` | Chunks loaded in a specific world | | `%viewdistancetweaks_ticking_chunk_count%` | Total ticking chunks globally | | `%viewdistancetweaks_ticking_chunk_count_%` | Ticking chunks in a specific world | | `%viewdistancetweaks_nonticking_chunk_count%` | Total non-ticking chunks globally | | `%viewdistancetweaks_nonticking_chunk_count_%` | Non-ticking chunks in a specific world | | `%viewdistancetweaks_chunk_weight_%` | Configured chunk weight of a world | --- ## 👥 Credits | | | |---|---| | **LucasTHCR** | Creator & maintainer | Discord: [dc.gg/paperstream](https://dc.gg/paperstream)

ViewDistanceTweaks

1.0-RELEASE

Information

Platforms