@ao_serialize

@ao_serialize 注解控制哪些字段会被持久化，并可在检查器中编辑。

@ao_serialize 是你添加在 struct/class 字段上的注解，用于将它们纳入引擎的序列化系统。没有它，字段就只在运行时存在——不会被保存，不会显示在检查器中，也不会在场景写入磁盘时被包含进去。

Enemy :: class : Component {
    // 已保存，在检查器中显示，包含在场景数据中
    max_health: int @ao_serialize;
    patrol_radius: float @ao_serialize;

    // 仅运行时——不保存，不在检查器中
    current_target: v2;
    aggro_timer: float;
}

它的作用

当你将一个字段标记为 @ao_serialize时，引擎将会：

1. 在检查器中显示它 这样你就可以在编辑器中编辑实体上的该值。

2. 随场景一起保存它 这样在场景加载时会恢复该值。

3. 将其包含在 JSON 序列化中 (Save.set_json / Save.try_get_json).

没有 @ao_serialize 的字段只在运行时占用内存。每次组件创建或场景加载时，它们都会以默认（零）值开始。

支持的类型

@ao_serialize 可用于所有常见的 CSL 类型：

类型	示例
整数	s8, s16, s32, s64 / int
无符号整数	u8, u16, u32, u64 / uint
浮点数	f32 / float, f64
布尔值	bool
字符串	string
向量	v2, v3, v4
枚举	任何用户定义的枚举
固定数组	[N]T
动态数组	[..]T
结构体 / 类	嵌套类型（其 @ao_serialize 字段会递归包含）

对于嵌套的 struct/class，只有标记为 @ao_serialize 的字段才会被序列化。该注解不会级联——你必须逐个标记每个字段。

与组件一起使用

最常见的用法是在组件字段上。这样这些字段就会在编辑器的检查器中可编辑，并作为场景的一部分被保存。

Chest :: class : Component {
    capacity: int @ao_serialize;
    loot_table: string @ao_serialize;
    is_locked: bool @ao_serialize;

    // 运行时状态——无需序列化
    has_been_opened: bool;
}

你可以在编辑器中为每个实体设置 容量, loot_table和 is_locked 。当场景加载时，这些值会自动恢复。

与保存系统一起使用

@ao_serialize 还控制你在使用 JSON 保存 API 时哪些字段会被包含。只有标记过的字段才会写入 JSON。

Player_Progress :: class {
    version: s64 @ao_serialize;
    xp: s64 @ao_serialize;
    level: s64 @ao_serialize;
    unlocked_skins: [..]string @ao_serialize;
}

// 保存
Save.set_json(player, "progress", ref progress);

// 加载
progress: Player_Progress;
if !Save.try_get_json(player, "progress", ref progress) {
    // 新玩家——设置默认值
    progress.version = 1;
    progress.level = 1;
}

有关保存系统的完整细节，请参阅 保存系统 和 JSON 序列化.

与独立 JSON 一起使用

你可以将任何带注解的类型序列化到/从 JSON 字符串，而不依赖保存系统：

config: My_Config;
config.difficulty = 3;

json_str := JSON.serialize(ref config);
// json_str 只包含 @ao_serialize 字段

loaded: My_Config;
JSON.try_deserialize(json_str, ref loaded);

默认值与零填充

在反序列化时，数据中缺失的字段（例如你在玩家已有存档后新增了一个字段）会被 零填充:

• 数字 → 0

• 布尔值 → false

• 字符串 → ""

• 数组 → 空

如果零不是合理的默认值，请在加载后检查并自行补上默认值：

if !Save.try_get_json(player, "stats", ref stats) {
    stats.version = 1;
    stats.max_health = 100;  // 零会是个不好的默认值
}

什么不应序列化

并非每个字段都应该被序列化。不要在以下字段上使用 @ao_serialize ：

• 运行时派生的 （每帧计算的位置、缓存的查找结果）

• 临时状态 （计时器、冷却计数器、帧局部标志）

• 每帧都会变化的大量数据 （不必要的保存开销）

一个好的经验法则是：如果某个值只设置一次（在编辑器中或加载时）且很少变化，就序列化它；如果它每帧都会重新计算，就不要序列化。

常见模式

用于模式选择的枚举

AI_Mode :: enum {
    IDLE;
    PATROL;
    CHASE;
}

Guard :: class : Component {
    mode: AI_Mode @ao_serialize;
    patrol_speed: float @ao_serialize;
}

嵌套结构体

Spawn_Point :: struct {
    position: v2 @ao_serialize;
    radius: float @ao_serialize;
}

Spawner :: class : Component {
    points: [..]Spawn_Point @ao_serialize;
    spawn_interval: float @ao_serialize;
}

资产引用

有些字段引用引擎资源（纹理、预制体、音效）。这些会被序列化为资源标识符，并在加载时自动解析。请参阅内置组件（例如 Sprite_Renderer）获取示例。