游戏引擎 / 系统课时

用类型标注描述游戏状态

用类型标注描述游戏状态

角色血量、背包和移动状态往往挤在一个对象里,字段拼错或混入字符串后,错误才在界面刷新时出现。本节用基础类型、数组、对象与联合类型描述一个小型角色状态,让调用方在修改数据时就获得清晰反馈。

学习目标

  • 为状态边界选择准确的基础类型、数组与对象结构。
  • 使用有限联合类型限制状态值。
  • 分清静态类型约束与业务数值校验。

先确定数据允许什么值

血量是 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;其余纯逻辑主例程采用同样方式。

ts
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(','));

预期输出:

text
0|false|idle
potion

hurt 的参数不接受字符串伤害;motion 也不能随意写成 running。死亡时把移动状态归为 idle 是业务规则,并非联合类型自动完成的行为。这里把几个关联字段集中修改,避免 hp 为零而 alive 仍为 true 的矛盾状态。

数组和对象仍然会被修改

string[] 表示每个元素都是字符串,不代表数组永远只有一件道具,也不保证非空。读取不存在的数组索引仍可能得到 undefined,业务代码应先检查长度或查找结果。对象结构则约束所需字段,不能代替血量范围、道具唯一性等条件。

const 固定变量绑定,通常不冻结它引用的对象。例中 player 仍可以被 hurt 改写,items 也可以追加元素。若要求不可修改的输入,可在函数签名使用 readonly 约束调用方式;运行时冻结对象是另一项需要明确选择的操作。

把检查放在输入边界

练习把伤害改为负数,观察函数主动抛错;把调用参数改为字符串,则应在编译阶段被拒绝。前者说明值域校验有效,后者说明类型边界有效。不要用类型断言把字符串强行声明为 number,那不会把真实内容转换成数值。

本例描述内存中的可信状态。来自 JSON、网络或存档的数据还需要解析和校验后才能交给 hurt。把“类型检查通过”和“输入值有效”分开,才能准确判断问题应在编译期修复还是在运行边界处理。基础类型规则见 TypeScript Everyday Types。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用类型标注描述游戏状态

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通