Java版函数

  本文章介绍的是Java版中的函数。关于基岩版的函数，请见“基岩版函数”。关于函数的命令，请见“命令/function”。

函数（Function）是一个允许玩家利用扩展名为.mcfunction的文本文档编写和运行多行命令的功能。本页面主要讲述如何使用Java版中的函数。

用法

要使用函数，首先必须在[世界名称]/datapacks/[数据包名称]/data/[命名空间]/functions这个顶层文件夹中放置名为[函数名称].mcfunction文本文档，这个文档将包含此函数内所有需要执行的命令。注意它必须是UTF-8无BOM的格式，否则将不能被Minecraft读取。如果是单人游戏，这个世界文件夹可以在.minecraft/saves中找到；如果是多人游戏，函数必须放置在每一个需要使用这个函数的世界文件夹中。这个顶层文件夹的名字将在调用其中函数时作为其命名空间。

在执行函数时，推荐写为严谨格式[命名空间]:[函数名称]。如果你可以确认你的函数不和其他现有函数冲突，则可以简写为[函数名称]，程序将先遍历默认命名空间minecraft:中的函数名称，再检索其他命名空间。但是为了避免在未来的版本因为Mojang对默认命名空间的改动而导致意料之外的事，最好使用自定义的命名空间并明确地使用它。当然，函数也可以被放置在这个顶层文件夹的子文件夹中。例如，如果需要调用datapacks/[数据包名称]/data/custom/functions/example/test.mcfunction的函数文件。则需描述为custom:example/test（相对路径）

作为一个文本文件，函数可以很容易地进行修改，并且在执行大量命令时更不容易像命令方块一样造成延迟。如果对函数文件或其位置进行了修改，则可以使用/reload来重新从硬盘加载整个数据包。这允许Minecraft识别对函数文件的更改，而不必退出并重新进入世界。

成功执行函数将会在聊天栏显示信息：执行了函数[函数名]中的[数量]条命令。函数内部命令的成功与否并不能直接被比较器检测（虽然你还是可以通过/execute与/scoreboard来获取这些信息）。

函数格式

测试函数系统。这个简单的函数使用了发送了3次/tellraw消息，执行了1次/give命令

在一个.mcfunction文档里，每一条有效的命令占据一行，并且不允许在行首使用斜杠。函数允许空行，也可以在函数文档中通过#来添加注释。

在函数文档中，单个命令的长度不受命令方块字符数上限32,500的限制，但是同一游戏刻运行的总命令数量受/gamerule maxCommandChainLength的限制（默认为65536）。超过此数量限制的命令将在运行时被忽略。

函数的运行

函数将在一游戏刻内运行其中的所有命令。同时，如果一个函数是被其他的函数所引用，那么它将同其父函数在同一游戏刻运行。函数会使用函数调用者的命令环境，这包括命令执行者、位置、坐标等。

无论命令的顺序如何，对函数内发生的命令环境的更改都不会影响同一函数内（及其子函数内）其他命令使用的命令环境，直到下一次迭代为止。 /execute命令是一个例外，它将更新命令环境。

例如：

execute as @a at @s run function foo:bar

其中foo:bar的内容是：

teleport @s ~ ~5 ~
setblock ~ ~-1 ~ minecraft:emerald_block
execute at @s run setblock ~ ~-1 ~ minecraft:diamond_block

这3个命令会将所有玩家向上传送5个方块、在玩家传送前位置的脚下放置绿宝石块，再于玩家传送后位置的脚下放置钻石块。这个特性不会影响到命令中出现的目标选择器参数。

游戏中目前有以下几种方式运行函数：

命令

/function

• 允许玩家运行一个函数一次。
• 函数中命令的执行者为执行此命令的实体或命令方块。
• 语法：function <name>

/schedule

• 允许在延迟指定时间后执行函数。
• 函数将由服务器执行，没有执行者，执行位置在世界出生点

进度

达成一个进度时，可以运行一个函数作为奖励。函数中命令的执行者是达成进度的玩家。

奖励函数在进度JSON文件中通过以下方式调用：

{
    "rewards": {
         "function": "命名空间:指向函数文件的路径"
    }
}

标签

函数可以通过数据包中的标签组合到一起。之后可以使用/function #(命名空间):tag调用标签来运行该标签内的所有函数。

有tick标签的函数会自动在每一个游戏刻的开始运行。有load标签的函数会在加载数据包之后运行。

历史

Java版
1.12		pre1			加入了函数。
		pre3			函数中的命令不再允许以/开头。
					现在仅能使用#来注释，不再允许使用先前的//。
		pre4			加入了新的参数：[if|unless] [选择器]。
		pre6			在命令中使用函数时，函数执行被跳过（执行条件不符）的情况现在被视为命令失败。
1.13		17w43a			自定义函数被移动至数据包中。
		17w45a			函数在加载时就会被完全解析与缓存。
		17w49b			函数现在可以有标签了。
					标签了tick的函数现在会在每一个游戏刻的开始时执行。