JSON 序列化

对于保存更高级的数据结构，你可以将它们序列化为 JSON，并存储在保存系统中。

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

在底层，这使用的是 Save 系统的 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 返回 false 如果键不存在或 JSON 字符串格式不正确。如果键存在，但结构已经改变（新增字段、删除旧字段），则返回 true ，缺失字段会被填充为零值。

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 模式会变化，请在结构中包含一个 version 字段，并在加载后进行迁移。

保持兼容性的最佳实践：

• 优先新增字段 （旧 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 当你想存储一个内聚的结构（进度、装备配置、解锁内容）并集中管理保存逻辑时使用。

独立的 JSON API

你也可以独立于 Save 系统进行 JSON 的序列化/反序列化（例如用于日志、网络或自定义存储）：

JSON :: struct {
    serialize       :: proc(obj: ref $T) -> string;
    try_deserialize :: proc(json: string, out_value: ref $T) -> bool;
}