マクロ

投稿日:2015年9月22日 | 最終更新日:2026年1月26日

マクロは、「ある程度似たような処理を一まとめにする」ための仕組みです。
宴のマクロは、全て「Macro」という名前のシート内に記述する必要があります。

マクロの基本的な書き方

サンプル

Macroシート内に記述します。（Macroという名前のシートがなければ作成します）
マクロの開始はシナリオラベルと同様に、Command列に「*マクロ名」としてください。
マクロの終了は、Command列に「EndMacro」としてください。

マクロシート内のマクロ定義

マクロの呼び出し

呼び出すのは、どのシナリオシートからでも行えます。
Command列に、「マクロ名」を記述してください。
「複数のコマンドを組み合わせた新しいコマンドを作る」というのがマクロの使いかたの基本的なイメージ

サンプル

マクロで引数を使う

引数つき

%Arg1のように、%列名 とした部分は、マクロ呼び出しの引数として使えます。

マクロの書き方

マクロの呼び出し

このサンプルでは
・Arg1を切り替える背景の名前
・Arg2をフェードの色
・Arg3をフェードアウト時間
・Arg4をフェード後の待機時間
・Arg5をフェードインの時間
のマクロになります。

%マクロ引数を記述しない部分は、通常のコマンドの書式で入力可能ですので、直接0.2やblackなどの値を記述してもかまいません。

デフォルト引数

マクロの引数にデフォルト引数を設定することもできます。
デフォルト引数の設定は、マクロ名の列にそれぞれ数値を記述します。
デフォルト引数が設定してあると、マクロを呼び出すときに引数が空欄だとその値が使われるようになります。

マクロの書き方

マクロの呼び出し

このサンプルでは
・Arg1を切り替える背景の名前
・Arg2をフェードの色（デフォルトはblack）
・Arg3をフェードアウト時間（デフォルトは0.2）
・Arg4をフェード後の待機時間（デフォルトは1）
・Arg5をフェードインの時間（デフォルトは0.2）
のマクロになります。

引数をパラメーターに

マクロの引数は、Paramコマンドの変数としても使えます。

マクロの書き方

マクロの呼び出し

マクロ引数マークの%と、剰余演算子の%は併用できますが、()などで囲うのを推奨します。
また、マクロ引数には型がないので、内部的にはそのままマクロ内コマンドの文字として扱われます。
これを利用すれば、パラメーター名を手軽に表示できます。

引数をパラメーターテーブルに

パラメーターテーブルの場合は、
「テーブル名、キー、パラメーター名」のそれぞれの要素に、引数を割り当てることができます。

マクロの書き方

マクロの呼び出し

エンティティ（マクロ内で、パラメーターを各コマンドの引数に使う）

これは、パラメーターに設定した文字列や数字を各コマンドの引数に設定する特殊な使い方です。
表示キャラクターが動的に変更されうる場合で、自動分岐で処理するには複雑すぎるケースなどに使います。

エンティティの記述の仕方

マクロ内で&パラメーター名 とします。

たとえば、これはパラメーター名「entity_name」に設定されたキャラクターを表示するマクロです。

エンティティとマクロの引数の違い

マクロの引数はあくまでシナリオ内に「固定的な数値や文字で引数を設定する」必要があります。
それに対して、エンティティの場合は、パラメーターの操作したいで「動的に変化しうる数値や文字が設定できる」という点で大きく違います。

エンティティの注意点

まず、マクロ内のみで有効です。
通常のコマンドには使えないようにしてありますので注意してください。
エンティティはパラメーターの演算でシナリオを変えられるので、便利ではあるのですがリスクもあります。

エラーチェックができない

宴のシナリオインポート時のチェックが通用しなくなるため、動作が不安定になるリスクがあります。
たとえば、数字ではないパラメーターを数字のコマンド引数に使っている場合など、不正な値の場合はランタイムエラーとなってしまいます。
つまり、パラメーターに設定する値しだいでエラーになる可能性があるということです。
また、インポート時にはパラメーター名の初期値でエラーチェックをするため、エンティティに使うパラメーターの初期値は不正な値にならないようにしてください。

使えないケースがある

エンティテイが適用されるのはコマンド実行時のみになります。
PageCtrlのように、コマンド実行前に情報が必要になる部分では使用してもまともに動作しません。

Text表示は不安定

Textにエンティティを使ってパラメーターの内容を表示しようとすると制御が難しくなります。
基本的にはparamタグを使ってください。

トラブルケースその1
&Parameter本文とすると、
「Parameter」という名前のパラメーターと、「本文」というテキスト
ではなく
「Parameter本文」という名前のパラメーターだと解釈して表示しようとしてしまいます。

トラブルケースその2
Param=”Hoge”で、ParamTbl=”Tbl”と設定されている場合
＆Parameter　は「Hoge」というテキストになり、
＆ParamTbl[0].name　は「Tbl[0].name」というテキストになってしまいます。
「Tbl[0].name」の中身のテキストを拾ってくるには、さらにもう一段階エンティティを解析可能な構文が必要になるのですが、それは対応していません。

動作が重くなる可能性がある

ほとんどのケースであまり問題ならないと思いますが、
エンティティは複雑なテキスト解析をゲーム実行中に行う必要があるため、場合によって動作が重くなる可能性があります。

マクロの注意点

イメージとしては「複数のコマンドを組み合わせた新しいコマンドを作る」イメージに近いです。
サブルーチンと違って、引数を持たせて変化をつけられるのが長所です。

サブルーチンが「処理を呼び出す」のに対し、マクロは「あらかじめコマンドを埋め込む」仕組みになっています。
そのため既読ページ判定なども個別に判定されますが、マクロ内でシナリオラベルを記述すると、あちことに同じシナリオラベルが存在することになり不具合を起こします。

Tweenコマンドの簡略化

マクロを使うと、Tweenコマンドが扱いやすくなります。詳細

構造化マクロ（難易度高）

宴4.2.6から、構造化マクロ機能を追加しました。

基本的には宴の書式は、1セルに1要素を記述するという形になっています。
（例外としてはTweenコマンドで、必要な要素数が多いため1セルに複数の要素を記述可能にしています）
そのため、標準で必要になるセル数（列数）が多かったり、どの引数がどの意味をもっているか把握しづらいという欠点もあります。
構造化マクロを使用するとTweenコマンドのように1つのセルに複数の要素を記述可能にすることができます。

要素の名前も記述する形になるのでhtmlやxmlのようなメタ言語やプログラム的な記述に近い書き方ができます。
宴のコマンド書式自体を変えるレベルの高度なマクロを作りたいなど挑戦的なケースで使用してください。
ただし、これは難易度は高く、イレギュラーで独自性の高い書き方になるので、無理に使用する必要はありません。

構造化マクロのセットアップ

使用するには、通常状態では使用できないので、追加設定が必要です。
1.マクロ解析用のScriptableObjectを作成
Projectウィンドウで、Create > Utage > Scenario > StructuredMacroParser から作成してください。
作成されたScriptableObjectはこのようになります。

2.現在のプロジェクトに適用
現在のプロジェクトのCustomProjectSettingsを選択してください（通常は、宴プロジェクト名/ScriptableObjectフォルダ以下にあります）
作成したScriptableObjectに、「Structured Macro Parser」という項目が追加されているので、先ほど作成した ScriptableObject を 設定してください。

構造化マクロの定義

マクロ内で、下記のように「%引数列名.プロパティ名」という使い方ができるようになります。

マクロサンプル

サンプルでは、Args列を使用する形になっていますが、任意の列名を使ってもよいです。
既存の列名を使ってもいいですし、追加してもよいです。
ただし、その列名全体がほかの列名の先頭文字列と重複しないようしてください。
たとえば「Arg」という名前の列名を追加すると、ArgはArg1の先頭文字列と重複してしまうので、追加するならArgsのように重複を避けてください。

また通常のマクロのデフォルト引数の項目（マクロ名の行のArgs行）に、使用するすべてのプロパティ名とデフォルト引数の値を設定してください。

区切り文字

・プロパティ名と値の区切り文字は　=（イコール）
・複数あった場合の区切り文字は　,（カンマ）
となっています。
これはScriptableObjectのほうで変更可能です。
デフォルト引数が未設定の場合は空文字扱いになります。
ここに設定されていないプロパティ名は使用しようとするとエラーになります（スペスミス防止）

構造化マクロの使用

シナリオ上では次のようにして、マクロとして呼び出せます。

引数として渡す値の中に＝が入っていても一応動作します。
見た目が紛らわしいようであれば、ScriptableObjectの「Key Value Separator」の項目を　=（イコール）ではなく　:(コロン)　などに変更してみてください。
Tweenコマンドのように、すでに1セル内に複数項目を設定する前提になっているコマンドは、上記のparamsのように（途中の＝を含めて）まとめて引数として渡す形になります。
（マクロを工夫すれば細かい分割も可能ではあると思いますが、限界はあると思います）

構造化マクロの注意点

問題が予想されるのは、引数として渡す値の中に　,（カンマ）　が必要なパターンです。
,（カンマ）になった時点で値ではないものとしてデータが区切られてしまうので意図しない結果になると思います。
これが問題になるようであれば、ScriptableObjectの「Pair Separator」の項目を ,（カンマ） ではなく　;（セミコロン）などに変更してみてください。
（今度はセミコロンが必要なときに問題が起きるかもしれませんが、完全に避けるためにエスケープ文字解析などをいれるといよいよ難しくなってしまうので、やってないです）