Function (Java Edition)

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

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:

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>[[Cyan Dye|Cyan Dye]]<br/>{{Item | image = Cyan Dye.png | renewable = Yes | stackable = Yes (64) }} '''Cyan dye''' is a [[Dyeing#Secondary|secondary dye color]]. == Obtaining == === Crafting === {{Crafting |head=1 |showdescription=1 |showname=0 |Blue Dye |Green Dye |Output=Cyan Dye,2 |type=Material }} {{Crafting |Lapis Lazuli |Green Dye |Output=Cyan Dye,2 |description={{only|bedrock|education}} |type=Material }} {{Crafting |Pitcher Plant |Output=Cyan Dye,2 |description= |type=Material |foot=1 }} === Trading === [[Wandering trader]]s sell 3 cyan dye for an [[emerald]]. == Usage == {{dye usage}} === Crafting ingredient === {{crafting usage|ignore=Banner|continue=1}} {{banner crafting usage}} === Loom ingredient === {{Banner loom usage|Cyan Dye}} === Trading === {{IN|bedrock}}, journeyman-level shepherd villagers have 20% chance to buy 12 cyan dye for an emerald. {{More info|java=1|Java UI does not use a specific trade slot, which results in a different chance to offer this trade.}} == Data values == === ID === {{edition|java}}: {{ID table |edition=java |showforms=y |generatetranslationkeys=y |displayname=Cyan Dye |spritetype=item |nameid=cyan_dye |form=item |foot=1}} {{edition|bedrock}}: {{ID table |edition=bedrock |showaliasids=y |shownumericids=y |showforms=y |notshowbeitemforms=y |generatetranslationkeys=y |displayname=Cyan Dye |spritetype=item |nameid=cyan_dye |aliasid=dye / 6 |id=401 |form=item |translationkey=item.dye.cyan.name |foot=1}} == History == {{History|java beta}} {{History||1.2|[[File:Cyan Dye JE1 BE1.png|32px]] Added cyan dye.}} {{History|java}} {{History||1.4.2|snap=12w34a|Added the ability to [[Armor#Dyeing|dye]] leather [[armor]] and [[wolf]] collars.}} {{History||1.4.6|snap=12w49a|Cyan dye can now be [[crafting|crafted]] with [[gunpowder]] to create a [[firework star]].}} {{History||1.6.1|snap=13w19a|[[Stained clay]] can now be crafted.}} {{history||1.7.2|snap=13w36a|With the addition of new [[flower]]s, many secondary and tertiary dyes are now primary [[dye]]s.}} {{History|||snap=13w41a|[[Stained glass]] can now be crafted.}} {{History||1.8|snap=14w02a|Due to [[lapis lazuli]] being [[renewable resource|renewable]], cyan dye is also renewable.}} {{History|||snap=14w30a|Added [[banner]]s, which can be dyed.}} {{History||1.13|snap=17w47a|The different data values for the <code>dye</code> ID have now been split up into their own IDs. |Prior to [[1.13/Flattening|''The Flattening'']], this [[item]]'s numeral ID was 351.}} {{History||1.14|snap=18w43a|Cyan dye is now [[crafting|crafted]] using [[blue dye]], instead of [[lapis lazuli]]. |[[File:Cyan Dye.png|32px]] The texture of cyan dye has now been changed.}} {{History|||snap=18w44a|Cyan dye can now change the text color on [[sign]]s to cyan.}} {{History|||snap=19w05a|Added the [[wandering trader]], which sell cyan dyes.}} {{History|||snap=19w11a|Cyan dye can now be [[trading|bought]] by shepherd villagers.}} {{History||1.17|snap=20w45a|Cyan dye can now be used to craft [[cyan candle]]s.}} {{History|||snap=21w19a|Cyan dye can no longer be used to craft cyan candles.}} {{History|||snap=Pre-release 1|Cyan dye can once again be used to craft cyan candles.}} {{History||1.20<br>(Experimental)|link=1.19.3|snap=22w42a|Cyan dye can now change the text color on [[hanging sign]]s to cyan.}} {{History||1.20|snap=23w12a|Added [[pitcher plant]]s, which can be crafted into cyan dye.}} {{History|||snap=23w14a|[[Pitcher plant]]s now craft into 2 cyan dye instead of 1.}} {{History|pocket alpha}} {{History||v0.3.0|[[File:Cyan Dye JE1 BE1.png|32px]] Added cyan dye. It is currently unobtainable and serves no purpose.}} {{History||v0.4.0|Cyan dye is now craftable with [[lapis lazuli]] and [[cactus green]]. |Cyan dye can now be used to craft cyan wool.}} {{History||v0.6.0|Cyan dye can now be used to dye [[sheep]].}} {{History||v0.9.0|snap=build 11|Cyan dye can now be used to craft colored [[terracotta]].}} {{History||v0.11.0|snap=build 1|Cyan dye can now be used to dye tamed [[wolf]] collars.}} {{History||v0.14.0|snap=build 1|Cyan dye can now be used to dye water in [[cauldron]]s.}} {{History|pocket}} {{History||1.0.0|snap=alpha 0.17.0.1|Cyan dye can now be used to dye [[shulker]]s.}} {{History||1.1.0|snap=alpha 1.1.0.0|Cyan dye can now be used to craft [[concrete powder]], colored [[bed]]s and dyed [[shulker box]]es.}} {{History|bedrock}} {{History||1.2.0|snap=beta 1.2.0.2|Cyan dye can now be used to craft [[firework star]]s, [[stained glass]] and patterns on [[banner]]s.}} {{History||1.4.0|snap=beta 1.2.20.1|Cyan dye can now be used to craft [[balloon|ballons]] and [[glow stick|glow sticks]].}} {{History||1.8.0|snap=beta 1.8.0.8|Cyan dye can now be used to dye tamed [[cat]] collars.}} {{History||1.10.0|snap=beta 1.10.0.3|Cyan dye are now [[trading|sold]] by [[wandering trader]]s. |Cyan dye can now be used to dye white [[carpet|carpets]] and undyed [[glass pane]]s. |[[File:Cyan Dye.png|32px]] The texture of cyan dye has now been changed.}} {{History||1.11.0|snap=beta 1.11.0.4|Cyan dye can be [[trading|sold]] to shepherd [[villager]]s.}} {{History||1.16.100|snap=beta 1.16.100.56|The ID of cyan dye has been changed from <code>dye/6</code> to <code>cyan_dye</code>.}} {{History|console}} {{History||xbox=TU1|xbone=CU1|ps=1.00|switch=1.0.1|wiiu=Patch 1|[[File:Cyan Dye JE1 BE1.png|32px]] Added cyan dye.}} {{History|PS4}} {{History||1.90|[[File:Cyan Dye.png|32px]] The texture of cyan dye has now been changed.}} {{History|new 3ds}} {{History||0.1.0|[[File:Cyan Dye JE1 BE1.png|32px]] Added cyan dye.}} {{History|foot}} == Issues == {{issue list}} {{Items}} [[Category:Items]] [[Category:Dyes]] [[Category:Renewable resources]] [[cs:Azurové barvivo]] [[de:Türkiser Farbstoff]] [[es:Tinte cian]] [[fr:Teinture cyan]] [[hu:Ciánkék festék]] [[ja:青緑色の染料]] [[ko:청록색 염료]] [[nl:Turquoise kleurstof]] [[pl:Błękitny barwnik]] [[pt:Corante ciano]] [[ru:Бирюзовый краситель]] [[zh:青色染料]]</li><li>[[Disc Fragment|Disc Fragment]]<br/>{{Item | image = Disc Fragment.png | renewable = No | stackable = Yes (64) }} A '''disc fragment''' is a [[music disc]] fragment obtained from [[ancient city]] loot chests. Nine fragments can be combined in a [[Crafting Table|crafting table]] to make a music disc named "5". == Obtaining == === Chest loot === {{LootChestItem|disc-fragment-5}} == Usage == === Crafting ingredient === {{crafting usage|Disc Fragment 5}} == Data values == === ID === {{ID table |edition=java<!-- |showitemtags=y--> |showforms=y |firstcolumnname=Track |generatetranslationkeys=y |displayname=Samuel Åberg - 5 |spritename=disc-fragment-5 |spritetype=item |nameid=disc_fragment_5<!-- |itemtags=--> |form=item |foot=y}} == History == {{History|java}} {{History||1.19|snap=22w16a|[[File:Disc Fragment.png|32px]] Added disc fragments.}} {{History|bedrock}} {{History||1.19.0|snap=beta 1.19.0.28|[[File:Disc Fragment.png|32px]] Added disc fragments.}} {{History|foot}} == Issues == {{Issue list}} ==Gallery== <gallery> 9 to 5.jpg|9 fragments of the 5 music disc. </gallery> ==See also== * {{EnvLink|Music}} * {{ItemLink|Music Disc}} {{Items}} [[de:Plattenbruchstück]] [[es:Fragmento de disco]] [[fr:Fragment de disque]] [[ja:レコードの破片]] [[pl:Fragment płyty]] [[pt:Fragmento de disco]] [[ru:Фрагмент пластинки 5]] [[uk:Фрагмент платівки]] [[zh:唱片残片]] [[Category:Non-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>[[Raw Gold|Raw Gold]]<br/>{{Item | image = Raw Gold.png | renewable = No | stackable = Yes (64) }} '''Raw gold''' is a raw metal resource obtained from mining [[gold ore]]. == Obtaining == === Mining === [[Gold ore]] and [[deepslate gold ore]] mined with an [[iron pickaxe]] or higher drops 1 unit of raw gold. If the pickaxe is enchanted with [[Fortune]], it can drop an extra unit per level of Fortune, allowing for a maximum of 4 with Fortune III. If the ore is mined using a pickaxe enchanted with [[Silk Touch]], it drops the ore block instead. === Crafting === {{Crafting |showname=1 |Block of Raw Gold |Output=Raw Gold,9 |type=Material |foot=1 }} == Usage == The primary usage of raw gold is smelting it into [[gold ingot]]s. === Crafting === {{crafting usage|Raw Gold}} === Smelting ingredient === {{Smelting |showname=2 |Raw Gold |Gold Ingot |1.0 }} === Piglins === {{EntityLink|Piglin|Piglins}} are attracted to raw gold. They run toward any raw gold on the ground, and inspect it for 6 to 8 seconds before putting it in their inventory. == Advancements == {{load advancements|Oh Shiny}} == Data values == === ID === {{edition|java}}: {{ID table |edition=java |showitemtags=y |showforms=y |generatetranslationkeys=y |displayname=Raw Gold |spritetype=item |nameid=raw_gold |itemtags=piglin_loved |form=item |foot=1}} {{edition|bedrock}}: {{ID table |edition=bedrock |shownumericids=y |showforms=y |notshowbeitemforms=y |generatetranslationkeys=y |displayname=Raw Gold |spritetype=item |nameid=raw_gold |form=item |id=506 |foot=1}} == History == {{History|java}} {{History||1.17|snap=21w14a|[[File:Raw Gold JE1.png|32px]] Added raw gold.}} {{History|||snap=April 13, 2021|slink={{Tweet|JasperBoerstra|1381991999952277513}}|[[File:Raw Gold JE2.png|32px]] [[JAPPA]] shows a new raw gold texture.}} {{History|||snap=21w15a|[[File:Raw Gold JE2.png|32px]] The texture of raw gold has been changed. |Raw gold can now be used to craft [[block of raw gold]].}} {{History|||snap=April 16, 2021|slink={{Tweet|JasperBoerstra|1383047666037325829}}|[[File:Raw Gold (pre-release).png|32px]] [[JAPPA]] shows a new raw gold texture again.}} {{History|||snap=21w16a|[[File:Raw Gold JE3.png|32px]] The texture of raw gold has been changed.}} {{History|Bedrock}} {{History||1.17.0|snap=beta 1.17.0.50|[[File:Raw Gold JE2.png|32px]] Added raw gold.}} {{History|||snap=beta 1.17.0.52|Raw gold are now available without enabling [[experimental gameplay]].}} {{History|||snap=beta 1.17.0.54|[[File:Raw Gold JE3.png|32px]] The texture of raw gold has been changed.}} {{History|foot}} == Issues == {{Issue list}} ==Gallery== <gallery> JE 1.17 Dev Raw Metals.jpg|Jappa shows raw ore textures. Jappa Raw Ores 1.jpg|Jappa shows raw ore textures. Jappa Raw Ores 2.png|Jappa shows raw ore textures. Jappa Raw Ores 3.jpg|Jappa shows raw ore textures. Jappa Raw Ores 4.jpg|Jappa shows raw ore textures. Jappa Raw Ores 5.jpg|Jappa shows raw ore textures. </gallery> {{Items}} [[Category:Non-renewable resources]] [[de:Rohgold]] [[es:Oro en bruto]] [[fr:Or brut]] [[ja:金の原石]] [[pl:Surowe złoto]] [[pt:Ouro bruto]] [[ru:Необработанное золото]] [[uk:Необроблене золото]] [[zh:粗金]]</li><li>[[Yellow Dye|Yellow Dye]]<br/>{{Item | title = Yellow Dye | renewable = Yes | stackable = Yes (64) }} '''Yellow dye''' is a [[Dye#Primary|primary dye]] created by placing a [[dandelion]] or [[sunflower]] into a [[crafting]] grid. == Obtaining == === Crafting === {{Crafting |Dandelion;Sunflower |Output=Yellow Dye;Yellow Dye,2 |type=Material }} === Chest loot === {{LootChestItem|yellow-dye}} === Trading === [[Wandering trader]]s sell 3 yellow dye for an [[emerald]]. == Usage == {{dye usage}} === Crafting ingredient === {{crafting usage|ignore=Banner|continue=1}} {{banner crafting usage}} === Loom ingredient === {{Banner loom usage|Yellow Dye}} === Trading === Expert-level shepherd villagers have a {{frac|1|6}} chance to buy 12 yellow dye for an emerald. == Data values == === ID === {{edition|java}}: {{ID table |edition=java |showforms=y |generatetranslationkeys=y |displayname=Yellow Dye |spritetype=item |nameid=yellow_dye |form=item |foot=1}} {{edition|bedrock}}: {{ID table |edition=bedrock |showaliasids=y |shownumericids=y |showforms=y |notshowbeitemforms=y |generatetranslationkeys=y |displayname=Yellow Dye |spritetype=item |nameid=yellow_dye |aliasid=dye / 11 |id=406 |form=item |translationkey=item.dye.yellow.name |foot=1}} == Video == {{yt|nOQUDjEHGRg}} == History == {{History|java beta}} {{History||1.2|[[File:Yellow Dye JE1 BE1.png|32px]] Added dandelion yellow.}} {{History||1.6.6|Dandelions can now be generated using [[Bone Meal|bone meal]], making dandelion yellow [[renewable resource|renewable]].}} {{History|java}} {{History||1.4.2|snap=12w34a|Added the ability to [[Armor#Dyeing|dye]] leather [[armor]] and [[wolf]] collars.}} {{History||1.4.6|snap=12w49a|Dandelion yellow can be crafted with [[gunpowder]] to create a [[firework star]].}} {{History||1.6.1|snap=13w19a|[[Stained clay]] can now be crafted.}} {{History||1.7.2|snap=13w36a|Can now be crafted using sunflower.}} {{History|||snap=13w37a|Each dandelion now yields only 1 dandelion yellow, instead of 2.}} {{History|||snap=13w41a|[[Stained glass]] can now be [[crafting|crafted]].}} {{History||1.8|snap=14w30a|Added [[banner]]s, which can be [[dye]]d.}} {{History||1.11|snap=16w39a|Added the ability to dye [[shulker box]]es.}} {{History||1.12|snap=17w06a|Yellow dye can now be used to craft yellow [[concrete powder]].}} {{History|||snap=17w15a|Added the ability to dye [[bed]]s.}} {{History||1.13|snap=17w47a|The different data values for the <code>dye</code> ID have now been split up into their own IDs. |Prior to [[1.13/Flattening|''The Flattening'']], this [[item]]'s numeral ID was 351.}} {{History||1.14|snap=18w43a|"Dandelion Yellow" has now been renamed to "Yellow Dye". |[[File:Yellow Dye JE2 BE2.png|32px]] The texture of yellow dye has now been changed.}} {{History|||snap=18w44a|Yellow dye can now change the text color on [[sign]]s to yellow.}} {{History|||snap=18w49a|Yellow dye can now be found in [[chest]]s in [[village]] mason houses.}} {{History|||snap=19w05a|Added the [[wandering trader]], which sells yellow dye.}} {{History|||snap=19w11a|Yellow dye can now be [[trading|bought]] by shepherd villagers.}} {{History||1.17|snap=20w45a|Yellow dye can now be used to craft [[yellow candle]]s.}} {{History|||snap=21w19a|Yellow dye can no longer be used to craft yellow candles.}} {{History|||snap=Pre-release 1|Yellow dye can once again used to craft yellow candles.}} {{History||1.20<br>(Experimental)|link=1.19.3|snap=22w42a|Yellow dye can now change the text color on [[hanging sign]]s to yellow.}} {{History||1.20|snap=23w12a|Yellow dye can now be found in [[suspicious gravel]] and [[suspicious sand]] in [[trail ruins]].}} {{History|||snap=23w16a|Yellow dye no longer generates in [[suspicious sand]] in [[trail ruins]].|Due to the split of the archaeological loot tables for suspicious gravel within [[trail ruins]], yellow dye is now common loot.}} {{History|pocket alpha}} {{History||v0.3.0|[[File:Yellow Dye JE1 BE1.png|32px]] Added dandelion yellow.}} {{History||v0.8.0|snap=build 1|Dandelion yellow is now used to craft [[cocoa beans]].}} {{History||v0.14.0|snap=build 1|Yellow dye can now be used to dye [[water]] in [[cauldron]]s.}} {{History||v0.16.0|snap=build 1|Dandelion yellow is no longer used to [[crafting|craft]] cocoa beans.}} {{History|pocket}} {{History||1.0.0|snap=alpha 0.17.0.1|Yellow dye can now be used to dye [[shulker]]s.}} {{History||1.1.0|snap=alpha 1.1.0.0|Yellow dye can now be used to dye [[shulker box]]es, [[bed]]s, and craft [[concrete powder]].}} {{History|bedrock}} {{History||1.2.0|snap=beta 1.2.0.2|Yellow dye can now be used to craft patterns on [[banner]]s, [[firework star]]s, and [[stained glass]].}} {{History||1.4.0|snap=beta 1.2.20.1|Yellow dye can now be used to craft [[balloon]]s and [[glow stick]]s.}} {{History||1.8.0|snap=beta 1.8.0.8|Dandelion yellow can now be used to dye [[cat]] collars.}} {{History|||snap=beta 1.8.0.10|"Dandelion Yellow" has now been renamed to "Yellow Dye".}} {{History||1.10.0|snap=beta 1.10.0.3|Yellow dye is now [[trading|sold]] by [[wandering trader]]s. |[[File:Yellow Dye JE2 BE2.png|32px]] The texture of yellow dye has now been changed.}} {{History||1.11.0|snap=beta 1.11.0.1|Yellow dye can now be found in [[village]] mason [[chest]]s.}} {{History|||snap=beta 1.11.0.4|Yellow dye can now be sold to shepherd [[villager]]s.}} {{History||1.16.100|snap=beta 1.16.100.56|The ID of yellow dye has been changed from <code>dye/11</code> to <code>yellow_dye</code>.}} {{History|console}} {{History||xbox=TU1|xbone=CU1|ps=1.00|switch=1.0.1|wiiu=Patch 1|[[File:Yellow Dye JE1 BE1.png|32px]] Added dandelion yellow.}} {{History|ps4}} {{History||1.83|"Dandelion Yellow" has now been renamed to "Yellow Dye".}} {{History||1.90|[[File:Yellow Dye JE2 BE2.png|32px]] The texture of yellow dye has now been changed.}} {{History|new 3ds}} {{History||0.1.0|[[File:Yellow Dye JE1 BE1.png|32px]] Added dandelion yellow.}} {{History|foot}} == Issues == {{issue list}} == References == {{reflist}} {{Items}} [[cs:Pampelišková žluť]] [[de:Gelber Farbstoff]] [[es:Tinte amarillo]] [[fr:Teinture jaune]] [[hu:Pitypangsárga]] [[ja:黄色の染料]] [[ko:노란색 염료]] [[nl:Paardenbloemgeel]] [[pl:Żółty barwnik]] [[pt:Corante amarelo]] [[ru:Жёлтый краситель]] [[zh:黄色染料]] [[Category:Items]] [[Category:Dyes]] [[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.