Skip to content

Combat 2.1d: Compile math expressions once and evaluate with variables - #194

Merged
Travja merged 1 commit into
devfrom
combat-2.1d-compiled-expressions
Nov 15, 2026
Merged

Travja merged 1 commit into
devfrom
combat-2.1d-compiled-expressions

Conversation

@Travja

@Travja Travja commented Nov 15, 2026

Copy link
Copy Markdown
Collaborator

Problem

Evaluator.eval(String, int) takes no variables and parses the string on every call. Underneath, Javaluator's DoubleEvaluator.evaluate(String, context) supports variables but also tokenizes and parses every time. For max(d/5, d - 4*x/max(1, t+8)) that is about 3,400 ns per call (about 4,300 ns in the original measurement), against about 4 ns for the same arithmetic in Java. That is too slow for a combat hot path. Needed by magemonkeystudio/divinity#371, which moves damage formulas into a config file and evaluates them on every hit.

API

CompiledExpression ce = Evaluator.compile("max(d / 5, d - 4 * x / max(1, t + 8))", "d", "x", "t");
double v = ce.eval(def, dmg, toughness);
  • Evaluator.compile(String expression, String... variables) parses once and resolves each variable to its position in the name list. It throws IllegalArgumentException with a one-line message that names the expression and the cause (with the position where the parser has one) for: a syntax error, an unknown variable or function, mismatched brackets, a wrong argument count, and a variable name that is unusable. Names that are a function, a constant, a number, empty, contain whitespace or an operator/bracket/comma, are null or are repeated are rejected.
  • CompiledExpression.eval(double...) is immutable and thread safe. It throws IllegalArgumentException if the number of values differs from the number of names. NaN and infinity are returned as they are.
  • getSource() and getVariableNames() (unmodifiable list).
  • Nothing existing changes. Evaluator.eval(String, int) and all Javaluator classes are untouched. No visibility changes were needed in the bundled Javaluator classes.
  • Allocation: the evaluator is a tree of immutable nodes, evaluated recursively. There is no per-call allocation inside eval. The only array is the varargs array at the call site, which javac creates and the JIT usually scalar-replaces. A caller can pass its own double[] to avoid it.
  • codex-api builds with <release>14</release> on Spigot 1.16.5 API. The new code uses nothing newer than Java 8 APIs and the repo's Lombok (@Getter, @ToString).

How it reuses Javaluator

ExpressionCompiler extends AbstractEvaluator<ExpressionNode>, with DoubleEvaluator.getDefaultParameters(). The values the parser pushes are tree nodes instead of doubles. So the tokenizer, operator precedence and associativity, unary minus guessing, bracket matching, argument-count checks, and the constant, operator and function tables are Javaluator's own, not a second grammar. Only the meaning of each operator and function is written out again (copied branch by branch from DoubleEvaluator). Number literals go through the same NumberFormat(Locale.US) parse as DoubleEvaluator.toValue.

Equivalence guarantee and its limits

For every expression both accept, CompiledExpression returns the same double as DoubleEvaluator.evaluate with a StaticVariableSet (compared with Double.doubleToLongBits). Limits:

  • DoubleEvaluator throws when a function returns NaN (for example sqrt(-1)). The compiled form returns NaN there, as requested. If such an inner NaN is later absorbed (for example round(NaN) is 0), the compiled result is that finite number, while DoubleEvaluator throws. Tests only compare where DoubleEvaluator gives a result.
  • NaN is compared canonically. The sign bit of a NaN depends on how it was produced and is not meaningful.
  • random() gives a new value per call, as in DoubleEvaluator.
  • Quirks of the shared parser are kept on purpose, for example 2^-1 is rejected by both, and ^ is left associative.
  • A new function or operator added to DoubleEvaluator fails at compile time as "unsupported" until the compiled form learns it. Tests iterate over all functions, constants and operators of DoubleEvaluator to catch that.

Benchmark

ExpressionBenchmark (a harness in src/test, run with main, one mode per JVM, 15 rounds, median). JDK 21.0.12, 4 vCPU container, so treat as indicative.

Mode ns/op (median) min max
String evaluation (DoubleEvaluator + StaticVariableSet) 3,444 2,846 4,056
CompiledExpression.eval 34.7 30.7 39.6
Hand-written Java 3.6 3.5 5.5

Compiled is about 99x faster than string evaluation, so the 20x target is met. It is about 10x slower than hand-written Java. A short non-timing pass runs in the build and checks that the three give identical sums.

Tests (mvn -DskipNms -pl codex-api,codex-core -am test, JDK 21, exit 0)

codex-api 355 run (54 before, +301 new), codex-core 13; 0 failures, 0 errors, 0 skipped.

  • Differential: about 140 expressions (operators, precedence, associativity, nested functions, unary minus, constants, exponent, modulo, whitespace, number formats, the formula above) x 12 value sets (zeros, negatives, extremes, infinities, negative zero, NaN), once in declared order and once with variables in a different order. Also a seeded random-expression test (4,000 expressions, more than 40,000 comparisons, asserting the NaN path is exercised).
  • Errors: every failure listed above, with message checks. Also wrong value count, null inputs, and expressions both evaluators reject.
  • Concurrency: 8 threads x 100,000 evaluations on one instance with different values, and concurrent compiles.

Break-it checks (each applied, test suite run, then reverted; the tree is identical to the committed one)

Deliberate bug Result
/ made right associative (parser operator swapped) 9 failures (differential, shifted-order and random tests)
Variable index reversed 190 failures
Binary operands swapped (b - a, b / a, pow(b, a)) 118 failures
Unary minus dropped 45 failures
Variadic functions skip the last argument 40 failures

Decisions for review

  • eval(double...) is the only entry point. If the call-site varargs array shows up in profiles, fixed-arity overloads are easy to add.
  • Variable names with whitespace or numeric names are rejected, which goes beyond the required rules.

Generated by Claude Code

Add Evaluator.compile(String, String...) returning an immutable, thread-safe
CompiledExpression. The expression is parsed once with the bundled Javaluator
grammar and evaluated from a tree without parsing or allocating per call.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FaEyTqc8jf3RR3v7Fz7SHm
@Travja Travja added the build:minor label Nov 15, 2026 — with Claude
@Travja
Travja merged commit 0c57d82 into dev Nov 15, 2026
2 of 3 checks passed
@Travja
Travja deleted the combat-2.1d-compiled-expressions branch November 15, 2026 09:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants