Function (Java Edition)

This article is about functions in Java Edition. For functions in Bedrock Edition, see Function.

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]/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 data/custom/functions/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>

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

Java Edition
1.12 {{Extension DPL}}<ul><li>[[Obsidian Boat|Obsidian Boat]]<br/>{{for|other uses|Obsidian (disambiguation)}} {{for|other kinds of boats|Boat (disambiguation)}} {{Joke feature}} {{ItemEntity |title=Obsidian Boat |image=Obsidian Boat.png |image2=Obsidian Boat (item).png |stackable=No |renewable=Yes }} The '''obsidian boat''' was a joke [[boat]] variant released in an April Fools' joke version. == Obtaining == === Crafting === {{crafting |A2 = Obsidian |C2 = Obsidian |A3 = Obsidian |B3 = Obsidian |C3 = Obsidian |Output= Obsidian Boat |ignoreusage=1 }} == Usage == Obsidian boats sank in [[water]] instead of floating. They also sank in lava like other boats but did not get destroyed in it. == Sounds == Obsidian boats used the Friendly Creatures sound category for entity-dependent sound events, although did not have any sounds of their own. == Data values == === ID === {{ID table |shownumericids=y |showforms=y |generatetranslationkeys=java |displayname=Obsidian Boat |spritetype=item |nameid=obsidian_boat |id=432 |form=item |translationkey=item.obsidian_boat.name |foot=1}} {{ID table |shownumericids=y |generatetranslationkeys=java |displayname=Obsidian Boat |spritetype=entity |nameid=boat |id=41 |translationkey=entity.Boat.name |foot=1}} === Entity data === {{/ED}} == History == {{History|java}} {{History||1.10|snap=15w14a|link=Java Edition 15w14a|[[File:Obsidian_Boat_(item).png|32px]] [[File:Obsidian Boat.png|32px]] Added the obsidian boat.}} {{History|foot}} == Issues == Obsidian boat is a joke feature and as such issues relating to them cannot be fixed. {{Items}} {{Entities}} {{Jokes}} [[Category:Joke items]] [[Category:Joke entities]] [[it:Barca di ossidiana]] [[ja:黒曜石のボート]] [[pt:Bote de obsidiana]] [[uk:Обсидіановий човен]] [[zh:15w14a]]</li><li>[[Poisonous Potato|Poisonous Potato]]<br/>{{Item | title = Poisonous Potato | image = Poisonous Potato.png | heals = {{hunger|2}} |effects={{EffectLink|Poison}} (0:05) (60% chance) | stackable = Yes (64) | renewable = Yes }} A '''poisonous potato''' is a type of [[potato]] that can [[poison]] the [[player]]. == Obtaining == The poisonous potato is a rare [[drop]] when harvesting (destroying) [[potato|potato crops]]; a fully grown plant has a 2% chance of dropping one in addition to the 2-5 regular potatoes. === Chest loot === {{LootChestItem|poisonous-potato}} == Usage == Poisonous potatoes cannot be planted on [[farmland]] or [[Baked Potato|baked]]. They also have no use with the [[composter]].<ref>{{bug|MC-142373|resolution=WAI}}</ref> === Food === {{see also|Tutorials/Hunger management|title1=Hunger management}} To eat a poisonous potato, press and hold {{control|use}} while it is selected in the hotbar. Eating one restores {{hunger|2}} [[hunger]] and 1.2 hunger [[Hunger#Mechanics|saturation]] and has a 60% chance of applying 5 seconds of [[Poison]] II, draining {{hp|4|poisoned=1}} points of [[health]]. Interestingly, a poisonous potato actually restores double the hunger and saturation than a normal, unpoisoned potato. (A normal potato gives {{hunger|1}} hunger and 0.6 saturation points.) ==Sounds== {{Sound table/Entity/Food}} == Advancements == {{load advancements|Husbandry;A Balanced Diet}} == Data values == === ID === {{edition|java}}: {{ID table |edition=java |showforms=y |generatetranslationkeys=y |displayname=Poisonous Potato |spritetype=item |nameid=poisonous_potato |form=item |foot=1}} {{edition|bedrock}}: {{ID table |edition=bedrock |shownumericids=y |showforms=y |notshowbeitemforms=y |generatetranslationkeys=y |displayname=Poisonous Potato |spritetype=item |nameid=poisonous_potato |id=282 |form=item |foot=1}} == History == {{History|java}} {{History||1.4.2|snap=12w34a|[[File:Poisonous Potato JE1 BE1.png|32px]] Added poisonous potatoes.}} {{History||1.13|snap=17w47a|Prior to [[Java_Edition_1.13/Flattening|''The Flattening'']], this [[item]]'s numeral ID was 394.}} {{History|||snap=18w11a|Poisonous potatoes now generate in the [[chest]]s of [[shipwreck]]s.}} {{History||1.14|snap=18w43a|[[File:Poisonous Potato JE2.png|32px]] The texture of poisonous potatoes has been changed.}} {{History|||snap=18w50a|[[File:Poisonous Potato JE3 BE2.png|32px]] The texture of poisonous potatoes has been changed, once again.}} {{History|pocket alpha}} {{History||v0.12.1|snap=build 1|[[File:Poisonous Potato JE1 BE1.png|32px]] Added poisonous potatoes.}} {{History|bedrock}} {{History||1.4.0|snap=beta 1.2.14.2|Poisonous potatoes can now be found inside of [[shipwreck]] [[chest]]s.}} {{History||1.10.0|snap=beta 1.10.0.3|[[File:Poisonous Potato JE3 BE2.png|32px]] The texture of poisonous potatoes has been changed.}} {{History|console}} {{History||xbox=TU14|xbone=CU1|ps=1.04|wiiu=Patch 1|switch=1.0.1|[[File:Poisonous Potato JE1 BE1.png|32px]] Added poisonous potatoes.}} {{History||xbox=none|xbone=none|ps=1.90|wiiu=none|switch=none|[[File:Poisonous Potato JE3 BE2.png|32px]] The texture of poisonous potatoes has been changed.}} {{History|New 3DS}} {{History||0.1.0|[[File:Poisonous Potato JE1 BE1.png|32px]] Added poisonous potatoes.}} {{History|foot}} == Issues == {{issue list}} == References == {{reflist}} {{Items}} [[Category:Plants]] [[cs:Jedovatá brambora]] [[de:Giftige Kartoffel]] [[es:Patata envenenada]] [[fr:Pomme de terre empoisonnée]] [[hu:Mérgező burgonya]] [[it:Patata velenosa]] [[ja:青くなったジャガイモ]] [[ko:독이 있는 감자]] [[nl:Giftige aardappel]] [[pl:Trujący ziemniak]] [[pt:Batata venenosa]] [[ru:Ядовитый картофель]] [[th:มันฝรั่งพิษ]] [[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>[[Knowledge Book|Knowledge Book]]<br/>{{exclusive|java}} {{Item | image = Knowledge Book.png | renewable = No | stackable = No | rarity = Epic }} A '''knowledge book''' is a utility item that reveals available [[crafting]] recipes to the player when {{control|used|use}}. == Obtaining == Knowledge books can be obtained only by using [[commands]], as it is not found in the [[creative]] inventory; therefore, it is impossible to obtain in other modes such as [[survival]] and [[adventure]] except with commands. For example, to give oneself a knowledge book that reveals the recipes for [[bucket]]s and [[flower pot]]s, use: {{cmd|give @s minecraft:knowledge_book{Recipes:["minecraft:bucket", "minecraft:flower_pot"]} }}. == Usage == Knowledge books are used to reveal recipes to the player who uses it, by adding it to their [[recipe book]]. Using a knowledge book consumes it, removing it from the player's inventory. Knowledge books are especially useful to mapmakers in conjunction with {{cmd|gamerule doLimitedCrafting true}}, because then any item is craftable only if its recipe is unlocked first. == Sounds == {{Sound table |sound=Chiseled bookshelf insert1.ogg |sound2=Chiseled bookshelf insert2.ogg |sound3=Chiseled bookshelf insert3.ogg |sound4=Chiseled bookshelf insert4.ogg |subtitle=Book placed |source=block |description=When a knowledge book is placed in a chiseled bookshelf |id=block.chiseled_bookshelf.insert |translationkey=subtitles.chiseled_bookshelf.insert |volume=0.8 |pitch=''varies'' <ref group=sound>Can be 1.0, 0.85, or 1.1 for each sound</ref> |distance=16}} {{Sound table |sound=Chiseled bookshelf pickup1.ogg |sound2=Chiseled bookshelf pickup2.ogg |sound3=Chiseled bookshelf pickup3.ogg |subtitle=Book taken |source=block |description=When a knowledge book is removed from a chiseled bookshelf |id=block.chiseled_bookshelf.pickup |translationkey=subtitles.chiseled_bookshelf.take |volume=0.8 |pitch=''varies'' <ref group=sound>Can be 1.0, 0.8, or 1.1 for each sound</ref> |distance=16 |foot=1}} == Data values == === ID === {{ID table |edition=java |showforms=y |generatetranslationkeys=y |displayname=Knowledge Book |spritetype=item |nameid=knowledge_book |form=item |foot=1}} === Item data === Recipe books use the NBT tag <code>Recipes</code> to indicate the recipes they contain. ''The following NBT structure is provided to show how the <code>Recipes</code> tag is organized, and is not comprehensive above the <code>tag</code> tag. The full NBT for an item can be found [[Chunk format#Items and XP Orbs|here]].'' <div class="treeview" style="margin-top: 0;"> * {{nbt|compound}} Entity data ** {{nbt|compound|Item}}: The item *** {{nbt|compound|tag}}: Additional information about the item. This tag is optional for most items. **** {{nbt|list|Recipes}}: The list of recipes this book contains. ***** {{nbt|string}} the name of a recipe, for instance <code>minecraft:gold_nugget</code> or <code>minecraft:gold_ingot_from_nuggets</code> </div> == History == {{History|java}} {{History||1.12|snap=17w13a|[[File:Knowledge Book JE1.png|32px]] Added knowledge books.}} {{History||1.13|snap=17w47a|Prior to [[1.13/Flattening|''The Flattening'']], this [[item]]'s numeral ID was 453.}} {{History||1.14|snap=18w43a|[[File:Knowledge Book JE2.png|32px]] The texture of knowledge books has now been changed.}} {{History||1.20|snap=1.20 Release Candidate 1|Knowledge books can now be placed in [[chiseled bookshelf|chiseled bookshelves]].}} {{History|Foot}} == Issues == {{Issue list}} == See also == * [[Book]] * [[Enchanted Book]] * {{cmd|recipe}} command {{Items}} [[Category:Non-renewable resources]] [[de:Buch des Wissens]] [[es:Enciclopedia]] [[fr:Livre des connaissances]] [[ja:知恵の本]] [[ko:지식의 책]] [[lzh:天工開物]] [[pl:Księga wiedzy]] [[pt:Enciclopédia]] [[ru:Книга знаний]] [[zh:知识之书]]</li><li>[[Totem of Undying|Totem of Undying]]<br/>{{redirect|Totem}} {{Item | image = Totem_of_Undying_JE2_BE2.png | renewable = Yes | stackable = No | rarity = Uncommon |effects=: {{EffectLink|Absorption}} II (0:05) : {{EffectLink|Regeneration}} II (0:45){{only|java|short=yes}}/ II (0:40){{only|bedrock|short=yes}} : {{EffectLink|Fire Resistance}} I (0:40) }} A '''totem of undying''' is an uncommon [[combat]] item that can save holders from death. It is dropped by [[Evoker|evokers]], which spawn in [[woodland mansion]]s and [[raid]]s. == Obtaining == === Mob loot === Evokers always drop one totem of undying upon death. The drop rate is not affected by [[Looting]]. == Usage == [[File:Totem of Undying Animation.gif|alt=The totem animation in Java Edition.|thumb|Animation of the totem activating {{in|java}}.]] [[File:Totem of Undying Bedrock Animation.gif|alt=The totem animation in Bedrock Edition.|thumb|Animation of the totem activating {{in|bedrock}}.]] If the [[player]] is holding a totem of undying in their [[off-hand]] or main-hand slot and receives otherwise fatal [[damage]], the totem saves the player from [[death]]. The totem of undying must be in the player's hand (main hand or offhand) for it to work—it does not work if it is in the [[Heads-up display#Hotbar|hotbar]], unless selected. Any [[mob]] that can hold a totem of undying (in a hand or in the mouth) can use it while holding it.{{only|JE}} The totem can be used only once; it disappears after use. It does not save the player from death caused by [[void]] damage, the {{cmd|kill}} [[command]]s or even a [[tipped arrow]] with [[Instant Damage|harming]] effect damage.<ref>{{bug|MC-206307}}</ref> == Effect == When activated, the totem of undying restores {{hp|1}}, removes all existing [[status effect]]s, then grants 40{{only|bedrock|short=1}} or 45{{only|java|short=1}} seconds<ref>{{bug|MCPE-90716}}</ref> of [[Regeneration]] II, 40 seconds of [[Fire Resistance]] I and 5 seconds of [[Absorption]] II. An animation shows the totem of undying appearing to hover in front of the [[player]]'s screen, similar to the animation seen when a player receives the [[Bad Omen]] or [[Hero of the Village]] effect{{only|bedrock|short=1}} or encounters an [[elder guardian]]. When killed by an [[Instant Damage]] tipped [[arrow]], the arrow's instant damage takes effect after the totem has been activated. The totem of undying also works in [[Hardcore]] mode. == Sounds == {{edition|java}}: {{Sound table |sound=Totem of Undying.ogg |subtitle=Totem activates |source=dependent |description=When something dies, using a totem of undying |id=item.totem.use |translationkey=subtitles.item.totem.use |volume=1.0 |pitch=1.0 |distance=16 |foot=1}} {{edition|bedrock}}: {{Sound table |type=bedrock |sound=Totem of Undying.ogg |source=player |description=When something dies, using a totem of undying |id=random.totem |volume=1.0 |pitch=1.0 |foot=1}} == Data values == === ID === {{edition|java}}: {{ID table |edition=java |showforms=y |generatetranslationkeys=y |displayname=Totem of Undying |spritetype=item |nameid=totem_of_undying |form=item |foot=1}} {{edition|bedrock}}: {{ID table |edition=bedrock |showaliasids=y |shownumericids=y |showforms=y |notshowbeitemforms=y |generatetranslationkeys=y |displayname=Totem of Undying |spritetype=item |nameid=totem_of_undying |aliasid=totem |id=568 |form=item |translationkey=item.totem.name |foot=1}} == Achievements == {{load achievements|Cheating Death}} == Advancements == {{load advancements|Postmortal}} == History == {{History||2016|[[File:Totem of Undying (pre-release).png|32px]] An early version of the totem of undying was seen during Minecon shortly before its reveal.}} {{History|java}} {{History||1.11|snap=16w39a|[[File:Totem of Undying JE1 BE1.png|32px]] Added totem of undying.}} {{History||1.11.1|snap=16w50a|The ID name has now been changed from <code>totem</code> to <code>totem_of_undying</code>.}} {{History||1.13|snap=17w47a|Prior to [[1.13/Flattening|''The Flattening'']], this [[item]]'s numeral ID was 449.}} {{History||1.14|snap=18w43a|[[File:Totem of Undying JE2 BE2.png|32px]] The texture of the totem of undying has been changed.}} {{History|||snap=18w47a|The totem of undying is now [[renewable resource|renewable]] as [[evoker]]s now spawn in [[raid]]s.}} {{History||1.16.2|snap=20w28a|The totem of undying now gives the [[Fire Resistance]] II status effect for 40 seconds.}} {{History|||snap=20w29a|The level of Fire Resistance given by the totem of undying is now reduced from II to I.<ref>{{bug|MC-194220}}</ref>}} {{History||1.20.2|snap=23w31a|Totems of undying now trigger [[sculk sensor]]s when they activate.<ref>{{bug|MC-261427||Sculk sensors and calibrated sculk sensors don't detect totem of undying activating|Fixed}}</ref>}} {{History|pocket}} {{History||1.1.0|snap=alpha 1.1.0.0|[[File:Totem of Undying JE1 BE1.png|32px]] Added totem of undying.}} {{History|bedrock}} {{History||1.10.0|snap=beta 1.10.0.3|[[File:Totem of Undying JE2 BE2.png|32px]] The texture of the totem of undying has been changed.}} {{History||1.11.0|snap=beta 1.11.0.3|The totem of undying is now [[renewable resource|renewable]] as [[evoker]]s now spawn in [[raid]]s.}} {{History||1.16.100|snap=beta 1.16.100.54|The level of Fire Resistance given by the totem of undying is now reduced from II to I.<ref>{{bug|MCPE-52364}}</ref>}} {{History||1.16.100|snap=beta 1.16.100.56|The ID of totems of undying has been changed from <code>totem</code> to <code>totem_of_undying</code>.}} {{History|console}} {{History||xbox=TU54|xbone=CU44|ps=1.52|wiiu=Patch 24|switch=1.0.4|[[File:Totem of Undying JE1 BE1.png|32px]] Added totem of undying.}} {{History||xbox=TU56|xbone=CU48|ps=1.55|wiiu=Patch 26|switch=1.0.6|The totem of undying now applies [[Fire Resistance]] II when used.}} {{History||xbox=none|xbone=none|ps=1.90|wiiu=none|switch=none|[[File:Totem of Undying JE2 BE2.png|32px]] The texture of the totem of undying has been changed.}} {{History||xbox=none|xbone=none|ps=1.91|wiiu=none|switch=none|The totem of undying is now [[renewable resource|renewable]] as [[evoker]]s now spawn in [[raid]]s.}} {{History|new3ds}} {{History||1.9.19|[[File:Totem of Undying JE1 BE1.png|32px]] Added totem of undying.}} {{History|foot}} == Issues == {{issue list}} == Trivia == * If a [[mob]] holds a totem of undying, the mob also resurrects upon [[Health#Death|death]] and the [[sound]] effect plays. However, the animation does not appear. * In the {{el|ds}}, the totem of undying can be put in any hotbar slot to activate it, due to the lack of an [[Dual wield|off-hand slot]] in that version. * Being able to obtain totems of undying in [[raids]] without exploring [[woodland mansions]] is considered a "massive game play design flaw" by Mojang.<ref>{{ytl|YRPlscod34Y}}</ref> == Gallery == <gallery> File:Particle totem of undying.png|Screenshot of the totem of undying being used mid-animation after a [[drowned]] deals otherwise fatal damage to the player. File:Totem of Undying activating.gif|Animation of the totem activating. File:Totem animation in third person mode.png|The totem animation in third person mode. </gallery> == References == {{reflist}} {{Items}} [[de:Totem der Unsterblichkeit]] [[fr:Totem d'immortalité]] [[ja:不死のトーテム]] [[ko:불사의 토템]] [[lzh:保命符]] [[nl:Totem der onsterfelijkheid]] [[pl:Totem nieśmiertelności]] [[pt:Totem da imortalidade]] [[ru:Тотем бессмертия]] [[th:Totem of Undying]] [[zh:不死图腾]] [[Category:Renewable resources]]</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.