保存系统

保存系统提供了一个键值数据存储系统，用于在不同会话之间持久保存玩家进度和偏好。

Save 系统是一个简单的 键值存储。你给它一个字符串键（例如 "xp"），它会存储一个值，并且在玩家下次加入时这个值还会保留在那里。

保存数据有两种类型：

• 玩家保存：某个玩家的个人数据（XP、升级、设置、库存等）

• 全局保存：游戏中的所有人共享（世界纪录、服务器设置、全局计数器等）

不要使用保存系统来存储玩家用火花购买的物品。请使用 购买/产品 API 上，而不是其他地方。

快速开始（保存 + 加载一个状态）

最常见的模式是：

• 在以下位置加载已保存的值 ao_start

• 每当值改变时再次保存

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

    ao_start :: method() {
        // 新玩家会使用默认值
        xp    = Save.get_int(this, "xp", 0);
        level = Save.get_int(this, "level", 1);
    }
}

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

    // ... 你的升级逻辑写在这里 ...

    // 值变化时立即保存
    Save.set_int(player, "xp", player.xp);
    Save.set_int(player, "level", player.level);
}

玩家保存（每玩家数据）

玩家保存的作用范围是单个玩家。每个玩家都有自己独立的键/值数据。

支持的类型：

• 字符串: Save.set_string / Save.get_string

• 整数（s64): Save.set_int / Save.get_int （注意：当前值在内部会被截断为 32 位）

• 浮点数（f64): Save.set_f64 / Save.get_f64

• JSON（高级）: Save.set_json / Save.try_get_json

// 偏好设置
Save.set_string(player, "selected_skin", "knight");
music_volume := Save.get_f64(player, "music_volume", 0.8);

// 删除一个键（在迁移/移除旧数据时很有用）
Save.delete_key(player, "old_key_name");

读取时始终提供一个合理的默认值。新玩家还没有这些键， get_* 会返回你的默认值。

保存“更大”的数据（JSON）

如果你有一小组字段（比如进度 + 已解锁内容），通常把它作为一个 JSON 数据块来保存会更好。

只有带有 @ao_serialize 标记的字段会被保存。

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

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

load_progress :: proc(player: Player, out: ref Player_Progress) {
    if !Save.try_get_json(player, "progress", out) {
        // 缺少键（或解析失败）→ 填入默认值
        out.version = 1;
        out.max_health = 100;
        out.unlocked_skins = .{};
    }
}

Save.try_get_json 在以下情况下返回 false ：如果键不存在，或者 JSON 字符串格式不正确。如果键存在但结构已更改（新增字段、删除旧字段），则返回 true 并将缺失字段补零。把 false 这种情况视为“使用默认值重新开始”。

保存版本控制（安全迁移旧数据）

如果你以后更改了保存格式，请保留一个 版本 键，并将旧保存数据向前迁移。

Player :: class : Player_Base {
    hp: f64;

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

        if save_version < 6 {
            // 示例迁移：hp 以前是整数，现在是浮点数
            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);

        // 加载当前格式
        hp = Save.get_f64(this, "hp", 100);
    }
}

全局保存（所有人共享）

全局保存是整个游戏共享的，不是按玩家区分的。

// 全局纪录保持者
Save.set_game_string("world_record_holder", player->get_username());
holder := Save.get_game_string("world_record_holder", "nobody yet");

// 全局计数器（原子递增，适合多人同时更新）
Save.increment_game_int("total_games_played", 1);
total := Save.get_game_int("total_games_played", 0);

使用 Save.increment_game_int 适用于多个玩家可能同时更新的计数器（击杀、加入、已进行回合等）。

常见模式

布尔值

将布尔值保存为 0/1:

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

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

键命名

键只是字符串，所以请选择以后不会冲突的名称：

• "xp", "level", "selected_skin"

• "tycoon.cash", "tycoon.upgrades.mouth_level"

如果你通过游戏父子关系连接了多个游戏（大厅 + 小游戏），请参阅 跨游戏产品/数据 了解保存数据如何共享。

其他 API

Save :: struct {
    // 删除键
    delete_key      :: proc(player: Player, key: string);
    delete_all_keys :: proc(player: Player);

    // 枚举键
    get_all_keys :: proc(player: Player) -> []string;

    // 全局枚举
    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_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));
}