HN 日本語サマリー

← 一覧へ戻る
オープンソース

Capcom RE:Dox、ゲームエンジン向けのオープンソースシリアライゼーション/デシリアライゼーション

Capcom RE:Dox, open source serialization/deserialization for game engines (github.com)

31 pointsby vblanco7 コメント

要約

Capcomが開発したRE:Doxは、.NET向けの高性能トークンベース構造化データエンジンです。JSON、CBOR、MessagePack、TOML、XMLなど多様なフォーマットに対応し、単なるシリアライザではなく、構造化データをコンパクトなトークンDOM/IRに解析し、それを基に読み込み、編集、フォーマット変換、シリアライズ、デシリアライズ、自動並列デシリアライズを行います。これにより、従来のシリアライザが持つ速度、編集性、柔軟性のトレードオフを克服し、高速かつ低アロケーションなデータ処理を実現します。

全文翻訳

4. パフォーマンス

RE:Dox

[画像: ビルドとテスト] [画像: NuGet] [画像: ライセンス]

1. RE:Doxとは?

RE:Doxは、CAPCOMの次世代ゲームエンジン向け「REX」テクノロジーの中核コンポーネントとして開発された、.NET向けの高性能トークンベース構造化データエンジンです。

RE:Doxは単なるJSONシリアライザーではありません。構造化データをコンパクトで固定サイズのトークンDOM / IRに解析し、その構造インデックスを使用して読み取り、編集、フォーマット変換、シリアライゼーション、デシリアライゼーション、および自動並列デシリアライゼーションを行います。

JSON / JSON5 / CBOR / MessagePack / TOML / XML / HTML / CSV / INI / DOX
        ↓
コンパクトなトークンDOM / IR
        ↓
リーダー / ライター / シリアライザー / デシリアライザー
        ↓
.NETオブジェクト、JSON、CBOR、MessagePack、TOML、XML、HTML、DOX、...

同じトークン表現は、コンパクトな解析済みドキュメントモデルと、シリアライザー、コンバーター、サポートされているフォーマット間で共有される共通の構造レイヤーの両方として機能します。

2. なぜ気にかけるべきか?

RE:Doxは、通常は相反する3つの目標を組み合わせています。

  • テープDOMの解析速度 (System.Text.Json.JsonDocument)
  • ノードDOMの編集性 (System.Text.Json.Nodes.JsonNode)
  • Newtonsoft.Jsonの柔軟性(位置に依存しない$type、$id / $ref、順不同のコンストラクタバインディング)

得られるもの:

  • 高性能なシリアライゼーションとデシリアライゼーション — 以下のベンチマークデータセットでは、System.Text.Jsonと比較して、シーケンシャルデシリアライゼーションで最大約1.8倍、自動並列デシリアライゼーションで最大約2.8倍、シリアライゼーションで最大約1.6倍高速です。
  • テストされたワークロードでのアロケーション削減 — 例えば、canada.jsonのデシリアライゼーションでは、RE:Doxは約2.56 MBをアロケーションするのに対し、System.Text.Jsonは約8.53 MBをアロケーションします。JSON、JSON5、CBOR、MessagePack、INI、DOXはコアモデルに統合されています。TOML、XML、HTML、CSVは現在プレビューコンポーネントです。
  • フォーマットを横断する単一のコンバーターモデル — DataConverter<T>は、特定のワイヤーフォーマットではなく、フォーマットに依存しないDataReader / DataWriter抽象をターゲットとしています。
  • 変更可能なトークンDOM — 重いマネージドオブジェクトツリー全体を置き換えることなく、オブジェクトや配列を編集できます。
  • トリビアを保持するJSON5編集 — コメントやその他の保持されたトリビアは、ドキュメントの編集や再エンコード後も存続します。
  • System.Text.Json、Newtonsoft.Json、DataContractJsonSerializer用の互換性レイヤー。
  • Apache-2.0ライセンス。

3. 30秒の例

コアパッケージをインストールします。

dotnet add package CAPCOM.REDox

同じAPIサーフェスを通じて、シリアライズ、デシリアライズ、パース、編集を行います。

using REDox.Json;

var player = new Player
{
    Name = "Leon",
    Level = 42,
    Items = ["Handgun", "Green Herb"]
};

// シリアライズ / デシリアライズ
var json = JsonSerializer.Serialize(player);
var restored = JsonSerializer.Deserialize<Player>(json);

// トークンDOMにパースしてインプレースで編集
using var doc = JsonDocument.Parse(json);

var root = doc.RootElement.AsObject();
root["Name"] = "Claire";            // 置換
root.Add("Hp", 100);                // 追加
root.Remove("Level");               // 削除

var items = root["Items"].AsArray();
items.Add("First Aid Spray");       // 追加
items.Insert(0, "Knife");           // 挿入
items.RemoveAt(1);                  // インデックスで削除

var edited = doc.RootElement.ToJsonString();

public sealed class Player
{
    public string? Name { get; set; }
    public int Level { get; set; }
    public string[] Items { get; set; } = [];
}

環境: BenchmarkDotNet, .NET 10 (X64 RyuJIT x86-64-v3), AMD Ryzen Threadripper PRO 5975WX, Windows 11。

要約: System.Text.Json JsonSerializer との速度比較

[画像: System.Text.Jsonとの速度比較]

データセットデシリアライズデシリアライズ (並列)シリアライズ
canada.json1.68x2.84x1.06x
citm_catalog.json1.77x2.25x1.62x
twitter.json1.36x2.34x1.42x

これらの比率は以下のベンチマークデータセットを示しており、普遍的なパフォーマンス保証ではありません。

デシリアライズ: canada.json (数値中心、約2.2 MB)

[画像: canada.json デシリアライズ]

デシリアライズ: 平均 / アロケーション

[画像: citm_catalog.json デシリアライズ]

[画像: twitter.json デシリアライズ]

データセットRE:DoxRE:Dox (並列)System.Text.JsonSTJ (JsonTypeInfo)Utf8Json
canada.json9,113.0 us / 2,619.92 KB5,384.6 us / 2,685.11 KB15,303.1 us / 8,734.66 KB15,005.9 us / 8,734.59 KB15,864.0 us / 6,655.67 KB
citm_catalog.json2,280.5 us / 553.55 KB1,795.8 us / 631.87 KB4,041.1 us / 1,175.38 KB3,940.8 us / 1,175.38 KB2,605.5 us / 1,124.13 KB
twitter.json1,008.8 us / 504.91 KB587.4 us / 555.84 KB1,371.6 us / 557.09 KB1,401.6 us / 557.09 KB1,370.6 us / 530.05 KB
シリアライズ: 平均 / アロケーション

[画像: canada.json シリアライズ]

[画像: citm_catalog.json シリアライズ]

[画像: twitter.json シリアライズ]

データセットRE:DoxSystem.Text.JsonSTJ (JsonTypeInfo)Utf8Json
canada.json13,615.5 us / 2,041.41 KB14,388.3 us / 2,042.85 KB14,433.1 us / 2,042.85 KB11,714.2 us / 6,042.21 KB
citm_catalog.json668.7 us / 494.41 KB1,085.4 us / 494.85 KB1,073.8 us / 494.87 KB707.3 us / 1,389.64 KB
twitter.json557.3 us / 465.15 KB789.0 us / 467.95 KB800.3 us / 467.91 KB709.4 us / 1,361.37 KB

再現するには:

dotnet run -c Release --project benchmarks/REDox.Json.Benchmarks

ベンチマーク結果は、データの形状、ターゲット型、ランタイム、CPU、およびシリアライザーオプションによって異なります。常に独自のワークロードでベンチマークを行ってください。

5. アーキテクチャ

コアとなる64ビットデュアルモードトークン

すべての値は、固定サイズの64ビットトークンによって記述されます。拡張ビットが、ペイロードの解釈方法を選択します。

拡張ビット = 0 → ペイロードの解釈はドキュメント/フォーマットレイヤーに委任される
                      (ソースバック、フォーマット固有のペイロード; 多数のフォーマット、1つのトークン形状)

拡張ビット = 1 → ペイロードの解釈はRE:Doxによって固定され、制御トークンにより
                      フォーマットに依存しない編集 (挿入 / 削除 / 置換) が可能になる

これにより、単一のトークン構造が、フォーマットデータのソースバックビューと、シリアライザー、コンバーター、サポートされているフォーマット間で共有されるRE:Dox所有の編集可能なDOMの両方を表すことができます。ドキュメント/フォーマットレイヤーが元のペイロードを保持できる場合、変更されていない値は、早期にマテリアライズされることなくソーススライスを再利用し続けることができます。

トークンは、null、ブール値、整数、浮動小数点数、文字列、バイナリ、タイムスタンプ、大きな数値、配列、マップ/オブジェクト、トリビア(コメント/空白)、またはフォーマット固有の拡張データを表すことができます。インラインデータ、ソースオフセット/長さ、コンテナカウント、リンク情報、または拡張IDを格納できます。

非対称な読み書き設計

読み取りと書き込みでは異なる情報要件があるため、RE:Doxは各方向で異なるパスを使用します。

シリアライズ    : DataWriter、ワンパス、出力バッファに直接書き込み
               (情報が既知 → 先読みなし、中間DOMなし)

デシリアライズ  : トークンDOM上のDataReader、トークンIDによるランダムアクセス
               (情報が未知 → 先読み、順不同、コンテキストルックアップ)

書き込みパスでは値は既にわかっているため、RE:Doxはバルク(WriteValues)およびフューズドプロパティ(WriteProperty*)ヘルパーを使用して直接バッファに書き込みます。中間オブジェクトツリーは構築されません。

読み取りパスでは構造が不明なため、RE:DoxはまずコンパクトなトークンDOMを構築します。構造が完全にアドレス可能になった後、RE:Doxは以下のことが可能になります。

  • 配列とコレクションの事前サイズ設定。
  • マテリアライズ前に各要素のトークンIDを知る。
  • $typeがオブジェクトのどこに現れても解決する。
  • コンストラクタ引数を順不同で収集し、一度だけバインドする(レコードとプライマリコンストラクタ)。
  • ドキュメント全体のコンテキストを使用して$id / $refサイクルを解決する。
  • シーケンシャルまたはパラレルデシリアライゼーションを自動的に選択する。
  • 要求されたときにのみ文字列と数値をデコードする。
  • 変更されていない値に対して生のソーススライスを再利用する。
遅延デコードとオンデマンドマテリアライゼーション

トークンは、元のソースバッファへのオフセットと長さを格納できます。文字列、数値、タイムスタンプ、バイナリ値は、要求されたときにのみデコードされます。要素はドキュメントとトークンIDに対する軽量なハンドルであり、オブジェクトと配列ビューは必要になったときにのみマテリアライズされます。

変更可能なテープDOM

テープDOMは、その論理構造がフラットなトークンシーケンスによって表されるため、通常は読み取り専用です。RE:Doxはコンテナビューで間接参照を追加します。DArray、DObject、DMapは再リンク可能な値スロットを保持し、フリーリストは空になったトークンスロットを再利用し、拡張/制御トークンは編集状態を運びます。

これにより、シーケンシャルなトークン表現のキャッシュフレンドリーな特性を維持しつつ、ドキュメント全体を編集ごとに再構築することなく、挿入、削除、置換などのノードライクな操作を提供できます。

ユニファイドコンバーター

コンバーター(DataConverter<T>)は、特定のフォーマット実装ではなく、フォーマットに依存しないDataReader / DataWriter抽象に対して記述されます。

概念的には:

                 DataConverter<T>
                        │
               DataReader / Writer
                /       |        \
             JSON      CBOR    MessagePack   ...

これにより、コンバーターロジックを共通リーダー/ライターモデルに参加するフォーマット間で共有できます。RE:Doxは、各タイプフォーマットペアの同等の変換ロジックを重複させる代わりに、それらのフォーマット間で単一のコンバーター実装を再利用できます。これは、将来のAOT / ソースジェネレーターサポートの基盤も提供します。

6. フォーマット/パッケージ

NuGetパッケージIDはCAPCOM.REDox.*プレフィックスを使用します。C#名前空間はREDox.*を使用します。

パッケージステータス説明
CAPCOM.REDox公開コア + JSON + JSON5 + DOX + 共通シリアライザーインフラ
CAPCOM.REDox.Cbor公開CBORパーサー/ライター統合
CAPCOM.REDox.MessagePack公開MessagePackパーサー/ライター統合
CAPCOM.REDox.Dynamic公開トークンDOMへのdynamicアクセス
CAPCOM.REDox.Serialization.SystemTextJsonプレビューSystem.Text.Json互換性レイヤー
CAPCOM.REDox.Serialization.NewtonsoftJsonプレビューNewtonsoft.Json互換性レイヤー
CAPCOM.REDox.Serialization.DataContractJson公開DataContractJsonSerializer互換性レイヤー
CAPCOM.REDox.Tomlプレビューコメント対応トークンDOM統合によるTOMLパーサー/ライター
CAPCOM.REDox.XmlプレビューXML構造パーサー/ライター
CAPCOM.REDox.Htmlプレビュー実用的なHTML構造パーサー/ライター
CAPCOM.REDox.Ini公開INIサポート
CAPCOM.REDox.CsvプレビューCSVサポート

プレビューパッケージは0.1.0-preview.1のようなNuGetのプレリリースバージョンを使用します。パッケージ名自体に-previewは含まれません。プレビューコンポーネントは、安定リリース前にAPIの動作を変更する可能性があります。

公開パッケージをインストールするには:

dotnet add package CAPCOM.REDox
dotnet add package CAPCOM.REDox.Cbor
dotnet add package CAPCOM.REDox.MessagePack
dotnet add package CAPCOM.REDox.Dynamic
dotnet add package CAPCOM.REDox.Serialization.DataContractJson
dotnet add package CAPCOM.REDox.Ini

プレビューパッケージを--prerelease付きでインストールするには:

dotnet add package CAPCOM.REDox.Serialization.SystemTextJson --prerelease
dotnet add package CAPCOM.REDox.Serialization.NewtonsoftJson --prerelease
dotnet add package CAPCOM.REDox.Toml --prerelease
dotnet add package CAPCOM.REDox.Xml --prerelease
dotnet add package CAPCOM.REDox.Html --prerelease
dotnet add package CAPCOM.REDox.Csv --prerelease
CBOR
using REDox.Cbor;

byte[] cbor = CborSerializer.Serialize(new Player
{
    Name = "Jill",
    Level = 30,
    Items = ["Lockpick"]
});

var player = CborSerializer.Deserialize<Player>(cbor);

// トークンDOMにパースして再エンコード
using var doc = CborDocument.Parse(cbor);
byte[] encoded = CborDocument.Encode(doc.RootElement);
MessagePack
using REDox.MessagePack;

byte[] msgpack = MessagePackSerializer.Serialize(new Player
{
    Name = "Chris",
    Level = 35,
    Items = ["Knife", "First Aid Spray"]
});

var player = MessagePackSerializer.Deserialize<Player>(msgpack);

using var doc = MessagePackDocument.Parse(msgpack);
byte[] encoded = MessagePackDocument.Encode(doc.RootElement);
Dynamic
using REDox;
using REDox.Dynamic;
using REDox.Json;

using var doc = JsonDocument.Parse(@"{ "name":"Leon","level":40,"stats":{"alive":true}} ");

var player = doc.RootElement.AsDynamic()!;
var name = (string)player.name;
var level = (int)player.level;
var alive = (bool)player["stats"]["alive"];

// 新しいオブジェクトを動的に構築
var obj = new DObject().AsDynamic();
obj.Name = "Ada";
obj.Items = new[] { "Hookshot" };

string json = JsonSerializer.Serialize(obj); // {"Name":"Ada","Items":["Hookshot"]}
クロスフォーマット変換

共通トークンIRを共有するフォーマットは、ドキュメントモデルを通じて変換できます。

using REDox.Cbor;
using REDox.Json;

using var doc = JsonDocument.Parse(json);
byte[] cbor = CborDocument.Encode(doc.RootElement);
JSON5  → トークンIR → JSON
JSON   → トークンIR → CBOR
CBOR   → トークンIR → MessagePack
TOML   → トークンIR → JSON
XML    → トークンIR → JSONライクな構造表現

ネイティブデータモデルが異なるフォーマットは、損失のないセマンティックラウンドトリップではなく、構造的な投影を使用する場合があります。

7. 高度な機能

自動並列デシリアライゼーション

デシリアライザーは、オブジェクトをマテリアライズする前に、各配列の要素数とトークン範囲を検査します。配列が大きい場合、要素トークンIDが収集され、各要素が並列にその対応するインデックスにデシリアライズされます。小さい配列は、並列スケジューリングのオーバーヘッドを回避するためにシーケンシャルなままです。

using REDox;
using REDox.Json;
using REDox.Serialization;

var settings = new DoxSerializerSettings
{
    ParallelOptions = new ParallelDeserializeOptions
    {
        ParallelDeserializeEnabled = true,
        MinimumNumberOfElements = 1024,
        MinimumNumberOfTokens = 4096
    }
};

var players = JsonSerializer.Deserialize<Player[]>(json, settings);
コメントとトリビアを保持するJSON5
using REDox.Json;

var json5 = @"{ // Player name
  name: 'Leon',

  // Inventory
  items: [
    'Handgun',
    'Green Herb',
  ],
}";

using var doc = Json5Document.Parse(json5, options: new Json5DocumentOptions
{
    PreserveTrivia = true,
    EnableValueValidation = true
});

var root = doc.RootElement.AsObject();
root["name"] = "Claire";

var output = Json5Document.EncodeToString(doc.RootElement, new Json5WriteOptions
{
    PreserveTrivia = true
});
NDJSON / JSONシーケンスの非同期ストリーミング

JsonSequenceは、入力全体をメモリにロードすることなく、NDJSON / JSON Lines、または大きなトップレベル配列のJSON値のストリームを一度に1つの値として非同期に読み取ります。NDJSONの場合、JsonDocumentOptionsでUseNewlineDelimitedFormatを有効にします。

using REDox.Json;

var options = new JsonDocumentOptions { UseNewlineDelimitedFormat = true };

await using var stream = File.OpenRead("players.ndjson");

// 各行を.NETオブジェクトにデシリアライズ
await foreach (var player in JsonSequence.DeserializeAsync<Player>(stream, options: options, cancellationToken: ct))
{
    Console.WriteLine(player?.Name);
}

トークンDOMを直接操作するには、ParseAsyncを使用します。UseNewlineDelimitedFormatなしでは、トップレベルのJSON配列が要素ごとにストリーミングされます。生成されるDElementは再利用可能なドキュメントによってバックされており、次のイテレーションまでしか有効ではありません。保持する必要がある場合は、Clone()を呼び出すか、To<T>()で変換してください。

using REDox;
using REDox.Json;

await using var stream = File.OpenRead("events.json"); // [ { "level": "info", ... }, { "level": "error", ... }, ... ]

var errors = new List<DElement>();

await foreach (var element in JsonSequence.ParseAsync(stream, cancellationToken: ct))
{
    if (element.TryGetProperty("level", out var level) && level.GetString() == "error")
    {
        errors.Add(element.Clone());
    }
}
DOXフォーマットとディープクローン

DOXは、メモリ内のトークン配列に密接にミラーリングするように設計されたバイナリレイアウトです。DOXからドキュメントを構築するには、構造的な再構築はほとんど必要ありません。これにより、DOXはシリアライゼーションベースのディープクローンにも適しています。結果は、共有読み取り専用ビューではなく、独立した編集可能なコピーになります。

using REDox;

byte[] dox = DoxSerializer.Serialize(player);
var clone = DoxSerializer.Deserialize<Player>(dox);
互換性レイヤー

互換性パッケージにより、既存のシリアライザーオプションをRE:Doxに適合させることができます。

System.Text.Json
using REDox.Serialization.SystemTextJson;

var stjSettings = new SystemTextJsonSerializerSettings(new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase
});
Newtonsoft.Json
using Newtonsoft.Json;
using REDox.Serialization.NewtonsoftJson;

var nsjSettings = new NewtonsoftJsonSerializerSettings(new JsonSerializerSettings
{
    NullValueHandling = NullValueHandling.Ignore
});
DataContractJsonSerializer
using REDox.Serialization.DataContractJson;

var dcjSettings = new DataContractJsonSerializerSettings(
    new System.Runtime.Serialization.Json.DataContractJsonSerializerSettings());

セキュリティ

DOXは信頼できる入力のみ

DoxDocumentで扱われるDOXフォーマットは、メモリ内のトークン配列をミラーリングするバイナリレイアウトです。高速化のために設計されており、敵対的なデータに対する防御的なパーサーを意図していません。信頼できるソースからのDOXデータのみを受け入れてください。信頼できない、または認証されていないオリジン(ネットワーククライアント、ユーザーアップロードなど)から受信したDOXをデシリアライズしないでください。信頼できない入力には、JSONのようなテキストフォーマットを使用してください。

スレッドセーフティ
  • DElement: APIは読み取り専用であるため、DElementは複数のスレッドから同時に参照できます。
  • DValue / DObject / DMap / DArray: これらは同時に複数のスレッドから使用してはなりません。値の取得やGetPathの呼び出しなど、読み取り専用に見える操作でも、内部状態が変更される可能性があります。外部でアクセスを同期するか、各スレッドに独自のインスタンスを提供してください(例: ディープクローン経由)。

要件

  • .NET 10 以降。

ビルド方法

1. サブモジュール付きでクローン

テストおよびベンチマークデータ(simdjson-data、JSONTestSuite、json5-tests、toml-test)は、external/の下にgitサブモジュールとして格納されています。

git clone --recurse-submodules https://github.com/CAPCOM-TD-OSS/REDox.git
cd REDox

サブモジュールなしで既にクローンした場合:

git submodule update --init --recursive
2. ビルド
dotnet build REDox.slnx -c Release
3. テストの実行
dotnet test REDox.slnx -c Release
4. ベンチマークの実行

ベンチマークはBenchmarkDotNetを使用し、Release構成で実行する必要があります。

dotnet run -c Release --project benchmarks/REDox.Json.Benchmarks

サードパーティコンポーネント

RE:Doxライブラリパッケージはサードパーティコードをバンドルしていません。以下のサードパーティプロジェクトがテストとベンチマークで参照されています。それぞれ独自のライセンスの下で配布されています。

テスト
リポジトリ使用目的ライセンス
simdjson/simdjson-dataベンチマークデータセット(canada.json、citm_catalog.json、twitter.jsonなど)リポジトリを参照
nst/JSONTestSuiteJSON準拠テストMIT
json5/json5-testsJSON5準拠テストMIT
toml-lang/toml-testTOML準拠テストMIT

ライセンス

RE:DoxはApache License 2.0の下でリリースされています。

ステータス

RE:Doxは活発に開発中です。API、パッケージ境界、およびプレビューフォーマットのサポートは、最初の安定した公開リリース前に変更される可能性があります。

RE:Doxは、CAPCOMの次世代ゲームエンジン向け「REX」テクノロジーの一部として開発されています。