Formula Loader

A mod for developers and datapack creators. Reads custom formulas from JSON files and evaluates them with parameters passed via the in-game command:

``` /formula ``` or Java method.

## Supported Operations

Arithmetic operators: `+`, `-`, ``, `/`, `%` (floor remainder: `a - floor(a / b) b`)

Two-argument formulas: `min(x, y)`, `max(x, y)`, `pow(x, y)`, `log(x, y)` (logarithm base `x` of `y`), `div(x, y)` (floor division toward negative infinity)

One-argument formulas: `round(x)`, `floor(x)`, `ceil(x)`, `abs(x)`, `exp(x)`, `trunc(x)` (truncation toward zero)

Trigonometric formulas: `sin(x)`, `cos(x)`, `tan(x)`, `asin(x)`, `acos(x)`, `atan(x)`

Special — `rem(x, y)`: Returns the remainder `x - floor(x / y) y` and simultaneously writes the quotient `floor(x / y)` back into `x`. Note that if you write `#a = rem(#a, #b)`, the assignment `#a = ...` will overwrite the quotient that `rem` just stored into `#a` with the return value (the remainder), so `#a` ends up holding the remainder, not the quotient.

Unary minus is supported without requiring parentheses: `-3`, `-x`, `-min(a, b)`, `1 + -x` all work.

## Performance

Formulas are pre-compiled at load time into an optimized stack-based bytecode VM. Short formulas (4 or fewer operations) benefit from loop unrolling and super-instruction merging (e.g., variable-variable binary operations become single opcodes). Constant folding is applied at compile time. Benchmarks on a typical desktop JVM:

• Simple arithmetic: ~9 ns per evaluation
• Chained conditionals (3 branches): ~15 ns per evaluation
• Sequential steps (3 steps): ~14 ns per evaluation
• Trigonometric with rounding: ~40 ns per evaluation

In practice, even 3 million calls complete in under 120 ms. Performance is not a concern.

## Client-Side Installation

This mod is optional on the client. If you only need server-side computation, client installation is unnecessary. If you need to display values in UI elements, install on the client to provide the formulas locally. When another mod that requires both sides (e.g. (https://modrinth.com/mod/tconstruct-armor-extension)) deeply integrates this mod, this mod becomes a transitive dependency and must be installed on the client as well.

## For Developers

1. Access loaded formulas via `FormulaManager.getOrNull(ResourceLocation)` and evaluate with `formula.accept(double...)`. 2. Use `FormulaBuilder` to programmatically construct formula JSON. Formulas are loaded from `data//formula/` at startup.

## For Data Pack Creators

Use the `/formula` command to evaluate formulas with parameters in-game. This replaces scoreboard-based computations that would require dozens of commands with a single call, significantly improving datapack performance and readability.

## JSON Format Reference

### Simple Formula

``` { "inputs": ["result", "left", "right"], "formula": "#result = #left + #right 2" } ```

### Sequential Steps

``` { "inputs": ["a", "b", "c"], "formula": [ "#a = #b + #c", "#b = #a #c", "#a = #b + 1" ] } ```

### If/Else Branching

``` { "inputs": ["score", "kills", "deaths"], "formula": { "if": "#kills > #deaths", "formula": "#score = #kills 3 - #deaths 2", "else": "#score = max(0, #kills - #deaths)" } } ```

### Conditional Chain (if / else-if / else)

``` { "inputs": ["result", "value"], "formula": { "chain": [ {"condition": "#value >= 100", "formula": "#result = #value 2"}, {"condition": "#value >= 50", "formula": "#result = #value 1. 5"}, {"condition": "#value >= 10", "formula": "#result = #value"} ], "default": "#result = 0" } } ```

### Mixed Nesting (Sequential + Conditional)

``` { "inputs": ["result", "base", "modifier"], "caches": ["scaled"], "formula": [ "#scaled = log(2, #base + 1)", { "chain": [ {"condition": "#modifier > 10", "formula": "#result = #scaled #modifier 2"}, {"condition": "#modifier > 0", "formula": "#result = #scaled #modifier"} ], "default": "#result = #scaled" } ] } ```

### Explicit Output Slot

By default the result of the last step is returned. Use `"output"` to specify a different variable:

``` { "inputs": ["dummy", "x", "y"], "caches": ["tmp", "extra"], "output": "#extra", "formula": [ "#tmp = #x #y", "#dummy = #tmp + #x", "#extra = #tmp 2 + #y" ] } ```

### Numeric Mode (Abbreviated)

``` { "input": 3, "cache": 2, "output": "#4", "formula": [ "#0 = #1 + #2", "#3 = #0 * #1", "#4 = #3 + #2" ] } ```

## FormulaBuilder — Developer Guide

`FormulaBuilder` is a fluent API for generating formula JSON in Java. It automatically adds the `#` prefix to named variables.