Czech, Thai, and Turkish language wikis are now available. Please help with translating!

Function

From Minecraft Wiki
Jump to: navigation, search

Functions allow players to run lists of commands using text files with the extension .mcfunction. It is recommended to use UTF-8 (without BOM) encoding on function files to prevent any problems.

Usage[edit | edit source]

To utilize functions, the text files must first be placed into a top-level folder within .minecraft/saves/[WORLD_NAME]/data/functions. The name of this top-level folder will be the namespace used when running functions inside this folder. Functions can also be placed into subfolders within the top-level folder.

For example, running the function custom:example/test will refer to the file located at functions/custom/example/test.mcfunction. If the namespace is left out when trying to call a function, it will default to the minecraft: namespace. Using a custom namespace is recommended in order to prevent unintended behavior in the case of future additions to the default namespace.[1]

Functions, being text files, are easily modifiable and less likely than command blocks to induce lag when used in large quantities. If a function is modified or added, using the /reload command will reload the function files from disk. This allows Minecraft to recognize any changes to the function files, without the need to quit and re-enter the world.

Upon successfully running a function, a message will display in the chat: Executed [amount] command(s) from function '[function file directory]'. The successful output of the commands inside a function cannot be measured with a comparator (although the same effect could be accomplished with the use of /stats and /scoreboard commands).

Function syntax[edit | edit source]

Testing the function system. Three /tellraw messages and one /give command were used in this simple function.

Within the .mcfunction 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 #.

Individual commands in functions can be longer than the 32,500 character limit in command blocks but the total number of commands run inside a function will still obey /gamerule maxCommandChainLength, which is 65,536 commands by default; any commands beyond this limit will be ignored.

Running a function[edit | edit source]

Functions will run all of their commands in a single tick and functions called from within other functions will also 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 within its child functions) until the next iteration, regardless of the order of commands. The /execute command circumvents this.

For example:

tp @s ~ ~5 ~
setblock ~ ~-1 ~ emerald_block
execute @s ~ ~ ~ setblock ~ ~-1 ~ diamond_block

When called through a player this function will teleport that player 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.

There are several methods of running a function file in-game:

Commands[edit | edit source]

/function
  • 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.
  • Usage: /function <namespace:path/to/function/file> (<if|unless> <selector>)
/gamerule gameLoopFunction
  • Runs a function every tick.
  • The commands in the function are run through the server.
    • The coordinates from which the "server" executes commands are (0, 0, 0).
  • If multiple functions need to be looped, it is possible to insert function commands into this looped function file, put function commands in those functions, etc.
  • Usage: /gamerule gameLoopFunction <namespace:path/to/function/file>

Advancements[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.

Reward functions are called within advancement JSON files using the following format:

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

History[edit | edit source]

Official release
1.12 pre1 Added functions.
pre3 Commands are no longer allowed to begin with a / (forward slash)
Comments can now only be preceded with #; using // is no longer allowed
pre4 Added new arguments to the /function command: [if|unless] [selector]
pre6 Skipped functions (when a conditional fails) are now considered failures when used in commands.

Issues[edit | edit source]

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

References[edit | edit source]