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

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

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

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

Ваш первый скрипт (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 только. Не разбрасывайте импорты по множеству файлов — в итоге вы столкнётесь с запутанными проблемами порядка/видимости.

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

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

Переменные

// Общая форма
<имя>: <тип> = <выражение>;

Можно опустить либо <тип> или <выражение> :

// Явный тип
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

• любой

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

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

pos: v2 = {10, 20};        // x=10, y=20
color: v4 = {1, 0, 0, 1};  // красный с альфой=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).