NPC 配置 npcs.yml

npcs.yml 定义了副本中的 NPC 角色。NPC 可以与玩家对话、响应点击事件、执行脚本。

使用内置实体实现，无需安装任何外部 NPC 插件。

完整配置

npcs:
  引导者:
    name: "&6&l副本引导者"       # 显示名称（支持颜色代码）
    type: PLAYER                 # NPC 类型
    location: "0,64,0"           # 相对副本原点的坐标 x,y,z
    skin: "Notch"                # 皮肤玩家名（仅 PLAYER 类型有效）
    look_at_player: true         # 是否朝向附近玩家

    dialogue:                    # 对话内容列表
      - "&e[引导者] &7欢迎来到试炼副本！"
      - "&e[引导者] &7前方有强大的敌人，请做好准备。"
    dialogue_delay: 40           # 对话行间延迟（tick）

    click_script: |              # 点击时执行的脚本
      action.sound('@trigger', 'ENTITY_VILLAGER_YES', 1.0, 1.0)
      action.message('@trigger', '&e引导者向你点了点头。')

    once: false                  # 是否只能交互一次

NPC 类型

类型	说明
PLAYER	玩家外形（支持皮肤设置）
VILLAGER	村民
ZOMBIE	僵尸
SKELETON	骷髅
WITCH	女巫
CREEPER	苦力怕
ENDERMAN	末影人
BLAZE	烈焰人
PILLAGER	掠夺者
WANDERING_TRADER	流浪商人
IRON_GOLEM	铁傀儡

提示

PLAYER 类型在内置实现中会使用村民实体代替（原生 Bukkit 无法创建假玩家实体）。如需真正的玩家外形 NPC，可考虑后续扩展。

字段说明

字段	类型	必填	默认值	说明
name	String	否	NPC key	头顶显示名称，支持 & 颜色代码
type	String	否	PLAYER	NPC 实体类型
location	String	否	0,64,0	坐标 x,y,z（或 x,y,z,yaw,pitch），相对副本世界原点
skin	String	否	-	皮肤玩家名，仅 PLAYER 类型
look_at_player	Boolean	否	true	是否自动朝向附近玩家
dialogue	List	否	[]	对话文本列表
dialogue_delay	Long	否	30	对话行间延迟（tick，20tick = 1秒）
click_script	String	否	-	点击时执行的 JavaScript 脚本
once	Boolean	否	false	是否只能交互一次
dialogue_choices	Section	否	-	聊天栏可点击的对话选项
shop	Section	否	-	商店配置（购买 / 出售）
quests	Section	否	-	NPC 任务配置
dialogue_stages	Section	否	-	多段对话阶段（按顺序推进）

对话选项 dialogue_choices

在聊天栏显示可点击的对话选项，玩家点击后执行对应脚本。每个子项的键为选项 ID。

字段	类型	必填	默认值	说明
text	String	否	""	选项显示文本，支持 & 颜色代码
script	String	否	-	点击该选项执行的脚本
condition	String	否	""	显示条件（空=无条件显示）

npcs:
  长老:
    name: "&6村庄长老"
    type: VILLAGER
    location: "0,64,0"
    dialogue_choices:
      ask_quest:
        text: "&a我想接受任务"
        script: |
          action.message('@trigger', '&7长老：很好，去消灭森林里的怪物吧。')
        condition: ""
      ask_shop:
        text: "&e我想看看商品"
        script: |
          action.open_chest_ui('@trigger', '长老货柜')

商店 shop

商店分为 购买 / buy（玩家花费货币或物品换取物品）和 出售 / sell（玩家用物品换取奖励）两个子段。

购买 buy

字段	类型	必填	默认值	说明
name	String	否	子项 key	商品名称
icon	String	否	STONE	图标材质名
price_type	String	否	money	价格类型
price	Int	否	0	价格数值
price_item	String	否	""	价格物品（当用物品支付时）
give_item	String	否	""	购买后给予的物品
give_script	String	否	-	购买后执行的脚本

出售 sell

字段	类型	必填	默认值	说明
name	String	否	子项 key	商品名称
icon	String	否	STONE	图标材质名
require_item	String	否	""	出售所需物品
reward_type	String	否	money	奖励类型
reward	Int	否	0	奖励数值
reward_script	String	否	-	出售后执行的脚本

npcs:
  商人:
    name: "&d神秘商人"
    type: VILLAGER
    location: "5,64,5"
    shop:
      buy:
        apple:
          name: "&c回复苹果"
          icon: APPLE
          price_type: money
          price: 100
          give_item: "GOLDEN_APPLE"
      sell:
        old_sword:
          name: "&7回收旧剑"
          icon: IRON_SWORD
          require_item: "IRON_SWORD"
          reward_type: money
          reward: 50

任务 quests

NPC 可发布任务，玩家点击接受、满足条件后提交。每个子项的键为任务 ID（也可用 id 字段覆盖）。

字段	类型	必填	默认值	说明
id	String	否	子项 key	任务唯一 ID
name	String	否	子项 key	任务名称
description	String	否	""	任务描述
accept_text	String	否	&a[接受]	接受按钮文本
accept_script	String	否	-	接受时执行的脚本
submit_text	String	否	&e[提交]	提交按钮文本
submit_condition	String	否	""	提交条件（满足才可提交）
submit_script	String	否	-	提交时执行的脚本

npcs:
  任务发布者:
    name: "&b任务官"
    type: VILLAGER
    location: "0,64,0"
    quests:
      kill_zombies:
        name: "&a清剿僵尸"
        description: "击杀 10 只僵尸"
        accept_text: "&a[接受任务]"
        accept_script: |
          action.message('@trigger', '&7任务已接受！')
        submit_text: "&e[提交任务]"
        submit_condition: ""
        submit_script: |
          action.message('@trigger', '&a任务完成，奖励已发放！')

对话阶段 dialogue_stages

多段对话按顺序推进，每次点击播放当前阶段的对话并前进到下一阶段，支持条件门控和循环。每个子项的键为阶段 ID。

字段	类型	必填	默认值	说明
lines	List	否	[]	该阶段的对话行
condition	String	否	""	推进条件（空=无条件推进）
script	String	否	-	播放该阶段后执行的脚本
loop	Boolean	否	false	是否为循环阶段（所有阶段播完后回退到此阶段）

npcs:
  剧情NPC:
    name: "&6神秘老人"
    type: VILLAGER
    location: "0,64,0"
    dialogue_stages:
      stage1:
        lines:
          - "&e[老人] &7年轻人，你终于来了……"
        condition: ""
      stage2:
        lines:
          - "&e[老人] &7前方的封印需要你来解开。"
        script: |
          action.message('@trigger', '&a你获得了封印之钥。')
      stage3:
        lines:
          - "&e[老人] &7祝你好运。"
        loop: true

提示

所有子段（dialogue_choices / shop / quests / dialogue_stages）的中文键与英文键均可使用，例如 对话选项 / dialogue_choices、商店 / shop、任务 / quests、对话阶段 / dialogue_stages。

脚本中的选择器

click_script 中可使用以下选择器：

选择器	说明
@trigger	点击 NPC 的玩家
@all	副本内所有玩家
@party	队伍内所有玩家

示例：带路 NPC

npcs:
  带路人:
    name: "&a&l带路人"
    type: VILLAGER
    location: "0,64,0"
    look_at_player: true
    dialogue:
      - "&e[带路人] &7跟我来，我带你去下一个区域。"
    dialogue_delay: 30
    click_script: |
      action.npc_talk('@trigger', '带路人')
      action.delay(80)
      action.npc_walk('带路人', '20,64,30', 0.3)

脚本动作

NPC 相关的脚本动作详见 NPC 脚本动作。