游戏引擎 / 系统课时
串起事件与角色状态切换
串起事件与角色状态切换
移动输入和攻击输入同时到达时,角色不应把攻击状态随意覆盖成待机。本节建立带类型的动作协议,用一个转移函数集中决定状态变化,再把真实 UI 输入接进该入口,使事件、规则与显示各自保持明确职责。
学习目标
- 用联合类型表达动作与状态各自的数据。
- 在统一转移函数中处理冲突动作。
- 验证事件序列与 Cocos 输入接入产生一致状态。
先规定冲突动作怎样处理
本例只有待机、移动和攻击。移动动作决定待机或移动;攻击动作必须提供非空目标;攻击期间忽略移动动作;结束攻击后回到待机。规则刻意保持简单,事件到达并不表示一定改变状态,是否接受由转移函数决定。
动作表示请求发生什么,状态表示当前处于什么条件,二者不应共用一个任意字符串。攻击状态需要 targetId,攻击动作也需要 targetId,但结束动作不需要目标。判别字段使每个分支只访问合法字段,避免到处填空字符串来凑统一对象。

让纯函数决定下一状态
文件:state.ts,完整纯 TypeScript 模块。
export type State = { kind: 'idle' } | { kind: 'run'; speed: number }
| { kind: 'attack'; targetId: string };
export type Action = { kind: 'move'; active: boolean }
| { kind: 'attack'; targetId: string } | { kind: 'finish' };
export function transition(state: State, action: Action): State {
switch (action.kind) {
case 'move':
// 攻击锁定期间不被移动输入覆盖。
if (state.kind === 'attack') return state;
return action.active ? { kind: 'run', speed: 100 } : { kind: 'idle' };
case 'attack':
if (!action.targetId) throw new Error('target missing');
return { kind: 'attack', targetId: action.targetId };
case 'finish':
return state.kind === 'attack' ? { kind: 'idle' } : state;
default: {
const missing: never = action;
throw new Error(`unhandled:${JSON.stringify(missing)}`);
}
}
}
export function describe(state: State): string {
return state.kind === 'attack' ? `attack:${state.targetId}` : state.kind;
}下面入口提供一条完整事件序列。文件:main.ts,与 state.ts 一起 strict 编译并运行。
import { transition, describe } from './state';
import type { State, Action } from './state';
let state: State = { kind: 'idle' };
const actions: Action[] = [
{ kind: 'move', active: true }, { kind: 'attack', targetId: 'e1' },
{ kind: 'move', active: false }, { kind: 'finish' },
];
// 同一入口消费全部动作,没有订阅者自行改写状态。
for (const action of actions) { state = transition(state, action); console.log(describe(state)); }预期输出:
run
attack:e1
attack:e1
idle把 UI 事件转换成动作
文件:RoleActions.ts,片段示例,依赖 Creator 3.8 与同目录 state.ts。这里两个 UI 区域分别切换移动和攻击;攻击区再次点击表示结束,便于独立验证状态规则。
import { _decorator, Component, Node } from 'cc';
import { transition, describe } from './state';
import type { State, Action } from './state';
const { ccclass, property } = _decorator;
@ccclass('RoleActions')
export class RoleActions extends Component {
@property(Node) moveNode: Node | null = null;
@property(Node) attackNode: Node | null = null;
private state: State = { kind: 'idle' };
onEnable(): void {
if (!this.moveNode || !this.attackNode) { console.error('input missing'); return; }
this.moveNode.on(Node.EventType.TOUCH_END, this.move, this);
this.attackNode.on(Node.EventType.TOUCH_END, this.attack, this);
}
onDisable(): void {
this.moveNode?.off(Node.EventType.TOUCH_END, this.move, this);
this.attackNode?.off(Node.EventType.TOUCH_END, this.attack, this);
this.state = { kind: 'idle' };
}
private dispatch(action: Action): void {
this.state = transition(this.state, action);
console.log(describe(this.state));
}
private move(): void { this.dispatch({ kind: 'move', active: this.state.kind !== 'run' }); }
private attack(): void {
// 示例用再次点击结束,真实动画完成也应派发同一 finish 动作。
this.dispatch(this.state.kind === 'attack' ? { kind: 'finish' }
: { kind: 'attack', targetId: 'e1' });
}
}预期结果:Canvas 下创建两个可点击 UI 节点,各有 UITransform,挂载 RoleActions 到活动管理节点,将两节点拖入对应 Inspector 字段。保存预览后依次点击移动、攻击、移动、攻击,控制台状态与纯逻辑的四行输出一致。
给实际事件链保留单一修改入口
这个组件只验证动作接入,没有播放攻击动画。接入动画时应在真实完成回调派发 finish,并确认旧动画完成事件是否仍属于当前攻击。输入订阅者、动画订阅者与表现刷新者都应围绕同一状态所有者,不能各自保存一份并独立转移。
如果状态没有变化,先查看动作是否被发出,再查看转移规则是否选择忽略。攻击中的移动被忽略是预期行为,不是事件丢失。正式日志应同时记录旧状态、动作与新状态,避免仅打印最终状态难以解释冲突。
纯函数收到新的 attack 动作会更新攻击目标,这是本例协议允许的行为;UI 适配则把再次点击攻击区转成 finish。适配选择与领域允许范围是不同层次,接入其他输入来源时要明确是否允许换目标,不能假设所有来源都等同于按钮切换。
状态函数本身不发事件、不写节点,也不修改原快照。调用者获得结果后,可以通知表现层播放对应效果;如果表现层也再调用转移函数,就可能形成重复状态推进。保持状态所有者唯一,能让一个动作只有一条可解释的处理链。
验证扩展不会破坏边界
练习在待机时派发 finish,状态应仍为待机;提供空目标时应失败而不生成无目标攻击。新增 hurt 等动作时,穷尽检查会暴露遗漏处理分支,但不能替你决定转移规则。类型负责合法结构,业务函数负责允许的变化。
引擎事件身份与清理见 Cocos 3.8 事件,判别联合见 TypeScript Narrowing。纯逻辑输出和真实 UI 输入是两项独立验证,只有都吻合才说明这条接入链完整。