语言基础

在这些文档中，我们将 CSL 与围绕它的运行时/平台交替使用称呼

此页面是 CSL 的“数据建模”部分：原语、结构体/类，以及用于清晰表示游戏状态的模式。

如果你是全新开始，请从 CSL 入门开始。本页假定你已经知道如何声明变量和编写 proc/method.

原始类型

数字和布尔值

• 有符号整数： s8, s16, s32, s64 （别名： int == s64)

• 无符号整数： u8, u16, u32, u64 （别名： uint == u64)

• 浮点数： f32 （别名： float), f64

• 布尔值： b8 （别名： bool), b16, b32, b64

health: int = 100;
speed: float = 6.5;
is_dead: bool = false;

字符串

string 常用于 ID、名称和格式化。

item_id := "sword";
log_info("picked up %", {item_id});

向量

v2, v3, v4 是内建的数学/数据类型：

pos: v2 = {10, 20};
color: v4 = {1, 0, 0, 1};

枚举

枚举非常适合可读的“模式/状态”字段：

Game_Phase :: enum {
    LOBBY;
    RUNNING;
    POST_GAME;
}

phase := Game_Phase.LOBBY;

if phase == .RUNNING {
    // ...
}

当编译器能推断出枚举类型时，枚举值通常用简写引用为 .VALUE 。

结构体（值类型）

对要廉价复制的“纯数据”使用结构体（配置、小状态块、描述符）。

Damage_Desc :: struct {
    amount: int;
    knockback: v2;
}

hit := Damage_Desc{amount=10, knockback={2, 1}};

何时使用结构体

• 描述符/配置对象（*_Desc)

• 想按值复制的小型、自包含的状态

• 想嵌入到另一个类型中的数据

何时不使用结构体

• 跨多个系统共享的大型可变状态（使用类）

• “身份”对象（玩家、物品、长生命周期对象）（使用类）

类（引用类型）

类是引用类型。使用以下方式创建实例 new(...).

Enemy :: class {
    health: int;
    target: v2;
}

e := new(Enemy);
e.health = 50;
e.target = {0, 0};

继承

你可以从其他结构体/类继承：

Weapon_Definition :: class {
    id: string;
    name: string;
}

Gun_Definition :: class : Weapon_Definition {
    fire_rate: float;
}

当存在真实的“是一个”关系时使用继承。对于大多数游戏数据，组合（字段）更简单且更易维护。

数组、切片和动态数组

你会看到三种常见形式：

• 固定数组: [N]T （编译时大小）

• 切片 / 管理数组: []T （数组的视图）

• 动态数组: [..]T （可调整大小的列表）

示例：

spawn_points: [4]v2 = {{0,0}, {5,0}, {0,5}, {5,5}};

alive_enemy_ids: [..]int;
alive_enemy_ids->append(123);
alive_enemy_ids->append(456);

完整指南见 数组和集合.

按引用传递（ref)

如果过程需要修改一个值，请使用 ref:

apply_damage :: proc(health: ref int, amount: int) {
    health -= amount;
}

hp := 100;
apply_damage(ref hp, 10);

这对逐步裁剪/缩小矩形的“布局式” API 特别有用：

draw_panel :: proc(rect: ref Rect) {
    header := rect->cut_top(50);
    draw_header(header);
    // rect 现在是用于内容的剩余区域
}

类型转换

使用 expr.(T):

f := 12.7;
i := f.(int);    // 12
f2 := i.(float); // 12.0

类型多态（类似泛型的过程）

CSL 使用以下方式支持多态过程 $ 以在调用处推断类型：

min :: proc(a: $T, b: T) -> T {
    if a < b return a;
    return b;
}

a := min(10, 20);       // T == int
b := min(1.25, 3.5);    // T == float

类型作为值（typeid)

typeid 是在运行时和/或用于多态调用时表示类型的值：

default_of :: proc($T: typeid) -> T {
    t: T;
    return t;
}

zero := default_of(int);
empty := default_of(string);

实用建模指南

• 每个玩家的状态存放在 Player. 如果它在玩家之间应有所不同，就不应是全局的。

• 偏好使用小型结构体作为描述符 并将运行时状态存储在类/组件中。

• 保持服务器权威数据的权威性。 如果它影响游戏玩法，不要只在客户端计算它。

有关玩家特定模式，请参见 添加玩家逻辑。对于世界的 ECS 方面，请参见 实体与组件.