Advanced Language Reference

CSL gives you a few “array-like” tools that cover most gameplay needs: fixed arrays, slices, and dynamic arrays. This page is the practical guide to using them without foot-guns.

Quick glossary

• Fixed array: [N]T — size is known at compile time.
• Slice / managed array: []T — a view over array data (often used for parameters).
• Dynamic array: [..]T — resizable list with count and capacity.

fixed: [4]int = {1, 2, 3, 4};
view: []int = fixed; // slice view

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

Dynamic array methods use normal dot calls (e.g. list.append(x)). Fields also use dot access (e.g. list.count).

Dynamic arrays ([..]T)

Dynamic arrays are the “default list” type for gameplay code.

Creating and appending

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

Reserving capacity (performance)

If you know you’ll add a lot of items, reserve first to avoid repeated reallocations.

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

Removing items

You generally pick between fast removal (order doesn’t matter) and ordered removal (preserve order).

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

values.unordered_remove_by_value(20); // swaps with last, fast
values.ordered_remove_by_value(10);   // shifts, keeps order

You can also remove by index:

values.unordered_remove_by_index(0);
values.ordered_remove_by_index(0);

Clearing

values.clear(); // O(1): just sets count to 0

Passing arrays into procedures

Many APIs accept []T (a slice/view). Dynamic arrays can be passed where []T is expected.

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); // implicit [..]int -> []int

Iteration patterns

Iterate elements

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

Iterate indices

Use ..< when you want a normal "0 up to, but not including, count" loop:

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

.. ranges are inclusive. ..< ranges exclude the upper bound.

Reverse loops use #reverse:

for i: 0..<inventory.capacity #reverse {
    item := inventory.get_item(i);
    if item == null continue;
    // ...
}

Hashtables

Use Hashtable(Key_Type, Value_Type) when you need fast lookup by key. It supports integer and string keys, along with the usual methods for lookup, insertion, overwrite, removal, and iteration.

scores: Hashtable(string, s64);
scores.add("alice", 10);
scores.add_or_overwrite("bob", 25);

score, ok := scores.find("alice");
if ok {
    log_info("alice score: %", {score});
}

for value, key: scores {
    log_info("% = %", {key, value});
}

Use add when duplicate keys should assert. Use add_or_overwrite when updating an existing key is expected. try_add returns true if the key already existed and leaves the old value unchanged.

Closures, callbacks, and userdata (important)

CSL does not have closures. Inline proc() { ... } definitions cannot capture surrounding variables.

When you need callbacks (UI handlers, death hooks, etc), pair the callback with a userdata: Object field.

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 reference

Each project includes an api_references/ folder containing the current core API. Open the matching .csl_engine file to inspect a type or procedure.