最初のシナリオを書いてみる

あなたの最初のシナリオを書いてみましょう。

---

注意事項

この項目では, 最も基本的なシナリオを書く方法について説明しています。
ここにない高度な機能についての説明や, その他の完全な構文についてはこちらを参照してください。

ステップ０. シナリオの概念について理解する

Scenamatica は, シナリオと呼ばれるファイルを使用して, プラグインの動作をテストします。
シナリオとは, 簡単に言うと, プラグインの正しい動きとその発火方法をまとめたもの, そしてそれを記述したファイルのことです。

参考：以下は, シナリオのかんたんな概要を示した図です。

このチュートリアルでは, シナリオの基本的な構成要素についてのみ触れています。シナリオについて詳しく知りたい方はこちらを参照してください。

📄️ シナリオ

シナリオの概念とその概要について説明しています。

ステップ１. ファイルを作成する

まずは, シナリオファイルと呼ばれる YAML ファイルを作成する方法を学びましょう。
シナリオファイルとは, 前述のシナリオを記述したファイルのことです。 シナリオ一つごとに, 一つのシナリオファイルが必要です。

はじめに, 拡張子が .yml もしくは .yaml のファイルを作成します。 プラグインの最終的な .jar ファイルに配置されるのであれば場所は, どこでも構いません。

この例では, test-hoge-success.yml というファイル名を使用します。

ファイル名のフォーマットについて

ファイル名は, 特に技術的な制約等はありませんが, Scenamatica では以下のフォーマットを推奨しています。

• ASCII の小文字のみ
• ケバブケース（単語をハイフンで結合します）
• 推奨フォーマット： test-<機能名>-<success|failure-with-[失敗内容]>.yml
  先頭を test-<機能名> とすることで, 特定の機能のテストであるということが分かりやすくなります。
  また, 正常に成功することを確認するテストの場合は success-<機能名>,
  異常入力等で失敗することを確認するテストの場合は failure-<機能名>-with-<失敗理由> とすると良いでしょう。

例： test-hoge-success.yml , test-hoge-failure-with-no-argument.yml

ステップ２. Scenamatica のバージョンを記述する

シナリオファイルの先頭には, バージョン scenamatica を必ず記述します。

これは, シナリオが対応している Scenamatica のバージョンを明確に記述することで, 誤った（互換性のない） Scenamatica で実行することを防ぐことが目的です。

プラグインのデバッグ用のサーバに配置されている Scenamatica と同じバージョンを記述してください。

記述例：

scenamatica: "1.0.0"

警告

ここで記述したバージョンよりも古いバージョンの Scenamatica では, このシナリオは実行できません。
つまり, このシナリオは Scenamatica v1.0.0 未満のバージョンでは実行できません。

ステップ３. 名前と説明を記述する

シナリオファイルの次に, シナリオの名前と説明を記述します。

名前（name）は, シナリオの識別子として使用されます。プラグインの中で一意な命名をしてください。
説明（description）は, 人間が読みやすいような説明文を記述します。

記述例：

test-hoge-success.yml

scenamatica: "1.0.0"
name: "test-hoge-success"
description: "hoge 機能の正常系テスト"

警告

シナリオの名前は, 他のシナリオと重複しないようにしてください。
これは識別子として使用されるため, 一意である必要があります。

ステップ４. コンテキストを記述する

コンテキスト（context）には, シナリオを実行するワールド（ステージという）の環境や, シナリオに登場する擬似的なプレイヤ（アクタという）, 豚や牛などのモブ（エンティティという）などの, シナリオテストの実行に必要な前提環境を指定します。 これらはシナリオの実行前に生成され, 終了時に自動的に破棄されます。

今回のテストでは, /hoge コマンドの実行者としてアクタ Actor1 が存在することを想定しているので, 以下のように記述します。
また, ネザーで実行するようにもしてみましょう。

test-hoge-success.yml

scenamatica: "0.0.1"
name: "test-hoge-success"
description: "hoge 機能の正常系テスト"

context:
  actors:
  - name: Actor1
  # ステージには, シナリオを実行するワールドの情報を指定します。
  stage:
    env: NETHER

ヒント

コンテキストについて詳しく知りたい方はこちらを参照してください。

📄️ コンテキスト

Scenamatica のシナリオを構成する要素について説明しています。

ステップ５. トリガを記述する

各シナリオは, 発火されるためのトリガが必要です。
例えば, 「プラグインが有効されたときにシナリオを実行するトリガ」（on_load）などが該当します。

トリガは, onというキーでオブジェクトのリストで記述します。

今回は手動実行のみを想定しているので, 手動実行（manual_dispatch）というトリガを設定します。

test-hoge-success.yml

scenamatica: "0.0.1"
name: "test-hoge-success"
description: "hoge 機能の正常系テスト"

context:
  actors:
  - name: Actor1
  stage:
    env: NETHER

# トリガを設定する
on:
- type: manual_dispatch

ヒント

今回は上記のトリガのみを実装しましたが, ほかにもいろいろなトリガがあります。

詳しくはこちらを参照してください。

ステップ６. シナリオを記述する

次に, 実際にシナリオを記述します。

プラグインの機能と, それらを発火させるために必要な条件とをおおまかに考えて, シナリオ化することが重要です。
例として, 今回のプラグインの機能について考えてみましょう。以下に例を示します：

• 機能ABの発火条件：コマンド /hoge が発行される。

• 機能A：fuga というメッセージが 実行者 に表示される。
• 機能B：実行者 がキルされる。

アクションの概念

Scenamatica では, 上記のような振る舞いや動作を, 「アクション」と定義しています。
アクションとは, 「プレイヤが死亡する」や「プレイヤがメッセージを送信する」などの, ゲームにおける具体的な動作のことです。 これらは Scenamatica によってあらかじめ定義されたもので, プラグインの機能を最小単位に分解したものです。

たくさん用意されているこれらを, 積み木のように組み合わせてシナリオを記述します。
この例では, それぞれ以下のアクションを使用すると実現できそうです：

項目名	アクション	引数
機能ABの発火条件	コマンドの発行	実行者: Actor1, コマンド: /hoge
機能A	プレイヤのメッセージの受信	ターゲット: Actor1, メッセージ: fuga
機能B	プレイヤの死亡	ターゲット: Actor1

ところで, 上記の表にある「機能A」や「機能B」は, プラグインが実行すべき動作（＝実行されることを期待する動作）です。
一方で「機能ABの発火条件」は, Scenamatica が実行すべき動作（＝プラグイン機能の契機となる動作）です。
つまり,「機能A」と「機能B」については, Scenamatica は何も行わず, ただそれが発生することを検証するだけです。

Scenamatica では, これらをそれぞれ「アクション実行タイプ」（expect）と「アクション実行期待タイプ」（execute）として分けて考えます。 前者は, 動作を Scenamatica が発生させます。後者は, プラグインによる動作を（Scenamaticaが）検知するか, 検知するまで待機します。

（参考：フローの図）

アクションの三様

前述の機能を達成するために, それぞれのアクションは, 最大で３つの異なる振る舞いを持ちます。 これらは, 同時に記述されるシナリオタイプによって制御されます。 例えば, アクション プレイヤの死亡は以下のように振る舞います：

シナリオタイプ	アクション プレイヤの死亡のふるまい
アクション実行(execute)	プレイヤをキルする
アクション実行期待(expect)	プレイヤがキルされるまで待機する（検知する）
条件要求(require)	プレイヤが（もう既に）死亡していることを要求する

シナリオの記述例

以上を踏まえ, シナリオを記述すると以下のようになります。

test-hoge-success.yml

scenamatica: "0.0.1"
name: "test-hoge-success"
description: "hoge 機能の正常系テスト"

context:
  actors:
  - name: Actor1
  stage:
    env: NETHER

on:
- type: manual_dispatch

scenario:
  # Actor1 が /hoge を実行する。
- type: execute
  action: command_dispatch
  with:
    command: "/hoge"
    sender: Actor1
  # fuga というメッセージが（Actor1 に）表示されることを期待する。
- type: expect
  action: message
  with:
    content: "fuga"
    recipient: Actor1
  # Actor1 がキルされることを期待する。
- type: expect
  action: player_death
  with:
    target: Actor1

ステップ７. シナリオを実行する

シナリオが記述できたら, 実行してみましょう。

今回の例では手動実行のトリガを追加していますから, コマンド /scenamatica run <プラグイン名> test-hoge-success を実行します。

警告

シナリオを手動実行に対応させるためには, on に manual_dispatch が含まれている必要があります。

その他のトリガに関しては, こちらを参照してください。

ステップ８. 糸冬 了

以上で基本的なチュートリアルは終了です。お疲れ様でした。

他の応用的なチュートリアルを読むにはこちらを参照してください。
シナリオファイルの完全な構文についてはこちらを参照してください。
CI/CD で Scenamatica を使用する方法についてはこちらを参照してください。