アドオン制作

連載 アドオン制作入門 第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 を挟む ここまでで、環境構築からアイテム追加、簡単なスクリプトまで一通り触りました。次からは実際に配布している聖遺物アドオンの中身を、もう少し実践的な題材として掘り下げていきます。