
# 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](https://github.com/Stoupy51/StewBeet/blob/main/templates/extensive/src/link.py) <br>  
**Source Code**: [stewbeet/core/utils/equation.py](https://github.com/Stoupy51/StewBeet/blob/main/python_package/stewbeet/core/utils/equation.py) <br>

- 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)
```

| 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](https://github.com/Stoupy51/StewBeet/blob/main/templates/extensive/src/link.py):
```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")
```

| 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
```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

| 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 `scoreboard` second 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 `scale` parameter of `StorageEquation` to 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](../2_writing_to_files/en.md): embed the commands an equation produces.
- [auto.scoreboard_constants](../plugins/auto.scoreboard_constants.md): how the constants equations need get initialised.
- [Defining items and blocks](../1_definitions_setup/en.md): where the items equations operate on are declared.

