Minecraft:Function (Java Edition)

Functions are Minecraft:data pack files, allowing players to run lists of Minecraft:commands.

File:TestingFunctions.png

Testing the function system. Three Template:Cmd messages and one Template:Cmd command were used in this simple function.

This page covers how functions are defined and invoked Template:In.

Definition

A function is a text file with the file extension .mcfunction. Function files are part of the data pack directory structure, highlighted below: Template:Data pack directory

As with all other data pack files, the function folder may also contain subfolders to further organize the function files within a namespace. These subfolders must be referenced when invoking the function.

Within the .mcfunction file, one valid command is placed per line, without the usual forward slash (/). Individual commands in functions can be longer than the 32,500 character limit in command blocks.

Comments can be added within the function text file by beginning a line with #. A line can have tabs and spaces before and after the command.

A single backslash \ as the last non-whitespace character of a line allows a command to be continued on the next line, and the leading and trailing whitespace of the following line are stripped before appending.

Invocation

Functions can be invoked in several different manners from other data pack files.

Invocation from commands

Functions can be invoked using the Template:Cmd command and Template:Cmd command.

A single function can be invoked by specifying its Minecraft:resource location.

Functions are supported by tags, allowing them to be grouped together. /function also accepts a function tag, invoking all listed functions.

Invocation from function tags

As mentioned above, functions can be grouped together using Minecraft:function tags. Functions in a tag get executed in the defined order, but only the first occurrence of the same function if it occurs multiple times.

In addition, there are two function tags within the minecraft namespace that have special behavior:

• Functions listed in the minecraft:load tag run when the world is loaded, or when the server is started. Listed functions also run whenever the data pack is reloaded.
  • These functions run before the player joins the world, meaning any Minecraft:target selectors do not find players. Therefore, commands like Template:Cmd and Template:Cmd do not appear for any player.
• Functions listed in the minecraft:tick tag run at the beginning of each tick, repeating every tick.

Invocation from advancements

Minecraft: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 Minecraft:JSON files using the following format:

<syntaxhighlight lang=json> {

   "rewards": {
        "function": "test:test"
   }

} </syntaxhighlight>

Invocation from scheduling

The Template:Cmd command schedules a function to be invoked after a certain amount of time. The function is invoked by the server when the scheduled time arrives.

Invocation from enchantments

Enchantment [[Minecraft:Enchantment_definition#run_function|entity effect Template:Cd]] can run a function once as an enchantment effect. <syntaxhighlight lang="json"> ...

 "type": "run_function",
 "function": "test:test",

... </syntaxhighlight>

Behaviors

Loading and Parsing

Each time a level or a server is opened, the game loads all the functions in the data pack.

In a running level, if function files are changed, use Template:Cmd to reload them from disk.

When a function is loaded or reloaded, all non-macro lines are parsed as commands, and if any of the lines in a function file is unparseable, the function file cannot be loaded. Macro lines are parsed into commands each time before the function executes.

Executing

In a singleplayer or a LAN world, like a Minecraft:command block, a function can run any command that is no more restrictive than permission level 2.

On the default multiplayer software, a function can run any command that is no more restrictive than the permission level prescribed in function-permission-level setting in server.properties.

Functions run all their commands in a single Minecraft:tick and other functions called from within also run their commands in the same tick as their parent. The total number of commands run inside a function obeys Template:Cmd, which is 65,536 commands by default; any commands beyond this limit are ignored.

Functions use the execution context of whatever is invoking the function. This includes executing entity, as well as execution position, rotation, dimension, and anchor. Contextual parameters are preserved for every command in the function. An Template:Cmd command can change the context, but that change does not carry through to any following commands in the same function.

For example: <syntaxhighlight lang="mcfunction"> execute as @p at @s run function foo:bar </syntaxhighlight> Where, the function foo:bar is: <syntaxhighlight lang="mcfunction"> teleport @s ~ ~5 ~ setblock ~ ~-1 ~ emerald_block execute at @s run setblock ~ ~-1 ~ diamond_block </syntaxhighlight> When invoked, this function teleports the nearest player 5 blocks up, places an Minecraft:emerald block one block below their original position before the teleport, and then places a Minecraft:diamond block one block below their new position after the teleport.

As seen in the above example, contextual parameters can be changed as usual by their respective Template:Cmd sub-commands.

Execution order

The order that functions get executed within a single tick is:

1. Functions invoked from advancements.
2. Functions invoked from enchantments.
3. Functions that belong to Template:Cd, from top to bottom.
4. Functions that are scheduled on that tick, from whichever one was added to the queue first.
5. Functions invoked from command blocks and by players

In addition, upon (re)loading a data pack, Template:Cd is executed before any of the ones above.

Macros

Functions can include macro lines, lines preceded by $. Macro lines act similar to normal commands but can reference the compound Minecraft:NBT tag provided when invoking the function with the Template:Cmd command. Values from this compound tag can be referenced with their associated key by using $(<key>) anywhere in the macro line.

Macro lines are evaluated each time before the function executes, substituting the variable specifications with the associated values and parsing the resulting command. The compound tag provided must contain one entry for each variable used in the macro function, but may contain entries not referenced by the macro function. If any variables are not provided, or any commands evaluated from macro lines are unparseable, the entire function is not invoked and no commands in it run.

Valid characters for a <key> are:

• a-z
• A-Z
• 0-9
• _

Tags in the compound tag can be of any type. The method in which the values are inserted vary by type:

• For strings, the value of the string is inserted directly. (That is, without the quotes.)
• For all numeric types, the value is converted to plain text.
  • The type suffix is not included. (For example, 10b is converted to 10)
  • The number is rounded to a maximum of 15 fraction digits.
  • true and false are equivalent to 1b and 0b, so they are converted to 1 and 0 respectively.
• For lists, compound tags, and the array types, the canonical SNBT representation is used.

For example, running the command: <syntaxhighlight lang="mcfunction"> function foo:bar {key_1:"Example String", key_2:10} </syntaxhighlight> With the function foo:bar being: <syntaxhighlight lang="mcfunction"> say This is a normal non-macro command where $(key_1) does not work $say This is a macro line, using $(key_1)! $teleport @s ~ ~$(key_2) ~ </syntaxhighlight>

Would teleport you 10 blocks up, as well as show in chat the following: <syntaxhighlight lang="text"> [Steve] This is a normal non-macro command where $(key_1) does not work [Steve] This is a macro line, using Example String! </syntaxhighlight>Macro functions can also harness stored Minecraft:NBT data using the with instruction that may follow the function name. The argument succeeding with must specify a NBT source (a block, entity, or Minecraft:command storage) followed by the Minecraft:NBT path of a compound tag.

For example: <syntaxhighlight lang="mcfunction"> execute as @p run function foo:bar2 with entity @s SelectedItem </syntaxhighlight> And the function foo:bar2 is: <syntaxhighlight lang="mcfunction"> $say The player running this function is holding $(count) items with ID $(id)! </syntaxhighlight>

Returning

A function can be forcibly stopped by a Template:Cmd command. Following a Template:Cmd or a forking Template:Cmd command that may terminate, a Template:Cmd command can be restricted to only execute under certain conditions. With this, under different conditions a function can stop at different lines, thus achieving more complex behaviors.

After execution, the function can return a return value and a successfulness. The return value is an integer, and the successfulness is failure or success. If no Template:Cmd command is executed in the function, the function is a void function that does not return any return value or successfulness. With Template:Cmd executed, the function is stopped and its return value and successfulness are set.

If the function is called by a Template:Cmd command, its return value and successfulness is returned to the Template:Cmd command. See also Template:Cmd article for the details.

If the function is called by a Template:Cmd command, its return value is checked whether it is not 0.