FancyNpcs – Minecraft Java Edition 1.19.4–1.21.x

在 Minecraft 服务器上创建可交互的非玩家角色（NPC）通常伴随着巨大的硬件开销。过时的解决方案会将 NPC 注册为完整的服务器实体（Entity），迫使核心处理它们的人工智能、物理碰撞、寻路和区块加载。随着角色数量的增加，这会导致 TPS（Ticks Per Second，每秒刻数）指标的严重下降。FancyNpcs 插件提供了一种基于数据包渲染虚拟角色的替代方法，可以在不影响服务器线程性能的情况下维持数百个可交互的形象。

数据包架构与 Folia 兼容性

FancyNpcs 的主要技术特点在于，它所创建的角色仅存在于插件的内存中以及已连接客户端一侧。服务器不会将它们添加到世界数据库中，也不会在通用的实体更新循环中处理它们。

当玩家接近指定坐标时，插件会拦截网络流量，并向客户端发送 ClientboundAddPlayerPacket 数据包（用于人形模型）或 ClientboundAddEntityPacket（用于其他生物）。后续的行为、装备和显示状态则通过 ClientboundSetEntityDataPacket（元数据）和 ClientboundSetEquipmentPacket（装备）数据包进行更新。对服务器而言，这些角色并不存在——它们是面向终端用户的"虚拟投影"。

这种方式使 FancyNpcs 成为基于 Folia 的多线程服务器的理想选择。由于 Folia 将世界划分为各自在独立线程中运行的不同区域，传统的 NPC 插件常常因尝试在不同区域的线程之间进行交互而引发死锁和严重错误。FancyNpcs 以异步方式处理数据，并直接向玩家发送数据包，从而完全避免了与 Folia 任务调度器的冲突。

外观自定义功能

该插件支持广泛的实体类型和视觉效果。玩家可以将 NPC 创建为任意原版生物（Player、Cow、Zombie、Skeleton、Villager、Pig 等）的形态，并精细地调整其外观。

皮肤管理（用于人形模型）

对于 player 类型的角色，提供了多种纹理加载来源：

• @mirror： NPC 的皮肤会动态复制此刻正在注视它的那名玩家的皮肤。

• 正版账户的名称或 UUID： 插件会自动向 Mojang 会话服务器发送请求，以加载相应的纹理。

• 指向网络资源的直接链接（URL）： 能够从 Web 服务器加载任意第三方的 .png 文件。

• 本地文件： 预先放置在 /plugins/FancyNpcs/skins/ 文件夹中的图像。

• 标志 --slim： 为通过链接加载的皮肤启用纤细手臂模型（Alex 风格）。

视觉效果与属性

• 发光（Glowing）： 在角色周围添加彩色轮廓。颜色与原版的队伍颜色（Team Colors）相关联。

• 装备（Equipment）： 可以为角色的左手或右手赋予任意物品，也可以为其穿戴头盔、胸甲、护腿和靴子。

• 姿势（Poses）： 支持特定的显示状态，例如坐着、躺着（模拟在床上睡觉）、游泳和爬行。

• 尺寸（Scale）： 在新版插件中实现了对实体缩放（更改模型物理尺寸）的支持。

命令系统与语法

角色的管理完全通过游戏内聊天框或服务器控制台中的命令来完成。下表包含了基本语法的说明：

对于插件的全局管理，需使用平台命令：

• /fancynpcs reload —— 重新加载系统配置。

• /fancynpcs save —— 强制将所有 NPC 的当前状态写入磁盘上的数据库文件。

交互式动作系统（Actions）

FancyNpcs 包含一个内置的脚本式动作机制，当玩家与角色交互时即会触发。动作可以针对不同的点击类型进行配置（LEFT_CLICK、RIGHT_CLICK、ANY_CLICK）。

该插件提供以下可执行的动作类型：

• message： 向玩家发送一条消息。支持 MiniMessage（Hex 颜色）和 PlaceholdersAPI 变量。

• player_command： 以玩家的身份执行一条命令。

• player_command_as_op： 以玩家的身份执行命令，并临时授予其管理员（OP）权限（用于激活普通玩家无法使用的命令）。

• console_command： 由服务器控制台执行一条命令。变量 {player} 会自动替换为玩家的名称。

• send_to_server： 将玩家即时转移到 BungeeCord 或 Velocity 网络中的另一台服务器。

• wait： 在动作之间创建一个暂停（以服务器刻为单位的延迟）。

• block_until_done： 在当前动作脚本完成之前，阻止对 NPC 的重复点击。

• execute_random_action： 从列表中以下动作里随机选取一个。

为名为 Bob 的 NPC 创建复杂交互式脚本的示例：

1. 添加一条欢迎消息：
   /npc action Bob RIGHT_CLICK add message <yellow>欢迎来到我们的服务器，%player_name%！</yellow>

2. 添加 40 刻（2 秒）的暂停：
   /npc action Bob RIGHT_CLICK add wait 40

3. 通过控制台将玩家传送到出生点：
   /npc action Bob RIGHT_CLICK add console_command teleport {player} 0 100 0

得益于可以添加多个连续步骤并通过 add_before、add_after 以及 move_up/move_down 来调整队列，管理员无需安装诸如 Denizen 或 MyCommand 之类的额外插件，即可构建完整的对话树或在大厅服务器之间切换的复杂机制。

配置文件结构

所有数据都存储在 plugins/FancyNpcs/ 目录中。插件的运行基于两个文件：

1. config.yml

此文件定义了插件的全局行为，并包含以下设置：

• turn_to_player_distance（默认值 5）：角色将头转向玩家所在的半径范围（以方块为单位）。降低此参数可优化在繁忙区域中网络数据包的传输。

• visibility_distance（默认值 20）：向客户端发送 NPC 出现数据包的距离（以方块为单位）。减小该值有助于将角色隐藏在墙壁或渲染雾之后，以节省玩家的 FPS。

• enable_autosave： 自动定期将更改写入磁盘。

2. npcs.yml

插件在此文件中存储已创建 NPC 的数据库。每个角色都由一个独立的数据块来描述：

YAML

结论

FancyNpcs 插件是在 Minecraft Java Edition 服务器上创建装饰性和交互式角色的一种现代且高性能的解决方案。它消除了旧工具的主要问题——服务器为维护实体而消耗的 CPU 时间。

该插件的主要局限在于完全缺乏人工智能。由于这些角色是客户端一侧的虚拟投影，它们无法在世界中自行移动、与方块交互或攻击其他生物。

与支持复杂移动机制（路径点导航）并能与战斗系统（Sentinel 模组）集成的经典插件 Citizens 相比，FancyNpcs 在人工智能的灵活性上有所逊色。然而，Citizens 会对服务器主线程造成巨大的负载，几乎无法在 Folia 上使用。FancyNpcs 为大厅服务器、Velocity 中枢以及大型 SMP 项目提供了理想的替代方案，在这些场景中，对角色的要求仅仅是静态的存在、良好的外观以及点击时快速执行命令。