Library Overview

Think of a BinaryFormatter file as a saved object graph: objects contain fields, fields can contain numbers or strings, and some fields point to other objects. dnbflib gives you two ways to work with that graph.

Which Tool to Use

Start with the workflow that matches how you want to edit the file.

Installation

dnbflib requires Python 3.11 or newer. It depends on pydatastreams, which installs the Python module named datastream.

PowerShell

When running from a checkout without installing the package, point Python at the local src folder first.

$env:PYTHONPATH = "src"
python -c "from dnbflib import DNBFRecordStore; print(DNBFRecordStore)"

Package Install

python -m pip install -e .

PyPI

pip install dnbflib

Core Concepts

Records

A BinaryFormatter file is not one big object. It is a list of smaller chunks called records. One record might say "this is a string," another might say "this object has these fields," and another might say "this field points to object 42." dnbflib scans those records in order.

Object IDs and References

BinaryFormatter often gives objects numeric IDs. A field may not contain the object directly; it may contain a reference to an ID instead. When you call member.deref(), dnbflib follows that reference and gives you the target object.

Raw Bytes

Every record has original bytes in the source file. dnbflib keeps those bytes around. If a record is not edited, those exact bytes can be written back out unchanged.

Decoded Views

A decoded view is dnbflib's best human-readable explanation of a record. For example, a class record might decode into a class name and a list of fields. If a decoded field is marked editable, dnbflib knows how to rebuild that part safely.

Quickstart

This script checks the safest promise first: export a binary, rebuild it without edits, and verify that the rebuilt bytes match the input exactly.

from pathlib import Path

from dnbflib import export_dnbf_to_yaml, rebuild_yaml_export

input_path = Path("src/test.bin")
export_dir = Path("parsed_yaml")

export_dnbf_to_yaml(input_path, export_dir)
rebuilt = rebuild_yaml_export(export_dir)

print("roundtrip:", rebuilt == input_path.read_bytes())

If this prints roundtrip: True, the export folder can rebuild the original file exactly. After that, make one small edit at a time and rebuild again.

Command Line

The included example script does the same thing from PowerShell or a terminal.

python examples/export_to_yaml.py save.dat save_export --verify

Record Database

DNBFRecordStore is a SQLite-backed table of records. You usually do not need it for simple edits, but it is useful when you want to inspect a file by offsets and IDs.

Query Records

from dnbflib import DNBFRecordStore

store = DNBFRecordStore("parsed.dnbf.sqlite3")

print("source sha256:", store.get_metadata("source_sha256"))

for record in store.iter_records():
    print(record.sequence, record.record_type.name, record.offset, record.size)

Find an Object by ID

This is low-level. For normal object navigation, prefer DNBFDocument.

stored = store.get_by_object_id(42)
print(stored.record_type.name)
print(stored.raw.hex())

Editing Tutorial

There are two editing styles. Use DNBFDocument when you know the object and field names. Use YAML export when you want to inspect records by hand before deciding what to change.

Edit Through Object Traversal

This example finds one Life object, follows its Finances field, changes BankBalance, and writes a new file.

from pathlib import Path

from dnbflib import DNBFDocument

input_path = Path("save.dat")
output_path = Path("edited.bin")

with DNBFDocument.open(input_path) as doc:
    life = doc.one(class_name="Life", where=lambda obj: obj.member("Name").value == "Alex")
    finances = life.member("Finances").deref()
    finances.member("BankBalance").set(123456)
    doc.write(output_path)

Edit Through YAML

In an exported record file, raw.bin is the original record bytes and record.yaml describes how to rebuild that record. If a decoded value is editable, set rebuild to decoded and change the decoded field.

In a Life record, the member might look like this:

{
  "name": "<Finances>k__BackingField",
  "binary_type": "Class",
  "editable": true,
  "record_type": "MemberReference",
  "ref_id": 42,
  "ref_path": "records/objects/Game.Finances/000128_ClassWithMembersAndTypes/record.yaml"
}

That means the field does not contain the finances data here. It points to object 42. Open the referenced record.yaml and edit the value fields there:

{
  "record_type": "ClassWithMembersAndTypes",
  "decoded": {
    "type": "ClassWithMembersAndTypes",
    "fields": {
      "class_name": "Game.Finances",
      "members": [
        {
          "name": "<BankBalance>k__BackingField",
          "binary_type": "Primitive",
          "editable": true,
          "primitive_type": "Int64",
          "value": 123456,
          "value_offset": 184,
          "value_size": 8
        }
      ]
    }
  }
}

Can I Insert New Objects?

Not safely yet. dnbflib currently supports editing supported values inside records that already exist. It does not currently provide a high-level API for adding a brand-new object to the BinaryFormatter graph.

For now, use dnbflib to change existing objects and existing fields. If you need insertion support, it should be implemented as a dedicated graph-editing feature that allocates IDs, writes the required records, and updates every referencing record together.

Scalar Number Example

This changes one standalone primitive integer record from its old value to 250.

{
  "record_type": "MemberPrimitiveTyped",
  "rebuild": "decoded",
  "decoded": {
    "editable": true,
    "type": "MemberPrimitiveTyped",
    "fields": {
      "primitive_type": "Int32",
      "value": 250
    }
  }
}

For primitive arrays, edit the numbers in decoded.fields.values.

{
  "record_type": "ArraySinglePrimitive",
  "rebuild": "decoded",
  "decoded": {
    "editable": true,
    "type": "ArraySinglePrimitive",
    "fields": {
      "object_id": 55,
      "primitive_type": "Int16",
      "values": [1, 9, 3]
    }
  }
}

For class records, primitive fields appear as member entries. The value_offset and value_size fields tell dnbflib exactly where the old value lives inside the original raw record, so it can patch that value while preserving the rest.

{
  "record_type": "ClassWithMembersAndTypes",
  "rebuild": "decoded",
  "decoded": {
    "type": "ClassWithMembersAndTypes",
    "fields": {
      "class_name": "Person",
      "members": [
        {
          "name": "Age",
          "binary_type": "Primitive",
          "editable": true,
          "primitive_type": "Int32",
          "value": 31,
          "value_offset": 42,
          "value_size": 4
        }
      ]
    }
  }
}

API Reference

DNBFDocument

Use this API for Python-only object traversal and editing.

from dnbflib import DNBFDocument

with DNBFDocument.open("save.dat") as doc:
    life = doc.one(class_name="Life", where=lambda obj: obj.member("Name").value == "Alex")
    finances = life.member("Finances").deref()
    finances.member("BankBalance").set(123456)
    doc.write("edited.dat")

DNBFRecordStore

Use this API when you want the low-level record table.

DNBFWriter

Use this API when you already have raw records or stored records and want bytes back.

Top-Level Exports

Troubleshooting

ModuleNotFoundError: No module named 'datastream'

Install pydatastreams or activate the environment where it is already installed. The package name is pydatastreams, but the Python import name is datastream.

The rebuilt file does not match the input

First test a no-edit YAML round trip with rebuild_yaml_export(...). If an untouched export does not rebuild exactly, stop and inspect the record mentioned by the error before editing.

A specific record type fails while exporting

The error should include a record type or offset. Use that to inspect the exported record.yaml and raw.bin. The scanner or decoded rebuild code may need support for that record shape.

References point to the old value

References usually point to object IDs, not byte offsets. If you edit a value while keeping the same object ID, references should still point to it. Be careful when changing object IDs or adding new objects.