Function (Java Edition)

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

Usage
To utilize functions, the text files must first be placed into a top-level folder within. For single player, the world folders can be found in. For multiplayer, functions must be placed in every world folder that wants to utilize them (In 1.12 you MUST place the functions inside the main world folder (the one specified in the server.properties, level-name=(world-name here)), otherwise it will NOT work.). The name of the new top-level folder will be the namespace used when running the functions inside. Functions can also be placed into subfolders within the top-level folder.

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

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 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 and  commands).

Function syntax


Within the  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, which is 65,536 commands by default; any commands beyond this limit will be ignored.

Running a function
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. Functions will use the command environment of whatever called the function. This includes command sender, position, rotation, etc.

Changes to the command environment that happen within a function will not affect the command environment used by the other commands within that same function (or within its child functions) until the next iteration, regardless of the order of commands. The command is an exception and will update the command environment.

For example:

1.12

execute @a ~ ~ ~ function foo:bar

foo:bar teleport @s ~ ~5 ~ setblock ~ ~-1 ~ emerald_block execute @s ~ ~ ~ setblock ~ ~-1 ~ diamond_block

1.13

execute as @a at @s run function foo:bar

foo:bar teleport @s ~ ~5 ~ setblock ~ ~-1 ~ emerald_block execute at @s run 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 target selector arguments.

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

Commands

 * Allows players to run a function once.
 * The commands in the function are run through the entity or command block that ran the command.
 * The optional arguments  and   will make the function only run when the   was found or not found in the world respectively.
 * Usage:
 * Usage:

Advancements
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" } }

Tags
Functions can be grouped together using tags in data packs. These tags can then be called to run all the functions inside that tag with.

Functions tagged in  will automatically run every tick at the beginning of the tick. Functions tagged in  will run after (re)loading the datapack.