DynamicDistance

DynamicDistance 是一个面向 Lophine 26.2 与 Folia 区域线程模型的动态视距、模拟距离管理插件。

插件可以按权限组、在线人数、世界和时间段调整玩家距离，并提供 AFK 视距限制、LuckPerms 距离上限、PlaceholderAPI 占位符以及 YAML/MariaDB 数据存储。

运行要求

项目	要求
服务端	Lophine 26.2
Java	Java 25
LuckPerms	可选，用于权限组和最大距离限制
PlaceholderAPI	可选，用于提供 %dd_*% 占位符
MariaDB	可选，默认使用 YAML 存储

当前版本：4.1

功能

• 按权限组配置视距和模拟距离上下限。
• 按在线人数阈值动态降低距离。
• 支持全服阈值和按世界阈值。
• 按服务器时区和时间段调整距离。
• AFK 后只限制视距，模拟距离保持不变。
• 支持永久固定距离和仅当前登录会话生效的临时距离。
• 使用 LuckPerms 权限节点限制玩家可用的最大距离。
• 支持自适应白名单、世界切换重算和可配置提示消息。
• 支持 YAML 与 MariaDB，MariaDB 驱动已包含在插件 JAR 中。
• 内置可关闭的 bStats 匿名使用统计。
• 使用 Folia global、entity 和 async scheduler，不依赖传统全局主线程假设。

安装

1. 确认服务端使用 Lophine 26.2 和 Java 25。
2. 将 DynamicDistance-4.1.jar 放入服务端的 plugins 目录。
3. 启动服务器，生成默认配置。
4. 修改 plugins/DynamicDistance/config.yml。
5. 使用 /dd reload 重载配置，或重启服务器。

LuckPerms 和 PlaceholderAPI 都是可选依赖。未安装时，对应集成会自动关闭。

距离规则

普通玩家的距离会按以下规则计算：

1. 读取玩家匹配到的最高优先级组，priority 数值越小越优先。
2. 应用玩家个人偏好。
3. 应用 LuckPerms 最大距离限制。
4. 应用在线人数和时间段限制。
5. 应用组内最小距离。
6. 应用当前会话的临时距离。
7. 玩家处于 AFK 时，最后限制视距，模拟距离不变。
8. 将结果限制在全局 bounds 范围内。

通过 /dd set 设置的固定距离会绕过自适应与 AFK 规则，但仍受全局 bounds 限制。通过 /dd setonline 设置的距离只在当前登录会话有效。

命令

主命令别名：/dynamicdistance、/dd、/dist

命令中的 vd 表示视距，sd 表示模拟距离。

命令	说明
/dd help	查看插件帮助
/dd get <vd|sd> [玩家]	查看视距或模拟距离
/dd set <vd|sd> <2-32> [玩家]	设置永久固定距离
/dd setonline <vd|sd> <玩家> <2-32>	设置当前会话的临时距离
/dd reset [玩家|all]	重置固定、个人和临时距离设置
/dd playercount [on|off|info]	控制人数自适应模式
/dd whitelist add <玩家>	添加人数自适应白名单
/dd whitelist remove <玩家>	移除人数自适应白名单
/dd whitelist list	查看白名单
/dd reload	重载配置和语言文件

玩家还可以使用 /dd <2-32> 快速设置自己的固定视距。

权限

权限	默认值	说明
dd.help	所有人	查看帮助
dd.get.self	所有人	查看自己的距离
dd.get.others	OP	查看其他玩家的距离
dd.set.self.vd	OP	设置自己的固定视距
dd.set.self.sd	OP	设置自己的固定模拟距离
dd.set.others.vd	OP	设置其他玩家的固定视距
dd.set.others.sd	OP	设置其他玩家的固定模拟距离
dd.setonline	OP	设置在线玩家的临时距离
dd.reset.self	OP	重置自己的设置
dd.reset.others	OP	重置其他玩家的设置
dd.reset.all	OP	重置全部玩家的设置
dd.mode.playercount	OP	控制人数自适应模式
dd.whitelist	OP	管理人数自适应白名单
dd.reload	OP	重载插件配置
dd.bypass.playercount	无	绕过人数自适应限制
dd.bypass.afk	无	绕过 AFK 视距限制
dd.bypass.maxdistance	无	绕过 LuckPerms 最大距离限制

LuckPerms 距离上限

使用带数值后缀的权限节点设置最大距离：

dd.maxdistance.view.12
dd.maxdistance.simulation.8

插件会读取玩家当前世界的 LuckPerms 上下文。同一维度存在多个节点时，优先使用当前世界节点中的最大值，否则使用全局节点中的最大值；未配置时上限为 32。

配置示例

下面是一个精简的人数自适应配置：

groups:
default:
priority: 100permission: ""max-view-distance: 12max-simulation-distance: 8min-view-distance: 4min-simulation-distance: 3bypass-adaptive: falseplayer-count:
enabled: trueper-world: falsethresholds:
0: { view-distance: 12, simulation-distance: 8 }20: { view-distance: 10, simulation-distance: 6 }50: { view-distance: 8, simulation-distance: 4 }player-count:
enabled: trueinterval: 200hysteresis: 3afk:
enabled: truetimeout-seconds: 300check-batch-size: 50view-distance: 2

完整配置和字段注释见 src/main/resources/config.yml。

AFK 行为

• AFK 检测使用服务端玩家 idle clock，不注册高频移动或交互监听器。
• 玩家进入或退出 AFK 状态时才重新计算距离。
• afk.view-distance 仅设置 AFK 视距上限，不修改模拟距离。
• 固定距离玩家和拥有 dd.bypass.afk 权限的玩家不受 AFK 限制。
• 旧版 afk.simulation-distance 配置项会在自动配置更新时删除。

MariaDB

将存储类型改为 mariadb，然后填写连接信息：

storage:
type: "mariadb"save-interval-minutes: 5save-on-quit: truesave-on-change: truemariadb:
host: "127.0.0.1"port: 3306database: "dynamicdistance"username: "root"password: ""table-prefix: "dd_"use-ssl: falsemax-pool-size: 4

PlaceholderAPI

占位符	返回内容
%dd_count%	当前在线人数
%dd_mode%	人数自适应模式状态
%dd_vd%	当前玩家视距
%dd_sd%	当前玩家模拟距离
%dd_afk%	当前玩家 AFK 状态
%dd_whitelisted%	当前玩家是否在白名单
%dd_world%	当前玩家所在世界
%dd_vd_<玩家>%	指定在线玩家的视距
%dd_sd_<玩家>%	指定在线玩家的模拟距离
%dd_afk_<玩家>%	指定在线玩家的 AFK 状态

bStats 匿名统计

插件使用 bStats 统计匿名使用情况，插件 ID 为 33381。统计页的数据通常每 30 分钟更新一次。

bStats 默认统计匿名服务器 UUID、服务端数量、在线人数、在线模式、服务端软件、Minecraft/Java/插件版本、操作系统、CPU 架构与核心数，并生成国家或地区分布。本插件额外统计以下配置分布：

• 存储类型：YAML 或 MariaDB。
• AFK 视距限制是否启用。
• 时间段模式是否启用。

统计不会上传玩家 UUID、玩家名称、聊天内容或数据库连接信息。请求的来源 IP 可能由 bStats 按其隐私政策处理并用于生成地区统计。服主可以在 plugins/bStats/config.yml 中将 enabled 设置为 false，关闭该服务器上所有使用 bStats 的插件统计。

从源码构建

需要 Java 25 和 Maven 3.9 或更高版本：

mvn clean test package

构建产物位于：

target/DynamicDistance-4.1.jar

Lophine 与 Folia 说明

插件直接使用 Lophine 26.2 提供的玩家视距与模拟距离 API。这些 API 已进入服务端的 CraftPlayer、FeatureHooks 和 Moonrise 距离处理路径，因此没有额外使用易碎的版本专用 NMS 调用。

所有实时玩家状态都在对应 entity owner context 中访问；磁盘、数据库和离线玩家资料查询在异步线程执行。folia-supported: true 表示插件允许在 Folia 风格服务端加载，但正式部署前仍建议在自己的服务端环境测试登录、跨世界、重载和高并发上下线流程。

语言文件

内置语言：

• zh_CN
• en_US

可复制 plugins/DynamicDistance/lang 下的语言文件并修改，然后在 config.yml 中设置 language。将任意消息设置为 none 可以关闭该提示。