Function (Java Edition)
If this move affects many pages or may potentially be controversial, do not move the page until a consensus is reached. [discuss]
When moving, be sure to use the appropriate tool instead of simply copying and pasting the page's contents, to preserve edit history.
Functions allow players to run lists of commands using text files with the extension .mcfunction
. It is recommended to use ANSI encoding (without BOM) for function files to prevent any problems. This page covers how to use functions in Java Edition.
Contents
Usage[edit]
To utilize functions, a text file [FUNCTION_NAME].mcfunction
may be placed in the folder [WORLD_NAME]/datapacks/[DATA_PACK_NAME]/data/[NAMESPACE]/functions
. To execute the function, use the fully qualified function name, which is [NAMESPACE]:[FUNCTION_NAME]
. If there's no ambiguity with other datapacks or with an existing minecraft command, you can just use [FUNCTION_NAME]
. 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 can also be placed into subfolders within the functions
folder. It is also necessary to have a pack.mcmeta file in the [DATA_PACK_NAME] folder. For example, running the function custom:example/test
will refer to the file located at data/custom/functions/example/test.mcfunction
.
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 /function
, a message will display in the chat: Executed [amount] command(s) from function '[function file directory]'. Embedded functions won't display this chat messsage. 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 /execute store
command).
In a singleplayer or a LAN world, like a 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.
Function syntax[edit]
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 beginning a line with #
.
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]
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. This command context is preserved for all the commands in the function, so a /setblock
command will use the saved position context even when a previous command in the same function teleported the original executor to a different position. For example:
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.
As seen in the above example, the command context can be updated as usual by their respective /execute
sub-commands.
It is suggested to use @s
target selector for the most frequently used entity in a function and use /execute as
when calling that function to modify the executor entity to that most frequently used entity. This can simplify content if the entity was selected with target selector arguments and improve performance in general for the reduced iteration through the world entity list.
There are several methods of running a function file in-game:
Commands[edit]
- Allows players to run a function or all functions in a function tag once.
- Uses the command environment of whatever called the
/function
command. - Initial command environment may be modified by the
/execute
command. - Usage:
/function <name>
Advancements[edit]
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[edit]
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 /function #(namespace):(tag)
.
Functions tagged in tick
will automatically run every tick at the beginning of the tick. Functions tagged in load
will run after (re)loading the datapack.
- Note:
tick
will run beforeload
after reloading the datapack. This means that you can't inherently rely on a stable state of the datapack for the first tick.
History[edit]
Java Edition | |||||
---|---|---|---|---|---|
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. | ||||
1.13 | 17w43a | Custom functions have been moved into data packs. | |||
17w45a | Functions are now completely parsed and cached on load. | ||||
17w49b | Removed /gamerule gameLoopFunction . | ||||
Function can now be tagged. | |||||
Functions tagged in tick now run every tick in the beginning of the tick. | |||||
18w01a | Functions tagged in load now run after (re)loading the datapack. | ||||
1.14.4 | pre4 | Added function-permission-level to server.properties |
Issues[edit]
Issues relating to "Function" are maintained on the bug tracker. Report issues there.
References[edit]
Versions | |||
---|---|---|---|
Development |
| ||
Technical |
| ||
Multiplayer | |||
Game customization |
Components |
|
---|---|
Tutorials |