Minecraft Functions
#
Creating a Minecraft functionAs you saw earlier, you can create a Minecraft function using MCFunction
:
By specifying only the function's name, it will be created inside the default namespace. However, you can specify it yourself:
Here, your function will be created inside the mydatapack
namespace.
#
Calling a Minecraft functionOne of the goal of Sandstone is to promote reusable block of commands. To make this possible, you have the ability to call other functions.
Your first possibility is to call another Minecraft function, just like you would in a normal Minecraft Datapack. To achieve this, you need to assign your MCFunction to a variable:
This will result in the following functions:
This approach has several advantages:
Commands are not duplicated. This results in a lighter datapack.
The function can be recursive.
It has a meaningful name in Minecraft (here, default:main).
However, it has three drawbacks:
It will create a
.mcfunction
file for each functions, even if they are never called. Therefore, it makes it hard to share your functions with other peoples: if your library contains 100 helper functions, all datapacks using your library will include those 100 functions - even if they only use one.It cannot take parameters. If you want to have a generic set of commands, that changes depending on some parameters, this is not possible.
The first drawback can be solved using lazy functions, and the second one using inline functions.
#
Lazy Minecraft FunctionsTo prevent Sandstone creating functions when not mandatory, you can use lazy functions. A lazy function will be created only if another function calls it. A lazy function that isn't called won't even be present in the datapack:
Results in:
As you can see, the useless
function has not been created. Let's call it from the main function
:
Results in:
As you can see, the useless
function has been created, because it is called from main
. This feature is very useful to distribute lot of functions, in a library for example.
#
Minecraft function optionsYou can specify different options, other than lazy
, for your Minecraft functions.
option | type | description |
---|---|---|
runEachTick | boolean | Whether the function should run each tick. |
runOnLoad | boolean | Whether the function should run when the datapack is loaded or reloaded. |
tags | string[] | The function tags to apply to this function. |
lazy | boolean | If true, then the function will only be created if it is called from another function. |
``
#
Inline functionsInline functions are normal, Javascript functions. They group up related commands in a reusable, readable piece of code. Inline functions do not create additional MCFunctions. They are inlined when they are called.
Let's take a simple example using inline functions:
This results in:
As you can see, the commands from the giveDiamonds
function are directly written inside main
. Inline functions are a very efficient way to group up related commands, which helps writing a clean and logical datapack.
Inline functions can do everything a normal function does: using commands, calling MCFunctions, calling other lazy functions...
#
Waiting between commands#
The basicsSandstone allows you to wait a fixed amount of time between some commands, without having to manually declare a new function each time. This has several purpose: dialogs, event scheduling, animations etc... Under the hood, this uses the /schedule
command: however, all the complexity is abstracted away.
#
Basic syntaxTo wait a specific time between commands, there are two things to do:
Change your function to an asynchronous function, by adding the
async
keywordAdd the
await sleep(delay)
line between your commands.
delay
can be a number of ticks, or a time string like '1t'
, '1s'
, '1d'
...
Here is a minimal syntax:
There are two things to notice. First, our function is now asynchronous. They async
keyword has been added before the parameters list:
Second, we await the sleep
function
#
ExampleYou could simulate a dialog like this:
This example would compile to the following resources: