タグについて

概要

テキスト情報はlibmsのLMS_GetTextというAPIを利用すると取得することが可能ですが、取得されたテキストデータの一部には「タグ」が入っています。

「タグ」とは、文章中に埋め込む制御命令のことです。たとえば、特定の範囲にルビをつけたり、主人公の名前を埋め込んだり、ウィンドウに表示する際に一定時間ウェイトをかけさせたりすることができます。 Message Studioでは、これらのタグを編集者が入力することができるようになっています。詳細は、タグの概要についての項を参照してください。

出力される標準バイナリリソースでは、テキスト情報の中に特定のフォーマットでタグがバイナリ化されたものが出力されます。このタグ情報をどのように表示したりするかはゲーム側の実装に任せられています。

「システムタグ」と「ユーザー定義タグ」はどちらもバイナリ化されて出力されます。したがって、どちらも適切にハンドリングして処理する必要があります。「システムタグ」であってもMessage Studioがゲーム側のレンダリングまで受け持つわけではなく、独自に実装する必要がある点に注意してください。テキストの中のタグであるかどうかという情報は、 Nintendo Ware for Revolutionの中のTagProcessorクラスを使用すると比較的単純にハンドリングすることができます。

タグのバイナリフォーマット

タグに関する基本的なフォーマットについて

タグの入ったテキストは、以下のようなフォーマットになっています。

表中の、「STRING」の部分はユーザーが入力した文字列を示します。その途中にタグが入っていた場合、タグの情報が埋め込まれます。データの終端はNULL文字で終わります。ユーザーが入力した部分およびNULL文字は出力する際に指定されたエンコーディング形式でエンコードされます。

単独のタグ、及び範囲を持ったタグの開始の目印はSHIFT IN文字(U+000E)になって、これも指定されたエンコーディング形式で書き出されます。つまり、UTF-16のビッグエンディアンで出力される場合はタグ開始の目印は 00 0E になりますし、 UTF-32のリトルエンディアンの場合は 0E 00 00 00 と出力されることになります。

この文字の直後に、タグとして入力されたデータが一定量続きます。データのフォーマットはプロジェクトファイル(*.msproj)に登録されたタグのパラメータ設定に依存します。開始タグ全体のフォーマットは以下のようになります(これについては一部例外があります。詳しくは次の章で解説します)。

パラメータ設定によってどのように内容が変化するかは、ページ下部をご覧ください。

開始タグは上の図のように、SHIFT INで始まった直後に、タググループID、タグID、パラメータサイズ(バイト単位)と続きます。タググループIDは2バイトの情報で、プロジェクトファイルに定義した順番に自動的に番号が割り振られます。タグの定義される順番は、プロジェクトバイナリファイルを出力させて確認したり、C言語ヘッダファイルを出力させて取得させることが出来ます。パラメータサイズは、それに続くパラメータ部分のバイト数が入ります。次にテキストを表示させる位置へは、必ずこの値だけポインタを移動させてから描画を開始してください。

範囲を持ったタグの終端部分は、目印としてSHIFT OUT文字(U+000F)が出力されます。その後に、グループID、タグIDが各2バイトずつ出力され、全体は以下のようになります。

カラータグ

カラータグは、範囲を持つタグとしてMessage Studioに定義されています。色変更の開始位置と色変更の終了位置を指定することができます。しかし、このままではレンダリングする際に色用にスタックなどを用いてテキストを描画していく必要があるため、 Message Studioはバイナリ化する段階でカラータグの情報を平坦化します。平坦化された場合、終了タグのことを考慮することなく、現れた色に即座に切り替えてレンダリングすればよいことになります。

カラー情報は、メッセージバイナリ(*.msbt)の出力方法設定によって二種類の書き出し方が可能です。ひとつは、直接色の成分を出力する方法で、もうひとつはプロジェクト設定のインデックス番号を参照する方式です。設定を変更するためには、「プロジェクト」→「データの出力設定」メニューを選択し、「メッセージバイナリ」のアイテムを選択します。デフォルトの設定は、直接、色の成分を出力する方式になっています。

まず、色の成分を直接出力する方式について説明します。色の成分で出力する場合は、パラメータのところに4バイトの値が出力されます。値は下図のように、それぞれR(赤)、G(緑)、B(青)、A(アルファ)が1バイトずつ書き出されます。地の文(カラータグが適用されていない部分)については黒として書き出されます(今後、設定可能なように改善予定です)。

プロジェクト設定参照方式にて書き出す場合、パラメータは2バイトの値が出力されます。この部分には2バイトで、プロジェクトファイルにおけるカラー設定のインデックス番号が書き出されます。地の文(カラータグが適用されていない部分)については0xFFFFが出力されます。

フォントサイズ変更タグ

フォントのサイズ変更についても色と同様に範囲指定が可能ですが、平坦化して出力されます。サイズ情報はパーセント単位で出力されます(つまり、100が等倍の大きさです)。

ルビタグ

ルビタグを利用するとよみにくい漢字にひらがなを振ることができます。このタグも、特定の範囲の漢字に、指定されたパラメータのルビをつける、という形で表現されますが、特殊な形式で出力されます。

ルビタグは、タグフォーマットの中に後続の漢字の長さがバイト単位で格納されます。続いて、ルビ部分の長さがバイト単位で格納されます。ルビ部分はバイナリ出力時に指定されたエンコーディング形式で出力されます。

アライメントについて

テキストを描画する際、メモリのアライメントによっては描画処理を続行できなくなる場合があります。たとえば、Nintendo Ware for Revolutionの CharStrmReaderクラスは、2バイト境界からデータが始まらないとアサートに失敗します。これを回避するため、Message Studioではタグパラメータが境界にあっていない場合に自動的にパディングを挿入するように設計されています。パディングは以下のアルゴリズムに従って挿入されます。

指定されたエンコーディング形式でデータを出力した状態で、制御コードを出力した場合のバイト数を計算します。たとえばUTF-8なら1バイト、UTF-16なら2バイト、UTF-32なら4バイトとなります。
文字列型のパラメータを出力する場合、現在出力しているデータの位置が、先ほど計算したバイト数の倍数になっていない場合は、文字列のバイト数が入っている位置の前後にパディングを挿入します。
すべてのタグパラメータを出力した状態で、その位置が先ほど計算したバイト数の倍数でなければ、直後にパディングを挿入します。

なお、パディングはプログラマが気づきやすいように0xCDを書き込みます。

アライメントに関する例

以下のようなユーザータグを定義し、UTF-16で出力させると、

libms_u8_t

data1

のようになります。実際のパラメータサイズは1バイトですが、パディングが追加されることによってパラメータサイズ(PARAM SIZE)に値2が入っていることに注目してください。

u8の情報が2個続いた場合で、data1に2が、data2に4が入力され、UTF-16で出力されると、

libms_u8_t	data1
libms_u8_t	data2

のようになり、パディングは入りません。

パラメータについて

文字列型のパラメータ

LENには、後続?byteの文字列データのサイズが格納されます。 TEXTには、LENのサイズだけ文字データが格納されます。（出力設定で指定したエンコード）

リスト型のパラメータ

INDEXには、選択したリストアイテムのインデックスが格納されます。

その他のパラメータ

指定した型に従って、書き出されます。

パラメータのサンプル

[Sound:SE name="TEST_SOUND" volume="10" effect="BLINK" ]

上記のようなタグがあり、以下のように設定されていると仮定します。

Sound: システムグループから数えて3番目に定義されているタググループ
SE: グループ内で4番目に定義されているタグ
name: string型のパラメータ
volume: s32型のパラメータ
effect: リスト型のパラメータ

この状態で、エンコーディング形式をUTF16として出力すると、データは以下のような構成になります。