frdt 0.2.3

Edit and inspect Resonite FrDT (.brson) documents without expanding them to JSON
Documentation

frdt

Resonite の .brson(中身は FrDT 形式)を、JSON へ展開せずに読み、編集し、書き戻す Rust クレートです。

Read and edit Resonite .brson (FrDT) files without expanding them into JSON.

できること

  • .brson を開き、スロット、コンポーネント、Types、Assets、FeatureFlags、VersionNumber を読む。
  • 1回のストリーム読みで、スロット数、コンポーネント数、Dynamic Variable を数える。文書を展開しないので、大きなファイルでも軽く済みます。
  • スロットとコンポーネントを足す。フィールドの値や参照を書き換える。同じ文書の中で親を変える。スロットを外す。
  • 別の文書のスロット部分木を、コンポーネントとフィールドごと写す。id はすべて振り直し、参照は同じ相手を指したままにします。写した部分木が参照するアセットだけを連れていきます。
  • Types と TypeVersions を、残っているコンポーネントから作り直す。
  • 部分木を、そのスロットをルートにした新しいファイルとして切り出す。
  • Resonite で保存した雛形から、コンポーネントを 1 つ写す。フィールドと型の版は雛形のとおりになります。
  • 書き出す前に id を振り直す。同じ中身なら、同じバイト列になります。
  • 2つの文書を構造で比べる。id は比べず、参照は指している先で比べます。
  • Resonite が読み込める .brson を書き出す。

考え方

  • JSON を通さない。 編集の実体は、展開した BSON 1枚と、スロットの位置を指す索引です。全体をオブジェクトの木にはしません。変えていない値はバイト列のままコピーします。
  • 知らないものを落とさない。 コンポーネントごとのスキーマは持たず、触ったフィールドだけを読み書きします。未知のコンポーネントやフィールドは、そのまま残ります。
  • Resonite の形で書く。 新しく書く値は、Resonite が保存するのと同じ形にします({ID, Data} で包んだフィールド、int64、float3 / floatQ は double の配列)。Infinity、-Infinity、NaN も、文字列にせず IEEE のビットのまま残します。

使い方

[dependencies]
frdt = "0.2"

読む

let bytes = std::fs::read("item.brson")?;

// 展開せずに数える
let summary = frdt::summarize(&bytes)?;
println!("{} slots, {} components", summary.slot_count, summary.component_count);

// 開いて辿る
let doc = frdt::Document::open(&bytes)?;
let root = doc.root();
println!("{} ({})", root.name()?, doc.version_number()?);
for child in root.children()? {
    for (i, c) in child.components()?.iter().enumerate() {
        println!("{} #{i}: {}", child.name()?, c.type_name);
    }
}

編集して書き出す

use frdt::{Document, Value};

let mut doc = Document::open(&bytes)?;
let root = doc.root();
let panel = doc.add_slot(&root, "Panel")?;
let (i, _) = doc.add_component(
    &panel,
    "[FrooxEngine]FrooxEngine.DynamicValueVariable<string>",
    None,
    &[
        ("VariableName", Some(Value::String("App.Title".into()))),
        ("Value", Some(Value::String("Hello".into()))),
    ],
)?;
panel.set_component_value(i, "Value", Some(Value::String("Hello, Resonite".into())))?;
panel.set("Name", Value::String("TitlePanel".into()))?;

let mut out = Vec::new();
doc.write_brson(&mut out)?;

別のファイルの部分木を、新しい木にまとめる

let part = frdt::Document::open(&part_bytes)?;
let source = part.slot_by_id(&slot_id)?;

let mut out = frdt::Document::empty("Combined", &part.version_number()?, part.feature_flags()?)?;
let import = out.import(&out.root(), &[source])?;
// 写した先の id は import.new_id(元の id) で引ける
out.rebuild_types()?;

部分木を、新しいファイルとして切り出す

let saved = frdt::Document::open(&saved_bytes)?;
let unit = saved.root().children()?[0].clone();
let part = saved.extract(&unit, frdt::UnresolvedPolicy::Error)?;
// part.document() のルートは unit の写し。使うアセットだけが残る

雛形からコンポーネントを写す

let templates = frdt::Document::open(&template_bytes)?;
let source = templates.root().children()?[0].clone();
let added = out.copy_component(&out.root(), &source, 0, &frdt::ImportOptions::default())?;
out.root().set_component_value(added.index(), "VariableName", Some(frdt::Value::String("Static.Main".into())))?;

まとめるときの選択肢と、書き出す前の仕上げ

use frdt::{ImportOptions, UnresolvedPolicy, VersionPolicy};

let options = ImportOptions {
    unresolved: UnresolvedPolicy::Error, // 写さなかったものを指す参照があれば失敗
    versions: VersionPolicy::Newer,      // VersionNumber などが違えば新しい方を取る
};
let import = out.import_with(&out.root(), &[source], &options)?;
for m in import.mismatches() {
    eprintln!("版が食い違いました: {m:?}");
}

out.renumber_ids(0)?; // 同じ中身なら同じバイト列になる
for d in frdt::compare(&out, &frdt::Document::open(&expected_bytes)?)? {
    println!("{} {} {:?} {:?}", d.path, d.item, d.left, d.right);
}

API の詳細は docs.rs にあります。

対応している範囲

  • 圧縮は Brotli(FrDT の圧縮種別 0x03)です。LZ4 と LZMA は読みません。
  • BSON の日時型(0x09)は、まだ扱えません。
  • 参照かどうかは、文字列が文書内の id と一致するかで決めます。コンポーネントのスキーマは見ません。

Node.js から

同じ操作を、npm パッケージ @frdt/frdt で Node.js から呼べます。TypeScript の型付きで、Windows x64、Linux x64、macOS arm64 ではネイティブ版、それ以外では同梱の WebAssembly 版が動きます。

npm install @frdt/frdt
import { Document } from '@frdt/frdt'

const doc = Document.open(bytes)
const panel = doc.addSlot(doc.root(), 'Panel')
const out = doc.writeBrson()

使われているところ

もともとは、Resonite 向けの UI フレームワーク MirageX と、アイテム共有サービス UniPocket のために作りました。MirageX は、部品ごとの .brson を1本のクライアントの .brson にまとめる処理に、このクレートの編集と写しを使います。UniPocket は、アイテムの .brson の検証、加工、集計に使う予定です。

生成AI

このクレートのコードと文書は、生成AIの支援を受けて作成しています。

ライセンス

MIT License