メインコンテンツまでスキップ

シナリオファイル

シナリオファイルについて説明します。

ヒント

シナリオやシナリオファイルの概念が初めての方は, 先にこちらを参照して理解しておくことを推奨します。
また, 慣れている方でも以下のシナリオファイルを記述する際の注意を読んでおことをおすすめします。

概要​

シナリオファイルは, .yml もしくは .yaml の拡張子を持つ YAML ファイルで, シナリオを記述します。 プラグインの .jar に同梱されるのであれば, プロジェクトの任意の場所に配置できます。
１つのシナリオまたはテストにつき１つのシナリオファイルが必要です。
そのため, シナリオファイルを配置するディレクトリは構造的に管理すると良いでしょう。

シナリオファイルの構造​

シナリオファイルは, 最上位に ScenarioFile 型のオブジェクトを持ちます。
このオブジェクトは, シナリオファイルのメタデータやトリガ, シナリオなど, テストに関するすべての情報を保持します。

Scenamatica のすべてのオブジェクトは自動生成されたリファレンスが提供されています。
詳しくはこちらを参照してください。

シナリオファイルの例​

以下のファイルは最小構成のシナリオファイルの例です。
これらの値は必須です。

# メタデータ
scenamatica: "0.8.0"  # Scenamatica のバージョン
name: "test-hoge-success"  # シナリオの名前
description: "hoge 機能の正常系テスト"  # シナリオの説明

on:  # トリガ（１つ以上のアイテムが必要）
- type: on_load  # トリガ：プラグインのスタートアップ時に実行

scenario:  # シナリオ
  # Actor1 が /hoge を実行する。
- type: execute
  action: command_dispatch
  with:
    command: "/hoge"
    sender: Actor1

また, 以下のファイルは完全なシナリオファイルの例です。
シナリオファイルの要素と Scenamatica の機能の対応を理解するために参考にしてください。

完全なシナリオファイルの例
# メタデータ
scenamatica: "0.8.0"
name: "test-hoge-success"
description: "hoge 機能の正常系テスト"

runif:  # 実行条件：hoge-milestone を達成している場合に実行する
  action: milestone
  with:
    name: hoge-milestone

context:  # コンテキスト
  actors:  # コンテキスト：アクタ
  - name: Actor1
    permissions:
    - "hogeplugin.commands.hoge"
  stage:  # コンテキスト：ステージ
    env: NETHER
    seed: 114514

on:  # トリガ
- type: on_load  # トリガ：プラグインのスタートアップ時に実行
- type: manual_dispatch  # トリガ：Scenamatica のコマンドで実行
  # このトリガが発火した時, メイン・シナリオの実行前に実行されるシナリオを指定する
  before:
  - type: execute
    action: milestone
    with:
      name: hoge-milestone
  #          〃        , メイン・シナリオの実行後に実行されるシナリオを指定する
  after:
  - type: execute
    action: milestone
    with:
      name: fuga-milestone
  

scenario:  # シナリオ
  # Actor1 が /hoge を実行する。
- type: execute
  action: command_dispatch
  with:
    command: "/hoge"
    sender: Actor1
  timeout: 20 # タイムアウト：20 tick
  # fuga というメッセージが（Actor1 に）表示される。
- type: expect
  action: message
  with:
    content: "fuga"
    recipient: "${scenario.scenario.0.sender}"  # 変数：前のアクションの実行者を指定
  # Actor1 が死亡する。
- type: expect
  action: player_death
  with:
    target: "${scenario.scenario.0.sender}"  # 変数：前のアクションの実行者を指定

その他のシナリオファイルの例については, こちらを参照してください。

✨ Scenamatica では自己テストをしています！✨

Scenamatica は, Scenamatica 自体のデバッグとデグレードの監視に使用されます。
ソースコードを GitHub にプッシュすると, CI によって自動的に Scenamatica のテストが実行されます。

シナリオファイルを記述する際の注意​

ファイルの命名​

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

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

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

ヒント

名前等の識別子のフォーマットは統一することが重要でありますので, Scenamatica が推奨するフォーマットに従わなくても問題はありません。

Scenamatica が採用している YAML のキーの命名規則​

Scenamatica のシナリオファイルにおける YAML のキーは, 原則として以下の命名規則に従い定義されます。

  • camelCase で記述します。
  • Minecraft 固有の単語は区切らずに記述します。
    例： gameMode => gamemode, mineCraft => minecraft など
警告

アクションの ID は, 例外的に snake_case で定義されます。

  • ❌ action: setBlock
  • ✅ action: set_block

列挙値におけるシンタックスシュガー​

一部のアクションの引数には, Minecraft/Bukkit 固有の列挙値（例： GameMode, Material など）を取るものがあります。
Scenamatica では, これらのシンタックスシュガーのために, 列挙値の名前の大小文字を無視します。

例：

  • gamemode: survival は gamemode: SURVIVAL と同じ意味です。
  • material: sToNe は material: STONE と同じ意味です。

プレイヤの指定におけるシンタックスシュガー​

一部のアクションの引数には, プレイヤ（の名前）を引数として指定できます。
こちらも上記と同じく, プレイヤの名前の大小文字を無視します。

例（サーバに Player1(00000000-1111-2222-3333-444444444444) というプレイヤが参加している場合）：

  • player: player1 は player: Player1 と同じ意味です。
  • player: 00000000-1111-2222-3333-444444444444 は内部的に player: Player1 と同じ意味です。
ヒント

これはプレイヤ・エンティティ指定子機能によるものです。

詳しくは以下のドキュメントを参照してください：

定義と参照の利用​

同じ YAML 内で任意の値を, 「定義」として記述し, 任意の場所から参照できます。 複数回使用する値を定義しておき, 参照することで, シナリオファイルの冗長性を減らして可読性と保守性を向上させます。

詳しくは以下のドキュメントを参照してください：