星桅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）
- 新版本自动使用原生文本实体渲染，老版本自动降级，无需手工配置
姿态与行为
- 姿势：站立 / 潜行 / 坐姿
- 注视：头部跟踪、全身跟随、跟踪范围、平滑插值
- 朝向：手动设置、面向自己、面向指定坐标
交互
- 左键 / 右键 / 任意点击触发
- 动作类型：执行命令、控制台命令、发送消息、播放音效、传送、玩家指令等
- 每个动作可单独设权限；NPC 可设全局冷却
权限与可见性
- 可见距离限制、自动剔除（远离玩家自动隐藏，零开销）
- 玩家白名单：只有指定玩家能看到
- 交互权限节点、玩家列表（Tab）显示开关
管理
- 游戏内管理菜单、创建 / 删除 / 列表 / 详情 / 传送 / 移动
- NPC 导入导出（可跨服搬运）
- 配置热重载、自动定时保存
- 中文 / 英文语言文件，可自行新增语言
装备
- 头 / 胸 / 腿 / 靴 / 主手 / 副手六个槽位
- 支持随时更换，也支持一键取下（填 none）

四、安装

前置要求

项目	要求
服务端	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，并请使用 PacketEvents 标准版（自带 Adventure 的构建；1.8 ~ 1.16.4 服务端没有 Adventure API，需要它提供）；另外 1.8 协议本身不含"发光轮廓 / 队伍碰撞规则 / 独立副手槽位 / 玩家列表隐藏"，插件会自动跳过这些字段（不会报错，也不会踢客户端），详见 README 的「兼容性与优雅降级说明」。

安装步骤

把 PacketEvents 放入 plugins/ 目录；
把 StarMastNPCs-x.y.z.jar 放入 plugins/ 目录；
可选：如需占位符支持，一并放入 PlaceholderAPI；
重启服务端（首次安装请勿使用 /reload）；
控制台出现星桅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 段。

坐姿小贴士：坐姿座位高度已按客户端版本自动取值（1.20.4 及更早 ≈1.68，1.20.5+ ≈1.975，均经实测标定），从 1.8 到 26.3 一般无需调整；若确实"悬空"或"略微下沉"，把 npc.sitting-seat-offset 从 AUTO 改成具体数值按 0.05 步进微调即可（悬空调小、下沉调大）。

七、授权说明

本插件带有在线时间授权校验：

授权有效期至 2027-06-30 23:59；
启动时会联网校时（读取公共站点的标准时间，多源取中位数，防止单点篡改）；
超出有效期，或无法联网校时，插件会强制停止运行（停止前会正常保存全部 NPC 数据、移除已渲染的 NPC 并注销相关监听，不会留下脏数据）；
运行期会固定每 1 小时复查一次日期与时间，因此长期不重启的服务器也不会"跨过授权期继续跑"（复查间隔内置，不可配置）；
若你的服务器处于内网 / 受控网络，请为其放行插件固定使用的几个公共校时站点的出网访问（校时源内置，不支持替换）。

八、常见问题

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，收集的是匿名聚合的技术数据：服务端版本、插件版本、在线人数、Java 版本，以及运行平台（Folia / Spigot-Paper）、插件语言、NPC 数量区间。不含任何玩家信息、IP 或服务器地址。如需关闭，把 plugins/bStats/config.yml 里的 enabled 改成 false 即可（该开关对所有使用 bStats 的插件生效）。

九、作者与版权

作者：星桅工作室（StarMastStudio）
内测交流群：1093939989（QQ）

版权声明 未经授权，禁止搬运、使用、反编译此代码产品。本插件为授权产品，授权有效期至 2027-06-30 23:59。请勿将本插件二次分发、转售或用于未获授权的服务器。

感谢选择星桅NPC。使用中遇到问题，欢迎加内测交流群反馈。

【Foila支持】高性能NPC插件-StarMastNPCs

【Foila支持】高性能NPC插件-StarMastNPCs

基本信息

我的世界Java版本

平台

运行环境

创作团队

详情信息

【Foila支持】高性能NPC插件-StarMastNPCs 0.1.0

更新日志