Skip to content

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 变量声明

将载荷类的属性映射为脚本内的变量名。

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 直接复用事件对象

getter 查找优先级

  1. getXxx() — 标准 Java Bean getter
  2. isXxx() — boolean getter
  3. xxx() — Record 风格 accessor

flow 流程节点

flow 是一个有序列表,引擎按顺序执行每个节点。共支持 7 种节点类型:

类型 YAML 触发键 说明
CHECK check 条件判断
ACTION action 或动态推断 调用已注册动作
RETURN return 返回值并终止
SWITCH switch 多分支选择
MATH math 数学表达式求值
ANY any OR 复合条件
ALL all AND 复合条件

节点类型通过短语法自动推断,无需显式声明 type 字段。


check 条件判断

# 基本格式
- 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 字段支持的类型

# 数值
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 动作调用

# 标准格式
- 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 否 将返回值存入此变量名

WarriorView 内置动作

动作 参数 说明
showIndicator [target, source, value, tag] 触发指示器显示
  • target — 受击实体(LivingEntity)
  • source — 攻击来源实体(Entity)
  • value — 数值(double)
  • tag — 指示器标签,对应 indicator/*.yml 中的 tag 名称

第三方插件可通过 API 注册自定义动作,详见 WarriorView API。


return 返回值

支持 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 多分支

- switch: weaponType
  cases:
    SWORD:
      - action: "log"
        args: ["剑类武器"]
    BOW:
      - action: "log"
        args: ["弓类武器"]
    DAGGER:
      - action: "log"
        args: ["匕首类武器"]
字段 类型 必填 说明
switch / variable String 是 用于分支匹配的变量
cases Map 是 分支映射,key 为匹配值,value 为动作列表

math 数学运算

- math: "{damage} * 1.5 + {bonus}"
  store: "finalDamage"
字段 类型 必填 说明
math / expr String 是 数学表达式(支持 {变量} 引用)
store String 是 结果存入此变量名(double 类型)

完整的运算符、内置函数、优先级和使用场景 → 数学表达式


any / all 复合条件

# 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 窄化

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

完整示例

示例 1:伤害指示器(实际默认配置)

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}"]

示例 2:复合条件与失败回退

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"]

Clone this wiki locally