函數(Function)是一個允許玩家利用擴展名為.mcfunction的文字文件編寫和執行多行指令的功能。本頁面主要講述如何使用Java版中的函數。
用法
要使用函數,首先必須在[世界名称]/datapacks/[数据包名称]/data/[命名空间]/functions這個頂層資料夾中放置名為[函数名称].mcfunction文字文件,這個文件將包含此函數內所有需要執行的指令。注意它必須是UTF-8無BOM的格式,否則將不能被Minecraft讀取。如果是單人遊戲,這個世界資料夾可以在.minecraft/saves中找到;如果是多人遊戲,函數必須放置在每一個需要使用這個函數的世界資料夾中。這個頂層資料夾的名字將在調用其中函數時作為其命名空間。
在執行函數時,推薦寫為嚴謹格式[命名空间]:[函数名称]。如果你可以確認你的函數不和其他現有函數衝突,則可以簡寫為[函数名称],程式將先遍歷預設命名空間minecraft:中的函數名稱,再檢索其他命名空間。但是為了避免在未來的版本因為Mojang對預設命名空間的改動而導致意料之外的事,最好使用自訂的命名空間並明確地使用它。[1]當然,函數也可以被放置在這個頂層資料夾的子資料夾中。例如,如果需要調用datapacks/[数据包名称]/data/custom/functions/example/test.mcfunction的函數檔案。則需描述為custom:example/test(相對路徑)
作為一個文字檔案,函數可以很容易地進行修改,並且在執行大量指令時更不容易像指令方塊一樣造成延遲。如果對函數檔案或其位置進行了修改,則可以使用/reload來重新從硬碟載入整個資料包。這允許Minecraft識別對函數檔案的變更,而不必退出並重新進入世界。
成功執行函數將會在聊天欄顯示資訊:執行了函數[函數名]中的[數量]條指令。函數內部指令的成功與否並不能直接被比較器檢測(雖然你還是可以透過/execute與/scoreboard來取得這些資訊)。
函數格式
在一個.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 <name>
- 允許在延遲指定時間後執行函數。
- 函數將由伺服器執行,沒有執行者,執行位置在世界重生點
進度
達成一個進度時,可以執行一個函數作為獎勵。函數中指令的執行者是達成進度的玩家。
獎勵函數在進度JSON檔案中透過以下方式調用:
{
"rewards": {
"function": "命名空间:指向函数文件的路径"
}
}
標籤
函數可以透過資料包中的標籤組合到一起。之後可以使用/function #(命名空間):tag調用標籤來執行該標籤內的所有函數。
在minecraft命名空間下,有tick標籤的函數會自動在每一個遊戲刻的開始執行;有load標籤的函數會在載入資料包之後執行。
註:在minecraft:tick標籤中的第一個函數將在minecraft:load中的函數執行前執行。這意味著,假定minecraft:tick中依次有tick1、tick2、tick3,minecraft:load中有load1,則/reload後函數的執行順序為:tick1、load1、tick2、tick3...
歷史
| Java版 | |||||
|---|---|---|---|---|---|
| 1.12 | pre1 | 加入了函數。 | |||
| pre3 | 函數中的指令不再允許以/開頭。
| ||||
現在僅能使用#來注釋,不再允許使用先前的//。 | |||||
| pre4 | 加入了新的參數:[if|unless] [选择器]。 | ||||
| pre6 | 在指令中使用函數時,函數執行被跳過(執行條件不符)的情況現在被視為指令失敗。 | ||||
| 1.13 | 17w43a | 自訂函數被移動至資料包中。 | |||
| 17w45a | 函數在載入時就會被完全解析與快取。 | ||||
| 17w49b | 函數現在可以有標籤了。 | ||||
標籤了minecraft:tick的函數現在會在每一個遊戲刻的開始時執行。 | |||||
參考
| 組件 |
| ||
|---|---|---|---|
| 資料包 | |||
| 教學 | |||
| 版本 | |||||||
|---|---|---|---|---|---|---|---|
| 開發週期 |
| ||||||
| 技術 |
| ||||||
| 多人遊戲 | |||||||
| 遊戲訂製 | |||||||