便利なエンジン プラグイン インタフェース

このページでは、プラグインで利用可能な、最も一般的に使用されるいくつかのエンジン API について概要を示します。

プラグインの非常に一般的な機能の 1 つは、新しいモジュールおよび関数をエンジンの Lua 環境に追加することです。プロジェクトの Lua スクリプトが Lua 環境内でこれらの新しい関数の 1 つをプロジェクトとして呼び出すと、プラグイン内の対応する C 関数が呼び出されます。

この仕組みを示す非常に単純な例については、エンジン プラグインのサンプルに含まれている simple_plugin/plugin.c ファイルを参照してください。このファイルは新しい C 関数 static int test(struct lua_State *L) を定義します。その後、エンジンの LuaApi を取得し、add_module_function("SimplePlugin", "test", test) を呼び出して、C から Lua に test 関数を公開します。この関数に stingray.SimplePlugin.test() と名前を付けて、プロジェクトの Lua コードから呼び出すことができます。

C 関数に lua_State が渡されることに注意してください。これは、Lua 呼び出しによって渡されたパラメータに C 関数からアクセスできるようにして、Lua に値を戻す Lua の「スタック」です。この方法は、Lua と C の間で情報をやり取りする標準的な方法です。詳細については、Lua のドキュメントを参照してください。その他に知っておく必要があるのは、スタック操作(lua_tonumber や lua_pushnumber)を行うためにプラグインから Lua 関数にアクセスする際に Stingray LuaApi (LuaApi::tonumber や LuaApi::pushnumber)を使用することのみです。LuaApi は、Stingray に固有のタイプを処理する追加関数(LuaApi::getunit や LuaApi::pushvector3 など)を使用して、これらの標準関数も拡張します。これにより、プラグインおよびプロジェクトの Lua コードの間で、ユニット、ベクトル、クォータニオン、および行列をやり取りできるようになります。

ScriptApi を使用すると、アプリケーションとプロジェクト コンテンツを操作する多数の関数にアクセスすることができます。Lua スクリプト API と同様、ScriptApi を使用してレベルのロード、ユニットのスポーンとスポーン解除、物理シミュレーションのコントロールなどを実行できます。Lua で実行できるほとんどの操作を ScriptApi で実行できます。実際、ほとんどの Lua スクリプト API はシーンの背後で C API を呼び出すため、C から直接関数を呼び出して、操作をすばやく実行することができます。

ScriptApi は、プロジェクトが実行されているときに、プラグインからプロジェクトのコンテンツを追加または変更する必要がある場合に役立ちます。また、Lua ではなく、C でゲームプレイ コードを記述して、ランタイムのパフォーマンスを限界まで引き上げようと考えるプロジェクト制作者にも役立ちます。

通常、プラグインがジョブを実行するには、何らかの特殊なカスタム データを利用する必要があります。このデータをプロジェクト内のファイルに保存することができれば、エンジンのリソース管理システムを利用してデータをコンパイルし、エンジンからランタイムにアクセスできるようになります。

まず、エンジンから DataCompilerApi を取得する必要があります。add_compiler() 関数を使用して、リソース タイプ用の新しいコンパイル関数を追加します。カスタム タイプのリソースをコンパイルする必要があるときはいつでも、エンジンからこの関数が呼び出されます。関数はディスク ファイル表現からデータを取得し、それをプラグインがランタイムで使用するバイナリ表現に変換します。

プラグインから自分のデータにランタイムにアクセスする必要がある場合は、ResourceManagerApi を使用してカスタム タイプのリソースをクエリーし、取得することができます。

このリソース管理パイプラインを示す例(ファイルからバイナリ表現に SJSON データをコンパイルしてから、ランタイムにこのデータにアクセスする方法)については、エンジン プラグイン サンプル内の bigger_plugin/plugin.cpp ファイルを参照してください。

プラグインで MeshObjectApi および RenderBufferApi を併用すると、ランタイムに新しいメッシュを作成し、シーン内でレンダリングすることができます。新しいオブジェクトは、Stingray エディタでシーン内に配置された場合とまったく同じように、動的なライティングによってシェーディングされます。

プラグインでメッシュを即座に作成してレンダリングする方法を示す作業例については、エンジン プラグイン サンプル内の render_plugin/plugin.cpp ファイルを参照してください。このプラグインは Stingray という単語のような形状のメッシュをプログラムによって作成し、メッシュの各フレームを変形して布地エフェクトをシミュレートします。

この例を自分のプロジェクト内で操作するには、まず .dll をコンパイルして、インストールします。次に、プロジェクトの Lua スクリプトから、プラグインによって Lua 環境に追加された stingray.RenderPlugin.create_logo() 関数を呼び出します。この関数に次の 3 つのパラメータを渡す必要があります。

• 新しいメッシュの親として機能するユニット
• 新しいメッシュがこのユニット内で使用する必要があるシーン グラフのインデックス(1 を使用可能)
• メッシュで使用する必要があるマテリアル生成されたメッシュには法線チャネルがないため、標準マテリアルは機能しません。core/stingray_renderer/shader_import/no_uvs を使用できます。または、標準マテリアルを編集し、出力ノードの法線データを生成するノードを削除することができます。

問題が発生した場合は、プラグインからユーザにフィードバックを戻すことをお勧めします。エンジンにはメッセージを記録するためのメカニズムが組み込まれていて、Stingray エディタ内で作業しているユーザは、Log Console でこれらのメッセージを表示することができます。エンジンが独自のメッセージにも同じメカニズムを再利用するようプラグインを設定することができます。

エンジンから LoggingApi を取得し、error(), info() または warning() メソッドを呼び出す必要があります。これらのメソッドを呼び出す場合は、system パラメータ(プラグインの名前)を指定して、ログ メッセージ内に表示されるようにする必要があります。たとえば、次のようになります。

_logging_api->warning("My Custom Plugin", "Something may have gone wrong!");

プラグインのあらゆる面が魅力的かつ独創的というわけではありません。プラグインを利用するには、ベクトル、クォータニオン計算、文字列と配列およびメモリ割り当ての管理など、おもしろくない計測作業も行う必要があります。

この作業を簡易化して、プラグイン間でこれらの処理方法を標準化するために、Stingray SDK には「プラグインの基礎」が付属しています。プラグインの基礎は、このような一般的なタスクを処理するためにプラグイン内で使用できる一連のインタフェースです。プラグインの基礎は全体を省略することができ、必要なだけ自由に使用することができます。

プラグインの基礎が特に役立つのは、ScriptApi と組み合わせた場合です。このタイプのほとんどは、ScriptApi 関数で使用されるタイプと一緒に前後にキャストできるためです。たとえば、ScriptApi から CApiQuaternion が返された場合は、これを stingray_plugin_foundation::Quaternion にキャストし、stingray_plugin_foundation::lerp() または stingray_plugin_foundation::normalize() などの基礎関数を使用して変換することができます。

基礎の機能を参照するには、SDK の plugin_foundation フォルダ内にあるヘッダー ファイルを参照してください。いずれかの基礎コンポーネントを使用する場合は、これらのコンポーネントを定義するヘッダー ファイルをプラグインにインクルードするだけで済みます。

すべての実装はインライン処理されるため、関数の動作を正確に確認することができます。プラグインの実装を変更する必要がある場合は、独自プロジェクトにファイルをコピーして、コピーを変更できるようにする必要があります。