原创 工具 【Foila支持】高性能NPC插件-StarMastNPCs 0.1.0 - Fix

[MD] # 星桅NPC · StarMastNPCs > **零实体占用的虚拟 NPC 插件** —— 不生成任何真实生物实体，用数据包直接把 NPC 渲染到客户端。 > 从 1.8 到 26.3 一个包通吃，原生支持 Folia。 *** ## 一、为什么选星桅NPC ### 1. 不占生物上限，想放多少就放多少 传统 NPC 插件的做法是"生成一个真实实体，再把外观改成玩家模样"。这意味着： - 每个 NPC 都要占用一个实体名额，服务器玩家一多，NPC 数量就被迫压缩； - NPC 会参与服务端的实体计算（寻路、碰撞、AI 判定），几十上百个就开始明显吃 Tick； - 一不小心还会被怪物打、被岩浆烧、被清实体指令误删。 **星桅NPC 完全不需要真实实体。** NPC 只存在于客户端画面里，服务端实体表里根本没有它。 因此： - ✅ 不占用生物上限（mob cap），不计入 Folia 的区域实体数量； - ✅ 不参与服务端实体 Tick、不做寻路、不做碰撞计算，规模上去了也不掉帧； - ✅ 无法被攻击、被烧、被清除指令误删，也不会掉落任何物品； - ✅ NPC 脚下的区域可以正常放方块、正常走人，不会"卡住"玩家。 ### 2. 一个包通吃几乎所有版本 | 服务端 | 版本支持 | | --------------------- | ------------------------------------------ | | Spigot / Paper（含各类分支） | Minecraft Java Edition **1.8 \~ 1.21.11** | | 前瞻版本 | **26.1 \~ 26.3** | | Folia | **原生支持**（内部自带区域化调度适配，非"勉强能跑"） | 不需要为不同版本下载不同的包，也不需要等服务端升级后再等作者更新。 ### 3. 服务端升级不再"炸插件" 插件通过公开的数据包 API 与客户端通信，**不依赖任何服务端内部实现细节**。 这意味着小版本更新通常无需更新插件，也不会出现"NMS 改名导致整个插件报废"的情况。 ### 4. Folia 不再是难题 很多 NPC 插件在 Folia 上要么无法加载、要么线程报错。星桅NPC 内置了一套区域化调度适配层， 所有渲染与行为任务都投递到正确的区域线程执行，**开箱即可在 Folia 上稳定运行**。 *** ## 二、和传统 NPC 插件的区别 | 对比维度 | 传统插件（真实实体方案） | 星桅NPC（StarMastNPCs） | | ------------ | -------------------- | --------------------------------- | | **实体占用** | 每个 NPC = 1 个真实实体 | **0 个实体**，只在客户端可见 | | **生物上限** | 占用 mob cap，受服务器限制 | **完全不占用** | | **性能表现** | 数量越多越吃 Tick，需要刻意控制规模 | 不参与服务端实体计算，规模友好 | | **Folia 支持** | 大多不支持，或需专用分支 | **原生支持** | | **跨版本** | 大量依赖 NMS，升级易报错 | 纯 API 实现，跨版本稳定 | | **可被破坏** | 可能被打死、烧毁、误删、掉落物品 | 不可攻击、不可破坏、不产生掉落 | | **脚下交互** | 实体碰撞体可能挡住放方块 / 影响行走 | 不阻挡放置与通行 | | **依赖安装** | 通常无额外依赖 | 需要安装 PacketEvents（见下文） | | **皮肤与外观** | 支持 | 支持正版名 / 皮肤链接 / 本地图片 / MineSkin 生成 | | **全息文本** | 常见 | 支持，且按版本自动选择最佳渲染方式 | | **点击动作链** | 常见 | 支持，可配置权限、冷却、多动作 | *** ## 三、功能一览 - **外观** - 皮肤来源：正版玩家名、皮肤链接（URL）、本地图片文件、MineSkin 在线生成 - 模型切换：经典（粗手臂）/ 苗条（细手臂） - 皮肤第二层完整渲染（帽子、外套、左右袖、左右裤腿） - 发光轮廓（任意颜色，"队长级"高亮效果） - **头顶文本（全息）** - 多行文本、支持 `&` 颜色代码与 `&#RRGGBB` 十六进制颜色 - 高度偏移、等比缩放、按玩家解析占位符（PlaceholderAPI） - 新版本自动使用原生文本实体渲染，老版本自动降级，无需手工配置 [/MD]

[MD] - **姿态与行为** - 姿势：站立 / 潜行 / 坐姿 - 注视：头部跟踪、全身跟随、跟踪范围、平滑插值 - 朝向：手动设置、面向自己、面向指定坐标 [/MD]

[MD] - **交互** - 左键 / 右键 / 任意点击触发 - 动作类型：执行命令、控制台命令、发送消息、播放音效、传送、玩家指令等 - 每个动作可单独设权限；NPC 可设全局冷却 - **权限与可见性** - 可见距离限制、自动剔除（远离玩家自动隐藏，零开销） - 玩家白名单：只有指定玩家能看到 - 交互权限节点、玩家列表（Tab）显示开关 - **管理** - 游戏内管理菜单、创建 / 删除 / 列表 / 详情 / 传送 / 移动 - NPC 导入导出（可跨服搬运） - 配置热重载、自动定时保存 - 中文 / 英文语言文件，可自行新增语言 [/MD]


[MD] - **装备** - 头 / 胸 / 腿 / 靴 / 主手 / 副手 六个槽位 - 支持随时更换，也支持**一键取下**（填 `none`） [/MD]

[MD] *** ## 四、安装 ### 前置要求 | 项目 | 要求 | | -------- | --------------------------------------------------------------- | | 服务端 | Spigot / Paper / Folia，Minecraft 1.8 \~ 1.21.11 或 26.1 \~ 26.3 | | Java | 服务端对应版本所需的运行环境（1.8 / 1.12 用 Java 8，1.17+ 用 Java 17/21） | | **必须安装** | **PacketEvents**（插件名 `packetevents`，2.x；Bukkit 平台最低支持 MC 1.8.8） | | 可选安装 | PlaceholderAPI（用于头顶文本/名称中的占位符） | > ⚠️ **重要**：本插件以"外部依赖"方式使用 PacketEvents，**必须先把 PacketEvents 放进** **`plugins/`** **目录**。 > 若缺少 PacketEvents，服务端会直接拒绝加载本插件并给出提示（这是刻意的保护，避免运行期才报错）。 > > 💡 **1.8 服主注意**：PacketEvents 的 Bukkit 平台自 **1.8.8** 起可用，因此 1.8 请使用 **1.8.8 / 1.8.9**； > 另外 1.8 协议本身不含"发光轮廓 / 队伍碰撞规则 / 独立副手槽位 / 玩家列表隐藏"，插件会自动跳过这些字段 > （不会报错，也不会踢客户端），详见 README 的「兼容性与优雅降级说明」。 ### 安装步骤 1. 把 `PacketEvents` 放入 `plugins/` 目录； 2. 把 `StarMastNPCs-x.y.z.jar` 放入 `plugins/` 目录； 3. 可选：如需占位符支持，一并放入 `PlaceholderAPI`； 4. 重启服务端（首次安装请勿使用 `/reload`）； 5. 控制台出现星桅NPC 启动横幅即安装成功。 ### 文件结构 ``` plugins/StarMastNPCs/ ├── config.yml # 主配置 ├── lang/ # 语言覆盖文件（可选） │ ├── zh_CN.yml │ └── en_US.yml └── npcs/ # NPC 数据，一人一文件 └── <id>.yml ``` *** ## 五、快速上手 主命令：`/starmastnpc`，别名 `/npc`、`/smnpc`。 ### 最常用的几条 ``` /starmastnpc create shop 欢迎光临 # 在脚下创建一个叫 shop 的 NPC /starmastnpc skin shop player Notch # 使用正版玩家 Notch 的皮肤 /starmastnpc pose shop sitting # 设为坐姿 /starmastnpc displayname shop &6杂货铺 # 设置头顶文本 /starmastnpc action shop add right 命令 say 欢迎！ # 右键触发 ``` ### 完整命令表 | 命令 | 说明 | | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | | `create <id> [显示名]` | 在脚下创建 NPC | | `remove <id>` | 删除 NPC | | `list` | 列出全部 NPC | | `info <id>` | 查看 NPC 详情 | | `tp <id>` | 传送到该 NPC | | `movehere <id>` | 把 NPC 移动到你的位置 | | `reload` | 热重载配置与数据 | | `export <id> [文件名]` | 导出 NPC | | `import <文件名> [新id]` | 导入 NPC | | `menu` | 打开管理界面 | | `skin <id> player\|url\|file <值> [模型]` | 设置皮肤 | | `skin <id> reset` | 清除皮肤 | | `skinqueue` | 查看皮肤异步队列 | | `model <id> wide\|slim` | 切换手臂模型 | | `look <id> on\|off` | 注视开关 | | `range <id> <格>` | 注视范围 | | `bodyfollow <id> on\|off` | 全身跟随开关 | | `rotate <id> <yaw> <pitch>` | 设置朝向 | | `face <id>` | 面向自己 | | `faceloc <id> <x> <y> <z>` | 面向指定坐标 | | `pose <id> standing\|sneaking\|sitting` | 设置姿势 | | `displayname <id> <文本>` | 设置头顶文本（用 `\|` 换行） | | `rename <id> <名称>` | 设置实体名称 | | `namevisible <id> on\|off` | 名称显示开关 | | `hologram <id> on\|off` | 头顶文本显示开关 | | `hologramoffset <id> <值>` | 头顶文本高度偏移 | | `hologramscale <id> <0.5~2.0>` | 头顶文本缩放 | | `showintab <id> on\|off` | 玩家列表显示开关 | | `glowing <id> <颜色\|off>` | 发光轮廓 | | `collidable <id> on\|off` | 碰撞开关 | | `viewdistance <id> <格>` | 可见距离 | | `equip <id> <槽位> <物品\|none>` | 设置 / 取下装备（槽位：`helmet`/`chestplate`/`leggings`/`boots`/`mainhand`/`offhand`） | | `action <id> add <left\|right\|any> <类型> <值> [--perm 权限] [--volume 音量] [--pitch 音调]` | 添加点击动作 | | `action <id> remove <序号>` | 移除动作 | | `action <id> list` | 列出动作（含序号） | | `action <id> clear [left\|right\|any]` | 清空动作 | | `cooldown <id> <秒>` | 设置交互冷却 | | `permission <id> <权限节点\|none>` | 设置交互权限 | | `whitelist <id> add\|remove\|clear\|list [玩家]` | 可见白名单 | ### 权限节点 | 权限 | 说明 | 默认 | | ----------------------- | -------------- | --- | | `starmastnpcs.*` | 全部权限 | OP | | `starmastnpcs.command` | 使用主命令 | OP | | `starmastnpcs.admin` | 管理类操作 | OP | | `starmastnpcs.interact` | 允许点击 NPC | 所有人 | | `starmastnpcs.see` | 白名单模式下允许看到 NPC | 所有人 | *** ## 六、配置要点 配置文件：`plugins/StarMastNPCs/config.yml`，改动后执行 `/npc reload` 生效。 | 配置块 | 作用 | | ------------- | ------------------------------------- | | `language` | 语言（`zh_CN` / `en_US`，可在 `lang/` 自行扩展） | | `skin` | 皮肤缓存时长、MineSkin API Key、并发数、超时与重试 | | `behavior` | 注视行为默认值与静态属性 | | `hologram` | 头顶文本的渲染方式、偏移、缩放、行数、刷新间隔 | | `npc` | 皮肤外层显示、坐姿座位高度微调 | | `visibility` | 可见距离、自动剔除、Tab 显示、扫描间隔 | | `performance` | 皮肤加载线程数、批量 tick 规模、单次扫描上限 | | `storage` | 自动保存间隔、关服保存超时 | | `click` | 默认冷却、是否强制交互权限 | | `license` | 授权校验的运行参数（校时源与截止时间内置，见下节） | > **坐姿小贴士**：坐姿 NPC 若出现"悬空"或"略微下沉"，把 `npc.sitting-seat-offset` > 按 0.05 的步进微调即可（悬空调小、下沉调大）。 *** ## 七、授权说明 本插件带有**在线时间授权校验**： - 授权有效期至 **2027-06-30 23:59**； - 启动时会联网校时（读取公共站点的标准时间，多源取中位数，防止单点篡改）； - **超出有效期，或无法联网校时，插件会强制停止运行**（停止前会正常保存全部 NPC 数据、移除已渲染的 NPC 并注销相关监听，不会留下脏数据）； - 运行期会定期复查（默认每 180 分钟），因此长期不重启的服务器也不会"跨过授权期继续跑"； - 若你的服务器处于内网 / 受控网络，请为其放行插件固定使用的几个公共校时站点的出网访问（校时源内置，不支持替换）。 *** ## 八、常见问题 **Q：为什么装好插件后 NPC 一个都看不到？** A：请确认 PacketEvents 已安装且正常启用；并检查玩家与 NPC 的距离是否超过 `visibility.view-distance`。 **Q：NPC 会不会占用服务器的生物数量？** A：不会。NPC（包括坐姿 NPC 的隐形座位）都是纯客户端虚拟实体，服务端实体表中不存在它们，因此不占用生物上限、不计入区域实体数量，也不参与实体 Tick。 **Q：坐姿 NPC 的腿部角度看起来有点"外张"？** A：这是原版客户端对"骑乘中"人形模型的固定姿态，插件已经把座位朝向与 NPC 身体朝向保持同步，使双腿夹角平分线始终朝向 NPC 面向的方向。 **Q：装备怎么取下来？** A：`/npc equip <id> <槽位> none`（也可以填 `air`），客户端会立即清空该槽位。 **Q：支持多少个 NPC？** A：不占用实体的特性让它很容易上百甚至上千，实际规模主要取决于可见距离与扫描间隔（`performance` / `visibility` 可调）。 **Q：升级服务端后需要换包吗？** A：1.8 \~ 1.21.11 与 26.1 \~ 26.3 使用同一个包；小版本更新通常无需更换。 **Q：插件会收集服务器数据吗？** A：插件集成了 [bStats](https://bstats.org/plugin/bukkit/StarMastNPCs/34447)，收集的是**匿名聚合**的技术数据：服务端版本、插件版本、在线人数、Java 版本，以及运行平台（Folia / Spigot-Paper）、插件语言、NPC 数量区间。**不含任何玩家信息、IP 或服务器地址**。如需关闭，把 `plugins/bStats/config.yml` 里的 `enabled` 改成 `false` 即可（该开关对所有使用 bStats 的插件生效）。 *** ## 九、作者与版权 - **作者**：星桅工作室（StarMastStudio） - **内测交流群**：1093939989（QQ） > **版权声明** > 未经授权，禁止搬运、使用、反编译此代码产品。 > 本插件为授权产品，授权有效期至 **2027-06-30 23:59**。 > 请勿将本插件二次分发、转售或用于未获授权的服务器。 *** *感谢选择星桅NPC。使用中遇到问题，欢迎加内测交流群反馈。* [/MD]