游戏引擎 / 系统课时
拆分一套角色控制脚本
拆分一套角色控制脚本
输入处理、位移计算和节点显示挤在同一个 update 里,修改一处很难判断影响。本节实现按住移动、松开停止的最小角色控制,把纯逻辑控制器与 Cocos 输入和位置适配分开,先验证位移与状态,再在真实 UI 场景检查接入。
学习目标
- 根据输入、移动、状态与表现划分职责。
- 独立验证角色控制器,避免纯逻辑依赖场景。
- 正确处理触摸取消与组件停用后的移动状态。
把最小需求写成可验收行为
按住指定 UI 区域后,角色沿局部 x 方向以固定速度移动;松开、触摸取消或组件停用后停止。控制器保存坐标与是否移动,输入适配把真实事件转成布尔动作,表现适配把计算结果写回节点。这个最小版本不加入跳跃、碰撞或动画,先保证责任边界稳定。
同一字段应有唯一所有者:控制器拥有本例 x 坐标,组件只在初始化时设置起点并消费快照。如果物理系统或动画也写同一坐标,必须另行协调,不能让多个系统互相覆盖后再用每帧重置修补。本例的 UI 按钮与移动角色是两个不同节点。

先让控制器独立运行
文件:controller.ts,完整纯 TypeScript 模块。
export class Controller {
private x = 0;
private moving = false;
constructor(private readonly speed: number) {
if (!Number.isFinite(speed) || speed < 0) throw new Error('invalid speed');
}
resetX(x: number): void {
if (!Number.isFinite(x)) throw new Error('invalid x');
this.x = x;
}
setMoving(active: boolean): void { this.moving = active; }
tick(dt: number): void {
if (!Number.isFinite(dt) || dt < 0) throw new Error('invalid dt');
if (this.moving) this.x += this.speed * dt;
}
snapshot(): { x: number; state: 'idle' | 'run' } {
// 新快照隔离内部状态,表现层只消费结果。
return { x: this.x, state: this.moving ? 'run' : 'idle' };
}
}控制器本身不打印。文件:main.ts,两文件一起 strict 编译后执行 dist/main.js。
import { Controller } from './controller';
const role = new Controller(100);
role.setMoving(true);
role.tick(0.25); role.tick(0.75);
console.log(JSON.stringify(role.snapshot()));
// 松开以后,继续推进时间也不改变坐标。
role.setMoving(false); role.tick(1);
console.log(JSON.stringify(role.snapshot()));预期输出:
{"x":100,"state":"run"}
{"x":100,"state":"idle"}接入触摸和节点表现
文件:RoleDriver.ts,片段示例,依赖 Creator 3.8 与同目录 controller.ts。
import { _decorator, Component, Node } from 'cc';
import { Controller } from './controller';
const { ccclass, property } = _decorator;
@ccclass('RoleDriver')
export class RoleDriver extends Component {
@property(Node)
inputNode: Node | null = null;
private model = new Controller(100);
onLoad(): void { this.model.resetX(this.node.position.x); }
onEnable(): void {
if (!this.inputNode) { console.error('inputNode missing'); return; }
this.inputNode.on(Node.EventType.TOUCH_START, this.move, this);
this.inputNode.on(Node.EventType.TOUCH_END, this.stop, this);
this.inputNode.on(Node.EventType.TOUCH_CANCEL, this.stop, this);
}
onDisable(): void {
this.inputNode?.off(Node.EventType.TOUCH_START, this.move, this);
this.inputNode?.off(Node.EventType.TOUCH_END, this.stop, this);
this.inputNode?.off(Node.EventType.TOUCH_CANCEL, this.stop, this);
// 停用也要释放业务输入状态,避免恢复后继续跑。
this.model.setMoving(false);
}
private move(): void { this.model.setMoving(true); }
private stop(): void { this.model.setMoving(false); }
update(dt: number): void {
this.model.tick(dt);
const p = this.node.position;
this.node.setPosition(this.model.snapshot().x, p.y, p.z);
}
}预期结果:Canvas 下创建角色 Sprite 并挂 RoleDriver,再创建有 UITransform 的可见触摸区域,拖到 Inspector 的 inputNode。角色初始 x 设为零,保存并预览,按住区域约一秒后角色沿局部 x 移动约 100 单位,松开停止;实际测量随触摸时长变化。
验证职责与失效边界
触摸取消也要停止,否则手指移出或交互被取消时,角色可能一直保持移动。停用 RoleDriver 后输入不再影响状态,重新启用不应恢复旧按住状态。测试应使用同一个预览实例的启停,重新开始预览只会创建新对象,无法证明旧状态已清理。
如果没有移动,先核对 inputNode 引用、UITransform 尺寸和事件是否到达,再核对组件是否启用,最后观察控制器快照与节点写入。位移错误则先比较累计时间,再检查坐标系与其他位置写入者。按这条数据链排查,能把输入失败与计算失败分开。
后续增加角色能力时,优先把与节点无关的规则放进控制器或独立能力对象,表现仍留在组件。配置速度也可以作为初始化参数注入,但不要让控制器自行读取 Inspector。
角色组件开始时把节点的局部坐标传给控制器,使场景配置的起点和模型保持一致;如果模型固定从零开始而场景角色位于其他位置,第一帧就会跳回零。运行中传送角色也应通过同一坐标所有者更新,不能只修改节点而忽略模型快照。
本例只支持一个明确的触摸输入源。多指同时操作时,需要记录触摸身份或采用独立输入服务,否则一根手指松开可能停止另一根仍按住的输入。先满足单输入需求,再扩展输入协议,避免为尚未出现的能力堆叠复杂分支。
模块拆分的验收还包括依赖方向:controller.ts 不导入 RoleDriver,RoleDriver 不复制积分公式,输入回调不直接改角色坐标。这样一旦位移规则需要调整,修改点就集中在控制器;引擎事件变化则集中在适配层。Node 触摸规则见 Cocos 3.8 Node 事件,位置访问见 节点与组件。