高级语言参考

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 到 count 但不包含 count”的循环时：

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

.. 范围是包含端点的。 ..< 范围不包含上界。

反向循环使用 #reverse:

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

哈希表

使用 Hashtable(键类型, 值类型) 当你需要按键快速查找时使用。它支持整数和字符串键，以及用于查找、插入、覆盖、删除和迭代的常用方法。

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

使用 add 当重复键应触发断言时使用。使用 add_or_overwrite 当预期要更新已有键时使用。 try_add 返回 true 如果键已存在则返回失败，并保持旧值不变。

闭包、回调和 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_references/ 文件夹，其中包含当前的核心 API。打开对应的 .csl_engine 文件即可查看某个类型或过程。