Macro


マクロは、「ある程度似たような処理を一まとめにする」ための仕組みです。
宴のマクロは、全て「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本文」というパラメーターだと解釈して表示しようとして、パラメータがない場合はそのまま「Parameter本文」と表示してしまいます。

トラブルケースその2

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

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

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

マクロの注意点

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

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

サブルーチンとの組み合わせ

Tweenコマンドの簡略化

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