mirror of
https://codeberg.org/vlw/mcfstd.git
synced 2026-04-13 14:39:38 +02:00
255 lines
9 KiB
Markdown
255 lines
9 KiB
Markdown
# Standard library for mcfunction
|
|
Make development of Minecraft datapacks in mcfunction easier with variables, arithmetic, and relational (comparison) operators.
|
|
|
|
```mcfunction
|
|
# Set variable 'my_variable' to 10
|
|
function var:set { k: my_variable, v: 10 }
|
|
|
|
# Add 5 to 'my_variable'
|
|
function math:add { k: my_variable, v: 5 }
|
|
|
|
# Put the result of the calculation back into 'my_variable'
|
|
function var:put { k: my_variable }
|
|
|
|
# if 'my_variable' == 15
|
|
function comp:eq { k: my_variable, v: 15 }
|
|
|
|
# then
|
|
execute if std:out run return run function my_function
|
|
|
|
# else
|
|
execute unless std:out run return fail
|
|
```
|
|
|
|
**See the [function reference](#functions) for a full list of available functions**
|
|
|
|
# Installation
|
|
This is not a stand-alone datapack but is instead intended to be placed inside the `data/` directory of your own datapack. Clone this repository into the `data/` directory of your datapack.
|
|
|
|
```
|
|
git clonne http://codeberg.org/vlw/mcfstd
|
|
```
|
|
|
|
It is highly recommended that you rename the directory that contains this library after you clone it. This will prevent other datapacks that use this library from interfering with yours, and it also prevents your datapacks from interfering with theirs. This is important since other datapacks might use a version of this library that is not compatible with yours.
|
|
|
|
For example
|
|
```
|
|
data/
|
|
mcfstd/
|
|
```
|
|
would become:
|
|
```
|
|
data/
|
|
std_my_datapack/
|
|
```
|
|
|
|
One that is done, reload your plugins with `/reload` and you should have access to mcfstd functions
|
|
|
|
# The standard output
|
|
This library contains a standard output that is used as an intermediary for arithmetic and comparison operations.
|
|
|
|
# Arithmetics
|
|
When performing arithmetic and comparisons on variables, the result of the operation is not stored back into the variable immediately. When a function, for example `std:add` is performed on a varaible, the result is stored in an internal register called the "A" register. This allows for simple equations to be constructed without needing to create temporary or mutating existing variables.
|
|
|
|
```mcfunction
|
|
function var:set { k: addend, v: 10 }
|
|
function var:set { k: sum, v: 0 }
|
|
|
|
# Add 10 to the variable 'addend' and store the result in 'sum'
|
|
function math:add { k: addend, v: 10 }
|
|
function var:put { k: sum }
|
|
```
|
|
Note that the variable `addend` is still 10 and the variable `sum` contains the sum of the calculation.
|
|
|
|
# Comparisons
|
|
The result of comparing variable values is not returned immediately from the comparison functions. This is mainly due to a limitation in mcfunction which does not permit function arguments to be passed after an `execute (if|unless)` statement. To work around this, we store the result of the last comparison in a standard output function `std:out`. This function will return nothing (pass) if the last comparison was truthy, and return 0 (fail) if the comparison was falsy.
|
|
|
|
```mcfunction
|
|
function var:set { k: x, v: 20 }
|
|
function var:set { k: y, v: 10 }
|
|
|
|
# x != y, so std:out will be false
|
|
function comp:eq { a: x, b: y }
|
|
execute if std:out run return run function my_function
|
|
|
|
# x > y, so std:out will be TRUE and this function will return with my_function
|
|
function comp:gt { a: x, b: y }
|
|
execute if std:out run return run function my_function
|
|
```
|
|
|
|
# Functions
|
|
<table>
|
|
<tr>
|
|
<th>Function</th>
|
|
<th>Arguments</th>
|
|
<th>Description</th>
|
|
<th>Example</th>
|
|
</tr>
|
|
<tr>
|
|
<th colspan="4">Variables</th>
|
|
</tr>
|
|
<!-- var:set -->
|
|
<tr>
|
|
<td rowspan="2"><code>var:set</code></td>
|
|
<td><code>k</code> Name of the variable (string)</td>
|
|
<td rowspan="2">Set the value of a variable</td>
|
|
<td rowspan="2"><code>function var:set { k: my_variable, v: 10 }</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>v</code> Value of the variable (int)</td>
|
|
</tr>
|
|
<!-- var:unset -->
|
|
<tr>
|
|
<td><code>var:unset</code></td>
|
|
<td><code>k</code> Name of the variable (string)</td>
|
|
<td>Remove a varialbe</td>
|
|
<td><code>function var:unset { k: my_variable }</code></td>
|
|
</tr>
|
|
<!-- var:mv -->
|
|
<tr>
|
|
<td rowspan="2"><code>var:mv</code></td>
|
|
<td><code>k</code> Old variable name (string)</td>
|
|
<td rowspan="2">Rename a variable</td>
|
|
<td rowspan="2"><code>function var:mv { k: my_variable, v: my_renamed_variable }</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>v</code> New variable name (string)</td>
|
|
</tr>
|
|
<!-- var:inc -->
|
|
<tr>
|
|
<td><code>var:inc</code></td>
|
|
<td><code>k</code> Name of the variable (string)</td>
|
|
<td>Increment the value of a variable</td>
|
|
<td><code>function var:inc { k: my_variable }</code></td>
|
|
</tr>
|
|
<!-- var:dec -->
|
|
<tr>
|
|
<td><code>var:dec</code></td>
|
|
<td><code>k</code> Name of the variable (string)</td>
|
|
<td>Decrement the value of a variable</td>
|
|
<td><code>function var:dec { k: my_variable }</code></td>
|
|
</tr>
|
|
<!-- var:put -->
|
|
<tr>
|
|
<td><code>var:put</code></td>
|
|
<td>-</td>
|
|
<td>Put the current value of A into this variable</td>
|
|
<td><code>function var:put { k: my_variable }</code></td>
|
|
</tr>
|
|
<tr>
|
|
<th colspan="4">Arithmetic</th>
|
|
</tr>
|
|
<!-- math:add -->
|
|
<tr>
|
|
<td rowspan="2"><code>math:add</code></td>
|
|
<td><code>k</code> Name of the variable (string)</td>
|
|
<td rowspan="2">Add a number to the current value of a variable and store the result in A</td>
|
|
<td rowspan="2"><code>function math:add { k: my_variable, v: 10 }</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>v</code> Number to add (string)</td>
|
|
</tr>
|
|
<!-- math:sub -->
|
|
<tr>
|
|
<td rowspan="2"><code>math:sub</code></td>
|
|
<td><code>k</code> Name of the variable (string)</td>
|
|
<td rowspan="2">Subtract a number to the current value of a variable and store the result in A</td>
|
|
<td rowspan="2"><code>function math:sub { k: my_variable, v: 10 }</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>v</code> Number to subtract (string)</td>
|
|
</tr>
|
|
<!-- math:mul -->
|
|
<tr>
|
|
<td rowspan="2"><code>math:mul</code></td>
|
|
<td><code>k</code> Name of the variable (string)</td>
|
|
<td rowspan="2">Multiply a number with the current value of a variable and store the result in A</td>
|
|
<td rowspan="2"><code>function math:mul { k: my_variable, v: 10 }</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>v</code> Number to multiply (string)</td>
|
|
</tr>
|
|
<!-- math:div -->
|
|
<tr>
|
|
<td rowspan="2"><code>math:div</code></td>
|
|
<td><code>k</code> Name of the variable (string)</td>
|
|
<td rowspan="2">Divide a number with the current value of a variable and store the result in A</td>
|
|
<td rowspan="2"><code>function math:div { k: my_variable, v: 10 }</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>v</code> Number to divide (string)</td>
|
|
</tr>
|
|
<!-- math:mod -->
|
|
<tr>
|
|
<td rowspan="2"><code>math:mod</code></td>
|
|
<td><code>k</code> Name of the variable (string)</td>
|
|
<td rowspan="2">Modulo a number with the current value of a variable and store the result in A</td>
|
|
<td rowspan="2"><code>function math:mod { k: my_variable, v: 10 }</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>v</code> Number to modulo (string)</td>
|
|
</tr>
|
|
<tr>
|
|
<th colspan="4">Relation / Compare</th>
|
|
</tr>
|
|
<!-- comp:eq -->
|
|
<tr>
|
|
<td rowspan="2"><code>comp:eq</code></td>
|
|
<td><code>a</code> Name of the first variable (string)</td>
|
|
<td rowspan="2">Check if <code>a = b</code> and store the result in <code>stdout</code></td>
|
|
<td rowspan="2"><code>function comp:eq { a: my_variable, b: my_other_variable }</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>v</code> Name of the second variable (string)</td>
|
|
</tr>
|
|
<!-- comp:gt -->
|
|
<tr>
|
|
<td rowspan="2"><code>comp:gt</code></td>
|
|
<td><code>a</code> Name of the first variable (string)</td>
|
|
<td rowspan="2">Check if <code>a > b</code> and store the result in <code>stdout</code></td>
|
|
<td rowspan="2"><code>function comp:gt { a: my_variable, b: my_other_variable }</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>v</code> Name of the second variable (string)</td>
|
|
</tr>
|
|
<!-- comp:gteq -->
|
|
<tr>
|
|
<td rowspan="2"><code>comp:gteq</code></td>
|
|
<td><code>a</code> Name of the first variable (string)</td>
|
|
<td rowspan="2">Check if <code>a >= b</code> and store the result in <code>stdout</code></td>
|
|
<td rowspan="2"><code>function comp:gteq { a: my_variable, b: my_other_variable }</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>v</code> Name of the second variable (string)</td>
|
|
</tr>
|
|
<!-- comp:lt -->
|
|
<tr>
|
|
<td rowspan="2"><code>comp:lt</code></td>
|
|
<td><code>a</code> Name of the first variable (string)</td>
|
|
<td rowspan="2">Check if <code>a < b</code> and store the result in <code>stdout</code></td>
|
|
<td rowspan="2"><code>function comp:lt { a: my_variable, b: my_other_variable }</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>v</code> Name of the second variable (string)</td>
|
|
</tr>
|
|
<!-- comp:lteq -->
|
|
<tr>
|
|
<td rowspan="2"><code>comp:lteq</code></td>
|
|
<td><code>a</code> Name of the first variable (string)</td>
|
|
<td rowspan="2">Check if <code>a <= b</code> and store the resulteq in <code>stdout</code></td>
|
|
<td rowspan="2"><code>function comp:lteq { a: my_variable, b: my_other_variable }</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>v</code> Name of the second variable (string)</td>
|
|
</tr>
|
|
<tr>
|
|
<th colspan="4">Built-in operations</th>
|
|
</tr>
|
|
<!-- std:out -->
|
|
<tr>
|
|
<td><code>std:out</code></td>
|
|
<td>-</td>
|
|
<td>Will return true if the value of stdout is 0 (success)</td>
|
|
<td><code>execute if function std:out run function my_function</code></td>
|
|
</tr>
|
|
</table>
|