Stingray タイプシステム

Stingray には、.type ファイルを中心とする内部データ入力システムが含まれています。プロジェクトコンテンツに SJSON 形式で格納されているこれらのファイルは、プロパティ、および複雑なデータタイプ間の関係を記述します。編集ツールおよびデータコンパイラはプロジェクト内で type ファイルをスキャンし、これらのファイルを使用して、プロジェクトコンテンツを構成する SJSON データファイル形式について論理的に判断します。この情報はユーザインタフェースをカスタマイズしたり、名前変更の影響を受けるファイルを判別したり、プロパティ値を検証したりする場合に使用できます。

Stingray は、JSON ファイル形式で提供される値をおおよそのベースとする、いくつかの事前定義された組み込みデータタイプを最低限サポートしています。これらの組み込みタイプを使用して、カラー、カメラ、ライトなど、複雑な「複合」タイプを記述することができます。これらは最終的に、ユニットやレベルのようにさらにリッチなファイル形式のタイプ記述に組み込むことができます。

注: 開発中です。 このシステムが完成するにつれて、変更される予定です。

Stingray での type ファイルの使用

type ファイルは Stingray のいくつかの場所で既に使用されています。

データコンポーネントのカスタムタイプを表現するためにエンティティシステムで使用される .component ファイルは、タイプシステムに基づいています。詳細については、「カスタムコンポーネントを作成する」を参照してください。
一部のプラグインでは、独自のデータタイプを定義する方法として、また Stingray エディタ内でこれらのデータタイプを編集する方法として、type ファイルを使用します。.type ファイルを使用して、エディタの UI で .scatter_brush、.blend_shape、および .capture_settings をのどのように編集するのかを記述する方法については、「カスタムアセットタイプを編集する」を参照してください。
.type ファイルを使用して新しい汎用読み込みダイアログボックスをカスタマイズする方法については、「新しいインポータを作成する」も参照してください。

独自のプラグイン内で .type ファイルメカニズムを使用する必要はありませんが、使用事例が上記の例と似ている場合は、使用した方が操作が簡単になることがあります。

ヒント: Script Editor を使用し、プロジェクトの .type ファイルを開いて編集します。

組み込みタイプ

組み込みタイプは基本的に、JSON ファイル形式でサポートされているタイプのスーパーセットです。コラボレーションによる編集を簡易化するたるために、いくつかの点が大きく異なっています。プラグインで作成される可能性のあるユーザ定義タイプと区別するために、組み込みタイプの先頭には常に : 文字が配置されます。

:array - シンプルで、変更不可能な、値のコレクションです。アニメーションやジオメトリデータなどのローバッファを格納するために使用されます。
:bool - true または false の値を取るシンプルなブール値です。
:dict - キーと値間のシンプルで変更可能なディクショナリマッピングです。
:enum - 事前に定義された一連の有効値の中のいずれかを取る値です。
:guid - ユニバーサルに一意な識別子です。JSON ファイル内で文字列として表されます。
:interface - 実装する具体的なタイプのプロトコルを指定する仮想データタイプです。
:number - シンプルな数値です。JSON ファイル内で倍精度浮動小数点値として表されます。
:resource - プロジェクト内の別のファイルに対する参照です。
:set - シンプルな衡平値で構成される、変更可能な、順序指定のないコレクションです。
:string - シンプルで変更不可能な UTF-8 エンコード文字列です。
:struct - 入力したフィールドを含み、インタフェースを実装することができる、複雑で変更可能なタイプです。
:switch - データ自体を調べた後に、指定されたいずれかのタイプに解決される仮想データタイプです。
:value - カスタマイズされていない、シンプルな任意の値を表すことができる仮想データタイプです(基本的には任意の JSON データです)。

タイプシステム内でハードコード化されるのは、組み込みタイプのみです。組み込みタイプを追加するには、編集ツールまたはデータコンパイラを変更する必要がありますが、その必要が生じることはほとんどありません。追加のプロパティを使用して有効な範囲、既定値などを指定することにより、ほとんどの組み込みタイプをカスタマイズできます。組み込みタイプごとにサポートされているタイプのプロパティの完全なリストについては、「組み込みタイプのリファレンス」を参照してください。

タイプ宣言

修飾されていない形式の場合、タイプ宣言は、別の既知のタイプを参照する type キーを含む SJSON オブジェクトになります。このオブジェクトに、次の例における min や max のように、タイプをカスタマイズするタイプ固有の追加プロパティを含めることができます。

{
    type = ":number"
    min = 0
    max = 1
}

タイプ宣言では一般的にカスタマイズが不要なため、カスタマイズされていないタイプの省略形としてタイプの名前を使用し、type = キーの使用は省略することができます。次の 2 つのタイプ宣言は同等です。

{
    type = ":number"
}
":number"

type ファイルの形式

他のユーザが使用できる 3D ベクトルタイプを宣言する type ファイルについて、シンプルな例を見てみましょう。

// core/types/vector3.type
export = {
    type = ":struct"
    fields = {
        x = ":number"
        y = ":number"
        z = ":number"
    }
}

ここで、ファイル core/types/vector3.type は、浮動小数点値構成されるシンプルな構造体を宣言するタイプ宣言を書き出します。

内部では、type = ":struct" プロパティを含むオブジェクト全体が :struct タイプカスタマイザにディスパッチされ、このカスタマイザが提供されたプロパティに基づいて新しいタイプ定義を発行します。この場合、:struct タイプカスタマイザは fields という名前の付いたプロパティを検索するようにハードコード化されていて、フィールド名をタイプにマップするディクショナリとなることが予想されます。オートデスクの :struct には x、y、および z フィールドがあり、これらのすべてのフィールドがカスタマイズされていない :number 値を取ります(:struct タイプカスタマイザでサポートされているすべてのプロパティのリストについては、「組み込みタイプのリファレンス」を参照してください)

:struct タイプカスタマイザは、オートデスクのベクトルを表す新しいタイプを発行します。オートデスクでは、このタイプ定義を .type ファイル内の export キーに割り当てることにより、別のタイプのファイルで使用できるようにしています。その他の .type ファイルは、独自のタイプ宣言内でオートデスクの .type ファイルのリソース名を指定することにより、オートデスクのベクトルタイプを参照できるようになっています。たとえば、次のようになります。

// core/types/pose.type
export = {
    type = ":struct"
    fields = {
        position = "core/types/vector3"
        rotation = "core/types/quaternion"
        scale = {
            type = "core/types/vector3"
            fields = {
                x = { default = 1 }
                y = { default = 1 }
                z = { default = 1 }
            }
        }
    }
}

ユーザ定義タイプをさらにカスタマイズするには、ネストされたディクショナリを使用してプロパティを上書きする必要があることに注意してください。上記のタイプ例の position フィールドには、オートデスクのカスタム core/types/vector3 タイプのインスタンスがカスタマイズされないで使用されています。ただし、scale フィールドでは、x、y、および z フィールドの default プロパティが上書きされています。

プライベートタイプ

type ファイルには複数のタイプ宣言を含めることができます。外部に表示されるのは、exported タイプという 1 つのタイプのみです。ただし、ファイル内で定義されている他のタイプは、このファイル内で自由に参照することができます。これにより、単一の .type ファイル内で非常に複雑なデータタイプを作成し、書き出されたタイプ内でより原子的なデータタイプを何度も再利用することができます。

このシナリオでは、プライベートタイプ宣言をタイプファイル内のルートレベルの types キーの下に配置する必要があります。配置した後、これらの type キーの前にハッシュ文字を配置して、type ファイル内の他の場所からこれらのタイプを参照することができます。

// core/types/direction.type
export = "#direction"
types = {
    direction = {
        type = ":struct"
        fields = {
            x = "#component"
            y = "#component"
            z = "#component"
        }
    }
    component = {
        type = ":number"
        min = -1
        max = 1
    }
}

ここでは、方向を表すために使用されるタイプを宣言しており、そのコンポーネントは [-1, 1] の範囲に収まります。この方向タイプは、x、y、および z フィールドごとにプライベートな #component タイプを参照します。ルートレベルにある export プロパティは #direction タイプを参照することで、この方向タイプを core/types/direction (オートデスクの type ファイルの名前)としてワールドの残りの部分に公開しています。その他の type ファイルはこの方向タイプを直接参照できるようになりましたが、コンポーネントタイプを直接参照することはできません。方向を構成する構成要素としてコンポーネントタイプを「使用する」ことができますが、独自のプライベートタイプを再利用することはできません。

type ファイルを使用してファイル形式を表す方法

type ファイルの主な用途は、他の SJSON ベースファイル形式の構造およびセマンティックを記述することです。type ファイルに、これらのファイル内の情報をどのように解釈するのかを編集ツールに指示する、特定のリソースタイプを関連付けることができます。type ファイルにリソースタイプを関連付けるには、type ファイル内の extension プロパティを、ファイルが表すリソースタイプ(つまり、これらのリソースファイルで使用される拡張機能)の名前に設定します。

// core/types/unit.type
extension = "unit"
export = {
    type = ":struct"
    fields = {
        ...
    }
}

タイプのメタデータ

すべてのタイプに、タイプ自体に関するデータを格納するために使用できるオプションの metadata ブロックがあります。このブロックはデータコンパイラや、場合によっては Stingray エディタによって読み取られ、これらによるタイプの処理方法に影響を及ぼすことがあります。一般に、データコンパイラまたはエディタのコード自体に独自の追加を行った場合を除き、metadata ブロックを使用することはありません。

エディタのメタデータ

タイプの metadata ブロックのほかに、editor ブロック内のエディタ専用のメタデータを設定することができます。このメタデータは Stingray エディタによって読み取られ、プロパティエディタ内でのタイプの表示方法などをコントロールします。たとえば、以下では、組み込みの adskPropertySlider コントロールを使用して :number プロパティを表示しています。エディタのメタデータには、スライダの step 設定など、control 固有のプロパティを含めることができます。

{
    type = ":number"
    min = 0
    max = 100
    default = 50
    editor = {
        label = "Health"
        description = "Initial health of the entity"
        priority = 140
        control = "adskPropertySlider"
        step = 10
    }
}

後でゲーム固有のウィジェットをプロジェクトに追加することができますが、オートデスクで現在サポートされているのは組み込みウィジェットの一部のみです。コントロールと使用可能なプロパティの包括的なリストについては、「組み込みメタデータのプロパティ」を参照してください。

これで、タイプの他のプロパティと同様に、editor メタデータのプロパティをカスタマイズできるようになりました。したがって、共有 type ファイル内で実用的既定値を指定し、必要に応じてそのラベルおよび説明を上書きすることができます。

{
    type = ":struct"
    fields = {
        bloom_tint = {
            type = "core/types/color"
            editor = {
                label = "Tint"
                description = "Bloom tint color"
            }
        }
    }
}

type ファイルのプロパティのリファレンス

このセクションでは、type ファイルのサポート対象プロパティの中の上位のものをすべて示します。

プロパティ	タイプ	既定値	説明
export	Type	null	オートデスクのタイプリソース名に関連付ける必要があるタイプです。この値にはインラインタイプの記述、または types ブロック内で定義されているタイプの参照を指定することができます。
extension	String	null	書き出されたタイプに関連付けるオプションのファイル拡張子です。
references	Object<String, String>	{}	(廃止予定)名前で暗黙的に参照されているファイル拡張子のオプションのマップです。オートデスクのタイプが参照されている場合、これらのファイルが存在していれば、これらも参照されます。
types	Object<String, Type>	{}	内部の type キーとタイプ宣言のオプションのマップです。export プロパティに # が先頭に付加されたキーを使用して、これらの 1 つを書き出すことができます。

例

// core/types/unit.type
{
    export = "#unit"
    extension = "unit"
    references = {
        anim = "unit_anim"
        flow = "flow"
        mesh = ["fbx", "bsi"]
        physics = "physics"
    }
    types = {
        unit = {
            type = ":struct"
            fields = {
                lights = {
                    type = ":dict"
                    key = ":string"
                    value = "#light"
                }
                ...
            }
        }
        light = {
            type = ":struct"
            fields = {
                color = "core/types/color"
                ...
            }
        }
    }
}

Stingray タイプ システム