游戏引擎 / 系统课时

拆分一套角色控制脚本

拆分一套角色控制脚本

输入处理、位移计算和节点显示挤在同一个 update 里,修改一处很难判断影响。本节实现按住移动、松开停止的最小角色控制,把纯逻辑控制器与 Cocos 输入和位置适配分开,先验证位移与状态,再在真实 UI 场景检查接入。

学习目标

  • 根据输入、移动、状态与表现划分职责。
  • 独立验证角色控制器,避免纯逻辑依赖场景。
  • 正确处理触摸取消与组件停用后的移动状态。

把最小需求写成可验收行为

按住指定 UI 区域后,角色沿局部 x 方向以固定速度移动;松开、触摸取消或组件停用后停止。控制器保存坐标与是否移动,输入适配把真实事件转成布尔动作,表现适配把计算结果写回节点。这个最小版本不加入跳跃、碰撞或动画,先保证责任边界稳定。

同一字段应有唯一所有者:控制器拥有本例 x 坐标,组件只在初始化时设置起点并消费快照。如果物理系统或动画也写同一坐标,必须另行协调,不能让多个系统互相覆盖后再用每帧重置修补。本例的 UI 按钮与移动角色是两个不同节点。

角色控制职责边界

先让控制器独立运行

文件:controller.ts,完整纯 TypeScript 模块。

ts
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。

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

预期输出:

text
{"x":100,"state":"run"}
{"x":100,"state":"idle"}

接入触摸和节点表现

文件:RoleDriver.ts,片段示例,依赖 Creator 3.8 与同目录 controller.ts。

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 事件,位置访问见 节点与组件。

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

目录与阅读设置

阅读设置

17

记录一个想法

拆分一套角色控制脚本

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

登录哪都通