Data Lists

Data Listsは、C# Listsと同様に、インデックスによって Data Tokens を格納します。Data Listの関数のほとんどは、基盤となるC#リストのラッパーであるため、より詳細な情報が必要な場合はC#リストのドキュメントも併せて参照してください。

Data Listsは、VRCJSON を使用してJSON文字列との間でシリアライズを行うことができます。これが、現在ネットワーク経由でData Listsを同期する際に推奨される方法です。

UdonSharpを使用している場合は、using VRC.SDK3.Data; ディレクティブを含めることでData Listsを使用できます。

コンストラクタ

プロパティ

Functions

Jsonから生成されたData Listに対して Contains、IndexOf、LastIndexOf といった、すべての値を操作または参照する関数を呼び出すと、まだ解析されていないトップレベルの値がすべて解析される点に注意してください。値が多数ある場合、これには高いコストがかかる可能性があります。一度解析されれば、その後の操作は低コストになります。

DataList から値を取得する

DataList から値を取得する方法はいくつかあります。それぞれ用途が異なるため、目的に合わせて最適なものを選んでください。

• TryGetValue
• TokenType を指定した TryGetValue
• 短縮形のブラケット構文

TryGetValue

リストから安全に値を取得したい場合は、TryGetValue を使用することを推奨します。これは値の取得に成功したかどうかによって true または false を返す関数です。この関数は if や branch の条件式内に入れ、成功時と失敗時の挙動を明確にするための設計になっています。

if (list.TryGetValue(0, out DataToken value))
{
    Debug.Log($"Success! {value}");
}
else
{
    Debug.Log("Failed! {value}");
}

もし取得に失敗した場合でも、受け取る DataToken 自体は有効ですが、データが含まれている代わりに error が格納されます。

このメソッドは、特定の場所から値を取得したいが、その内容が何であるかは（現時点では）問わない場合に適しています。

この関数には型チェック機能が組み込まれていないため、if、branch、または switch といった何らかの型チェックを併用してください。もし特定の型のみを扱いたい場合は、自動的に型チェックを行ってくれる TokenType 指定版の TryGetValue を使用することを推奨します。

TokenType を指定した TryGetValue

リストから値を取得したいものの、どのような型であるかわからない場合は、型チェックが重要です。自前でコードを記述することもできますが、複雑になりがちです。代わりに、TokenType を引数に含むバージョンの TryGetValue を使用してください。これを使用すると、期待する型である場合にのみ値が取得されます。そうでない場合は false が返されるため、適切に処理を行うことができます。

このメソッドは、特定の場所から特定の値を取得したいが、データが外部ソース由来であり、正しいデータが格納されているか確信が持てない場合に適しています。

// You could do it this way, but it's a bit ugly
if (list.TryGetValue(0, out DataToken value)) {
    if (value.TokenType == TokenType.DataDictionary)
    {
        Debug.Log($"Success! Matching dictionary has {value.DataDictionary.Count} items");
    }
}

// This approach has a type check built in! It's functionally the same, but streamlined.
if (list.TryGetValue(0, TokenType.DataDictionary, out value)) {
    Debug.Log($"Success! Matching dictionary has {value.DataDictionary.Count} items");
}

短縮形のブラケット構文

UdonSharp での list[5] = "value"; や、Udon Graph での DataList Get Item ノードといったブラケット構文を使用して、DataList のアイテムを取得・設定することも可能です。この方法は記述が短く、簡単に利用できます。ただし、これは完全な安全性は保証されておらず、無効な操作を行うと UdonBehaviour が停止する可能性がある点に注意してください。データの内容を完全に把握しており、確実に存在し、かつ期待する型であることが保証されている場合にのみ使用してください。それ以外の場合は、何らかの形の TryGetValue を使用することを推奨します。

list[0] = 5;
list[1] = 10;

// This makes the assumption that index 0 and 1 will always contain integers.
// This is a safe assumption to make since we set them just above in a controlled environment.
// If the data is coming from an external source, we shouldn't make these assumptions!
int sum = list[0].Int + list[1].Int;

Data Listの初期化

Udonsharpでは、Data Listはプライベート変数内で初期化できます。これにより、コードが実行される前に定義された既存のデータセットを持つことができます。また、ネストされた辞書やDataTokenがサポートするその他すべての型にも対応しています。この構文の使用例を以下に示します。

private DataList _groceries = new DataList()
{
    "Bananas",
    "Grapes",
    "Milk",
    "Soda",
    "Turkey",
    "Ham",
    "Roast Beef"
}

現時点では、Udonsharpは関数内部でのこのような初期化をサポートしていません。これはUdonsharpに対する機能リクエストとなります。

また、現時点ではUnityはDataListをシリアライズしないため、シリアライズされるpublic変数に対してこれを使用することは推奨されません。 これはあくまで private または [NonSerialized] public の変数に対してのみ使用してください。これは現在開発中の機能への追加要素となります。

他のプレイヤーとネットワーク越しにデータリストを同期する

Data Listは直接同期することはできません。しかし、VRCJson を使用してJSON文字列との間でシリアライズを行うことが可能です。これが現在のUdonSyncでData Listを同期するための推奨される手法です。

このための方法の一つとして、OnPreSerializationおよびOnDeserializationを使用してJSON文字列のシリアライズとデシリアライズを行う手法があります。この手法を使えば、コードの残りの部分でシリアライズを意識する必要がなくなり、単に値を設定するだけで済みます。

[UdonSynced]
private string _json;
private DataList _list;

public override void OnPreSerialization()
{
    if (VRCJson.TrySerializeToJson(_list, JsonExportType.Minify, out DataToken result))
    {
        _json = result.String;
    }
    else
    {
        Debug.LogError(result.ToString());
    }
}

public override void OnDeserialization()
{
    if(VRCJson.TryDeserializeFromJson(_json, out DataToken result))
    {
        _list = result.DataList;
    }
    else
    {
        Debug.LogError(result.ToString());
    }
}

FAQ

なぜ各型用の ToArray メソッドがないのですか？

各データ型に対して ToArray メソッドがあれば理想的ですが、現状の Udon ではジェネリクスがサポートされていないため実現できません。ToStringArray、ToFloatArray、ToDoubleArray などの個別のメソッドを作成することは技術的に可能ですが、すべての型に対応させようとするとコードが肥大化してしまいます。さらに、Udon 2 でジェネリクスが導入されれば、これらのメソッドはすぐに非推奨となってしまいます。また、単純な ToArray メソッドだけでは、それほど大きな利点は得られません。真の利点は ToArray(typeof(Collider)) のようにオブジェクト型に対して ToArray を実行し、キャストの必要性をなくすことにありますが、あらゆるオブジェクトに対して ToArray をサポートするのは現実的ではありません。また、object 専用の ToArray をサポートすることは、DataToken を扱うよりもさらに手間がかかることになります。

DataToken から値を取得する作業は多少煩雑に感じるかもしれませんが、これこそが DataToken の本来の設計用途であり、その作業を支援するためのユーティリティがいくつか用意されています。

配列と似ていますが、何が違うのですか？

配列（Array）は、多数の値を順番に格納し、インデックスでアクセスするための似たような構造です。配列は非常にシンプルで、その役割を果たすことに特化しており、非常に効率的です。一方、DataList はより多くのことができる複雑な型です。例えば、配列は最初に作成する際に特定の長さを指定する必要があり、新しい配列に置き換えない限りアイテムを追加することはできません。しかし、だからといって配列が劣っているわけではなく、リストよりも配列を使うべき正当な理由は依然として存在します。

どのような場合に配列ではなく DataList を使うべきですか？

配列ではなく DataList を選ぶべきなのは、特定の機能が必要な場合です。すべてを DataList に置き換える必要はありません。

• コンテナに対して動的にアイテムを追加・削除したい場合。配列では不可能です。
• 1つのコンテナに複数の異なる型を同時に格納したい場合。配列では不可能です。
• コンテナの中にコンテナを任意に含めたい場合。配列でも可能ですが、厳密な深さを定義する必要があります。DataList なら、必要に応じて任意の深さにネストできます。

どのような場合に DataList ではなく配列を使うべきですか？

• 毎フレームコンテナを反復処理するなど、パフォーマンスが重要な場合。DataList は DataToken から値を取り出す際に、ごくわずかなパフォーマンスオーバーヘッドが発生する可能性があります。
• コンテナをネットワーク経由で同期したい場合。どうしても DataList が必要な場合は JSON を介して技術的に同期可能ですが、通常の配列同期よりもパフォーマンスと帯域幅の両面で負荷がはるかに大きくなります。
• コンテナに特定の1つの型のみを格納すればよい場合。DataList でも可能ですが、C# の厳密な型付けの特性をバイパスすることになります。つまり、コードエディタがコンテナに含まれる型を正確に把握できなくなり、本来であればコンパイルエラーになるようなバグを書いてしまう可能性があります。
• DataToken で直接サポートされていない型を格納したい場合。DataToken はオブジェクト参照やボックス化を通じてあらゆる型を格納できますが、理想的ではありません。参照を取り出して、目的の型にキャストする必要があります。

最終更新: 2026年6月17日