JSON 序列化

要保存更复杂的数据结构，你可以将它们序列化为 JSON 并存储在保存系统中。

CSL 可以为你将某些数据结构序列化为 JSON。当你想保存一组相关字段（比如玩家进度、升级、解锁等）而不想管理大量单独的存档键时，这最有用。

在底层，这使用了存档系统的 JSON API：

• Save.set_json(player, key, value)

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

JSON 存档/加载是 每个玩家 （它需要一个 player）。全局存档目前仅支持字符串和整数。

什么会被保存？

只有带有 @ao_serialize 包含在 JSON 中。

Player_Progress :: class {
    version: s64 @ao_serialize;

    xp: s64 @ao_serialize;
    level: s64 @ao_serialize;

    unlocked_skins: [..]string @ao_serialize;
}

保存 JSON

将整个结构保存在一个键下：

// 注意：只有带 @ao_serialize 的字段会被写入
Save.set_json(player, "progress", ref progress);

加载 JSON（带默认值）

Save.try_get_json 返回 假 如果键丢失 或 已保存的 JSON 无法解析为你当前的结构。

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

    if !Save.try_get_json(player, "progress", ref progress) {
        // 新玩家（或旧 JSON 不再匹配）→ 使用默认值
        progress.version = 1;
        progress.xp = 0;
        progress.level = 1;
        progress.unlocked_skins = .{};
    }

    return progress;
}

如果你重命名/移除序列化字段，旧的 JSON 可能无法解析，你将进入默认值路径。及早规划迁移（见下文）。

版本控制与迁移

如果你预计 JSON 模式会改变，在结构中包含一个 版本 字段并在加载后进行迁移。

保持兼容性的最佳实践：

• 优先添加新字段 （旧的 JSON 往往仍能解析；在加载后填入默认值）

• 避免重命名/移除字段 （可能导致解析失败）

• 如果需要彻底更改，考虑使用一个 新键 （例如 "progress_v2"）并保留一个回退的加载器

迁移示例：

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

    if !Save.try_get_json(player, "progress", ref progress) {
        progress.version = 1;
        progress.xp = 0;
        progress.level = 1;
        progress.unlocked_skins = .{};
    }

    // 向前迁移
    if progress.version < 2 {
        progress.version = 2;
        // 示例：v2 引入了 unlocked_skins（对此进行初始化）
        progress.unlocked_skins = .{};
    }

    // 将迁移后的版本写回
    Save.set_json(player, "progress", ref progress);
    return progress;
}

何时使用 JSON 与 简单键

• 使用 简单键 (Save.set_int, Save.set_string等）用于少量你经常读/写的值。

• 使用 JSON 当你想存储一个完整的结构（进度、装备配置、解锁项）并将存档逻辑集中管理时使用。