mirror of
https://codeberg.org/vlw/mcfstd.git
synced 2026-04-13 06:39:37 +02:00
vlw
c4195baf85
So it turns out it will be much harder to create namespaced instances of this datapack like we initially thought. It might be worth considering in the future, but we would not be able to use any functions that we add with this library by the library itself, since the namespace change will make all internal function calls point to an undefined target. So we will bundle this as a datapack for now. Reviewed-on: https://codeberg.org/vlw/mcfstd/pulls/1 Co-authored-by: vlw <victor@vlw.se> Co-committed-by: vlw <victor@vlw.se>
243 lines
8.6 KiB
Markdown
243 lines
8.6 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
|
|
Download the datapack as a zip from [the releases page](/vlw/mcfstd/releases) for the version that you require. Place the zip file directly into the `datapacks/` directory of your Minecraft world save directory.
|
|
|
|
Enable this library in Minecraft by typing the following two commands
|
|
```mcfunction
|
|
reload
|
|
|
|
datapack enable "file/mcfstd-X-X-X.zip" # Where X-X-X would be the version of the datapack
|
|
```
|
|
|
|
# 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>
|