Fundamentos del lenguaje

A los efectos de esta documentación, nos referimos a CSL y al runtime/plataforma en torno a él de forma indistinta

Esta página es la parte de “modelado de datos” de CSL: primitivas, structs/clases y los patrones que usarás para representar el estado del juego con claridad.

Si eres totalmente nuevo, empieza con Primeros pasos con CSL. Esta página asume que ya sabes declarar variables y escribir proc/method.

Tipos primitivos

Números y bools

• Enteros con signo: s8, s16, s32, s64 (alias: int == s64)

• Enteros sin signo: u8, u16, u32, u64 (alias: uint == u64)

• Flotantes: f32 (alias: float), f64

• Booleanos: b8 (alias: bool), b16, b32, b64

health: int = 100;
speed: float = 6.5;
is_dead: bool = false;

Cadenas

string se usa constantemente para IDs, nombres y formato.

item_id := "sword";
log_info("recogido %", {item_id});

Vectores

v2, v3, v4 son tipos integrados de matemáticas/datos:

pos: v2 = {10, 20};
color: v4 = {1, 0, 0, 1};

Enums

Los enums son ideales para campos de “modo/estado” legibles:

Game_Phase :: enum {
    LOBBY;
    RUNNING;
    POST_GAME;
}

phase := Game_Phase.LOBBY;

if phase == .RUNNING {
    // ...
}

Los valores de enum suelen referenciarse con la forma abreviada .VALUE cuando el compilador puede inferir el tipo de enum.

Structs (tipos por valor)

Usa structs para “datos simples” que quieras copiar de forma barata (configuración, pequeños bloques de estado, descriptores).

Damage_Desc :: struct {
    amount: int;
    knockback: v2;
}

hit := Damage_Desc{amount=10, knockback={2, 1}};

Cuándo usar un struct

• Un objeto descriptor/configuración (*_Desc)

• Estado pequeño e independiente que quieras copiar por valor

• Datos que quieras incrustar dentro de otro tipo

Cuándo no usar un struct

• Estado mutable grande compartido entre varios sistemas (usa una clase)

• Objetos de “identidad” (jugadores, objetos, objetos de larga vida) (usa una clase)

Clases (tipos por referencia)

Las clases son tipos por referencia. Crea instancias con new(...).

Enemy :: class {
    health: int;
    target: v2;
}

e := new(Enemy);
e.health = 50;
e.target = {0, 0};

Herencia

Puedes heredar de otros structs/clases:

Weapon_Definition :: class {
    id: string;
    name: string;
}

Gun_Definition :: class : Weapon_Definition {
    fire_rate: float;
}

Usa herencia cuando exista una relación real de “es-un”. Para la mayoría de los datos de gameplay, la composición (campos) es más simple y más fácil de mantener.

Arrays, slices y arrays dinámicos

Verás tres formas comunes:

• Arrays fijos: [N]T (tamaño en tiempo de compilación)

• Slices / arrays gestionados: []T (una vista de un array)

• Arrays dinámicos: [..]T (lista redimensionable)

Ejemplo:

spawn_points: [4]v2 = {{0,0}, {5,0}, {0,5}, {5,5}};

alive_enemy_ids: [..]int;
alive_enemy_ids->append(123);
alive_enemy_ids->append(456);

Para una guía completa, consulta Arrays y colecciones.

Paso por referencia (ref)

Si un procedimiento necesita modificar un valor, usa ref:

apply_damage :: proc(health: ref int, amount: int) {
    health -= amount;
}

hp := 100;
apply_damage(ref hp, 10);

Esto es especialmente útil para APIs de estilo “layout” que recortan/reducen progresivamente un rect:

draw_panel :: proc(rect: ref Rect) {
    header := rect->cut_top(50);
    draw_header(header);
    // rect es ahora el área restante para el contenido
}

Conversión de tipos

Usa expr.(T):

f := 12.7;
i := f.(int);    // 12
f2 := i.(float); // 12.0

Polimorfismo de tipos (procedimientos de estilo genérico)

CSL admite procedimientos polimórficos usando $ para deducir tipos en el sitio de llamada:

min :: proc(a: $T, b: T) -> T {
    if a < b return a;
    return b;
}

a := min(10, 20);       // T == int
b := min(1.25, 3.5);    // T == float

Tipos como valores (typeid)

typeid es un valor que representa un tipo en tiempo de ejecución y/o para llamadas polimórficas:

default_of :: proc($T: typeid) -> T {
    t: T;
    return t;
}

zero := default_of(int);
empty := default_of(string);

Pautas prácticas de modelado

• El estado por jugador vive en Player. Si debe diferir entre jugadores, no debería ser global.

• Prefiere structs pequeños para descriptores y guarda el estado en tiempo de ejecución en clases/componentes.

• Mantén autoritativos los datos autorizados por el servidor. Si afecta al gameplay, no lo calcules solo en el cliente.

Para patrones específicos de jugador, consulta Añadir lógica de jugador. Para la parte ECS del mundo, consulta Entidades y componentes.