控制(玩家可見標記 — 切勿使用反向設定)
在為任何使用 WASD、方向鍵、追蹤攝影機或飛行載具的遊戲撰寫移動/操控/飛行程式碼之前,請完整閱讀此內容。 請不要跳過這部分而只查看 racing-kart 或 fps —— 那些類型檔案假設你已經知道這些標記。A/D 反向是車輛和飛行示範中最常見的阻礙因素。
請搭配 building-games(迴圈、攝影機、3D 方向)和 building-games/references/input.md(按鍵按下狀態、遊戲手把、觸控)一起使用。這個技能文件定義了左/右/上對玩家而言的意義以及你如何證明它。
0. 硬性規則(違反則建置失敗)
- 玩家可見的左/右是鐵律。 從追蹤 / 後方攝影機視角,並且載具向前移動時:
- A / ← → 機頭(或傾斜)在螢幕上向左轉
- D / → → 機頭(或傾斜)在螢幕上向右轉
- 絕對不要將 FPS 的橫向移動當作車輛操控。 FPS 的「D → +右向量」是地面平面上的位置位移。車輛的 A/D 是偏航(或滾轉)速率,而不是橫向偏移。將兩者混用是造成 A/D 反向的第一大原因。
- 在說完成之前,你必須執行控制自我測試(§5)。 僅截圖驗證是不夠的。如果 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 = +前進, S = -前進, D = +右, A = -右 // 位置,非偏航
滑鼠:yaw -= movementX * sens; pitch -= movementY * sens; 限制 pitch 範圍
身體偏航用於觀看方向;移動只使用偏航(不要對步行應用 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. 直升機 / 無人機 / 六自由度飛行器
請在開始疊層中記錄控制方案。至少需包含:
- 油門/高度的離散按鍵在按一次後不應保持「永遠上升」的狀態(使用按住狀態或明確的向上/向下)。
- 橫向移動/偏航:A 左轉,D 右轉,在載具的水平框架中(玩家可見)。
2e. 2D 橫向捲軸 / 平台遊戲
D / → 在螢幕上向右移動;A / ← 向左移動。除非遊戲類型明確是上下顛倒,否則重力不應反向。
3. 攝影機必須一致
- 追蹤攝影機:
desired = craftPos + up*height + forward*(-followDist);插值;lookAt(craft)。 - 一次計算
forward用於移動和攝影機 —— 不要在攝影機路徑中使用相反的偏航正負號重新計算。 - 除錯順序:(1) 按鍵註冊 → (2) 正負號正確(§5)→ (3) 攝影機一致。
4. 輸入管道(簡要說明)
- 使用
Set在keydown/keyup事件中追蹤按鍵,使用event.code;在blur/visibilitychange時清除。在遊戲迴圈中使用 dt 移動,而不是在按鍵處理函數中。 - 將鍵盤 + 觸控 + 遊戲手把統一成動作(
throttle、steer、pitch、roll、…)。請參閱building-games/references/input.md。 - 觸控:左搖桿 = 移動/操控,右搖桿 = 動作;按鈕目標大小 ≥44px。
5. 強制性控制自我測試(在說「完成」之前)
對於任何使用 A/D 的載具,僅截圖不足以驗證。
5a. 玩家可見檢查清單(每個車輛 / 飛行建置)
當向前移動(速度 > 小正數 epsilon)時,追蹤攝影機在後方:
| 按住 | 必須在約 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 會以非零退出;僅僅是假值則不會,因此請透過拋出錯誤來斷言。作為一個 batch 執行 —— 一次 CLI 呼叫,而不是每個動作一次 —— 在 stdin 接收 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)。
- 在開發/QA 環境中提供
window.__controlsTest(或等效功能)並已使用一次。 - 相對於滾轉/操控輸入,沒有反向傾斜的網格。
- 按鍵是按住狀態 + dt 縮放;沒有因為單次按下空格鍵而卡住推力,除非是有意為之且有標示。
如果有任何一個方框未勾選,表示遊戲尚未完成。