関数 (Java Edition)

この項目はJava Edition限定の要素です。

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

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

定義方法

格納位置

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

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

フォーマット

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

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

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

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

マクロ関数

この節には、Java Editionのアップデートに含まれる要素に関する内容が含まれています。

この要素はJava Edition の開発版では登場していますが、この要素を含む正式なアップデートは行われていません。

$を行の初めに付すとその行はマクロ行として認識されるようになる‌^{[JE 1.20.2で追加予定]}。マクロ行ではコマンドの構文中に$(<変数名>)と記述することで、実行時にそこに値を代入するように設定できる。\でコマンドの途中で行分けしている場合、その行の初めに$を記述すればその部分のみマクロ行とすることも可能である。

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

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

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

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

関数を次々と実行していく場合、ゲームは直近数個の関数で使用されている変数をキャッシュしようとする。したがって、同じ変数を使用している関数は可能であれば連続して実行した方が負荷が少ない。

コマンドの制限

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

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

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

呼び出し方

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

functionコマンド

/function

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

functionサブコマンド

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

一つの関数、または関数タグに含まれる関数すべてを実行し、その戻り値に従って条件の絞り込みを行う。
- 条件を通過できるのは、「関数が最低一つ成功」し、「その関数が/returnによって終了」し、「その関数の戻り値が0でない」場合である。

進捗

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

報酬の関数は、次の形式を使用して進捗の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-pre3	コメントの前には # しか付けられなくなり、// が使えなくなった。
	1.12-pre4	`/function` コマンドに新しい引数が追加された: `[if\|unless] [対象]`
	1.12-pre6	スキップされた関数（条件が失敗した場合）がコマンドで使用されると、失敗と見なされるようになった。
1.13	17w43a	オリジナルの関数がデータパックへ移動された。
	17w45a	ロード時に関数がすべて読み込みおよびキャッシュされるようになった。
	17w49b	関数をタグ付けできるようになった。
	17w49b	`minecraft:tick` でタグ付けされた関数が、ティックごとに関数を実行するようになった。
	18w01a	`load` のファンクションタグが、データパックの(リ)ロードを追跡するようになった。
1.14.4	pre4	server.propertiesに `function-permission-level` が追加された。
1.20	23w16a	関数を終了させ関数の戻り値を指定することの出来るコマンド`/return`が追加された。
開発中のJava Edition
1.20.2	23w31a	改行に`\`が使えるようになった。
		`/execute (if\|unless) function ...`が追加され、条件確認に使用されうるようになった。
		`/return run ...`構文の追加により、関数の戻り値に別のコマンドの戻り値を援用できるようになった。
		マクロ機能が追加された。

問題点

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