Entidades y Componentes

Todos los juegos de Out están construidos alrededor de entidades (cosas en el mundo) y componentes (comportamiento/datos adjuntos a las entidades).

Si has usado Unity antes: piensa “GameObject + Components”. Si has usado Roblox: piensa “Instance + Scripts/Components”. La idea central es la misma: compones la jugabilidad añadiendo componentes a las entidades.

Entidades

Las entidades existen de dos maneras comunes:

• Colocadas en el editor: ya están en la escena al iniciar.

• Creadas en tiempo de ejecución: las generas desde un script.

Creación y destrucción de entidades

entity := Scene.create_entity();
entity->set_local_position({10, 20});
entity->set_local_scale({2.5, 2.5});
entity->set_local_rotation(0);

// Cuando hayas terminado:
entity->destroy();

Destruir una entidad también destruye sus componentes. No conserves referencias a componentes después de destruir su entidad.

Iterar entidades

foreach e: entity_iterator() {
    // ...
}

Componentes

Los componentes son las unidades de comportamiento. Un componente “vive en” una entidad y puede leer/modificar esa entidad.

Obtener y añadir componentes

sprite := entity->get_component(Sprite_Renderer);

player := entity->get_component(Player);

my_comp := entity->add_component(My_Component);

Iterar componentes

foreach enemy: component_iterator(Enemy) {
    enemy->tick_ai();
}

Componentes integrados que usarás mucho

Sprite_Renderer

texture := get_asset(Texture_Asset, "ui/button.png");

sprite := entity->get_component(Sprite_Renderer);
sprite->set_texture(texture);
sprite.color = {1, 1, 1, 1}; // RGBA
sprite.depth_offset = 0.5;
sprite.layer = 10;

Prefabs (Prefab_Asset)

Los prefabs deben crearse en el editor. En los scripts, los instancias.

prefab := get_asset(Prefab_Asset, "MyPrefab.prefab");
spawned := instantiate(prefab);
spawned->set_local_position({1, 3});

Spine (Spine_Animator)

Si usas personajes animados en 2D, a menudo trabajarás con Spine_Animator. Ver Spine.

Escribir un componente personalizado

Crea nuevos componentes en archivos dedicados (por ejemplo orbiter.csl) y adjúntalos a las entidades ya sea:

• Manualmente en el editor, o

• En tiempo de ejecución con entity->add_component(...)

Los componentes pueden implementar callbacks de ciclo de vida:

• ao_start()

• ao_update(dt)

• ao_late_update(dt) (después de todas las actualizaciones)

• ao_end() (cuando se destruye)

Ejemplo:

Orbiter :: class : Component {
    center: v2;
    radius: float;
    speed: float;
    angle: float;

    ao_start :: method() {
        center = entity.local_position;
        radius = 2;
        speed = 1;
        angle = 0;
    }

    ao_update :: method(dt: float) {
        angle += speed * dt;

        offset_x := cos(angle) * radius;
        offset_y := sin(angle) * radius;

        entity->set_local_position({center.x + offset_x, center.y + offset_y});
    }
}

Métodos de ciclo de vida para scripts globales (ao_start, ao_update, ...) se tratan en Ciclo de vida del juego/cuadro.

Campos serializados (@ao_serialize)

Usa @ao_serialize para exponer un campo en el editor (y a menudo para habilitar el guardado/persistencia cuando corresponda).

Chest :: class : Component {
    capacity: int @ao_serialize;
}

Encontrar componentes cercanos (consultas de proximidad)

CSL no tiene callbacks de colisión. Un patrón común es “consultar componentes cercanos y comprobar la distancia”.

Ayudas útiles:

Scene.get_all_components_in_range     :: proc(position: v2, range: float, results: ref [..]$T)
Scene.get_closest_component_in_range  :: proc(position: v2, range: float, $T: typeid) -> T

Ejemplo:

nearby: [..]Enemy;
Scene.get_all_components_in_range(player.entity.world_position, 5.0, ref nearby);

for e: nearby {
    // ...
}

closest_pickup := Scene.get_closest_component_in_range(player.entity.world_position, 2.0, Pickup);
if closest_pickup != null {
    // ...
}

Buenas prácticas

• El estado por jugador pertenece a Player. Evita variables globales que se romperían con múltiples jugadores.

• Prefiere componentes para los comportamientos de jugabilidad. Acabarás con piezas reutilizables que puedes adjuntar a diferentes entidades.

• Mantén el trabajo cosmético local. La UI/las partículas normalmente deberían ejecutarse detrás de is_local() comprobaciones.