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 # comment header 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 objective
  • StorageEquation: 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 set prefix

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.

python
equation = ScoreboardEquation("#value", f"{ns}.data").set(10).add(5).multiply(2)
mcfunction
# 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 #5 constant is needed, so auto.scoreboard_constants has nothing to initialise for these equations.

ScoreboardEquation

Constructor

python
ScoreboardEquation(player: str, scoreboard: str | None = None)
ParameterTypeDefaultDescription
playerstr-Target player or fake-player (e.g. "@s", "#value")
scoreboardstr | None{project_id}.dataTarget scoreboard objective

Basic Example

From the extensive template:

python
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:

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>.data

Note: When scoreboard is omitted it defaults to {project_id}.data. Integer operands are automatically registered as scoreboard constants (e.g. #5) and initialized by the auto.scoreboard_constants plugin.

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:

python
# 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:

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>.data

Combining 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:

python
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:

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_score

StorageEquation

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

python
StorageEquation(storage: str, path: str, scale: float = 1.0, storage_type: str = "double")
ParameterTypeDefaultDescription
storagestr-Storage resource location (e.g. "my_ns:my_storage")
pathstr-NBT path inside the storage (e.g. "result")
scalefloat1.0Multiplier applied when writing to storage: use small values (e.g. 0.000001) to convert integers to floats
storage_typestr"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

python
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:

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>.data

Note: Lines beginning with $ are Minecraft macro commands, generated automatically whenever a macro argument ($(name)) appears as an operand.


Operations Reference

Methods and Python Operators

MethodPython operatorScoreboard opDescription
.set(value)(scoreboard players setInitial 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*= #-1Multiplies the current value by -1

All methods accept an optional scoreboard second argument to target a different objective for the source value.

Accepted value types

TypeExampleBehavior
int42Generates 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
BaseEquationanother equationInlines the source equation's commands first, then uses its final player/scoreboard as source

Important: All Minecraft scoreboard arithmetic is integer-only. Use the scale parameter of StorageEquation to convert the integer result to a floating-point NBT value when writing to storage.

Glossary

TermMeaning
ScoreboardEquationA chainable builder that generates Minecraft scoreboard players operation commands and stores the final result in a scoreboard objective.
StorageEquationA 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 chainingEvery operation method returns self, so calls can be chained: .set(10).add(5).multiply(2).
Equation header commentThe first line of every rendered equation is a human-readable # comment that mirrors the full mathematical expression, making generated functions self-documenting.
Macro argumentA Minecraft function macro parameter in the form $(name). When used as an operand, a $scoreboard players set line is automatically prepended.

Next steps