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.
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
• PlaceholderAPI — optional — Modrinth

---

🔧 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.

---

⚙️ Configuration

# ============================================================
#   ViewDistanceTweaks — LucasTHCR Edition
# ============================================================

version: 1

# Set to true once you have configured the plugin.
enabled: false

# Adjustment mode:
#   proactive — adjusts based on chunk count targets
#   reactive  — adjusts based on MSPT thresholds
#   mixed     — combines both; prioritizes reducing distance under load (recommended)
adjustment-mode: mixed

# Ticks to wait after startup before the first check runs.
# 2400 = 2 minutes — lets the server stabilize after a restart.
start-delay: 2400

# How often to run a check (in ticks). 600 = every 30 seconds.
ticks-per-check: 600

# How many consecutive checks must confirm an increase before it is applied.
# Higher = more conservative. Recommended: 8–15.
passed-checks-for-increase: 10

# How many consecutive checks must confirm a decrease before it is applied.
# 1 = immediate reaction to overload (recommended).
passed-checks-for-decrease: 1

# Log a console message whenever distances change.
log-changes: true

# Send an in-game message to players with the viewdistancetweaks.notify permission.
announce-changes-in-chat: false

# Format of the announce message. Supports & color codes.
# Placeholders: {world}, {oldSim}, {newSim}, {oldView}, {newView}
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 total ticking chunks across all worlds.
  # Formula: (2*sim+1)^2 * players
  # Example: 20 players at sim 8 → (17)^2 * 20 = 5780
  global-ticking-chunk-count-target: 5780

  # Maximum total non-ticking chunks (view distance beyond sim distance).
  # Formula: ((2*view+1)^2 - (2*sim+1)^2) * 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 this MSPT, consider increasing distances.
  increase-mspt-threshold: 40.0

  # Above this MSPT, consider decreasing distances.
  # A full tick takes 50ms. Above ~47ms players start noticing lag.
  decrease-mspt-threshold: 47.0

  mspt-tracker-settings:

    # How many ticks of data to average for MSPT calculation.
    # 1200 = 1 minute. Higher = more stable but slower to react.
    collection-period: 1200

    mspt-prediction:
      # Use historical MSPT/chunk data to block increases that would cause lag.
      enabled: true

      # How many minutes of history to keep for the prediction model.
      history-length: 30

      # Minimum data points before the prediction model activates.
      # Prevents bad decisions right after a server restart.
      min-samples: 5

# ============================================================
#   WORLD SETTINGS
# ============================================================
# Worlds not listed here inherit the 'default' settings.
# Use the exact world folder name as the key.

world-settings:

  default:
    simulation-distance:
      exclude: false
      min-simulation-distance: 4
      max-simulation-distance: 12

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

    # How much weight this world's chunks have in global calculations.
    # 0.5 = half weight (e.g. The End with many empty chunks).
    # 0.0 = excluded from global chunk budget entirely.
    chunk-weight: 1.0

    chunk-counter-settings:
      # Count overlapping chunks from nearby players only once.
      exclude-overlap: true

    # Never reduce distances below the number of players currently in this world.
    never-reduce-below-players: false

    # Give this world 50% more chunk budget in proactive calculations.
    # Useful for the main overworld on multi-world servers.
    priority-world: false

  # Example — Nether
  # 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

  # Example — The End (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

---

🔑 Commands

Command	Permission	Default
/vdt reload	viewdistancetweaks.vdt.command.reload	OP
/vdt status [--weight]	viewdistancetweaks.vdt.command.status	OP
/vdt simulationdistance <value> [world] [--duration <min>]	viewdistancetweaks.vdt.command.simulationdistance	OP
/vdt viewdistance <value> [world] [--duration <min>]	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 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_mode%	Active adjustment mode
%viewdistancetweaks_enabled%	true or false
%viewdistancetweaks_sim_distance%	Simulation distance (first world)
%viewdistancetweaks_sim_distance_<world>%	Simulation distance of a specific world
%viewdistancetweaks_view_distance_<world>%	View distance of a specific world
%viewdistancetweaks_min_sim_distance_<world>%	Configured minimum sim distance
%viewdistancetweaks_max_sim_distance_<world>%	Configured maximum sim distance
%viewdistancetweaks_min_view_distance_<world>%	Configured minimum view distance
%viewdistancetweaks_max_view_distance_<world>%	Configured maximum view distance
%viewdistancetweaks_chunk_count%	Total chunks loaded globally
%viewdistancetweaks_chunk_count_<world>%	Chunks loaded in a specific world
%viewdistancetweaks_ticking_chunk_count%	Total ticking chunks globally
%viewdistancetweaks_ticking_chunk_count_<world>%	Ticking chunks in a specific world
%viewdistancetweaks_nonticking_chunk_count%	Total non-ticking chunks globally
%viewdistancetweaks_nonticking_chunk_count_<world>%	Non-ticking chunks in a specific world
%viewdistancetweaks_chunk_weight_<world>%	Configured chunk weight of a world

---

👥 Credits

LucasTHCR	Creator & maintainer

Discord: dc.gg/paperstream