操作(プレイヤー視認サイン — 反転出荷禁止)
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)を必ず実行しなければなりません。 スクリーンショットだけの 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 を生成しなければならない |
ベースが異なる場合は、一貫性のある ペアを 1 つだけ維持してください。ただし、上記の プレイヤー視認 行は必須です。
2. ジャンルマップ
2a. FPS / 徒歩(横移動、操縦ではない)
W = +forward, S = −forward, D = +right, A = −right // 位置、ヨーではない
mouse: 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 / ↑ | ピッチ(1 つのスキームを選択し、HUD にラベル表示) | 通常は機首下げ または 引き起こし — 一貫性を保つ |
| S / ↓ | 逆ピッチ | |
| Q / E | ヨー / ラダー(オプション) | Q 左、E 右 |
- A/D は横移動ではなく、「FPS 記号による地上操縦」でもありません。
- ロールは乗り物の ローカル前方軸 に適用し、A で左バンク となる符号にします。メッシュが逆向きにバンクする場合は、ロール適用(または A/D → ロールマッピング)の 1 つ の符号を反転させ、ベース全体は反転させないでください。
- 協調旋回: 正のバンクは、チェイス/外部カメラでバンク方向と一致する旋回を生成する必要があります。
2d. ヘリ / ドローン / 6DOF
開始オーバーレイにスキームを文書化します。最低限:
- 個別キーによるスロットル/高度は、1 回の押下で「常に上」になってはいけません(保持状態または明示的な上/下を使用)。
- 横移動/ヨー: 乗り物の水平フレームで A 左、D 右(プレイヤー視認)。
2e. 2D 横スクロール / プラットフォーマー
D / → は画面上で 右に移動。A / ← は画面上で 左に移動。重力が反転するのは、ジャンルが明示的に上下逆の場合のみ。
3. カメラは一致しなければならない
- チェイスカメラ:
desired = craftPos + up*height + forward*(-followDist); lerp;lookAt(craft)。 forwardは移動とカメラの 両方 で 1 回 計算し、カメラパスで反対のヨー符号で再構築しないでください。- デバッグ順序: (1) キーが認識される → (2) 符号が正しい(§5) → (3) カメラが一致する。
4. 入力配管(簡潔に)
- キーは
keydown/keyupでevent.codeを使用して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 が失敗した場合: 操縦/ロールの符号を 1 回 反転し、A と D の両方を再テストしてください。
5b. 最小テストインターフェース(これを実装する)
あなた自身(および自動 QA)が非公開のクロージャを推測せずに符号を証明できるように、小さなフックを公開します:
// 例: src/game/controlsTest.ts — dev/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. 自動化スモークテスト(実行する)
§5b のプローブをプリインストールされた agent-browser CLI で駆動します。これが最初の手順であり、手書きスクリプトではありません。スローされた eval は非ゼロで終了します。単に偽値の場合は非ゼロになりません。そのため、スローしてアサートします。1 つの batch として実行します(動詞ごとに 1 回ではなく、1 回の CLI 呼び出し)。JSON を標準入力で受け取ります。--bail は最初の失敗ステップで停止し、非ゼロで終了します。
agent-browser batch --bail <<'JSON' # find のラベルは大文字小文字を区別: 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 ノートにメカニズムと形式があります。
保持は 1 つの eval の 内側 にあります: コマンドに分散すると、コマンドの実行時間だけ保持され、Math.atan2(Math.sin(d), Math.cos(d)) での ±π ラップは、π 以上回転した乗り物を反対方向に回転していると読み取ります。IIFE はステップを再実行可能に保つものです — ベアの const d = … は 2 回目に「既に宣言されています」で失敗し、async は保持をページ時間で実行させるものです。D についても同様に、'KeyD' を使用し、両方の比較を反転させて(w > 0.05 は反転、w >= -0.05 はわずか)、JSON がエスケープを必要としないように一重引用符で囲みます。飛行機の場合は ロール をアサートします: A ⇒ 左バンク。
A turns RIGHT は符号エラーです: 1 つ の符号を反転して再実行してください。
A barely turned は符号エラーではありません — 乗り物は正しい方向に動いていますが、300 ms で 0.05 ラジアン未満です。これはボートや重いローバーが行うことです。保持時間を延ばすか、シミュレーションが実行されていることを確認し、何も反転しないでください。その他の非ゼロ終了 — プローブなし、デーモンの停止 — はチェックが実行されなかったことを意味します: 最初にメッセージを読んでください。最初のフローの前に、ブラウザ QA リファレンス AGENTS.md のリンクを読んでください。動詞、引数の形状、およびフォールバックがそこにあります。
5d. やってはいけないこと
- 「D で内部変数が増加する」だけをテスト しないでください。
- FPS の「−Z 方向を向いているときに D → +X」を乗り物の合格条件として使用 しないでください。
- 修正時にメッシュバンク、カメラ、操縦をすべて一度に反転 しないでください。1 つ の符号を変更し、再テストしてください。
6. 完了基準(操作)
- 移動 / 操縦 / 飛行コードを書く 前に このスキルを開きました。
- ジャンルマップを選択し(§2)、スタート画面 / HUD ラベルがそれと一致しています。
- チェイスカメラ A/D プレイヤー視認テストに 合格しました(§5a)。
-
window.__controlsTest(または同等のもの)が dev/QA で利用可能で、1 回使用されました。 - ロール / 操縦入力に対して反転したバンクメッシュはありません。
- キーは保持状態 + dt スケーリングされています。単一の Space タップによる粘着スラストは、意図的かつラベル表示されている場合を除き、ありません。
どのボックスもチェックされていない場合、ゲームは 完了していません。