🧰 Zion Tools

Tutorial

Seven worked examples that take you from first open to writing your own source and format, then into the 1.1 diagnostic workflow. Read in order or jump to what you need.

Example 1 - Edit your first JSON save

Goal: change a stat in a save without leaving Unity. Assume your game writes a file to Application.persistentDataPath with fields like playerName, level, gold, and an inventory array.

1. Run your game once so the save file exists.
2. Open Tools > Zion Games > Save Inspector.
3. The Source dropdown is already on "Persistent Data Folder".
4. Your save appears on the left. Click it to render the tree on the right.
5. In a real save with hundreds of fields, type gold into the tree search field instead of scrolling - matches highlight and everything else hides.
6. Change gold from 540 to 9999. The header now shows a trailing * - unsaved edits.
7. Click Save Changes. The file is written back as pretty-printed, two-space-indented JSON.
8. Re-run your game - the new value is live.

Example 2 - Override the auto-detected format

Goal: force a specific format when auto-detection picks wrong - for example, viewing a half-corrupted JSON file as plain text to fix it by hand.

1. Load the save.
2. Open the Format dropdown.
3. Pick "Raw text". The tree is replaced with a single text node holding the entire file.
4. Edit, then Save Changes.

The same dropdown lets you force JSON onto a payload that has a leading // comment line your game expects but the parser rejects - strip the line, force JSON, fix the data, then add the comment back via raw text.

Example 3 - Write a custom PlayerPrefs source

Goal: understand the ISaveSource lifecycle by walking through a real implementation. A production-quality PlayerPrefsSource already ships with the asset; the full teaching code is on the Custom Source tab, including the 1.1 ISaveBackupProvider opt-in that gives your custom source backup diffs.

Example 4 - Write a custom binary format

Goal: view and edit a binary save the inspector doesn't know. Implement ISaveFormat.CanParse with a magic-byte sniff, then Parse and Serialize. The full example is on the Custom Format tab. Once it compiles, diff, validation and search work on your binary saves too.

Example 5 - Duplicate a save for safe testing

Goal: fork a save before destructive edits so you can roll back instantly.

Since 1.1, the automatic backup plus Compare > With Backup covers the common "undo my last save" case with zero setup. A manual fork is still the right tool for a long-lived snapshot that survives multiple saves - the .bak sibling only ever holds the previous write.

Drop a helper into Assets/Editor/SaveFork.cs:

using System.IO;
using System.Linq;
using UnityEditor;
using UnityEngine;

public static class SaveFork
{
    [MenuItem("Tools/Zion Games/Duplicate Most Recent Save")]
    public static void DuplicateLatestSave()
    {
        var dir = Application.persistentDataPath;
        var files = Directory.GetFiles(dir, "*.json")
            .OrderByDescending(File.GetLastWriteTime)
            .ToArray();

        if (files.Length == 0)
        {
            Debug.LogWarning("No JSON saves found in persistentDataPath.");
            return;
        }

        var source = files[0];
        var dest = Path.Combine(
            dir,
            Path.GetFileNameWithoutExtension(source) +
            "-backup-" +
            System.DateTime.Now.ToString("yyyyMMdd-HHmmss") +
            ".json");

        File.Copy(source, dest, overwrite: false);
        Debug.Log($"Duplicated:\n  {source}\n→ {dest}");
    }
}

Now your workflow is: duplicate the file, hit Refresh so both files appear, edit the original aggressively, and if it breaks, run Compare > With Another Save against the fork to see what you broke, then delete the original and rename the backup back.

Example 6 - Diff a save against its backup 1.1

Goal: answer "what did that play session actually write?" without reading two JSON files side by side.

1. Open a save that has been written at least once through the game or the inspector, so a backup exists.
2. Click Compare ▾ > With Backup. The Save Diff window opens with the backup on the left and the current save on the right.
3. Every difference is one row - ADDED, REMOVED, CHANGED, or TYPE - with before/after values side by side and dotted paths like inventory[2].id.
4. Use the toggles to hide categories, the search field to filter paths, and Copy as Markdown to paste the whole diff into an issue.

Because unsaved edits are included, Compare > With Backup right before Save Changes doubles as a pre-save preview. And Compare > With Another Save between a player's broken save and a known-good slot pinpoints the divergence in seconds.

Example 7 - Validate saves with a schema 1.1

Goal: catch missing fields and wrong types in any save with one click - before they crash your loader.

1. Open a save you trust - freshly written by the current build of your game.
2. Schema ▾ > Capture Schema From Current Save…, name it after the slot type (e.g. campaign-v3), and confirm.
3. Open any other save - a bug-report attachment, an old slot from a previous version, a hand-edited test file.
4. Schema ▾ > Validate Against > campaign-v3. The results window flags MISSING fields, TYPE mismatches, and EXTRA fields the schema never saw.

Re-capture the schema whenever your save format intentionally changes. Pair a validation run with Export Report and you have a complete, pasteable diagnostic for any save a player sends you.