创建 NPC
将定义保存在 plugins/EliteMobs/npcs/，使用包含 .yml 的唯一文件名。保存后执行 /em reload，再放置新定义的 NPC。具有 elitemobs.place.npc 权限的玩家可在所需位置和朝向执行 /em place npc <npcfilename.yml>。一个文件支持多处放置。
复用另一个 NPC 文件
一个 NPC 文件可以通过 extends 以另一个 NPC 文件为基础，然后只修改不同的部分：
extends: my_base_npc.yml
name: "&aSecond Guard"
spawnLocations:
- my_world,20,64,20,90,0
该文件会继承基础文件中的所有值，并覆盖它自己设置的键。嵌套的配置节（例如 patrol）会逐键合并；列表（例如 dialog）则会整体替换基础文件中的列表。引用基础文件时只写文件名，不要带文件夹路径。它必须是 npcs 中（包括其子文件夹）的另一个文件，并且它本身也可以再继承其他基础文件。
isEnabled、spawnLocation 和 spawnLocations 永远不会被继承，因此每个文件都保留自己的放置位置。设置为 isEnabled: false 的基础文件可以当作模板使用：继承它的文件仍会正常加载。EliteMobs 不会向使用了 extends 的文件写入默认值。如果基础文件缺失、extends 中写了路径，或 extends 引用形成了循环，该文件会被禁用，并在控制台给出警告。巡逻编辑器在把某个放置位置从含有多个放置位置的文件中拆分出来时，就会使用 extends。
配置设置
isEnabled
在读取配置时启用此定义。修改后需重新加载。SCROLL_APPLIER 还要求全局 useEliteItemScrolls 已启用才会生成。
| 键 | 值 | 默认值 |
|---|---|---|
isEnabled | 布尔值 | true |
示例
isEnabled: true
name
设置显示名称，支持颜色代码。EliteMobs 将原文注册到翻译 CSV，并在存在对应译文时使用已配置语言的翻译。
| 键 | 值 | 默认值 |
|---|---|---|
name | 字符串 | 空字符串 |
示例
name: "&aEnn Peecee"
名牌布局
名称与角色标签使用固定布局，没有每个 NPC 独立的 nameplateScale 或 nameplateLineGap 设置。普通和伪装 NPC 的标签跟随实体或伪装高度。兼容的 FreeMinecraftModels 模型自行管理名牌；ModelEngine 保留自己的名称，由 EliteMobs 显示角色标签。个人任务标记位于标签上方。
启用赌博后，特殊 NPC gambling_den_owner.yml 会在同一组标签中加入庄家收益，约每秒刷新一次。
scale
通过 Minecraft 的缩放属性设置底层村民的大小。自定义模型或伪装可以自行控制视觉大小，因此不保证外观随村民同步缩放。
| 键 | 值 | 默认值 |
|---|---|---|
scale | 倍率 | 1.0 |
进行缩放时，1.0 代表默认大小。要让实体变大，请增大该值（例如 1.2）。要让实体变小，请减小该值（例如 0.8）。
示例
scale: 1.2
role
设置名称下方的角色标签，仅影响显示。支持颜色代码，并注册到翻译 CSV。
| 键 | 值 | 默认值 |
|---|---|---|
role | 字符串 | 空字符串 |
示例
role: "&c<Red Fellow>"
profession
设置底层村民的职业；未使用伪装或自定义模型时，它决定村民的外观。
| 键 | 值 | 默认值 |
|---|---|---|
profession | 职业 | NITWIT |
示例
profession: NITWIT
greetings
邻近扫描首次在 activationRadius 内检测到玩家时，尝试从此列表随机选择一句问候，作为仅该玩家可见、持续约 5 秒的悬浮气泡。列表会注册到翻译 CSV。发言仍要求 canTalk 启用且共享对白冷却结束。
| 键 | 值 | 默认值 |
|---|---|---|
greetings | 字符串列表 | 无 |
只在检测到进入时尝试问候。若被共享冷却阻止，玩家继续留在范围内不会重试该问候。
示例
greetings:
- Hi there!
- Good day.
dialog
设置悬浮气泡台词。每次随机选择一条，不按列表顺序读取。列表会注册到翻译 CSV。
何时触发取决于 interactionType：
CHAT在交互时尝试发言，通常是右键点击。FreeMinecraftModels 也会将模型上的左键点击传给交互处理器。- 其他类型在玩家留在范围内的后续扫描中尝试对白；进入时的扫描尝试问候。
字面量 \n 将气泡分成多行。请使用 YAML 单引号保留它，或在双引号内写成 \\n。问候和告别也遵循此规则。
| 键 | 值 | 默认值 |
|---|---|---|
dialog | 字符串列表 | 无 |
示例
dialog:
- I like apples!
- Sure is hot.
farewell
设置随机选择并显示为悬浮气泡的告别语。列表会注册到翻译 CSV。
| 键 | 值 | 默认值 |
|---|---|---|
farewell | 字符串列表 | 无 |
关闭任何标题非空的物品栏界面，都会尝试让附近 NPC 告别。搜索范围是以玩家为中心沿各轴延伸 5 格的区域，不限于所打开菜单的拥有者。多个 NPC 都可能发言。走出 activationRadius 不会触发告别。
示例
farewell:
- Until next time!
- Bye!
canTalk
控制内置聊天气泡。false 抑制 greetings、dialog 和 farewell，但不禁用菜单、命令、Lua 脚本、任务对白、邻近检测或任务标记。
| 键 | 值 | 默认值 |
|---|---|---|
canTalk | 布尔值 | true |
示例
canTalk: true
activationRadius
设置 NPC 能检测到玩家靠近的半径（以方块为单位）。
| 键 | 值 | 默认值 |
|---|---|---|
activationRadius | 双精度 | 3.0 |
每 100 tick（约 5 秒）扫描一次，使用三维距离且不检查视线遮挡。静止 NPC 可以朝向玩家、在检测到进入时问候，并在后续扫描中对白。0 或更低会禁用这些交互，包括 Lua 邻近钩子。QUEST_GIVER 和 CUSTOM_QUEST_GIVER 的个人任务标记使用独立的 30 格半径，在 activationRadius: 0 时仍可显示，并反映该玩家可接取和可提交的任务。
巡逻正在移动或编辑时，会抑制扫描和气泡。patrol.pauseNearPlayersRadius 与 patrol.faceNearbyPlayers 控制玩家附近的暂停和朝向；参阅巡逻。
示例
activationRadius: 3.0
scripts
设置附加到该 NPC 的 Lua 脚本。脚本文件从 plugins/EliteMobs/npc_scripts/ 加载。.lua 扩展名是可选的 —— 如果省略，系统会自动补上。
| 键 | 值 | 默认值 |
|---|---|---|
scripts | 字符串列表 | 无 |
共享的 MagmaCore Lua 引擎支持 on_spawn、on_game_tick、on_remove、on_npc_interact、on_npc_proximity_enter、on_npc_proximity_leave、on_zone_enter 和 on_zone_leave。NPC 的 tick 钩子名为 on_game_tick。每个 NPC 拥有自己的脚本实例，较小的优先级先执行。只有 tick 钩子的脚本还需添加一个可为空的 on_spawn 才能初始化。API 与示例请参阅 Lua NPC 脚本。
名称无法对应到已加载的脚本定义时，会警告并跳过，但 NPC 仍会生成。请匹配文件名的大小写，修改脚本后重新加载。
任务对白可能在 on_npc_interact 之前处理掉点击。否则，该钩子在配置的交互之前运行，不会取消后续交互。
示例
scripts:
- wave.lua
interactionType
设置 NPC 将执行的交互类型。
| 键 | 值 | 默认值 |
|---|---|---|
interactionType | 特殊 [1] | NONE |
示例
interactionType: TELEPORT_BACK
noPreviousLocationMessage
TELEPORT_BACK 没有保存的返回位置时显示此消息。返回位置是从 EliteMobs 世界之外执行 EliteMobs 传送时保存的出发点，不是最近走过的位置或死亡点。返回采用正常的 EliteMobs 传送流程，包括配置的延迟与取消规则。支持颜色代码，并注册到翻译 CSV。
| 键 | 值 | 默认值 |
|---|---|---|
noPreviousLocationMessage | 字符串 | 空字符串 |
示例
noPreviousLocationMessage: '&8[EliteMobs] &cCouldn''t send you back to your previous location - no previous location found!'
timeout
生成后多少分钟移除 NPC。0 或更低禁用计时器。移除不删除已保存的放置位置，也不禁用定义，因此重新加载、重启或恢复区块时 NPC 可能返回。
要删除一个放置位置，执行 /em remove 开启移除模式，击打 NPC，再次执行 /em remove 关闭模式。需要 elitemobs.remove。列表形式会删除对应条目；旧式单位置定义则会被禁用。迁移至 spawnLocations 时请删除旧键 spawnLocation，否则列表清空后旧位置可能重新生效。
| 键 | 值 | 默认值 |
|---|---|---|
timeout | 双精度 | 0（永不） |
示例
timeout: 0
questFileName
为 CUSTOM_QUEST_GIVER 列出 plugins/EliteMobs/customquests/ 中的任务文件名，包括 .yml。键名是单数，值是列表。菜单提供符合条件的任务，也接受分配给此 NPC 文件名的任务提交，因此专用于提交任务的 NPC 可以使用空列表。同一文件的所有放置位置共享此任务身份。各任务自身的权限和条件仍然适用。
| 键 | 值 | 默认值 |
|---|---|---|
questFileName | 字符串列表 | 无 |
示例
questFileName:
- my_quest_one.yml
- my_quest_two.yml
disguise
设置伪装，需要 LibsDisguises。成功加载的自定义模型优先于伪装。
| 键 | 值 | 默认值 |
|---|---|---|
disguise | LibsDisguises 格式 | 无 |
示例
disguise: SKELETON
customDisguiseData
设置自定义 LibsDisguises 伪装的数据。
| 键 | 值 | 默认值 |
|---|---|---|
customDisguiseData | LibsDisguises 格式 | 无 |
示例
disguise: custom:my_cool_disguise_name
customDisguiseData: player my_cool_disguise_name setskin {"id":"364acb6d-9050-46f7-b5fb-f8c3fd83a6fc","name":"Unknown","properties":[{"name":"textures","value":"ewogICJ0aW1lc3RhbXAiIDogMTYxMTk4ODA4Nzc1NSwKICAicHJvZmlsZUlkIiA6ICJkZGVkNTZlMWVmOGI0MGZlOGFkMTYyOTIwZjdhZWNkYSIsCiAgInByb2ZpbGVOYW1lIiA6ICJEaXNjb3JkQXBwIiwKICAic2lnbmF0dXJlUmVxdWlyZWQiIDogdHJ1ZSwKICAidGV4dHVyZXMiIDogewogICAgIlNLSU4iIDogewogICAgICAidXJsIiA6ICJodHRwOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlLzliYmVkODQzNWY4YmYyNzhhZmUyNmU2NGZkOTI2YjhiMzc3MzJkODhlMzM0ODk3ZGJkNTI3ZDU2ZmY5MTk5MGUiCiAgICB9CiAgfQp9","signature":"ujLq1joYVktuQAp1xpFKlxQFUVinSePiDBiVCAxxix/mA5vP86i/eAOfb1mtGjaAZ6sO0l2olbzvycnGXNBtbAxgqprguROXY4tpWiePVTDmy3iD4GdOCxHAkYLoyMV5qTT4SNsldUFFuND8GSEgbNMltKDLmhNKwzm08iCigPfpeuYpwljgJPxu6ka54PKNaQu4doI0ZDZXKqq4hPhR3Bs2Sz9MI0SmdmQWwcCzUz3DFdVno27fmQ6LwqmT+eSoOv0EttVG/XMaTYQ5lhBY61mqf6WlJyYVUSfjJk1AbYsctu7dWM+sbY8jFq5ljvXJGGr5TyKi+fs8vHy06Z2go20QgTYOw+caFxFijAS6fgm3oY57VEO/+/9OLHdD+Z9BrWqQWcIIrVeIfxjue/yt4pyeVv9jX59hjNFjhcPEwotkxJ+vZ96WlTLWDG4BiqauDr2VeGyLlVaygO9ZU0wwsN65iSh91GI3tMIA5wbDR0Hts/9ABvt9eafHbowS+4SZXN0i9mYnKg7op1eiB8nMEAGsPJg3DwsmUrh3ACAapQ6eYHiJpo59RXDqKlRcXwo7wsEFp//5LgQWbPj0NP3nxnywdpozqSAeq6236qlhE9BT9eiyJ41V9sMelYFEWMlUAltR40NdbIrHB0J3nmfuLJz44/sTwWf6P1khOy//XX0="}],"legacy":false}
customModel
设置 FreeMinecraftModels 或 ModelEngine 模型。先在所选提供方中安装模型，再引用其 ID。两者都可用时优先使用 FreeMinecraftModels；缺少 FMM 模型不会转而选择 ModelEngine。若没有模型加载成功，则使用配置的伪装或普通村民外观。参阅自定义模型。
| 键 | 值 | 默认值 |
|---|---|---|
customModel | 字符串 | 无 |
示例
customModel: MY_MODEL_ONE
职业导师与运输 NPC
使用 interactionType: CLASS_TRAINER 和 classRoot 选择职业分支。请从随附的 class_trainer_*.yml 定义开始。试炼与进度见 Advanced Combat System。
对于 interactionType: TRANSPORT，transportRoutes 列出不含 .yml 的路线 ID，点击 NPC 会打开目的地选择。参阅运输路线。
arena
设置 NPC 将为之打开菜单的竞技场的文件名（需要 ARENA_MASTER interactionType）。
| 键 | 值 | 默认值 |
|---|---|---|
arena | 文件名 | 无 |
示例
arena: my_arena.yml
command
COMMAND 的命令，在下一 tick 以点击者身份执行，需要该玩家正常的命令权限。省略开头的 /。此字段不会自动展开玩家占位符，也不使用 EliteMobs 控制台命令格式。
| 键 | 值 | 默认值 |
|---|---|---|
command | 字符串 | 无 |
示例
command: say Look at me running a command, how cool!
spawnLocation
为 NPC 设置单个生成位置。这是旧式的单位置键：只有在 spawnLocations 缺失或为空时才会被读取。在游戏内放置的新位置会改为写入 spawnLocations，因此请优先使用那个键。
推荐格式为 world,x,y,z,yaw,pitch。所指世界必须已加载，此设置不会加载世界。
| 键 | 值 | 默认值 |
|---|---|---|
spawnLocation | 字符串 | 无 |
示例
spawnLocation: my_world,10,50,10,0,0
spawnLocations
定义同一 NPC 的多个放置位置。/em place npc <npcfilename.yml> 将当前位置和朝向四舍五入到两位小数后追加，并设置 isEnabled: true。序列化后完全相同的位置不会重复添加。区块可以处理实体 tick 后，NPC 才会恢复。
每个条目的格式为 world,x,y,z,yaw,pitch。
| 键 | 值 | 默认值 |
|---|---|---|
spawnLocations | 字符串列表 | 无 |
示例
spawnLocations:
- my_world,10,50,10,0,0
- my_world,-10,50,-10,0,0
instanced
设置 NPC 是否应被实例化（用于实例地下城）。当设为 true 时，该 NPC 不会在蓝图世界中生成；它会被注册为一个模板，并为每个地下城实例克隆一份，每个克隆体存在于对应的实例世界中。
| 键 | 值 | 默认值 |
|---|---|---|
instanced | 布尔值 | false |
示例
instanced: false
syncMovement
设置 NPC 的自定义模型是否应与底层实体同步移动。只有在设置了 customModel 且模型已加载时才有效 —— 对于普通 NPC 和 LibsDisguises NPC 会被忽略。
有效的 patrol 配置会启用移动同步，即使巡逻暂停或本项为 false。本项仍用于不巡逻的自定义模型。
| 键 | 值 | 默认值 |
|---|---|---|
syncMovement | 布尔值 | true |
示例
syncMovement: true
patrol
为 NPC 添加使用原生导航和自动寻路的路线。节点是相对于此 NPC 预设生成位置的偏移；设置 patrol.relative: false 时则是其所在世界中的精确坐标。长路段会自动拆分，且不会强制加载区块。patrol.startNodeWaitSeconds 会让 NPC 每圈在第一个节点处停留休息一次；NPC 专用的 patrol.pauseNearPlayersRadius 会让它在玩家附近暂停，patrol.faceNearbyPlayers 则让它在暂停时转向这些玩家。完整配置、游戏内编辑器、长距离行为和 Lua 控制请参阅 NPC 与首领巡逻。
NPC 配置示例
isEnabled: true
name: "&cRed Rubin"
role: "&a<Generic NPC>"
profession: NITWIT
greetings:
- Hiya!
- Hello!
dialog:
- Great conversation!
- Pleasure talking with you!
farewell:
- Goodbye!
- Laters!
canTalk: true
activationRadius: 4
interactionType: CHAT
timeout: 0
spawnLocations:
- my_world,584,55,127,90,10
特殊 [1]
以下是有效的 NPC 交互类型列表：
| 类型 | 描述 |
|---|---|
GUILD_GREETER | 打开武器技能加成。需要 elitemobs.skill.npc。 |
CLASS_TRAINER | 打开 classRoot 指定的分支。需要 elitemobs.command。 |
TRANSPORT | 打开 transportRoutes 中的目的地。 |
CHAT | 交互时尝试随机说出一句 dialog。 |
CUSTOM_SHOP | 打开自定义商店。需要 elitemobs.shop.custom.npc。 |
PROCEDURALLY_GENERATED_SHOP | 打开生成商店。需要 elitemobs.shop.dynamic.npc。 |
BAR | 未实现。告知玩家该功能即将推出。 |
ARENA | 不执行任何操作。请改用 ARENA_MASTER。 |
QUEST_GIVER | 打开生成任务。需要 elitemobs.quest.npc。 |
CUSTOM_QUEST_GIVER | 提供 questFileName 中符合条件的任务，并接受指定任务的提交。 |
NONE | 没有内置动作；脚本、邻近检测和任务对白仍可运行。 |
SELL | 打开出售。需要 elitemobs.shop.sell.npc。 |
TELEPORT_BACK | 使用保存的 EliteMobs 返回位置。需要 elitemobs.back.npc。 |
SCRAPPER | 打开拆解。需要 elitemobs.scrap.npc。 |
REPAIRMAN | 打开修理。需要 elitemobs.repair.npc。 |
ENCHANTER | 打开附魔。需要 elitemobs.enchant.npc。 |
REFINER | 已替换 —— 告知玩家该功能已被替换；建议管理员移除该 NPC |
SMELTER | 已替换 —— 告知玩家该功能已被替换；建议管理员移除该 NPC |
ENHANCER | 已替换 —— 告知玩家该功能已被替换；建议管理员移除该 NPC |
UNBINDER | 打开解绑。需要 elitemobs.unbind.npc。 |
ARENA_MASTER | 打开 arena 中所设竞技场的竞技场菜单 |
COMMAND | 运行 command 中所设的命令 |
SCROLL_APPLIER | 打开精英物品卷轴。需要 elitemobs.scroll.npc；useEliteItemScrolls 禁用时不生成。 |
ARROW_SHOP | 打开箭矢商店。需要 elitemobs.shop.arrow.npc。 |
GAMBLING_BLACKJACK | 打开二十一点。需要 elitemobs.gambling.npc。 |
GAMBLING_COINFLIP | 打开抛硬币。需要 elitemobs.gambling.npc。 |
GAMBLING_SLOTS | 打开老虎机。需要 elitemobs.gambling.npc。 |
GAMBLING_HIGHERLOWER | 打开猜大小。需要 elitemobs.gambling.npc。 |
关于 SCRAPPER 及类似交互类型的更多信息，请点击 这里。
NPC 行为说明
内置行为还包括：
- 移动：通常静止并朝向附近玩家，巡逻和脚本可以移动 NPC。巡逻路线代替普通村民行为。
- 交互顺序：任务对白可能先于 Lua 和内置动作处理点击。否则先运行 Lua，再运行配置的动作及其权限检查。每个玩家有跨 NPC 的 1 tick 防重复限制。编辑巡逻会阻止交互，普通巡逻移动不会。
- 保护：NPC 本体不会正常发生碰撞。EliteMobs 取消伤害、村民转化以及普通村民交易界面的打开。
- 标签：名称与角色使用上述固定布局。普通和伪装 NPC 使用当前本体高度，因此缩放也可能移动标签。兼容的 FMM 模型统一管理名称和角色。
- 基岩版：显示取决于当前模型和显示集成。当前 NPC 名牌渲染器不使用保留的
bedrockNPCRoleYOffset配置键。 - 对白冷却：每个 NPC 在所有玩家之间共享 3 秒的发言间隔。向一名玩家问候可能阻止同时向另一名玩家问候。个人气泡约 5 秒后消失。
- 隐身：处于隐身药水效果下的 NPC 不会显示聊天气泡。
- 区块：卸载时移除 NPC，区块恢复实体 tick 处理后重建。NPC 实体不保存到世界，放置位置由配置提供。
- 重命名：主手持命名牌对本体村民进行普通右键交互时，会取消并提示。模型使用自己的点击回调；FreeMinecraftModels 将左键与右键点击都传给 NPC 交互处理器。