Начало работы с CSL

CSL — собственный язык программирования All Out, созданный, чтобы писать многопользовательские игры было так же просто, как создавать одиночные игры.

CSL — это собственный скриптовый язык All Out. Он статически типизирован и по ощущениям ближе всего к Go/Odin — за исключением состояние игрового процесса автоматически синхронизируется с сервера на клиенты.

Вам не нужно писать RPC, SyncVar'ы или собственную репликацию. Сосредоточьтесь на логике игрового процесса; платформа позаботится о сетевом взаимодействии.

Ваш первый скрипт (main.csl)

Когда вы создаёте новый проект, All Out генерирует main.csl в каталоге вашего проекта scripts/ папку.

import "core:ao"

// ============================================================================
// Глобальный жизненный цикл
// ============================================================================

ao_before_scene_load :: proc() {
    // Регистрирует определения предметов, валюты и т.д.
    // Выполняется до создания сцены.
}

ao_start :: proc() {
    // Вызывается один раз при старте сцены.
}

ao_update :: proc(dt: float) {
    // Вызывается каждый кадр.
}

ao_late_update :: proc(dt: float) {
    // Вызывается каждый кадр после ao_update.
}

// ============================================================================
// Жизненный цикл игрока
// ============================================================================

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

    ao_update :: method(dt: float) {
    }

    ao_late_update :: method(dt: float) {
    }

    ao_end :: method() {
    }
}

Например, выводите сообщение в лог, когда каждый игрок присоединяется:

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

Если вам нужно более подробное объяснение того, когда эти функции выполняются, см. Жизненный цикл игры/кадра.

Импорты

Ваш main.csl должен импортировать core:ao и любые папки, которые вы создаёте (например ui/, abilities/, и т.д.).

import "core:ao"
import "ui"

В большинстве проектов импорт в main.csl только. Не разбрасывайте импорты по множеству файлов — в конце концов вы получите запутанные проблемы с порядком/видимостью.

Объявления (переменные и константы)

Объявления связывают имя со значением.

Переменные

// Общая форма
<name>: <type> = <expression>;

Либо <type> или <expression> можно опустить:

// Явный тип
my_value: int = 42;

// Выведение типа
my_value := 42; // выведено как int

// Нулевая инициализация (аналогично my_value := 0;)
my_value: int;

Константы

Константы используют :: и должны быть вычислены во время компиляции:

PI :: 3.14159265359;
MAX_PLAYERS :: 12;

Это недопустимо (потому что a не является константой времени компиляции):

a := 123;
b :: a; // ошибка компиляции

Типы

Примитивные типы

• Знаковые целые: s8, s16, s32, s64

• Беззнаковые целые: u8, u16, u32, u64

• Булевы: b8, b16, b32, b64

• Вещественные: f32, f64

• Псевдонимы:

  • int == s64

  • uint == u64

  • bool == b8

  • float == f32

• Векторы: v2, v3, v4

• string

• typeid

• any

Типы векторов

v2 имеют .x, .y; v3 добавляют .z; v4 добавляют .w — все поля типа float:

pos: v2 = {10, 20};        // x=10, y=20
color: v4 = {1, 0, 0, 1};  // красный с alpha=1
offset := v3{1, 4, 9};     // вывод типа

Структуры и классы

Структуры являются типами-значениями (копируются при присваивании). Классы являются ссылочными типами (вы их выделяете с помощью new).

Структуры (типы-значения)

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

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

Классы (ссылочные типы)

Foo :: class {
    value: int;
    position: v2;
}

foo := new(Foo);
foo.value = 123;
foo.position = {12, 34};

Наследование

Структуры/классы могут наследоваться от других структур/классов:

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

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

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

Процедуры и методы

Процедуры (proc)

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

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

Процедуры — обычные значения и могут быть присвоены/храниться как любые другие значения:

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

Методы (method)

Используйте method() внутри структуры/класса. У методов есть неявный this параметр-ссылка.

Dog :: class {
    name: string;

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

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

Доступ к полю vs вызов метода

Используйте . для полей — -> для методов:

hp := player.health;        // доступ к полю
player->respawn();          // вызов метода
entity->set_local_scale({2, 2});

Любую процедуру можно вызвать как «метод», если её первый параметр совпадает с типом приёмника. Это распространённый шаблон в CSL.

Массивы

В CSL есть несколько типов «похожих на массив» структур, которые вы будете постоянно использовать:

• Фиксированные массивы: [4]int

• Срезы / управляемые массивы: []T (часто используются как «просмотр только для чтения» в массиве)

• Динамические массивы: [..]T (изменяемый список)

• Неуправляемые массивы: [^]T (используются в сигнатурах встроенного API, таких как format_string, log_info, и т.д. — передавайте значения как {a, b, c})

Динамические массивы предоставляют .data, .count, и .capacity, и используют синтаксис вызова метода для операций:

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

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

Для полного руководства (включая шаблоны удаления) см. Массивы и коллекции.

Управление потоком выполнения

If / else

if hp <= 0 {
    die();
} else if hp < 25 {
    Notifier.notify(player, "Low health!");
} else {
    // всё в порядке
}

Switch

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:      return {0.3, 0.5, 1.0, 1.0};
        case .EPIC:      return {0.7, 0.3, 0.9, 1.0};
        case .LEGENDARY: return {1.0, 0.8, 0.2, 1.0};
    }
    return {1, 1, 1, 1};
}

While / for / foreach

while condition {
    // ...
}

// Включающий диапазон: 0..9 включает 9
for i: 0..9 {
    log_info("i=%", {i});
}

// Итерация по элементам массива/среза
for item: my_items {
    // ...
}

// С переменной индекса
for item, i: my_items {
    log_info("item % at index %", {item, i});
}

// Итерация по пользовательским итераторам (часто для сущностей/компонентов)
foreach enemy: component_iterator(Enemy) {
    enemy->update_ai();
}

Приведение типов

Используйте expr.(T) для приведения:

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

Передача по ссылке: ref (предпочтительно)

Когда нужно изменить параметр, предпочитайте ref сырым указателям.

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

Обратные вызовы: указатели на функции + userdata (замыканий нет)

В CSL нет замыканий. Встроенные proc(...) { ... } не могут захватывать внешние переменные.

Чтобы нести контекст, сочетайте колбэки с userdata: Object полем:

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

    die :: method() {
        if 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;
        };
    }
}

Информация о типах (типы как значения)

typeid значения могут передаваться в полиморфные процедуры:

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}

Лучшие практики (CSL в All Out)

• Избегайте глобального состояния игрового процесса. К нескольким игрокам подключаются — храните состояние на игрока в Player вместо этого.

• Разделяйте косметическую и игровую логику. Используйте is_local() для локального UI/частиц, и is_local_or_server() для игровых вводов, которые должны выполняться на сервере и локальном клиенте.

• По умолчанию ориентируйтесь на мобильные устройства. Не полагайтесь на ввод с клавиатуры/мыши, если ваша игра явно не ориентирована на ПК.

• Если вы не уверены в синтаксисе или API, проверьте api_reference/ папку, сгенерированную в вашем проекте (она содержит актуальную версию core.csl surface).