语言基础

CSL 基本类型、枚举、结构体、类、引用和多态。

本页介绍 CSL 的“数据建模”一侧：原始类型、结构体/类，以及你将用来清晰表示游戏状态的模式。

如果你是新手，请先看 CSL 入门. 本页假定你已经知道如何声明变量并编写 proc/method.

原始类型

数字和布尔值

• 有符号整数： s8, s16, s32, s64 （别名： int == s64)
• 无符号整数： u8, u16, u32, u64 （别名： uint == u64)
• 浮点数： f32 （别名： float), f64
• 布尔值： bool

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

CSL 在安全时会扩大数字类型：较小的有符号整数可以变为更大的有符号整数，较小的无符号整数可以变为更大的无符号整数，当目标类型能够容纳完整范围时，无符号整数可以变为更大的有符号整数，并且 f32 可以变为 f64.

字符串

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

结构体可以继承其他结构体。复合字面量会先包含继承来的字段：

Base_Stats :: struct {
    health: int;
}

Enemy_Stats :: struct : Base_Stats {
    speed: float;
}

stats: Enemy_Stats = {100, 4.5};

何时使用结构体

• 描述符/配置对象（*_Desc)
• 小型、独立的状态，你希望按值复制
• 你想嵌入到另一种类型中的数据

何时不要使用结构体

• 在多个系统之间共享的大型可变状态（用类）
• “身份”对象（玩家、物品、长期存在的对象）（用类）

类（引用类型）

类是引用类型。使用 new(...).

Enemy :: class {
    health: int = 50;
    target: v2 = {0, 0};
}

e := new(Enemy);

继承

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

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

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

派生类会继承默认字段值。它们可以在类体中用 field = value 覆盖继承来的默认值：

Weapon_Definition :: class {
    damage: int = 10;
}

Rocket_Definition :: class : Weapon_Definition {
    damage = 100;
    splash_radius: float = 3.0;
}

当存在真正的“is-a（是一个）”关系时使用继承。对于大多数游戏玩法数据来说，组合（字段）更简单，也更容易维护。

数组、切片和动态数组

你会看到三种常见形式：

• 固定数组: [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) 或 cast(T)expr:

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

当目标类型已经已知时， expr.() 和 cast expr 会推断目标类型。

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

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

value.#type 会返回类值的运行时类型。当你从基类向下转换时，如果精确的派生类型很重要，请先使用它。

实用建模指南

• 每个玩家的状态保存在 Player. 如果它在不同玩家之间应该不同，就不应该是全局的。
• 描述符优先使用小型结构体 并将运行时状态存放在类/组件中。
• 在共享的预测路径中运行游戏逻辑。 不要只在 is_local() 下计算游戏状态，也不要用 Game.is_server().

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