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. Function files will be added in Bedrock Edition 1.8,‌ however they are only available in behavior packs. To see how to use Functions in Bedrock Edition, see the page Function (Bedrock).

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>[[Fish|Fish]]<br/>{{About|the type of mob|the action|Fishing}} '''Fish''' are aquatic creatures that are found in [[river]] and [[ocean]] biomes. == Mobs == There are four categories of fish mobs in ''Minecraft'': *{{EntityLink|Cod}} *{{EntityLink|Salmon}} *{{EntityLink|Pufferfish}} *{{EntityLink|Tropical Fish}} - many color and pattern varieties In addition, there are other fish-like mobs that have different characteristics from fish: {{EntityLink|Axolotl}}, {{EntityLink|Guardian}}, and {{EntityLink|Elder Guardian}}. ==Obtaining and transporting== A live fish can be captured by using a [[water bucket]] on a fish, to obtain a [[bucket of fish]], which is the only way to obtain the live mob in item form. Using the bucket of fish on a water source block transfers the fish from the bucket to the body of water. A water bucket may also be used on [[axolotl]]s in this manner. ==Items== Fish exist in several different item forms. Upon death, fish drop their item form equivalent (cooked if on fire), with a chance to drop a [[bone]]{{only|bedrock}} or [[bone meal]].{{only|java}} ;Non-living *{{ItemLink|Raw Cod}} *{{ItemLink|Cooked Cod}} *{{ItemLink|Raw Salmon}} *{{ItemLink|Cooked Salmon}} *{{ItemLink|Pufferfish|link=Pufferfish (item)}} *{{ItemLink|Tropical Fish|link=Tropical Fish (item)}} ;Living *{{ItemLink|Bucket of Cod}} *{{ItemLink|Bucket of Salmon}} *{{ItemLink|Bucket of Pufferfish}} *{{ItemLink|Bucket of Tropical Fish}} == Spawning == Various fish can be found in different [[ocean]] [[biomes]], but only [[salmon]] appear in rivers. Fish can also spawn in player-created bodies of water, as long as they are within a river or ocean biome. {| class="wikitable sortable" style="text-align:left" data-description="Fish biomes" !'''Fish''' ! style="text-align:left" |{{BiomeLink|Warm Ocean}} ! style="text-align:left" |{{BiomeLink|Lukewarm Ocean}}<br>{{BiomeLink|Deep Lukewarm Ocean}} ! style="text-align:left" |{{BiomeLink|Ocean}}<br>{{BiomeLink|Deep Ocean}} ! style="text-align:left" |{{BiomeLink|Cold Ocean}}<br>{{BiomeLink|Deep Cold Ocean}} ! style="text-align:left" |{{BiomeLink|Frozen Ocean}}<br>{{BiomeLink|Deep Frozen Ocean}} ! style="text-align:left" |{{BiomeLink|River}}<br>{{BiomeLink|Frozen River}} |- ! rowspan=2 style="text-align:left" |{{EntityLink|Cod}} | rowspan=2 {{tc|no}} | rowspan=2 {{tc|yes}} | rowspan=2 {{tc|yes}} | rowspan=2 {{tc|yes}} | {{tc|no|No{{only|je|short=1}}}} | rowspan=2 {{tc|no}} |- | {{tc|yes|Yes{{only|be|short=1}}}} |- ! rowspan=2 style="text-align:left" |{{EntityLink|Salmon}} | rowspan=2 {{tc|no}} | {{tc|no|No{{only|je|short=1}}}} | {{tc|no|No{{only|je|short=1}}}} | rowspan=2 {{tc|yes}} | rowspan=2 {{tc|yes}} | rowspan=2 {{tc|yes}} |- | {{tc|yes|Yes{{only|be|short=1}}}} | {{tc|yes|Yes{{only|be|short=1}}}} |- ! rowspan=2 style="text-align:left" |{{EntityLink|Pufferfish}} | rowspan=2 {{tc|yes}} | {{tc|yes|Yes{{only|je|short=1}}}} | rowspan=2 {{tc|no}} | rowspan=2 {{tc|no}} | rowspan=2 {{tc|no}} | rowspan=2 {{tc|no}} |- | {{tc|no|No{{only|be|short=1}}}} |- ! style="text-align:left" |{{EntityLink|Tropical Fish}}<ref group="note">Also spawns in {{BiomeLink|Lush Caves}} at any Y-level.</ref> | {{tc|yes}} | {{tc|yes}} | {{tc|no}} | {{tc|no}} | {{tc|no}} | {{tc|no}} |- ! style="text-align:left" |{{EntityLink|Squid}} | {{tc|yes}} | {{tc|yes}} | {{tc|yes}} | {{tc|yes}} | {{tc|yes}} | {{tc|yes}} |- ! rowspan=2 style="text-align:left" |{{EntityLink|Dolphin}} | rowspan=2 {{tc|yes}} | rowspan=2 {{tc|yes}} | rowspan=2 {{tc|yes}} | {{tc|no|No{{only|je|short=1}}}} | rowspan=2 {{tc|no}} | rowspan=2 {{tc|no}} |- | {{tc|yes|Yes{{only|be|short=1}}}} |} {{notelist}} In ''Java Edition'', fish can spawn inside a water block at Y-level 50 to 63 (from 13 blocks below sea level up to inside the block one above it), that also has water above and below it. The spawn block and the block below can be any kind of water, such as a source block, falling water, bubble column, kelp, or even a waterlogged block (as long as the fish can be placed at the bottom center of the spawn block without colliding with anything solid). The block above must be pure water, such as a source block, falling water, or flowing water of any depth. Particularly, the block above cannot also be a bubble column, so fish no longer spawn inside bubble elevators.<ref>{{cite bug|MC|244683|Tropical fish spawn in bubble columns (fixed in 22w07a)}}</ref> ''Bedrock Edition'' does permit fish to spawn in bubble columns.<ref>{{cite bug|MCPE|73967|Squids, Dolphins, and fish not spawning in bubble columns (fixed in 1.16.20)}}</ref> Fish can spawn between 24 and 64 block spherical range away from the player.{{only|java}} === Despawning === As of [[1.16]], fish can despawn at range of 40 blocks or more from the player, and will instantly despawn more than 64 blocks away, except when spawned using a [[bucket of fish]]. {{Items}} {{Entities}} [[cs:Ryba]] [[de:Fisch (Begriffsklärung)]] [[es:Pez]] [[fr:Poisson]] [[it:Pesce]] [[ja:魚]] [[ko:물고기]] [[nl:Vis]] [[pl:Ryba (ujednoznacznienie)]] [[pt:Peixe]] [[ru:Рыба]] [[th:ปลา (แก้ความกำกวม)]] [[uk:Риба]] [[zh:鱼]]</li><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></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>[[Nether Sprouts|Nether Sprouts]]<br/>{{Block |title=Nether Sprouts |image=Nether Sprouts.png |image2=Nether Sprouts (texture) JE2 BE2.png |transparent=Yes |tool=shears |light=No |renewable=Yes |stackable=Yes (64) |flammable=No |lavasusceptible=Yes }} '''Nether sprouts''' are a non-solid fungi block that generate in [[warped forest]]s. == Obtaining == === Natural generation === Nether sprouts generate in [[warped forest]] biomes. === Breaking === Nether sprouts can be mined instantly with any item. The block also breaks if the block below is removed, or if [[water]] flows into its space. The block only drops if broken with [[shear]]s. === Post-generation === Applying [[bone meal]] to warped [[nylium]] creates nether sprouts on that block and surrounding nylium, along with both types of [[roots]] and [[fungi]]. == Usage == [[File:RootsSproutsPlaceBlock.png|thumb|All of the blocks that nether sprouts can be placed on.]] Nether sprouts can be planted on the same blocks that [[fungus|fungi]] and [[roots]] can be placed on: [[nylium]], [[soul soil]], [[Grass Block|grass]], [[podzol]], [[mycelium]], [[Moss Block|moss]], [[dirt]], [[coarse dirt]], [[rooted dirt]], and [[farmland]]. However, they cannot be planted in [[flower pot]]s. === Composting === Placing nether sprouts into a [[composter]] has a 50% chance of raising the compost level by 1. == Sounds == {{Sound table/Block/Nether sprouts}} == Data values == === ID === {{edition|java}}: {{ID table |edition=java |generatetranslationkeys=y |showforms=y |displayname=Nether Sprouts |spritetype=block |nameid=nether_sprouts |foot=1}} {{edition|bedrock}}: {{ID table |edition=bedrock |firstcolumnname=Nether Sprouts |shownumericids=y |showforms=y |generatetranslationkeys=y |displayname=Block |spritename=nether-sprouts |spritetype=block |nameid=nether_sprouts |id=493 |form=block |itemform=item.nether_sprouts}} {{ID table |displayname=Item |spritename=nether-sprouts |spritetype=item |nameid=nether_sprouts |id=621 |form=item |translationkey=tile.nether_sprouts.name |foot=1}} == History == {{History|java}} {{History||1.16|snap=20w06a|[[File:Nether Sprouts JE1 BE1.png|24px]] [[File:Nether Sprouts (texture) JE1 BE1.png|24px]] Added nether sprouts.}} {{History|||snap=20w10a|[[File:Nether Sprouts JE2 BE2.png|24px]] [[File:Nether Sprouts (texture) JE2 BE2.png|24px]] The textures of the nether sprouts have now been changed.}} {{History|||snap=20w15a|Nether sprouts can now be [[composter|composted]].}} {{History|||snap=20w19a|Nether sprouts now only [[drops|drop]] if [[breaking|broken]] with [[shears]].}} {{History|||snap=20w21a|[[File:Nether Sprouts (item) JE3 BE2.png|24px]] The [[inventory]] texture of the nether sprouts have now been changed. |The [[block]] [[model]] of nether sprouts is now centered of the block rather than positioned randomly.}} {{History||1.19.3|snap=22w44a|Nether sprouts now make sounds when being walked on.<ref>{{bug|MC-171621|||Fixed}}</ref>}} {{History|bedrock}} {{History||1.16.0|snap=beta 1.16.0.51|[[File:Nether Sprouts JE1 BE1.png|24px]] [[File:Nether Sprouts (texture) JE1 BE1.png|24px]] Added nether sprouts.}} {{History|||snap=beta 1.16.0.57|Nether sprouts can now be [[composter|composted]].}} {{History|||snap=beta 1.16.0.59|[[File:Nether Sprouts JE2 BE2.png|24px]] [[File:Nether Sprouts (item) JE3 BE2.png|24px]] The textures of the nether sprouts have now been changed. |[[File:Nether Sprouts Glitched BE.png|32px]] Nether sprouts now appear with a glitched texture when [[breaking|broken]] in [[survival]] mode or when picking the [[block]] in [[creative]] mode. The [[item]] received is also nameless.<ref>{{bug|MCPE-74339}}</ref>}} {{History|||snap=beta 1.16.0.63|Nether sprouts now give the [[player]] the correct item when broken in survival mode or when picking the block in creative mode.}} {{History|foot}} == Issues == {{issue list}} == Trivia == * Unlike other warped "plants", nether sprouts don't have a crimson equivalent. This is also the case with [[nether wart]], which lacks a warped equivalent. == References == {{Reflist}} {{Blocks|vegetation}} {{Items}} [[Category:Nether blocks]] [[Category:Fungi]] [[Category:Natural blocks]] [[Category:Non-solid blocks]] [[de:Nethersprossen]] [[de:Nethersprossen]] [[es:Rastrojo del Nether]] [[fr:Germes du Nether]] [[ja:ネザースプラウト]] [[pl:Netherowe kiełki]] [[pt:Brotos do Nether]] [[ru:Адские ростки]] [[zh:下界苗]]</li><li>[[Purple Dye|Purple Dye]]<br/>{{Item | image = Purple_Dye_JE2_BE2.png | renewable = Yes | stackable = Yes (64) }} '''Purple dye''' is a [[Dyeing#Secondary colors|secondary dye color]] created by combining [[red dye]] and [[blue dye]] in a crafting grid. == Obtaining == === Crafting === {{Crafting |head=1 |showname=0 |Blue Dye |Red Dye |Output=Purple Dye,2 |type=Material }} {{Crafting |foot=1 |Lapis Lazuli |Red Dye |Output=Purple Dye,2 |description={{only|bedrock|education}} |type=Material }} === Trading === [[Wandering trader]]s sometimes sell 3 purple dye for an [[emerald]]. == Usage == {{dye usage}} === Crafting ingredient === {{crafting usage|ignore=Banner|continue=1}} {{banner crafting usage}} === Loom ingredient === {{Banner loom usage|Purple Dye}} === Trading === Apprentice-level Shepherd villagers have a 20% chance to buy 12 purple dye for an emerald as part of their trades.{{only|bedrock}} Expert-level Shepherd villagers have a {{frac|2|7}} chance to buy 12 purple dye for an emerald.{{only|java}} == Data values == === ID === {{edition|java}}: {{ID table |edition=java |showforms=y |generatetranslationkeys=y |displayname=Purple Dye |spritetype=item |nameid=purple_dye |form=item |foot=1}} {{edition|bedrock}}: {{ID table |edition=bedrock |showaliasids=y |shownumericids=y |showforms=y |notshowbeitemforms=y |generatetranslationkeys=y |displayname=Purple Dye |spritetype=item |nameid=purple_dye |aliasid=dye / 5 |id=400 |form=item |translationkey=item.dye.purple.name |foot=1}} == Video == <div style="text-align:center">{{yt|Cx52CGo5QnI}}</div> == History == {{History|java beta}} {{History||1.2|[[File:Purple Dye JE1 BE1.png|32px]] Added purple 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|Purple 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]] now, purple dye is also now 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|Purple dye is now [[crafting|crafted]] using [[blue dye]], instead of [[lapis lazuli]]. |[[File:Purple_Dye_JE2_BE2.png|32px]] The texture of purple dye has now been changed.}} {{History|||snap=18w44a|Purple dye can now change the text color on [[sign]]s to purple.}} {{History|||snap=19w05a|Added the [[wandering trader]], which sells purple dye.}} {{History|||snap=19w11a|Purple dye can now be [[trading|bought]] by shepherd villagers.}} {{History||1.17|snap=20w45a|Purple dye can now be used to craft [[purple candle]]s.}} {{History|||snap=21w19a|Purple dye can no longer be used to craft purple candles.}} {{History|||snap=Pre-release 1|Purple dye can once again be used to craft purple candles.}} {{History||1.20<br>(Experimental)|link=1.19.3|snap=22w42a|Purple dye can now change the text color on [[hanging sign]]s to purple.}} {{History|pocket alpha}} {{History||v0.3.0|[[File:Purple Dye JE1 BE1.png|32px]] Added purple dye. It is currently unobtainable and serves no purpose.}} {{History||v0.4.0|Purple dye is now [[craft]]able with rose red and lapis lazuli. |Purple dye can now be used to craft purple [[wool]].}} {{History||v0.6.0|Purple dye can now be used to dye [[sheep]].}} {{History||v0.8.0|snap=build 1|Purple dye can now be used to craft [[magenta dye]].}} {{History||v0.9.0|snap=build 11|Purple dye can now be used to craft colored [[terracotta]].}} {{History||v0.11.0|snap=build 1|Purple dye can now be used to dye tamed [[wolf]] collars.}} {{History||v0.14.0|snap=build 1|Purple dye can now be used to dye [[water]] in [[cauldron]]s.}} {{History|pocket}} {{History||1.0.0|snap=alpha 0.17.0.1|Purple dye can now be used to dye [[shulker]]s.}} {{History||1.1.0|snap=alpha 1.1.0.0|Purple 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|Purple 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|Purple dye can now be used to craft [[balloon]]s and [[glow stick]]s.}} {{History||1.8.0|snap=beta 1.8.0.8|Purple dye can now be used to dye tamed [[cat]] collars.}} {{History||1.10.0|snap=beta 1.10.0.3|Purple dye is now [[trading|sold]] by [[wandering trader]]s. |Purple dye can now be used to dye white [[carpet]]s and undyed [[glass pane]]s. |[[File:Purple_Dye_JE2_BE2.png|32px]] The texture of purple dye has now been changed.}} {{History||1.11.0|snap=beta 1.11.0.4|Purple dye can now be [[trading|sold]] to shepherd [[villager]]s.}} {{History||1.16.100|snap=beta 1.16.100.56|The ID of purple dye has been changed from <code>dye/5</code> to <code>purple_dye</code>.}} {{History|console}} {{History||xbox=TU1|xbone=CU1|ps=1.00|switch=1.0.1|wiiu=Patch 1|[[File:Purple Dye JE1 BE1.png|32px]] Added purple dye.}} {{History|PS4}} {{History||1.90|[[File:Purple_Dye_JE2_BE2.png|32px]] The texture of purple dye has now been changed.}} {{History|new 3ds}} {{History||0.1.0|[[File:Purple Dye JE1 BE1.png|32px]] Added purple dye.}} {{History|foot}} == Issues == {{issue list}} {{Items}} [[Category:Items]] [[Category:Dyes]] [[Category:Renewable resources]] [[cs:Fialové barvivo]] [[de:Violetter Farbstoff]] [[es:Tinte morado]] [[fr:Teinture violette]] [[hu:Lila festék]] [[ja:紫色の染料]] [[ko:보라색 염료]] [[nl:Paarse kleurstof]] [[pl:Fioletowy barwnik]] [[pt:Corante roxo]] [[ru:Фиолетовый краситель]] [[zh:紫色染料]]</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.