Function (Java Edition)

This article is about functions in Java Edition. For functions in Bedrock Edition, see Function (Bedrock 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. This page covers how to use functions in Java Edition.

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

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>[[Footprint|Footprint]]<br/>{{about|the joke item|the unused particle|Java Edition unused features#Footprint particle}} {{Joke feature}} {{Item | image = Footprint (item).png | renewable = No | stackable = Yes (64) }} The '''Footprint''' was a joke item from [[Java Edition 20w14∞]], found only in the {{code|missing}} dimension. == Appearance == This item is semi-transparent with a grey colour scheme. == Obtaining == === Dimension === Footprints were obtained only from a chest in the {{Code|missing}} dimension. Only existing in 2020 April fools snapshot 20w14∞, it cannot exist in any non-April Fool's joke versions and April Fool's joke versions before or after 20w14∞. There is a maximum of 2 footprints that can be obtained legitimately in any given world. === Cheats/Creative Mode === Despite these footprints not being available in the creative inventory, it is still possible to acquire them via the command {{Code|code=give <target> minecraft:footprint <amount>}} or duplicating them by holding down middle-click whilst in creative mode. == Usage == As of snapshot 20w14∞, this item cannot be placed or used in any way other than a trophy. This item can be inserted and/or rotated inside of an item frame, and it has a stack limit of 64. == Data values == === ID === {{ID table |showforms=y |generatetranslationkeys=java |displayname=Footprint |spritetype=item |nameid=footprint |form=item |foot=1}} == History == {{History|java}} {{History||20w14∞|[[File:Footprint (item).png|32px]] Added the footprint item.}} {{History|foot}} == Gallery == <gallery> File:Missing biome.png|The Easter Egg dimension that the item spawns in. </gallery> == Trivia == * This is a reference to the removed "Footstep" particle, hence in the "missing" dimension. ** This item is intended as a joke directed towards the commands' community where the "Footstep" particle is commonly requested.<ref>https://gist.github.com/boq/8e65cb85badc75765eeb8956af78aaa5</ref> == References == {{reflist}} {{Items}} {{Jokes}} [[Category:Non-renewable resources]] [[Category:Joke items]] [[es:Footprint]] [[pt:Pegada]]</li><li>[[Portfolio|Portfolio]]<br/>{{exclusive|education}} {{Item | image = Portfolio.png | renewable = No | stackable = Yes (64) }} A '''portfolio''' is an [[item]] that can save [[photo]]s taken with a [[camera]].<ref>https://education.minecraft.net/support/knowledge-base/using-cameras-portfolios/</ref> == Obtaining == Portfolios can be obtained in the creative inventory or through the {{cmd|give}} command. == Usage == [[File:Portfolio Interface.png|thumb|upright=1.5|The portfolio interface]] Once a photo has been taken using the [[camera]], it appears in the portfolio. Once equipped, right-clicking brings up a two-page book of photos the [[player]] has taken, in chronological order. Captions can be added below each picture. Pressing the "Export Portfolio" button creates a .zip file with all photos as JPGs in a specified folder. The portfolio is also used to load custom items in [[Minecraft China]]. == Data values == === ID === {{ID table |edition=bedrock |shownumericids=y |showforms=y |notshowbeitemforms=y |generatetranslationkeys=y |displayname=Portfolio |spritetype=item |nameid=portfolio |id=456 |form=item |foot=1}} == History == {{History|pocket alpha}} {{History||v0.16.0|snap=build 1|[[File:Portfolio BE1.png|32px]] Added portfolios.}} {{History|||snap=build 2|Portfolios have been removed.}} {{History|bedrock}} {{History||1.16.100|Data-driven portfolios, allowing for add-ons to create custom portfolios. Normal Portfolios are still unobtainable.}} {{History|education}} {{History||1.0|[[File:Portfolio BE1.png|32px]] Added portfolios.}} {{History|foot}} == References == {{Reflist}} {{Items}} {{Education Edition}} [[Category:Non-renewable resources]] [[Category:Education Edition items]] [[Category:Storage]] [[de:Fotoalbum]] [[es:Portafolio]] [[ja:ポートフォリオ]] [[ko:포트폴리오]] [[pl:Portfolio]] [[pt:Portfólio]] [[ru:Портфолио]] [[uk:Портфоліо]] [[zh:公文包]]</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>[[Black Dye|Black Dye]]<br/>{{Item | image = Black Dye.png | renewable = Yes | stackable = Yes (64) }} '''Black dye''' is a [[Dye#Primary|primary color dye]] similar to an [[ink sac]]. == Obtaining == === Trading === [[Wandering trader]]s have a chance to [[trading|trade]] 3 black dyes for 1 [[emerald]].{{only|java}} === Crafting === {{Crafting |head=1 |showname=0 |Ink Sac |Output=Black Dye |type=Material }} {{Crafting |Wither Rose |Output=Black Dye |type=Material |foot=1 }} == Usage == {{dye usage}} === Crafting ingredient === {{crafting usage|ignore=Banner|continue=1}} {{banner crafting usage}} === Loom ingredient === {{Banner loom usage|Black Dye}} === Trading === Apprentice-level Shepherd villagers have a 20%{{only|bedrock}} or {{frac|2|7}}{{only|java}} chance to buy 12 black dye for an emerald. == Data values == === ID === {{edition|java}}: {{ID table |edition=java |showforms=y |generatetranslationkeys=y |displayname=Black Dye |spritetype=item |nameid=black_dye |form=item |foot=1}} {{edition|bedrock}}: {{ID table |edition=bedrock |showaliasids=y |shownumericids=y |showforms=y |notshowbeitemforms=y |generatetranslationkeys=y |displayname=Black Dye |spritetype=item |nameid=black_dye |aliasid=dye / 16 |id=395 |form=item |translationkey=item.dye.black_new.name |foot=1}} == History == {{History|java}} {{History||1.14|snap=18w43a|[[File:Black Dye JE1 BE1.png|32px]] Added black dye.}} {{History|||snap=18w44a|Black dyes now can changed the text color on the [[sign]]s to black.}} {{History|||snap=19w05a|Added the [[wandering trader]], which sell black dyes.}} {{History|||snap=19w11a|Black dyes can now be [[trading|bought]] by shepherd villagers.}} {{History||1.15|snap=Pre-release 1|Black dye can now be used to craft [[prismarine|dark prismarine]], just like [[Bedrock Edition]].}} {{History||1.17|snap=20w45a|Black dyes can now used to craft newly added [[black candle]]s.}} {{History|||snap=21w19a|Black dyes can no longer used to craft black candles.}} {{History|||snap=Pre-release 1|Black dyes can once again used to craft black candles.}} {{History||1.20<br>(Experimental)|link=1.19.3|snap=22w42a|Black dyes now can change the text color on [[hanging sign]]s to black.}} {{History|bedrock}} {{History||1.8.0|snap=beta 1.8.0.10|[[File:Black Dye JE1 BE1.png|32px]] Added black dye.}} {{History||1.11.0|snap=beta 1.11.0.4|Black dye can now be [[trading|sold]] to shepherd [[villager]]s.}} {{history||1.13.0|snap=beta 1.13.0.9|Black dye can now be [[crafting|crafted]] from [[flower|wither roses]].}} {{History||1.16.100|snap=beta 1.16.100.56|The ID of black dye has been changed from <code>dye/16</code> to <code>black_dye</code>.}} {{History|ps4}} {{History||1.83|[[File:Black Dye JE1 BE1.png|32px]] Added black dye.}} {{History|foot}} == Issues == {{issue list}} {{Items}} [[Category:Dyes]] [[Category:Renewable resources]] [[de:Schwarzer Farbstoff]] [[es:Tinte negro]] [[fr:Teinture noire]] [[ja:黒色の染料]] [[ko:검은색 염료]] [[pl:Czarny barwnik]] [[pt:Corante preto]] [[th:สีย้อมสีดำ]] [[zh:黑色染料]]</li><li>[[Gold Nugget|Gold Nugget]]<br/>{{About|the nugget|the block that can drop nuggets|Gilded Blackstone|the ore|Gold Ore|the ingot form|Gold Ingot|the mineral block|Block of Gold}} {{Item | image = Gold Nugget.png | renewable = Yes | stackable = Yes (64) }} '''Gold nuggets''' are items used to make [[gold ingot]]s and other various golden items. One gold nugget is effectively worth one-ninth of a gold ingot. == Obtaining == === Mob loot === [[Zombified Piglin|Zombified piglin]]s, when killed, may drop 0-1 gold nuggets. When killed using a weapon enchanted with [[Looting]], they may drop an additional gold nugget per level of Looting used, up to a maximum of 4. === Crafting === {{Crafting |Gold Ingot |Output= Gold Nugget, 9 |type= Material }} === Smelting === {{Smelting |Golden Sword; {Any golden tools}; {Any golden armor}; Golden Horse Armor |Gold Nugget |0,25 }} === Chest loot === {{LootChestItem|gold-nugget}} === Mining === [[Nether gold ore]] mined using a [[pickaxe]] drops 2-6 gold nuggets. If the pickaxe is enchanted with [[Fortune]], it has a 33.3% chance to multiply the drops by 2, Fortune II has a 25% chance to multiply the drops by 2 or 3 and Fortune III has a 20% chance each to multiply the drops by 2, 3, or 4 for a maximum possible drop of 24 golden nuggets. The average drop rate for a Fortune III pickaxe is 8.8, while the drop rate for a [[Silk Touch]] pickaxe is a single ingot, or a flat rate of 9. It is slightly more efficient to mine with a Silk Touch pickaxe. [[Gilded Blackstone|Gilded blackstone]] mined using a pickaxe has a 10% chance to drop 2-5 gold nuggets. If the pickaxe is enchanted with Fortune I, the chance gold nuggets drop is increased 14.29%, Fortune II increases the drop chance to 25%, and Fortune III guarantees the drop. == Usage == Gold nuggets can be used to craft a [[golden carrot]] or [[glistering melon]] for brewing. Also, gold nuggets can be combined with gunpowder and dye to create a [[firework star]] that bursts in a star-shaped explosion. [[Piglin]]s instantly pick up any gold nuggets that are within 1 [[block]] of them. Unlike other gold-related items, they do not intentionally seek out gold nuggets to pick up and only pick them up if they walk near it. Unlike gold ingots, gold nuggets picked up are dropped upon the piglin's death. === Crafting ingredient === {{crafting usage}} == Data values == === ID === {{edition|java}}: {{ID table |edition=java |showforms=y |generatetranslationkeys=y |displayname=Gold Nugget |spritetype=item |nameid=gold_nugget |form=item |foot=1}} {{edition|bedrock}}: {{ID table |edition=bedrock |shownumericids=y |showforms=y |notshowbeitemforms=y |generatetranslationkeys=y |displayname=Gold Nugget |spritetype=item |nameid=gold_nugget |id=425 |form=item |foot=1}} == History == {{History|Java}} {{History||1.0.0|snap=Beta 1.9 Prerelease|[[File:Gold Nugget JE1.png|32px]] Added gold nuggets. |Gold nuggets are [[drops|dropped]] by [[zombie pigmen]]. |Gold nuggets can be used to craft [[gold ingot]]s. |Gold nuggets currently do not have a mouseover name.}} {{History|||snap=Beta 1.9 Prerelease 2|Gold nuggets now have a mouseover name.}} {{History|||snap=Beta 1.9 Prerelease 4|Gold nuggets are now used to craft [[glistering melon]]s. |Gold nuggets can now be [[crafting|crafted]] from a single [[gold ingot]].}} {{History||1.1|snap=release|Normal [[golden apple]]s are now crafted with gold nuggets.}} {{History||1.3.1|snap=1.3|[[File:Gold Nugget JE2 BE1.png|32px]] The texture of gold nuggets has been changed.}} {{History||1.4.2|snap=12w34a|Gold nuggets are now used to craft [[golden carrot]]s.}} {{History||1.4.6|snap=12w49a|Gold nuggets can now be used to craft a [[firework star]] for a star shaped effect on a [[firework rocket|firework]].}} {{History||1.6.1|snap=13w23a|Gold nuggets can no longer be used to [[crafting|craft]] a [[golden apple]].}} {{History||1.9|snap=15w43a|Gold nuggets may now be found among the loot in [[igloo]] basement [[chest]]s.}} {{History||1.11.1|snap=16w50a|Gold nuggets can now be [[smelting|smelted]] from golden [[tool]]s and [[armor]].}} {{History||1.13|snap=17w47a|Prior to [[1.13/Flattening|''The Flattening'']], this [[item]]'s numeral ID was 371.}} {{History|||snap=18w09a|Gold nuggets can now be found in [[underwater ruins]] loot [[chest]]s.}} {{History|||snap=18w11a|Gold nuggets now generate in the chests of [[shipwreck]]s.}} {{History||1.14|snap=18w43a|[[File:Gold Nugget JE3 BE2.png|32px]] The texture of gold nuggets has been changed.}} {{History|||snap=18w48a|Gold nuggets can now be found in chests in [[plains]] [[village]] houses.}} {{History|||snap=18w49a|Gold nuggets can now be found in chests in [[savanna]] village houses.}} {{History||1.16|snap=20w12a|[[Nether gold ore]] now [[drops]] 2-6 gold nuggets, affected by [[Fortune]].}} {{History|||snap=20w15a|[[Gilded blackstone]] now has 10% chance to drop 2-5 gold nuggets. Only the drop chance is affected by [[Fortune]].}} {{History|||snap=20w16a|Gold nuggets now generate in [[bastion remnant]]s and [[ruined portal]] chests.}} {{History|||snap=Pre-release 1|Gold nuggets can now be used to distract [[piglin]]s.}} {{History|||snap=Pre-release 3|Gold nuggets can no longer be used to distract [[piglin]]s.}} {{History||1.20|snap=23w12a|Gold nuggets can now be found in [[suspicious gravel]] and [[suspicious sand]] in cold and warm [[ocean ruins]] and in [[trail ruins]].}} {{History|||snap=23w16a|Gold nuggets no longer generate in [[suspicious sand]] in [[trail ruins]].|Due to the split of the archaeological loot tables for suspicious gravel within [[trail ruins]], gold nuggets are now common loot.}} {{History|pocket alpha}} {{History||v0.12.1|snap=build 1|[[File:Gold Nugget JE2 BE1.png|32px]] Added gold nuggets. |Gold nuggets can be used to craft [[glistering melon]]s, [[gold ingot]]s and [[golden carrot]]s.|[[Gold ingot]]s can now be [[crafting|crafted]] into 9 gold nuggets.|[[Zombie pigmen]] now [[drops|drop]] gold nuggets upon being killed.}} {{History|pocket}} {{History||1.0.0|snap=alpha 0.17.0.1|Gold nuggets can now be found inside [[igloo]] basement [[chest]]s.}} {{History||1.1.0|snap=alpha 1.1.0.0|Gold nuggets can now be [[smelting|smelted]] from golden [[tool]]s and [[armor]].}} {{History|bedrock}} {{History||1.2.0|snap=beta 1.2.0.2|Gold nuggets can now be used to craft [[firework star]]s.}} {{History||1.4.0|snap=beta 1.2.14.2|Gold nuggets can now be found in some [[shipwreck]] [[chest]]s.}} {{History|||snap=beta 1.2.20.1|Gold nuggets can now be found in [[underwater ruins]] chests.}} {{History||1.10.0|snap=beta 1.10.0.3|The gold nugget can now be found in [[plains]] [[village]] house chests.|[[File:Gold Nugget JE3 BE2.png|32px]] The texture of gold nuggets has been changed.}} {{History||1.11.0|snap=beta 1.11.0.1|The gold nugget can now be found in [[savanna]] village house [[chest]]s.}} {{History||1.16.0|snap=beta 1.16.0.57|[[Nether gold ore]] now [[drops]] 2-6 gold nuggets.|[[Gilded blackstone]] now has 10% chance to drop 2-5 gold nuggets.}} {{History||1.16.100|snap=beta 1.16.100.50|Gold nuggets can now be used as fuel for a [[furnace]].<ref>{{bug|MCPE-114216}}</ref>}} {{History||1.18.30|snap=beta 1.18.30.26|Gold nuggets can no longer be used as fuel for a furnace.}} {{History|Legacy Console}} {{History||xbox=TU7|xbone=CU1|ps=1.0|wiiu=Patch 1|switch=1.0.1|[[File:Gold Nugget JE2 BE1.png|32px]] Added gold nuggets.}} {{History||xbox=TU53|xbone=CU43|ps=1.49|wiiu=Patch 23|switch=1.0.3|Gold nuggets can now be [[smelting|smelted]] from golden [[tool]]s and [[armor]].}} {{History||xbox=none|xbone=none|ps=1.90|wiiu=none|switch=none|[[File:Gold Nugget JE3 BE2.png|32px]] The texture of gold nuggets has been changed.}} {{History|3DS}} {{History||0.1.0|[[File:Gold Nugget JE2 BE1.png|32px]] Added gold nuggets.}} {{History||1.9.19|Gold nuggets can now be [[smelting|smelted]] from golden [[tool]]s and [[armor]].}} {{History|foot}} == Issues == {{issue list}} == See also == * [[Iron Nugget]] * [[Gold]] {{Items}} [[cs:Zlatý nuget]] [[de:Goldklumpen]] [[es:Pepita de oro]] [[fr:Pépite d'or]] [[hu:Aranyrög]] [[it:Pepita d'oro]] [[ja:金塊]] [[ko:황금 조각]] [[nl:Goudklompje]] [[pl:Bryłka złota]] [[pt:Pepita de ouro]] [[ru:Кусочек золота]] [[uk:Золотий самородок]] [[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.