Function (Java Edition)

Template:Desktop

Functions are an upcoming feature that will allow players to easily script and run lists of commands using text files with the extension .mcfunction.

Usage

To use a function in a Minecraft world, the text file must first be placed into the WORLDNAME/data/functions folder. They can then be run using the several methods detailed below. Functions can be further divided into subfolders, and are run in-game using the format namespace:path/to/function/file. For example, running custom:example/test will refer to the function located at WORLDNAME/data/functions/custom/example/test.mcfunction. If the namespace is left out when trying to call a function, it will default to minecraft:. This means that all functions must be contained within a sub folder (of the functions folder) in order to be located.

Within the text 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 #. If a function is added or modified, the /reload command will reload the function files from disk, allowing Minecraft to recognise any changes to the function files. Commands run inside a function will obey /gamerule maxCommandChainLength.

Commands in functions can be longer than the 32 500 character limit in command blocks. Functions will also run all of their commands in a single tick. Functions called from within other functions will run their commands in the same tick as their parent. Position changes that happen within a function will not affect the relative coordinates used in other commands within that function (or other functions called within the function) till the next iteration regardless of the order of commands, the /execute command circumvents this. For example:

tp @a ~ ~5 ~

setblock ~ ~-1 ~ emerald_block

execute @a ~ ~ ~ setblock ~ ~-1 ~ diamond_block

These 3 commands will teleport all players 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 position arguments within selectors, which will always test for the current position at the time of execution.

Since they are simply text files, functions are easily modifiable and less likely to induce lag when used in large quantities, compared to command blocks. However, the successful output of a function cannot be measured with a comparator (without the use of complex scoreboard commands).

There are currently three ways of running a function file in-game:

/function

The /function command 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. Currently the if argument only succeeds upon matching 1 target (beyond which the function will be skipped), and the unless argument with 0 or 2+ targets (with only 1, the function will be skipped), although this behavior is likely unintended.

Usage: /function <namespace:path/to/function/file> [if|unless] [selector]

/gamerule gameLoopFunction

The /gamerule gameLoopFunction will run a function every tick. The commands in the function are run through the server.

Usage: /gamerule gameLoopFunction <namespace:path/to/function/file>

Advancement rewards

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.

Usage:

{
    "rewards": {
        "function": "namespace:path/to/function/file"
    }
}

History

Upcoming
1.12 {{Extension DPL}}<ul><li>[[Written Book|Written Book]]<br/>{{Item | title = Written Book | image = Written Book.gif | renewable = Yes | stackable = Yes (16) }} A '''written book''' is an [[item]] created after a [[book and quill]] is signed. == Obtaining == === Signing a book and quill === Written books can be obtained by signing a [[book and quill]]. After it has been signed, it cannot be edited again. The label does not say "Written Book", but whatever the [[player]] titles it. The title appears on the top line of the label, and "by <''player''>" (the player's username) on the bottom. {{IN|bedrock}}, this is customizable without [[commands]]. === Copying === {{crafting |name=Written Book |showdescription=1 |;;;Book and Quill;Book and Quill;Book and Quill;Book and Quill;Book and Quill |;;;;Book and Quill;Book and Quill;Book and Quill;Book and Quill |;;;;;Book and Quill;Book and Quill;Book and Quill |Book and Quill |Written Book |;;;;;;Book and Quill;Book and Quill |;Book and Quill;Book and Quill;Book and Quill;Book and Quill;Book and Quill;Book and Quill;Book and Quill |;;Book and Quill;Book and Quill;Book and Quill;Book and Quill;Book and Quill;Book and Quill |;;;;;;;Book and Quill |Output= Written Book; Written Book,2; Written Book,3; Written Book,4; Written Book,5; Written Book,6; Written Book,7; Written Book,8 |description=The input written book is not consumed.<br>The new copies are "Copy of Original" or "Copy of Copy", depending on whether the input written book is "Original" or "Copy of Original".<br>Copies of copies cannot be copied.<br>Copied books of the same generation ("Original", "Copy of Original", "Copy of Copy", or "Tattered") stack. |type=Miscellaneous }} == Usage == Written books can be opened by right-clicking (or holding down on the screen {{in|bedrock}}), and display a GUI allowing the [[player]] to read it or turn the page. The contents of a book are an extra set of data attached to the item. This means that when a book is destroyed, its contents are lost with it. === Lecterns === One can place a [[written book]] on an empty [[lectern]]. The lectern then emits a redstone signal depending on the displayed page in the book. On the last page, the lectern emits a signal strength of 15. === Chiseled bookshelf === {{control|Use|text=Using}} the [[chiseled bookshelf]] while having a written book in the main hand will put the book inside the chiseled bookshelf. == Sounds == {{edition|java}}: {{Sound table |sound=Page turn1.ogg |sound2=Page turn2.ogg |sound3=Page turn3.ogg |subtitle=Page rustles |source=master |description=When the page of a book is turned |id=item.book.page_turn |translationkey=subtitles.item.book.page_turn |volume=2.0 |pitch=1.0 |distance=16}} {{Sound table |sound=Page turn1.ogg |sound2=Page turn2.ogg |sound3=Page turn3.ogg |subtitle=Page rustles |source=block |description=When the page of a book is turned on a lectern |id=item.book.page_turn |translationkey=subtitles.item.book.page_turn |volume=2.0 |pitch=0.9-1.0 |distance=16}} {{Sound table |sound=Book thump1.ogg |sound2=Book thump2.ogg |subtitle=Book thumps |source=block |description=When a book is placed on a lectern |id=item.book.put |translationkey=subtitles.item.book.put |volume=1.0 |pitch=1.0 |distance=16}} {{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 written 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 written 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}} {{edition|bedrock}}: {{Sound table |type=bedrock |sound=Page turn1.ogg |sound2=Page turn2.ogg |sound3=Page turn3.ogg |source=sound |description=When the page of a book is turned |id=item.book.page_turn |volume=2.0 |pitch=1.0}} {{Sound table |sound=Book thump1.ogg |sound2=Book thump2.ogg |source=block |description=When a book is placed on a lectern |id=item.book.put |volume=4.8 |pitch=1.0}} {{Sound table |type=bedrock |sound=Chiseled bookshelf insert1.ogg |sound2=Chiseled bookshelf insert2.ogg |sound3=Chiseled bookshelf insert3.ogg |sound4=Chiseled bookshelf insert4.ogg |source=block |description=When a written book is placed in a chiseled bookshelf |id=insert.chiseled_bookshelf |volume=0.8 |pitch=''varies'' <ref group=sound>Can be 1.0, 0.85, or 1.1 for each sound</ref>}} {{Sound table |sound=Chiseled bookshelf pickup1.ogg |sound2=Chiseled bookshelf pickup2.ogg |sound3=Chiseled bookshelf pickup3.ogg |source=block |description=When a written book is removed from a chiseled bookshelf |id=pickup.chiseled_bookshelf |volume=0.8 |pitch=''varies'' <ref group=sound>Can be 1.0, 0.8, or 1.1 for each sound</ref> |foot=1}} == Data values == === ID === {{JE}}: {{ID table |edition=java |showitemtags=y |showforms=y |generatetranslationkeys=y |displayname=Written Book |spritetype=item |nameid=written_book |itemtags=bookshelf_books, lectern_books |form=item |foot=1}} {{BE}}: {{ID table |edition=bedrock |showitemtags=y |shownumericids=y |showforms=y |notshowbeitemforms=y |generatetranslationkeys=y |displayname=Written Book |spritetype=item |nameid=written_book |id=511 |itemtags=minecraft:bookshelf_books, minecraft:lectern_books |form=item |foot=1}} === Item data === {{el|java}}: {{main|Player.dat format}} <div class="treeview"> * {{nbt|compound|tag}}: The item's '''tag''' tag. {{:Player.dat_format/Written Books}} </div> {{el|bedrock}}: : See [[Bedrock Edition level format/Item format]]. == History == {{History|java}} {{History||1.3.1|snap=12w17a|[[File:Written Book JE1 BE1.png|32px]] Added written books.}} {{History|||snap=12w21a|Written books can now be [[trading|sold]] to librarian [[villager]]s, at 1 written book for 1 [[emerald]].}} {{History||1.7.2|snap=13w36a|Written books can now be cloned the same way [[map]]s can, but by using [[book and quill|books and quills]] instead of Empty Maps. Multiple copies of the same written book can be cloned by putting more book and quills in the crafting grid. |Written books can now be stacked (up to 16 per stack).}} {{History||1.8|snap=14w02a|[[Trading]] has been changed: librarian [[villager]]s now [[trading|buy]] 2 written books for 1 [[emerald]].}} {{History|||snap=14w05a|Copying written books now mark them as "Copy of Original" or "Copy of Copy". The copying status of a book is denoted in a separate line in the tooltip, beneath the author's name. Copies of copies cannot be copied.}} {{History||1.9|snap=15w33c|A written book titled "Work in Progress" now generates within a [[hopper]] as a part of the [[end ship]] in the [[end cities]]. It reads: "We will have something else here soon..." and is signed by [[Searge]].}} {{History|||snap=15w41a|End ships no longer contain a written book.}} {{History||1.13|snap=17w47a|Prior to [[1.13/Flattening|''The Flattening'']], this [[item]]'s numeral ID was 387.}} {{History||1.14|snap=18w43a|[[File:Written Book JE2 BE2.png|32px]] The texture of written books has been changed.}} {{History|||snap=19w02a|Written books can now be held on [[lectern]]s.}} {{History|||snap=19w11a|Librarian [[villager]]s no longer [[trading|buy]] written books.}} {{History||1.20<br>(Experimental)|link=1.19.3|snap=22w42a|Written books can now interact with [[chiseled bookshelves]].}} {{History|bedrock}} {{History||1.2.0|snap=beta 1.2.0.2|[[File:Written Book JE1 BE1.png|32px]] Added written books.}} {{History||1.10.0|snap=beta 1.10.0.3|[[File:Written Book JE2 BE2.png|32px]] The texture of written books has been changed. |Written books can now be held on [[lectern]]s.}} {{History|console}} {{History||xbox=TU25|xbone=CU14|ps=1.17|wiiu=Patch 1|[[File:Written Book JE1 BE1.png|32px]] Added written books.}} {{History|PS4}} {{History||1.90|[[File:Written Book JE2 BE2.png|32px]] The texture of written books has been changed.}} {{History|foot}} == Issues == {{issue list}} == Trivia == *When written books are obtained with [[commands]] (without the correct [[Player.dat format#Written Books|data tag]]), the label shows "Written Book" and has the text "*Invalid book tag*" when opened. The book is signed and cannot be edited without commands. *Commands that were added to a written book using serialized JSON objects are executed through the chat system. This means that any command added to a written book can't be longer than 256 characters, which is the maximum chat line limit. *During the 2020 April Fools Update [[Java Edition 20w14∞]], throwing a written book into a lit [[Nether Portal (block)|nether portal]] would create a portal to one of the 2,147,483,645 new dimensions. == Gallery == <gallery> Written Book tooltip.png|A signed book. Test by Dinnerbone.png|Copying a signed book. BookandQuillOperators12w17a.png|Different types of characters can be used to simulate a different font. JSON Book.png|First image of a book using JSON text. No NBT written book GUI.png|A no NBT written book using commands. Book Background (JE).png|Java Edition book background texture. Book Background (BE).png|Bedrock Edition book background texture. Book Arrowleft (JE).png|Java Edition left arrow texture. Book Arrowright (JE).png|Java Edition right arrow texture. Book Arrowleft (BE).png|Bedrock Edition left arrow texture. Book Arrowright (BE).png|Bedrock Edition Right arrow texture. </gallery> == See also == *[[Book]] *[[Bookshelf]] *[[Book and Quill]] {{Items}} [[Category:Renewable resources]] [[cs:Napsaná kniha]] [[es:Libro escrito]] [[fr:Livre édité]] [[hu:Megírt könyv]] [[it:Libro]] [[ja:記入済みの本]] [[ko:글이 쓰인 책]] [[nl:Geschreven boek]] [[pl:Zapisana książka]] [[pt:Livro escrito]] [[ru:Написанная книга]] [[uk:Написана книга]] [[zh:成书]]</li><li>[[Kelp|Kelp]]<br/>{{About|the plant|the dried variant|Dried Kelp}} {{For}} {{Block |image=Kelp.gif |invimage=Kelp |transparent=Yes |tool=Any |renewable=Yes |stackable=Yes (64) |flammable=No |lavasusceptible=No |light=No |hardness=0}} '''Kelp''' is an underwater plant that generates in most [[ocean]]s. == Obtaining == === Natural generation === Kelp naturally generates in any [[ocean]] [[biome]]s (except in [[Frozen Ocean|frozen]], [[Deep Frozen Ocean|deep frozen]] and [[Warm Ocean|warm]]), near and around [[seagrass]]. Each chunk has {{frac|1|18}} chance to generate a [[vegetation]] of kelp. === Breaking === Kelp can be mined instantly with any [[tool]] or with the player's fist. Removing water from the kelp block destroys the kelp. Breaking one part of a kelp stalk destroys all kelp [[block]]s above it. Each block drops a kelp [[item (entity)|item]]. === Trading === Kelp can be bought from [[wandering trader]]s for 3 emeralds. == Usage == Kelp can be placed underwater by hand, or anywhere by the use of [[commands]] such as {{cmd|setblock}}. Placing it by hand gives it a random {{code|age}} value between 0 and 24. Kelp can be placed only in [[water]] source blocks or downward-flowing water, not horizontally flowing water. When placed in downward-flowing water, the flowing water transforms into a water source block,<ref>{{bug|MC-134229}}</ref> which is useful for faster [[bubble column]] elevator creation. Any building block can be placed on top of a kelp plant, which is useful for building structures over a deep ocean without needing to build from the ocean floor (see also [[lily pad]]). === Cooking ingredient === {{smelting | showname = 1 | Kelp | Dried Kelp | 0.1 }} === Composting === Placing kelp into a [[composter]] has a 30% chance of raising the compost level by 1. === Growth mechanics === Kelp can be planted on a broad variety of blocks. It grows underwater if it has either a source block of water or, {{in|Java}}, flowing water above it.<ref>{{bug|MC-133354}}</ref> Neither [[player]]s nor [[dispenser]]s can remove the water source block that kelp grows in without breaking the kelp first. Kelp does not require any [[light]] level to grow. Kelp also grows without having [[sky]] access. [[Bone meal]] can be used to grow kelp by 1 block on each use. Kelp, when planted, is generated with a randomly chosen age value, which can be checked when pressing [[Debug screen|<kbd>F3</kbd>]]{{only|java}}. The age value of a newly planted kelp plant varies randomly from 0 to 24. Each time the kelp grows in height by one block, the newly generated top of the kelp plant increases its age by 1. When the top block of the kelp plant reaches an age of 25, it stops growing. This means that kelp can naturally grow to a height between 2 (if the first kelp plant had an age of 24) and 26 blocks (if the first kelp plant had an age of 0). When a kelp plant block is broken, the age of the kelp plant block underneath is randomized to a value from 0 to 24 and the kelp continues growing until it reaches age 25. It is possible to use this mechanic to cultivate a kelp plant to increase its growth height beyond its natural maximum height of 26 blocks. This can be done by breaking the top-most block of the kelp plant each time it reaches age 25. A kelp plant cultivated by a player in this way repeatedly grows until it reaches the water surface. Each time it receives a [[random tick]], kelp has a 14% chance of growing. If [[shears]] are used on the topmost block of kelp, that block automatically sets its {{cd|age}} value to {{cd|25}} and stop growing.{{only|JE}} === Farming === {{Main|Tutorials/Kelp farming}} Kelp farming is similar to farming [[sugar cane]], although kelp must be placed underwater. Automation of harvest is easier because items float up in water. == Sounds == === Generic === {{Sound table/Block/Wet grass}} === Unique === {{edition|java}}: {{Sound table |sound=Shear.ogg |subtitle=Plant cropped |source=block |description=When the tip of kelp is cropped with [[Shears#Cropping growing plants|shears]] |id=block.growing_plant.crop |translationkey=subtitles.block.growing_plant.crop |volume=1.0 |pitch=1.0 |distance=16 |foot=1}} {{edition|bedrock}}: ''None'' == Data values == === ID === {{edition|java}}: {{ID table |edition=java |showforms=y |generatetranslationkeys=y |displayname=Kelp |spritetype=block |nameid=kelp}} {{ID table |displayname=Kelp Plant |spritetype=block |nameid=kelp_plant |form=block |foot=1}} {{edition|bedrock}}: {{ID table |edition=bedrock |firstcolumnname=Kelp |shownumericids=y |showforms=y |generatetranslationkeys=y |displayname=Item |spritename=kelp |spritetype=item |nameid=kelp |id=382 |form=item}} {{ID table |displayname=Block |spritename=kelp |spritetype=block |nameid=kelp |id=393 |form=block |itemform=item.kelp |translationkey=- |foot=1}} === Block states === {{see also|Block states}} {{/BS}} == History == {{History|java classic}} {{History||May 21, 2009|link=https://web.archive.org/web/0/http://notch.tumblr.com/post/110762705/my-list-on-tile-types-so-far|[[Notch]] shows interest in adding a "[[seaweed]]" [[block]].}} {{History|java}} {{History||November 18, 2017|link={{YouTubeLink|mAapz_nIC_Y}}|Kelp plants were shown in a clip of [[MineCon Earth]].}} {{History||1.13|snap=18w07a|[[File:Kelp JE1 BE1.gif|32px]] [[File:Kelp (item) JE1 BE2.png|32px]] Added kelp.}} {{History|||snap=18w07b|Kelp now behaves more like [[water]], meaning [[mob]]s can no longer spawn within the plant under water nor can they replenish their breath by [[swimming]] through it.}} {{History|||snap=18w10a|[[File:Kelp JE2.gif|32px]] The texture for kelp has been overhauled.}} {{History|||snap=18w14a|[[File:Kelp.gif|32px]] Top of the kelp textures have been shifted slightly downward. |The generation rules for kelp have been changed, it now mainly generates in [[cold ocean]] [[biome]]s and can no longer generate in [[warm ocean]]s.}} {{History|||snap=18w20a|The {{cd|kelp_top}} has been changed ID to {{cd|kelp}} and {{cd|kelp}} has been changed to {{cd|kelp_plant}}, for both the [[block]] and [[item]] forms.}} {{History|||snap=pre2|Kelp is now destroyed by [[sponge]]s.<ref>{{bug|MC-127111}}</ref>}} {{History|||snap=pre6|Added 5 new [[sound]] events that apply to kelp: <code>block.wet_grass.break</code>, <code>block.wet_grass.fall</code>, <code>block.wet_grass.hit</code>, <code>block.wet_grass.place</code>, and <code>block.wet_grass.step</code>.}} {{History||1.14|snap=19w03a|Placing kelp into the new [[composter]] has a 10% chance of raising the compost level by 1.}} {{History|||snap=19w05a|Kelp now has a 30% chance of increasing the compost level in a composter by 1. |Added [[Wandering Trader|wandering trader]]s, which sell kelp.}} {{History||1.16|snap=20w11a|Kelp can now be grown with [[bone meal]].}} {{History|||snap=20w13a|Kelp has been moved from the Miscellaneous tab to the Decoration Blocks tab in the [[Creative inventory]].<ref name="misc decoration">https://bugs.mojang.com/browse/MC-174434</ref>}} {{History||1.17|snap=20w46a|Kelp no longer generates on magma blocks.<ref>{{Bug|MC-185605|resolution=Fixed}}</ref>}} {{History||1.18|snap=21w37a|Kelp now stops growing if [[shears]] are used on the tip.}} {{History|bedrock}} {{History||1.4.0|snap=beta 1.2.14.2|[[File:Kelp JE1 BE1.gif|32px]] [[File:Kelp (item) BE1.png|32px]] Added kelp.}} {{History|||snap=beta 1.2.20.1|[[File:Kelp (item) JE1 BE2.png|32px]] The kelp [[item]] texture has been updated to the {{el|je}}'s.}} {{History||1.5.0|snap=beta 1.5.0.4|[[File:Kelp.gif|32px]] The texture of the kelp plant has been updated.}} {{History||1.10.0|snap=beta 1.10.0.3|Kelp can now be bought from [[wandering trader]]s for 3 [[emerald]]s.}} {{History||1.11.0|snap=beta 1.11.0.1|Kelp can now be used to fill [[composter]]s.}} {{History|console}} {{History||xbox=TU69|ps=1.76|wiiu=Patch 38|[[File:Kelp.gif|32px]] [[File:Kelp (item) JE1 BE2.png|32px]] Added kelp.}} {{History|foot}} == Issues == {{issue list}} == Trivia == * In real life, [[wikipedia:kelp|kelp]] is not considered a [[wikipedia:plant|plant]]. It is classified by scientists as a [[wikipedia:Brown algae|brown algae]]. ** Kelp in real life absorbs nutrients directly from the water, instead of through its root-like structure, [[wikipedia:Holdfast (biology)|holdfast]], which merely attaches it to the seabed. This is in accordance with kelp being able to grow on almost any solid block in ''Minecraft''. == Gallery == <gallery heights="60"> SeaPlantsMineConEarth2017.jpg|Kelp shown in a clip from MINECON Earth 2017. Kelp in ocean with Jappa textures.jpg|Naturally generated kelp in an [[ocean]] biome. Kelp on shoreline.png|Naturally generated kelp near the shore. Ocean life.png|An ocean with kelp visible in the far distance. Kelp on Land.png|Kelp placed outside of [[water]] using the {{cmd|setblock}} command before 18w07b. Waterless kelp.png|What kelp looks like without water (water removed using a [[resource pack]]). Coral reef at night.png|Kelp within a [[coral reef]]. Floating Kelp.png|Kelp that generated in mid-air due to an [[ocean monument]]'s water cutting through it. Kelp in ocean.jpg|Multiple kelps. Kelp 255 blocks tall.png|Without obstacles, kelp can grow all the way to building limit. ArgoMajor Kelp.jpg|First image of kelp in ''Bedrock Edition''. </gallery> == References == {{reflist}} {{Blocks|vegetation}} {{Items}} [[Category:Plants]] [[Category:Natural blocks]] [[Category:Non-solid blocks]] [[de:Seetang]] [[es:Alga]] [[fr:Algue]] [[ja:コンブ]] [[ko:켈프]] [[pl:Wodorosty]] [[pt:Alga]] [[ru:Ламинария]] [[th:สาหร่ายทะเล]] [[zh:海带]]</li></ul>		1.12-pre1			Added functions.
		1.12-pre3			Commands are no longer allowed to begin with a / (forward slash)
					Comments must now be proceeded by a #; using // is no longer allowed
		1.12-pre4			Added new arguments: [if|unless] [selector]

Issues

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

See also

• Advancements
• JSON format