VRC JSON

Data Dictionaries および Data Lists には、JSON との相互変換を行う関数が含まれています。Data List は JSON 配列に相当し、JSON オブジェクトは文字列キーを持つ Data Dictionary に相当します。

JSON スキーマ自体の詳細については、JSON ドキュメントを参照してください。このページの内容はすべて、この特定の JSON スキーマ実装に関連しています。

JSON 関数

• Udon Graph ではすべてのクラス名の先頭から "VRC" が削除されているため、これらの関数を探すには "Json" で検索する必要があることに注意してください。
• UdonSharp では、これらのクラスは VRC.SDK3.Data 名前空間にあります。

サポートされている型と値

JSON は小さく、シンプルで厳格な仕様です。DataList や DataDictionary はより幅広い構成をサポートできるため、データコンテナから JSON に変換する際にいくつかの制限に直面する可能性があります。これらの制限を理解し、JSON の使用を意図している状況では該当する構成を使用しないようにしてください。

JSON は Object Reference データトークンをサポートしていません。 JSON へのシリアライズを試みる際、データコンテナ内にオブジェクト参照が含まれていると、TrySerializeToJson は false を返し、DataError.TypeUnsupported を返します。

JSONは文字列キーの辞書のみをサポートしています。DataDictionariesに文字列以外のキーが含まれている状態でJSONへのシリアライズを試みると、TrySerializeToJson は DataError.TypeUnsupported を伴って false を返します。

JSONはNaNやInfinityをサポートしていません。NaNやInfinityを含むfloatやdoubleが存在する場合、TrySerializeToJson は DataError.ValueUnsupported を伴って false を返します。

JSONはルートとしてDictionaryまたはList以外をサポートしていません。子要素を持たない単純な値のDataTokenを使用した場合、TrySerializeToJson は DataError.TypeUnsupported を伴って false を返します。

JSONは単一の数値型のみをサポートしています。 すべての異なる数値型を区別しません。その結果、JSONからデシリアライズすると、すべての数値は Double 形式で保存されます。int、byte、float といった他の数値型を含むData Tokenがある場合、それらはJSONにシリアライズ可能ですが、そのJSONを再びData Containerにデシリアライズすると、それらは Double に変換されてしまいます。

JSONからのデシリアライズ

VRCJson.TryDeserializeFromJson は、JsonからData Containerに変換する際に使用する関数です。if や branch の条件として使用することを推奨します。これにより、失敗した場合と成功した場合の処理をそれぞれ選択できるようになります。

TryDeserializeFromJson が true を返す場合、Json文字列はDataListまたはDataDictionaryへの変換に成功したことを意味します。その後、結果に対して型チェックを行い、各ケースで何を行うかを決定してください。

これが false を返す場合、提供した文字列は有効な JSON ではありません。受け取った DataToken は DataError となり、それに対して DataToken.ToString を実行すると、エラー内容と何が問題だったのかを説明する詳細な文字列の両方が得られます。

パフォーマンス上の理由から、VRCJSON はすべてを即座にパースするわけではありません。その代わり、まずは JSON のトップレベルのみをパースします。トップレベルが有効であっても、ネストされた構造の内部に無効な JSON が含まれている場合、最初の TryDeserializeFromJson が true を返す可能性があります。その後、TryGetValue を使用して無効な箇所から値を取得しようとすると、false が返され、DataError.UnableToParse が発生します。

if (VRCJson.TryDeserializeFromJson(json, out DataToken result))
{
    // Deserialization succeeded! Let's figure out what we've got.
    if (result.TokenType == TokenType.DataDictionary)
    {
        Debug.Log($"Successfully deserialized as a dictionary with {result.DataDictionary.Count} items.");
    }
    else if (result.TokenType == TokenType.DataList)
    {
        Debug.Log($"Successfully deserialized as a list with {result.DataList.Count} items.");
    }
    else 
    {
        // This should not be possible. If TryDeserializeFromJson returns true, this it *must* be either a dictionary or a list.
    }
} else {
    // Deserialization failed. Let's see what the error was.
    Debug.Log($"Failed to Deserialize json {json} - {result.ToString()}");
}

JSON へのシリアライズ

VRCJson.TrySerializeToJson は、Data コンテナから JSON に変換する際に使用すべき関数です。失敗した場合と成功した場合の処理を分岐させるため、if や branch の条件式として使用することを推奨します。

TrySerializeToJson が true を返す場合、それは DataList または DataDictionary が Json 文字列に正常に変換されたことを意味しており、result トークンから安全に文字列を取り出すことができます。

if (VRCJson.TrySerializeToJson(dictionary, JsonExportType.Beautify, out DataToken json))
{
    // Successfully serialized! We can immediately get the string out of the token and do something with it.
    Debug.Log($"Successfully serialized to json: {json.String}");
} 
else 
{
    // Failed to serialize for some reason, running ToString on the result should tell us why.
    Debug.Log(json.ToString());
}

JsonExportType

Json にシリアライズする際、任意の JsonExportType を選択できます。人間が読みやすい形式にしたい場合は Beautify が適しており、ネットワーク送信用にコンパクトな形式にしたい場合は Minify が適しています。

• Beautify: 各要素を新しい行に展開し、深さごとにタブを 1 つ追加します。
• Minify: すべてを 1 行にまとめ、空白を最小限に抑えます。