マクロ

マクロとは

CS2のシーンスクリプトでは「マクロ」を使用することができます。
マクロとは、1行以上のコマンド・コマンド群を任意に登録し、呼び出すことができる機能です。

何度も繰り返し使用するコマンドを簡単に使ったり、コマンド名やパラメータ指定を分かやすい形にするなど、応用方法はいろいろあります。
また、複数人数でのスクリプト作業における意思統一を図るうえでも、非常に有用です。

マクロファイル

マクロを使用するためには、[game]-[scene]フォルダに「&macro.txt」というマクロファイルを用意します。
このファイルにコマンドマクロを記述しておくことで、コンパイル時、シーンスクリプト側の対応部分にコマンド群が展開されます。

ファイル名の「&macro.txt」は固定なので変更しないでください

初期化マクロ

通常、表示位置などのデフォルト値はVRAM定義ファイルで設定します。
しかし中には、kcsで設定されていて直接変更できないものがあります。
もしそれがシーンスクリプトコマンドで変更できる内容であれば、「初期化マクロ」として定義しておくと便利です。

例として、rdrawやrwipeのデフォルト動作フレーム値を変更するdrawdefwipedefなどがあります。
こういったシステム操作系コマンドとパラメータ無指定による初期化を併用し、マクロ化しておくことで、作業者全員が同じ環境で作業することが可能になります。

マクロ定義

マクロファイルにマクロ名とコマンドを記述することで定義できます。

マクロ名は「%」から始まる名前で、コマンドはシーンスクリプトと同じです。
シーンファイル同様、コマンド群の途中やマクロ同士の間には空白行やコメントを挟めます。

1.マクロの記述と展開

マクロ名を行頭から記述し、その下に、その名前で定義するシーンスクリプトコマンドを続けます。

例1:cg 0を30フレームで左に100px動かし、その後元の位置に戻すマクロ

%LR
	cg 0 move 30 @-100 @
	wait
	cg 0 move 30 @+100 @
//他にも定義する場合は、これ以下にマクロ名・コマンドを続ける

行頭にマクロ名があると、次のマクロ名の行までが一つのマクロブロックとして認識されます。
(個々のファイルが作成されたりはしませんが、シーンスクリプトのラベルと同様の感覚です)。

定義したマクロは、シーンファイル側で通常のコマンドのように使用できます。

例2:シーンファイルから例1のマクロを呼び出し

	cg 0 ba01,1,1,1,1,1
	wait
	%LR

「%LR」が例1で定義したコマンドに置換され、以下のように記述したのと同じことになります。

	cg 0 ba01,1,1,1,1,1
	wait
	cg 0 move 30 @-100 @
	wait
	cg 0 move 30 @+100 @

この置換はシーンファイルをcstファイルに変換する時点で行われます。
マクロファイルを書き換えたときは、マクロを呼び出しているシーンファイルをコンパイルしないと反映されません

注意

マクロの階層化
マクロ中、さらにマクロを呼び出すことはできません。
wait
定義したコマンド群の最後にwaitを置くかどうかで、マクロの使い方が変わります。
waitまで定義しておくと、シーンファイルで呼び出すだけで処理が完了します。
ただし、テキストの直前に使用した場合などは、処理を待ってからメッセージが表示されることになります。

2.パラメータ置換機能

「パラメータ置換機能」を使用すると、さらに汎用的なマクロが作成できます。
これは、シーンファイルで呼び出す際に、マクロ定義したコマンドの任意の部分をパラメータとして指定できるようになるものです。

マクロ定義の段階で、どの部分をシーンファイル側で指定できるようにするかを決定します。

以下は前述のマクロです。

例1:cg 0を30フレームで左に100px動かし、その後元の位置に戻すマクロ

%LR
	cg 0 move 30 @-100 @
	wait
	cg 0 move 30 @+100 @

このコマンドの一部を、シーンファイルで呼び出すときに指定できるようにしましょう。

指定可能とする部分を「[]」で囲み、その前に%数値を入れます。

例2:マクロファイルにパラメータ置換を追加

%LR
	cg %1[0] move %3[30] @-%2[100] @ //数値の意味は後述
	wait
	cg %1[0] move %3[30] @+%2[100] @

これでシーンファイルから各項目を指定できるようになりました。

「cg 1を60フレームで左に200px動かし、その後元の位置に戻す」と指定します。

例3:シーンファイルで指定

	cg 1 bb01,1,1,1,1,1
	wait

	%LR 1 200 60 //マクロ名以降はパラメータ

実行すると指定どおりに動きます。

マクロファイルに指定した数値

※ここからは説明のためにマクロ部分だけを抜き出します

シーンファイル側記述:

	%LR 1 200 60 //バンク 移動距離 フレーム

シーンファイルでの指定はこのような順番になっていました。

一方マクロファイル側では、%の後に以下のように数値を指定しました。。

マクロファイル側記述:

%LR
	cg %1[0] move %3[30] @-%2[100] @
	wait
	cg %1[0] move %3[30] @+%2[100] @

このように、マクロファイルで「%」と「[]」の間に指定した数値は、シーンファイルでのパラメータの位置(順番)になります。

書式

%[n]([param])

n
シーンファイルに記述するパラメータの位置(1〜9)
param
シーンファイルでの指定が省略された場合に適用されるデフォルト値(「[]」も必要)
置換は文字列扱いとなるので、数値だけでなくファイル名などにも利用できます。
バンクを置換可能にする場合の注意
・複数バンクを指定する場合は、「[]」の中にさらに「[]」とバンクを指定してください
・「バンクすべて(数値を省略)」とする場合は空欄にしてください

シーンファイルでマクロを呼び出してパラメータを指定する場合、通常のコマンドと同じく後に来るものから省略ができます。
「%1」から「%3」までを置換可能として定義していた場合、3番目だけを指定したい場合でも、1番目や2番目を省略してデフォルト値を適用することはできません。

よって、パラメータは、指定することが多くなるものから順番をつけるようにすると効率的です。
また、デフォルト値も、一番使う可能性が高いと思われる数値を入れるようにします。

マクロ定義での注意

マクロ定義のコマンド中に、剰余を求める演算子として「%」を使用する場合は注意が必要です。
置換指定と判断されるので、%の後ろに直接数値を記述しないでください。

演算としての記述は「#100 = 500 % 3」のように、セパレータを挿入することで正しく計算されます。

逆に、コマンドのパラメータとして使用したい場合にセパレータが入ると別パラメータと判断されてしまいます。

	cg 0 pos 500 % 3

上記の記述では、「500」「%」「3」、それぞれがパラメータと判断されます。
こういった場合は変数を使うなどして回避する必要があります。

	#100 = 3
	cg 0 pos 500%#100

マクロファイルの分割

マクロを記述するテキストファイルは、&macro.txt以外にも複数作成できます。
マクロの内容で分けて分かりやすいファイル名にしておくと、マクロの使用時や追加・修正時に便利です。
※ファイル名も自由です

分割したファイルを作成したら[scene]フォルダに置き、以下の記述で&macro.txtかシーンファイルから呼び出します

#include [filename]

filename
呼び出すファイル名(拡張子「.txt」も必要)

&macro.txtから呼び出す

&macro.txtの先頭行に、行頭から記述してください。

例:

#include ¯o_char.txt //行頭にスペースやタブを入れない
#include ¯o_pl.txt
#include ¯o_begin.txt

//以下、マクロファイル内の登録マクロ
%def
	bg
	cg
	fg
	eg
	fw
	pl

マクロファイル(&macro.txt)内に記述することで、指定ファイルを読み込み、マクロ定義の一部として使用できます。

シーンファイルから呼び出す

こちらも先頭行・行頭から記述します。
ラベル行よりも上になることに注意してください。

例:

#include ¯o_00.txt

//以下、通常のシーンスクリプト
#01_01

スクリプト作業者ごとに異なるマクロファイルを作成し使い分けることが可能です。
この場合は&macro.txtも必須ではありません。