表达式

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

常见使用场景

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

表达式变量

变量由调用模块注入。不同场景可用变量不同，例如：

场景	可能变量
强化	%star%、%level%、%base_cost%、%success_rate%
技能	%skill_level%、%cooldown%、%resource%
锻造	%quality%、%material_score%、%recipe%
条件	%player_level%、%value%、%amount%

上表列出了常见变量示例，各模块实际注入的变量名请参阅对应模块文档。

变量写法统一为 %name%。数值表达式中，变量必须能解析为数字；文本模板中，变量会被转成字符串。

数值表达式

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)

数值比较会尝试把左右两侧都当作数值表达式求值；如果无法作为数值求值，则仅支持字符串 == / != 比较。字符串建议加引号。

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

actions:
  - '@if=%phase%=="success" sendmessage text="成功阶段"'

文本模板与字符串配置

文本求值用于把变量插入到字符串中，也可把数值/布尔配置转成文本。

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

文本变量缺失时会替换为空字符串，并在详细结果中记录问题。数字会尽量格式化为简洁文本：整数显示为整数，小数最多保留两位显示。

对象形式也可用于字符串配置：

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

等价类型别名：

类型	别名
字符串	string、str、text
布尔	boolean、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'
  expression: '%base% + %bonus%'

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

支持的随机数值类型

类型	别名	必填/常用字段	说明
constant	const、fixed	value	固定值；value 可继续是表达式或随机配置。
range	-	value 或 min + max	如果有 value 则求 value；否则等同 uniform。
uniform	-	min、max	在 [min,max] 之间均匀随机。
gaussian	normal	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	-	expression 或 formula	使用数值表达式计算。

示例：

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、values、options、texts、value。

控制字段：

字段	别名	默认	说明
count	rolls、times、random_times、amount	1	抽取条数。可写数值表达式或随机数值配置。
allow_duplicates	allow_duplicate、allow_repeat、allow_repeats、repeat、repeatable、with_replacement	false	是否允许重复抽取同一个候选。
separator	joiner	换行	多条结果连接符。

示例：

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'
  values:
    - '+%level% 攻击力'
    - '+%level% 防御力'
    - '+%level% 生命值'

在 YAML 中书写表达式的建议

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