Расширенная справка по языку

CSL предоставляет несколько «похожих на массив» инструментов, покрывающих большинство игровых задач: фиксированные массивы, срезы и динамические массивы. Эта страница — практическое руководство по их использованию без опасных ошибок.

Быстрый глоссарий

• Фиксированный массив: [N]T — размер известен во время компиляции.

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

• Динамический массив: [..]T — изменяемый список с количеством и вместимостью.

fixed: [4]int = {1, 2, 3, 4};
view: []int = fixed; // представление (срез)

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

Методы динамических массивов используют -> (например, list->append(x)). Поля используют . (например, list.count).

Динамические массивы ([..]T)

Динамические массивы — это «списочный тип по умолчанию» для игрового кода.

Создание и добавление

players_seen: [..]string;
players_seen->append(player->get_user_id());

Резервирование вместимости (производительность)

Если вы знаете, что добавите много элементов, сначала зарезервируйте место, чтобы избежать повторных перераспределений.

results: [..]Enemy;
results->reserve(128);

Удаление элементов

Обычно вы выбираете между быстрым удалением (порядок не важен) и упорядоченным удалением (с сохранением порядка).

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

values->unordered_remove_by_value(20); // меняет местами с последним, быстро
values->ordered_remove_by_value(10);   // сдвигает, сохраняет порядок

Также можно удалить по индексу:

values->unordered_remove_by_index(0);
values->ordered_remove_by_index(0);

Очистка

values->clear(); // O(1): просто устанавливает count в 0

Передача массивов в процедуры

Многие API принимают []T (срез/представление). Динамические массивы можно передавать там, где []T ожидается.

sum :: proc(arr: []int) -> int {
    total := 0;
    for v: arr {
        total += v;
    }
    return total;
}

nums: [..]int;
nums->append(1);
nums->append(2);
nums->append(3);

total := sum(nums); // неявное [..]int -> []int

Шаблоны итерации

Итерация по элементам

for v: nums {
    log_info("v=%", {v});
}

Итерация по индексам (включительные диапазоны)

0..n-1 обычно используется для «слотовых» циклов:

for i: 0..inventory.capacity-1 {
    item := inventory->get_item(i);
    if item == null continue;
    // ...
}

Диапазоны включительные. Если вам нужен типичный цикл «0 до count-1», напишите 0..count-1.

Замыкания, колбэки и userdata (важно)

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

Когда нужны колбэки (обработчики UI, хук смерти и т. п.), свяжите колбэк с userdata: Object полем.

Button_Handler :: class {
    clicks: int;
}

UI_Button :: class {
    on_click_userdata: Object;
    on_click: proc(userdata: Object);
}

setup :: proc(btn: UI_Button, handler: Button_Handler) {
    btn.on_click_userdata = handler;
    btn.on_click = proc(userdata: Object) {
        h := userdata.(Button_Handler);
        h.clicks += 1;
    };
}

Справочник API

Каждый проект включает папку api_reference/ , содержащую последнюю версию основной поверхности API. Если вы пытаетесь найти «какие методы существуют у этого типа?», эта папка является источником истины.