組み込みタイプのリファレンス

このページでは、Stingray に付属していてすぐに使えるタイプ、およびこれらの各タイプをカスタマイズする場合に使用できるサポート対象プロパティのセットについて詳細に説明します。

• equatable 特性を持つタイプは、指定したタイプの 2 つのインスタンス間の同等性をテストすることができます。これらは、セットのメンバーシップをテストする場合などに、ディクショナリ キーとして使用するのが最適です。
• mutable 特性を持つタイプは、その場で変更できます。可変データ構造の参照を保持しているすべてのタイプは、変更を適用した後に、その変更内容を確認できます。
• simple 特性を持つタイプは、未処理の JSON 値をカスタマイズされていない形式で記述します。このタイプをカスタマイズすると、simple タイプの特性が失われることにご注意ください。
• virtual 特性を持つタイプは、保持されているデータに基づいて、ランタイムで非仮想タイプに動的に調整されます。

これらのタイプおよびこれらの使用方法の背景情報については、「Stingray タイプ システム」を参照してください。

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

固定されている、値のコレクションです。読み込まれたアニメーションやジオメトリ データなど、変更する必要がないデータの未処理バッファを格納するには、配列を使用します。作成後に変更できるコレクションが必要な場合は、:dict または :struct を選択して、コラボレーションによる編集または結合をサポートする必要があります。 equatable 値のコレクションがあり、順序は重要ではないがその中のエントリを追加および削除できるようにする必要がある場合は、:set を使用してください。

たとえば、次のようになります。

{
    type = ":array"
    value = ":number"
}

単純なブール値です。true または false のいずれかを指定できます。

キーを値にマッピングする可変の結合ディクショナリです。

たとえば、次のようになります。

{
    type = ":dict"
    key = ":guid"
    value = ":string"
}

値には、有効な値の定義済みセットの 1 つを指定する必要があります。

次に示す editor メタデータ プロパティは、Stingay エディタ内の :enum タイプの動作に影響します。

たとえば、次のようになります。

{
    type = ":enum"
    value = ":string"
    cases = [
        "AmbientLight"
        "OmniLight"
        "SpotLight"
    ]
    default = "OmniLight"
    editor = {
        case_labels = {
            "OmniLight" = "Omnidirectional Light"
        }
    }
}

ユニバーサルに一意な識別子です。 新しい一意の ID に初期化されます。

カスタマイズ可能なプロパティはありません。

コレクションまたはプロパティで、ランタイムにのみ決定可能なタイプを参照する必要がある場合に使用されます。たとえば、シェイプのコレクションがあり、さまざまな種類のシェイプにタイプに応じて追加プロパティを設定できるとします。この場合は、シェイプの値タイプに :interface を使用して、すべてのシェイプに必要な共通のプロパティを記述することができます。

interface タイプでは、値の具体的なタイプの決定方法に関する調整戦略も指定します。

オブジェクト内のキーの値からタイプを参照して、インタフェースを調整します。

たとえば、次のインタフェースでは、ランタイムで具体的なタイプを決定するためにオブジェクトの "type" プロパティの値を読み取ります。この値は、通常はタイプのリソース名、またはタイプを示す短いエイリアス文字列になります。

// core/types/flow_node.type
export = {
    type = ":interface"
    refine = {
        type = ":key"
        key = "type"
    }
}

インタフェースを実装するゲーム固有の :struct を見てみましょう。implements 宣言は、タイプ システムに、仮想タイプ core/types/flow_node のコンテキスト内で短いタイプのエイリアス "sword_trail" を具体的なタイプ game/types/sword_trail_flow_node に解決するよう指示します。短いタイプのエイリアスを使用しない場合は、implements 宣言内で "core/types/flow_node" = true を代わりに指定することができます。

// game/types/sword_trail_flow_node.type
export = {
    type = ":struct"
    implements = {
        "core/types/flow_node" = "sword_trail"
    }
    fields = {
        ...
    }
}

次に、.flow ファイル形式を示す type ファイルであるインタフェースの使用例を示します。オートデスクのノード セットには、core/types/flow_node インタフェースを実装することを宣言するいずれかの構造が含まれています。

// core/types/flow.type
extension = "flow"
export = {
    type = ":struct"
    fields = {
        nodes = {
            type = ":dict"
            key = ":guid"
            value = "core/types/flow_node"
        }
    }
}

オートデスクではこれらのタイプの宣言に基づいて、この .flow ファイル内のノードのコレクションに含まれる最初の要素がタイプ game/types/sword_trail_flow_node であることを判別できるようになりました。なぜなら、nodes は タイプ core/types/flow_node の値の :dict であるからです。オブジェクトの type は "sword_trail" であるため、指定したエントリは具体的なタイプ game/types/sword_trail_flow_node に調整されます。

// game/units/guard/guard.flow
nodes = {
    "2c91b841-a48f-49cb-8a48-9e5f2d5550e1" = {
        type = "sword_trail"
        variable_values = {
            parent_node = "right_hand"
            axis = "z"
            sword_length = 1.1
            ...
        }
    }
    ...
}

数値です。JSON ファイルでは数値は常に倍精度浮動小数点値として表されますが、配列のインデックスなどを表すようにカスタマイズできます。

次に示す editor メタデータ プロパティは、Stingay エディタ内の :number タイプの動作に影響します。

たとえば、次のようになります。

{
    type = ":number"
    min = 0
    max = 1
    default = 0.5
    editor = {
        step = 0.1
    }
}

resource タイプはプロジェクト内の別のファイルの参照です。これは、このファイルと参照先ファイルの間に関係があることをデータ コンパイラに指示します。

参照は 2 つの特殊なキー($resource_name および $resource_type)を含むディクショナリとして表されます。両方とも文字列値であると予測されます。リソース名は、プロジェクト関連のスラッシュ区切りのファイル パスです。"core/units/camera" のようにファイル拡張子は含まれません。リソース タイプは、先行ドットを除く単なるファイルの拡張子です。したがって、既定のカメラ ユニットの参照は、JSON ファイル内で次のようになります。

{
    "$resource_name" = "core/units/camera"
    "$resource_type" = "unit"
}

参照の種類によっては、複数のリソース タイプがサポートされることがあります。これに対処するために、extension プロパティでファイルの拡張子からなる配列を指定したり、単一の拡張子を文字列として指定したりできます。

たとえば、次のようになります。

{
    type = ":resource"
    extension = ["fbx", "bsi"]
}

可変の、順序変更できない、単一の equatable 値のコレクションです。セットは、JSON ファイル内で通常の JavaScript 配列として表されます。

たとえば、次のようになります。

{
    type = ":set"
    value = ":string"
}

固定されている UTF-8 エンコード文字列です。

入力したフィールド、ユーザインタフェースのメタデータ、およびサブ要素の宣言を含めることができる複合タイプです。構造体は、JSON ファイル内で通常の JavaScript オブジェクトとして表されます。構造体の既定の状態は、フィールドの既定値によって判別されますが、ネストされたプロパティオーバーライド宣言(他の場所で詳述)を使用してオーバーライドすることができます。

構造台は、構造体が準拠する interfaces、または複数の異なるタイプの構造体を含むコレクションが使用可能な implements のセットを指定できます。インタフェースの詳細については、:interface タイプのリファレンス エントリを参照してください。

たとえば、次のようになります。

{
    type = ":struct"
    fields = {
        nodes = {
            type = ":dict"
            key = ":string"
            value = "#node"
        }
        geometries = {
            type = ":dict"
            key = ":string"
            value = "#geometry"
        }
    }
}

データ形式の変動の方法がデータ自体を調べることによってのみ決定される場合に使用します。フィールド値、タイプ、または JSON 値自体のタイプをオンにする場合に設定できます。通常は、代わりに :interface タイプを使用する必要があります。このタイプの場合は、:switch 宣言を変更しなくても、新しい実装を追加することができるからです。ただし、シナリオによっては、:switch タイプが役立つこともあります。

":type" を on にすると、JSON 値は組み込みの simple タイプの名前に解決されます。値を決定できない場合は、":null" になります。

たとえば、うっかりして、配列またはディクショナリのいずれかを指定できるフィールドを含むデータ構造がプロジェクト内に設定されたとします。両方の変数を処理するために、値の ":type" をオンにする :switch タイプとしてフィールドが宣言されています。

{
    type = ":switch"
    on = ":type"
    default = ":dict"
    cases = {
        ":array" = {
            type = ":array"
            value = {
                type = ":resource"
                extension = "material"
            }
        }
        ":dict" = {
            type = ":dict"
            key = ":string"
            value = {
                type = ":resource"
                extension = "material"
            }
        }
    }
}

この例では、データ内に異なるプロパティを持つ 2 種類のライト "omni" または "spot" を含めることができます。調べている JSON 値がディクショナリである場合は、"light_type" キーに関連付けられた値を調べます。この値が "spot" の場合は、ディクショナリを range および angle フィールドを持つ :struct として処理します。"light_type" が "omni" の場合は、radius フィールドだけがあるものとして処理します。default ケースは "omni" であるため、タイプの新しいインスタンスはオムニ ライトになります。また、"light_type" キーにアクセスしたり、cases ディクショナリ内のキーのいずれかと比較することができない場合も、オムニ ライトであると想定します。

この特定の状況では、ライト タイプのオプションがタイプの宣言内で指定されたケースに限定されるため、:switch を使用する必要がない可能性があります。代わりに、他のタイプのライトで実装可能な :interface タイプを作成してください。

{
    type = ":switch"
    on = ":value"
    of = "light_type"
    default = "omni"
    cases = {
        "omni" = {
            type = ":struct"
            fields = {
                radius = ":number"
                ...
            }
        }
        "spot" = {
            type = ":struct"
            fields = {
                range = ":number"
                angle = ":number"
                ...
            }
        }
    }
}

任意の simple タイプ(任意の JSON 値)を表すことができる可変データ タイプです。

カスタマイズ可能なプロパティはありません。