@ao_serialize

Выберите поля для сериализации сцены, инспектора и JSON.

@ao_serialize это аннотация, которую вы помещаете на поля struct/class, чтобы подключить их к системе сериализации движка. Добавление этого позволяет редактировать поля скрипта в редакторе для удобной настройки и также требуется, если вы собираетесь использовать 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 также определяет, какие поля включаются при использовании API JSON-сохранения. В 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;
}

Если сериализованное поле отсутствует, при десериализации класса сохраняется значение по умолчанию этого поля. Неизвестные поля игнорируются. Поля структур не могут иметь встроенные значения по умолчанию, поэтому перед десериализацией инициализируйте структуру, если ей нужны ненулевые значения.

Десериализация массива фиксированного размера ограничена размером назначения. Лишние элементы 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) для примеров.