表达式

表达式在配置里算出一个数值, 一段文本或一个真假结果, 让费用, 概率, 等级成长, 条件判断不用写死

常见使用场景

• 强化费用: 随星级增加而提高
• 技能消耗: 随技能等级变化
• 锻造品质概率: 受材料品质或玩家属性影响
• 条件判断: 等级, 属性, 资源是否达到要求
• 伤害或奖励: 根据变量计算最终数值
• 随机配置: 在区间, 正态分布, 三角分布等模型中抽取数值
• 随机文本: 从多个候选文案中抽取一条或多条

表达式变量

先记住: 变量完全由调用模块和当前字段注入, CoreLib 不会为所有公式自动提供一组全局业务变量. 同一插件内的成本, 成功率, 属性值, Action 和消息模板也可能使用不同上下文

想知道某个字段能用哪些变量, 查 变量, 表达式与占位符上下文矩阵; 它按 10 个插件的生产 parser, service, model 和 PlaceholderAPI expansion 列出真实变量, 单位与作用域限制

变量写法统一为 %name%. 你写数值表达式时, 变量必须能解析为数字; 写文本模板时, 变量会被转成字符串. 注意不要把内部模板变量或 PlaceholderAPI 占位符直接当作公式变量使用

数值表达式

CoreLib 使用 exp4j 计算数值表达式, 除它自带的运算外还额外注册了一组常用函数

支持的运算符与函数

类型	支持内容
基础运算	+, -, *, /, %, ^, 括号
单参数函数	ceil(x), floor(x), round(x), log10(x)
双参数函数	min(a,b), max(a,b), pow(a,b)

示例:

economy:
  enabled: true
  base_cost: 100
  cost_formula: '100 + %star% * 50'

quality:
  chance_formula: 'min(0.95, 0.05 + %material_score% * 0.001)'

reward:
  amount_formula: 'ceil(pow(%level%, 1.5) * 10)'

数值表达式限制

为了防止配置误用和表达式注入, CoreLib 给表达式定了几条硬约束:

规则	限制值	说明
最大长度	256 字符	一个表达式最长 256 字符, 超了就直接拒绝解析
最大嵌套深度	10 层	随机配置的嵌套层数, 或者变量一层层往下解析的层数, 最多 10 层
禁止字符	`, $, \	这几个字符不许出现, 防止有人往表达式里塞代码
结果限制	不能是 NaN 或无限值	结果不能是 NaN 或无穷大的值, 否则这次求值算失败

变量替换完成后, 数值表达式里只能出现数字, 空白, 运算符, 括号, 逗号和允许的函数名

遇到变量缺失, 变量转不成数字, 表达式过长或含不支持字符时: 详细求值接口会返回失败原因; 简化求值接口则给一个备用值, 多数情况是 0, 有些接口会改用调用模块自己的默认值

布尔表达式

布尔表达式常出现在这些地方: 条件, 管道的 if 分支, 随机文本开关

布尔字面量

以下值会被识别为 true:

• true
• yes
• y
• on
• 1

以下值会被识别为 false:

• false
• no
• n
• off
• 0

比较与逻辑运算

运算	示例
数值比较	%level% >= 10, %score% < 100
字符串相等	"forge" == "forge", %phase% != "fail"
逻辑与	%level% >= 10 && %money% >= 100
逻辑或	`%rarity% == "rare"
逻辑非	!%locked%, !(%level% < 10)
括号	`(%a% > 0 && %b% > 0)

数值比较会先把左右两侧都当作数值表达式求值; 无法按数值求值时, 就只支持字符串 == / != 比较. 字符串记得加引号

condition:
  entries:
    - type: expression
      expression: '%player_level% >= 20 && %money% >= 1000'

actions:
  - 'if %phase%=="success" [ self | send_message text="成功阶段" ]'

文本模板与字符串配置

文本求值帮你把变量插进字符串, 也可以把数值/布尔配置转成文本

message: '当前等级：%level%，下一次费用：%next_cost%'

文本变量缺失时会被替换成空字符串, 并在详细结果中记录问题. 数字会格式化成简洁文本: 整数按整数显示, 小数最多保留两位

字符串配置也可以写成对象形式:

name:
  type: string
  value: 'Lv.%level% 强化石'

注意 type 只认这两个字面量, 没有别名:

类型	可写值
字符串	string
布尔	boolean

写成 str, text, bool, flag 都不会被识别, 配置会落到解析失败分支

随机数值配置

除了普通公式, 你还可以把数值字段写成随机配置对象. 随机配置可以直接作为变量, 也可以作为字段值被 evaluateRandomConfig 求值

简写区间

在字符串里用 min~max 表示均匀随机:

reward_amount: '10 ~ 20'

min 和 max 本身也可以写成表达式:

reward_amount: '%level% * 5 ~ %level% * 8'

通用字段

随机配置对象支持声明局部变量:

amount:
  type: expression
  variables:
    base: 100
    bonus: '%level% * 5'
  value: '%base% + %bonus%'

variables 会覆盖或补充外部变量, 并参与当前配置及其子配置的求值

支持的随机数值类型

类型	别名	必填/常用字段	说明
constant	-	value	固定值; value 可继续是表达式或随机配置
range	-	value 或 min + max	填了 value 就按 value 求值, 没填就和 uniform 一样
uniform	-	min, max	在 [min,max] 之间均匀随机
gaussian	-	mean, std_dev, min, max, max_attempts 均可选	正态分布. mean 没写时, 有 min/max 就取区间中点, 没有就是 0; std_dev 没写时, 有 min/max 就是区间长度除以 6, 没有就是 1
skew_normal	-	同 gaussian, 另有 skewness	偏态正态分布. skewness 默认 0
triangle	-	mode, deviation 可选	三角分布. mode 默认 0, deviation 默认 1
expression	-	value	使用数值表达式计算

示例:

bonus:
  type: uniform
  min: 5
  max: '10 + %level%'

quality_score:
  type: gaussian
  min: 0
  max: 100
  mean: '50 + %material_quality% * 5'
  std_dev: 12
  max_attempts: 128

crit_bonus:
  type: skew_normal
  min: 0
  max: 50
  mean: 10
  std_dev: 8
  skewness: 2

shake_offset:
  type: triangle
  mode: 0
  deviation: 0.3

没写 type 时, 按下面的顺序推断:

1. 有 value: 按 value 求值
2. 同时有 min 与 max: 按 uniform 处理
3. 否则返回"不支持的数值配置"

注意 expression 字段只在 type: expression 时被读取; 不写 type 时单独写 expression: 不会被推断为数值配置

随机文本配置

文本配置能从多个候选里随机抽文本, 支持这些类型:

• random_text
• random_text_lines
• random_lines
• random_line
• text_lines

候选写在 lines 字段:

控制字段:

字段	别名	默认	说明
count	-	1	要抽几条. 可以写数值表达式或者随机数值配置
allow_duplicates	-	false	抽的时候允不允许重复抽到同一个候选
separator	-	换行	抽到多条结果时, 拼起来用的连接符

示例:

message:
  type: random_text
  count: 1
  lines:
    - '<green>锻造成功！</green>'
    - '<gold>火花四溅，武器成型。</gold>'
    - '<aqua>%player_name% 完成了一次杰作。</aqua>'

lore_bonus:
  type: random_lines
  count: 2
  allow_duplicates: false
  separator: '\n'
  lines:
    - '+%level% 攻击力'
    - '+%level% 防御力'
    - '+%level% 生命值'

随机字符配置

除了随机文本, 文本配置还支持三族随机字符类型. 它们共用 count, allow_duplicates, separator 三个控制字段, 含义与随机文本一致

类型	别名	候选字段
random_char	random_chars, char_random, chars_random	chars
weighted_random_char	weighted_random_chars, weighted_char, weighted_chars, weighted_char_random	chars
conditional_char	condition_char, case_char, if_char	cases

chars 没写时默认用 abcdefghijklmnopqrstuvwxyz

suffix:
  type: random_char
  count: 3
  chars: 'ABCDEF'

conditional_char 会按顺序求值 cases 中每一项的 condition, 命中第一个为真的项就返回它的 value; 全部不命中时返回 fallback, 没写 fallback 则返回空串

grade_mark:
  type: conditional_char
  cases:
    - condition: '%level% >= 50'
      value: 'S'
    - condition: '%level% >= 20'
      value: 'A'
  fallback: 'B'

数量配置 (quantity)

费用, 概率, 容量, 经验这类"需要按情况算出一个数"的字段, 除了普通公式和随机配置, 还可以写成数量配置对象, 支持固定值, 公式, 查找表三种类型

固定值

quantity: 100

想写全的话, 等价的完整写法是:

quantity:
  type: fixed
  value: 100

公式

quantity:
  type: formula
  expression: "player_level * 10 + 50"

查找表

按某个变量的整数取值查表, 表里查不到时取 default:

quantity:
  type: lookup_table
  key: player_level
  default: 0
  table:
    1: 10
    2: 20
    5: 50

字段	类型	必填	默认值	取值范围	说明
type	string	否	fixed	fixed, formula, lookup_table (别名 table)	数量配置的类型; 写了个不认识的类型就按 fixed 处理
value	number	否	0	数值或数值表达式	fixed 类型下要取的值
expression	string	否	"0"	CoreLib 数值表达式	formula 类型下要算的公式
key	string	否	player_level	变量名	lookup_table 按哪个变量去查表
default	number	否	0	数值	lookup_table 在表里查不到时用的值
table	section	否	空	整数键到数值的映射	整数键到数值的对照表; 键不是整数的条目会被跳过

取值规则

写法不合法时它不会报错, 而是按下面几种情况处理:

• 直接写数值或数值字符串 → 视为 fixed;
• 写配置节 → 按 type 解析, type 不认识时按 fixed 处理, 取 value;
• 留空或不写 → fixed(0)

Cron 表达式

cron 字段用 6 段 Quartz 格式, 按服务器系统的真实时间触发, 跟游戏里的节奏无关:

秒 分 时 日(月) 月 日(周)

支持 *, ? (等价于 *), 固定值, , 枚举, - 区间, / 步长

"0 0 19 * * ?"        每天 19:00:00
"0 30 8 ? * MON-FRI"  工作日 08:30:00
"0 0/15 * * * *"      每 15 分钟

注意: 若 4 年内找不到下一次触发时间, 该任务不会被调度. 表达式非法时对应任务被跳过并在控制台留下告警, 插件其余部分不受影响

使用 cron 的位置: EmakiMobs 的 type: autonomous + trigger: cron 刷新规则, 以及 EmakiSkills 的被动技能定时触发

在 YAML 中书写表达式的建议

• 对包含 >, <, :, {}, %, #, &, * 的表达式加引号
• 概率字段要确认调用模块期望的是 0~1 还是 0~100; 管道里的 chance 检查明确支持 0.25 与 25% 这两种写法
• 金钱, 数量, 等级这类结果建议在公式中用 max(0, value) 限制最小值
• 复杂公式先在纸面或计算器中验证, 再写入配置
• 玩家可影响变量时, 要考虑极端值, 负数和刷资源问题
• 随机配置可以嵌套, 但最大嵌套深度为 10