Function (Java Edition)

Functions allow players to run lists of commands using text files with the extension .mcfunction. 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 [WORLD_NAME]/data/functions‌ or into [WORLD_NAME]/datapacks/[DATA_PACK_NAME]/data/[NAMESPACE]/functions.‌ For single player, the world folders can be found in .minecraft/saves. 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 custom:example/test will refer to the file located at functions/custom/example/test.mcfunction. 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.

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

Function syntax

Testing the function system. Three /tellraw messages and one /give command were used in this simple 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 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 /gamerule maxCommandChainLength, 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 /execute 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

/function

• Allows players to run a function once.
• The commands in the function are run through the entity or command block that ran the /function command.
• The optional arguments if and unless will make the function only run when the selector was found or not found in the world respectively.
• Usage: /function <name>

/gamerule gameLoopFunction‌

• Runs a function every tick.
• The commands in the function are run through the server.
  • The coordinates from which the "server" executes commands are (0, 0, 0).
• If multiple functions need to be looped, it is possible to insert function commands into this looped function file, put function commands in those functions, etc.
• Usage: /gamerule gameLoopFunction <namespace:path/to/function/file>
• To stop the loop just point gameLoopFunction to a non-existing function: /gamerule gameLoopFunction -, this value is also the default.

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 /function #(namespace):tag.

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

History

release
1.12 {{Extension DPL}}<ul><li>[[Photo|Photo]]<br/>{{exclusive|education}} {{Item | image = Photo EE2.png | renewable = No (unless [[portfolio]] is available) | stackable = }} A '''photo''' is an [[item]] containing a picture taken with a [[camera]].<ref>{{cite|url=https://web.archive.org/web/20210925044841mp_/https://educommunity.minecraft.net/hc/en-us/articles/4407489082644-Feature-Walkthrough-Minecraft-Education-Edition-GOAT-Beta-version-1-17-30-| title = Feature Walkthrough Minecraft: Education Edition GOAT Beta (version 1.17.30)|website=Minecraft: Education Edition Support|date=September 24, 2021}}</ref><ref>{{cite|url=https://education.minecraft.net/en-us/blog/new-update-and-anniversary-for-mee| title = The GOAT Update Celebrates a Minecraft Milestone!|website=Minecraft: Education Edition|date=November 2, 2021}}</ref><ref>{{ytl|2Wd0J-EIfws|GOAT Release Playthrough|Minecraft: Education Edition|December 2, 2021}}</ref> == Obtaining == A photo in a [[portfolio]] can be saved as a photo item by selecting the "Save to Inventory" button underneath it. == Usage == Photos display an image when held in the hand or when placed in an [[item frame]], similarly to [[map]]s. Photos can have captions added to them by renaming them in an [[anvil]] or by adding a caption while they are in a portfolio. Photos can be added to [[book and quill]]s and portfolios by selecting the "Add Photo" button in the book and quill or portfolio. == Data values == === ID === {{ID table |edition=bedrock |shownumericids=y |showforms=y |notshowbeitemforms=y |generatetranslationkeys=y |displayname=Photo |spritetype=item |nameid=photo_item |id=? |form=item |foot=1}} == History == {{History|education}} {{History||1.17.30|snap=1.17.30.2|[[File:Photo EE1.png|32px]] Added photos.}} {{History||1.17.30|snap=release|[[File:Photo EE2.png|32px]] Changed photo texture.}} {{History|foot}} == Gallery == <gallery> Photo Item 1.png|A photo being placed in an item frame. Photo Item 2.png|A photo being saved from a portfolio. Photo Item 3.png|A photo being added to a book and quill. </gallery> == References == {{Reflist}} {{Items}} {{Education Edition}} [[Category:Education Edition items]] [[Category:Non-renewable resources]] [[ja:写真]] [[zh:相片]]</li><li>[[Rabbit Stew|Rabbit Stew]]<br/>{{Item | title = Rabbit Stew | heals = {{hunger|10}} | renewable = Yes | stackable = No }} '''Rabbit stew''' is a [[food]] [[item]] that can be eaten by the [[player]]. == Obtaining == === Crafting === {{Crafting |shapeless=true |B1=Cooked Rabbit |A2=Carrot |B2=Baked Potato |C2=Any Mushroom |B3=Bowl |Output=Rabbit Stew |type=Foodstuff }} === Trading === {{IN|bedrock}}, novice-level Butcher villagers always offer to sell rabbit stew for one emerald as their second trade. {{IN|java}}, novice-level Butcher villagers have a 50% chance of offering rabbit stew for one emerald. == Usage == === Food === To eat rabbit stew, press and hold {{control|use}} while it is selected in the hotbar. Eating one restores {{hunger|10}} [[hunger]] and 12 hunger [[Hunger#Mechanics|saturation]]. This restores more hunger than any other food type in the game except [[cake]], but has less saturation than a [[golden carrot]], a [[cooked porkchop]], or a [[steak]]. Eating rabbit stew leaves the player with an empty bowl, similar to [[mushroom stew]], [[suspicious stew]], and [[beetroot soup]]. === Wolves === {{IN|bedrock}}, rabbit stew can be used to feed [[wolves]], healing them by {{hp|10|mob=1}}. However, unlike other wolf food, rabbit stew does not speed up the growth of baby wolves, and it cannot be used to breed them. It is usable only on a wolf that has less than full health. == Sounds == {{Sound table/Entity/Food}} == Data values == === ID === {{edition|java}}: {{ID table |edition=java |showforms=y |generatetranslationkeys=y |displayname=Rabbit Stew |spritetype=item |nameid=rabbit_stew |form=item |foot=1}} {{edition|bedrock}}: {{ID table |edition=bedrock |shownumericids=y |showforms=y |notshowbeitemforms=y |generatetranslationkeys=y |displayname=Rabbit Stew |spritetype=item |nameid=rabbit_stew |id=290 |form=item |foot=1}} == Advancements == {{load advancements|Husbandry;A Balanced Diet}} == Video == <div style="text-align:center">{{yt|GwCqwtydRBc}}</div> == History == {{History|java}} {{History||1.8|snap=June 30, 2014|slink={{tweet|TheMogMiner|483725253018157057}}|[[Ryan Holtz]] tweets the recipe of rabbit stew, and that it can restore hunger better than any other item other than [[golden apple]]s (which was incorrect, as golden apples restore less hunger, but a whole [[cake]] restores more).}} {{History|||snap=14w27a|[[File:Rabbit Stew JE1 BE1.png|32px]] Added rabbit stew.}} {{History||1.13|snap=17w47a|Prior to [[1.13/Flattening|''The Flattening'']], this [[item]]'s numeral ID was 413.}} {{History||1.14|snap=18w43a|[[File:Rabbit Stew JE2.png|32px]] The texture of rabbit stew has been changed. |The rabbit stew's [[recipe]] is now shapeless.}} {{History|||snap=18w50a|[[File:Rabbit Stew JE3 BE2.png|32px]] The texture of rabbit stew has been changed.}} {{History|||snap=19w11a|Butcher [[villager]]s now [[trading|sell]] rabbit stew.}} {{History|pocket alpha}} {{History||v0.13.0|snap=build 1|[[File:Rabbit Stew JE1 BE1.png|32px]] Added rabbit stew.}} {{History|bedrock}} {{History||1.10.0|snap=beta 1.10.0.3|[[File:Rabbit Stew JE3 BE2.png|32px]] The texture of rabbit stew has been changed. |The recipe for rabbit stew is now shapeless.}} {{History||1.11.0|snap=beta 1.11.0.4|Butcher [[villager]]s now [[trading|sell]] rabbit stew.}} {{History|console}} {{History||xbox=TU31|xbone=CU19|ps=1.22|wiiu=Patch 3|switch=1.0.1|[[File:Rabbit Stew JE1 BE1.png|32px]] Added rabbit stew.}} {{History||xbox=none|xbone=none|ps=1.90|wiiu=none|switch=none|[[File:Rabbit Stew JE3 BE2.png|32px]] The texture of rabbit stew has been changed. |The recipe for rabbit stew is now shapeless.}} {{History|new 3ds}} {{History||0.1.0|[[File:Rabbit Stew JE1 BE1.png|32px]] Added rabbit stew.}} {{History|foot}} == Issues == {{issue list}} == Trivia == * If the ingredients of rabbit stew were eaten separately and the [[mushroom]] had become half of a [[mushroom stew]], they would restore a total of {{Hunger|16}} and 19.2 saturation points. Without counting the mushroom, the separate ingredients would restore {{Hunger|13}} and 15.6 saturation points. Therefore, crafting rabbit stew results in a net loss of restorative points, though it is quicker than eating all the ingredients separately. * Rabbit stew restores more hunger and total food points (hunger + saturation) than nearly any other single item (the exception is a suspicious stew with Saturation). This is balanced by the point that the stew does not stack, and with its complex recipe it's not so easy to make "on the road". The suspicious stew shares the unstackability, but with only four ingredients it can at least be crafted in the inventory. ==Gallery== <gallery> Rabbit Stew Crafting.jpg|Crafting rabbit stew. </gallery> == References == {{Reflist}} {{items}} [[de:Kaninchenragout]] [[es:Estofado de conejo]] [[it:Stufato di coniglio]] [[fr:Ragoût de lapin]] [[ja:ウサギシチュー]] [[ko:토끼 스튜]] [[nl:Konijnenstoofpot]] [[pl:Gulasz z królika]] [[pt:Ensopado de coelho]] [[ru:Тушёный кролик]] [[uk:Тушкований кролик]] [[zh:兔肉煲]] [[Category:Food]] [[Category:Renewable resources]]</li></ul>		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 {{Extension DPL}}<ul><li>[[:Category:Dyes|Category:Dyes]]<br/>These are items that can be used to dye sheep, wool blocks, or combined to make other dyes. [[Category:Items]] [[es:Categoría:Tintes]] [[fr:Catégorie:Teinture]] [[hu:Kategória:Festékek]] [[zh:Category:染料]]</li><li>[[:Category:Minecraft Legends resources|Category:Minecraft Legends resources]]<br/>[[Category:Minecraft Legends]] [[Category:Items]] [[pt:Categoria:Recursos do Minecraft Legends]]</li></ul>		17w43a			Custom functions have been moved into data packs.
		17w45a			Functions are now completely parsed and cached on load.
		17w49b			Function can now be tagged.
					Functions tagged in minecraft:tick now run every tick in the beginning of the tick.

Issues

Issues relating to "Function (Java Edition)" are maintained on the bug tracker. Report issues there.