チュートリアル(プログラマ向け拡張編)

このページではプログラマに向けた拡張性について記述します。

TogakiMakerの基本概念やメインツールの操作は導入編のページに記述しています。
拡張を行う際にもメインツールの操作については変わりませんので、こちらを先にご覧ください。
http://doilworks.com/index.php/documents/tutorial-001/


Step01.TogakiMakerでは何ができるの?

TogakiMakerでは以下の拡張が容易にできるよう設計されています。

  • 再生機能を何種類でも追加できる
  • 特定のシナリオ再生機能が実行できるコマンドの追加削除
  • 特定のシナリオ再生機能が実行できるコマンドの挙動変更
  • ストーリーファイルのインポート機能を追加する
  • デコレーションコマンドごとにシリアライズ,デシリアライズの手段を変える
  • デコレーションコマンドごとにリソースの読み込み手段を変える

このページではそれぞれの項目について、実際に拡張を行いながら解説します。
順番に辿ることでTogakiMakerの拡張がマスターできるようになっています。


Step02. このページで学ぶこと

ゲームを作ろうとすると、1つのプロジェクトで複数の会話表現が必要になることがあります。

例えば、ノベルゲームのような全画面を使った会話や、戦闘中の掛け合いのような表現。簡易的な吹き出しでの発言など…
スマートフォンアプリではホーム画面でキャラクターを タップすると台詞を喋るような演出も多くみられます。

このようにプロジェクトによって台詞や会話に関連する表現は様々です。また1つのプロジェクト内で1種類とは限りません。

TogakiMakerは、1つのプロジェクト内に複数の再生クラスを構築できるよう設計されています。

このページでは、実際に手を動かしながら簡単な再生クラスを新規で作っていきます。
順番に進めることでTogakiMakerの拡張の全てを理解できるようになります。


Step03.ストーリーファイルを作成する

最初に、新しいシナリオ再生機能で再生するストーリーを記述するストーリーファイルを作っていきます。

今回はあらかじめ作成しておいたこちらのファイルをダウンロードしてください。

ダウンロードしていただいたファイルを開くとA列のID部分が「trial…」になっています。
IDの接頭辞はシナリオ再生機能とデータを紐づけるために使用される重要な部分です。
*標準搭載されているSimpleAvgは「avg…」から始まるIDのシナリオと紐づいています。

ここからは「trial…」で始まるIDのシナリオデータを再生するための機能を作っていきます。


Step04. シナリオ再生機能の新規作成

それでは何もない状態からシナリオ再生機能を作っていきましょう。

シナリオ再生機能の作成には専用のウィザード機能を使います。

これが最も小規模なScenarioPlayerの状態になります。

prefixの入力欄に[trial]を記入したことで、[trial]から始まるシナリオデータはこのScenarioPlayerを使って編集するものとして関連付けが行われています。

実際にオリジナルの機能を作る際には、目的に合った接頭辞を指定するようにしてください。

Tips.TogakiMakerでエディットするための事前準備

TogakiMakerのメインツールはランタイムで編集やシミュレートを行います。
この時、ScenarioPlayerの実体が実行中のシーンに存在する必要があります。
今回は専用のシーンを作っていますが、ゲームの本編を実行中にScenarioPlayerの実体が配置されている場合には本編実行中にも同じようにエディットとシミュレートの機能が使用できます。

Tips.メインツールでコマンドを見た時の設定欄について

メインツールのコマンドリストから台詞コマンドのパラメータを見ると、とてもシンプルな設定欄しか持っていないことに気づきます。

これは標準で登録される StandardActorLineCommandParams のパラメータが乏しいことが原因です。
後述のコマンド自作機能でプロジェクト固有の台詞コマンドを作って差し替えることで、メインツールの設定欄が変化し、引数で届くパラメータの内容も拡張されます。

ScenarioPlayerに登録されている台詞コマンドを差し替えると、ストーリーファイルの再インポートが必要になります。


Step08.プロジェクト独自のコマンドを新規作成する

TrialScenarioPlayerでシナリオを編集しようとすると、選択できる修飾コマンドが1つもないことに気付きます。

コマンドの追加にもウィザード機能を使います。

ウィザード機能により出来上がった3種類のクラスはそれぞれ以下のようなクラスになります。

  • CommandParams.cs
    コマンドのパラメータをまとめたクラスです。
    このクラスはシリアライズされ保存されます。
    TogakiMakerのメインツールでこのクラスの変数を編集します。
  • CommandParamsEdit.cs
    メインツールで変数を編集するためのGUI操作を指定するクラスです。
    メインツールのコマンドパラメータウィンドウはこのクラスで設定したレイアウトで表示されます。
    UnityEditorにしか含まれないクラスであり、ビルド時に除外されます。
  • CommandWork.cs
    コマンドの処理をScenarioPlayerへアタッチするための作業クラスです。
    このクラスをアタッチすることで、メインツールから挿入できるようになります。

ScenarioPlayerのRegisterWork関数でCommandWorkを登録すると、コマンド実行時にはCommandWorkを経由してCommandParam が渡ってくるような挙動になります。

Tips. ScenarioPlayerが使わないコマンドについて

ScenarioPlayerが使用可能な修飾コマンドは「RegisterWork」の関数で登録されたものだけです。

開発が進んでくると、特定のScenarioPlayer専用のコマンドが増えてきます。
aaaScenarioPlayer専用に作ったコマンドがxxxScenarioPlayerで設定できないようにすることで、プログラマの意図しないデータは作れないようになっています。

Tips.コマンドの流用について.

今回は新規作成したコマンドを登録しましたが、既存のコマンドもRegisterWork関数で登録するだけで流用できるようになっています。
コマンドごとの挙動についてはAssetパッケージに含まれているSimpleAvgシーンを参考にしてみてください。

RegisterWork でコマンドの変数やTogakiMakerのGUIレイアウトを流用し、実行時にコマンドが呼ばれた際の挙動についてはScenarioPlayerごとに固有の動作を行うような実装ができるようになっています。

Tips.コマンドが使うリソースの管理について

ScenarioPlayerは「RegisterWorkでコマンドを登録すると実行タイミングでパラメータクラス付きで呼ばれる」というシンプルな実装になっています。

コマンドごとに必要なリソース読み込みも RegisterWork の記述周りで実装することになります。
コマンドの変数をもとにどの手法で読み込むかの実装を行うことができるため、プロジェクトに合わせてAssetBundleやAddressablesなどのリソース管理手法への移行が容易に行えます。

Tips.ScenarioPlayerが複数種類ある場合のデータとの関連付けについて.

プロジェクト内に複数種類のScenarioPlayerが存在する場合、「このシナリオデータはこのScenarioPlayerでの再生を想定して編集する」という判断が必要になります。

シナリオデータとScenarioPlayerの関連付けを、ScenarioPlayerの作成ウィザードで指定した [Playable scenario id prefix] の項目をもとに行っています。

TrialScenarioPlayerは作成の際に「trial」の文字列を指定したため、「シナリオIDの最初が trial でないものは管轄外」として扱うようになっています。

これで新規コマンドの追加は完了です。

今回はフォントサイズのパラメータのみ実装しましたが、テクスチャ名を持たせてコマンド実行時に切り替えたり、サウンド名を持たせて実行時に鳴らしたり、どのような演出も容易に作ることができます!
プロジェクトの仕様にあわせたコマンドを追加して独自のScenarioPlayerを作り上げてください!


Assetには標準実装のSimpleAvgScenarioPlayerのcsファイルが全て含まれています。
そちらで使用しているコマンドなども参考にしてみてください。


Step09.コマンドのシリアライズ,デシリアライズの変更

ここまででScenarioPlayerの種類を増やせるようになりました。
TogakiCommandを新しく作り、ScenarioPlayerへ登録することでプロジェクト固有のコマンド拡張が容易に行えることも確認できました。

表現の拡張性についてはこれで全てになります。


ここからは細かい部分ついて記述します。
まずは「コマンドのシリアライズ,デシリアライズはどのような手段で実装されているか」についてです。

シリアライズの実装はコマンド単位で行います。
ウィザードで作ったばかりのコマンドのシリアライズ,デシリアライズはJsonUtilityを使ってCommandParamsを丸ごとバイナリデータに変換するような実装になっています。
これは開発初期の仕様変更による変数の追加削除に耐えられるようにするためです。

開発中盤を超えてコマンドの仕様が確定したものは、CommandWorkクラスの関数をoverrideして独自の実装へ差し替えることが可能な作りになっています。
パッケージに含まれる標準的なコマンドは既に差し替えが行われていますので、移行の際には参考にしてください。


Step10.ストーリーファイルのインポーターの拡張

次にストーリーファイルのインポーターの拡張について説明します。

標準実装されているのはcsvファイルのインポートだけですが、プロジェクト独自のインポーターを追加して選択肢を増やせるようになっています。

以下のリンク先にExcelファイルに対応したインポーターを置いています。
こちらをダウンロードして解凍後にUnityプロジェクトの任意フォルダへ追加してください。

追加したところでインポーターの拡張は完了です。
メインツールからストーリーファイルをインポートする際に、ExcelStoryImporterが選択できるようになったはずです。
上記のzipファイルにはExcelフォーマットのサンプルストーリーファイルを入れていますので、試しにインポートしてみてください。
* サンプルストーリーファイルは[avg]を接頭辞とするシナリオデータが入力されています。SimpleAvgScenarioPlayerが配置されているシーン(Assets/TogakiMakerSimpleAvg/SimpleAvg.unity)を起動してインポートしてください。


インポーターの種類はいくつでも追加できます。
ExcelStoryImporterを参考に独自のインポーターを作ってみてください!


Step11.シナリオスクリプトのように本文にタグを仕込む手法について

ここまでTogakiMakerの拡張について解説してきましたが、会話の演出を作る場合はストーリーの本文テキストにタグを仕込む手法が主流です。

TogakiMakerでは以下の点を重視し、台詞と台詞の間に演出を挟むことに特化した作りになっています。

  • 習得コストの削減
  • 他言語対応の容易さ
  • 意図しない組み合わせによる不具合発生の抑制
  • タイプミスやヒューマンエラーによる調査工数の削減

半面、台詞の間にコマンドを挟む手法は本文中にタグを仕込む手法と比較するとタイミングの柔軟性が少々劣ります。

TogakiMakerの設計思想と反するため公式な対応は予定していませんが、どうしてもタグを仕込む手法と併用したい場合には拡張が可能です。

ストーリーファイルの時点で文中にタグを仕込んでおくと、実行時には RegisterWorkで登録した台詞コマンドの処理にそのまま文字列で届きます。
この文字列をどう扱うかはScenarioPlayerに任せていますので、そこでタグをチェックして独自の実装を加えれば、台詞中の任意のタイミングで演出を行うことも可能です。

SimpleAvgの本文表示機能でも簡易的なタグを使えるようになっています。
SimpleAvgScenarioPlayer::RegisterActorsLineCommandWork 関数内でタグの処理を実装していますので、拡張の際にはそちらを参考にしてください。


Step12.最後に

カスタマイズについての解説は以上になります。

昨今ではどのような規模のゲームでもストーリーが必要です。
TogakiMakerはシンプルな設計でどのような拡張でも受け止めることができ、様々なプロジェクトで使っていただけます。




TogakiMakerを使って、楽しくゲームを作っていきましょう!