保存系统

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

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

有两种保存数据：

• 玩家存档：单个玩家的个人数据（经验值、升级、设置、物品栏等）

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

不要使用存档系统来存储玩家用火花购买的物品。请使用 购买/产品 API 多个玩家连接 —— 将每个玩家的状态存储在

快速开始（保存 + 加载 一个统计）

最常见的模式是：

• 在……中加载已保存的值 尤其是

• 在值更改时再次保存

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

• 浮点数（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", 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 返回 假 如果键不存在 或 保存的 JSON 不再与您的结构匹配。将其视为“用默认值重新开始”。

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

如果你更改了存档格式，请保留一个 版本 键并将较旧的存档向前迁移。

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"

如果你有多个通过游戏父子关系连接的游戏（中心 + 迷你游戏），请参阅 跨游戏产品/数据 以了解存档数据如何共享。