User:Nixinova/Function

Functions allow players to run lists of commands using text files with the extension .mcfunction. Being text files, functions are easily modifiable and less likely than command blocks to induce lag when used in large quantities.

Function syntax[edit | edit source]

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. However, the total number of commands run inside a function is limited. Functions obey /gamerule maxCommandChainLength in Java Edition, which is 65,536 commands by default, and have a maximum of 10,000 in Bedrock Edition. Any commands beyond this limit are ignored.

It is recommended to use ANSI encoding (without a byte order mark) for function files to prevent any problems.

The execution location does not move with the executor if it is teleported in a function. So if a function is executed as and at an entity‌^{[JE only]} or at ~ ~ ~,‌^{[BE only]} teleports the executor away and then sets a block at ~ ~ ~, the block would be at the original execution location. To target the new location a new execute command is needed.

File location[edit | edit source]

Java Edition[edit | edit source]

To create a function, a text file [FUNCTION_NAME].mcfunction may be placed in the folder .minecraft/saves/[WORLD_NAME]/datapacks/[DATA_PACK_NAME]/data/[NAMESPACE]/functions.

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.

Bedrock Edition[edit | edit source]

In Bedrock Edition, function files must be placed into a top-level folder named "functions" within a behavior pack, located at com.mojang/behavior_packs/[BEHAVIOR_PACK_NAME]/functions.

Subfolders can be added to this folder to serve as namespaces. For example, the function sub/foo refers to the file located at [BEHAVIOR_PACK_NAME]/functions/sub/foo.mcfunction.

Invocation[edit | edit source]

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, just [FUNCTION_NAME] may be used instead. If the namespace is left out when trying to call a function, it will default to the minecraft: namespace. Using a custom namespace in Java Edition is recommended in order to prevent unintended behavior in the case of future additions to the default namespace.^[1]

Upon successfully running /function, a message will display in the chat: Executed [amount] command(s) from function '[file path]'. 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).

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.

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 in Java Edition, a function can run any command that is no more restrictive than the permission level prescribed in function-permission-level setting in server.properties.

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.

If a function is updated while the player is still in-game, the /reload command is used to alert the game that the function files have been changed. In Bedrock Edition, the game must be restarted if new functions are added, as the command only reloads functions already known to the game.

Methods[edit | edit source]

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

Commands[edit | edit source]

/function <name>

• 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.

Advancements[edit | edit source]

This feature is exclusive to Java Edition. 

In Java Edition, 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 | edit source]

This feature is exclusive to Java Edition. 

In Java Edition, 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 before load after reloading the datapack. This means that you cannot inherently rely on a stable state of the datapack for the first tick.

Engine version[edit | edit source]

This feature is exclusive to Bedrock Edition. 

In Bedrock Edition, functions require a minimum engine version specified as min_engine_version in the pack manifest.json file. This field determines which version of a command to run. The number specified here should match the version number of the game. For example, say that /fill was changed in 1.9.0. If the behavior pack has "min_engine_version": [1, 8, 0] and runs a function that contains /fill, it runs the older version of fill (as if the version was still 1.8.0).

Manifest example[edit | edit source]

{
  "format_version": 1,
  "header": {
    "description": "Function worldedit",
    "name": "Function worldedit",
    "uuid": "11111111-1111-1111-1111-111111111111",
    "version": [1, 11, 3],
    "min_engine_version": [1, 11, 3]
  },
  "modules": [
    {
      "description": "",
      "type": "data",
      "uuid": "22222222-2222-2222-2222-222222222222",
      "version": [1, 11, 3]
    }
  ]
}

History[edit | edit source]

{"type": "java", "version": "1.12", "exp": "", "snap": "pre1", "content": "Added functions."}

{"type": "java", "version": "1.12", "exp": "", "snap": "pre3", "content": "Commands are no longer allowed to begin with a / (forward slash)"}

{"type": "java", "version": "1.12", "exp": "", "snap": "pre3", "content": "Comments can now only be preceded with #; using // is no longer allowed"}

{"type": "java", "version": "1.12", "exp": "", "snap": "pre4", "content": "Added new arguments to the <!-- Command --><code ><span>/(link to Commands/function article, displayed as function)</span></code><!-- /Command --> command: <code>[if|unless] [selector]</code>"}

{"type": "java", "version": "1.12", "exp": "", "snap": "pre6", "content": "Skipped functions (when a conditional fails) are now considered failures when used in commands."}

{"type": "java", "version": "1.13", "exp": "", "snap": "17w43a", "content": "Custom functions have been moved into data packs."}

{"type": "java", "version": "1.13", "exp": "", "snap": "17w45a", "content": "Functions are now completely parsed and cached on load."}

{"type": "java", "version": "1.13", "exp": "", "snap": "17w49b", "content": "Removed <!-- Command --><code ><span>/(link to Commands/gamerule article, displayed as gamerule) gameLoopFunction</span></code><!-- /Command -->."}

{"type": "java", "version": "1.13", "exp": "", "snap": "17w49b", "content": "Function can now be tagged."}

{"type": "java", "version": "1.13", "exp": "", "snap": "17w49b", "content": "Functions tagged in <code>tick</code> now run every tick in the beginning of the tick."}

{"type": "java", "version": "1.13", "exp": "", "snap": "18w01a", "content": "Functions tagged in <code>load</code> now run after (re)loading the datapack."}

{"type": "java", "version": "1.14.4", "exp": "", "snap": "pre4", "content": "Added <code>function-permission-level</code> to (link to server.properties article, displayed as server.properties)"}

{"type": "bedrock", "version": "1.8.0", "exp": "", "snap": "beta 1.8.0.8", "content": "Added function files."}

{"type": "bedrock", "version": "1.8.0", "exp": "", "snap": "beta 1.8.0.8", "content": "Function files are available only in behavior packs."}

{"type": "bedrock", "version": "1.13.0", "exp": "", "snap": "beta 1.13.0.1", "content": "Function files are now visible in command list."}

Issues[edit | edit source]

Issues relating to "Function" are maintained on the bug tracker. Issues should be reported and viewed there.

References[edit | edit source]