Equations
ScoreboardEquation and StorageEquation are chainable equation builders that translate a readable Python expression into a series of Minecraft scoreboard players operation commands. Both classes generate a self-documenting output: the first line is always a # comment showing the full equation, followed by every scoreboard command needed to compute it.
Use equations any time you need multi-step integer arithmetic in a datapack function: instead of writing raw scoreboard players operation commands by hand, you build the expression in Python and call str() to get the full mcfunction block.
Example File: extensive/src/link.py
Source Code: stewbeet/core/utils/equation.py
- Build complex scoreboard arithmetic with clean, readable Python syntax
- Auto-generate a
# commentheader that mirrors the full equation for self-documenting functions - Chain operations via methods (
.set(),.add(),.multiply(), ...) or Python operators (+,-,*,/,//,%, unary-) ScoreboardEquation: result stays in a scoreboard objectiveStorageEquation: result is flushed to NBT storage with a float scale factor- Pass another equation instance as an operand. Its commands are inlined automatically
- Macro arguments (
$(name)) are handled transparently with a$scoreboard players setprefix
Required: StewBeet framework (from stewbeet import *)
Required: stewbeet.plugins.auto.scoreboard_constants: initializes all integer constants (e.g. #5) generated by equations
Position: Called inside a beet_default plugin hook, after definitions setup
Integration: Output is passed to write_function() to embed commands in datapack functions
From Minecraft 26.3: one /compute command
When the project targets 26.3 or later, an equation is rendered as a single execute store result ... run compute default integer <provider> command, the provider being a tree of add, sub, mul, floor_div and floor_mod number providers that rounds exactly like the scoreboard operations. The examples below show the scoreboard operations, which are still what .ops holds and what is written before 26.3.
equation = ScoreboardEquation("#value", f"{ns}.data").set(10).add(5).multiply(2)# scoreboard #value <ns>.data = 10 + 5 * 2
execute store result score #value <ns>.data run compute default integer {type:"mul",inputs:[{type:"add",inputs:[10,5]},2]}- An operand a number provider cannot name, a selector other than
@s, keeps the whole equation on scoreboard operations. - A combined equation is computed inline: its own target score is not written.
- No
#5constant is needed, soauto.scoreboard_constantshas nothing to initialise for these equations.
ScoreboardEquation
Constructor
ScoreboardEquation(player: str, scoreboard: str | None = None)| Parameter | Type | Default | Description |
|---|---|---|---|
player | str | - | Target player or fake-player (e.g. "@s", "#value") |
scoreboard | str | None | {project_id}.data | Target scoreboard objective |
Basic Example
From the extensive template:
ns: str = ctx.project_id
equation = ScoreboardEquation("#value", f"{ns}.data").set(10).add(5).multiply(2).divide(3).modulo(100)
equation2 = (ScoreboardEquation("#value2", f"{ns}.data").set(20) - 6 + 7) * 8 // 4 % 5
write_function(f"{ns}:equation/test", str(equation) + "\n" + str(equation2))Generated mcfunction:
# scoreboard #value <ns>.data = 10 + 5 * 2 / 3 % 100
scoreboard players set #value <ns>.data 10
scoreboard players operation #value <ns>.data += #5 <ns>.data
scoreboard players operation #value <ns>.data *= #2 <ns>.data
scoreboard players operation #value <ns>.data /= #3 <ns>.data
scoreboard players operation #value <ns>.data %= #100 <ns>.data
# scoreboard #value2 <ns>.data = 20 - 6 + 7 * 8 / 4 % 5
scoreboard players set #value2 <ns>.data 20
scoreboard players operation #value2 <ns>.data -= #6 <ns>.data
scoreboard players operation #value2 <ns>.data += #7 <ns>.data
scoreboard players operation #value2 <ns>.data *= #8 <ns>.data
scoreboard players operation #value2 <ns>.data /= #4 <ns>.data
scoreboard players operation #value2 <ns>.data %= #5 <ns>.dataNote: When
scoreboardis omitted it defaults to{project_id}.data. Integer operands are automatically registered as scoreboard constants (e.g.#5) and initialized by theauto.scoreboard_constantsplugin.
Using a Player Scoreboard as Operand
Pass any player name or selector as the source: supply an explicit scoreboard as the second argument if it differs from the equation's own objective:
# Copy @s's score from another objective, then divide by 100
equation = ScoreboardEquation("@s", f"{ns}.data").set("@s", f"{ns}.base").divide(100)Generated mcfunction:
# scoreboard @s <ns>.data = @s <ns>.base / 100
scoreboard players operation @s <ns>.data = @s <ns>.base
scoreboard players operation @s <ns>.data /= #100 <ns>.dataCombining Two Equations
Any equation instance can be passed directly as an operand. Its commands are inlined first, and its final player/scoreboard is used as the source value:
eq_a = ScoreboardEquation("@s").set(10) * 5
eq_b = ScoreboardEquation("#toto", "some_score").set(20) * 2
write_function(f"{ns}:equation/combined", str(eq_a * eq_b))Generated mcfunction:
# scoreboard @s <ns>.data = 10 * 5 * (scoreboard #toto some_score = 20 * 2)
scoreboard players set @s <ns>.data 10
scoreboard players operation @s <ns>.data *= #5 <ns>.data
scoreboard players set #toto some_score 20
scoreboard players operation #toto some_score *= #2 <ns>.data
scoreboard players operation @s <ns>.data *= #toto some_scoreStorageEquation
StorageEquation works exactly like ScoreboardEquation for the arithmetic steps, but when str() is called an execute store result storage ... command is appended to persist the result to NBT storage.
Constructor
StorageEquation(storage: str, path: str, scale: float = 1.0, storage_type: str = "double")| Parameter | Type | Default | Description |
|---|---|---|---|
storage | str | - | Storage resource location (e.g. "my_ns:my_storage") |
path | str | - | NBT path inside the storage (e.g. "result") |
scale | float | 1.0 | Multiplier applied when writing to storage: use small values (e.g. 0.000001) to convert integers to floats |
storage_type | str | "double" | NBT number type: "double", "float", "int", "long", "short", "byte" |
All arithmetic runs on a hidden #temp_result fake-player scoreboard. The final execute store result is added automatically when you call str().
Example with Macro Arguments
equation = (
StorageEquation("some_namespace:some_path", "result_path", 0.000005, "double")
.set("-$(amount)")
.multiply(1000000)
.divide("$(max_damage)")
.subtract("#toto")
)
write_function(f"{ns}:compute/result", str(equation))Generated mcfunction:
# storage some_namespace:some_path result_path = (-$(amount) * 1000000 / $(max_damage) - #toto) * 0.000005
$scoreboard players set #temp_result <ns>.data -$(amount)
scoreboard players operation #temp_result <ns>.data *= #1000000 <ns>.data
$scoreboard players set #temp_divide <ns>.data $(max_damage)
scoreboard players operation #temp_result <ns>.data /= #temp_divide <ns>.data
scoreboard players operation #temp_result <ns>.data -= #toto <ns>.data
execute store result storage some_namespace:some_path result_path double 0.000005 run scoreboard players get #temp_result <ns>.dataNote: Lines beginning with
$are Minecraft macro commands, generated automatically whenever a macro argument ($(name)) appears as an operand.
Operations Reference
Methods and Python Operators
| Method | Python operator | Scoreboard op | Description |
|---|---|---|---|
.set(value) | ( | scoreboard players set | Initial assignment)must be called first |
.add(value) | + | += | Addition |
.subtract(value) | - | -= | Subtraction |
.multiply(value) | * | *= | Multiplication |
.divide(value) | / or // | /= | Integer division (// behaves identically to /) |
.modulo(value) | % | %= | Modulo |
| Unary negation | -equation | *= #-1 | Multiplies the current value by -1 |
All methods accept an optional
scoreboardsecond argument to target a different objective for the source value.
Accepted value types
| Type | Example | Behavior |
|---|---|---|
int | 42 | Generates a #42 fake-player constant; uses scoreboard players operation with {project_id}.data |
str: player / selector | "@s", "#other" | Direct scoreboard operation; uses the equation's own objective unless scoreboard is supplied |
str: macro argument | "$(amount)" | Prepends $scoreboard players set #temp_... ... to handle the macro before the operation |
BaseEquation | another equation | Inlines the source equation's commands first, then uses its final player/scoreboard as source |
Important: All Minecraft scoreboard arithmetic is integer-only. Use the
scaleparameter ofStorageEquationto convert the integer result to a floating-point NBT value when writing to storage.
Glossary
| Term | Meaning |
|---|---|
| ScoreboardEquation | A chainable builder that generates Minecraft scoreboard players operation commands and stores the final result in a scoreboard objective. |
| StorageEquation | A chainable builder that computes via a hidden #temp_result scoreboard, then flushes the result to NBT storage using an execute store result command with a configurable scale factor. |
| Method chaining | Every operation method returns self, so calls can be chained: .set(10).add(5).multiply(2). |
| Equation header comment | The first line of every rendered equation is a human-readable # comment that mirrors the full mathematical expression, making generated functions self-documenting. |
| Macro argument | A Minecraft function macro parameter in the form $(name). When used as an operand, a $scoreboard players set line is automatically prepended. |
Next steps
- Writing to files: embed the commands an equation produces.
- auto.scoreboard_constants: how the constants equations need get initialised.
- Defining items and blocks: where the items equations operate on are declared.