NPC Plugin

插件

· 作者 Eisi05

通过 GUI 和 API 自定义 NPC

0 本站下载 0 关注 更新于 1 周前

最新 1.20.6-3.6.4 · 1.20.6 · Folia / Paper

一键开服(送7天)
NPC Plugin Logo

如果您有任何建议、希望添加新功能或遇到任何问题,您可以使用 issue 页面 或在 Discord 上联系我 @eisi05


通过游戏内编辑器 GUI、点击动作、AI 目标和内置路径系统,创建、自定义和管理类似玩家的外挂 NPC。

⚠️ Folia 支持目前处于测试阶段,可能包含错误!

⚠️ 重要提示: 如果您是从 2.1.0 之前的版本升级,您必须先更新到 2.1.0 和 2.4.2 之间的版本,然后再安装 3.x.x。

? 翻译与本地化:

如果您想为项目添加新语言,请联系我,以便我在 Crowdin 上为您设置!或者您也可以直接发送给我翻译好的 .zip 文件

如果您想制作关于此的教程视频,请随意制作

支持版本

Spigot: 1.20.6 - 26.3

Paper/Purpur/Folia: 1.21 – 26.3 (1.20.6: 更新频率较低)

概述

  • 游戏内编辑器:直接在您的服务器上创建和配置 NPC。
  • 点击动作:构建左键/右键/双击的动作链。
  • 路径系统:创建和重用路径(包括可视化 + 测试)。

入门指南

  • /npc create
  • /npc edit
  • 右键点击 NPC 以打开其编辑器。

链接

  • 插件文档:
  • API / 开发者文档:
    • Spigot:
    • Paper:

亮点

  • 游戏内 NPC 编辑器
    • 切换编辑模式并通过与 NPC 交互直接配置它们。
    • 编辑常见属性,如名称、皮肤、装备、发光效果、可见性、标签页列表、姿势等。
  • 点击动作(左键 / 右键 / 两者)
    • 构建当玩家点击 NPC 时运行的动作链。
    • 内置动作类型包括:
      • Command(运行带有占位符和变量的命令)
      • Server(将玩家发送到 BungeeCord 服务器)
      • Wait(按时间等待或由命令触发等待)
      • Animation(播放动画)
      • Path(让 NPC 沿保存的路径行走)
      • SetVariable(设置局部/实例/全局数值变量)
      • Condition(如果表达式为真,则运行子链)
      • Loop(重复子链;while 循环或 for 循环)
      • Npc(作为动作,按玩家应用 NPC 选项或全局应用)
      • Stop(停止链)
  • 路径系统
    • 使用点创建路径,可视化它们,用临时 NPC 测试它们,并在 NPC 动作中重用它们。
  • AI 目标
    • 使用内置目标配置 NPC 行为:走到位置、沿路径行走、跟随实体、攻击实体、环顾四周、等待和漫游。
    • 使用表达式设置目标谓词,以实现动态实体选择。
  • 表达式解析器
    • 使用带有变量、函数和布尔逻辑的数学表达式。
    • 支持局部、实例和全局变量。
    • 在表达式中执行命令并使用其结果。
  • 本地化 + PlaceholderAPI
    • 附带语言文件(默认 en_US)。
    • 支持 PlaceholderAPI(软依赖):在适用的插件消息中可以使用占位符。

指南

入门指南(安装 + 快速开始)

安装

  1. 下载 jar 文件并将其放入服务器的 plugins/ 文件夹中。
  2. 启动服务器一次。
  3. 配置(可选):
    • plugins/NpcPlugin/config.yml
    • plugins/NpcPlugin/lang/<language>/*.json
  4. 重启或运行 /npc reload。

快速开始

1) 创建 NPC

  • /npc create

2) 启用编辑模式

  • /npc edit

在编辑模式启用时:

  • 与 NPC 交互 以打开其编辑器 GUI。

如果 NPC 不可编辑,您将收到类似 This NPC is not editable! 的消息。

3) 在 GUI 中配置 NPC 选项

GUI 允许您更改以下内容:

  • 名称
  • 皮肤(玩家名称 / UUID / 本地 .png / URL / .yml 文件 / PlaceholderAPI)
  • “使用玩家皮肤”(每个玩家的皮肤)
  • 装备槽位
  • 可见性 / 启用状态
  • 标签页列表可见性
  • 隐藏名字标签
  • 姿势
  • 皮肤部件
  • 发光效果 + 颜色
  • 看向玩家半径 / 间隔
  • 缩放
  • 传送到 NPC / 将 NPC 传送到你身边
  • 删除 NPC
  • 目标

有关设置皮肤的详细信息,请参阅 皮肤指南。

点击动作

点击动作(左键 / 右键 / 两者)

在 NPC GUI 中进入 Click Action(点击动作)。

您可以为以下情况分别配置动作:

  • 左键点击
  • 右键点击
  • 两者(组合)

您可以通过添加多个动作为其创建动作链。

动作编辑技巧

  • 移除动作:鼠标中键点击现有动作。
  • 快速添加动作:按住 Shift 并点击动作类型以追加它。
  • 重新排序/插入:将动作类型拾取到光标上,然后点击一个槽位。

常见动作类型

Command(命令)

执行一条命令。

  • 输入可以带或不带前导 /(插件将其存储为 /<command>)。
  • 支持占位符:
    • {player} / %player% / <player>
    • {player_name} / %player_name% / <player_name>
  • 通过插件的动作系统支持变量/表达式。
  • 提供可选的语法验证。

示例:

  • warp spawn
  • server hub
  • msg {player} Welcome!

Server(BungeeCord)

将玩家发送到另一个 BungeeCord 服务器。

示例服务器名称:

  • hub

Wait(等待)

在继续之前暂停链条。

您可以在编辑器中切换两种模式:

时间模式
  • 左键/右键点击调整时间
  • Shift+左键/Shift+右键进行大步长调整
  • 范围被限制(最小 0.05s,最大 600s)
命令模式

链条不等待时间,而是等待管理员触发:

  • Wait 存储一个名称(字符串)
  • 仅在满足以下条件后链条才会继续:
    • /npc wait <player> <name> [values...]

如果提供了 [values...],它们将作为局部变量暴露给后续动作:

  • <name>-0, <name>-1, ...(数值;无效数字变为 0.0)

这适用于等待外部系统(小游戏、脚本事件等)。

注意(路径)

Path 动作也在内部使用相同的等待机制:当 NPC 完成行走时链条继续。

Path(路径)

使 NPC 沿着保存的路径行走。

  • 您选择一个路径名称(必须存在;同一世界)+ 速度(0.01–1.0)。
  • 可选标志:
    • For all(所有人都看到 NPC 行走)
    • Change real location(更新 NPC 的实际位置,使其在行走过程中实时更新)

Animation(动画)

为点击者播放 NPC 的动画。

  • 左键点击:下一个动画
  • 右键点击:上一个动画

SetVariable(设置变量)

设置一个数值变量。

  • 类型:
    • Local(按玩家存储)
    • Instance(存储在 NPC 上)
    • Global(全服存储;持久化保存在 global-variables.yml 中)
  • 名称必须符合 ^[a-zA-Z_][a-zA-Z0-9_-]*$
  • 值是一个表达式

如果缺少值,该动作将不起作用(管理员会收到警告)。

Condition(条件)

仅在其表达式为 true 时运行子链。

  • 像正常动作列表一样编辑子链
  • 条件表达式通过“值”物品进行编辑

Loop(循环)

重复一个子链。

有两种循环类型:

While 循环
  • 当表达式为 true 时重复执行
For 循环
  • 使用整数循环索引重复执行
  • 可配置的值:
    • Start(可选;默认为 0)
    • End(必需)
    • Step(可选;默认为 1)

您可以通过按住 Shift 并点击该动作来更改循环类型。

Npc(NPC)

打开一个特殊编辑器,允许您将 NPC 选项作为动作应用。

这主要用于更改 NPC 的外观/行为,针对:

  • 仅限点击者(按玩家覆盖)
  • 所有人(全局)

存在两个标志:

  • Change globally(全局更改):将配置的选项应用到 NPC 的全局选项
  • Reset to default(重置为默认):移除按玩家的覆盖并重置为 NPC 的默认值

Stop(停止)

立即停止当前链条(也停止嵌套链条)。

Run-on-show(显示时运行)

在动作编辑器中,您可以启用 Run on show。

如果启用,当 NPC 向玩家展示时链条就会触发(而不仅仅是点击时)。

路径系统指南

路径系统指南

路径是共享的,并存储在:

  • plugins/NpcPlugin/paths.yml

从点创建路径

  1. 在您当前位置添加点:

    • /npc path point add

    或在特定索引处添加:

    • /npc path point add <index>
  2. 列出点:

    • /npc path point list [page]
  3. 可视化/切换当前点的可视化:

    • /npc path visualize points
  4. 创建路径:

    • /npc path create <name>(打开带有基本导航选项的 GUI)
    • /npc path create <name> default(使用默认预设创建)
    • /npc path create <name> natural(使用自然预设创建)
    • /npc path create <name> global(使用全局预设创建)
    • /npc path create <name> gui(打开带有基本导航选项的 GUI)

    您还可以在预设或 gui 子命令之后添加特定的导航选项:

    • /npc path create <name> default --option value ...
    • /npc path create <name> gui --option value ...

创建后,您可以可视化它:

  • /npc path visualize <name>

通过行走录制路径

  1. 开始录制:

    • /npc path record start [snap-to-grid]

    可选的 snap-to-grid 参数将录制的点吸附到最近的方块中心。

  2. 沿路线行走。

  3. 停止录制:

    • /npc path record stop
  4. 创建路径:

    • /npc path create <name>

编辑现有路径

  • /npc path edit <name>

这将加载已保存路径的路径点进入点列表,以便您可以删除/添加点并重新创建它。

列出 / 删除 / 测试路径

  • /npc path list [page]
  • /npc path delete <name>
  • /npc path test <name> [speed]
目标指南

目标指南

目标赋予 NPC 自主行为。通过 NPC 编辑器 GUI 进行配置。

可用目标

  • 走到位置:NPC 使用寻路系统移动到指定位置
  • 沿路径行走:NPC 沿着保存的路径行走
  • 跟随实体:NPC 通过 UUID 跟随目标实体
  • 攻击实体:NPC 攻击附近匹配的实体
  • 环顾四周:NPC 随机环顾四周(空闲行为)
  • 等待:NPC 等待指定的持续时间
  • 漫游:NPC 在半径范围内随机漫游

攻击实体谓词

使用带有变量的表达式来筛选目标实体:

  • $distance - 到 NPC 的距离
  • $entity.x, $entity.y, $entity.z - 实体坐标
  • $entity.health - 实体生命值
  • $npc.x, $npc.y, $npc.z - NPC 坐标
  • [if entity @s[type=zombie]] - 基于命令的实体类型检查

示例谓词:

  • $distance < 5 - 仅在 5 格内攻击
  • $entity.health < 10 - 攻击低生命值的实体
  • $distance < 10 && $entity.health > 5 - 组合条件

更多详情请参阅 完整的目标文档。

表达式解析器指南

表达式解析器指南

在点击动作、目标条件和变量计算中使用数学表达式。

支持的元素

运算符:+, -, *, /, ^ (幂), &&, ||, !, ==, !=, <, >, <=, >=

数学函数:sin(), cos(), tan(), sqrt(), log(), exp(), ceil(), floor(), round(), trunc(), abs()

常量:PI, E

变量

  • $varName - 自动解析(局部 → 实例 → 全局)
  • $global.varName - 服务器级变量
  • $instance.varName - NPC 专属变量
  • $local.varName - 玩家专属变量

特殊变量:

  • $self.rightClick / $self.leftClick - 点击类型(1 或 0)
  • $self.sneaking, $self.flying, $self.op - 玩家状态
  • $loop.index - 循环迭代索引

命令执行

  • (/command) - 在表达式中执行命令
  • /command - 独立命令执行

示例:

  • 2 + (/count players) - 在计算中使用命令结果
  • $global.score + 1 - 增加变量值
  • ($entity.health < 10) * 5 - 条件返回值

完整语法参考请参阅 表达式解析器文档。

命令

命令

核心

  • /npc create [options](选项以键值对形式定义,例如 --name "Test")
  • /npc copy <npc>
  • /npc edit(切换编辑模式)
  • /npc edit <npc>(编辑特定 NPC)
  • /npc edit <npc> <options>(编辑特定 NPC 的选项,选项以键值对形式定义,例如 --name "Test")
  • /npc delete <npc> [force](删除特定 NPC)
  • /npc list(打开 NPC 列表 GUI)
  • /npc tp <npc> [location] [rotation]
  • /npc tphere <npc>
  • /npc reload [npc]
  • /npc version
  • /npc update(检查是否有新的插件版本)
  • /npc cancel <npc>(取消 NPC 点击动作)
  • /npc cancel all(取消所有 NPC 点击动作)
  • /npc load <npc>(从存储中加载 NPC)
  • /npc load <npc> <location>(在指定位置加载 NPC)
  • /npc load <npc> <location> <rotation>(在指定位置及旋转角度加载 NPC)
  • /npc click <npc>(对自己执行 NPC 点击动作)
  • /npc click <npc> <target>(对目标执行 NPC 点击动作)
  • /npc move <npc> turn <degree>(按相对角度旋转 NPC)
  • /npc move <npc> <flag> [steps] [speed](使用方向标志移动 NPC)
  • /npc help(显示帮助信息)
  • /npc issue(显示问题追踪器链接)
  • /npc wiki(显示 Wiki 链接)
  • /npc message <player> <message>(可在命令动作中使用以发送消息,支持 '&' 颜色代码)
  • /npc tag <npc> add <tag>(为 NPC 添加标签)
  • /npc tag <npc> remove <tag>(移除 NPC 的标签)
  • /npc tag <npc> list(列出 NPC 的所有标签)
  • /npc animation <animation> [targets](在指定目标上播放动画)
  • /npc languages reload(从磁盘重新加载所有语言文件)
  • /npc languages restore [language](从资源中恢复默认语言文件,覆盖所有“官方”语言文件)

配置

  • /npc config reload
  • /npc config debug [true|false]
  • /npc config avoid-command-check [true|false]
  • /npc config look-at-update-interval [ticks]
  • /npc config input-time [seconds]
  • /npc config auto-update [true|false]
  • /npc config placeholder-timer [ticks]
  • /npc config check-valid-path [true|false]
  • /npc config walking-viewer-distance [distance]
  • /npc config precise-sleeping-hitbox [true|false]
  • /npc config load-chunks-on-path [true|false]
  • /npc config pathfinding-factory [a_star|bounding_box] [gridStep]
  • /npc config name-display
  • /npc config list

异常(启动加载失败)

  • /npc exceptions [page]
  • /npc exceptions show <name>
  • /npc exceptions delete <name>

路径

所有路径命令位于:

  • /npc path ...

主要子命令:

  • point add [index] [location] [rotation]
  • point remove [index|location]
  • point list [page]
  • point clear
  • create [name] [pathfinder] [maxIterations] [allowDiagonalMovement]
  • delete <name>
  • list [page]
  • visualize [name]
  • visualize points
  • record start [snap-to-grid](开始记录行走时的路径点)
  • record stop(停止记录)
  • test <name> [speed]
  • edit <name>(加载已保存路径的路标以供编辑)

移动

所有移动命令位于:

  • /npc movement ...

主要子命令:

  • record start [player](开始录制移动轨迹)
  • record stop [player] <name> [overwrite](停止录制并保存)
  • record stop <name> [overwrite](停止录制并为自身保存)
  • record(给予录制物品)
  • list [page](列出所有移动录制,支持分页)
  • details <name>(显示录制的详细信息)
  • delete <name>(删除移动录制)
  • play <name> [speed](在自身上播放录制)
  • play <name> <target> [speed](在目标实体上播放录制)

执行上下文 (Execute Context)

允许动态选择目标和重定向上下文的 NPC 子命令执行修饰符:

  • /npc execute as <selector> do <command>(以选定的 NPC 上下文执行目标 NPC 命令)
  • /npc execute at <selector> do <command>(使用选定 NPC 的瞄准位置和朝向执行命令)
  • /npc execute positioned as <selector> do <command>(在选定 NPC 的位置执行命令)
  • /npc execute rotated as <selector> do <command>(使用选定 NPC 的旋转角度执行命令)

NPC 选择器系统 (NPC Selector System)

目标选择器系统 (NpcSelector) 解析符合标准 Minecraft 目标选择器语法的实体目标语法,以查询已注册的 NPC:

  • 目标指定符 (Target Specifiers):
    • @a – 匹配所有已加载/已注册的 NPC。
    • @s – 匹配当前处于活动 /npc execute 上下文中的被选定 NPC(自我引用)。
    • @n / @p – 相对于命令源原点,选择距离最近的单个 NPC。
    • @r – 随机选择一个 NPC 候选者。
    • <name|uuid> – 直接通过显示名称或唯一 ID 查询 NPC。
  • 过滤参数 ([...]):
    • tag=<value> / tag=!<value> – 筛选拥有(或缺少)特定已分配标签的 NPC。
    • nbt={<key>:<value>} – 针对特定的内部 NpcOption 状态或自定义存储数据评估目标选项。
    • distance=<min>..<max> – 根据从执行原点的欧几里得距离边界限制候选者。
    • limit=<count> – 限制最大返回结果数量。

等待触发器 (Wait trigger)

与 Wait 点击动作(命令模式)配合使用:

  • /npc wait <player> <name> [values...]

变量 (Variables)

通过命令管理服务器范围内的全局变量:

  • /npc variable list - 列出所有全局变量
  • /npc variable get <name> - 获取变量的值
  • /npc variable set <name> <expression> - 设置变量(支持表达式)
  • /npc variable delete <name> - 删除变量

也可以通过 SetVariable 点击动作管理变量,并在插件中的表达式里使用它们。

配置

配置 (config.yml)

  • look-at-update-interval:
    • “注视玩家”更新的间隔刻度数。
  • avoid-command-check:
    • 如果为 true,添加到 NPC 动作的命令将不会进行严格验证。
  • debug:
    • 启用额外的调试日志记录。
  • input-time:
    • 对话超时时间(秒)(如果 < 0,则无超时)。
  • auto-update:
    • 更改选项后自动更新 NPC。
  • placeholder-timer:
    • 占位符刷新的间隔刻度数。
  • check-path:
    • 检查路径是否有效(路径下方是否有实心方块)
  • walking-viewer-distance:
    • 玩家能看到 NPC 行走的距离(方块单位)
  • precise-sleeping-hitbox:
    • 如果为 true,对正在睡觉的 NPC 使用精确的碰撞箱检测
  • load-chunks-on-path:
    • 如果为 true,加载 NPC 路径上的区块
  • pathfinding-factory:
    • 使用的寻路工厂。选项有 ASTAR 和 BOUNDING_BOX <gridStep>(例如 "BOUNDING_BOX 0.5")。<gridStep> 必须在 0.01 到 1.0 之间。
    • BOUNDING_BOX 基于 Theta* 算法,提供更精确的碰撞检测,例如用于那些虽然是实心但仍可穿过的方块(如架子)。
  • pathfinding-passable-override:
    • 即使通常是实心的(如架子),也应被视为可通过的路径查找方块类型列表。
    • 此设置仅可通过 config.yml 文件编辑,不能通过 /npc config 命令修改!
故障排除

故障排除

  • “该插件不支持 Paper 服务器!”
    • 您在 Paper 服务器上运行的是 Spigot 构建版本。请改为安装 Paper 构建版本。
  • 服务器动作无任何反应
    • 确保已设置 BungeeCord,且服务器名称与您的代理配置匹配。
  • 无法打开编辑器 GUI
    • 请确保您:
      • 拥有 npc.admin 权限
      • 已通过 /npc edit 启用编辑模式
      • NPC 被标记为可编辑
Skript 支持

要在 Skript 中使用此插件的事件,您需要 Skript-Reflect


基本用法

import:
  de.eisi05.npc.api.events.<EventName>

on <EventName>:
    # 在此处编写您的代码

将 <EventName> 替换为下面列出的事件之一。


可用事件


NpcHideEvent

当 NPC 对某玩家隐藏后触发。

可用值:

  • event.getNpc() → NPC
  • event.getPlayer() → Player

NpcInteractEvent

当玩家与 NPC 交互时触发。

可用值:

  • event.getNpc() → NPC
  • event.getPlayer() → Player
  • event.getAction() → ClickActionType (LEFT / RIGHT)
  • event.isCancelled() → boolean

NpcPostShowEvent

当 NPC 对某玩家完全可见后调用。

注意: 此事件无法被取消。

可用值:

  • event.getNpc() → NPC
  • event.getPlayer() → Player
  • event.wasViewer() → boolean(如果玩家之前已经见过此 NPC,则为 true)

NpcPreShowEvent

在 NPC 向玩家显示之前调用。

注意: 此事件可以被取消。

可用值:

  • event.getNpc() → NPC
  • event.getPlayer() → Player
  • event.wasViewer() → boolean
  • event.isCancelled() → boolean

NpcStartWalkingEvent

在 NPC 开始沿路径行走之前调用。

可用值:

  • event.getNpc() → NPC
  • event.getPath() → Path
  • event.getWalkSpeed() → double
  • event.isChangeRealLocation() → boolean(是否更新 NPC 的真实位置)
  • event.isCancelled() → boolean

NpcStopWalkingEvent

在 NPC 停止行走后调用。

可用值:

  • event.getNpc() → NPC
  • event.getWalkingResult() → WalkingResult(SUCCESS / CANCELLED)
  • event.changeRealLocation() → boolean(是否应用最终位置)

示例

你还可以像在 Skript 中直接访问 Java 方法一样使用以下方式:

import:
  de.eisi05.npc.api.events.NpcInteractEvent

on NpcInteractEvent:
    set {_player} to event.getPlayer()
    send "Triggered!" to {_player}

其他资源

有关 Skript-Reflect 语法和功能的更多信息,请访问:

bStats

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源