連載 アドオン制作入門 第5回
⑤Script API を有効にして、動く処理を書く
ビヘイビアパックに script モジュールを追加して、最小限の Script API を動かすところまでをやります。
ここまでの4本は JSON を書くだけの「静的な」アドオンでした。今回からは Script API を使って、実際にコードで処理を書く「動く」アドオンに進みます。基礎編としては今回が最後です。
実験的機能は要る?
今の Script API は、安定版のバージョンを使う限り「実験的機能」をオンにしなくても動きます。この記事の内容は安定版だけで完結するので、ワールドの設定は普段のままで大丈夫です。
オンにする必要があるのは、@minecraft/server のバージョンに -beta が付いた、まだ実験中の機能を使う時だけです。その場合はワールド作成・編集画面の「実験的機能」で「ベータ API」をオンにします。オンにしていないと、パックごと読み込みに失敗します。
manifest.json に script モジュールを足す
第2回で作った manifest.json の modules に、script 用のモジュールを追加します。
{
"format_version": 2,
"header": {
"name": "Aoki First Addon",
"description": "スクリプトを動かす",
"uuid": "ここにUUID",
"version": [1, 0, 0],
"min_engine_version": [1, 21, 120]
},
"modules": [
{
"type": "data",
"uuid": "ここにUUID",
"version": [1, 0, 0]
},
{
"type": "script",
"language": "javascript",
"uuid": "ここにUUID",
"entry": "scripts/main.js",
"version": [1, 0, 0]
}
],
"dependencies": [
{
"module_name": "@minecraft/server",
"version": "2.6.0"
}
]
}
type: "script"のモジュールが、コードを動かすための入り口ですentryに書いたパスの JS ファイルが最初に実行されますdependenciesで@minecraft/serverを指定します。2.6.0は自分の配布中のアドオンで使っているバージョンです。新しい Minecraft では使えるバージョンが上がっていくので、書く時点の公式ドキュメントで確認して入れてください
最初のスクリプトを書く
scripts/main.js を作ります。
import { world } from '@minecraft/server';
world.afterEvents.playerSpawn.subscribe((event) => {
if (!event.initialSpawn) return;
world.sendMessage(`${event.player.name} が参加しました`);
});
world.afterEvents.playerSpawn— プレイヤーがワールドに出現した時に呼ばれるイベントevent.initialSpawn— リスポーンと区別するためのフラグ。最初の参加時だけtrueになります
before と after の違い
イベントには afterEvents(起きた後に呼ばれる)と beforeEvents(起きる直前に呼ばれる)の2種類があります。beforeEvents の中は「読み取り専用」で、ワールドを書き換える処理(メッセージ送信、アイテムを渡す、など)を直接書くとエラーになります。その場合は system.run で1テンポ遅らせて実行します。
import { world, system } from '@minecraft/server';
world.beforeEvents.chatSend.subscribe((event) => {
// ここで直接 sendMessage するとエラーになる
system.run(() => {
world.sendMessage('チャットを受け取りました');
});
});
今回の playerSpawn は afterEvents なので、system.run なしでそのまま書けます。
動作確認
パックをワールドに適用して入り直すと、チャット欄に参加メッセージが出るはずです。
コードを直した時は、ワールドに入ったまま /reload を実行するとスクリプトが読み込み直されます(チートの許可が必要です)。テクスチャや JSON の変更は /reload では反映されないことがあるので、その時はワールドから出て入り直します。
つまずきやすい所
dependenciesのバージョンが実際に使えるものとずれている — パックの読み込みに失敗します。エラーメッセージが出ないこともあるので、まずここを疑うと早いです-betaのバージョンを指定したのに「ベータ API」をオンにしていない — これもパックごと読み込まれませんentryのパスとファイルの実際の場所が違う — こちらも静かに失敗するので気づきにくいですbeforeEventsの中でワールドを書き換えてエラーになる —system.runで1テンポ遅らせると解消します
まとめ
manifest.jsonにtype: "script"のモジュールとdependenciesを追加すると Script API が使えるようになる- 安定版の API なら実験的機能は不要。
dependenciesのバージョン一致がハマりやすいポイント beforeEventsの中でワールドを書き換える時はsystem.runを挟む ここまでで、環境構築からアイテム追加、簡単なスクリプトまで一通り触りました。次からは実際に配布している聖遺物アドオンの中身を、もう少し実践的な題材として掘り下げていきます。