11 KiB
name, description, metadata, user-invocable
| name | description | metadata | user-invocable | ||
|---|---|---|---|---|---|
| controls | Player-facing input signs for browser games: WASD, vehicles, flight, FPS mouse-look, and the #1 failure mode (inverted A/D). Mandatory control self-tests and a tiny test interface so you can verify A turns left before shipping. Load for ANY game with movement, steering, flying, driving, tanks, boats, mechs, drones, planes, karts, third-person follow cams — not only racing. Triggers on "controls", "WASD", "inverted", "steer", "flight", "airplane", "kart", "vehicle", "yaw", "roll", "pitch", "mouse look", "A/D". |
|
false |
Controls (player-visible signs — do not ship inverted)
Read this end-to-end before writing movement/steer/flight code for any game
that uses WASD, arrows, a chase camera, or a flying craft. Do not skip this
and only open racing-kart or fps — those genre files assume you already
know these signs. Inverted A/D is the most common ship-blocker in vehicle and
flight demos.
Pair with building-games (loop, camera, 3D orientation) and
building-games/references/input.md (keydown state, gamepad, touch). This
skill owns what left/right/up mean to the player and how you prove it.
0. Hard rules (fail the build if broken)
- Player-visible left/right is law. From a chase / behind camera while
the craft moves forward:
- A / ← → nose (or bank) turns left on screen
- D / → → nose (or bank) turns right on screen
- Never reuse FPS strafe as vehicle steer. FPS “D → +right vector” is position on the ground plane. Vehicle A/D is yaw (or roll) rate, not a strafe offset. Mixing them is the #1 cause of inverted A/D.
- You must run a control self-test (§5) before saying done. Screenshot-only QA is not enough. If A turns right, flip the steer/roll sign, retest, then ship — do not invent a new coordinate story.
1. Shared 3D basis (use this everywhere)
three.js: right-handed, +Y up, meshes face +Z, cameras look −Z.
Yaw-only heading on XZ (ground vehicles, walkers, most arcade craft):
// yaw = 0 faces world −Z; +yaw is CCW about +Y (nose moves toward −X)
forward = (-sin(yaw), 0, -cos(yaw))
right = ( cos(yaw), 0, -sin(yaw)) // = normalize(cross(forward, worldUp))
With a chase cam behind the craft (camera near position - forward * dist):
| Player sees | World (this basis) | Input |
|---|---|---|
| Nose left | +yaw | A / ← must produce +yaw (or equivalent bank-left for planes) |
| Nose right | −yaw | D / → must produce −yaw |
If your basis differs, keep one consistent pair — but the player-visible row above is mandatory.
2. Genre maps
2a. FPS / on-foot (strafe, not steer)
W = +forward, S = −forward, D = +right, A = −right // position, not yaw
mouse: yaw -= movementX * sens; pitch -= movementY * sens; clamp pitch
Body yaw for look; movement uses yaw only (do not apply pitch to walk).
2b. Ground / water vehicle (kart, bike, jetski, boat, tank, rover, snowmobile)
Arcade body with heading/yaw and forward speed:
// Input (held keys → actions once per frame)
let steer = 0; // -1..+1, player-visible
if (keys.has('KeyA') || keys.has('ArrowLeft')) steer += 1; // LEFT
if (keys.has('KeyD') || keys.has('ArrowRight')) steer -= 1; // RIGHT
// Optional: steer = clamp(steer + gamepadX, -1, 1) with same sign convention
// Integrate (speedFactor ~ 0..1 from |speed|)
const reverse = speed >= 0 ? 1 : -1; // wheel-left still feels left in reverse
yaw += steer * turnRate * speedFactor * reverse * dt;
// Move along heading
const fx = -Math.sin(yaw), fz = -Math.cos(yaw);
position.x += fx * speed * dt;
position.z += fz * speed * dt;
Canonical bug (do not copy):
// WRONG — this is what ships inverted A/D in the wild
if (KeyA) steer -= 1;
if (KeyD) steer += 1;
yaw += steer * turnRate * dt; // A → −yaw → nose RIGHT on chase cam
If you already wrote KeyA → steer--, either swap the key mapping or
negate once at integrate (yaw += -steer * …) — then run §5. Do not flip
twice (keys + integrate + bank mesh).
2c. Fixed-wing flight (airplane, glider, RC plane)
| Input | Action | Player expectation |
|---|---|---|
| A / ← | Roll left (aileron) | Left wing down / bank left |
| D / → | Roll right | Right wing down / bank right |
| W / ↑ | Pitch (pick one scheme and label HUD) | Usually nose down or pull-up — be consistent |
| S / ↓ | Opposite pitch | |
| Q / E | Yaw / rudder (optional) | Q left, E right |
- A/D are not strafe and not “ground steer with FPS signs.”
- Apply roll in the craft’s local forward axis with a sign that matches bank left on A. If the mesh banks the wrong way, flip one sign on the roll apply (or on the A/D → roll mapping), not the whole basis.
- Coordinated turn: positive bank should produce a turn that matches the bank direction under the chase/external cam.
2d. Heli / drone / 6DOF
Document the scheme on a start overlay. Minimum:
- Throttle/altitude on discrete keys must not stick “always up” after one press (use held state or explicit up/down).
- Strafe/yaw: A left, D right in the craft’s horizontal frame (player-visible).
2e. 2D side-scroller / platformer
D / → moves right on screen; A / ← moves left. Gravity only inverted if the genre is explicitly upside-down.
3. Camera must agree
- Chase cam:
desired = craftPos + up*height + forward*(-followDist); lerp;lookAt(craft). - Compute
forwardonce for both movement and camera — do not rebuild with opposite yaw sign in the camera path. - Debug order: (1) keys register → (2) signs correct (§5) → (3) camera agrees.
4. Input plumbing (brief)
- Track keys with a
Setonkeydown/keyupusingevent.code; clear onblur/visibilitychange. Move in the game loop with dt, not in the key handler. - Unify keyboard + touch + gamepad into actions (
throttle,steer,pitch,roll, …). Seebuilding-games/references/input.md. - Touch: left stick = move/steer, right = actions; ≥44px targets.
5. Mandatory control self-test (before “done”)
Screenshot-only is not enough for any craft with A/D.
5a. Player-visible checklist (every vehicle / flight build)
While moving forward (speed > small epsilon), chase cam behind:
| Hold | Must observe within ~0.5s |
|---|---|
| A | Nose or bank moves left on screen |
| D | Nose or bank moves right on screen |
| W (ground) | Speed increases / moves along facing |
| S (ground) | Brakes or reverse (as designed) |
If A fails: flip steer/roll sign once, retest both A and D.
5b. Minimal test interface (implement this)
Expose a tiny hook so you (and automated QA) can prove signs without guessing private closures:
// e.g. src/game/controlsTest.ts — dev/QA only is fine
export type ControlsProbe = {
getYaw: () => number; // radians; or getHeading()
getSpeed: () => number;
/** Inject held actions instead of real keys; both stay applied until you
* change them, so §5c can hold a key across frames and clear at the end. */
setSteer?: (v: number) => void; // -1..1, same sign as production
setKeys?: (codes: string[]) => void; // held until the next call; `[]` clears
};
declare global {
interface Window {
__controlsTest?: ControlsProbe;
}
}
Wire window.__controlsTest from the game loop when import.meta.env.DEV or a
?qa=1 flag is set.
5c. Automated smoke (run it)
Drive the §5b probe with the preinstalled agent-browser CLI — that is the
first move, not a hand-written script. A thrown eval exits non-zero; a
merely falsy one does not, so assert by throwing. Run it as one batch — one
CLI call, not one per verb — taking JSON on stdin; --bail stops at the first
failing step and exits non-zero.
agent-browser batch --bail <<'JSON' # find's label is case-sensitive: copy it from `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
Hold keys through the probe, not with keydown — agent-browser keydown
does not reach §4's Set, so a correct game reads as broken. No setKeys on
your probe? Add it (§5b), or dispatch the key event yourself — the browser-QA
reference's Keys note has the mechanism and the form.
The hold sits inside one eval: spread across commands it lasts however
long they take, and the ±π wrap in Math.atan2(Math.sin(d), Math.cos(d))
reads a craft that turned more than π as one turning the other way. The IIFE is
what keeps the step re-runnable — a bare const d = … fails the second time
with "already declared" — and async is what lets the hold run in page time.
Repeat for D with 'KeyD' and both comparisons mirrored (w > 0.05 is
inverted, w >= -0.05 is barely), single-quoted so the JSON needs no escapes;
for planes assert roll: A ⇒ bank left.
A turns RIGHT is the sign error: flip one sign and re-run.
A barely turned is not — the craft moved the right way, just less than
0.05 rad in 300 ms, which a boat or a heavy rover will do; raise the hold, or
check the sim is running, and flip nothing. Any other non-zero exit — no probe,
a wedged daemon — means the check never ran: read the message first. Read the
browser-QA reference AGENTS.md links before your first flow — verbs, argument
shapes and the fallback are there.
5d. What not to do
- Do not only test “D increases some internal variable.”
- Do not use FPS “D → +X when facing −Z” as the vehicle pass condition.
- Do not flip mesh bank, camera, and steer all at once when fixing — change one sign, retest.
6. Finish criteria (controls)
- Opened this skill before writing movement/steer/flight.
- Genre map chosen (§2) and start-screen / HUD labels match it.
- Chase-cam A/D player-visible test passed (§5a).
window.__controlsTest(or equivalent) available in dev/QA and used once.- No inverted bank mesh relative to roll/steer input.
- Keys are held-state + dt-scaled; no sticky thrust from a single Space tap unless intentional and labeled.
If any box is unchecked, the game is not done.