Repository navigation
Script Engine
Noogear edited this page Mar 8, 2026
·
5 revisions
GloomLib Script Module — 高性能 YAML 脚本引擎,将事件处理逻辑以声明式配置驱动。
数学表达式完整语法(运算符、内置函数、使用场景)→ 数学表达式
id: "my-script" # 脚本标识符(可选,默认 AnonymousScript)
event: "com.example.MyEvent" # 必填,事件/载荷类的全限定名
priority: 0 # 可选,事件优先级(整数,默认 0)
ignore-cancelled: false # 可选,指定 true 时已取消事件不触发(默认 true)
variables:
# ...
flow:
# ...| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
id |
String | 否 | AnonymousScript |
脚本唯一标识,用于日志和错误追踪 |
event |
String | 是 | — | 载荷类全限定名 |
priority |
Integer | 否 | 0 |
事件监听优先级 |
ignore-cancelled |
boolean | 否 | true |
true 时已被其他插件取消的事件不会触发脚本 |
variables |
Map | 否 | {} |
变量声明映射 |
flow |
List | 否 | [] |
流程节点列表 |
将载荷类的属性映射为脚本内的变量名。
variables:
# 简单属性:映射 event.getDamage()
damage: "damage"
# 链式属性:映射 event.getEntity().getName()
entityName: "entity.name"
# 集合索引:映射 event.getPlayer().getInventory().get(0)
firstItem: "player.inventory[0]"
# Map 索引:映射 event.getMetadata().get("key")
metaValue: "metadata[key]"
quotedKey: "metadata['damage_all']"
# payload 别名:直接引用事件对象本身
event: "$self"| 语法 | 示例 | 解析方式 |
|---|---|---|
| 简单属性 | damage |
调用 getDamage() 或 damage()
|
| 链式属性 | entity.name |
依次调用 getEntity() → getName()
|
| List 索引 | inventory[0] |
调用 getInventory() → List.get(0)
|
| Map 索引 | metadata[key] |
调用 getMetadata() → Map.get("key")
|
| payload 别名 | $self |
直接复用事件对象 |
-
getXxx()— 标准 Java Bean getter -
isXxx()— boolean getter -
xxx()— Record 风格 accessor
flow 是一个有序列表,引擎按顺序执行每个节点。共支持 7 种节点类型:
| 类型 | YAML 触发键 | 说明 |
|---|---|---|
| CHECK | check |
条件判断 |
| ACTION |
action 或动态推断 |
调用已注册动作 |
| RETURN | return |
返回值并终止 |
| SWITCH | switch |
多分支选择 |
| MATH | math |
数学表达式求值 |
| ANY | any |
OR 复合条件 |
| ALL | all |
AND 复合条件 |
节点类型通过短语法自动推断,无需显式声明 type 字段。
# 基本格式
- check: <variable>
op: "<operator>"
value: <value>
# 带失败动作
- check: damage
op: ">"
value: 100
on_fail:
- action: "log"
args: ["条件不满足"]| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
check / variable
|
String | 是 | 检查的变量名 |
op |
String | 是 | 操作符(支持 ! 前缀取反) |
value |
any | 视操作符 | 比较目标值 |
on_fail |
List | 否 | 条件不满足时执行的动作列表 |
# 数值
value: 100
value: 3.14
# 字符串
value: "sword"
# 布尔
value: true
# 列表(用于 in / between 操作符)
value: ["sword", "bow", "axe"] # in:候选值列表
value: [10.0, 50.0] # between:[下界, 上界] 闭区间
# 变量引用
value: "{maxHp}"
# 数学表达式(数值操作符时自动解析)
value: "{maxHp} * 0.5"
# 类名(用于 instanceof)
value: "com.example.PlayerEntity"# 标准格式
- action: "showIndicator"
args: ["{target}", "{source}", "{value}", "CRITICAL"]
# 短语法(动态推断)
# 当节点中不含保留字段(check/switch/return/any/all/math)时,
# 引擎将第一个非保留字段视为 action 名,其值视为 args
- showIndicator: ["{target}", "{source}", "{value}", "{cause.name}"]
# 捕获返回值
- action: "someAction"
args: ["arg1"]
store: "result"| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
action |
String | 是 | 已注册的动作名 |
args |
List | 否 | 参数列表,支持 {变量} 模板插值 |
store |
String | 否 | 将返回值存入此变量名 |
| 动作 | 参数 | 说明 |
|---|---|---|
showIndicator |
[target, source, value, tag] |
触发指示器显示 |
-
target— 受击实体(LivingEntity) -
source— 攻击来源实体(Entity) -
value— 数值(double) -
tag— 指示器标签,对应 indicator/*.yml 中的 tag 名称
第三方插件可通过 API 注册自定义动作,详见 WarriorView API。
支持 5 种返回路径:
# 1. 空返回(返回 null)
- return
# 2. 变量返回
- return: "{damage}"
# 3. 模板字符串返回
- return: "HP:{hp} 伤害:{damage}"
# 4. 字面量返回
- return: 42
- return: true
- return: "固定文本"
# 5. 集合字面量返回
- return: [1, "{hp}", "fixed", true]- switch: weaponType
cases:
SWORD:
- action: "log"
args: ["剑类武器"]
BOW:
- action: "log"
args: ["弓类武器"]
DAGGER:
- action: "log"
args: ["匕首类武器"]| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
switch / variable
|
String | 是 | 用于分支匹配的变量 |
cases |
Map | 是 | 分支映射,key 为匹配值,value 为动作列表 |
- math: "{damage} * 1.5 + {bonus}"
store: "finalDamage"| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
math / expr
|
String | 是 | 数学表达式(支持 {变量} 引用) |
store |
String | 是 | 结果存入此变量名(double 类型) |
完整的运算符、内置函数、优先级和使用场景 → 数学表达式
# ANY(OR 短路):任一子条件成立即通过
- any:
- check: damage
op: ">"
value: 50
- check: weaponName
op: "=="
value: "sword"
on_fail:
- action: "log"
args: ["所有条件都不满足"]
# ALL(AND 短路):全部子条件成立才通过
- all:
- check: damage
op: ">"
value: 10
- check: weaponName
op: "=="
value: "sword"
# 嵌套:ANY 内嵌 ALL,ALL 内嵌 ANY
- any:
- all:
- check: damage
op: ">"
value: 100
- check: rank
op: ">="
value: 5
- check: weaponName
op: "=="
value: "legendary_sword"| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
any / all
|
List | 是 | 子条件列表 |
on_fail |
List | 否 | 条件不满足时执行的动作列表 |
所有操作符前均可加 ! 前缀取反(如 !null、!contains、!==)。多重 ! 自动规范化。
| 操作符 | 分类 | 说明 |
|---|---|---|
null |
空值检测 | 检查变量是否为 null |
instanceof |
类型检测 | 检查是否为指定类的实例,成功后自动窄化类型 |
== |
相等 | 相等比较 |
!= |
相等 | 不等比较 |
> |
数值 | 大于 |
>= |
数值 | 大于等于 |
< |
数值 | 小于 |
<= |
数值 | 小于等于 |
between |
数值 | 闭区间范围检查,value 为 [low, high]
|
starts_with |
字符串 | 前缀匹配 |
ends_with |
字符串 | 后缀匹配 |
matches |
字符串 | Java 正则全匹配 |
contains |
成员 | 字符串包含 / 集合成员检查 |
in |
成员 | 检查变量值是否在给定列表中 |
引擎内置常见拼写错误的自动提示:
| 错误拼写 | 建议修正 |
|---|---|
startsWith, startswith, start_with
|
starts_with |
endsWith, endswith, end_with
|
ends_with |
match, regex
|
matches |
include, includes, has
|
contains |
eq, is, equal, equals
|
== |
ne, neq, not
|
!= |
gt / lt / gte / lte
|
> / < / >= / <=
|
instanceof 检查成功后,变量类型自动窄化为目标类,后续节点可直接访问子类属性:
variables:
entity: "entity"
flow:
- check: entity
op: "instanceof"
value: "org.bukkit.entity.Player"
# 窄化后可直接访问 Player 独有属性
- action: "log"
args: ["玩家名: {entity.playerName}"]使用 {变量名} 语法在字符串中插入变量值。
# 单变量引用
args: ["{damage}"]
# 多变量模板
args: ["玩家 {playerName} 受到 {damage} 点伤害"]
# 点链引用
args: ["{entity.name}"]
# return 中使用模板
- return: "HP:{hp} DMG:{damage}"属性路径支持多级嵌套:
player.inventory[0].amount
│ │ │ └── getAmount() → int
│ │ └──────── List.get(0) → ItemStack
│ └─────────────── getInventory() → List<ItemStack>
└─────────────────────── getPlayer() → Player
| 类型 | 语法 | 说明 |
|---|---|---|
| MethodAccessor | property |
标准 getter 调用 |
| ListAccessor | list[index] |
List.get(int) 调用 |
| MapAccessor | map[key] |
Map.get(String) 调用,支持引号包裹 key |
id: "damage-indicator"
event: "org.bukkit.event.entity.EntityDamageByEntityEvent"
priority: 3
variables:
target: "entity"
source: "damager"
value: "finalDamage"
cause: "cause"
critical: "critical"
flow:
- check: target
op: "instanceof"
value: "org/bukkit/entity/LivingEntity"
- check: value
op: ">"
value: "0"
- check: critical
op: "!="
value: true
on_fail:
- showIndicator: ["{target}", "{source}", "{value}", "CRITICAL"]
- return
- showIndicator: ["{target}", "{source}", "{value}", "{cause.name}"]id: "pvp-guard"
event: "org.bukkit.event.entity.EntityDamageByEntityEvent"
variables:
damage: "damage"
entity: "entity"
weapon: "damager.itemInMainHand.type.name"
flow:
- all:
- check: damage
op: ">"
value: 5
- check: weapon
op: "in"
value: ["DIAMOND_SWORD", "IRON_SWORD", "NETHERITE_SWORD"]
- check: entity
op: "!null"
on_fail:
- return
- any:
- check: damage
op: "between"
value: [100, 999]
- check: weapon
op: "starts_with"
value: "NETHERITE"
- showIndicator: ["{entity}", "{entity}", "{damage}", "SPECIAL"]