> For the complete documentation index, see [llms.txt](https://docs.allout.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.allout.game/all-out-docs/ru/dannye-i-sokhranenie/ao-serialize.md).

# @ao\_serialize

`@ao_serialize` это аннотация, которую вы помещаете на поля struct/class, чтобы подключить их к системе сериализации движка. Добавление этого позволяет редактировать поля скрипта в редакторе для удобной настройки и также требуется, если вы собираетесь использовать JSON-сериализацию/сохранение данных для структур.

```go
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` поля включаются рекурсивно) |
| Ссылки на движок         | Сущности, компоненты и ресурсы, где это поддерживается         |

{% hint style="info" %}
Для вложенных struct/class сериализуются только поля, помеченные `@ao_serialize` внутри вложенного типа. Аннотация не распространяется автоматически — нужно помечать каждое поле отдельно.
{% endhint %}

## Использование с компонентами

Самое распространённое применение — на полях компонентов. Они становятся редактируемыми в инспекторе редактора и сохраняются как часть сцены.

```go
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 записываются только помеченные поля.

```go
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) {
    // Новый игрок — значения по умолчанию класса уже инициализированы.
}
```

Полные сведения о системе сохранения см. в [Система сохранения](/all-out-docs/ru/dannye-i-sokhranenie/save.md) и [Сериализация JSON](/all-out-docs/ru/dannye-i-sokhranenie/json.md).

## Использование с автономным JSON

Вы можете сериализовать любой помеченный тип в/из строки JSON независимо от системы сохранения:

```go
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` после инициализатора:

```go
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, когда такое сохранение требуется.

## Распространённые шаблоны

### Перечисления для выбора режима

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

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

### Вложенные структуры

```go
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`) для примеров.