Expressions

Expressions are used to calculate numeric, text, and boolean values in configuration. They are commonly used for costs, chances, scaling, requirements, rewards, and random values.

Variables

Variables are injected by the calling module. Different contexts provide different variables, for example:

Context	Possible variables
Strengthen	%star%, %level%, %base_cost%, %success_rate%
Skills	%skill_level%, %cooldown%, %resource%
Forge	%quality%, %material_score%, %recipe%
Conditions	%player_level%, %value%, %amount%

The table is illustrative. Actual variable names depend on the module and the default configuration.

Variables use the %name% syntax. Numeric expressions require variables to resolve to numbers; text templates convert variables to strings.

Numeric expressions

CoreLib uses exp4j for numeric expressions and registers several helper functions.

Type	Supported syntax
Operators	+, -, *, /, %, ^, parentheses
One-argument functions	ceil(x), floor(x), round(x), log10(x)
Two-argument functions	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)'

Numeric expressions are limited for safety:

• Maximum expression length is 256 characters.
• Maximum nested evaluation depth is 10.
• Backticks, dollar signs, and backslashes are not allowed.
• After variables are resolved, a numeric expression may only contain numbers, whitespace, operators, parentheses, commas, and supported function names.
• Results must not be NaN or infinite.

Boolean expressions

Boolean expressions are used by conditions and action @if.

Truthy literals: true, yes, y, on, 1.

Falsy literals: false, no, n, off, 0.

Operation	Example
Numeric comparison	%level% >= 10, %score% < 100
String equality	"forge" == "forge", %phase% != "fail"
AND	%level% >= 10 && %money% >= 100
OR	`%rarity% == "rare"
NOT	!%locked%, !(%level% < 10)
Parentheses	`(%a% > 0 && %b% > 0)

String comparisons should be quoted to avoid numeric-expression ambiguity.

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

Text templates

Text evaluation replaces %name% variables with string values.

message: 'Current level: %level%, next cost: %next_cost%'

Missing text variables are replaced with an empty string and reported in detailed evaluation results. Numbers are formatted compactly: integer values are shown as integers, and decimals are shortened.

Object syntax is also supported:

name:
  type: string
  value: 'Lv.%level% Stone'

String type aliases: string, str, text.

Boolean type aliases: boolean, bool, flag.

Random numeric configs

Numeric fields can also be written as random config objects.

Range shorthand

A string in the form min~max means uniform random:

reward_amount: '10 ~ 20'

Both sides can be expressions:

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

Local variables

Random config objects may define local variables:

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

variables extend or override outer variables for the current config and its children.

Supported numeric config types

Type	Aliases	Fields	Description
constant	const, fixed	value	Fixed value.
range	-	value or min + max	Uses value if present; otherwise behaves like uniform.
uniform	-	min, max	Uniform random in [min,max].
gaussian	normal	optional mean, std_dev, min, max, max_attempts	Normal distribution. Defaults derive from min/max when possible.
skew_normal	-	same as gaussian, plus skewness	Skew-normal distribution. skewness defaults to 0.
triangle	-	optional mode, deviation	Triangle distribution. Defaults: mode=0, deviation=1.
expression	-	expression or formula	Numeric expression.

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

If type is missing, CoreLib tries to infer the config:

1. value exists: evaluate value.
2. min and max exist: treat as uniform.
3. expression exists: evaluate as an expression.
4. Otherwise the config is unsupported.

Random text configs

Text configs can randomly select one or more text candidates. Supported types:

• random_text
• random_text_lines
• random_lines
• random_line
• text_lines

Candidate fields: lines, values, options, texts, value.

Field	Aliases	Default	Description
count	rolls, times, random_times, amount	1	Number of selected lines. Can be a numeric expression or random numeric config.
allow_duplicates	allow_duplicate, allow_repeat, allow_repeats, repeat, repeatable, with_replacement	false	Whether the same candidate can be selected multiple times.
separator	joiner	newline	Separator used when joining multiple results.

message:
  type: random_text
  count: 1
  lines:
    - '<green>Forge success!</green>'
    - '<gold>Sparks fly as the item takes shape.</gold>'
    - '<aqua>%player_name% created a masterpiece.</aqua>'

YAML tips

• Quote expressions containing >, <, :, {}, %, #, &, or *.
• Verify whether a module expects chance values as 0~1 or 0~100; action @chance supports both decimals and percent notation.
• Clamp money, amount, and level formulas with max(0, value) when negative values are invalid.
• Random configs can nest, but nested evaluation depth is limited to 10.

Troubleshooting

Expression cannot be parsed

Common causes:

• Mismatched parentheses.
• Missing or misspelled variables.
• Unsupported functions.
• Disallowed characters such as backticks, dollar signs, or backslashes.
• Unquoted YAML strings containing special characters.

Result is unexpected

Check the actual variables injected by the current module, integer vs decimal behavior, percentage conventions, clamping or rounding logic, and whether string comparisons are quoted.

Random config always returns 0

Common causes include a misspelled type, missing min / max for uniform, missing expression / formula for expression configs, or nested variables that cannot resolve to numbers.