リソースの名前と ID について

プロジェクト内のさまざまな種類のものを名前の文字列によって識別できます。例: リソースとアセットはプロジェクト内で "content/models/floor" のようなパス名を持ちます。また "unit" または "material" のようなタイプ名も持ちます。ユニットおよびエンティティのようなレベル オブジェクトはエディタで設定できる名前を持ちます。マテリアルはスロット名を持ちます。フロー ノードは名前の付いた入力および出力ポートを持ちます。

これにより人間が読みやすく理解しやすくなります。ただし、ランタイムにゲーム エンジンでこれらの文字列を保存、使用することは非効率的です。パフォーマンスを最大化し、各識別子のメモリの占有量を予測可能で一貫性のあるものにするために、エンジンはほとんどの文字列を内部的にハッシュ値に変換します。

たとえば、content/models/floor として参照するユニットは、エンジン内で 0xc9f385895440595d として参照されます。

この C プラグインおよびスクリプト API をエンジン プラグインから直接使用するときには、通常、文字列の代わりにハッシュ ID 値を指定することによってリソースおよびレベル オブジェクトを識別する必要があります。stingray_plugin_foundation/id_string.h で提供されているクラスを使用して、これらのハッシュ値を構築できます。

• 呼び出す必要のある関数に unsigned 値が必要な場合は IdString32 クラスを使用します。これらのパラメータの名前には、多くの場合(必ずではありません)、_id32 接尾辞があります。

• 呼び出す必要のある関数に uint_64 値が必要な場合は IdString64 クラスを使用します。これらのパラメータの名前には、多くの場合(必ずではありません)、_id64 接尾辞があります。

これらのクラスは同じように動作しますが、唯一の違いは、アドレス可能空間の合計、つまり衝突せずに表すことができる異なる文字列の数です。

注: Lua スクリプト API の関数を呼び出すときに、通常、文字列または IdString32/IdString64 Lua オブジェクトを渡すことができます。Lua API 実装では C API を呼び出す前に、これらの入力文字列が自動的に適切なサイズのハッシュ値に変換されます。

文字列のハッシュへの変換は一方向のトランスフォームです。文字列からハッシュへ変換できますが、保持しているすべてがハッシュの場合、元の文字列に戻すことはできません。ハッシュ ID を返すエンジン API 関数を呼び出す場合、次のことが可能です

ここでは、ユニット用のマテリアル スロット名に割り当てられているマテリアル リソースを変更するために呼び出すことができる、c_api_unit.h からの UnitCApi::se _material() 関数の定義を示します。

uint64_t        (*set_material) (UnitRef, unsigned slot_name_id32, uint64_t material_resource_name_id64, const char *optional_debug_material_resource_name, unsigned debug_suppress_slot_assignment_warning);

変更するマテリアル スロット名を指定する slot_name_id32 パラメータは、unsigned 値です。これを作成するには、IdString32 を使用します。

プラグインに含まれているすべてが、参照する元の文字列 ID である場合は、次のようにこの関数を呼び出すことができます。

#include <plugin_foundation/id_string.h>
using namespace stingray_plugin_foundation;

...

    _c_api->Unit->set_material(unit_ref, IdString32("material_slot_name").id(), IdString32("content/materials/orange").id(), "orange", 0);

const char* または文字列変数で保存するのではなく、文字列の識別子を保存し、IdString32 または IdString64 オブジェクトを作成する必要がある場合は、一般的には、プラグインは、エンジンと同じ原則に従うことをお勧めします。