> 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

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

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

```go
Enemy :: class : Component {
    // Сохраняется, показывается в инспекторе, включается в данные сцены
    @ao_serialize max_health: int;
    @ao_serialize patrol_radius: float;

    // Только во время выполнения — не сохраняется, не отображается в инспекторе
    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`                                               |
| Перечисления             | Любой enum, определённый пользователем                         |
| Фиксированные массивы    | `[N]T`                                                         |
| Динамические массивы     | `[..]T`                                                        |
| Структуры / классы       | Вложенные типы (их `@ao_serialize` поля включаются рекурсивно) |
| Ссылки на объекты движка | Сущности, компоненты и ассеты, где это поддерживается          |

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

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

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

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

    // Состояние во время выполнения — сериализовать не нужно
    has_been_opened: bool;
}
```

Вы можете задавать `capacity`, `loot_table`и `is_locked` для каждой сущности в редакторе. Когда сцена загружается, эти значения автоматически восстанавливаются.

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

`@ao_serialize` также определяет, какие поля включаются при использовании JSON API сохранения. В JSON записываются только помеченные поля.

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

// Сохранить
Save.set_json(player, "progress", ref progress);

// Загрузить
progress := new(Player_Progress);
if !Save.try_get_json(player, "progress", ref progress) {
    // Новый игрок — значения по умолчанию класса уже инициализированы.
}
```

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

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

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

```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 {
    @ao_serialize version: s64 = 2;
    @ao_serialize max_health: int = 100;
    @ao_serialize unlocked_skins: [..]string;
}
```

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

Десериализация массивов фиксированного размера ограничена размером назначения. Лишние элементы JSON игнорируются. Если входных данных меньше, нетронутые элементы сохраняют свои инициализированные значения.

## Что НЕ следует сериализовать

Не каждое поле следует сериализовать. Не сериализуйте `@ao_serialize` поля, которые:

* **Определяются во время выполнения** (позиции, вычисляемые каждый кадр, кэшированные поиски)
* **Временное состояние** (таймеры, счётчики перезарядки, флаги только для текущего кадра)
* **Большие данные, которые меняются каждый кадр** (ненужные издержки на сохранение)

Хорошее правило: если значение задаётся один раз (в редакторе или при загрузке) и редко меняется, сериализуйте его. Если оно пересчитывается каждый кадр — не сериализуйте.

Одной лишь пометки поля компонента недостаточно, чтобы сохранять изменения во время выполнения между сеансами. Используйте Save, Economy или Inventory, когда такое сохранение требуется.

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

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

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

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

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

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

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

### Ссылки на ассеты

Некоторые поля ссылаются на ассеты движка (текстуры, префабы, звуки). Они сериализуются как идентификаторы ассетов и автоматически разрешаются при загрузке. Смотрите встроенные компоненты (например, `Sprite_Renderer`) для примеров.