Conceptos Básicos del Lenguaje

Para los propósitos de esta documentación, nos referimos a CSL y al entorno de ejecución/plataforma que lo rodea de manera intercambiable.

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

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

Tipos primitivos

Números y booleanos

• 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 identificadores, nombres y formateo.

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

Vectores

v2, v3, v4 son tipos matemáticos/de datos incorporados:

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

Enumeraciones

Las enumeraciones son geniales para campos legibles de “modo/estado”:

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

phase := Game_Phase.LOBBY;

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

Los valores de enum se referencian comúnmente con la abreviatura .VALUE cuando el compilador puede inferir el tipo de la enumeración.

Structs (tipos por valor)

Usa structs para “datos simples” que quieras copiar de forma barata (configuración, pequeños fragmentos 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/de configuración (*_Desc)

• Estado pequeño y autocontenido que quieras copiar por valor

• Datos que quieras incrustar dentro de otro tipo

Cuándo no usar un struct

• Estado grande y mutable compartido entre múltiples sistemas (usa una clase)

• Objetos de “identidad” (jugadores, ítems, objetos de larga duración) (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 la herencia cuando exista una verdadera relación de “es-un”. Para la mayoría de datos de jugabilidad, la composición (campos) es más simple y 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, véase Arrays y Colecciones.

Pasar 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 “diseño” que progresivamente cortan/reduzcan un rectángulo:

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

Casting

Usa expr.(T):

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

Polimorfismo de tipos (procedimientos estilo genérico)

CSL soporta 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);

Directrices 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 almacena el estado en tiempo de ejecución en clases/componentes.

• Mantén los datos autoritativos del servidor como autoritativos. Si afecta a la jugabilidad, no lo calcules solo en el cliente.

Para patrones específicos de jugador, véase Agregar Lógica de Jugador. Para el lado ECS del mundo, véase Entidades y Componentes.