游戏引擎 / 系统课时
用输入让角色向前移动
用输入让角色向前移动
本课让 3D 角色同时接受键盘方向键和单指拖动输入,将二维操作方向转换为 XZ 平面位移。完成后,按住 W 或向上拖动即可前进,松开就停止;对角移动不会比直线更快,且不同帧率下速度基本一致。
学习目标
- 监听键盘按下、松开和触摸拖动事件,并正确注销监听。
- 把输入转换为角色局部 XZ 平面的方向和位移。
- 使用
deltaTime、速度上限和触控死区验证移动手感。
确定方向和运动规则
准备一个能在预览中看见的 Player 3D 节点,并将它放在一个斜视角摄像机能观察到的位置。示例采用父节点未旋转的水平场景:X 轴代表左右,Y 轴代表高度,-Z 代表前进。按 W 或上方向键取 z=-1,按 S 或下方向键取 z=+1;A、D 改变 x。
触控采用简化的“按下位置为摇杆中心”方案:从落点向上拖动得到前进方向,左右拖动得到横向方向,松开即归零。拖动不足 15 像素不移动,80 像素达到最大输入强度。键盘与触控方向相加后限制总强度,最终按方向、速度和每帧时长计算位移。

编写完整的角色移动组件
在资源管理器中新建 TypeScript 组件 SimpleMover.ts,将以下代码完整替换进去。使用 Cocos Creator 3.8 的 input 全局事件接口;在 onEnable 注册,在 onDisable 注销,避免脚本停用后继续接收按键或触摸。
import {
_decorator, Component, EventKeyboard, EventTouch,
input, Input, KeyCode, Vec3
} from 'cc';
const { ccclass, property } = _decorator;
@ccclass('SimpleMover')
export class SimpleMover extends Component {
@property
speed = 3;
private keys = new Set<KeyCode>();
private touchId: number | null = null;
private originX = 0;
private originY = 0;
private dragX = 0;
private dragZ = 0;
private position = new Vec3();
onEnable() {
input.on(Input.EventType.KEY_DOWN, this.onKeyDown, this);
input.on(Input.EventType.KEY_UP, this.onKeyUp, this);
input.on(Input.EventType.TOUCH_START, this.onTouchStart, this);
input.on(Input.EventType.TOUCH_MOVE, this.onTouchMove, this);
input.on(Input.EventType.TOUCH_END, this.onTouchEnd, this);
input.on(Input.EventType.TOUCH_CANCEL, this.onTouchEnd, this);
}
onDisable() {
// 全局监听必须随组件停用移除。
input.off(Input.EventType.KEY_DOWN, this.onKeyDown, this);
input.off(Input.EventType.KEY_UP, this.onKeyUp, this);
input.off(Input.EventType.TOUCH_START, this.onTouchStart, this);
input.off(Input.EventType.TOUCH_MOVE, this.onTouchMove, this);
input.off(Input.EventType.TOUCH_END, this.onTouchEnd, this);
input.off(Input.EventType.TOUCH_CANCEL, this.onTouchEnd, this);
this.keys.clear();
this.touchId = null;
this.dragX = this.dragZ = 0;
}
private onKeyDown(event: EventKeyboard) {
this.keys.add(event.keyCode);
}
private onKeyUp(event: EventKeyboard) {
this.keys.delete(event.keyCode);
}
private onTouchStart(event: EventTouch) {
const id = event.getID();
if (this.touchId !== null || id === null) return;
this.touchId = id; // 仅追踪第一根有效手指。
const p = event.getLocation();
this.originX = p.x;
this.originY = p.y;
this.dragX = this.dragZ = 0;
}
private onTouchMove(event: EventTouch) {
if (this.touchId === null || event.getID() !== this.touchId) return;
const p = event.getLocation();
const dx = p.x - this.originX;
const dy = p.y - this.originY;
const distance = Math.hypot(dx, dy);
// 死区抗抖,超过80像素后不再增大输入。
const scale = distance < 15 ? 0 : 1 / Math.max(80, distance);
this.dragX = dx * scale;
this.dragZ = -dy * scale;
}
private onTouchEnd(event: EventTouch) {
if (event.getID() !== this.touchId) return;
this.touchId = null;
this.dragX = this.dragZ = 0;
}
update(deltaTime: number) {
const left = this.keys.has(KeyCode.KEY_A) || this.keys.has(KeyCode.ARROW_LEFT);
const right = this.keys.has(KeyCode.KEY_D) || this.keys.has(KeyCode.ARROW_RIGHT);
const forward = this.keys.has(KeyCode.KEY_W) || this.keys.has(KeyCode.ARROW_UP);
const back = this.keys.has(KeyCode.KEY_S) || this.keys.has(KeyCode.ARROW_DOWN);
let x = Number(right) - Number(left) + this.dragX;
let z = Number(back) - Number(forward) + this.dragZ;
const length = Math.hypot(x, z);
if (length === 0) return;
if (length > 1) {
x /= length;
z /= length;
}
// 在节点局部坐标中按秒累计位移,保持Y不变。
this.node.getPosition(this.position);
this.node.setPosition(
this.position.x + x * this.speed * deltaTime,
this.position.y,
this.position.z + z * this.speed * deltaTime
);
}
}预期结果(画面可见效果,而非控制台日志):
按住 W / ↑:Player 沿 -Z 方向前进,松开后停止
按住 D / →:Player 沿 +X 方向移动
同时按 W + D:角色斜向移动,总速度不超过 speed
按住屏幕并向上拖动:角色前进;松手后停止
只轻微拖动(不足15像素):角色保持静止理解输入为什么要分开处理
输入事件负责更新当前操作状态,update 才负责实际位移。这样按住键盘时,即使没有新的按键事件,角色仍然会在每帧继续移动;松开按键后,对应状态被移除,角色就停止。触控也遵循同样的原则,只是额外记录起点和当前拖动方向。
移动计算中最重要的是三个细节。
deltaTime:每帧经过的秒数。移动距离乘以它,才能让速度不直接依赖渲染帧率。- 方向长度限制:同时按下 W 和 D 时,原始向量长度大于 1,直接使用会让斜向移动更快;长度超过 1 时需要归一化。
- 触控死区:手指轻微抖动不应直接让角色移动。当前示例还限制最大输入强度,避免拖得越远角色越快。
getPosition 和 setPosition 操作的是节点相对父节点的局部位置。如果父节点发生旋转,实际世界运动方向也会跟着变化。本课先不实现相机相对移动,避免同时引入坐标变换和摄像机朝向计算。
运行验证与常见边界
将 SimpleMover 挂到 Player 上,将属性检查器中的 Speed 保持为 3,保存场景并启动预览。先点击游戏画面以确保键盘焦点在预览窗口,再分别按 W、D、W+D,并在支持触控的设备上测试拖动。
以 W 持续按住约两秒为例,在父节点不旋转、没有其他位移来源时,角色局部 Z 应减少约 6 个单位。这是位置变化的估算值,不是固定帧数;实际观察时应允许帧时长和操作时间产生少量偏差。
若角色不动,检查组件是否启用、运行窗口是否获得焦点,以及摄像机是否能看出前后位移。若方向不对,检查角色父节点是否旋转;若移动速度异常,确认没有同时挂载多个移动组件。
全局触摸在屏幕任意位置都可能生效,正式项目应改由专用虚拟摇杆区域接管触控,避免与 UI 按钮相互干扰。完成这些检查后,角色移动就具备了明确的输入来源、稳定的速度规则以及可控的监听生命周期。