@ao_serialize

La anotación @ao_serialize controla qué campos se persisten y son editables en el inspector.

@ao_serialize es la anotación que colocas en los campos de struct/class para integrarlos en el sistema de serialización del motor. Sin ella, un campo es solo de tiempo de ejecución — no se guardará, no aparecerá en el inspector y no se incluirá cuando la escena se escriba en disco.

Enemy :: class : Component {
    // Guardado, mostrado en el inspector, incluido en los datos de la escena
    max_health: int @ao_serialize;
    patrol_radius: float @ao_serialize;

    // Solo en tiempo de ejecución — no se guarda, no está en el inspector
    current_target: v2;
    aggro_timer: float;
}

Qué hace

Cuando marcas un campo con @ao_serialize, el motor hará lo siguiente:

1. Mostrarlo en el inspector para que puedas editarlo en las entidades en el editor.

2. Guardarlo con la escena para que el valor se restaure cuando se cargue la escena.

3. Incluirlo en la serialización JSON (Save.set_json / Save.try_get_json).

Los campos sin @ao_serialize existen solo en memoria en tiempo de ejecución. Comienzan con su valor predeterminado (cero) cada vez que se crea el componente o se carga la escena.

Tipos compatibles

@ao_serialize funciona con todos los tipos comunes de CSL:

Tipo	Ejemplo
Enteros	s8, s16, s32, s64 / int
Sin signo	u8, u16, u32, u64 / uint
Flotantes	f32 / float, f64
Booleanos	bool
Cadenas	string
Vectores	v2, v3, v4
Enums	Cualquier enum definido por el usuario
Arrays fijos	[N]T
Arrays dinámicos	[..]T
Structs / clases	Tipos anidados (sus @ao_serialize campos se incluyen recursivamente)

Para structs/clases anidados, solo se serializan los campos marcados @ao_serialize dentro del tipo anidado. La anotación no se hereda — debes marcar cada campo individualmente.

Uso con componentes

El uso más común es en campos de componentes. Estos pasan a ser editables en el inspector del editor y se guardan como parte de la escena.

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

    // Estado en tiempo de ejecución — no hace falta serializarlo
    has_been_opened: bool;
}

Puedes establecer capacity, loot_table, y is_locked por entidad en el editor. Cuando se carga la escena, esos valores se restauran automáticamente.

Uso con el sistema de guardado

@ao_serialize también controla qué campos se incluyen cuando usas las API de guardado en JSON. Solo los campos marcados se escriben en JSON.

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

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

// Cargar
progress: Player_Progress;
if !Save.try_get_json(player, "progress", ref progress) {
    // Nuevo jugador — establecer valores predeterminados
    progress.version = 1;
    progress.level = 1;
}

Para obtener detalles completos sobre el sistema de guardado, consulta Sistema de guardado y Serialización JSON.

Uso con JSON independiente

Puedes serializar cualquier tipo anotado hacia/desde una cadena JSON, independientemente del sistema de guardado:

config: My_Config;
config.difficulty = 3;

json_str := JSON.serialize(ref config);
// json_str contiene solo campos @ao_serialize

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

Valores predeterminados y relleno con ceros

Al deserializar, los campos que faltan en los datos (por ejemplo, añadiste un campo nuevo después de que los jugadores ya tuvieran partidas guardadas) se rellenan con ceros:

• Números → 0

• Booleanos → false

• Cadenas → ""

• Arrays → vacíos

Si cero no es un valor predeterminado razonable, comprueba y establece tus propios valores después de cargar:

if !Save.try_get_json(player, "stats", ref stats) {
    stats.version = 1;
    stats.max_health = 100;  // cero sería un mal valor predeterminado
}

Qué NO serializar

No todos los campos deben serializarse. Deja @ao_serialize desactivados los campos que sean:

• Derivados en tiempo de ejecución (posiciones calculadas en cada fotograma, búsquedas en caché)

• Estado temporal (temporizadores, contadores de enfriamiento, banderas locales del fotograma)

• Grandes cantidades de datos que cambian en cada fotograma (sobrecarga de guardado innecesaria)

Una buena regla general: si el valor se establece una vez (en el editor o al cargar) y rara vez cambia, sérialo. Si se recalcula en cada fotograma, no lo hagas.

Patrones comunes

Enums para selección de modo

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

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

Structs anidados

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

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

Referencias a recursos

Algunos campos hacen referencia a recursos del motor (texturas, prefabs, sonidos). Estos se serializan como identificadores de recurso y se resuelven automáticamente al cargar. Consulta los componentes integrados (como Sprite_Renderer) para ver ejemplos.