保存系统

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

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

有两种保存数据：

• 玩家保存：某个玩家的个人数据（XP、升级、设置、背包等）
• 全局保存：游戏中所有人共享（世界纪录、服务器设置、全局计数器等）

不要用保存系统来存储玩家用 sparks 购买的物品。请使用 购买/产品 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 = 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) {
        // 缺失的键（或解析失败）已经使用类默认值。
    }
    return progress;
}

Save.try_get_json 返回 false 如果键不存在或 JSON 字符串格式错误，则返回 false。加载前先分配类数据，因为 false 分支不会分配它。缺失的字段会保持其类默认值，未知字段会被忽略。

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

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

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 适用于多个玩家可能同时更新的计数器（击杀数、加入数、已玩回合数等）。它的 optimistic_update 参数默认值为 true，因此本地缓存值会立即改变。

常见模式

布尔值

将布尔值保存为 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));
}

ordered_get 和 ordered_get_all 它们是异步的，并在服务器上执行。请从正常的共享游戏流程中调用它们；不要添加 Game.is_server() 保护条件。

回调数组仅在回调期间有效，所以请复制你需要保留的任何条目：

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 {
                    每个完成的
                }
            }
        );
    }
}

请求都会调用一次其回调。缺失的条目或请求失败会返回提供的默认值。每个完成的 ordered_get 请求也都会调用一次其回调；空结果或请求失败会提供一个空数组。请求失败会被记录。 ordered_get_all 请求也都会调用一次其回调；空结果或请求失败会提供一个空数组。请求失败会被记录。