Function (Java Edition)

Functions are data pack files, allowing players to run lists of commands. Being text files, they are easily modifiable and less likely than command blocks to induce lag when used in large quantities.

This page covers how functions are defined and invoked in Java Edition.

Definition[]

A function is a text file with the file extension .mcfunction. The recommended encoding for function files is ANSI or UTF-8, without BOM.

As with all other data pack files, the functions 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 (/). Players can add comments within the function text file by beginning a line with #. Multiple spaces between command arguments are not allowed but a line can have tabs and spaces before and after the command.

Allowed commands[]

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 still obey /gamerule maxCommandChainLength, which is 65,536 commands by default; any commands beyond this limit are ignored.

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.

Invocation[]

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

Invocation from commands[]

Functions can be invoked using the /function command.

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

Unlike other data pack files, functions are supported by tags, allowing them to be grouped together. /function also accepts a function tag's resource location, invoking all listed functions.

Invocation from 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:subfolder/function"
  }
}

Invocation from function tags[]

Functions can be grouped together using 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 target selectors do not find players. Therefore, commands like /tellraw and /title do not appear for any player.
• Functions listed in the minecraft:tick tag run at the beginning of each tick, repeating every tick.

Note: The first instance of functions tagged minecraft:tick run before minecraft:load runs. This means that when reloading or loading, the order of execution is tick, load, tick, tick, tick, …

When invoked[]

Functions run all their commands in a single tick and other functions called from within also run their commands in the same tick as their parent. Functions use the execution context of whatever called 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 /execute command can change the context, but that change does not carry through to any following commands in the same function.

For example:

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

# function foo:bar
teleport @s ~ ~5 ~
setblock ~ ~-1 ~ emerald_block
execute at @s run setblock ~ ~-1 ~ diamond_block

When invoked, this function teleports the nearest 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, contextual parameters can be changed as usual by their respective /execute sub-commands.

History[]

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
Upcoming Java Edition
1.20.2		23w31a			A single backslash \ as the last non-whitespace character of a line now allows a command to be continued on the next line.
					Functions can now contain macro lines, making them Function Macros.
		1.20.2 Pre-release 1			Numbers used as macro arguments are now always inserted without suffixes, regardless of numeric type.

Issues[]

Issues relating to "Function" are maintained on the bug tracker. Report issues there.

References[]

Minecraft: Java Edition
Versions	Demo Locations PC Gamer Demo (Beta 1.3)
Development	Version history Pre-Classic Classic Early Classic Creative Multiplayer Test Survival Test Late Classic Creative Indev Infdev Alpha Beta Full Release Development versions Removed features Blocks Items Unused features Exclusive features Mentioned features Sky dimension Planned versions
Technical	Known bugs Minecraft Launcher Hardware requirements al_version Block entity Commands Functions Crashes Data values Classic Indev Pre-flattening Data version Debug screen Formatting codes Heightmap Key codes Minecraft Launcher Protocol version Resource location Screenshot Seed Statistics Tick Spawn chunk Coordinates .minecraft client.jar client.json launcher_profiles.json options.txt Development resources Anvil file format Chunk format Command storage format Entity format Generated structures format Level format Loot tables Map item format Model NBT format Obfuscation map Player format raids.dat format Raw JSON text format Region file format Structure block file format Schematic file format Scoreboard format Server list format sounds.json Subtitles villages.dat format Legacy development resources Classic level format Classic server protocol Indev level format Alpha level format Infdev 20100624 level format server_level.dat
Multiplayer	Server Minecraft Realms Server list server.properties Server requirements
Game customization	Skins Capes Resource packs Data packs

Data packs
Components	Advancements Functions Item modifiers Loot tables Predicates Recipes Structure templates Tags World generation Dimensions Dimension types World presets Density functions Biomes Carvers Features Structures
Data packs	Caves & Cliffs Prototype Data Pack
Tutorials	Installing a data pack Creating a data pack