関数 (Java Edition)

Bedrock Editionについては「関数 (Bedrock Edition)」をご覧ください。

関数（英：Function）は、複数のコマンドを一纏めにして簡単に実行するための機能である。データパック内にテキストファイルとして保存することで/functionを介して実行することができる。

関数はコマンドブロックよりもラグを引き起こしにくく、またテキストファイルであるために極めて簡単に編集することができる。さらに関数ではコマンドの中に変数を挿入し、実行の際に値を取得しそこへ代入することができるマクロ機能も存在し、高い機能性を持つ。

定義方法

格納位置

関数はデータパック内のdata/<名前空間名>/functions下に拡張子.mcfunctionのテキストファイルで保存する。エンコード方式にはBOM無しのUTF-8が推奨される。

functionsフォルダ下には他のデータパックのディレクトリ同様下位フォルダを設けることができ、この下位フォルダ下に格納した関数ファイルも正しく関数として認識される。ここで、下位フォルダ下に格納した関数のIDは<名前空間名>:<下位フォルダ名>/.../<ファイル名>となる。

フォーマット

関数ファイルには、実行したいコマンドを実行したい順に、一行に一コマンドずつ記述していく。この際、コマンドの前に/を前置する必要はない。

#から始まる行はコメントとして見なされ、実際の実行の際には無視される。関数内のコマンドに補足を付す際に利用できる。

\（バックスラッシュ）を行の最後に付すと、そのコマンドの続きを次の行に記述することができる。これを用いずに改行した場合は、改行より先は別のコマンドとして認識されてしまう。なお後述のスペース無視の使用の関係上、改行地点でスペースを使用する場合は必ず\の前にスペースを書いておかねばならない。

コマンドの引数と引数の間にスペースを複数挿入することはできないが、各行の先頭と末尾にある空白およびインデントはコマンドの解釈時に無視される。

マクロ関数

$を行の初めに付すとその行はマクロ行として認識されるようになる。マクロ行ではコマンドの構文中に$(<変数名>)と記述することで、実行時にそこに値を代入するように設定できる。

代入する値は/functionでの実行時に コンパウンドを用いて指定する。このコンパウンドには{<変数名1>: "<代入値1>", <変数名2>: "<代入値2>", ... }のように、その関数内で使用されている変数とそこに代入する値の組がすべて記述されていなければならない。

このコンパウンドは実行時に手動で直接記述することもできるが、/data get ...コマンドに類似した形式によって、ワールド内のブロックエンティティ、エンティティ、NBTストレージのNBT内にある コンパウンドを取得して利用することもできる。

なお多くの場合こうしたワールド内の対象から取得したコンパウンドが格納する値には 整数や リストといった様々な種類が存在するが、これらは全て代入の際に文字列に変換される。手動で直接記述する場合でも、代入値の部分は（スペースを含む場合には引用符で囲むなど）文字列としての形式を満たさねばならない。この際、数値データのデータ型を示す接尾辞は削除される。また（特にワールド内からコンパウンドを取得した場合において）コンパウンドにはそのマクロで使用していない値が格納されている場合もあり得るが、マクロ関数は自身の使用する値が存在しさえすればこれについては特に気にしない。

関数の実行時には指定された値を代入した上で代入のあったコマンドのみを構文解析し、実行へ移る。ここで、値の代入の結果一部のコマンドの構文に誤りが生じている場合には、関数全体の実行が破棄される。

コマンドの制限

関数内では、コマンドブロックと違ってコマンド一つ当たりの文字数制限（32500字）は存在しない。ただし関数は全てのコマンドを1ティック以内に実行するが、1ティック内に実行できるコマンドの個数はゲームルールmaxCommandChainLength（コマンドの最大チェーン数）で制限されている。この値のデフォルト値は65536である。

なお「実行文脈」の分岐がある場合はそれぞれの分岐におけるコマンドの実行がすべて計上されるほか、関数の呼び出し・/executeのサブコマンドの実行も同様に計上される。

また関数内に存在する/executeにより「実行文脈分岐」が生じることがあるが、作成できる実行文脈はゲームルールmaxCommandForkCout〔コマンドの実行文脈数上限〕‌で制限されており、この値のデフォルト値は65536である。

シングルプレイおよびLANに公開したワールドでは、関数の権限レベルはコマンドブロックと同等の2であり、これ以上の高権限が必要なコマンドを実行することはできない。

マルチプレイでは、関数の権限レベルはserver.propertiesで定義されたfunction-permission-levelになる。

呼び出し方

関数は/functionコマンド・/execute (if|unless) functionコマンド・進捗・および関数タグで呼び出すことができる。

functionコマンド

/function

• 一つの関数、または一つの関数タグに属する全ての関数を実行できる。
• マクロ関数を使用している場合には、実行時に変数部分に代入する値を与えるコンパウンドを指定する必要がある。

functionサブコマンド

/execute (if|unless) function ... run ...

• 一つの関数、または関数タグに含まれる関数すべてを実行し、その戻り値に従って条件の絞り込みを行う。
  • 条件を通過できるのは、「/returnコマンドによって戻り値が与えられている」かつ「その戻り値が0でない」関数が一つ以上存在した場合である。
  • /returnコマンドで戻り値が与えられたコマンドが一つもない場合は、if構文は失敗、unless構文は通過する。

進捗

カスタム進捗はワールド内で特定の事象が起きたことを検知するのに極めて有用である。進捗は達成時に関数を呼び出すことができ、これを利用することで特定の事象に反応してコマンドを実行させるよう設定できる。 進捗は、その達成報酬として一度関数を実行することができる。関数のコマンドは、進捗を達成したプレイヤーを介して実行される。

報酬の関数は、次の形式を使用して進捗のJSONファイルから使用することができる。なおここでは関数タグを使用することはできない。

{
    "rewards": {
        "function": "<名前空間名>:<関数のID>"
    }
}

タグ

タグを使用することで関数をグループ化することができ、一部の場面においては関数の代わりに関数タグを指定することでタグに含まれるすべての関数を実行できることは既述の通りである。なお補足として、一つのタグ内に同じ関数が複数登録されている場合には、最初の一つ分のみが実行される。

しかし関数タグの中でも、以下の2つは特殊な振る舞いによって関数を自動的に実行させることができる。

• minecraft:tick でタグ付けされた関数は、毎ティック開始時に実行される。
• minecraft:load でタグ付けされた関数は、ワールドが読み込まれた時（もしくは再読み込みされた時）、サーバーが開始された時に一度関数を実行するようになる。
  • この時点ではプレイヤーはワールドに参加していないため、ターゲットセレクターやプレイヤー名を指定してもプレイヤーをコマンドの対象にすることはできない。

注：ワールドが読み込まれた最初のティックにおいては、tickタグの関数の方が先に実行される。したがってワールド開始時点から実行される関数の順序は、tickタグ、loadタグ、tickタグ、tickタグ...となる。

呼び出し時の挙動

関数は、呼び出されたティック中に自身が含むコマンドの全てを実行する。関数の中で呼び出された関数についても、呼び出し元の関数と同じティック内にすべてのコマンドを実行する。実行地点とその回転やディメンション、ターゲットセレクターの基準である実行者などといった状況パラメータは、関数を実行した要因が使用していたものをそのまま使用する。/executeを使ってこうした状況パラメータの基準を変更した場合、その変更はその/executeコマンド内でのみ適用され、次のコマンドに引き継がれることはないため、必要な際に逐一/executeコマンドを使用する必要がある。

歴史

Java Edition
1.12		1.12-pre1			関数が追加された。
		1.12-pre3			コマンドが /（スラッシュ）から始められなくなった。
					コメントの前には # しか付けられなくなり、// が使えなくなった。
		1.12-pre4			/function コマンドに新しい引数が追加された: [if|unless] [対象]
		1.12-pre6			スキップされた関数（条件が失敗した場合）がコマンドで使用されると、失敗と見なされるようになった。
1.13		17w43a			オリジナルの関数がデータパックへ移動された。
		17w45a			ロード時に関数がすべて読み込みおよびキャッシュされるようになった。
		17w49b			関数をタグ付けできるようになった。
					minecraft:tick でタグ付けされた関数が、ティックごとに関数を実行するようになった。
		18w01a			load のファンクションタグが、データパックの(リ)ロードを追跡するようになった。
1.14.4		pre4			server.propertiesに function-permission-level が追加された。
1.20		23w16a			関数を終了させ関数の戻り値を指定することの出来るコマンド/returnが追加された。
1.20.2		23w31a			改行に\が使えるようになった。
					/execute (if|unless) function ...が追加され、条件確認に使用されうるようになった。
					/return run ...構文の追加により、関数の戻り値に別のコマンドの戻り値を使用できるようになった。
					マクロ機能が追加された。
		Pre-release 1			/execute (if|unless) function ...および/return run ...構文が一時的に削除された。
					数値データのデータ型を示す接尾辞が代入時に削除されるようになった。
開発中のJava Edition
1.20.5		24w06a			関数内のコマンドの最大文字数が、マクロを含めて200万文字に制限された。

問題点

「関数」に関する問題点は、バグトラッカーにて管理されている。問題点の報告はそちらで行ってほしい。