mcfstd/README.md

Standard library for mcfunction

Make development of Minecraft datapacks in mcfunction easier with variables, arithmetic, and relational (comparison) operators.

# 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 for a full list of available functions

Installation

Download the datapack as a zip from the releases page 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

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.

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.

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

Note

The functions under the z_: namespace are used internally by mcfstd and are not meant to be called directly unless you know what you are doing.

Function	Arguments	Description
Variables
var:set	k Name of the variable (string)	Set the value of a variable
	v Value of the variable (int)
var:unset	k Name of the variable (string)	Remove a varialbe
var:mv	k Old variable name (string)	Rename a variable
	v New variable name (string)
var:inc	k Name of the variable (string)	Increment the value of a variable
var:dec	k Name of the variable (string)	Decrement the value of a variable
var:put	-	Put the current value of A into this variable
Arithmetic
math:add	k Name of the variable (string)	Add a number to the current value of a variable and store the result in A
	v Number to add (int)
math:sub	k Name of the variable (string)	Subtract a number to the current value of a variable and store the result in A
	v Number to subtract (int)
math:mul	k Name of the variable (string)	Multiply a number with the current value of a variable and store the result in A
	v Number to multiply (int)
math:div	k Name of the variable (string)	Divide a number with the current value of a variable and store the result in A
	v Number to divide (int)
math:mod	k Name of the variable (string)	Modulo a number with the current value of a variable and store the result in A
	v Number to modulo (int)
Relation / Compare
comp:eq	a Name of the first variable (string)	Check if a = b and store the result in the standard output
	b Name of the second variable (string)
comp:gt	a Name of the first variable (string)	Check if a > b and store the result in the standard output
	b Name of the second variable (string)
comp:gteq	a Name of the first variable (string)	Check if a >= b and store the result in the standard output
	b Name of the second variable (string)
comp:lt	a Name of the first variable (string)	Check if a < b and store the result in the standard output
	b Name of the second variable (string)
comp:lteq	a Name of the first variable (string)	Check if a <= b and store the resulteq in the standard output
	b Name of the second variable (string)
Built-in operations
std:out	-	Will return nothing if the value of the standard output is not fail. Else this function will also fail