JSON Serialization

For saving more advanced data structures, you can serialize them to JSON and store them in the Save system.

CSL can serialize certain data structures into JSON for you. This is most useful when you want to save a “bundle” of related fields (like player progress, upgrades, unlocks, etc) without managing lots of separate save keys.

Under the hood, this uses the Save system's JSON APIs:

• Save.set_json(player, key, value)
• Save.try_get_json(player, key, out) -> bool

JSON save/load is per-player (it takes a player). Game-wide save currently supports strings + ints only.

What gets saved?

Only fields marked with @ao_serialize are included in the JSON.

Player_Progress :: class {
    version: s64 = 1 @ao_serialize;

    xp: s64 @ao_serialize;
    level: s64 = 1 @ao_serialize;

    unlocked_skins: [..]string @ao_serialize;
}

Saving JSON

Save the whole structure under one key:

// Note: Only @ao_serialize fields are written
Save.set_json(player, "progress", ref progress);

Loading JSON (with defaults)

Save.try_get_json returns false if the key is missing or the JSON string is malformed. Allocate class data before loading because the false path does not allocate it. Missing fields keep their class defaults, and unknown fields are ignored.

load_progress :: proc(player: Player) -> Player_Progress {
    progress := new(Player_Progress);

    if !Save.try_get_json(player, "progress", ref progress) {
        // New player (or malformed JSON) already has the class defaults.
    }

    return progress;
}

Changing a stored field to an incompatible type is invalid input and can fail loudly. Use a new field or save key when the old value cannot be converted safely.

Versioning & migrations

If you expect your JSON schema to change, include a version field in the structure and migrate after load.

Best practices for staying compatible:

• Prefer adding new fields with sensible class defaults.
• Keep a version field when a new value must be derived from old data.
• If you need a hard break, consider saving under a new key (e.g. "progress_v2") and keeping a fallback loader.

Migration Example:

load_progress_and_migrate :: proc(player: Player) -> Player_Progress {
    progress := new(Player_Progress);

    if !Save.try_get_json(player, "progress", ref progress) {
        // The class defaults already describe a new player.
    }

    // Migrate forward
    if progress.version < 2 {
        progress.version = 2;
        // Example: v2 introduced unlocked_skins (initialize it)
        progress.unlocked_skins = .{};
    }

    // Write back the migrated version
    Save.set_json(player, "progress", ref progress);
    return progress;
}

Fixed arrays

Fixed-array input is bounded by the destination:

• Extra JSON items are ignored.
• Missing items leave the remaining destination elements unchanged.

When to use JSON vs simple keys

• Use simple keys (Save.set_int, Save.set_string, etc) for a handful of values you read/write often.
• Use JSON when you want to store a cohesive structure (progress, loadouts, unlocks) and keep your save logic centralized.

Standalone JSON API

You can also serialize/deserialize JSON independently of the Save system (e.g. for logging, networking, or custom storage):

JSON :: struct {
    serialize       :: proc(obj: ref $T) -> string;
    try_deserialize :: proc(json: string, out_value: ref $T) -> bool;
}