游戏引擎 / 系统课时
用类型标注描述游戏状态
用类型标注描述游戏状态
角色血量、背包和移动状态往往挤在一个对象里,字段拼错或混入字符串后,错误才在界面刷新时出现。本节用基础类型、数组、对象与联合类型描述一个小型角色状态,让调用方在修改数据时就获得清晰反馈。
学习目标
- 为状态边界选择准确的基础类型、数组与对象结构。
- 使用有限联合类型限制状态值。
- 分清静态类型约束与业务数值校验。
先确定数据允许什么值
血量是 number,名字是 string,是否存活是 boolean,背包是 string 数组。移动状态只有 idle 和 run 两种,使用字符串字面量联合比任意 string 更精确。字段类型描述合法值的类别,字段名表达含义,两者都应该来自业务需求。
明确初始化值时,TypeScript 通常能推断类型,没必要给所有局部变量重复标注。函数参数、返回值和跨模块对象是优先标注的边界:调用者可以据此理解协议,修改数据时也能尽早看到影响。这里保留显式状态类型,方便辨认哪些字段可以变化。
用一个状态对象完成受伤流程
文件:main.ts,完整纯 TypeScript 程序,可用 TypeScript 5.9 严格检查,编译为 CommonJS 后在 Node.js 执行。保存文件后在该目录运行 tsc main.ts --strict --target ES2022 --module commonjs --outDir dist,再运行 node dist/main.js;其余纯逻辑主例程采用同样方式。
export {};
type Motion = 'idle' | 'run';
type PlayerState = {
name: string;
hp: number;
alive: boolean;
items: string[];
motion: Motion;
};
function hurt(player: PlayerState, damage: number): void {
// number 仍可能是 NaN 或负数,业务边界要运行时检查。
if (!Number.isFinite(damage) || damage < 0) {
throw new Error('invalid damage');
}
player.hp = Math.max(0, player.hp - damage);
player.alive = player.hp > 0;
if (!player.alive) player.motion = 'idle';
}
const player: PlayerState = {
name: 'Ada', hp: 30, alive: true,
items: ['potion'], motion: 'run',
};
hurt(player, 40);
// 输出聚焦最终状态,不依赖对象打印格式。
console.log(`${player.hp}|${player.alive}|${player.motion}`);
console.log(player.items.join(','));预期输出:
0|false|idle
potionhurt 的参数不接受字符串伤害;motion 也不能随意写成 running。死亡时把移动状态归为 idle 是业务规则,并非联合类型自动完成的行为。这里把几个关联字段集中修改,避免 hp 为零而 alive 仍为 true 的矛盾状态。
数组和对象仍然会被修改
string[] 表示每个元素都是字符串,不代表数组永远只有一件道具,也不保证非空。读取不存在的数组索引仍可能得到 undefined,业务代码应先检查长度或查找结果。对象结构则约束所需字段,不能代替血量范围、道具唯一性等条件。
const 固定变量绑定,通常不冻结它引用的对象。例中 player 仍可以被 hurt 改写,items 也可以追加元素。若要求不可修改的输入,可在函数签名使用 readonly 约束调用方式;运行时冻结对象是另一项需要明确选择的操作。
把检查放在输入边界
练习把伤害改为负数,观察函数主动抛错;把调用参数改为字符串,则应在编译阶段被拒绝。前者说明值域校验有效,后者说明类型边界有效。不要用类型断言把字符串强行声明为 number,那不会把真实内容转换成数值。
本例描述内存中的可信状态。来自 JSON、网络或存档的数据还需要解析和校验后才能交给 hurt。把“类型检查通过”和“输入值有效”分开,才能准确判断问题应在编译期修复还是在运行边界处理。基础类型规则见 TypeScript Everyday Types。