目次

はじめに
モジュールの種類
ScriptAPIの仕様
その他
- 他ファイルの参照
- eval関数の利用方法
最後に

はじめに

前回はScriptAPIの始め方ということで投稿しましたが、厳密に情報の説明が出来ていなかったので、今回はそれも兼ね、ScriptAPIの情報を纏めていきたいと思います。

最新バージョンが更新される度に出来るだけ早く更新するように心がけていますが、情報が追い付いていない可能性がありますので、予めご了承ください。(最終更新2024/09/14)

この「ScriptAPI参考書」シリーズではマインクラフト統合版のScriptAPIについて基礎から応用、例文まで詳細に解説し、ScriptAPI開発者や、ScriptAPIの開発を始めようと思っている人の助けになることを目的としています。

また、このシリーズを読むにあたって、ある程度のマインクラフトとJavaScriptの事前知識が必要になってくることがあります。

注意: このシリーズではMinecraft Bedrock Editionを省略してマインクラフトと表記しています。

前回: ScriptAPIの始め方
次回: 基本的な扱い

モジュールの種類

前回解説したのはScriptAPIの@minecraft/serverについてでしたが、他にも様々なモジュールがあります。

@minecraft/server

主に使用するモジュールで、プレイヤーやエンティティ、ワールドの操作を行えます。

manifest.jsonの詳細 (安定版)

manifest.json

{
    "module_name": "@minecraft/server",
    "version": "1.15.0"
}

NPMのバージョン

種類	バージョン
Stable	1.15.0
Beta	1.16.0-beta.1.21.42-stable
Preview Stable	1.16.0-rc.1.21.50-preview.25
Preview Beta	1.17.0-beta.1.21.50-preview.25

利用可能なmanifest.jsonの最新バージョン [安定版]

種類	バージョン	詳細
Stable	1.15.0	-
Beta	1.16.0-beta	BetaAPIの有効化が必要
Alpha	2.0.0-alpha	他モジュールもalphaの使用が必要

利用可能なmanifest.jsonの最新バージョン [プレビュー]

種類	バージョン	詳細
Stable	1.16.0	-
Beta	1.17.0-beta	BetaAPIの有効化が必要
Alpha	2.0.0-alpha	他モジュールもalphaの使用が必要

Document | npm

@minecraft/server-ui

マインクラフトのUIを表示の際に使用するモジュールです。以下の様なフォームを表示したり、操作したりすることが出来ます。

manifest.jsonの詳細 (安定版)

manifest.json

{
    "module_name": "@minecraft/server-ui",
    "version": "1.3.0"
}

NPMのバージョン

種類	バージョン
Stable	1.3.0
Beta	1.4.0-beta.1.21.43-stable
Preview Stable	1.3.0-rc.1.21.40-preview.21
Preview Beta	1.4.0-beta.1.21.50-preview.25

利用可能なmanifest.jsonの最新バージョン [安定版]

種類	バージョン	詳細
Stable	1.3.0	-
Beta	1.4.0-beta	BetaAPIの有効化が必要
Alpha	2.0.0-alpha	他モジュールもalphaの使用が必要

利用可能なmanifest.jsonの最新バージョン [プレビュー版]

種類	バージョン	詳細
Stable	1.3.0	-
Beta	1.4.0-beta	BetaAPIの有効化が必要
Alpha	2.0.0-alpha	他モジュールもalphaの使用が必要

Document | npm

@minecraft/server-gametest

マインクラフトのGameTest機能を扱う事が出来ます。

manifest.jsonの詳細 (安定版)

manifest.json

{
    "module_name": "@minecraft/server-gametest",
    "version": "0.1.0"
}

NPMのバージョン

種類	バージョン
Stable	0.1.0
Beta	1.0.0-beta.1.21.43-stable
Preview Stable	0.1.0-rc.1.21.40-preview.20
Preview Beta	1.0.0-beta.1.21.50-preview.25

利用可能なmanifest.jsonの最新バージョン [安定版]

種類	バージョン	詳細
Stable	0.1.0	-
Beta	1.0.0-beta	BetaAPIの有効化が必要
Alpha	2.0.0-alpha	他モジュールもalphaの使用が必要

利用可能なmanifest.jsonの最新バージョン [プレビュー版]

種類	バージョン	詳細
Stable	0.1.0	-
Beta	1.0.0-beta	BetaAPIの有効化が必要
Alpha	2.0.0-alpha	他モジュールもalphaの使用が必要

Document | npm

@minecraft/server-net

マインクラフトの外部とHTTPベースのリクエストを実行することが出来ます。
BDSサーバーでのみ使用可能な点に注意。

manifest.jsonの詳細 (ベータ版)

manifest.json

{
    "module_name": "@minecraft/server-net",
    "version": "1.0.0-beta"
}

NPMのバージョン

種類	バージョン
Stable	-
Beta	1.0.0-beta.1.21.43-stable
Preview Stable	-
Preview Beta	1.0.0-beta.1.21.50-preview.25

利用可能なmanifest.jsonの最新バージョン [安定版]

種類	バージョン	詳細
Stable	-	-
Beta	1.0.0-beta	BetaAPIの有効化が必要
Alpha	2.0.0-alpha	他モジュールもalphaの使用が必要

利用可能なmanifest.jsonの最新バージョン [プレビュー版]

種類	バージョン	詳細
Stable	-	-
Beta	1.0.0-beta	BetaAPIの有効化が必要
Alpha	2.0.0-alpha	他モジュールもalphaの使用が必要

Document | npm

@minecraft/server-admin

BDSサーバーの管理をするための機能を扱うことが出来ます。
BDSサーバーでのみ使用可能な点に注意。

manifest.jsonの詳細 (ベータ版)

manifest.json

{
    "module_name": "@minecraft/server-admin",
    "version": "1.0.0-beta"
}

NPMのバージョン

種類	バージョン
Stable	-
Beta	1.0.0-beta.1.21.43-stable
Preview Stable	-
Preview Beta	1.0.0-beta.1.21.50-preview.25

利用可能なmanifest.jsonの最新バージョン [安定版]

種類	バージョン	詳細
Stable	-	-
Beta	1.0.0-beta	BetaAPIの有効化が必要
Alpha	2.0.0-alpha	他モジュールもalphaの使用が必要

利用可能なmanifest.jsonの最新バージョン [プレビュー版]

種類	バージョン	詳細
Stable	-	-
Beta	1.0.0-beta	BetaAPIの有効化が必要
Alpha	2.0.0-alpha	他モジュールもalphaの使用が必要

Document | npm

@minecraft/server-editor

Minecraft Editorでのエディターの操作を行えます。
Minecraft Editorでのみ使用可能な点に注意

manifest.jsonの詳細 (ベータ版)

manifest.json

{
    "module_name": "@minecraft/server-editor",
    "version": "0.1.0-beta"
}

NPMのバージョン

種類	バージョン
Stable	-
Beta	0.1.0-beta.1.21.43-stable
Preview Stable	-
Preview Beta	0.1.0-beta.1.21.50-preview.25

利用可能なmanifest.jsonの最新バージョン [安定版] (使用できるかは未確認)

種類	バージョン	詳細
Stable	-	-
Beta	0.1.0-beta	BetaAPIの有効化が必要
Alpha	2.0.0-alpha	他モジュールもalphaの使用が必要

利用可能なmanifest.jsonの最新バージョン [プレビュー版]

種類	バージョン	詳細
Stable	-	-
Beta	0.1.0-beta	BetaAPIの有効化が必要
Alpha	2.0.0-alpha	他モジュールもalphaの使用が必要

Document | npm

ScriptAPIの仕様

JavaScriptの仕様

ScriptAPIはJavaScriptで記述していますが、JavaScriptの中でもESModuleという形式が採用されています。
また、ScriptAPIでは標準のAPI、外部のAPIを含めAPIを使用することが出来ません。fsやchild_processがその例です。また、net、httpモジュールやfetch関数が使用できないため、必然的にWebAPIも使用不可となっています。

beforeEventsの仕様

以下のコードは、ブロックを壊したときに、ブロックを壊したプレイヤーにブロックのIDの名前でタグを付与するものです。

index.js

import { world } from "@minecraft/server";

world.beforeEvents.playerBreakBlock.subscribe((ev) => {
    const { player, block } = ev;
    
    player.addTag(block.typeId);
});

しかし、実際に実行してみると、以下の様なエラーが出てしまいます。

これは、beforeEventsの仕様によるものです。beforeEventsの処理の際に、ノーディレイで対象（プレイヤーやワールド、ディメンション等）に変化を与えるような関数を呼び出した際にこのエラーが発生してしまいます。

どのように解決すればいいかというと、system.runTimeout()などで処理に遅延を与えることで解決できます。上のコードの場合、下記のようにします。systemをimportしなければならないことに注意してください。

index.js

import { world, system } from "@minecraft/server";

world.beforeEvents.playerBreakBlock.subscribe((ev) => {
    const { player, block } = ev;
    
    system.runTimeout(() => {
        player.addTag(block.typeId);
    }, 0);
});

system.setTimeoutの第二引数は遅延するtick数で、0にすることでほぼノーディレイのままエラーが発生せずに実行できます。

Playerクラスの仕様

@minecraft/serverで扱うPlayerクラスはEntityクラスの継承で構成されています。そのため、エンティティでは使用できるが、プレイヤーでは使用できないメソッドが存在しています。

以下のメソッドはプレイヤーに対して使用できません。

<Player>.remove()
<Player>.clearVelocity()
<Player>.applyImpulse()

また、以下のメソッドは使用できるものの、プレイヤーに対して効果がありません。

<Player>.setRotation()

その他

他ファイルの参照

通常、コードが短ければ1つのファイルで済むことでしょう。ただ、コードが長くなってくる場合、複数のファイルに分けることは必須事項です。

複数のファイルを参照するときのよくある間違いに、manifest.jsonのmodulesのentryを増やせばいいと思う方がいらっしゃいます。ですが、それでは出来ません。ではどうするかというと、現在entryに設定しているファイルで他のファイルを参照する必要があります。

文章だけでは少しわかりづらいので、1からJavaScriptの他ファイルの読み込み、読み取りの方法を解説していきます。だた、ここではちょっとした例を出すに過ぎないので、詳しく知りたい方はこちらをご確認ください。

まず注意して欲しいのが、ファイルの読み込み、読み取りにはscriptsフォルダ内にファイルが存在している必要があります。

例えば、以下の様な階層は誤りです。

Sample
┣ scripts
┃ ┗ index.js
┣ test.js
┣ manifest.json
┗ pack_icon.png

このような階層にする必要があります。

Sample
┣ scripts
┃ ┣ index.js
┃ ┗ test.js
┣ manifest.json
┗ pack_icon.png

注意点に留意して次に進みます。

このようなコードでtest.jsファイルを読み込むことができます。

index.js

import "./test.js";

./とは？と思った方、相対パスというパスの表現方法で、この場合同じ階層のtest.jsファイルを指定しています。詳しくは解説すると長くなってしまうので割愛します。

読み込みだけの場合はこれで十分ですが、他のファイルで関数や変数を用意して置き、読み取ることも出来ます。

以下の様なコードでファイルから読み取ることができます。

index.js

import { random } from "./random.js";

random.js

export function random(min, max) {
    return Math.floor(Math.random() * (max - min + 1)) + min;
}

読み取るには、読み取り側のファイルの関数、変数の始めにexportを記述する必要があることに注意してください。

eval関数の利用方法

eval関数は通常では使用できません。しかし、manifest.jsonで設定をすることによって使用することができます。

manifest.jsonに以下の要素を付け足すことにより可能です。
"capabilities": [ "script_eval" ]

実際に付け足した例です。

manifest.json

{
    "format_version": 2,
    "header": {
        "name": "Test",
        "description": "ScriptAPI Test Behavior Pack",
        "uuid": "<UUID>",
        "version": [ 1, 0, 0 ],
        "min_engine_version": [ 1, 21, 0 ]
    },
    "modules": [
        {
            "description": " ",
            "type": "script",
            "entry": "scripts/index.js",
            "uuid": "<UUID>",
            "version": [ 1, 0, 0 ]
        }
    ],
    "dependencies": [
        {
            "module_name": "@minecraft/server",
            "version": "1.13.0"
        }
    ],
    "capabilities": [
        "script_eval"
    ]
}

最後に

今回は、ScriptAPIについての情報を纏めてみました。恐らくですが、情報を全て網羅しているわけでは無いので、本記事に載っていない情報を見かけた、若しくは知っているよという方は、是非コメント等で情報共有をして頂けると助かります。
今後もより良い記事を製作していくよう努めていくつもりですので、よろしくお願いします。