Primeros pasos con CSL

CSL es el lenguaje de programación personalizado de All Out, creado para que escribir juegos multijugador sea tan fácil como crear juegos para un solo jugador.

CSL es el lenguaje de scripting personalizado de All Out. Es tipado estáticamente y se parece más a Go/Odin — excepto el estado de la jugabilidad se sincroniza automáticamente del servidor a los clientes.

No necesitas escribir RPCs, SyncVars ni replicación personalizada. ¡Nosotros nos encargamos de eso por ti!

Tu primer script (main.csl)

Cuando creas un nuevo proyecto, All Out genera un main.csl en tu carpeta de proyecto scripts/ folder.

import "core:ao"

// ============================================================================
// Ciclo de vida global
// ============================================================================

ao_before_scene_load :: proc() {
    // Registrar definiciones de objetos, monedas, etc.
    // Se ejecuta después de que existe la Scene vacía, antes de que se cargue el contenido de la escena.
}

ao_start :: proc() {
    // Se llama una vez cuando comienza la escena.
}

ao_update :: proc(dt: float) {
    // Se llama en cada frame.
}

ao_late_update :: proc(dt: float) {
    // Se llama en cada frame después de ao_update.
}

// ============================================================================
// Ciclo de vida del jugador
// ============================================================================

Player :: class : Player_Base {
    ao_start :: method() {
    }

    ao_update :: method(dt: float) {
    }

    ao_late_update :: method(dt: float) {
    }

    ao_end :: method() {
    }
}

Por ejemplo, registra un mensaje cuando se una cada jugador:

Player :: class : Player_Base {
    ao_start :: method() {
        log_info("hello %", {this.get_username()});
    }
}

Si quieres una explicación más profunda de cuándo se ejecutan estas funciones, consulta Ciclo de vida del juego/fotograma.

Importaciones

Tu main.csl debe importar core:ao y cualquier carpeta que crees (como ui/, abilities/, etc.).

import "core:ao"
import "ui"

Las importaciones apuntan a carpetas, no a archivos individuales. Una importación de carpeta incluye los .csl archivos de esa carpeta. Las importaciones dentro de esa carpeta se resuelven de forma relativa a ella:

// main.csl
import "core:ao"
import "abilities"

// abilities/projectiles.csl
import "helpers"

En la mayoría de los proyectos, importa en main.csl solo. No disperses importaciones por muchos archivos; tarde o temprano acabarás con problemas confusos de orden/visibilidad.

Declaraciones (variables y constantes)

Las declaraciones vinculan un nombre a un valor.

Variables

// Forma general
<nombre>: <tipo> = <expresión>;

O bien <tipo> o <expresión> puede omitirse:

// Tipo explícito
my_value: int = 42;

// Inferencia de tipos
my_value := 42; // inferido como int

// Inicialización a cero (igual que my_value := 0;)
my_value: int;

Constantes

Las constantes usan :: y deben ser constantes en tiempo de compilación. Pueden ser escalares, cadenas, tipos, valores de procedimiento, arrays o literales compuestos:

MAX_PLAYERS :: 12;

Spawn_Desc :: struct {
    name: string;
    pos: v2;
}

DEFAULT_SPAWNS: []Spawn_Desc : {
    {"Blue", {-4, 0}},
    {"Red", {4, 0}},
};

Esto no es válido (porque a no es una constante en tiempo de compilación):

a := 123;
b :: a; // error de compilación

Los inicializadores de variables globales también deben ser constantes en tiempo de compilación. Usa ao_before_scene_load o ao_start para la inicialización en tiempo de ejecución.

Variables globales

Las globales usan la misma sintaxis de declaración que las locales. Pueden dejarse inicializadas a cero o inicializadas con constantes en tiempo de compilación, incluidos structs, arrays, valores de procedimiento y typeid valores:

score_total: int;
spawn_names: []string = {"Blue", "Red"};
default_type: typeid = int;

start_round :: proc() {
}

on_match_start: proc() = start_round;

Las globales son mutables y persisten durante toda la vida útil de la instancia del script. Evita usarlas para el estado de jugabilidad por jugador.

Tipos

Tipos primitivos

• Enteros con signo: s8, s16, s32, s64
• Enteros sin signo: u8, u16, u32, u64
• Booleanos: bool
• Flotantes: f32, f64
• Alias:

  • int == s64
  • uint == u64
  • float == f32
• Vectores: v2, v3, v4
• string
• typeid
• cualquier

Los tipos vectoriales

v2 tiene .x, .y; v3 añade .z; v4 añade .w — todos los campos float:

pos: v2 = {10, 20};        // x=10, y=20
color: v4 = {1, 0, 0, 1};  // rojo con alpha=1
offset := v3{1, 4, 9};     // inferencia de tipos

Structs y clases

Los structs son tipos por valor (se copian al asignarse). Las clases son tipos por referencia (las asignas con new).

Structs (tipos por valor)

Food_Definition :: struct {
    name: string;
    food_value: int;
}

food: Food_Definition;
food.name = "Apple";
food.food_value = 10;

Clases (tipos por referencia)

Foo :: class {
    value: int = 10;
    position: v2 = {12, 34};
}

foo := new(Foo);

Los campos de clase pueden tener valores predeterminados. Una clase derivada puede sobrescribir los valores predeterminados heredados sin redeclarar el campo:

Enemy :: class {
    health: int = 100;
    speed: float = 3.0;
}

Boss :: class : Enemy {
    health = 500;
    speed = 1.5;
}

Herencia

Los structs/clases pueden heredar de otros structs/clases:

Animal :: class {
    name: string;
    age: int;
}

Dog :: class : Animal {
    breed: string;
}

dog := new(Dog);
dog.name = "Buddy";
dog.age = 5;
dog.breed = "Labrador";

Procedimientos y métodos

Procedimientos (proc)

add :: proc(a: int, b: int) -> int {
    return a + b;
}

result := add(2, 4); // 6

Los procedimientos son valores normales y pueden asignarse/almacenarse como cualquier otro valor:

op := proc(a: int, b: int) -> int { return a + b; };
op = proc(a: int, b: int) -> int { return a * b; };

Métodos (método)

Usa method() dentro de un struct/class. Los métodos tienen un parámetro implícito por referencia this de referencia.

Dog :: class {
    name: string;

    bark :: method() {
        log_info("% says bark!", {name});
    }
}

dog := new(Dog);
dog.name = "Buddy";
dog.bark();

Acceso a campos vs llamadas a métodos

Usa . tanto para campos como para métodos:

hp := player.health;        // acceso a campo
player.respawn();          // llamada a método
entity.set_local_scale({2, 2});

Cualquier procedimiento puede llamarse como un “método” si su primer parámetro coincide con el tipo del receptor. Los métodos reales y los campos de tipo valor de procedimiento tienen prioridad antes de que CSL recurra a un procedimiento libre coincidente.

Arrays

CSL tiene algunos tipos “similares a arrays” que usarás constantemente:

• Arreglos fijos: [4]int
• Slices / arreglos administrados: []T (a menudo usado como “vista de solo lectura” de un array)
• Arreglos dinámicos: [..]T (lista redimensionable)
• Arrays no gestionados: [^]T (usado en firmas de API integradas como format_string, log_info, etc. — pasa valores como {a, b, c})

Los arrays dinámicos exponen .data, .count, y .capacity, y usan sintaxis de llamada a método para las operaciones:

numbers: [..]int;
numbers.append(10);
numbers.append(20);

log_info("count: %", {numbers.count});
log_info("first: %", {numbers[0]});

Para una guía completa (incluidos los patrones de eliminación), consulta Arreglos y colecciones.

Flujo de control

Si / else

if hp <= 0 {
    die();
} else if hp < 25 {
    Notifier.notify(player, "¡Salud baja!");
} else {
    // todo bien
}

Switch

Usa default: para la cláusula predeterminada. Los cases admiten múltiples valores (separados por comas) y rangos. No hay fallthrough al estilo C.

Item_Tier :: enum {
    COMMON;
    UNCOMMON;
    RARE;
    EPIC;
    LEGENDARY;
}

get_tier_color :: proc(tier: Item_Tier) -> v4 {
    switch tier {
        case .COMMON:              return {0.7, 0.7, 0.7, 1.0};
        case .UNCOMMON:            return {0.3, 0.8, 0.3, 1.0};
        case .RARE, .EPIC:         return {0.3, 0.5, 1.0, 1.0};
        case .LEGENDARY:           return {1.0, 0.8, 0.2, 1.0};
        default:                   return {1, 1, 1, 1};
    }
}

// Casos por rango
get_difficulty :: proc(level: int) -> string {
    switch level {
        case 1..5:          return "Easy";
        case 6..<11:        return "Medium";
        case 11..20, 25:    return "Hard";
        default:            return "Unknown";
    }
}

.. incluye ambos extremos. ..< excluye el extremo superior.

While / for

while condition {
    // ...
}

// Rango inclusivo: 0..9 incluye 9
for i: 0..9 {
    log_info("i=%", {i});
}

// Rango semiabierto: 0..<count excluye count
for i: 0..<items.count {
    log_info("item %", {items[i]});
}

// Iteración inversa
for i: 0..<items.count #reverse {
    log_info("reverse item %", {items[i]});
}

// Iterar elementos de array/slice
for item: my_items {
    // ...
}

// Con variable de índice
for item, i: my_items {
    log_info("item % at index %", {item, i});
}

// Iterar iteradores personalizados (común para entidades/componentes)
for enemy: component_iterator(Enemy) {
    enemy.update_ai();
}

Basado en iterador personalizado for los bucles requieren un next :: method() -> bool y un campo .

Conversión de tipos

Usa expr.(T) o cast(T)expr Para convertir:

a := 123.4;
b := a.(int);   // 123
c := cast(float)b; // 123.0

Cuando el tipo objetivo ya se conoce, puedes dejar que CSL lo infiera:

i: int = a.;
j: int = cast a;

Pasar por referencia: ref (preferido)

Cuando necesites modificar un parámetro, prefiere ref en lugar de punteros en bruto.

update_position :: proc(pos: ref v2, velocity: v2, dt: float) {
    pos.x += velocity.x * dt;
    pos.y += velocity.y * dt;
}

my_pos := v2{0, 0};
update_position(ref my_pos, {10, 5}, 0.16);

Callbacks: punteros a funciones + userdata (sin cierres)

CSL no tiene cierres. En línea proc(...) { ... } no pueden capturar variables circundantes.

Para transportar contexto, combina los callbacks con un campo userdata: Object campo:

Player :: class : Player_Base {
    on_death_userdata: Object;
    on_death: proc(player: Player, userdata: Object);

    die :: method() {
        si on_death != null {
            on_death(this, on_death_userdata);
        }
    }
}

Death_Tracker :: class : Component {
    count: int;

    ao_start :: method() {
        player := entity.get_component(Player);
        player.on_death_userdata = this;
        player.on_death = proc(player: Player, userdata: Object) {
            tracker := userdata.(Death_Tracker);
            tracker.count += 1;
        };
    }
}

Información de tipos (tipos como valores)

typeid los valores pueden pasarse a procs polimórficos:

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

a := default_of(int);      // 0
b := default_of(string);   // ""
c := default_of([4]int);   // {0, 0, 0, 0}

Buenas prácticas (CSL en All Out)

• Evita el estado global de jugabilidad. Se conectan varios jugadores: guarda el estado por jugador en Player en su lugar.
• Dibuja toda la UI del jugador desde Player.ao_late_update. Envuélvelo en is_local_or_server().
• Usa is_local() solo para invalidaciones visuales específicas del jugador. No cambies el estado de jugabilidad ni de la UI dentro de él.
• Valores predeterminados orientados a móvil. No dependas del teclado/ratón a menos que tu juego esté explícitamente enfocado en PC.
• Si no estás seguro de la sintaxis o las API, abre el .csl_engine archivo correspondiente en api_references/ de tu proyecto.