**Kinetic** 是一个为 Paper 服务器 (1.21+) 提供的性能和游戏玩法优化器。
它通过智能控制 AI、合并实体、限制数据包、以及优化服务器机制来减少延迟——所有这些都不需要分叉或核心修改。
一些特性可以选择性地与 **ProtocolLib** 集成以实现高级数据包处理。 如果未安装 ProtocolLib 并且 `protocollib-required` 在配置文件中启用，则分层数据包模块将自动禁用。
---
## 关键特性
* **实体、物品和 XP 合并**
* 可配置每个生物类型、材质或 XP 球的堆叠大小。
* 可选的全息图显示 `{amount}`、`{name}`、`{material}`、`{type}`。
* 支持按玩家剔除，全息图随拥有者消失。
* **动态 AI 预算器 (DAB)**
* 距离和优先级感知 AI 节奏控制。
* TPS 适应和抖动注入以防止延迟峰值。
* 实体远离玩家的冻结系统，并使用 FOV/LOS 指标。
* **生成控制**
* 每个区块的软上限，按类别划分。
* TPS 保护，当服务器掉落到阈值以下时拒绝生成。
* 玩家活动区域以外的远距离拒绝生成。
* **漏斗和区块优化**
* 批量漏斗移动，每刻上限。
* 减慢玩家远离时流体更新、植物生长、落叶腐烂和活塞动作的速度。
* **数据包限制 (需要 ProtocolLib)**
* 隐藏远离的实体，限制声音和粒子效果，控制区块传输速度，进行空闲压缩。
* 减少客户端负载的同时保持游戏玩法正确性。
* **仅插件实体剔除**
* 使用 `Player#hideEntity`/`showEntity` 并设置每刻预算。
* 全息图集成确保每个玩家的一致性。
---
## 工作原理
| 子系统 | 目标 | 技术 |
| ------------------ | ------------------------------ | -------------------------------------------------------------------------- |
| **合并** | 减少实体数量 | 合并生物、物品和 XP；可配置堆叠大小和全息图 |
| **AI 预算** | 平滑每刻负载 | 距离加权、动作倍增器、TPS 缩放、抖动、冻结 |
| **生成** | 防止失控实体 | 每个区块上限、基于 TPS 的拒绝、距离拒绝 |
| **区块/漏斗** | 限制红石/机器成本 | 漏斗批处理、活塞上限、生长/腐烂节奏 |
| **数据包** | 减少带宽 + 客户端压力 | 隐藏远离实体、限制声音/粒子效果、控制区块传输速度、元数据限制 |
| **追踪器** | 安全的插件端剔除 | 基于玩家的隐藏/显示，与全息图集成 |
---
## AI 预算曲线示例
当 `activation-dist-mod: 8` 并且 `power: 2.0` 时，距离小于 8 格的实体几乎每游戏刻一次进行 tick，而远处的实体 tick 频率较低。 曲线是非线性的，更倾向于附近的生物：
```
距离 (格) | 相对 Tick 频率
------------------|-------------------
0–8 | 100%
16 | ~50%
32 | ~25%
64+ | ~10% 或冻结 (如果启用)
```
这确保了战斗生物对玩家响应迅速，而其他生物消耗的 CPU 资源很少。
---
## 配置文件
`config.yml` 具有完全注释且模块化的结构。
关键模块包括：
* `merging` – 实体/物品/XP 堆叠和全息图。
* `dab` – 带有冻结、FOV/LOS、排除项的动态 AI 预算器。
* `spawns` – 上限、TPS 保护、远距离规则。
* `hoppers`、`blocks` – 技术机制的时序和批处理。
* `packets` – 数据包限制 (需要 ProtocolLib)。
* `tracker` – 仅插件按玩家可见性。
* `performance` – 全局刻预算分配。
---
## 安装
1. 将 `Kinetic.jar` 放入 `plugins/` 目录。
2. 启动服务器以生成默认的 `config.yml` 文件。
3. 调整模块以适应你的玩家群和服务器类型。
4. 如果你想要高级数据包特性，安装 **ProtocolLib**。
---
## 兼容性
* 需要 **Paper 1.21+**。
* 数据包特性需要 **ProtocolLib**。
* 所有其他系统仅插件运行，不需要分叉或补丁。
---
## 为什么选择 Kinetic?
与轻量级堆叠器或一次性优化器不同，Kinetic 是 **模块化**、**安全**和 **可伸缩** 的。
它将常见的减慢延迟模式整合到一个连贯的系统，具有每个世界的预算、每个玩家的可见性和与 TPS 相关的自适应节奏。
结果： 更流畅的游戏体验、更高的刻率和更干净的服务器，而不会牺牲机制。
---
## 许可和贡献
* 对于错误、性能报告或功能请求，请提交问题。
* 欢迎通过 PR 或配置文件配方分享进行贡献。
* 许可信息提供在仓库中。
---
Спойлер
```
version: 1
# 这主要 Kinetic 的配置。注释解释了每个选项的作用，
# 预期单位/范围以及任何权衡。
# 距离 & 最近玩家缓存 (模块 1)
# 基于网格的缓存，用于预算引擎和其他模块快速
# 近似最近玩家距离。参见设计文档 §6.1。
proximity:
cell-size: 32 # 每个网格单元的方块
move-threshold: 1.25 # 触发单元更新的最小玩家移动量
neighbor-radius-cells: 2 # 要搜索的相邻环数
track-cross-world: false # 如果为 false，仅考虑同一个世界的玩家
# 动态 AI 预算器 (模块 3)。 将 AI 操作控制在刻预算内。
dab:
enabled: true
activation-dist-mod: 8 # 距离乘数，用于考虑实体相对于玩家的“活动”
power: 2.0 # 优先级衰减的非线性形状；较高值更倾向于附近的实体
base-period-ticks: 1 # 未受约束时的默认周期
min-period-ticks: 1 # 下限；永远不要比这个更频繁地安排 AI
max-period-ticks: 40 # 上限；永远不要延迟 AI 多于此
blacklist-entities: [] # 始终 throttling 的实体类型名称（即使已列入白名单）
whitelist-entities: [] # 如果非空，仅这些实体类型被预算器考虑
exempt-nametagged: true # 带名称的生物被视为重要；不太可能被 throttling
exempt-tamed: true # 驯服的生物被视为重要；不太可能被 throttling
# 每个世界的预算系统 - 高级世界级资源分配
per-world-budgets:
enabled: false # 启用每个世界的单独预算池
default-budget: 2500 # 未明确配置的默认世界预算
worlds: # 特定世界预算覆盖
# world: 5000 # 示例：主要世界较高的预算
# world_nether: 1500 # 示例：地狱较低的预算
# world_the_end: 1000 # 示例：末地最小预算
# 特定玩家的排除 - 高级玩家绕过系统
player-exemptions:
enabled: false # 启用个人玩家排除系统
exempt-ops: true # 操作员自动排除
exempt-names: # 需要排除的特定玩家名称
# - "AdminPlayer"
# - "BuilderUser"
exempt-permissions: # 授予排除的权限
- "Kinetic.budget.exempt"
# - "staff.moderator"
exempt-patterns: # 玩家名称的正则表达式模式（不区分大小写）
# - "^Admin.*" # 以“Admin”开头的玩家
# - ".*Builder$" # 以“Builder”结尾的玩家
hard-freeze:
enabled: false
min-player-distance: 64 # 超出此距离的实体可能被冻结（停止 AI）
recheck-period-ticks: 40 # 重复评估冻结资格的时间
max-entities-per-tick: 400 # 每次传递处理的最大实体数
fov:
enabled: true
fov-degrees: 110 # 玩家视野角度大小用于可见性考虑
require-los: true # 确定可见性时需要视线
max-distance: 96 # 用于 FOV 检查的最大距离
wake-on-damage:
enabled: true
duration-ticks: 80 # 受损时暂时解冻
always-active-types: [] # 永远不会冻结的实体类型；例如，如果需要 VILLAGER
per-action-multipliers:
PATHFIND: 1.0
TARGET: 1.2
BREED: 2.0
REPLENISH: 2.0
ANGER: 1.5
tps-adaptation:
enabled: true
threshold: 18.5 # 在此 TPS 以下，增加 throttling 积极性
multiplier: 1.5 # 当 TPS 低于阈值时应用的比例
jitter:
enabled: true
percent: 0.1 # 稍微随机化周期以避免 burst 对齐
cleanup-interval-ticks: 1200 # 定期清除内部簿记
# 生成控制。 提供每个区块的软上限和距离/TPS 保护。
spawns:
enabled: true
per-chunk-soft-cap:
MONSTER: 70 # 每个区块类别的近似软上限
CREATURE: 50
WATER_AMBIENT: 30
tps-guard:
enabled: true
threshold: 18.5 # 在此 TPS 以下，拒绝一部分否则允许的生成
denial-percent: 0.35 # 在 TPS 低于阈值时拒绝的生成比例 (0..1)
far-deny:
enabled: true
min-player-dist: 96 # 拒绝玩家活动区域以外的生成
merging:
entities:
enabled: false
# 搜索半径 (方块) 用于生物的 spawn
radius: 8.0
# 除非在 per-type 下进行覆盖，否则每个实体类型的最大堆叠大小
max-stack-size: 32
# 可选的在堆叠生物上设置自定义名称（可选视觉）。
show-name: true
# 不要堆叠已经有自定义名称的生物。
skip-named: true
# 可选的允许/拒绝控制。 如果 whitelist 不为空，则仅会堆叠这些类型。
# 类型为 Bukkit EntityType 名称，例如，ZOMBIE、SKELETON、CREEPER 等。
whitelist-types: []
blacklist-types: [VILLAGER, ENDER_DRAGON, WITHER, WARDEN, ELDER_GUARDIAN, IRON_GOLEM] # 永远不要堆叠这些类型
# 每个类型的覆盖
per-type:
SLIME:
max-stack-size: 8
MAGMA_CUBE:
max-stack-size: 8
hologram:
enabled: true
# 实体上方的垂直偏移量。 根据版本/模型进行调整。
offset: 0.75
# 没有 per-type 覆盖时使用的基本格式。
# 占位符：
# - {amount}: 堆叠大小（支持以下样式）
# - {type}: Bukkit EntityType 漂亮名称（例如，“僵尸”）
format: "x{amount}"
# {amount} 的格式样式： plain | thousands | compact
# - plain: 1200
# - thousands: 1,200
# - compact: 1.2k
format-style: plain
# 可选的 per-实体类型覆盖。 Key 为 Bukkit EntityType 名称.
# 示例：
# per-type:
# ZOMBIE: "{type} x{amount}"
# SKELETON: "{type} x{amount}"
per-type: {}
items:
enabled: true
# 物品实体的搜索半径 (方块)。
radius: 2.5
# 如果为 true，则仅具有相同的元数据（lore、enchant、model data）的物品才能堆叠在一起。
respect-metadata: true
# 以友好的方式在后台扫描附近的实体；世界修改仍然在主线程上。
async-scan: true
# 允许物品实体在地面上超出经典堆叠大小（库存堆叠不受影响）。
allow-oversize: false
# 合并计数上限（视觉 + 物理）用于一个物品实体。 库存堆叠不受影响。
max-entity-stack: 512
hologram:
enabled: true
# 实体上方的垂直偏移量。 根据版本/模型进行调整。
offset: 0.75
# 没有 per-material 覆盖时使用的基本格式。
# 占位符：
# - {amount}: 堆叠大小（支持以下样式）
# - {material}: Bukkit Material 漂亮名称（例如，“钻石”）
# - {name}: 如果存在显示名称，否则为 {material} 的物品显示名称
format: "x{amount}"
# {amount} 的格式样式： plain | thousands | compact
format-style: plain
# 可选的 per-material 覆盖。 Key 为 Bukkit Material 名称。
# 示例：
# per-material:
# DIAMOND: "{name} x{amount}"
# COBBLESTONE: "{material} x{amount}"
per-material: {}
xp:
enabled: true
# XP 球的搜索半径 (方块)。
radius: 3.0
# 分裂/合并时最大经典 XP 球大小（典型的最大值为 11）。
max-orb-size: 11
hologram:
enabled: true
offset: 0.75
# 占位符：
# - {amount}: 总 XP 值（支持以下样式）
# - {type}: 常量 "XP"
format: "{amount} xp"
# {amount} 的格式样式： plain | thousands | compact
format-style: plain
blocks:
# 对区块更新的节奏控制，以防止当玩家远离时出现级联。
# 更高的冷却时间降低了 churn 但延迟了传播。
physics-cooldown-ticks: 3
# 当玩家远离时，减慢流体更新速度以减少服务器负载。
throttle-fluids: true
# 叶子腐烂的速度：立即 | 推迟 | 推迟_远。 推迟_远在玩家不靠近时延迟。
leaves-decay: defer_far
# 植物生长节奏：立即 | 推迟 | 推迟_远。
plant-growth: defer_far
pistons:
# 限制每刻并发活塞动作以减轻机器负载。
limit-per-tick: 2
# 检测并抑制活塞引擎模式。可能影响红石装置；请谨慎使用。
anti-engines: false
hoppers:
# 漏斗优化模块：批量和限制每刻移动以减少每刻成本。
enabled: true
# 在此刻窗口中批量执行拉动/推动操作以获得更好的局部性。
batch-window-ticks: 4
# 所有漏斗的每刻移动全局上限。
max-moves-per-tick: 128
# 漏斗周围扫描物品实体的半径。
pickup-scan-radius: 1.0
async:
# 用于安全 async 任务的工作线程池大小。 通常 = CPU 核心 / 2.. 核心。
worker-threads: 2
# 增强型 WorkerPool 配置
core-threads: 4 # 核心线程数
max-threads: 8 # 繁忙时的最大线程数
max-queue-size: 100 # 队列中任务达到最大大小时的拒绝大小
# 任务超时设置
task-timeout-ms: 30000 # 默认任务超时 (30 秒)
keep-alive-time-ms: 60000 # 线程存活时间 (1 分钟)
queue-warning-threshold: 0.8 # 队列利用率警告阈值 (80%)
# 监控和健康检查
monitoring:
enabled: true # 启用全面的监控
health-check-interval-ms: 300000 # 定期健康检查 (5 分钟)
# 超载时应重试的任务的后备执行
fallback-execution: true # 在池超载时执行拒绝的任务到主线程中作为后备
# 性能优化
allow-core-timeout: true # 允许核心线程超时并终止
thread-priority-offset: -1 # 线程优先级偏移量相对于正常 ( -1 = 略低于)
packets:
# 基于数据包的优化。 有些特性需要 ProtocolLib。
enabled: false
# 如果为 true，则当缺少 ProtocolLib 时，需要 ProtocolLib 的功能将被禁用。
protocollib-required: true
hide-far-entities:
# 隐藏玩家以外的实体以减少客户端负载（服务器权威）。
enabled: true
# 距离阈值，以方块为单位。
max-distance: 96
# 不要隐藏玩家实体。
exempt-players: true
# 不要隐藏玩家拥有的驯服的生物。
exempt-tamed: true
sound-throttle:
# 限制重复相同的声音每刻的数量，以减少垃圾邮件。
enabled: true
# 每个玩家每刻的声音包上限。
max-per-tick: 5
# 可选的 spatial 去重：限制每个刻时相同位置的重复相同声音
de-duplicate:
enabled: true
bucket-radius: 8
max-per-bucket: 2
particle-throttle:
# 通过集群限制粒子包速率。
enabled: true
# 每个刻时附近集群的最大包数。
max-per-cluster: 20
chunk-streaming:
# 控制区块数据包，避免加入/快速旅行时的突发情况。
enabled: true
# 允许每个刻时传输更多的区块以防止初始渲染或快速旅行受限
max-per-tick: 8
# 不要在新玩家加入时 throttling 区块包以保证世界引导
warmup-ticks: 200
prioritize-player-heading: true
# 仅当 TPS 低于此阈值时启用 throttling
tps-guard:
enabled: true
threshold: 18.5
# 逐渐提升加入后的每个玩家配额，以避免突发
ramp:
enabled: true
base: 4
max: 8
step: 1
period-ticks: 40
metadata-rate-limit:
# 限制频繁的实体元数据更新；白名单关键索引以避免 desync
enabled: false
# 实体之间的时间间隔 (刻数)，用于元数据更新。
interval-ticks: 5
# 始终通过率限制的元数据索引（跳过正常速率限制），以避免 desync。
# 常见索引：0=标志，1=空气，2=自定义名称，3=自定义名称可见，4=静音，5=无重力，等等。
# 根据需要调整版本。 将空白留空不绕过任何内容。
whitelist-indexes: [0, 1]
player-idle-compression:
# 当玩家在阈值之外不活动时，缩放响亮/视觉包预算。
enabled: true
# 在阈值之外被认为是空闲的秒数。
idle-threshold-seconds: 60
# 当玩家空闲时，缩放每个刻时的包上限
sound-scale: 0.5 # 0.05..1.0，乘以声音 max-per-tick
particle-scale: 0.5 # 0.05..1.0，乘以粒子 max-per-cluster
performance:
# 每个刻的全局工作预算（内部单位）。 较低 = 更严格的 throttling。
tick-budget-per-tick: 5000
priorities:
# 每个子系统的相对预算份额。 较高 = 分配更多时间。
AI: 40
HOPPERS: 30
PHYSICS: 30
shared-budget:
# 如果启用，一个子系统中未使用的预算可以被其他子系统借用。
enabled: false
AI: 40
debug:
# 额外的日志记录用于诊断；增加了控制台垃圾邮件。
verbose: false
# 在启用时，采样事件的概率 [0..1]。
sampling-rate: 0.05
# 启用游戏内管理员命令进行调试。
commands-enabled: true
# 插件级别的实体可见性剔除（近似 async 追踪器行为）
tracker:
visibility:
enabled: false
radius: 96.0
exempt-players: true
include-types: [] # 如果非空，则仅将这些 Bukkit EntityType 名称 considered
exclude-types: [ITEM_FRAME, PAINTING] # 永远不要考虑用于 hide/show 决策
max-players-per-tick: 4
# 每个刻处理的最大隐藏/显示操作数
max-ops-per-tick: 400
# 运行可见性传递的频率。
period-ticks: 20
# 如果为 true，全息图 ArmorStands 也会遵循相同的规则进行隐藏/显示。
# 这可以防止为正在剔除的玩家呈现全息图。
integrate-holograms: true
# 区域配置文件和集成
regions:
worldguard:
# WorldGuard 区域 ID 列表，在此处禁用数据包抑制
exempt-packets: []
# TickService 配置
tick-service:
# TPS 监控设置
tps-monitoring:
# 启用实时 TPS 监控和计算
enabled: true
# 当低于此阈值时发出警告的 TPS 阈值 (默认：15.0)
warning-threshold: 15.0
# 健康检查设置
health-checks:
# 启用 tick 服务的全面健康监控
enabled: true
# 在触发健康警告之前允许丢失的最大刻数 (默认：100)
max-missed-ticks: 100
```
