Save System

The save system provides a key-value data storage system for persisting player progress and preferences across sessions.

The Save system is a simple key-value store. You give it a string key (like "xp"), and it stores a value that will still be there the next time the player joins.

There are two kinds of save data:

• Player save: one player's personal data (XP, upgrades, settings, inventory, etc)
• Game-wide save: shared by everyone in the game (world records, server settings, global counters, etc)

Do not use the save system to store purchases players made with sparks. Use the Purchasing/Product APIs instead.

Quick start (save + load a stat)

The most common pattern is:

• Load saved values in ao_start
• Save again whenever the value changes

Player :: class : Player_Base {
    xp: s64;
    level: s64;

    ao_start :: method() {
        // Defaults are used for brand new players
        xp    = Save.get_int(this, "xp", 0);
        level = Save.get_int(this, "level", 1);
    }
}

add_xp :: proc(player: Player, amount: s64) {
    player.xp += amount;

    // ... your level-up logic here ...

    // Save immediately when it changes
    Save.set_int(player, "xp", player.xp);
    Save.set_int(player, "level", player.level);
}

Player save (per-player data)

Player save is scoped to a single player. Every player has their own isolated key/value data.

Supported types:

• String: Save.set_string / Save.get_string
• Integer (s64): Save.set_int / Save.get_int (note: values are currently truncated to 32-bit internally)
• Float (f64): Save.set_f64 / Save.get_f64
• JSON (advanced): Save.set_json / Save.try_get_json

// Preferences
Save.set_string(player, "selected_skin", "knight");
music_volume := Save.get_f64(player, "music_volume", 0.8);

// Deleting a key (useful when migrating/removing old data)
Save.delete_key(player, "old_key_name");

Always provide a sensible default when reading. New players won't have keys yet, and get_* will return your default.

Saving “bigger” data (JSON)

If you have a little bundle of fields (like progress + unlocked things), it's often nicer to save it as one JSON blob.

Only fields marked with @ao_serialize are saved.

Player_Progress :: class {
    version: s64 = 1 @ao_serialize;
    max_health: s64 = 100 @ao_serialize;
    unlocked_skins: [..]string @ao_serialize;
}

save_progress :: proc(player: Player, progress: Player_Progress) {
    Save.set_json(player, "progress", ref progress);
}

load_progress :: proc(player: Player) -> Player_Progress {
    progress := new(Player_Progress);
    if !Save.try_get_json(player, "progress", ref progress) {
        // Missing key (or parse failed) already has the class defaults.
    }
    return progress;
}

Save.try_get_json returns false if the key doesn't exist 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.

Save versioning (migrating old data safely)

If you ever change your save format, keep a version key and migrate older saves forward.

Player :: class : Player_Base {
    hp: f64;

    ao_start :: method() {
        save_version := Save.get_int(this, "version", 0);

        if save_version < 6 {
            // Example migration: hp used to be an int, now it's a float
            save_version = 6;
            old_hp := Save.get_int(this, "hp", 100);
            Save.delete_key(this, "hp");
            Save.set_f64(this, "hp", old_hp.(f64));
        }

        Save.set_int(this, "version", save_version);

        // Load current format
        hp = Save.get_f64(this, "hp", 100);
    }
}

Game-wide save (shared by everyone)

Game-wide save is shared across the whole game, not per-player.

// Global record holder
Save.set_game_string("world_record_holder", player.get_username());
holder := Save.get_game_string("world_record_holder", "nobody yet");

// Global counters (atomic increment, safe when many players update it)
Save.increment_game_int("total_games_played", 1);
total := Save.get_game_int("total_games_played", 0);

Use Save.increment_game_int for counters that multiple players might update at the same time (kills, joins, rounds played, etc). Its optimistic_update parameter defaults to true, so the local cached value changes immediately.

Common patterns

Booleans

Save booleans as 0/1:

// Save
Save.set_int(player, "tutorial_complete", tutorial_complete ? 1 : 0);

// Load
tutorial_complete = Save.get_int(player, "tutorial_complete", 0) != 0;

Key naming

Keys are just strings, so pick names that won't collide later:

• "xp", "level", "selected_skin"
• "tycoon.cash", "tycoon.upgrades.mouth_level"

If you have multiple games connected via game parenting (hub + minigames), see Cross-Game Products/Data for how save data can be shared.

Additional APIs

Save :: struct {
    // Delete keys
    delete_key      :: proc(player: Player, key: string);
    delete_all_keys :: proc(player: Player);

    // Enumerate keys
    get_all_keys :: proc(player: Player) -> []string;

    // Game-wide enumeration
    get_all_game_strings :: proc() -> []Save_Game_String;
    get_all_game_ints    :: proc() -> []Save_Game_Int;
    get_all_game_keys    :: proc() -> []Save_Game_Key;

    // Ordered/ranked data (leaderboards)
    ordered_set     :: proc(document: string, key: string, value: f64);
    ordered_get     :: proc(document: string, key: string, default: f64,
                            userdata: Object,
                            callback: proc(entry: Ordered_Save_Entry, userdata: Object));
    ordered_get_all :: proc(document: string, offset: s64, limit: s64,
                            userdata: Object,
                            callback: proc(entries: []Ordered_Save_Entry, userdata: Object));
}

ordered_get and ordered_get_all are asynchronous and execute on the server. Call them from the normal shared gameplay path; do not add a Game.is_server() guard.

Callback arrays are valid only during the callback, so copy any entries you need to keep:

Ranking_State :: class : Component {
    entries: [..]Ordered_Save_Entry;

    refresh :: method() {
        Save.ordered_get_all(
            "weekly_score",
            0,
            100,
            this,
            proc(results: []Ordered_Save_Entry, userdata: Object) {
                state := userdata.(Ranking_State);
                state.entries.clear();
                for result: results {
                    state.entries.append(result);
                }
            }
        );
    }
}

Each completed ordered_get request invokes its callback once. A missing entry or request failure returns the supplied default. Each completed ordered_get_all request also invokes its callback once; an empty result or request failure supplies an empty array. Request failures are logged.