NPC 类动作

spawn_npc

在副本中生成 NPC。可以引用 npcs.yml 配置，也可以动态创建。

action.spawn_npc(配置ID)
action.spawn_npc(配置ID, 坐标覆盖)
action.spawn_npc(名称, 类型, 坐标)
action.spawn_npc(名称, 类型, 坐标, 皮肤)

参数	类型	说明
配置ID	String	`npcs.yml` 中定义的 NPC ID
坐标覆盖	String	可选，`x,y,z` 或 `x,y,z,yaw,pitch`，覆盖配置中的固定坐标
名称	String	动态创建时的显示名称
类型	String	实体类型（PLAYER / VILLAGER / ZOMBIE 等）
坐标	String	`x,y,z`
皮肤	String	可选，皮肤玩家名（仅 PLAYER 类型）

action.spawn_npc('guide')
action.spawn_npc('商人', '24.5,65,12.5')         // 引用配置但覆盖坐标
action.spawn_npc('临时NPC', 'VILLAGER', '10,64,10')

remove_npc

从副本中移除指定 NPC。

action.remove_npc(配置ID)

action.remove_npc('guide')

npc_talk

让 NPC 向玩家发送对话消息。

action.npc_talk(选择器, 配置ID)
action.npc_talk(选择器, 配置ID, 消息1, 消息2, ...)

参数	类型	说明
选择器	String	目标玩家
配置ID	String	NPC 配置 ID
消息	String	可选，自定义消息（不传则使用配置中的 dialogue）

action.npc_talk('@trigger', 'guide')
action.npc_talk('@all', 'guide', '&e快跑！', '&e敌人来了！')

npc_move

将 NPC 瞬间传送到目标位置。

action.npc_move(配置ID, 坐标)

参数	类型	说明
配置ID	String	NPC 配置 ID
坐标	String	`x,y,z` 或 `x,y,z,yaw,pitch`

action.npc_move('guide', '20,64,30,90,0')

npc_walk

让 NPC 沿路径行走到目标位置（寻路）。到达后自动停止。

action.npc_walk(配置ID, 坐标)
action.npc_walk(配置ID, 坐标, 速度)

参数	类型	说明
配置ID	String	NPC 配置 ID
坐标	String	目标位置 `x,y,z`
速度	Number	移动速度，默认 0.25

action.npc_walk('guide', '20,64,30')
action.npc_walk('guide', '20,64,30', 0.4)

npc_follow

让 NPC 持续跟随指定玩家。距离 < 3 格时停下，> 8 格时传送到附近。

action.npc_follow(配置ID, 选择器)
action.npc_follow(配置ID, 选择器, 速度)

参数	类型	说明
配置ID	String	NPC 配置 ID
选择器	String	跟随目标（`@trigger`、`@nearest` 等）
速度	Number	移动速度，默认 0.25

action.npc_follow('guide', '@trigger')
action.npc_follow('guide', '@trigger', 0.4)

npc_stop

停止 NPC 当前的行走或跟随行为。

action.npc_stop(配置ID)

action.npc_stop('guide')

npc_equip

给 NPC 设置装备。

action.npc_equip(配置ID, 槽位, 物品)

参数	类型	说明
配置ID	String	NPC 配置 ID
槽位	String	`HAND` / `OFF_HAND` / `HEAD` / `CHEST` / `LEGS` / `FEET`
物品	String	Bukkit Material 名称

action.npc_equip('guard', 'HAND', 'DIAMOND_SWORD')
action.npc_equip('guard', 'HEAD', 'IRON_HELMET')

npc_name

动态修改 NPC 的显示名称。

action.npc_name(配置ID, 新名称)

action.npc_name('guide', '&c&l愤怒的引导者')

npc_skin

修改 NPC 的皮肤（仅 PLAYER 类型）。

action.npc_skin(配置ID, 皮肤名)

action.npc_skin('guide', 'Herobrine')

npc_look

控制 NPC 是否自动朝向附近玩家。

action.npc_look(配置ID, 是否启用)

参数	类型	说明
配置ID	String	NPC 配置 ID
是否启用	String	`true` / `false`

action.npc_look('guide', 'true')

npc_shop

打开 NPC 的商店界面。NPC 需要在 npcs.yml 中配置 shop 节。

action.npc_shop(选择器, 配置ID)
action.npc_shop(选择器, 配置ID, 模式)

参数	类型	说明
选择器	String	目标玩家
配置ID	String	NPC 配置 ID
模式	String	`buy`（购买）/ `sell`（出售），默认 `buy`

action.npc_shop('@trigger', 'merchant')
action.npc_shop('@trigger', 'merchant', 'sell')

npc_choice

向玩家发送 NPC 对话选项（可点击的选择按钮）。NPC 需要在 npcs.yml 中配置 choices 节。

action.npc_choice(选择器, 配置ID)

参数	类型	说明
选择器	String	目标玩家
配置ID	String	NPC 配置 ID

action.npc_choice('@trigger', 'guide')

npc_quest

显示 NPC 的任务列表界面。NPC 需要在 npcs.yml 中配置 quests 节。

action.npc_quest(选择器, 配置ID)

参数	类型	说明
选择器	String	目标玩家
配置ID	String	NPC 配置 ID

action.npc_quest('@trigger', 'quest_giver')

track_task

注册一个局内任务追踪，以 BossBar 形式显示进度。

action.track_task(任务ID, 变量名, 目标数, 显示模板, 类型)
action.track_task(任务ID, 变量名, 目标数, 显示模板, 类型, 怪物过滤)

参数	类型	说明
任务ID	String	自定义标识符
变量名	String	绑定的脚本变量名
目标数	Int	完成所需数量
显示模板	String	BossBar 文字，支持 `{current}` 和 `{target}` 占位符
类型	String	`kill`（任意击杀）/ `kill:怪物ID`（特定怪物）/ `custom`（手动更新）
怪物过滤	String	可选，指定 MythicMobs 怪物 ID（仅 `kill` 类型有效）

action.track_task('kill_zombies', 'zombie_kills', 10, '&d击杀僵尸: {current}/{target}', 'kill', 'Zombie_Warrior')
action.track_task('collect_keys', 'keys', 3, '&e收集钥匙: {current}/{target}', 'custom')

complete_task

完成一个追踪任务，移除对应的 BossBar 显示。

action.complete_task(任务ID)

参数	类型	说明
任务ID	String	`track_task` 中注册的任务 ID

action.complete_task('kill_zombies')