表达式

表达式用于在配置中计算数值、文本或布尔结果。它能让费用、概率、等级成长、条件判断不再写死。

常见使用场景

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

表达式变量

变量完全由调用模块和当前字段注入，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 字符	超过会拒绝解析。
最大嵌套深度	10 层	随机配置嵌套或变量递归解析的最大深度。
禁止字符	`、$、\	防止表达式注入。
结果限制	不能是 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 都不会被识别，配置会落到解析失败分支。

随机数值配置

除普通公式外，CoreLib 还支持把数值字段写成随机配置对象。随机配置可以直接作为变量，也可以作为字段值被 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 时，CoreLib 会尝试按以下顺序推断：

1. 有 value：求 value。
2. 同时有 min 与 max：按 uniform 处理。
3. 有 expression：按表达式处理。
4. 否则返回“不支持的数值配置”。

随机文本配置

文本配置可从多个候选中随机抽取文本。支持类型：

• 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	-	fixed	fixed、formula、lookup_table（别名 table）。
value	-	0	fixed 的取值。
expression	-	"0"	formula 的公式。
key	-	player_level	lookup_table 的查表变量名。
default	-	0	lookup_table 未命中时的取值。
table	-	空	整数键到数值的映射。键不是整数的条目会被跳过。

取值规则

写法不合法时不会报错，而是按以下顺序退化：

• 直接写数值或数值字符串 → 视为 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。