Function

From Minecraft Wiki
Jump to: navigation, search
This page contains content on features that may be included in the next update.
These features have appeared in development versions, but the full update containing these features has not been released yet.

Functions are an upcoming feature that will allow players to easily script and run lists of commands using text files with the extension .mcfunction.

Usage[edit | edit source]

To use a function in a Minecraft world, the text file must first be placed into the WORLDNAME/data/functions folder. They can then be run using the several methods detailed below. Functions can be further divided into subfolders, and are run in-game using the format namespace:path/to/function/file. For example, running custom:example/test will refer to the function located at WORLDNAME/data/functions/custom/example/test.mcfunction. If the namespace is left out when trying to call a function, it will default to minecraft:. This means that all functions must be contained within a sub folder (of the functions folder) in order to be located.

Within the text file, one valid command is placed per line (without the usual forward slash). Players can add comments within the function text file by preceding them with a #. If a function is added or modified, the /reload command will reload the function files from disk, allowing Minecraft to recognise any changes to the function files. Commands run inside a function will obey /gamerule maxCommandChainLength.

Commands in functions can be longer than the 32 500 character limit in command blocks. Functions will also run all of their commands in a single tick. Functions called from within other functions will run their commands in the same tick as their parent. Position changes that happen within a function will not affect the relative coordinates used in other commands within that function (or other functions called within the function) till the next iteration regardless of the order of commands, the /execute command circumvents this. For example:

tp @a ~ ~5 ~

setblock ~ ~-1 ~ emerald_block

execute @a ~ ~ ~ setblock ~ ~-1 ~ diamond_block

These 3 commands will teleport all players 5 blocks up, place an emerald_block one block below their original position before the teleport and place a diamond block one block below their new position after the teleport. This behavior does not affect position arguments within selectors, which will always test for the current position at the time of execution.

Since they are simply text files, functions are easily modifiable and less likely to induce lag when used in large quantities, compared to command blocks. However, the successful output of a function cannot be measured with a comparator (without the use of complex scoreboard commands).

There are currently three ways of running a function file in-game:

/function[edit | edit source]

The /function command allows players to run a function once. The commands in the function are run through the entity or command block that ran the /function command. The optional arguments if and unless will make the function only run when the selector was found or not found in the world respectively. Currently the if argument only succeeds upon matching 1 target (beyond which the function will be skipped), and the unless argument with 0 or 2+ targets (with only 1, the function will be skipped), although this behavior is likely unintended.

Usage: /function <namespace:path/to/function/file> [if|unless] [selector]

/gamerule gameLoopFunction[edit | edit source]

The /gamerule gameLoopFunction will run a function every tick. The commands in the function are run through the server.

Usage: /gamerule gameLoopFunction <namespace:path/to/function/file>

Advancement rewards[edit | edit source]

Advancements can run a function once as a reward for completing them. The commands in the function are run through the player who completed the advancement.

Usage:

{
    "rewards": {
        "function": "namespace:path/to/function/file"
    }
}

History[edit | edit source]

Upcoming
1.12 1.12-pre1 Added functions.
1.12-pre3 Commands are no longer allowed to begin with a / (forward slash)
Comments must now be proceeded by a #; using // is no longer allowed
1.12-pre4 Added new arguments: [if|unless] [selector]

Issues[edit | edit source]

Issues relating to “Function” are maintained on the issue tracker. Report issues there.

See also[edit | edit source]