控制(面向玩家的标记——请勿反向发出)
在编写任何使用 WASD、方向键、追尾摄像头或飞行载具的游戏的移动/转向/飞行代码之前,请完整阅读此文档。请不要跳过此步骤,仅打开 racing-kart 或 fps 文件——那些流派文件假定你已了解这些标记。反向的 A/D 是载具和飞行演示中最常见的阻碍构建的问题。
与 building-games(循环、摄像机、3D 方向)和 building-games/references/input.md(按键状态、手柄、触摸)配合使用。本技能定义了左右上下对玩家意味着什么以及你如何证明这一点。
0. 硬性规则(违反则构建失败)
- 面向玩家的左右是绝对规则。 从追尾 / 后方视角看,且载具正在向前移动时:
- A / ← → 机头(或侧倾)在屏幕上向左转
- D / → → 机头(或侧倾)在屏幕上向右转
- 切勿将 FPS 平移(strafe)复用作载具转向。 FPS 中 "D → +right vector" 是地面平面上的位置移动。载具的 A/D 是偏航(或滚转)速率,而非平移偏移。将它们混用是导致 A/D 反向的头号原因。
- 在说完成之前,你必须运行控制自检(§5)。 仅凭截图 QA 是不够的。如果按 A 向右转,则翻转转向/滚转符号,重新测试,然后发布——不要编造一个新的坐标系故事。
1. 共享 3D 基础(各处均使用此基础)
three.js:右手系,+Y 向上,网格朝向 +Z,摄像机看向 −Z。
仅 XZ 平面上的偏航角指向(地面载具、步行者、大部分街机风格的载具):
// yaw = 0 朝向世界 −Z;+yaw 围绕 +Y 逆时针旋转(机头向 −X 移动)
forward = (-sin(yaw), 0, -cos(yaw))
right = ( cos(yaw), 0, -sin(yaw)) // = normalize(cross(forward, worldUp))
使用位于载具后方的追尾摄像机(摄像机位置约 position - forward * dist):
| 玩家所见 | 世界坐标系(以此为基础) | 输入 |
|---|---|---|
| 机头向左 | +yaw | A / ← 必须产生 +yaw(或飞机等效的向左侧倾) |
| 机头向右 | −yaw | D / → 必须产生 −yaw |
如果你的坐标系不同,请保持一致的一对——但上表中面向玩家的行是强制性的。
2. 流派映射
2a. FPS / 步行(平移,而非转向)
W = +forward, S = −forward, D = +right, A = −right // 位置移动,而非偏航
鼠标:yaw -= movementX * sens; pitch -= movementY * sens; 限制 pitch
身体偏航用于视角;移动仅使用偏航(不要将俯仰应用到行走方向)。
2b. 地面 / 水上载具(卡丁车、自行车、摩托艇、船、坦克、探测车、雪地摩托)
带有 heading/yaw 和前进 speed 的街机风格实体:
// 输入(按住按键 → 每帧执行动作)
let steer = 0; // -1..+1,面向玩家
if (keys.has('KeyA') || keys.has('ArrowLeft')) steer += 1; // 左
if (keys.has('KeyD') || keys.has('ArrowRight')) steer -= 1; // 右
// 可选:steer = clamp(steer + gamepadX, -1, 1) 使用相同符号约定
// 积分(speedFactor ~ 0..1 来自 |speed|)
const reverse = speed >= 0 ? 1 : -1; // 倒车时左转感觉仍为左转
yaw += steer * turnRate * speedFactor * reverse * dt;
// 沿航向移动
const fx = -Math.sin(yaw), fz = -Math.cos(yaw);
position.x += fx * speed * dt;
position.z += fz * speed * dt;
典型错误(请勿复制):
// 错误——这正是实际中导致 A/D 反向的原因
if (KeyA) steer -= 1;
if (KeyD) steer += 1;
yaw += steer * turnRate * dt; // A → −yaw → 追尾视角下机头向右
如果你已经写了 KeyA → steer--,则要么交换按键映射,要么在积分时取反一次(yaw += -steer * …)——然后运行 §5。不要翻转两次(按键 + 积分 + 网格旋转同时翻转)。
2c. 固定翼飞行(飞机、滑翔机、遥控飞机)
| 输入 | 动作 | 玩家预期 |
|---|---|---|
| A / ← | 向左滚转(副翼) | 左翼向下 / 向左倾斜 |
| D / → | 向右滚转 | 右翼向下 / 向右倾斜 |
| W / ↑ | 俯仰(选择一种方案并在 HUD 上标示) | 通常机头向下 或 拉起——保持一致 |
| S / ↓ | 相反的俯仰 | |
| Q / E | 偏航 / 方向舵(可选) | Q 向左,E 向右 |
- A/D 不是平移,也不是“使用 FPS 符号的地面转向”。
- 在载具的本地前进轴上应用滚转,符号必须与 按 A 向左倾斜 匹配。如果网格倾斜方向错误,在滚转应用(或 A/D 到滚转的映射)上翻转一个符号,而不是整个坐标系。
- 协调转弯:正的倾斜应在追尾/外部摄像机下产生与倾斜方向匹配的转弯。
2d. 直升机 / 无人机 / 六自由度(6DOF)
在开始覆盖层上记录方案。最低要求:
- 离散按键上的油门/高度不得在按一次后“始终向上”(使用按住状态或明确的上下键)。
- 平移/偏航:在载具的水平框架内,A 向左,D 向右(面向玩家)。
2e. 2D 横版卷轴 / 平台游戏
D / → 在屏幕上向右移动;A / ← 向左移动。仅在游戏流派明确为上下颠倒时才反转重力。
3. 摄像机必须保持一致
- 追尾摄像机:
desired = craftPos + up*height + forward*(-followDist);插值;lookAt(craft)。 - 一次计算
forward并同时用于移动和摄像机——不要在摄像机路径中使用相反的偏航符号重新构建。 - 调试顺序:(1) 按键注册 → (2) 符号正确(§5)→ (3) 摄像机保持一致。
4. 输入管道(简要说明)
- 使用
event.code在keydown/keyup事件上用Set追踪按键;在blur/visibilitychange上清除。在游戏循环中使用 dt 进行移动,而不是在按键处理器中。 - 将键盘 + 触摸 + 手柄统一为动作(
throttle、steer、pitch、roll……)。请参阅building-games/references/input.md。 - 触摸:左摇杆 = 移动/转向,右摇杆 = 动作;目标区域 ≥ 44px。
5. 强制控制自检(在“完成”之前)
对于任何使用 A/D 的载具,仅凭截图是绝对不够的。
5a. 面向玩家的检查清单(每个载具 / 飞行构建)
在向前移动时(速度 > 小阈值),追尾摄像机位于后方:
| 按住 | 必须在约 0.5 秒内观察到 |
|---|---|
| A | 机头或倾斜在屏幕上向左移动 |
| D | 机头或倾斜在屏幕上向右移动 |
| W(地面) | 速度增加 / 沿面向方向移动 |
| S(地面) | 刹车或倒车(按设计) |
如果 A 失败:翻转转向/滚转符号一次,然后重新测试 A 和 D。
5b. 最小测试接口(实现此接口)
暴露一个小钩子,以便你(和自动化 QA)无需猜测私有闭包即可证明符号正确:
// 例如 src/game/controlsTest.ts —— 仅用于开发/QA 即可
export type ControlsProbe = {
getYaw: () => number; // 弧度;或 getHeading()
getSpeed: () => number;
/** 注入按住的动作而非真实按键;两者都会保持生效,直到你
* 更改它们,因此 §5c 可以在多个帧中按住一个键并在结束时清除。 */
setSteer?: (v: number) => void; // -1..1,与生产版本相同的符号
setKeys?: (codes: string[]) => void; // 按住直到下一次调用;`[]` 清除
};
declare global {
interface Window {
__controlsTest?: ControlsProbe;
}
}
当 import.meta.env.DEV 或设置了 ?qa=1 标志时,从游戏循环中连接 window.__controlsTest。
5c. 自动化烟雾测试(运行它)
使用预装的 agent-browser CLI 来驱动 §5b 的探查器——这是第一步,而不是手动编写脚本。抛出的 eval 以非零退出;仅 falsy 值不会,因此通过抛出进行断言。将其作为一次 batch 运行——一次 CLI 调用,而不是每个动词一次——从标准输入读取 JSON;--bail 在第一个失败步骤处停止并以非零退出。
agent-browser batch --bail <<'JSON' # find 的 label 区分大小写:从 `snapshot -i` 复制
[["open","http://127.0.0.1:8080/"],
["find","text","Start","click"],
["eval","if (!window.__controlsTest?.setKeys) throw Error('no §5b probe: add setKeys')"],
["eval","__controlsTest.setKeys(['KeyW'])"],
["wait","600"],
["eval","if (__controlsTest.getSpeed() <= 0.1) throw Error('W: no move')"],
["eval","(async () => { const t = __controlsTest, y0 = t.getYaw(); t.setKeys(['KeyW','KeyA']); await new Promise(r => setTimeout(r, 300)); t.setKeys(['KeyW']); const d = t.getYaw() - y0, w = Math.atan2(Math.sin(d), Math.cos(d)); if (w < -0.05) throw Error('A turns RIGHT — inverted, got ' + w.toFixed(2)); if (w <= 0.05) throw Error('A barely turned (' + w.toFixed(2) + ') — hold longer or check the sim is running'); return 'A ok' })()"],
["eval","__controlsTest.setKeys([])"],
["screenshot","/workspace/screenshots/controls.png"],
["close"]]
JSON
通过探查器按住按键,而不是用 keydown——agent-browser keydown 无法到达 §4 的 Set,因此正确的游戏也会被读取为损坏。你的探查器上没有 setKeys?添加它(§5b),或者自己分发按键事件——浏览器 QA 参考的 Keys 注释提供了机制和形式。
按住逻辑位于一个 eval 内部:如果分散在多个命令中,它持续时间就是这些命令所需的时间,并且 Math.atan2(Math.sin(d), Math.cos(d)) 中的 ±π 包裹会读取一个转弯超过 π 的载具为向另一方向转弯。IIFE 可让步骤可重运行——裸的 const d = … 在第二次会失败并提示“已声明”——而 async 可让按住操作在页面时间内运行。对 D 重复上述操作,使用 'KeyD' 并将两个比较镜像(w > 0.05 是反向,w >= -0.05 是很小的转弯),使用单引号以便 JSON 无需转义;对于飞机断言 roll:A 意味着向左倾斜。
A turns RIGHT 是符号错误:翻转一个符号并重新运行。A barely turned 不是——载具向正确方向移动,只是在 300 毫秒内少于 0.05 弧度,对于船只或重型探测车来说可能如此;增加按住时间,或检查模拟是否在运行,不要翻转任何东西。任何其他非零退出——没有探查器,守护进程卡死——意味着检查从未运行:先阅读消息。在第一次流程之前,请阅读浏览器 QA 参考 AGENTS.md 中的链接——动词、参数形式和后备方案都在那里。
5d. 不要做什么
- 不要只测试“D 增加了某个内部变量”。
- 不要使用 FPS 的“D → +X 当面向 −Z”作为载具的通过条件。
- 不要在修复时同时翻转网格侧倾、摄像机和转向——每次更改一个符号,重新测试。
6. 完成标准(控制部分)
- 在编写移动/转向/飞行代码之前打开了此技能。
- 选择了流派映射(§2)并且开始画面/HUD 标签与之匹配。
- 追尾摄像机 A/D 面向玩家的测试通过(§5a)。
-
window.__controlsTest(或等效方法)在开发/QA 中可用并被使用。 - 相对于滚转/转向输入,没有反向的侧倾网格。
- 按键是按住状态 + dt 缩放;单次按空格不会粘滞推力,除非是有意为之并已标记。
如果任何选框未选中,则游戏未完成。