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 = 1 @ao_serialize;

    xp: s64 @ao_serialize;
    level: s64 = 1 @ao_serialize;

    unlocked_skins: [..]string @ao_serialize;
}

保存 JSON

将整个结构体保存到一个键下：

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

加载 JSON（带默认值）

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

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

    if !Save.try_get_json(player, "progress", ref progress) {
        // 新玩家（或格式错误的 JSON）已经拥有类默认值。
    }

    return progress;
}

将已存储字段改为不兼容的类型属于无效输入，可能会显式失败。当旧值无法安全转换时，请使用新字段或新的存档键。

版本控制与迁移

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

保持兼容性的最佳实践：

• 优先添加新字段 并为其设置合理的类默认值。
• 当新值必须由旧数据推导时，请保留版本字段。
• 如果你需要彻底断开兼容性，可以考虑将其保存到一个 新键 （例如 "progress_v2"）下，并保留一个回退加载器。

迁移示例：

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

    if !Save.try_get_json(player, "progress", ref progress) {
        // 类默认值已经描述了一个新玩家。
    }

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

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

固定数组

定长数组输入受目标限制：

• 多余的 JSON 项会被忽略。
• 缺失的项会使剩余的目标元素保持不变。

何时使用 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;
}