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

Function	Arguments	Description	Example
Variables
var:set	k Name of the variable (string)	Set the value of a variable	function var:set { k: my_variable, v: 10 }
	v Value of the variable (int)
var:unset	k Name of the variable (string)	Remove a varialbe	function var:unset { k: my_variable }
var:mv	k Old variable name (string)	Rename a variable	function var:mv { k: my_variable, v: my_renamed_variable }
	v New variable name (string)
var:inc	k Name of the variable (string)	Increment the value of a variable	function var:inc { k: my_variable }
var:dec	k Name of the variable (string)	Decrement the value of a variable	function var:dec { k: my_variable }
var:put	-	Put the current value of A into this variable	function var:put { k: my_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	function math:add { k: my_variable, v: 10 }
	v Number to add (string)
math:sub	k Name of the variable (string)	Subtract a number to the current value of a variable and store the result in A	function math:sub { k: my_variable, v: 10 }
	v Number to subtract (string)
math:mul	k Name of the variable (string)	Multiply a number with the current value of a variable and store the result in A	function math:mul { k: my_variable, v: 10 }
	v Number to multiply (string)
math:div	k Name of the variable (string)	Divide a number with the current value of a variable and store the result in A	function math:div { k: my_variable, v: 10 }
	v Number to divide (string)
math:mod	k Name of the variable (string)	Modulo a number with the current value of a variable and store the result in A	function math:mod { k: my_variable, v: 10 }
	v Number to modulo (string)
Relation / Compare
comp:eq	a Name of the first variable (string)	Check if a = b and store the result in stdout	function comp:eq { a: my_variable, b: my_other_variable }
	v Name of the second variable (string)
comp:gt	a Name of the first variable (string)	Check if a > b and store the result in stdout	function comp:gt { a: my_variable, b: my_other_variable }
	v Name of the second variable (string)
comp:gteq	a Name of the first variable (string)	Check if a >= b and store the result in stdout	function comp:gteq { a: my_variable, b: my_other_variable }
	v Name of the second variable (string)
comp:lt	a Name of the first variable (string)	Check if a < b and store the result in stdout	function comp:lt { a: my_variable, b: my_other_variable }
	v Name of the second variable (string)
comp:lteq	a Name of the first variable (string)	Check if a <= b and store the resulteq in stdout	function comp:lteq { a: my_variable, b: my_other_variable }
	v Name of the second variable (string)
Built-in operations
std:out	-	Will return true if the value of stdout is 0 (success)	execute if function std:out run function my_function