ViewDistanceTweaks

插件

· 作者 LucasTHCR

根据服务器处理能力,自动调整每个世界的视距和模拟距离——在有余量时增加距离,在玩家察觉卡顿前减少距离。

0 本站下载 0 关注 更新于 5 小时前

最新 2.17.0-BETA · 26.3 · Folia / Paper

一键开服(送7天)

Built with Java 21 Available for Paper Available for Purpur Available for Folia

Chat with us on Discord Available on Codeberg

ViewDistanceTweaks

根据服务器当前能承受的负载,为每个世界单独设置视距和模拟距离。


server.properties 中的数值必须足以应对最糟糕的情况,这意味着在其他大多数情况下它都太低了。凌晨三点只有十个人在线时,你节省了没人要求你节省的距离;而活动高峰期有六十人在线时,正是这个相同的数值导致 TPS 指标跌入谷底。

本插件替你处理这一切。它会监控 MSPT(每刻平均耗时)以及实际加载的区块数量,在有余量时恢复距离,并在玩家察觉之前降低距离。每个世界都有独立的下限和上限,因此下界可以保持在 6,而主世界可以运行在 16。

将 jar 文件放入插件文件夹并重启即可。默认配置无需任何设置就能发挥合理的作用。


依赖项

  • Paper 1.21.x / 26.x 或其分支(Purpur, Pufferfish, Leaves)
  • Folia 可用,已在 1.21.11 上测试通过
  • PlaceholderAPI - 可选,仅当你需要 占位符 时使用
  • EssentialsX - 可选,仅在你开启 AFK 节流功能且需要读取空闲状态时使用

不支持 Spigot 和 Bukkit:它们的 API 只能读取视距和模拟距离,无法修改它们,而修改距离正是本插件的功能所在。


决策机制

每刻都会采样 MSPT 数据。每隔 ticks-per-check(默认为 10 秒),每个世界都会被检查一次,并决定增加、减少或保持不变。

四种模式:

  • proactive(主动模式)- 你提供一个区块预算(服务器总共应承载的 ticking 和非 ticking 区块总数),插件据此计算出合适的距离
  • reactive(响应模式)- 忽略区块数量,仅根据两个阈值监控 MSPT
  • mixed(混合模式)- 同时运行上述两种模式,取更保守的结果。这是大多数服务器的正确选择,也是默认模式
  • off(关闭)- 从不调整视距或模拟距离。适用于只想使用预生成和预加载功能的服务器

除了模式本身之外:

不会重复已造成伤害的增加。 基于过去 30 分钟的区块数/MSPT 配对数据进行线性回归,预测下一步提升的成本。如果预测结果高于降低阈值,则不会执行该增加操作。这打破了常见的“提升-卡顿-下降”循环。

关注离散程度,而非仅看平均值。 服务器可能平均 30ms 看起来很舒适,但单个刻的耗时可能在 8ms 到 55ms 之间剧烈波动,没有人喜欢在这种环境下玩游戏。通过 Paper 最近 100 个刻样本的标准差来捕捉这种波动,因此当超过 variance-threshold 时,即使平均值看起来正常,服务器也被视为过载。

降低速度可以比增加更快。 max-increase-step 和 max-decrease-step 是独立的。1 和 4 是一对常见组合:每次只上升一级,一旦出现问题则一次性退回。revert-increase-if-overloaded 也会在增加后立刻重新检查,如果发现造成负担则立即回滚。

优先处理模拟距离,其次处理视距。 当启用 prioritize-simulation-distance 时,直到模拟距离已达到世界最小值之前,视距都不会被触碰。模拟距离消耗 TPS,而视距是玩家看到的,因此先花费廉价的那一项。

它能区分不同的世界。 服务器发布的是全局单一的 MSPT 数值,因此一个世界的崩溃会拉低所有其他世界的距离——安静的世界会因为邻居的问题受到惩罚。启用 per-world-mspt 后,刻时间会在世界间分配,每个世界根据其实际造成的部分进行评估。默认关闭;详见下文。


按世界划分的 MSPT

整个服务器单一数值并不适合用于按世界做出决策。如果你的下界农场消耗了 30ms,主世界并没有做错什么,缩小主世界的距离也无济于事。

启用 per-world-mspt.enabled 后,每个世界将根据其自身分摊的刻时间来评估:

公平份额    = 1 / 有玩家的世界数量
归属系数    = 该世界的份额 / 公平份额      (默认限制在 0.5x 到 2.0x 之间)
评估依据    = 服务器 MSPT x 归属系数

因此,一个恰好承担其重量(负荷)的世界由未更改的纯服务器数值来评判。一个承担两倍重量的世界将以两倍的数值来评判并最先缩小;一个安静(负荷低)的世界则以更低的数值评判,得以保留或继续增长,而其邻居则被迫退让。

你的阈值含义保持不变。 这仅调整了现有 decrease-mspt-threshold 所比较的目标数值——它并非用一个较小的单世界数值来替代它。无需重新调整任何配置,在单世界服务器上,此功能完全不会改变任何行为。

数值的来源取决于平台:

  • Paper(以及 Purpur 等分支)采用估算方式。由于没有每世界的时间读数,Tick 时间会根据每个世界导致服务器执行的工作量(实体、可 Tick 的方块实体、已加载区块)进行分配。这对于对世界进行排名是可靠的;但对于“体积成本低但内容成本高”的世界(例如互相 feeding 的几百个漏斗),估算可能会出错。
  • Folia 直接测量区域 Tick 时间,这意味着默认情况下每世界的 MSPT 在此平台上无效。一个跟得上进度的区域会报告其自身的 Tick 率,因此所有世界读取到的数值相同,不存在可操作的差异分割;只有当某个区域落后时,该数值才具有信息意义。设置 prefer-exact-source: false 可以在 Folia 上运行估算代理,从而区分不同世界。如果某个 laggy(卡顿)区域内没有玩家,无论哪种方式都不会对其进行探测。

/vdt mspt 命令显示详细分解情况,指出哪个世界最差,以及每个数值是实测值还是估算值。当一个世界基于调整后的数值进行评判时,/vdt simulate 会在其原因行中注明这一点。

如果因任何原因无法获取测量数据——例如仍在预热中,或库未能启动——每个世界将回退到纯服务器范围的数值,这正是本插件在此功能存在之前的行为。


占位符

安装 PlaceholderAPI 后,插件所知悉的所有信息均可用于计分板或聊天格式。标识符为 viewdistancetweaks —— 注意不是 vdt,那是大家首先尝试的错误拼写。

全服范围

占位符 提供内容
%viewdistancetweaks_mspt% 当前 MSPT,保留两位小数
%viewdistancetweaks_tps% 当前 TPS,上限为 20
%viewdistancetweaks_mspt_stddev% 近期 Tick 时间的波动程度
%viewdistancetweaks_mode% 当前激活的调整模式
%viewdistancetweaks_enabled% 插件是否正在管理视距
%viewdistancetweaks_mspt_color% 根据你的阈值对应的 &a/&e/&c 颜色代码
%viewdistancetweaks_tps_color% 同上,适用于 TPS
%viewdistancetweaks_mspt_stddev_color% 同上,适用于波动幅度
%viewdistancetweaks_chunk_count% 所有世界中已加载的区块总数
%viewdistancetweaks_ticking_chunk_count% 所有世界中处于 Tick 状态的区块总数
%viewdistancetweaks_nonticking_chunk_count% 所有世界中非 Tick 状态的区块总数

按世界划分。 在世界名称后追加后缀 —— 例如 %viewdistancetweaks_view_distance_world_nether%。如果不指定名称,则使用服务器的第一个世界。

占位符 提供内容
%viewdistancetweaks_sim_distance_<world>% 当前模拟距离
%viewdistancetweaks_view_distance_<world>% 当前视距
%viewdistancetweaks_min_sim_distance_<world>% 配置的最低模拟距离
%viewdistancetweaks_max_sim_distance_<world>% 配置的最高模拟距离
%viewdistancetweaks_min_view_distance_<world>% 配置的最低视距
%viewdistancetweaks_max_view_distance_<world>% 配置的最高视距
%viewdistancetweaks_chunk_count_<world>% 该世界中已加载的区块数量
%viewdistancetweaks_ticking_chunk_count_<world>% 该世界中处于 Tick 状态的区块数量
%viewdistancetweaks_nonticking_chunk_count_<world>% 该世界中非 Tick 状态的区块数量
%viewdistancetweaks_chunk_weight_<world>% 配置的区块权重

按世界划分的 MSPT。 这些需要开启 per-world-mspt 选项;若未开启,它们将回退到全服数值或报告该功能已关闭,而不会报错。

占位符 提供内容
%viewdistancetweaks_worst_world% 承担最多 Tick 负载的世界
%viewdistancetweaks_worst_world_mspt% 该世界消耗的 Tick 时间(毫秒)
%viewdistancetweaks_world_mspt_<world>% 该世界自身的贡献耗时(毫秒)
%viewdistancetweaks_world_mspt_share_<world>% 该世界所占的 Tick 比例,0-100
%viewdistancetweaks_per_world_mspt_state% 数值来源,或无数值的原因

对于未知世界,读取结果为 unknown 而非零值,这样计分板上的拼写错误会清晰可见,而不是看起来像是一个健康的服务器。


安全网

MSPT 并非唯一值得响应的指标。除内存和区块生成保护外,此处所有功能默认均为关闭状态。

  • 内存保护 - 当堆内存低于 min-free-percent(默认 15%)时,无论 MSPT(每刻毫秒数)显示如何,都会阻止任何增加。服务器可能空闲在 20ms,但仍距离“每一刻都花在 GC 上”仅有一圈区块之遥。
  • 区块生成保护 - 统计的是真正正在生成的区块,而非从磁盘读取的区块。当每秒生成速率超过阈值(默认 8),且 MSPT 也至少达到 min-mspt(默认 30)时,它会停止增加并将视距限制为 8,直到生成活动平息。独自探索的单个玩家不受影响。这适用于有人刚乘坐鞘翅飞入新地形的情况。自 2.14 版本起默认开启,因为基准测试显示,在新地形上单步生成耗时超过一秒时,视距会不断攀升。
  • AFK 节流 - 站在出生点的玩家不需要加载 16 圈区块。他们的个人视距会降低至 AFK 设定值,释放出的预算配额将归还给全局池。如果安装了 EssentialsX,则使用其 AFK 状态以便 /afk 命令立即生效;否则使用 Paper 的空闲计时器。
  • 延迟节流 - 原理相同,但由糟糕的网络连接触发而非空闲状态。如果某玩家的延迟连续几次检查均高于阈值,其个人视距也会降低,从而停止堆积数据包,并防止其他玩家的预算配额为其买单。如果两种节流同时生效,更严格的视距限制优先。
  • 密度缩放 - 二十名玩家聚集在一座农场附近时,加载的区块几乎相同,但主动公式假设这是二十个独立的环,从而导致世界无谓地被“饿死”。当足够多的玩家聚集在一起时,世界会获得额外的视距加成,加成幅度根据该群体占世界总玩家的比例进行缩放。
  • 复杂度加权 - 一个海洋区块是免费的,而一个装有 500 漏斗分拣器的区块可能单独消耗一整刻的时间,(2d+1)² 却只算作一个区块。系统会在玩家周围采样有限数量的区块并计算平均乘数,因此红石密集的world 获得的预算会比充满水的 world 更少。
  • 紧急救援 - 最后的手段。当世界已达到最小模拟和视距限制,MSPT 仍超标,且已无其他可削减项时,系统将移除雷暴和昼夜循环。当 MSPT 恢复、执行 /vdt disable 或服务器关闭时,两者会自动恢复。系统在介入时会记住世界的原始天气和 gamerule 状态。
  • 客户端视距上限 - 没有人能看到超过其客户端渲染范围以外的地方。如果世界中所有玩家的最高设置是 8,那么服务器视距设为 16 只会支付那些无人接收的区块环的费用。开启 client-view-distance-cap 后,世界视距将被限制为最高报告的客户端值加上少量余量,且不低于最小值也不低于模拟距离,这样单个玩家的视频设置不会拖慢所有人的农场效率。最高值会保持三分钟,因此玩家切换维度不会导致世界视距剧烈跳变。默认关闭。
  • 诊断日志 - /vdt diagnose on 会每分钟记录一次样本,并在每次视距变化时记录背后的规则,写入 plugins/ViewDistanceTweaks/diagnostics 目录,每天一个文件,且不包含玩家姓名。请将此文件夹随 bug 报告一起发送。默认关闭。
  • 报告上传 - /vdt diagnose send 显示将要发送的内容,而在执行 /vdt diagnose send confirm 后,会将过去 24 小时的诊断数据匿名化(无玩家姓名、UUID 或 IP,世界名称如 world_1、world_2,无备注)上传至插件作者运营的小型服务,以帮助修复问题。你将获得一个私有链接和一个删除密钥;执行 /vdt diagnose delete <id> 可删除报告,报告将在 30 天后自动消失。支持自定义时间每日上传(report-upload.daily,默认关闭)。发送者的 IP 地址不会被存储。隐私政策。
  • 冲突检测 - 如果另一个插件持续覆盖世界的视距设置,两者将陷入无休止的争夺。经过几个周期的冲突后,ViewDistanceTweaks 将停止管理该世界,在控制台中提示一次,并列出可能导致此问题的已安装插件。/vdt doctor 也会显示此信息。在该世界上手动执行 /vdt viewdistance 可恢复控制权。
  • 启动缓冲 - 在重启后的最初几分钟内维持较低的视距。防止冷启动服务器在尚未完全就绪时因最大视距而受到冲击。

玩家独立视距

两组权限可为单个玩家设置视距,而不影响世界整体设置:

viewdistancetweaks.fixed.<n>      视距
viewdistancetweaks.simfixed.<n>   模拟距离

取值范围为 2 到 32,若某人拥有多个权限,取最高值;收回权限后,该玩家将恢复使用世界默认值,无需重新登录。两者都需先在配置文件中启用。它们需要不同的前缀,否则一个节点会同时设置两者。

视距设置仅在客户端生效,不消耗服务器资源。模拟距离设置确实消耗资源,因此建议将其保留给工作人员,而非作为捐赠者福利出售。

/vdt status --fixed 可查看当前谁持有什么权限,以及这些设置是来自权限、AFK 节流还是延迟节流。


预设与配置文件

这是两个名字相似但功能不同的东西,对此表示歉意。

/vdt preset <small-server|large-network|performance-first> 会将设置写入你的 config.yml。如果你不想手动调整四十个参数,这是一个起点,而非最终答案。

/vdt profile <name> 会在现有配置之上叠加一个临时配置文件,定义在配置文件中的 profiles: 下。不会写入磁盘,执行 normal 即可恢复所有设置。它的存在是为了让你能在活动期间切换到事件专用设置,而无需中途编辑 config.yml。max-view-distance-cap 和 max-simulation-distance-cap 是硬上限,应用于所有其他规则之后,因此设置为 8 就真的是 8。


预生成地形

生成区块是服务器最昂贵的操作,也是其他所有功能只能被动响应的环节。提前构建地形可以消除这一瓶颈:已存在的区块直接从磁盘读取,成本极低,从而无需触发区块生成保护机制。

启用 idle-pregeneration(空闲预生成)后,它会在最后一名玩家下线时运行,并在有人上线时暂停。或者你可以手动驱动它:

/vdt pregen start world 500              以世界出生点为中心
/vdt pregen start world 500 --here       以你站立的位置为中心
/vdt pregen schedule world 500 04:00     每天凌晨 4 点(服务器时间)开始,即使有玩家在线也会执行
/vdt pregen schedule cancel              取消计划任务
/vdt pregen status                       查看进度、速率和预计剩余时间 (ETA)
/vdt pregen stop                         永久暂停,保留当前进度
/vdt pregen cancel --confirm             丢弃所有进度

scheduled(计划任务)适用于维护窗口,而非完全空载的服务器:START 触发器从“只要服务器为空就执行”变为“在指定时钟时间执行”,但一旦开始运行,它仍然受 pause-above-mspt(高于特定 MSPT 时暂停)、min-free-memory-percent(最低可用内存百分比)和 pause-when-players-online(玩家在线时暂停)的控制,与其他任何自动运行一样。它会每天重复执行,直到被取消;并且——像本插件中其他由命令驱动的状态一样——它不会写入 config.yml,因此重启后需要重新设置。

有三件事防止它变成它所解决的问题本身。它使用与距离引擎相同的滚动平均 MSPT 进行节流,因此两者永远不会就“服务器是否繁忙”产生分歧。当堆内存不足时,它会停止而不是减速,因为通往 OutOfMemoryError(内存溢出错误)的慢速路径依然是内存溢出错误。此外,它将进度写入磁盘,因此崩溃或夜间重启可以从断点继续。

它还将自身生成的区块排除在区块生成保护机制之外。如果没有这一机制,启动运行会让插件误以为玩家正在超越生成器速度,从而限制所有人的视距。这是插件在与自己对抗。

注意半径。工作量是 (2*radius+1)²,因此 250 大约是 251,000 个区块,而 1000 则超过四百万个。如果设置了世界边界,会自动将超出边界的半径限制下来(配置中的 respect-world-border,默认开启)——所以输入一个过大的数值只会产生一行日志,而不会浪费四百万个边界内玩家无法到达的区块。


预测性预加载

沿快速移动玩家的行进路径加载区块,以便到达某处时不会导致游戏刻卡顿。

需要明确的是这是什么:它在服务器端使区块就绪。没有人能看到更远的地方,因为客户端仍然只接收其自身视距覆盖的内容。你注意到的是卡顿的消失,而不是视野的扩大。

它跟随运动向量,而不是玩家注视的方向。在使用鞘翅飞行期间,视角会不断摆动,而飞行路径保持直线,正是这条路径决定了服务器需要哪些区块。注视方向可以按一半权重混合进去,但默认是关闭的。

生成默认也是关闭的,且应保持关闭。如果开启,这就不再是一个加载器,而是一个由飞行最快的玩家驱动的第二个不受控制的地形生成器,而这正是本插件其余部分旨在抑制的负载峰值。未探索的地形才是预生成的用途所在。


配置

点击展开完整 config.yml
# ============================================================
#   ViewDistanceTweaks - LucasTHCR Edition
#   Compatible with Paper 1.21.* - 26.*+
# ============================================================

# 插件版本 - 请勿更改
version: 6

# 总开关。插件默认管理模拟/视距,使用以下默认值;如果你希望先进行全部配置(或在游戏内使用 /vdt disable),请将此项设置为 false。
enabled: true

# ============================================================
#   更新
# ============================================================
# 有新版本发布时通知你?仅在启动时发起一次异步请求,从不阻塞服务器,且不下载任何内容。如果机器没有出站互联网访问权限,请将其关闭。无论此设置如何,/vdt update 始终可按需检查。
# (在 2.8.3 之前,这被称为 update-checker;旧名称仍然有效。)
update-notify: true

# 自行安装新版本。默认关闭,由你决定每次更新。如果你不想再操心此事,请将 enabled 设置为 true。
#
# 这仅涉及 ViewDistanceTweaks。不查看任何其他插件,更不用说替换它们:它能写入的唯一文件是以本插件自身的 jar 命名的。
#
# 运行的 jar 文件永远不会被修改。下载进入 Bukkit 的 update 文件夹(默认为 plugins/update/,参见 bukkit.yml 中的 update-folder),并在下次 START 时安装。因此:现在下载,下次重启后生效。没有任何插件能在运行中的服务器下安全地替换自己的 jar,本插件也不假装能做到这一点。
#
# 在写入任何内容之前,会根据 Modrinth 为该文件发布的 SHA-512 哈希验证下载文件。如果不匹配,则丢弃而不安装。
#
# 需要上方的 update-notify 保持为 true,因为此功能依赖于其结果。无论此设置如何,你始终可以使用 /vdt update download 按需获取更新。
auto-update:
  enabled: false

  # 仅接受列出本服务器运行的 Minecraft 版本的发布版本。强烈建议将此保持为 true。false 允许插件安装未经针对你的服务器版本测试的构建。
  require-matching-game-version: true

  # 可安装的 Modrinth 发布渠道:release(正式)、beta(测试)、alpha(实验)。
  # 如果你想尽早获得修复并接受随之而来的风险,请添加 "beta"。
  accepted-release-types:
    - release

# ============================================================
#   空闲预生成(可选,默认关闭)
# ============================================================
# 提前构建地形,使玩家无需等待。生成区块是服务器最耗时的操作,而该插件通常只能对此做出反应。如果地形已经存在,则直接从磁盘读取,这非常轻量,且永远不会触发区块生成保护机制。
#
# 有三条规则防止它变成它原本旨在解决的问题:
#   * 它使用与距离引擎相同的滚动平均 MSPT 进行节流控制,而不是瞬时读数,因此两者在判断服务器是否繁忙时不会发生分歧。
#   * 它在内存不足时停止,而不是减速。一条通往 OutOfMemoryError(内存溢出错误)的较慢路径仍然是 OutOfMemoryError。
#   * 它将进度写入磁盘,因此崩溃或夜间重启会从断点处恢复,而不是无声地丢失数小时的工作成果。
#
# 它还将自己的区块排除在区块生成保护机制之外。如果没有这一设置,启动运行会使插件误认为玩家跑在了生成器前面,从而限制所有人的视距。
idle-pregeneration:
  enabled: false

  # 在最后一位玩家下线后自动开始。将 "world" 设置为你想要生成的世界;留空则不会自动启动任何内容,但 /vdt pregen 命令仍可用。若要按固定时钟时间而非“当服务器为空时”启动,请使用 /vdt pregen schedule <world> <radius> <HH:mm> - 参见 /vdt pregen。
  start-when-empty: true
  world: ""
  # 围绕世界出生点的半径,以区块为单位。250 个区块相当于 4000 块的半径。
  # 注意平方效应:工作量是 (2*半径+1)^2 个区块,因此 250 大约是
  # 251,000 个区块,而 1000 则超过四百万。请根据世界边界来匹配此值,
  # 而不是随意选择一个整数。
  radius: 250

  # 拒绝任何高于此值的 /vdt pregen 启动请求,以防因半径输入错误而排入需要数周才能完成的运行任务。
  max-radius: 5000

  # 同时处于活动状态的区块请求数量,以及每批请求之间的等待刻数。数值越高 = 速度越快且负载越重。默认值故意设置得较为温和;如果在有剩余资源的机器上运行,可以提高这些值。
  chunks-per-batch: 4
  tick-interval: 5

  # 当服务器 MSPT 高于此值时暂停。故意远低于 decrease-mspt-threshold:
  # 预生成是可选工作,应在距离引擎开始防御 TPS 之前很久就让出资源。
  pause-above-mspt: 35.0

  # 当空闲堆内存低于此百分比时完全停止。高于 memory-safeguard 自身的下限,
  # 因为大规模生成比增加距离分配内存的速度快得多。
  min-free-memory-percent: 30.0

  # 一旦有任何人上线,立即暂停自动运行,并在服务器再次变为空闲时继续。
  #
  # 这不适用于通过 /vdt pregen 手动启动的运行:如果有人在世界中键入命令,
  # 并不表示他们希望被要求先下线。
  # 手动运行仍受 pause-above-mspt 和 min-free-memory-percent 的限制,因此
  # 它们仍然无法将服务器拖垮。
  pause-when-players-online: true

  # 将半径限制为世界边界在当前中心周围允许的范围,而不是生成边界内的人无法到达的区块。
  # 仅当设置了小于默认值(60,000,000 块)的边界时才有关联意义;
  # 如果你计划稍后扩大边界并希望提前准备好地形,请关闭此项。
  respect-world-border: true

# ============================================================
#   预测性预加载(可选,默认关闭)
# ============================================================
# 沿着快速移动玩家的行进路径加载区块,以便到达某处时不会导致游戏刻卡顿。
#
# 明确说明一下这是什么:它使区块在服务端就绪。它并不会让任何人看得更远。
# 客户端仍然只接收其自身视距范围内的内容。可见的效果是没有卡顿,而不是更宽的视野。
#
# 预测遵循移动向量,而不是视角方向。在使用鞘翅飞行期间,视角不断摆动,
# 而飞行路径保持直线,正是这条路径决定了服务器需要哪些区块。
predictive-preloading:
  enabled: false

  # 每次处理之间的间隔刻数,以及玩家必须维持的最低速度。
  # 每刻 0.8 块大致相当于疾跑速度;鞘翅飞行速度远高于此。
  tick-interval: 10
  min-speed-blocks-per-tick: 0.8

  # 沿路径查看多远,以及所有玩家共同参与的每个周期中区块请求的上限。
  lookahead-chunks: 4
  max-chunks-per-cycle: 8

  # 当服务器 MSPT 高于此值时跳过一次处理。预加载是一个舒适功能,在压力之下应最先被禁用。
  pause-above-mspt: 40.0

  # 将视角方向以一半权重混合到预测中。有助于玩家即将转弯的情况,但在持续旅行期间会增加噪声。默认关闭。
  blend-look-direction: false

  # 允许预加载尚未存在的生成地形。
  # 请保持此项为 false。如果开启,这将不再是一个加载器,而是变成了一个由飞得最快的人驱动的、不受控制的第二个生成器,这正是本插件其余部分旨在抑制的负载峰值。对于未探索的地形,请使用 idle-pregeneration。
  allow-generation: false

# ============================================================
#   调整
# ============================================================
# 调整模式:
#   proactive - 在性能受损前主动调整距离
#               (基于区块数量目标)
#   reactive  - 响应 MSPT 变化
#   mixed     - 结合两者;过载时优先减少(推荐)
#   off       - 完全禁用自动模拟/视距管理。模拟/视距保持原样不变;仅 /vdt simulationdistance|viewdistance
#               (临时覆盖)仍可更改它。其他一切功能独立运作:空闲预生成、预测性预加载、AFK
#               节流、按玩家固定距离、MSPT 跟踪。如果你只想使用预生成/预加载子系统而不需要其他功能,请使用此选项。
adjustment-mode: mixed

# 插件启动后应等待多少刻才运行第一次检查?
# 2400 = 2 分钟,有助于服务器在重启后稳定下来。
start-delay: 2400

# 检查距离是否需要调整之间的间隔是多少刻?
# 200 = 每 10 秒一次。较短的间隔主要能加快减小速度:
# 增大仍受下面的 passed-checks-for-increase 限制。
ticks-per-check: 200

# 必须有多少次连续检查确认增大才能应用?
#
# 这是控制距离恢复速度的主要刹车。当 ticks-per-check 为
# 200(10 秒)时,每次确认都需要十秒时间才会发生任何增大,并且
# 在任何不健康的检查中都会重置。
#
# 9 次确认和 max-increase-step 2 意味着大约每 90
# 秒增加 +2 个区块,因此在健康状况良好的情况下,世界会在大约九分钟内从 4 -> 16 增长。
# 如果更改 ticks-per-check,请按比例缩放此项以保持相同的节奏。
# 早期版本在此处默认为 10,步长为 1,这意味着每个区块需要五分钟,而同样 climb 则需要一小时 - 安全,但慢到足以让管理员合理地认为插件已停止工作。
#
# 如果你的 MSPT 波动较大且希望在增大前更加确定,请提高此值;
# 仅在你也信任 mspt-prediction 和 revert-increase 以纠正错误决策时降低此值。
passed-checks-for-increase: 9

# 必须有多少次连续检查确认减小?
# 1 = 过载时立即反应(推荐)
passed-checks-for-decrease: 1

# 是否在更改距离时在控制台记录一行日志?
log-changes: true

# 是否向拥有 viewdistancetweaks.notify 权限的玩家发送消息?
# 对于希望实时跟踪更改的管理员很有用。
announce-changes-in-chat: false

# 公告消息的格式。占位符:
#   {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-settings:

  # 全局最大 ticking 区块数(跨所有世界)。
  # 公式:(2*sim+1)^2 * 玩家数量
  # 示例:20 名玩家,Sim 8 -> (17)^2 * 20 = 5780
  global-ticking-chunk-count-target: 5780

  # 全局最大非 ticking 区块数(视距减去模拟距离)。
  # 公式:((2*view+1)^2 - (2*sim+1)^2) * 玩家数量
  # 示例:20 名玩家,View 12,Sim 8 -> (625 - 289) * 20 = 6720
  global-non-ticking-chunk-count-target: 6720

  # 2.6 新增:驱动玩家数量为 ZERO 的世界的目标。
  #   min  - 将其降至配置的最低值(推荐,默认)
  #   max  - 将其升至配置的最高值(2.6 之前的行为)
  #   keep - 保留当前值
  # 当世界为空时,没有区块会 tick,因此“max”直到有人进入之前都不消耗任何资源,此时他们会落入一个完全达到最大值的 world,
  # 且 max-decrease-step 只能在每次检查中将其降低一级。这正是 startup-grace 旨在防止的负载尖峰,因此“min”作为默认值。
  empty-world-target: min

  # 2.7 新增:根据区块内实际包含的内容对区块进行加权,而不是将它们全部同等计数。海洋区块几乎不花费成本;持有
  # 500 漏斗分拣系统的区块可能单独主导一次 tick,但简单的
  # (2*d+1)^2 公式将两者都视为一个单位,因此红石密集型世界与充满水的世界获得相同的预算。
  #
  # 检查区块本身也是工作,因此这会每轮采样每个世界中有限数量的
  # 已加载区块(轮询)并得出平均乘数,每 ticks-per-check 刷新一次。它从不扫描每个区块。
  use-complexity-weighting: false

  # 每次刷新时每世界采样的已加载区块数量。越高越准确但工作量越大。40 对于稳定的平均值来说已经足够。
  complexity-sample-chunks: 40

  # 在计算任何方块实体之前的普通区块的基础成本。
  complexity-default-weight: 1.0

  # 每种材料每个方块实体的附加费。名称为 Bukkit Material
  # 名称。未列出的任何内容均不添加任何成本。
  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-settings:

  # MSPT 低于多少时应考虑增加距离?
  increase-mspt-threshold: 40.0

  # MSPT 高于多少时应考虑减小距离?
  # 一次 tick 最长持续 50ms (= 20 TPS);玩家从约 47ms 开始注意到延迟。
  decrease-mspt-threshold: 47.0

# 如果为 true:当服务器过载时,优先降低模拟距离。
  # 只有在模拟距离已达到该世界的配置最小值后,才会降低视距。模拟距离对 TPS 的影响更大,而降低视距会导致玩家看到可见的区块闪烁,因此除非真正需要,否则不会调整视距。
  # 如果为 false:模拟距离和视距会同时降低(旧版行为)。
  # 默认值:false
  prioritize-simulation-distance: false

  # 在单个检查周期中,模拟/视距在每个方向上最多可变化的步数。将两者都设置为 1 则恢复旧版行为,即每次只变化一个区块的距离。
  #   max-increase-step - 限制一次检查中距离增长的最大幅度
  #   max-decrease-step - 限制一次检查中距离缩小的最大幅度
  #
  # 故意将这两个值设置得不同。增长是一种舒适体验:每次两个区块的速度足够快,恢复效果可在几分钟内显现;而且如果某次增长判断错误,会在下一次检查时被 revert-increase-if-overloaded 撤销。缩小是一种防御机制,设置为 4 可以让服务器在真正陷入困境时一步退出,而不是让玩家眼睁睁看着它缓慢下降。
  #
  # 默认值:向上 2,向下 4
  max-increase-step: 2
  max-decrease-step: 4

  # 在增加模拟/视距后,稍后重新检查 MSPT(见下文)。如果服务器因此立即过载,则在下次检查时回滚此次增加,而不是等待正常的 passed-checks-for-decrease 延迟。这可以防止“直接跳到最大值,然后每次只降一步慢慢回落”的问题。
  revert-increase-if-overloaded: true

  mspt-tracker-settings:

    # MSPT 平均值是在多少个 tick 内计算的?
    # 200 = 10 秒,即一个检查间隔。数值越高越平滑,但反应越慢:一分钟的平均值几乎完全掩盖了长达一秒的卡顿。
    collection-period: 200

    # MSPT 预测:即使我们知道从历史记录来看这会引发卡顿,也阻止增加距离。
    mspt-prediction:
      enabled: true

      # 应为预测存储多少分钟的历史数据?
      history-length: 30

      # 预测生效前所需的最小数据点数。
      # 防止在服务器启动后立即做出错误决策。
      min-samples: 5

    # MSPT 方差:服务器可能拥有非常理想的 *平均* MSPT,但仍然出现严重的逐 tick 尖峰(例如红石时钟、区块生成爆发、插件调度器)。仅检查平均值会遗漏这些问题。此处跟踪最近 tick 时间的离散程度(标准差),并可将高方差的服务器视为过载状态,即使平均 MSPT 仍低于 decrease-mspt-threshold。
    mspt-variance:
      enabled: true

      # 使用多少个最近的 tick 样本(来自 Paper 的 getTickTimes())来计算标准差。getTickTimes() 最多保存 100 个样本(约 5 秒,按 20 TPS 计算);此选项控制其中使用了多少样本。
      sample-window: 100

      # 超过此标准差(毫秒)时,服务器被视为“不稳定”,并在降低距离时被当作过载处理,即使平均 MSPT 正常。典型的稳定服务器标准差约为 1-4ms;明显的卡顿通常从 8-10ms+ 开始。
      variance-threshold: 8.0

      # 评估方差之前所需的最小样本数。
      # 防止在服务器启动后立即产生误报。
      min-samples: 20

      # 如果为 true,高方差也会阻止增加距离(除了强制减少外),即使平均 MSPT 看起来正常。推荐设置为 true。
      block-increase-on-high-variance: true

      # 标准差是对称的。它衡量最近的 tick 围绕平均值的离散程度,无论方向如何。一台在 4ms 和 18ms 之间波动(平均约 10ms,仍然完全正常)的服务器,可能会触发与在 40ms 和 55ms 之间波动(平均约 47ms,实际上正在挣扎)相同的标准差阈值。只有当平均 MSPT 至少达到此值时,方差才会被视为过载。低于该值时,即使方差超过 variance-threshold,也会被忽略。
      min-avg-mspt-to-trigger: 25.0

# ============================================================
#   每位玩家固定视距(可选)
# ============================================================
# 允许特定玩家(例如管理员、主播)保持固定的客户端视距,
# 无论插件为该世界设置的视距是多少。这仅影响该玩家接收到的数据。它不会改变世界的服务端视距,也不会影响本插件管理的大多数区块预算。
#
# 授予权限 "<permission-prefix><value>" 以设置该玩家的固定视距,例如使用权限前缀 "viewdistancetweaks.fixed." :
#   viewdistancetweaks.fixed.20   -> 该玩家始终获得视距 20
# 如果一名玩家拥有多个此类权限,则使用最高值。
# 有效值为 2-32;高于此范围的数值会被限制为 32。请注意,玩家永远不会看到超过其自身客户端渲染距离设置所允许的区块数。
# 撤销权限后,玩家将恢复为其所在世界的正常视距,无需重新登录。
# ---------------------------------------------------------------------------
# 按世界划分的 MSPT(每刻毫秒数)
# ---------------------------------------------------------------------------
# 服务器通常报告一个统一的 MSPT 数值。当单个世界导致负载过高时,这个单一数值会将所有世界拉低,导致所有世界都被节流——包括那些原本安静且并非问题来源的世界。
#
# 启用此功能后,插件将服务器 tick(刻)在多个世界之间进行分配,并根据每个世界的份额分别进行评估。导致延迟的世界会首先被缩小;安静的世界则不受影响,甚至可能继续增长。
#
# 重要提示:这并不改变上述阈值含义。一个恰好承担其公平份额 tick 的世界,仍会与之前相同的 decrease-mspt-threshold(降低 MSPT 阈值)进行比较。只有那些负担多于或少于其份额的世界才会看到调整后的数值,因此无需重新调优。
# 在单世界服务器上,此功能没有任何效果。
per-world-mspt:

  # 默认值:false。开启此项会改变哪个世界首先被节流。
  enabled: false

  # 每次读取按世界划分的开销之间的 tick 间隔。服务器 tick 时间本身是每刻读取一次的,因此提高此值并不会使插件对延迟尖峰的响应变慢——它只会降低世界间分配的刷新频率。在世界数量非常多的服务器上可提高此值。
  # 默认值:20(每秒一次)
  sample-interval: 20

  # 在 Folia 上,直接测量区域 tick 时间,而不是从世界内容中估算。在 Paper 上无效,因为 Paper 没有可供读取的区域级计时数据。
  #
  # 注意此项的代价:在 Folia 上测量的数值是区域的 tick 周期,而每个跟得上的区域都会报告实际的 tick 速率。因此,无论哪个世界繁忙,按世界划分的分配结果都是均匀的,无需归因——在此选项开启的情况下,直到区域实际落后之前,按世界划分的 MSPT 对 Folia 没有影响。将其设置为 false 可在 Folia 上也使用估算代理,虽然精度较低,但可以区分繁忙世界和空闲世界。
  # 默认值:true
  prefer-exact-source: true

  # 世界数值偏离全局服务器数值的最大比例。
  # 系数 1.0 表示“该世界恰好承担其公平的份额”。
  #   min - 下限,确保在 struggling(挣扎/高负载)的服务器上,安静的世界不会被误判为一切正常并无限增长
  #   max - 上限,确保某个世界仅在瞬间承担整个 tick 时,不会因为瞬时尖峰而被强行降至最小视距
  # 默认值:0.5 和 2.0
  min-attribution-factor: 0.5
  max-attribution-factor: 2.0

  # 每当根据调整后的数值评估某个世界时,记录一行日志。在初次开启此功能以观察其实际行为时非常有用;之后可能会产生大量噪音。
  # 默认值:false
  log-attribution: false

per-player-fixed-view-distance:
  # 必须为 true,viewdistancetweaks.fixed.<value> 权限才能生效。
  # 此项独立于顶部的总开关 "enabled" 工作。
  enabled: false
  # 必须区分大小写安全;如果末尾缺少 "." 会自动添加。
  permission-prefix: "viewdistancetweaks.fixed."

# ============================================================
#   每位玩家固定模拟距离(可选,2.6 版本新增)
# ============================================================
# 理念与上面的固定视距完全相同,但针对的是模拟距离(Paper 的 Player#setSimulationDistance)。模拟距离控制着玩家周围多大范围内的世界真正进行 TICK(刻):包括生物、红石和作物等。
#
# 小心:与视距不同,这会真正消耗服务器性能,因此广泛发放会给服务器带来负面影响。它旨在供少数工作人员使用,而非捐赠者等级。
#
#   viewdistancetweaks.simfixed.8   -> 该玩家始终获得模拟距离 8
#
# 有效值为 2-32;高于此范围的数值会被限制为 32。如果一名玩家拥有多个此类权限,则使用最高值。撤销权限后,玩家将恢复为其所在世界的正常距离,无需重新登录。
# 请使用与上述视距功能不同的 permission-prefix(权限前缀),否则单个权限将同时设置这两个值。
per-player-fixed-simulation-distance:
  enabled: false
  permission-prefix: "viewdistancetweaks.simfixed."

# ============================================================
#   挂机玩家限速(可选,2.7 新增)
# ============================================================
# 在出生点静止不动的玩家不需要像使用鞘翅飞行的玩家那样大的渲染范围。当玩家进入挂机状态时,其个人渲染距离将降至以下设定值,从而释放出的区块配额会直接归还给全局预算,供真正在游玩的玩家使用。
#
# 挂机状态来源于 Paper 自带的空闲计时器。如果安装了 EssentialsX,则优先使用其挂机状态判定,这样玩家在输入 /afk 命令后会立即被视为挂机,而无需等待 afk-time-minutes 设定的时间。
#
# 注意:显式的 viewdistancetweaks.fixed.<n> 权限优先级高于此限速机制。如果你希望工作人员在挂机时也受到限速,请不要赋予他们该权限。
afk-player-throttling:
  enabled: false
  afk-time-minutes: 5
  afk-simulation-distance: 4
  afk-view-distance: 6
  use-essentials-if-present: true

# ============================================================
#   延迟限速(可选,2.11 新增)
# ============================================================
# 连接状况不佳的玩家无法跟上当前渲染距离所发送的区块数据——数据包会堆积,客户端进一步滞后,而提高其他玩家的渲染距离只会增加该连接需要承载的数据量。降低个人的渲染距离可以释放预算,供那些连接状况良好、真正能利用这些配额的玩家使用。此机制与 afk-player-throttling 相同:仅影响个人渲染距离,通过 Player#setViewDistance / #setSimulationDistance 应用。
#
# 单次高延迟读数不会触发此机制。检查频率与 afk-player-throttling 及 fixed-view 覆盖项的检查周期相同(约每 5 秒一次),且阈值必须在 checks-before-throttle 次连续检查中持续满足,才会对玩家进行限速——因此默认的 3 次相当于持续约 15 秒的高延迟。恢复是即时的:下一次良好的延迟采样即可解除限速。
#
# 如果同一玩家同时受此机制和 afk-player-throttling 影响,取较小(更严格)的渲染距离生效——启用其中一个绝不会提高另一个已设定的距离。
#
# 注意:显式的 viewdistancetweaks.fixed.<n> 权限优先级高于此限速机制,这与 afk-player-throttling 的情况完全相同。
ping-throttling:
  enabled: false
  ping-threshold-ms: 200
  checks-before-throttle: 3
  ping-simulation-distance: 4
  ping-view-distance: 6

# ============================================================
#   区块生成保护(自 2.14 起默认开启)
# ============================================================
# mspt-variance 能注意到地形生成引起的卡顿,但无法识别原因。本机制统计真正正在“生成”的区块(而非仅从磁盘读取),并直接针对原因做出反应。
#
# 生成一个区块会运行完整的地形管线,这正是当玩家高速穿越未探索地形时导致主线程冻结的根本原因。
chunk-generation-safeguard:
  enabled: true

  # 每个世界每秒新生成的区块数阈值,超过此值即触发保护。
  # 8 这个数值适用于乘用鞘翅或马匹快速穿越新地形的情况;步行进入新陆地的玩家生成的区块较少,不会触发保护。
  chunks-per-second-threshold: 8

  # 保护仅在服务器繁忙时生效:MSPT 必须至少达到此值。单个玩家在闲置服务器上探索时会生成大量区块,但不会影响他人。设为 0 表示仅根据区块生成速率生效。
  min-mspt: 30

  # 生成期间锁定渲染距离的增加。在生成过程中扩大渲染距离会加剧导致服务器停滞的因素,进而引发橡皮筋效应(rubber-banding),而这正是本保护旨在避免的现象。
  lock-increase-during-gen: true

  # 此外,在生成期间将渲染距离限制在此值以内。
  # -1 禁用硬性限制,仅使用上方的 lock-increase-during-gen 设置。
  # 渲染距离永远不会低于世界的 min-view-distance。
  emergency-view-distance: 8

# ============================================================
#   客户端渲染距离上限
# ============================================================
# 没有人能看到比其客户端实际绘制范围更远的地方。如果某个世界中所有玩家客户端设置的最高值为 8,而服务器端设置为 16,那么服务器会加载、计算并为那些从未发送给任何人的外层区块支付性能开销。
#
# 开启此功能后,世界的渲染距离将被限制为所有玩家客户端报告的最大值加上下方的缓冲区块数。该上限永远不会低于该世界的 min-view-distance,也不会应用于空世界或客户端未报告值的玩家。
#
# 上限永远不会低于世界的模拟距离,因此单个玩家的视频设置不会拖慢全服农场和红石系统的运行。最高客户端值会保留三分钟,以防止玩家切换维度时导致世界渲染距离剧烈波动。
#
# 默认关闭:只有当你的玩家确实使用了较低的渲染设定时它才有意义;在所有人都使用 16+ 的服务器上,此功能毫无作用。
client-view-distance-cap:
  enabled: false

  # 基于最高报告值增加的额外区块数。设为 1 意味着当玩家将其滑块调高一档时,不会出现直到下次检查才生成出新地形而导致画面空白的问题。设为 0 则表示精确封顶。
  headroom-chunks: 1

# ============================================================
#   基于密度的缩放(可选,2.7 新增功能)
# ============================================================
# 20 名玩家分散在世界各处时,会加载 20 组独立的区块环。
# 而 20 名玩家聚集在同一个公共农场周围时,几乎加载的是相同的区块。
# 主动式公式假设的是第一种情况,因此会导致集群化世界被过度削减视距,
# 而这些视距本是可以轻松提供的。
#
# 当足够多的玩家彼此位于 cluster-radius(聚类半径)区块内时,
# 系统会根据该聚集中的人口占整个世界人口的比例,给予相应的距离奖励。
density-based-scaling:
  enabled: false
  # 在此半径(以区块为单位)内的玩家被视为“在一起”
  cluster-radius: 8
  # 触发任何距离奖励前,单个聚集中所需的最少玩家数
  cluster-player-threshold: 5
  # 最大额外距离奖励,当所有玩家都在同一聚集中时达到最大值
  max-bonus: 4

# ============================================================
#   紧急缓解措施(可选,2.7 新增功能)
# ============================================================
# 最后的手段。当一个世界已经处于最低模拟速度和视距,
# 且服务器仍然高于 decrease-mspt-threshold(降低 MSPT 阈值)时,
# 已经没有更多的距离参数可以削减了。为了防止服务器性能持续恶化,
# 转而移除两种对负载影响较小、更容易舍弃的因素:雷暴天气(额外的光照和天气更新)以及昼夜循环。
#
# 一旦 MSPT 降至 recover-below-mspt(恢复阈值)以下,或在插件禁用时,
# 这两项设置会自动恢复。系统会记住世界的原始 weather(天气)和 doDaylightCycle(昼夜循环)设置,
# 因此如果某个世界原本就故意关闭了昼夜循环,它在缓解结束后仍会保持关闭状态。
emergency-relief:
  enabled: false
  clear-weather: true
  freeze-time: true
  # 故意设置为低于 decrease-mspt-threshold,否则缓解措施会在触发值附近反复开关。
  recover-below-mspt: 40.0

# ============================================================
#   内存安全保护(2.7 新增)
# ============================================================
# 距离不仅仅消耗 CPU。每一圈额外的区块都会驻留在堆中。即使服务器能保持完美的 20ms MSPT,它也可能仅因一次增加操作就导致所有刻都花在垃圾回收上;此时 MSPT 反应过于滞后,无法作为唯一的信号使用。
#
# 当可用堆内存低于 min-free-percent 时,无论 MSPT 如何,所有增加操作都会被阻止。减少操作始终允许。
#
# “可用”指的是相对于 -Xmx 上限而言的“非活跃数据”空闲部分。它是过去一分钟内看到的最低堆使用量,而不是当前的使用量:每个收集器在回收之前都会故意让垃圾堆积,因此单次读数更多地反映了 GC 周期当前所处的位置,而非服务器实际需要的内存量。在一次收集之后,使用量确实等于活跃集,这正是此功能与之比较的对象。
#
# 已在 2.11.1 修复:旧的读数还会计入 JVM 仍被允许增长的额度。以 -Xms 等于 -Xmx 启动——这是 Aikar 的标志和所有托管面板所推荐的——堆会在启动时预先提交,该额度将永久为零,读数也会坍缩为原始占用率。在 ZGC 上,这完全阻止了增加操作;在 G1 上,则是在活跃数据超过大约一半堆大小后才开始。如果你曾通过降低 min-free-percent 来绕过此问题,现在可以将其恢复。
memory-safeguard:
  enabled: true
  min-free-percent: 15.0

# ============================================================
#   诊断信息(可选,2.15 新增)
# ============================================================
# 记录插件所见及所做的决策,以便事后排查问题,而不仅限于问题发生时查看。每天一个文件,位于 plugins/ViewDistanceTweaks/diagnostics,每条记录占一行 JSON:
#   * 每隔 interval-seconds 采样一次:MSPT、TPS、可用堆、玩家数量,以及每个世界的距离、已加载区块和安全保护正在执行的操作
#   * 每次距离变化及其触发的规则
#   * 关键设置,在启动时及每次 /vdt reload 后
# 不会写入任何玩家名称。超过 keep-days 的文件会被删除。
#
# 运行时使用 /vdt diagnose on|off 可切换开关状态,直到下次重启;在此处将 enabled 设置为 true 可从启动时开始记录。
diagnostics:
  enabled: false

  # 两次常规采样之间的秒数。最小值为 10。
  interval-seconds: 60

# 当 MSPT 超过此值时,额外记录一次样本(最多每 10 秒一次),
  # 以避免错过两次常规采样之间的短暂延迟峰值。设为 0 则关闭。
  extra-sample-above-mspt: 0

  # 要记录的内容。备注(使用 /vdt diagnose note <文本>)始终会被记录。
  record-samples: true
  record-changes: true

# 每个样本中包含的每世界详细信息(距离、区块、玩家、生成情况)。
  # 在拥有大量世界的服务器上,关闭此项以减小文件大小。
  per-world: true

  # 仅包含这些世界,例如 ["world", "world_nether"]。留空表示所有世界。
  worlds: []

  # 当今日文件达到此大小时,采样会在当天剩余时间内暂停。
  # 更改和注释仍会写入。
  max-file-size-mb: 50

# 将过去几天的文件打包为 .jsonl.gz,并删除超过 keep-days 天数的文件。
  compress-old-files: true
  keep-days: 7

# ============================================================
#   报告上传(可选,2.16 新增)
# ============================================================
# 将过去 24 小时的诊断数据匿名发送给由插件作者运营的小型服务,以便发现并修复插件中的问题。除非你主动操作,否则不会发送任何内容:
#   /vdt diagnose send            显示将要发送的内容并请求确认
#   /vdt diagnose send confirm    执行发送
#   /vdt diagnose delete <id>     删除你发送的一份报告
#   /vdt diagnose reports         列出从本服务器发送的报告
#
# 不发送的内容:玩家名称、UUID 或 IP 地址、现实世界名称(它们会变为 world_1, world_2 ...)、备注、服务器名称、其他插件。该服务不会存储你的 IP 地址。报告将在 30 天后被删除。
# 详情:https://reports.paperstream.dev/privacy
report-upload:
  url: https://reports.paperstream.dev

  # 每天单独发送一份报告。默认关闭。开启即表示你同意在指定时间发送过去 24 小时的匿名诊断数据。
  # 即使 diagnostics.enabled 为 false,它也会记录诊断数据。
  daily:
    enabled: false

    # 服务器时间,HH:mm。
    time: "04:30"

# ============================================================
#   配置方案(可选,2.7 新增)
# ============================================================
# 针对部分调整值的命名覆盖配置,可通过游戏内命令 /vdt profile <name> 切换,无需在活动进行中修改配置文件。“normal”始终可用,表示“上述配置的数值”。
#
# 方案内部支持的键名:
#   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
#
# 两个 *-cap 键是硬上限,应用于所有其他规则之后,因此设置为 8 确实意味着 8,且无法被 never-reduce-below-players 所抵消。
profiles:
  event-mode:
    decrease-mspt-threshold: 42.0   # 更早地响应负载压力
    max-view-distance-cap: 8        # 活动期间距离的硬性上限
    passed-checks-for-increase: 60  # 并且非常谨慎地增加距离

  night-mode:
    increase-mspt-threshold: 45.0   # 在服务器空闲时放宽限制
    max-increase-step: 2

# ============================================================
#   启动宽限期(可选)
# ============================================================
# 如果启用,插件会在启动时立即强制设置一个较低且固定的模拟/视距(此时 start-delay/ticks-per-check 尚未生效),而不是使用世界原有的距离(这在配置更改或手动覆盖后可能接近最大值,导致冷启动服务器瞬间过载/崩溃)。一旦 duration-ticks 经过,正常的主动/被动/混合调整机制将重新接管,max-increase-step 仍会限制其回升速度。
startup-grace:
  enabled: false
  simulation-distance: 4
  view-distance: 6
  # 6000 ticks = 5 分钟
  duration-ticks: 6000

# ============================================================
#   世界设置
# ============================================================
# 未在此列出的任何世界都将继承“default”设置。
# 你可以使用世界的确切名称来覆盖每个世界的设置。

world-settings:

  default:
    simulation-distance:
      # 完全排除该世界进行管理?
      # 区块仍会被计入全局计算(除非 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

    # 这个世界占多少区块“预算”权重?
    # 1.0 = 正常。0.5 = 重量减半(例如末地,大量空区块)。
    # 0.0 = 世界对全局计算无影响。
    chunk-weight: 1.0

    # 新增:覆盖检查此世界的频率,独立于上述全局 ticks-per-check。
    # 留空或 <= 0 以继承全局值。
    # 适用于繁忙的主世界需要快速响应,而安静、 mostly 空的下界/末地不需要每 30 秒检查一次的情况。
    # ticks-per-check: 200

    # 新增:永不将距离降低到当前玩家数量以下。
    # 适用于玩家较少的小型服务器。
    never-reduce-below-players: false

    # 新增:此世界在主动计算中获得 50% 更多的区块预算。
    # 适用于拥有多个维度的服务器上的主世界。
    priority-world: false

  # 示例:下界世界
  # 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

  # 示例:末地世界(大量空区块 -> 降低权重)
  # 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

  # 示例:具有优先级的核心世界
  # 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

messages.yml 包含玩家和工作人员看到的所有字符串,支持 & 颜色代码和 {placeholder} 占位符替换。它在首次启动时被复制到数据文件夹。每个键都在 jar 包内有回退文本,因此旧的 messages.yml 仍能正常工作而不会出现空白行,缺失的任何内容都会在加载时在控制台中列出一次。

距离单位为区块(chunks),时间单位为刻(ticks),因此 ticks-per-check: 200 相当于 10 秒。两个覆盖命令中的 --duration 参数是例外,该参数以分钟为单位计时。

启动时,旧版 config.yml 会补充新版构建中添加的配置项,而你的原文件会保留为 config.yml.bak。现有配置不会被重写。


命令

命令 功能
/vdt status [--weight] [--fixed] 显示各世界的实时状态:距离、区块计数、MSPT、方差,以及每个实际开启的子系统的信息。--weight 增加区块权重和复杂度乘数,--fixed 列出针对玩家的固定设置
/vdt simulate [world] 试运行。显示下一次检查会做出的决定及其原因,但不进行任何更改
/vdt history 最近应用的 20 次更改记录,每条均附带更改原因。用于事后回答“为什么当前视距是 6”等问题
/vdt analyze 基于本服务器历史记录的优化建议,例如从未被触及的阈值。不会进行任何更改
/vdt doctor 对常见错误进行一次全面检查:平台、阈值、世界限制、其他插件覆盖的距离、各世界 MSPT、可用内存、更新情况。可将结果粘贴到错误报告中
/vdt mspt [debug] 显示 MSPT、TPS 和标准差。添加 debug 参数后会显示原始的 Paper 刻样本数据
/vdt viewdistance <n> [world] [--duration <min>] 手动覆盖视距。若不指定 --duration,则设置将持续至下次重载生效
/vdt simulationdistance <n> [world] [--duration <min>] 同上,用于模拟距离
/vdt profile [name] 切换调优叠加层,或显示当前激活的叠加层
/vdt preset <name> 将内置预设之一写入 config.yml
/vdt pregen <start|pause|resume|stop|cancel|schedule|status> 预生成地形。start <world> [radius] [--here];schedule <world> <radius> <HH:mm> 或 schedule cancel;stop 保留进度,cancel --confirm 丢弃进度
/vdt diagnose [on|off|status|note <text>|send|delete <id>|reports] 记录插件所见及决策过程,保存至 plugins/ViewDistanceTweaks/diagnostics,直至下次重启(若启用 diagnostics.enabled 则从启动开始记录)。note 添加带有时间戳的自定义备注,例如玩家报告卡顿的时间点。send 显示匿名化报告的内容预览,send confirm 上传报告,reports 列出本服务器已发送的报告列表,delete <id> 删除指定报告
/vdt enable / /vdt disable 无需编辑配置文件即可启用或禁用插件的主开关
/vdt reload 重新读取 config.yml 和 messages.yml,并清除手动覆盖设置
/vdt update 询问 Modrinth 是否有新版本可用

权限

所有权限默认仅 OP 拥有,除底部两个数值型权限组外,后者永远不会自动授予。

节点 授予权限
viewdistancetweaks.command.vdt 访问所有 /vdt 命令
viewdistancetweaks.vdt.command.status /vdt status、/vdt history、/vdt mspt、/vdt analyze 和 /vdt doctor
viewdistancetweaks.vdt.command.simulate /vdt simulate
viewdistancetweaks.vdt.command.viewdistance /vdt viewdistance
viewdistancetweaks.vdt.command.simulationdistance /vdt simulationdistance
viewdistancetweaks.vdt.command.preset /vdt preset
viewdistancetweaks.vdt.command.profile /vdt profile
viewdistancetweaks.vdt.command.pregen /vdt pregen
viewdistancetweaks.vdt.command.reload /vdt reload、enable、disable、update、diagnose
viewdistancetweaks.notify 在距离发生变化时接收聊天广播通知
viewdistancetweaks.fixed.<n> 为该玩家设置固定视距
viewdistancetweaks.simfixed.<n> 为该玩家设置固定模拟距离

支持

由 LucasTHCR 制作并维护。

问题反馈、错误报告和功能建议请前往 dc.gg/paperstream。我会阅读那里的所有内容,提供包含你的 config.yml 和 /vdt status 输出的错误报告能省去双方反复猜测的时间。


许可证

版权所有 (C) 2026 LucasTHCR

ViewDistanceTweaks 是自由软件:你可以根据自由软件基金会发布的 GNU 通用公共许可证第 3 版 条款对其进行再分发和/或修改。

本程序的发布旨在希望其有用,但不提供任何担保;甚至不包括适销性或特定用途适用性的隐含担保。详情请参阅 GNU 通用公共许可证。

简而言之:使用它、研究它、修改它、传播它。任何基于此程序分发的衍生作品也必须遵循 GPLv3 协议,并附带源代码。

2.6-RELEASE 及更早版本的发布采用 MIT 许可证;在此条款下获得的副本仍受其约束。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源