@ao_serialize

为场景、检查器和 JSON 序列化选择字段。

@ao_serialize 这是你添加到 struct/class 字段上的注解，用于将它们纳入引擎的序列化系统。添加后，你可以在编辑器中编辑脚本字段，方便自定义；如果你打算为 struct 使用 JSON 序列化/保存数据，也必须添加它。

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

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

它的作用

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

1. 在检查器中显示它 这样你就可以在编辑器中修改实体上的它。
2. 将其包含在 JSON 序列化中 (Save.set_json / Save.try_get_json).

没有 @ao_serialize 的字段仅在运行时内存中存在。每次创建组件时，它们都会从正常的初始化值开始，但不会包含在场景或 JSON 序列化中。

支持的类型

@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;
}

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

与保存系统一起使用

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

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

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

// 加载
progress := new(Player_Progress);
if !Save.try_get_json(player, "progress", ref progress) {
    // 新玩家 — 类的默认值已经初始化。
}

有关保存系统的完整详情，请参见 保存系统 和 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);

默认值和模式更改

类字段可以具有常量内联默认值。将 @ao_serialize 放在初始化器后面：

Player_Progress :: class {
    version: s64 = 2 @ao_serialize;
    max_health: int = 100 @ao_serialize;
    unlocked_skins: [..]string @ao_serialize;
}

当序列化字段缺失时，类反序列化会保留该字段的默认值。未知字段会被忽略。struct 字段不能具有内联默认值，因此在需要非零值时，应先初始化 struct 再进行反序列化。

固定数组反序列化受目标大小限制。额外的 JSON 项会被忽略。如果输入更短，未触及的元素将保留其初始化值。

不要序列化什么

并非每个字段都应该被序列化。将 @ao_serialize 关闭用于以下情况的字段：

• 在运行时派生 (每帧计算的位置、缓存查找)
• 临时状态 (计时器、冷却计数、帧局部标志)
• 每帧都会变化的大型数据 (不必要的保存开销)

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

仅仅标记组件字段本身，并不会让运行时更改在会话之间持久保存。若需要这种持久性，请使用 Save、Economy 或 Inventory。

常见模式

用于模式选择的枚举

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）中的示例。