语言基础

就这些文档而言，我们将 CSL 及其运行时/平台等同指代

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

如果你是新手，先从 CSL 入门开始。本页假设你已经知道如何声明变量并编写 过程/方法.

原始类型

数字和布尔值

• 有符号整数： 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(...).

创建实例：
    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 部分，请参见 实体和组件.