NPCS
一款面向 Paper 服务器的轻量级 NPC 插件。NPCS 允许你创建和配置交互式 NPC,无需任何依赖即可使用 SQLite 持久化、点击动作以及内置的从 Citizens 和 FancyNpcs 导入 NPC 的迁移系统。
要求
- Paper 1.21.9 或更高版本
- Java 25+
NPCS 基于 Paper 在 1.21.9 中引入的 Mannequin API 构建。Mannequin 是一个稳定且由 Paper 官方提供的用于玩家外观 NPC 的 API,因此 NPCS 不依赖数据包黑客技术或假玩家技巧来渲染其 NPC。正因如此,预计 NPCS 将在新的 Paper 版本上持续正常工作,而无需为每个新版本进行更新,但正如往常一样,如果你要跳转到全新的 Minecraft 大版本,请查看发布页面。
NPCS 可独立运行。Citizens 和 FancyNpcs 是可选的,仅在你希望从其中之一迁移现有 NPC 时使用,请参阅下方的 迁移。
功能
- 基于 SQLite 的持久化:尽管
entity.isPersistent 为 false,NPC 仍能存活于重启和区块卸载之后
- 通过 Minecraft 玩家名称设置自定义皮肤(在线或离线,通过 Mojang 个人资料查询解析)
- 点击触发动作:以玩家或控制台身份运行命令,或发送聊天消息
- 支持 MiniMessage 标签、传统
&/§ 颜色代码以及在名称和消息中的 JSON 文本组件
- 针对每个 NPC 提供重力、不可移动性、无敌性和注视玩家的切换开关
- Folia 支持
- 从 Citizens 和 FancyNpcs 导入 NPC 的迁移系统
- bStats 指标统计
安装
- 从 发布页面 或 Modrinth 下载
NPCS-<version>.jar。
- 将其放入服务器目录下的
plugins/ 文件夹中。
- 重启服务器。
无需进一步配置。
命令
所有命令均以 /npcs 开头(别名 /npc)。
| 命令 |
描述 |
/npcs help |
显示帮助对话框 |
/npcs create <name> [entitytype] |
在你所在位置创建一个 NPC |
/npcs type <entitytype> |
更改选中 NPC 的生物类型 |
/npcs select [name] |
选择要编辑的 NPC,或清除你的选择 |
/npcs rename <newName> |
重命名选中的 NPC |
/npcs remove [name] |
移除一个 NPC |
/npcs skin <skin> |
设置选中 NPC 的皮肤(仅限 Mannequin 类型的 NPC) |
/npcs addcommand <action> <executor> <command> |
将命令附加到点击动作 |
/npcs removecommand [targetNpc] <commandId> |
移除已附加的命令 |
/npcs message <action> <msg> / /npcs sendmessage <action> <msg> |
将聊天消息附加到点击动作 |
/npcs removemessage [targetNpc] <messageId> |
移除已附加的消息 |
/npcs gravity |
切换选中 NPC 的重力状态 |
/npcs immovable |
切换选中 NPC 是否可被推动 |
/npcs invulnerable |
切换选中 NPC 的无敌状态 |
/npcs lookatme |
切换选中 NPC 是否转向面对附近的玩家 |
/npcs copy <newName> |
复制选中的 NPC |
/npcs teleport |
传送你自己到选中的 NPC 处 |
/npcs tphere |
将选中的 NPC 传送到你身边 |
/npcs near |
列出你位置附近的 NPC |
/npcs list |
列出所有 NPC |
/npcs migrate [migrator] |
从另一个插件迁移 NPC — 参见 迁移 |
/npcs reload |
重载插件 |
点击动作接受 LEFT_CLICK、RIGHT_CLICK 或 CLICK(任意点击),匹配时不区分大小写,并且接受 LEFT/RIGHT 作为两种特定点击触发器的简写。
迁移
NPCS 可以直接从 Citizens 或 FancyNpcs 导入 NPC,既可以从与 NPCS 一起安装的实时插件中导入,也可以直接从该插件的保存文件中导入(如果未安装插件)。
运行不带参数的 /npcs migrate 以查看可用的迁移器列表,然后再次运行并指定其中一个:
/npcs migrate citizens # 从正在运行的 Citizens 安装中导入
/npcs migrate citizens-file # 直接从 Citizens/saves.yml 导入
/npcs migrate fancynpcs # 从正在运行的 FancyNpcs 安装中导入
/npcs migrate fancynpcs-file # 直接从 FancyNpcs/npcs.yml 导入
迁移会将每个 NPC 的名称、位置、生物类型、皮肤和点击动作复制到 NPCS 自己的数据库中。从 Citizens 迁移意味着包含通过其 Command Trait 附加的命令。从 FancyNpcs 迁移则包括命令和聊天消息。对于没有对应 NPCS 等效项的动作类型(例如 FancyNpcs 的 wait 或 need_item 动作),将被跳过并在日志中记录为警告,而不是静默丢弃或猜测处理。
迁移基于可扩展的 Migrator 系统构建——每个迁移器都是一个实现单个 migrate() 方法的小型类,并且可以在运行时注册新的迁移器。如果你维护着另一个 NPC 插件(或希望从上述未列出的格式中进行迁移),你可以将自己的迁移器注册到 NPCS 的注册表中,而无需核心更新。
API
计划在未来的版本中为 NPCS 提供公共 API,以便其他插件能够以编程方式创建、查询和修改由 NPCS 管理的 NPC,包括注册自定义迁移器而无需使用反射。目前尚无时间表,请查看发布页面以获取更新。
指标统计
NPCS 通过 bStats 报告匿名使用统计数据:
bstats.org/plugin/bukkit/NPCS-Hihelloy/33242
可以通过 plugins/bStats/config.yml 全局禁用服务器上所有插件的此项功能。
权限
访问权限由顶层的 npcs.admin 或 npcs.use 控制,并为每个子命令提供单独的权限(npcs.command.<subcommand>,例如 npcs.command.create、npcs.command.migrate)以实现细粒度控制。
支持
发现 bug 或有功能请求?请在 GitHub 上提交 Issue。
NPCS
A lightweight NPC plugin for Paper servers. NPCS lets you create and configure interactive NPCs no dependencies required with SQLite persistence, click actions, and a builtin migration system for importing NPCs from Citizens and FancyNpcs.
Requirements
- Paper 1.21.9 or newer
- Java 25+
NPCS is built against Paper's Mannequin API, introduced in 1.21.9. Mannequin is a stable, first-party Paper API for player-look NPCs, so NPCS does not rely on packet hacks or fake-player tricks to render its NPCs. Because of this, NPCS is expected to keep working on newer Paper versions without needing an update for every release though as always, check the releases page if you're jumping to a major new Minecraft version.
NPCS works standalone. Citizens and FancyNpcs are optional and only used if you want to migrate existing NPCs from one of them see Migration below.
Features
- SQLite-backed persistence NPCs survive restarts and chunk unloads despite entity.isPersistent being false
- Custom skins by Minecraft player name (online or offline, resolved via Mojang profile lookup)
- Click-triggered actions: run commands as the player or console, or send chat messages
- Support for MiniMessage tags, legacy
&/§ color codes, and JSON text components in names and messages
- Gravity, immovability, invulnerability, and look-at-player toggles per NPC
- Folia support
- Migration system for importing NPCs from Citizens and FancyNpcs
- bStats metrics
Installation
- Download
NPCS-<version>.jar from the releases page or Modrinth.
- Drop it into your server's
plugins/ folder.
- Restart the server.
No further setup is required.
Commands
All commands are under /npcs (alias /npc).
| Command |
Description |
/npcs help |
Show the help dialog |
/npcs create <name> [entitytype] |
Create an NPC at your location |
/npcs type <entitytype> |
Change the entity type of the selected NPC |
/npcs select [name] |
Select an NPC to edit, or clear your selection |
/npcs rename <newName> |
Rename the selected NPC |
/npcs remove [name] |
Remove an NPC |
/npcs skin <skin> |
Set the skin of the selected NPC (Mannequin-type NPCs only) |
/npcs addcommand <action> <executor> <command> |
Attach a command to a click action |
/npcs removecommand [targetNpc] <commandId> |
Remove an attached command |
/npcs message <action> <msg> / /npcs sendmessage <action> <msg> |
Attach a chat message to a click action |
/npcs removemessage [targetNpc] <messageId> |
Remove an attached message |
/npcs gravity |
Toggle gravity on the selected NPC |
/npcs immovable |
Toggle whether the selected NPC can be pushed |
/npcs invulnerable |
Toggle invulnerability on the selected NPC |
/npcs lookatme |
Toggle whether the selected NPC turns to face nearby players |
/npcs copy <newName> |
Duplicate the selected NPC |
/npcs teleport |
Teleport yourself to the selected NPC |
/npcs tphere |
Teleport the selected NPC to you |
/npcs near |
List NPCs near your location |
/npcs list |
List all NPCs |
/npcs migrate [migrator] |
Migrate NPCs from another plugin — see Migration |
/npcs reload |
Reload the plugin |
Click actions accept LEFT_CLICK, RIGHT_CLICK, or CLICK (either click) matching is case-insensitive, and LEFT/RIGHT are accepted as shorthand for the two specific-click triggers.
Migration
NPCS can import NPCs directly from Citizens or FancyNpcs, either from the live plugin if it's installed alongside NPCS, or straight from that plugin's save file if it isn't.
Run /npcs migrate with no arguments to see a list of available migrators, then run it again with one:
/npcs migrate citizens # From a running Citizens installation
/npcs migrate citizens-file # Directly from Citizens/saves.yml
/npcs migrate fancynpcs # From a running FancyNpcs installation
/npcs migrate fancynpcs-file # Directly from FancyNpcs/npcs.yml
Migration copies over each NPC's name, location, entity type, skin, and click actions into NPCS's own database. From Citizens, this means commands attached via its Command Trait. From FancyNpcs, this includes both commands and chat messages. Action types with no NPCS equivalent (for example FancyNpcs's wait or need_item actions) are skipped and logged as a warning rather than silently dropped or guessed at.
Migration is built on an extensible Migrator system — every migrator is a small class that implements a single migrate() method, and new ones can be registered at runtime. If you maintain another NPC plugin (or want to migrate from a format not listed above), you can register your own migrator against NPCS's registry without needing a core update.
API
A public API for NPCS is planned for a future release, so other plugins will be able to create, query, and modify NPCS-managed NPCs programmatically including registering custom migrators without reflection. There's no timeline yet check the releases page for updates.
Metrics
NPCS reports anonymous usage statistics via bStats:
bstats.org/plugin/bukkit/NPCS-Hihelloy/33242
This can be disabled globally for all plugins on your server via plugins/bStats/config.yml.
Permissions
Access is gated by npcs.admin or npcs.use at the top level, with a permission per subcommand (npcs.command.<subcommand>, e.g. npcs.command.create, npcs.command.migrate) for granular control.
Support
Found a bug or have a feature request? Open an issue on GitHub.
评论 0
登录后参与评分
还没有评论,来抢沙发吧