Patch and Diff Workflow

Charon can compute the difference between two game data files and represent it as a reusable patch. That patch can later be applied to any compatible target file. This enables branching workflows, incremental DLC updates, audit trails, and automated data merging in CI/CD pipelines.

Overview

Two commands form the workflow:

DATA CREATEPATCH

Compares two game data sources and produces a patch file describing every addition, modification, and deletion between them.

DATA APPLYPATCH

Applies a patch file to a target game data file.

dataBase1 (before)  ─┐
                      ├─ CREATEPATCH ─→ patch.json
dataBase2 (after)   ─┘

target.json  ──┬── APPLYPATCH ──→ patched target.json
patch.json   ──┘

Common use cases:

  • Feature branch merge - keep a stable baseline; apply a feature branch as a patch.

  • DLC / live updates - ship incremental changes without distributing the full file.

  • Code-review diff - generate a human-readable changelog of data edits for review.

  • Automated reconciliation - merge concurrent edits from multiple environments in CI.

Creating a Patch

dnx dotnet-charon -- DATA CREATEPATCH \
    --dataBase1 gamedata_before.json \
    --dataBase2 gamedata_after.json \
    --output    changes.patch.json \
    --outputFormat json

  • --dataBase1 is the baseline (before).

  • --dataBase2 is the modified version (after).

  • Both can be local files or remote server URLs. A single --credentials value is used for both when they are remote.

Tip

When both sources are remote and the dataset is large, download them first with DATA BACKUP and run CREATEPATCH on the local copies to avoid network round-trips.

Patch file format

The patch file follows the standard game data JSON format.:

{
  "Collections": {
    "Item": {
      "IronSword": { Id: "IronSword", "Name": "Iron Sword", "Damage": 20 }, // addition
      "OldSword": { "Damage": 18 }, // modification
      "RustySword": null // deletion
    }
  }
}

Applying a Patch

dnx dotnet-charon -- DATA APPLYPATCH \
    --dataBase target.json \
    --input    changes.patch.json \
    --inputFormat json

Validation on apply

DATA APPLYPATCH validates the target after applying the patch with repairs only - repair, deduplicateIds, repairRequiredWithDefaults and resolveConflictingUnions - and no integrity checks. The command takes no --validationOptions parameter, so check the result separately whenever the patch is not fully trusted:

dnx dotnet-charon -- DATA VALIDATE \
    --dataBase target.json \
    --validationOptions checkRequirements checkFormat checkUniqueness \
                        checkReferences checkSpecification checkConstraints \
    --output err

End-to-End Example: Feature Branch Merge

# 1. Backup the stable main branch
dnx dotnet-charon -- DATA BACKUP \
    --dataBase "https://charon.live/view/data/MyGame/main/" \
    --output main.json --outputFormat json --credentials "$CHARON_KEY"

# 2. Backup the feature branch
dnx dotnet-charon -- DATA BACKUP \
    --dataBase "https://charon.live/view/data/MyGame/feature-loot/" \
    --output feature.json --outputFormat json --credentials "$CHARON_KEY"

# 3. Compute the diff
dnx dotnet-charon -- DATA CREATEPATCH \
    --dataBase1 main.json \
    --dataBase2 feature.json \
    --output loot_changes.patch.json

# 4. (Optional) review the patch in a text editor or commit it to version control

# 5. Apply to a staging branch
dnx dotnet-charon -- DATA APPLYPATCH \
    --dataBase staging/gamedata.json \
    --input loot_changes.patch.json

Storing Patches in Version Control

Patch files are plain JSON (or BSON / MessagePack). They can be:

  • Committed alongside game source code to track data changes per feature branch.

  • Applied conditionally during a build - e.g., apply a hotfix patch only in production builds.

  • Accumulated as a migration log: v1.0→v1.1.patch.json, v1.1→v1.2.patch.json, and so on.

See also