原创 工具 「鲸鱼系列」JYadyReset — Adyeshach NPC 智能刷新引擎 1.0

[MD] # 🐋 「鲸鱼系列」JYadyReset — Adyeshach NPC 智能刷新引擎 > NPC 消失？不用重登，一行指令即刻召回。 当网络波动、客户端卡顿、远距传送或新玩家进服导致 Adyeshach NPC 凭空消失时，JYadyReset 提供全自动 + 手动双重保障，进服即见 NPC，永不掉线。 **⚡ 全版本 · 全核心 | 🎯 零编译依赖 | 🛡️ 零数据风险 | 🔌 优雅降级** --- ## 🌐 兼容性 JYadyReset 通过纯反射桥接 Adyeshach，零编译时依赖、零 NMS 代码。只要你的服务端能跑 Adyeshach，JYadyReset 就能跑。 | 分类 | 支持列表 | |---|---| | MC 版本 | 1.12 / 1.16 / 1.18 / 1.19 / 1.20 / 1.21 及更高版本，全版本支持 | | 服务端核心 | CraftBukkit / Spigot / Paper / Purpur / CatServer / Mohist / Arclight 等，全核心支持 | --- ## 🧠 为什么 NPC 会消失？ Adyeshach 采用乐观可见性追踪——发送 spawn 包后即标记"已显示"。当 spawn 包未能到达客户端时，NPC 永久不可见且无法自愈。 | 场景 | 根因 | |---|---| | 玩家进服 | Adyeshach setup 期间 spawn 包未成功送达，进服看不到 NPC | | 网络丢包 | spawn 包丢失，服务端误以为 NPC 已显示 | | 客户端卡顿 | NPC被 GC 或区块卸载，Adyeshach 未感知 | | 远距传送 | spawn 包先于区块数据到达，客户端静默丢弃 | JYadyReset 的解决策略：强制销毁 → 等待客户端就绪（2 tick = 100ms）→ 强制重新生成。用确定性操作绕过乐观追踪的不确定性。 --- ## 📦 安装 1. 将 `插件` 放入 `plugins/` 目录 2. 确保 `Adyeshach` 已安装（版本 ≥ 2.0） 3. 重启服务器 4. 执行 `/adyreset debug` 验证桥接状态 5. （可选）编辑 `config.yml` 开启自动刷新 --- ## ⚙️ 完整配置 ```yaml # JYadyReset config.yml — 所有配置项 # ━━━ 定时自动刷新 ━━━ # 每隔 N 秒为所有在线玩家刷新 NPC auto-refresh: # 是否启用（默认关闭，建议先手动测试 /adyreset reload 后再开启） enabled: false # 刷新间隔（秒），最小值 5 interval-seconds: 60 # ━━━ 玩家进服自动刷新 ━━━ # 玩家进入服务器后，等待 Adyeshach 完成自身初始化，再强制刷新周围 NPC # 建议开启：进服后自动可见 NPC，无需玩家手动输入命令 refresh-on-join: true # 进服后等待多少 tick 再刷新（等 Adyeshach setupEntityManager + checkVisible 完成） # 默认 40 tick = 2 秒；Adyeshach JOIN 模式自带 20 tick 延迟，建议不低于 20 join-refresh-delay-ticks: 40 # ━━━ 世界切换刷新 ━━━ # 玩家跨世界时自动刷新 NPC refresh-on-world-change: true # ━━━ 远距传送刷新 ━━━ # 玩家同世界远距传送后自动刷新 # 场景：传送到 1000+ 格外再传回 → spawn 包先到、区块后到 → 客户端丢弃NPC refresh-on-teleport: true # 触发传送刷新的最小距离（格），短距离移动不需要刷新 # Adyeshach 默认可视距离为 64，以此作为阈值 teleport-min-distance: 64 # 传送/世界切换后等待多少 tick 再刷新（等客户端加载完区块） # 默认 60 tick = 3 秒；高延迟网络可调大到 80-100 teleport-refresh-delay-ticks: 60 ``` --- ## 🎮 完整指令 | 指令 | 权限 | 功能说明 | |---|---|---| | `/adyreset` | 无 | 显示命令帮助（根据权限自动显示可用子命令） | | `/adyreset reload` | `adyreset.use` | 刷新自己的 NPC | | `/adyreset reload <玩家>` | `adyreset.reloadall` | 刷新指定玩家的 NPC | | `/adyreset reloadall` | `adyreset.reloadall` | 刷新所有在线玩家的 NPC | | `/adyreset debug` | `adyreset.use` | 查看完整调试信息 | ### 完整权限节点 | 权限 | 默认 | 说明 | |---|---|---| | `adyreset.use` | OP | 允许使用 `/adyreset reload`（自身）和 `/adyreset debug` | | `adyreset.reloadall` | OP | 允许刷新指定玩家 `/adyreset reload <玩家>` 和全服刷新 `/adyreset reloadall` | ### Tab 补全 - 子命令自动补全：`reload`、`reloadall`、`debug` - `/adyreset reload` 后自动补全在线玩家名（需 `adyreset.reloadall` 权限） --- ## ✨ 五大触发机制 | 触发方式 | 配置项 | 说明 | |---|---|---| | 🚪 玩家进服 | `refresh-on-join` | 进服后延迟 40 tick 自动刷新周围 NPC，2 秒内就位 | | ⏰ 定时空扫 | `auto-refresh` | 每隔 N 秒为全服在线玩家静默批量刷新 | | 🌍 世界切换 | `refresh-on-world-change` | 跨世界时自动刷新，等待区块加载完成后执行 | | ✈️ 远距传送 | `refresh-on-teleport` | 同世界内传送距离超过阈值（64 格）时自动刷新 | | 👆 手动指令 | `/adyreset` | 玩家自救或管理员全服操作 | --- ## 🔧 四种刷新策略（内部实现） | 策略 | 触发场景 | 特点 | |---|---|---| | **全量刷新** `refreshPlayer()` | `/adyreset reload [玩家]` | 刷新全部公共 NPC，含立即反馈 + 异步完成通知 + 玩家离线保护 | | **近距刷新** `refreshNearby()` | 进服、世界切换、传送事件 | 仅刷可视距离内 NPC，轻量高效 | | **全服批量刷新** `refreshAllPlayers()` | `/adyreset reloadall`、定时空扫 | 分批 50 人/批，递推执行，防 TPS 暴跌 | | **自定义刷新** `refreshEntitiesForPlayer()` | 高级调用 | 可传入自定义NPC列表，仅刷新特定 NPC | --- ## 🖥️ 调试命令 `/adyreset debug` 输出完整示例： ``` ========== JYadyReset 调试信息 ========== Adyeshach 桥接: 已连接 ← 桥接状态 公共 NPC: 15 个（临时: 5 持久化: 10） ← NPC 分类统计 在线玩家: 3 人 ← 玩家数 自动刷新: 已关闭 (间隔: 60 秒) ← 定时刷新状态 世界切换刷新: 已开启 ← 世界切换状态 进服刷新: 已开启 (延迟: 40 tick) ← 进服刷新状态 传送刷新: 已开启 (最小距离: 64 格, 延迟: 60 tick) ← 传送刷新状态 ========================================== ``` --- [/MD]