如果您有任何建议、希望添加新功能或遇到任何问题,您可以使用 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 以打开其编辑器。
链接
亮点
- 游戏内 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(软依赖):在适用的插件消息中可以使用占位符。
指南
入门指南(安装 + 快速开始)
安装
- 下载 jar 文件并将其放入服务器的
plugins/ 文件夹中。
- 启动服务器一次。
- 配置(可选):
plugins/NpcPlugin/config.yml
plugins/NpcPlugin/lang/<language>/*.json
- 重启或运行
/npc reload。
快速开始
1) 创建 NPC
2) 启用编辑模式
在编辑模式启用时:
如果 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 服务器。
示例服务器名称:
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 循环
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
从点创建路径
-
在您当前位置添加点:
或在特定索引处添加:
/npc path point add <index>
-
列出点:
/npc path point list [page]
-
可视化/切换当前点的可视化:
/npc path visualize points
-
创建路径:
/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>
通过行走录制路径
-
开始录制:
/npc path record start [snap-to-grid]
可选的 snap-to-grid 参数将录制的点吸附到最近的方块中心。
-
沿路线行走。
-
停止录制:
-
创建路径:
编辑现有路径
这将加载已保存路径的路径点进入点列表,以便您可以删除/添加点并重新创建它。
列出 / 删除 / 测试路径
/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>
路径
所有路径命令位于:
主要子命令:
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>(加载已保存路径的路标以供编辑)
移动
所有移动命令位于:
主要子命令:
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:
auto-update:
placeholder-timer:
check-path:
walking-viewer-distance:
precise-sleeping-hitbox:
- 如果为 true,对正在睡觉的 NPC 使用精确的碰撞箱检测
load-chunks-on-path:
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
If you have any suggestions, would like a feature to be added, or encounter any issues, you can use the issue page or contact me on Discord @eisi05
Create, customize, and manage player-like NPCs with an in-game editor GUI, click actions, AI goals, and a built-in path system.
⚠️ Folia support is currently in beta and may contain bugs!
⚠️ Important: If you're upgrading from a version earlier than 2.1.0, you must first update to a version between 2.1.0 and 2.4.2 before installing 3.x.x.
? Translations & Localization:
If you want to add a new language to the project, please reach out to me so I can set it up on Crowdin for you! Or you can send me a translated .zip file directly
If you want to make a tutorial video about it, feel free to do so
Supported Versions
Spigot: 1.20.6 - 26.3
Paper/Purpur/Folia: 1.21 – 26.3 (1.20.6: less frequent updates)
Overview
- In-game editor: create and configure NPCs directly on your server.
- Click Actions: build action chains for left/right/both clicks.
- Path system: create and reuse paths (including visualization + testing).
Getting Started
/npc create
/npc edit
- Right-click an NPC to open its editor.
Links
- Plugin docs:
- API / Developer docs:
Highlights
- In-game NPC editor
- Toggle edit-mode and configure NPCs directly by interacting with them.
- Edit common properties like name, skin, equipment, glow, visibility, tab-list, pose, and more.
- Click Actions (Left / Right / Both)
- Build action chains that run when players click an NPC.
- Built-in action types include:
Command (run commands with placeholders + variables)
Server (send players to a BungeeCord server)
Wait (wait by time or by command trigger)
Animation (play an animation)
Path (make the NPC walk along a saved path)
SetVariable (set local/instance/global numeric variables)
Condition (run a sub-chain if an expression is true)
Loop (repeat a sub-chain; while-loop or for-loop)
Npc (apply NPC options per-player or globally as an action)
Stop (stop the chain)
- Path system
- Create paths using points, visualize them, test them with a temporary NPC, and reuse them in NPC actions.
- AI Goals
- Configure NPC behavior with built-in goals: Walk to Location, Walk Path, Follow Entity, Attack Entity, Look Around, Wait, and Wander.
- Set target predicates using expressions for dynamic entity selection.
- Expression Parser
- Use mathematical expressions with variables, functions, and boolean logic.
- Support for local, instance, and global variables.
- Execute commands within expressions and use their results.
- Localization + PlaceholderAPI
- Ships with language files (default
en_US).
- PlaceholderAPI is supported (soft-depend): placeholders can be used in plugin messages where applicable.
Guides
Getting Started (Installation + Quick Start)
Installation
- Download the jar and place it into your server’s
plugins/ folder.
- Start the server once.
- Configure (optional):
plugins/NpcPlugin/config.yml
plugins/NpcPlugin/lang/<language>/*.json
- Restart or run
/npc reload.
Quick Start
1) Create an NPC
2) Enable edit-mode
While edit-mode is enabled:
- Interact with an NPC to open its editor GUI.
If the NPC is not editable, you’ll get a message like This NPC is not editable!.
3) Configure NPC options in the GUI
The GUI lets you change things like:
- Name
- Skin (player name / UUID / local
.png / URL / .yml file / PlaceholderAPI)
- “Use Player Skin” (per-player skin)
- Equipment slots
- Visibility / enabled state
- Tab list visibility
- Hide nametag
- Pose
- Skin parts
- Glowing + color
- Look-at-player radius / interval
- Scale
- Teleport to NPC / teleport NPC to you
- Delete NPC
- Goals
For detailed information on setting skins, see the Skins guide.
Click Actions
Click Actions (Left / Right / Both)
In the NPC GUI go to Click Action.
You can configure actions separately for:
- Left click
- Right click
- Both (combined)
You can create an action chain by adding multiple actions.
Action editing tips
- Remove an action: middle-click an existing action.
- Add actions quickly: shift-click an action type to append it.
- Reorder / insert: pick up an action type onto your cursor and click a slot.
Common action types
Command
Executes a command.
- Input can be with or without leading
/ (the plugin stores it as /<command>).
- Placeholders supported:
{player} / %player% / <player>
{player_name} / %player_name% / <player_name>
- Supports variables/expressions via the plugin action system.
- There is optional syntax validation.
Example:
warp spawn
server hub
msg {player} Welcome!
Server (BungeeCord)
Sends the player to another BungeeCord server.
Example server name:
Wait
Pauses the chain before continuing.
You can switch between two modes in the editor:
Time mode
- Left/Right click to adjust the time
- Shift+Left/Shift+Right for bigger steps
- Range is clamped (min
0.05s, max 600s)
Command mode
Instead of waiting for time, the chain waits until an admin triggers it:
Wait stores a name (string)
- The chain continues only after:
/npc wait <player> <name> [values...]
If [values...] are provided, they are exposed to the next actions as local variables:
<name>-0, <name>-1, ... (numeric values; invalid numbers become 0.0)
This is useful to wait for external systems (minigames, scripted events, etc.).
Note (Path)
The Path action also uses the same wait mechanism internally: the chain continues when the NPC finishes walking.
Path
Makes the NPC walk along a saved path.
- You pick a path name (must exist; same world) + a speed (
0.01–1.0).
- Optional flags:
- For all (everyone sees the NPC walking)
- Change real location (updates the NPC's real location while walking)
Animation
Plays an animation on the NPC for the clicking player.
- Left click: next animation
- Right click: previous animation
SetVariable
Sets a numeric variable.
- Type:
- Local (stored per-player)
- Instance (stored on the NPC)
- Global (stored server-wide; persisted in
global-variables.yml)
- Name must match
^[a-zA-Z_][a-zA-Z0-9_-]*$
- Value is an expression
If the value is missing, the action does nothing (admins get a warning).
Condition
Runs a sub-chain only if its expression is true.
- You edit the sub-chain like a normal action list
- The condition expression is edited via the "value" item
Loop
Repeats a sub-chain.
There are two loop types:
While-loop
- Repeats while the expression is
true
For-loop
- Repeats with an integer loop index
- Configurable values:
- Start (optional; default
0)
- End (required)
- Step (optional; default
1)
You can change the loop type by Shift-clicking the action.
Npc
Opens a special editor that lets you apply NPC options as an action.
This is mainly used to change how the NPC looks/behaves for:
- Only the clicking player (per-player override)
- Everyone (global)
Two flags exist:
- Change globally: applies the configured options to the NPC’s global options
- Reset to default: removes per-player overrides and resets to the NPC’s defaults
Stop
Stops the current chain immediately (and stops nested chains too).
Run-on-show
In the action editor you can enable Run on show.
If enabled, the chain triggers when the NPC is shown to a player (not only when clicked).
Path System Guide
Path System Guide
Paths are shared and stored in:
plugins/NpcPlugin/paths.yml
Create a path from points
-
Add points at your current location:
Or add at a specific index:
/npc path point add <index>
-
List points:
/npc path point list [page]
-
Visualize / toggle visualization of current points:
/npc path visualize points
-
Create the path:
/npc path create <name> (opens GUI with base navigation options)
/npc path create <name> default (creates with default preset)
/npc path create <name> natural (creates with natural preset)
/npc path create <name> global (creates with global preset)
/npc path create <name> gui (opens GUI with base navigation options)
You can also add specific navigation options after the preset or gui subcommand:
/npc path create <name> default --option value ...
/npc path create <name> gui --option value ...
After creation you can visualize it:
/npc path visualize <name>
Record a path by walking
-
Start recording:
/npc path record start [snap-to-grid]
The optional snap-to-grid parameter snaps recorded points to the nearest block center.
-
Walk the route.
-
Stop recording:
-
Create the path:
Edit an existing path
This loads the saved path’s waypoints into the point list so you can remove/add points and re-create it.
List / delete / test paths
/npc path list [page]
/npc path delete <name>
/npc path test <name> [speed]
Goals Guide
Goals Guide
Goals give NPCs autonomous behavior. Configure them via the NPC editor GUI.
Available Goals
- Walk to Location: NPC walks to a specific location using pathfinding
- Walk Path: NPC walks along a saved path
- Follow Entity: NPC follows a target entity by UUID
- Attack Entity: NPC attacks nearby matching entities
- Look Around: NPC looks around randomly (idle behavior)
- Wait: NPC waits for a specified duration
- Wander: NPC wanders randomly within a radius
Attack Entity Predicates
Target entities using expressions with variables:
$distance - Distance to NPC
$entity.x, $entity.y, $entity.z - Entity position
$entity.health - Entity health
$npc.x, $npc.y, $npc.z - NPC position
[if entity @s[type=zombie]] - Command-based entity type check
Example predicates:
$distance < 5 - Only attack within 5 blocks
$entity.health < 10 - Attack low health entities
$distance < 10 && $entity.health > 5 - Combined conditions
For more details, see the full Goals documentation.
Expression Parser Guide
Expression Parser Guide
Use mathematical expressions in click actions, goal conditions, and variable calculations.
Supported Elements
Operators: +, -, *, /, ^ (power), &&, ||, !, ==, !=, <, >, <=, >=
Math Functions: sin(), cos(), tan(), sqrt(), log(), exp(), ceil(), floor(), round(), trunc(), abs()
Constants: PI, E
Variables
$varName - Auto-resolve (local → instance → global)
$global.varName - Server-wide variable
$instance.varName - NPC-specific variable
$local.varName - Player-specific variable
Special Variables:
$self.rightClick / $self.leftClick - Click type (1 or 0)
$self.sneaking, $self.flying, $self.op - Player state
$loop.index - Loop iteration index
Command Execution
(/command) - Execute command inside expression
/command - Standalone command execution
Examples:
2 + (/count players) - Use command result in calculation
$global.score + 1 - Increment variable
($entity.health < 10) * 5 - Conditional value
For the full syntax reference, see the Expression Parser documentation.
Commands
Commands
Core
/npc create [options] (options are defined in key-value pairs like --name "Test")
/npc copy <npc>
/npc edit (toggle edit-mode)
/npc edit <npc> (edit specific NPC)
/npc edit <npc> <options> (edit specific NPC option, which are defined in key-value pairs like --name "Test")
/npc delete <npc> [force] (delete specific NPC)
/npc list (opens NPC list GUI)
/npc tp <npc> [location] [rotation]
/npc tphere <npc>
/npc reload [npc]
/npc version
/npc update (checks for a new plugin version)
/npc cancel <npc> (cancels NPC click action)
/npc cancel all (cancels all NPC click actions)
/npc load <npc> (loads NPC from storage)
/npc load <npc> <location> (loads NPC at specific location)
/npc load <npc> <location> <rotation> (loads NPC at specific location with rotation)
/npc click <npc> (executes NPC click action on self)
/npc click <npc> <target> (executes NPC click action on target)
/npc move <npc> turn <degree> (rotates NPC by relative degrees)
/npc move <npc> <flag> [steps] [speed] (moves NPC using direction flags)
/npc help (shows help message)
/npc issue (shows issue tracker link)
/npc wiki (shows wiki link)
/npc message <player> <message> (Can be used in command actions to send a message which also allows '&' color codes)
/npc tag <npc> add <tag> (adds a tag to an NPC)
/npc tag <npc> remove <tag> (removes a tag from an NPC)
/npc tag <npc> list (lists all tags of an NPC)
/npc animation <animation> [targets] (plays an animation on the specified targets)
/npc languages reload (reloads all language files from disk)
/npc languages restore [language](restores default language files from resources, overwrites all 'official' language files)
Config
/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
Exceptions (startup load failures)
/npc exceptions [page]
/npc exceptions show <name>
/npc exceptions delete <name>
Paths
All path commands are under:
Main subcommands:
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] (starts recording path points while walking)
record stop (stops recording)
test <name> [speed]
edit <name> (loads a saved path's waypoints for editing)
Movement
All movement commands are under:
Main subcommands:
record start [player] (starts recording movement)
record stop [player] <name> [overwrite] (stops recording and saves)
record stop <name> [overwrite] (stops recording and saves for self)
record (gives recording item)
list [page] (lists all movement recordings with pagination)
details <name> (shows detailed information about a recording)
delete <name> (deletes a movement recording)
play <name> [speed] (plays a recording on self)
play <name> <target> [speed] (plays a recording on target)
Execute Context
Execution modifiers allowing dynamic target selection and context redirection for NPC subcommands:
/npc execute as <selector> do <command> (executes targeted NPC command as the selected NPC context)
/npc execute at <selector> do <command> (executes targeting location and orientation of selected NPC)
/npc execute positioned as <selector> do <command> (executes at the position of selected NPC)
/npc execute rotated as <selector> do <command> (executes with the rotation angles of selected NPC)
NPC Selector System
The target selector system (NpcSelector) parses entity target syntax matching standard Minecraft target selectors to query registered NPCs:
- Target Specifiers:
@a – Matches all loaded/registered NPCs.
@s – Matches the self-referential NPC currently targeted inside an active /npc execute context.
@n / @p – Targets the single nearest NPC relative to the command source origin.
@r – Selects a random NPC candidate.
<name|uuid> – Directly queries an NPC by display name or unique ID.
- Filter Arguments (
[...]):
tag=<value> / tag=!<value> – Filters NPCs possessing (or missing) specific assigned tags.
nbt={<key>:<value>} – Evaluates target options against specific internal NpcOption states or custom stored data.
distance=<min>..<max> – Constrains candidates based on Euclidean distance boundaries from the execution origin.
limit=<count> – Restricts maximum return results.
Wait trigger
Used with the Wait click action (command mode):
/npc wait <player> <name> [values...]
Variables
Manage server-wide global variables via commands:
/npc variable list - List all global variables
/npc variable get <name> - Get a variable's value
/npc variable set <name> <expression> - Set a variable (supports expressions)
/npc variable delete <name> - Delete a variable
Variables can also be managed via the SetVariable click action and used in expressions throughout the plugin.
Configuration
Configuration (config.yml)
look-at-update-interval:
- Time in ticks between “look at player” updates.
avoid-command-check:
- If
true, commands added to NPC actions will not be strictly validated.
debug:
- Enables extra debug logging.
input-time:
- Conversation timeout in seconds (if
< 0, no timeout).
auto-update:
- Automatically updates NPCs after option changes.
placeholder-timer:
- Time in ticks between placeholder refreshes.
check-path:
- Checks if a path is valid (solid block beneath the path)
walking-viewer-distance:
- Distance in blocks at which players can see NPCs walking
precise-sleeping-hitbox:
- If true, uses precise hitbox detection for sleeping NPCs
load-chunks-on-path:
- If true, loads chunks on the path of the NPCs
pathfinding-factory:
- Pathfinder factory to use. Options are ASTAR and BOUNDING_BOX <gridStep> (e.g. "BOUNDING_BOX 0.5"). <gridStep> must be between 0.01 and 1.0.
- BOUNDING_BOX is based on Theta* and provides more precise collision detection, e.g. for blocks that are solid but can still be walked through (like a shelf).
pathfinding-passable-override:
- List of block types that should be considered passable for pathfinding even though they are normally solid (like a shelf).
- This is only editable via the config.yml file and not via the
/npc config command!
Troubleshooting
Troubleshooting
- “This plugin does not support Paper servers!”
- You are running the Spigot build on a Paper server. Install the Paper build instead.
- Server action does nothing
- Ensure BungeeCord is set up and the server names match your proxy configuration.
- Can’t open the editor GUI
- Make sure you:
- Have
npc.admin
- Enabled edit-mode via
/npc edit
- The NPC is marked as editable
Skript Support
To use this plugin’s events in Skript, you need Skript-Reflect
Basic usage
import:
de.eisi05.npc.api.events.<EventName>
on <EventName>:
# your code here
Replace <EventName> with one of the events listed below.
Available Events
NpcHideEvent
Triggered after an NPC is hidden from a player.
Available values:
event.getNpc() → NPC
event.getPlayer() → Player
NpcInteractEvent
Triggered when a player interacts with an NPC.
Available values:
event.getNpc() → NPC
event.getPlayer() → Player
event.getAction() → ClickActionType (LEFT / RIGHT)
event.isCancelled() → boolean
NpcPostShowEvent
Called after an NPC is fully visible to a player.
Note: This event cannot be cancelled.
Available values:
event.getNpc() → NPC
event.getPlayer() → Player
event.wasViewer() → boolean (true if the player already saw this NPC before)
NpcPreShowEvent
Called before an NPC is shown to a player.
Note: This event can be cancelled.
Available values:
event.getNpc() → NPC
event.getPlayer() → Player
event.wasViewer() → boolean
event.isCancelled() → boolean
NpcStartWalkingEvent
Called before an NPC starts walking along a path.
Available values:
event.getNpc() → NPC
event.getPath() → Path
event.getWalkSpeed() → double
event.isChangeRealLocation() → boolean (whether real NPC location will update)
event.isCancelled() → boolean
NpcStopWalkingEvent
Called after an NPC stops walking.
Available values:
event.getNpc() → NPC
event.getWalkingResult() → WalkingResult (SUCCESS / CANCELLED)
event.changeRealLocation() → boolean (whether final position should be applied)
Example
You can also directly access Java methods inside Skript like this:
import:
de.eisi05.npc.api.events.NpcInteractEvent
on NpcInteractEvent:
set {_player} to event.getPlayer()
send "Triggered!" to {_player}
Additional Resources
For more information about Skript-Reflect syntax and features, visit:
bStats
评论 0
登录后参与评分
还没有评论,来抢沙发吧