ZNPCsPlus 2.0 NPC 插件

[HEADING=1]✪ 快速上手[/HEADING]
[TABLE]
[TR]
[TH][LEFT]操作[/LEFT][/TH]

[TH][LEFT]指令/说明[/LEFT][/TH]
[/TR]
[TR]
[TD][LEFT]安装插件[/LEFT][/TD]

[TD][LEFT]下载插件 → 放入 plugins 文件夹 → 重启服务器（/reload 无效）[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]查看版本[/LEFT][/TD]

[TD][LEFT]/npc version[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]重载配置[/LEFT][/TD]

[TD][LEFT]/npc reloadconfig[/LEFT][/TD]
[/TR]
[/TABLE]
[HEADING=1]✪ 指令与权限[/HEADING]
[TABLE]
[TR]
[TH][LEFT]功能[/LEFT][/TH]

[TH][LEFT]指令格式[/LEFT][/TH]

[TH][LEFT]示例[/LEFT][/TH]
[/TR]
[TR]
[TD][LEFT]创建 NPC[/LEFT][/TD]

[TD][LEFT]/npc create <ID> <类型>[/LEFT][/TD]

[TD][LEFT]/npc create shop villager[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]删除 NPC[/LEFT][/TD]

[TD][LEFT]/npc delete <ID>[/LEFT][/TD]

[TD][LEFT]/npc delete shop[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]修改 ID[/LEFT][/TD]

[TD][LEFT]/npc changeid <旧ID> <新ID>[/LEFT][/TD]

[TD][LEFT]/npc changeid shop market[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]切换显示[/LEFT][/TD]

[TD][LEFT]/npc toggle <ID>[/LEFT][/TD]

[TD][LEFT]/npc toggle shop[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]列出所有 NPC[/LEFT][/TD]

[TD][LEFT]/npc list[/LEFT][/TD]

[TD][LEFT]-[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]修改类型[/LEFT][/TD]

[TD][LEFT]/npc type <ID> <新类型>[/LEFT][/TD]

[TD][LEFT]/npc type shop zombie[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]克隆 NPC[/LEFT][/TD]

[TD][LEFT]/npc clone <ID> <新ID>[/LEFT][/TD]

[TD][LEFT]/npc clone shop shop2[/LEFT][/TD]
[/TR]
[/TABLE]
[TABLE]
[TR]
[TH][LEFT]功能[/LEFT][/TH]

[TH][LEFT]指令格式[/LEFT][/TH]

[TH][LEFT]示例[/LEFT][/TH]
[/TR]
[TR]
[TD][LEFT]设置坐标[/LEFT][/TD]

[TD][LEFT]/npc setlocation <ID> <x> <y> <z>[/LEFT][/TD]

[TD][LEFT]/npc setlocation shop 100 64 200[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]设置朝向[/LEFT][/TD]

[TD][LEFT]/npc setrotation <ID> <yaw> <pitch>[/LEFT][/TD]

[TD][LEFT]/npc setrotation shop 180 0[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]传送到 NPC[/LEFT][/TD]

[TD][LEFT]/npc teleport <ID>[/LEFT][/TD]

[TD][LEFT]/npc teleport shop[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]移动 NPC 到玩家[/LEFT][/TD]

[TD][LEFT]/npc move <ID>[/LEFT][/TD]

[TD][LEFT]/npc move shop[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]居中 NPC[/LEFT][/TD]

[TD][LEFT]/npc center <ID>[/LEFT][/TD]

[TD][LEFT]/npc center shop[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]看向玩家[/LEFT][/TD]

[TD][LEFT]/npc lookatme <ID>[/LEFT][/TD]

[TD][LEFT]/npc lookatme shop[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]查找附近 NPC[/LEFT][/TD]

[TD][LEFT]/npc near <距离>[/LEFT][/TD]

[TD][LEFT]/npc near 10[/LEFT][/TD]
[/TR]
[/TABLE]
[TABLE]
[TR]
[TD][LEFT]静态皮肤[/LEFT][/TD]

[TD][LEFT]/npc skin <ID> static <玩家名>[/LEFT][/TD]

[TD][LEFT]/npc skin shop static Notch[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]动态皮肤[/LEFT][/TD]

[TD][LEFT]/npc skin <ID> dynamic <玩家名>[/LEFT][/TD]

[TD][LEFT]/npc skin shop dynamic %player_name%[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]镜像皮肤[/LEFT][/TD]

[TD][LEFT]/npc skin <ID> mirror[/LEFT][/TD]

[TD][LEFT]/npc skin shop mirror[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]URL 皮肤[/LEFT][/TD]

[TD][LEFT]/npc skin <ID> url <classic/slim> <URL>[/LEFT][/TD]

[TD][LEFT]/npc skin shop url classic http://...[/LEFT][/TD]
[/TR]
[/TABLE]
[TABLE]
[TR]
[TD][LEFT]添加文字[/LEFT][/TD]

[TD][LEFT]/npc holo add <ID> <文字>[/LEFT][/TD]

[TD][LEFT]/npc holo add shop &6欢迎！[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]插入文字[/LEFT][/TD]

[TD][LEFT]/npc holo insert <ID> <行号> <文字>[/LEFT][/TD]

[TD][LEFT]/npc holo insert shop 1 &e你好[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]设置文字[/LEFT][/TD]

[TD][LEFT]/npc holo set <ID> <行号> <文字>[/LEFT][/TD]

[TD][LEFT]/npc holo set shop 1 &a新消息[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]删除文字[/LEFT][/TD]

[TD][LEFT]/npc holo delete <ID> <行号>[/LEFT][/TD]

[TD][LEFT]/npc holo delete shop 1[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]添加物品[/LEFT][/TD]

[TD][LEFT]/npc holo additem <ID>（手持物品）[/LEFT][/TD]

[TD][LEFT]/npc holo additem shop[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]设置偏移[/LEFT][/TD]

[TD][LEFT]/npc holo offset <ID> <数值>[/LEFT][/TD]

[TD][LEFT]/npc holo offset shop 1.5[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]刷新延迟[/LEFT][/TD]

[TD][LEFT]/npc holo refreshdelay <ID> <秒>[/LEFT][/TD]

[TD][LEFT]/npc holo refreshdelay shop 5[/LEFT][/TD]
[/TR]
[/TABLE]
[TABLE]
[TR]
[TD][LEFT]装备物品[/LEFT][/TD]

[TD][LEFT]/npc property set <ID> <部位>（手持物品）[/LEFT][/TD]

[TD][LEFT]/npc property set shop helmet[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]是否婴儿[/LEFT][/TD]

[TD][LEFT]/npc property set <ID> baby <true/false>[/LEFT][/TD]

[TD][LEFT]/npc property set shop baby true[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]是否坐下[/LEFT][/TD]

[TD][LEFT]/npc property set <ID> sitting <true/false>[/LEFT][/TD]

[TD][LEFT]/npc property set shop sitting true[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]是否发光[/LEFT][/TD]

[TD][LEFT]/npc property set <ID> glow [颜色][/LEFT][/TD]

[TD][LEFT]/npc property set shop glow RED[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]是否隐形[/LEFT][/TD]

[TD][LEFT]/npc property set <ID> invisible <true/false>[/LEFT][/TD]

[TD][LEFT]/npc property set shop invisible true[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]是否看向玩家[/LEFT][/TD]

[TD][LEFT]/npc property set <ID> look <类型>[/LEFT][/TD]

[TD][LEFT]/npc property set shop look CLOSEST_PLAYER[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]可视距离[/LEFT][/TD]

[TD][LEFT]/npc property set <ID> view_distance <数值>[/LEFT][/TD]

[TD][LEFT]/npc property set shop view_distance 50[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]权限可视[/LEFT][/TD]

[TD][LEFT]/npc property set <ID> permission_required <true/false>[/LEFT][/TD]

[TD][LEFT]/npc property set shop permission_required true[/LEFT][/TD]
[/TR]
[/TABLE]
[TABLE]
[TR]
[TD][LEFT]添加动作[/LEFT][/TD]

[TD][LEFT]/npc action add <动作类型> <ID> <点击类型> <冷却> <延迟> <值>[/LEFT][/TD]

[TD][LEFT]/npc action add message shop RIGHT_CLICK 5 0 &a你好！[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]列出动作[/LEFT][/TD]

[TD][LEFT]/npc action list <ID>[/LEFT][/TD]

[TD][LEFT]/npc action list shop[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]删除动作[/LEFT][/TD]

[TD][LEFT]/npc action delete <ID> <索引>[/LEFT][/TD]

[TD][LEFT]/npc action delete shop 1[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]清空动作[/LEFT][/TD]

[TD][LEFT]/npc action clear <ID>[/LEFT][/TD]

[TD][LEFT]/npc action clear shop[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]编辑动作[/LEFT][/TD]

[TD][LEFT]/npc action edit <ID> <索引> ...[/LEFT][/TD]

[TD][LEFT]/npc action edit shop 1 message LEFT_CLICK 0 0 &c再见！[/LEFT][/TD]
[/TR]
[/TABLE]
[TABLE]
[TR]
[TD][LEFT]保存所有 NPC[/LEFT][/TD]

[TD][LEFT]/npc storage save[/LEFT][/TD]

[TD][LEFT]-[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]重载 NPC 数据[/LEFT][/TD]

[TD][LEFT]/npc storage reload[/LEFT][/TD]

[TD][LEFT]-[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]导入 NPC 数据[/LEFT][/TD]

[TD][LEFT]/npc storage import <类型>[/LEFT][/TD]

[TD][LEFT]/npc storage import citizens[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]迁移存储格式[/LEFT][/TD]

[TD][LEFT]/npc storage migrate <from> <to> [force][/LEFT][/TD]

[TD][LEFT]/npc storage migrate YAML SQLITE[/LEFT][/TD]
[/TR]
[/TABLE]
[HEADING=1]权限系统[/HEADING]

[TABLE]
[TR]
[TH][LEFT]权限节点[/LEFT][/TH]

[TH][LEFT]说明[/LEFT][/TH]
[/TR]
[TR]
[TD][LEFT]znpcsplus.npc.<ID>[/LEFT][/TD]

[TD][LEFT]查看指定 ID 的 NPC（需设置 permission_required 为 true）[/LEFT][/TD]
[/TR]
[TR]
[TD][LEFT]znpcsplus.admin[/LEFT][/TD]

[TD][LEFT]拥有所有 NPC 管理权限（默认 OP）[/LEFT][/TD]
[/TR]
[/TABLE]
[HEADING=1]✪ API[/HEADING]
一、在项目里引入 API
[CODE]<repository>

<id>pyr-snapshots</id>

<url>https://repo.pyr.lol/snapshots</url>

</repository>



<dependency>

<groupId>lol.pyr</groupId>

<artifactId>znpcsplus-api</artifactId>

<version>填最新版本</version>

<scope>provided</scope>

</dependency>[/CODE]

[CODE]maven { url 'https://repo.pyr.lol/snapshots' }

compileOnly 'lol.pyr:znpcsplus-api:填最新版本'[/CODE]

（版本号去 Discord 或 GitHub 看徽章即可）
[HR][/HR]
二、5 步搞定一个 NPC
[LIST=1]
[*]拿 API 实例
[CODE]NpcApi api = NpcApiProvider.get();[/CODE]
[*]选类型
[CODE]NpcType type = api.getNpcTypeRegistry().getByName("player");[/CODE]
[*]创建
[LIST=1]
[*][CODE]NpcEntry npc = api.getNpcRegistry().create(
"npc1",
Bukkit.getWorlds().get(0),
type,
new NpcLocation(0, 100, 0, 0, 0)
);[/CODE]
[/LIST]
[*]一键启用
[CODE]npc.enableEverything(); // 处理、保存、允许指令修改全打开[/CODE]
[*]删 NPC
[CODE]api.getNpcRegistry().delete("npc1");[/CODE]
[/LIST]
[HR][/HR]
三、常用小动作换皮肤（仅玩家型 NPC 有效）
[CODE]EntityProperty<SkinDescriptor> skin = api.getPropertyRegistry().getByName("skin", SkinDescriptor.class);

npc.getNpc().setProperty(skin, api.getSkinDescriptorFactory().createStaticDescriptor("Steve"));[/CODE]


发送消息（左键点击）
[CODE]InteractionAction act = api.getActionFactory()

.createMessageAction("你好！", InteractionType.LEFT_CLICK, 5, 0);

npc.getNpc().addAction(act);[/CODE]


上下颠倒
[CODE]EntityProperty<Boolean> dinner = api.getPropertyRegistry().getByName("dinnerbone", Boolean.class);

npc.getNpc().setProperty(dinner, true);[/CODE]

[HR][/HR]
四、保存 / 读取
[CODE]// 存

NpcSerializer<YamlConfiguration> ser = api.getNpcSerializerRegistry().getSerializer(YamlConfiguration.class);

YamlConfiguration yaml = ser.serialize(npc);



// 读

NpcEntry loaded = ser.deserialize(yaml);

api.getNpcRegistry().register(loaded);[/CODE]


[HR][/HR]
五、排坑提示
[LIST]
[*]找不到类型 → 服务器版本不支持或写错名字，大小写不敏感。
[*]皮肤不显示 → 确认 NPC 类型是 player，且皮肤源合法。
[*]动作无响应 → 检查 processed 是否设为 true。
[/LIST]