ゲームテストフレームワークの作成チュートリアル

ゲームテストフレームワークで基本的なプログラムを組む手順を解説します。

開発環境を整える

まずは次の記事から開発環境とテンプレートを使えるようにしておいてください。

manifest.jsonの設定

まずはmanifest.jsonを、今回のチュートリアルように書き換えましょう。

//で始まる行はコメントなので、実行時に無視されます。通常のJSON形式はコメントを書くとエラーになりますが、マインクラフトのアドオンではエラーにならないので、書いても構いません。(書かなくても良い)

manifest.json

{
  "format_version": 2,
  "header": {
    // アドオンの名前です。わかりやすい名前をつけましょう
    "name": "ゲームテストフレームワークのチュートリアル",
    // アドオンの説明です。
    "description": "チュートリアル用に作成したアドオン",
    // 固有のUUIDです。必ず変更してください。
    "uuid": "59d5861d-0abd-4d52-8e56-a41d981a8a01",
    // このアドオンのバージョン名です。公開しない場合は気にしなくて構いません。
    "version": [0, 0, 1],
    // マインクラフト本体の必須バージョンです。とりあえず現行のバージョン名を付けておけば問題ありません。
    "min_engine_version": [1, 19, 0]
  },
  "modules": [
    // ゲームテストフレームワークを使用する設定です
    {
      // 説明欄
      "description": "Use Game Test Framework",
      // 1.18と1.19で設定が異なります。これらは1.19以降の設定です。
      "language": "javascript",
      "type": "script",
      // UUIDです。ここも独自の値に変更してください。
      "uuid": "0a4bbea0-a6fa-44b8-a207-d41bf9e872d6",
      // モジュールのバージョン名です。上と同様に公開しないのであれば変更しなくて構いません。
      "version": [0, 0, 1],
      // 最初に実行されるファイル名です。
      "entry": "scripts/main.js"
    }
  ],
  // 依存する他のアドオン・パッケージです
  // これらはゲームテストフレームワークで使用するパッケージのことです。
  // この設定をしないとゲームテストフレームワークは使えないので、削除しないでください。
  // バージョン名は頻繁に変わるので注意してください
  "dependencies": [
    {
      "uuid": "6f4b6893-1bb6-42fd-b458-7fa3d0c89616",
      "version": "1.0.0-beta"
    },
    {
      "uuid": "2bd50a27-ab5f-4f40-a596-3641627c635e",
      "version": "1.0.0-beta"
    }
  ]
}

main.tsの内容を削除

次にscripts/main.tsを開いてください。内部にはサンプルのコードが書かれていますが、今回は最初から記述するので、中の記述はすべて削除してください。

scripts/の中には他のファイルもありますが、一旦無視してください。

例文を作る

プログラムは、「X」をしたときに「A」をする。というのが基本形です。

最初の例文として、「hiと入力したとき」に「helloとメッセージを返す」だけの簡単な所から作ってみましょう。

これをプログラミングしやすい流れに分解すると、次のようになります。

チャット欄からメッセージが送信されたとき
そのメッセージの内容がhiならば
helloの内容で、/sayコマンドを実行する

1. アドオン用のパッケージをインポートする

Minecraft本体と連携する部分は、Minecraft側が用意してくれている要素を使います。まずは、この要素を別パッケージからインポートします。

scripts/main.ts

import * as mc from 'mojang-minecraft';

これは、mojang-minecraftパッケージから、すべて(*)の要素をmcという名前でインポートするという意味です。

このmojang-minecraftパッケージの内容は、どこからきているのかというと、manifest.jsonでの次の記載によって、Minecraft本体が内部のパッケージを読み込んでいます。

{
  "uuid": "6f4b6893-1bb6-42fd-b458-7fa3d0c89616",
  "version": "1.0.0-beta"
},

開発環境上では、npmからインストールしたTypeScriptの定義ファイルによって、どのような要素がインポートされてくるかの型情報だけを見ることができます。（直接Minecraft本体から情報を取得しているわけではありません）

2. イベント関数を作成する

次は、そのプログラムで何をするかの関数を作成していきましょう。

今回の関数名はhelloにしておきます。引数名はeventです。ここの名前は自由に設定できます。どのような名前にしても良いですが、必ずわかりやすい名前にしてください。

scripts/main.ts

import * as mc from 'mojang-minecraft';

// 関数の枠組みを作成
function hello(event) {
}

3. 引数の型をインポートして設定する

イベント内容によって、引数eventにわたってくる値は変わります。どんな値かを指定するために、TypeScriptの記法で型を設定しましょう。イベントの方はmcの中にあるので、ドットで繋げて取得します。

今回はチャット送信時なのでChatEventに設定します。

scripts/main.ts

import * as mc from 'mojang-minecraft';

// 引数に型を付ける(TypeScirptの機能)
function hello(event: mc.ChatEvent) {
}

この型を設定することにより、event引数にどのような値が渡ってくるかをエディター上で確認できるようになります。また、間違った値を取得しようとするとエラーとして検出してくれます。

このようにTypeScriptを使って型を指定しなかった場合は、Minecraftで動かしてみるまでエラーが出ません。 (エラーで動かない上に、どこのエラーかもわかりません)

ChatEventの他に、どのようなイベントがあるかは公式ドキュメントから探す必要があります。ただ基本的に英語であり、プログラミングに慣れている人でないと、ドキュメントの使い方がわからないと思いますので、当サイトの記事も併せて参考にしてください。

4. 引数からメッセージを取得して判定

送信したメッセージはevent.messageで取得でき、これをif文で判定します。

scripts/main.ts

import * as mc from 'mojang-minecraft';

function hello(event: mc.ChatEvent) {
  // イベントからメッセージを取得し、if文で判定
  if (event.message === 'hi') {
  }
}

エディターが正しく設定されていれば、event.と入力した段階でmessageの候補が現れます。

5. 引数の情報からコマンドを実行する

今回の追加メッセージは/sayコマンドを使うことにします。コマンドはどの次元(dimension/オーバーワールド、ネザー、ジ・エンド)で使われているかの判定が必要ですが、今回は送信者から取得できる次元情報を使うことにします。（つまり送信者と同じ次元にする）

eventオブジェクトからメッセージの送信者であるsenderオブジェクトを取得
senderオブジェクトからその次元情報であるdimensionオブジェクトを取得
さらに、そのdimensionオブジェクトにあるrunCommand()メソッドを実行
引数としてコマンドの文字列を渡す

これらを1行で書くと次のようになります。

scripts/main.ts

import * as mc from 'mojang-minecraft';

function hello(event: ChatEvent) {
  if (event.message === 'hi') {
    // イベントの情報を元に、スラッシュコマンドを実行
    event.sender.dimension.runCommand('say hello');
  }
}

ゲームテストフレームワークでは、他にコマンドよりも効率の良い処理方法がありますが、ひとまずは使い慣れたコマンドを積極的に使っていってください。慣れてきたら、ひとつずつ専用の処理方法を覚えていきましょう。

6. この関数をイベントに登録する

最後に、この関数をMinecraftが認識できるようにイベントに登録します。

mcの中からworld情報を取得し、その中のevent情報を取得、さらにその中のbeforeChatイベントを取得します。

このイベントのsubscribe()メソッドにhello関数を渡して、イベントを登録します。

scripts/main.ts

import * as mc from 'mojang-minecraft';

function hello(event: ChatEvent) {
  if (event.message === 'hi') {
    event.sender.dimension.runCommand('say hello');
  }
}

// hello関数を「BeforeChat」イベントに登録(subscribe)する
mc.world.events.beforeChat.subscribe(hello)

デプロイして実行

完成したら、使用している開発テンプレートの操作に従って、デプロイしましょう。

Ctrl + Shift + @でVS Code上のターミナルを開き次のコマンドを実行しましょう。

gulp

アドオンを適用したワールドのチャット画面でhiと送信したときに、helloと返ってくれば成功です。