Controles (señales visibles para el jugador — no enviar invertido)
Lee esto de principio a fin antes de escribir código de movimiento/dirección/vuelo para cualquier juego que use WASD, flechas, cámara de persecución o una nave voladora. No te saltes esto y solo abras racing-kart o fps — esos archivos de género asumen que ya conoces estas señales. A/D invertido es el bloqueador de envío más común en demostraciones de vehículos y vuelo.
Combínalo con building-games (bucle, cámara, orientación 3D) y building-games/references/input.md (estado de tecla presionada, gamepad, táctil). Este skill posee qué significan izquierda/derecha/arriba para el jugador y cómo lo pruebas.
0. Reglas estrictas (fallo de build si se incumplen)
- La izquierda/derecha visible para el jugador es ley. Desde una cámara de persecución / detrás mientras el vehículo se mueve hacia adelante:
- A / ← → el morro (o la inclinación) gira a la izquierda en pantalla
- D / → → el morro (o la inclinación) gira a la derecha en pantalla
- Nunca reutilices el strafe de FPS como dirección de vehículo. En FPS “D → vector +derecha” es posición en el plano del suelo. En vehículos A/D es velocidad de guiñada (o balanceo), no un desplazamiento lateral. Mezclarlos es la causa #1 de A/D invertido.
- Debes ejecutar una autocomprobación de control (§5) antes de decir que está listo. La revisión solo con captura de pantalla no es suficiente. Si A gira a la derecha, invierte el signo de dirección/balanceo, vuelve a probar y luego envía — no inventes una nueva historia de coordenadas.
1. Base 3D compartida (usa esto en todas partes)
three.js: diestro, +Y arriba, las mallas miran +Z, las cámaras miran −Z.
Dirección solo con guiñada en XZ (vehículos terrestres, caminantes, la mayoría de naves arcade):
// yaw = 0 mira hacia el mundo −Z; +yaw es antihorario sobre +Y (el morro se mueve hacia −X)
forward = (-sin(yaw), 0, -cos(yaw))
right = ( cos(yaw), 0, -sin(yaw)) // = normalize(cross(forward, worldUp))
Con una cámara de persecución detrás del vehículo (cámara cerca de position - forward * dist):
| El jugador ve | Mundo (esta base) | Entrada |
|---|---|---|
| Morro izquierda | +yaw | A / ← debe producir +yaw (o inclinación a la izquierda equivalente para aviones) |
| Morro derecha | −yaw | D / → debe producir −yaw |
Si tu base es diferente, mantén un par consistente — pero la fila visible para el jugador anterior es obligatoria.
2. Mapas de género
2a. FPS / a pie (strafe, no dirección)
W = +forward, S = −forward, D = +right, A = −right // posición, no guiñada
mouse: yaw -= movementX * sens; pitch -= movementY * sens; limitar pitch
Guiñada del cuerpo para mirar; el movimiento usa solo la guiñada (no apliques cabeceo para caminar).
2b. Vehículos terrestres / acuáticos (kart, bici, moto acuática, barco, tanque, rover, moto de nieve)
Cuerpo arcade con heading/yaw y velocidad hacia adelante speed:
// Entrada (teclas presionadas → acciones una vez por fotograma)
let steer = 0; // -1..+1, visible para el jugador
if (keys.has('KeyA') || keys.has('ArrowLeft')) steer += 1; // IZQUIERDA
if (keys.has('KeyD') || keys.has('ArrowRight')) steer -= 1; // DERECHA
// Opcional: steer = clamp(steer + gamepadX, -1, 1) con la misma convención de signo
// Integrar (speedFactor ~ 0..1 de |speed|)
const reverse = speed >= 0 ? 1 : -1; // girar a la izquierda sigue sintiéndose a la izquierda en reversa
yaw += steer * turnRate * speedFactor * reverse * dt;
// Mover a lo largo de la dirección
const fx = -Math.sin(yaw), fz = -Math.cos(yaw);
position.x += fx * speed * dt;
position.z += fz * speed * dt;
Error canónico (no copiar):
// INCORRECTO — esto es lo que envía A/D invertido en la naturaleza
if (KeyA) steer -= 1;
if (KeyD) steer += 1;
yaw += steer * turnRate * dt; // A → −yaw → morro DERECHA en cámara de persecución
Si ya escribiste KeyA → steer--, intercambia la asignación de teclas o niega una vez en la integración (yaw += -steer * …) — luego ejecuta §5. No inviertas dos veces (teclas + integración + inclinación de malla).
2c. Vuelo de ala fija (avión, planeador, avión RC)
| Entrada | Acción | Expectativa del jugador |
|---|---|---|
| A / ← | Balanceo a la izquierda (alerón) | Ala izquierda abajo / inclinación a la izquierda |
| D / → | Balanceo a la derecha | Ala derecha abajo / inclinación a la derecha |
| W / ↑ | Cabeceo (elige un esquema y etiqueta el HUD) | Generalmente morro abajo o tirar hacia arriba — sé consistente |
| S / ↓ | Cabeceo opuesto | |
| Q / E | Guiñada / timón (opcional) | Q izquierda, E derecha |
- A/D no son strafe ni “dirección terrestre con señales FPS”.
- Aplica el balanceo en el eje local hacia adelante del vehículo con un signo que coincida con inclinación a la izquierda en A. Si la malla se inclina en la dirección incorrecta, invierte un signo en la aplicación del balanceo (o en la asignación A/D → balanceo), no toda la base.
- Giro coordinado: una inclinación positiva debe producir un giro que coincida con la dirección de la inclinación bajo la cámara de persecución/externa.
2d. Helicóptero / dron / 6DOF
Documenta el esquema en una superposición de inicio. Mínimo:
- El acelerador/altitud en teclas discretas no debe quedar “siempre arriba” después de una pulsación (usa estado mantenido o arriba/abajo explícito).
- Strafe/guiñada: A izquierda, D derecha en el marco horizontal del vehículo (visible para el jugador).
2e. Side-scroller 2D / plataformas
D / → se mueve a la derecha en pantalla; A / ← se mueve a la izquierda. La gravedad solo se invierte si el género es explícitamente al revés.
3. La cámara debe estar de acuerdo
- Cámara de persecución:
desired = craftPos + up*height + forward*(-followDist); interpolar;lookAt(craft). - Calcula
forwarduna vez tanto para el movimiento como para la cámara — no lo reconstruyas con el signo de guiñada opuesto en la ruta de la cámara. - Orden de depuración: (1) las teclas se registran → (2) signos correctos (§5) → (3) la cámara está de acuerdo.
4. Cableado de entrada (breve)
- Rastrea las teclas con un
Setenkeydown/keyupusandoevent.code; limpia enblur/visibilitychange. Mueve en el bucle del juego con dt, no en el manejador de teclas. - Unifica teclado + táctil + gamepad en acciones (
throttle,steer,pitch,roll, …). Consultabuilding-games/references/input.md. - Táctil: stick izquierdo = mover/dirigir, derecho = acciones; objetivos ≥44px.
5. Autocomprobación de control obligatoria (antes de “listo”)
Solo con captura de pantalla no es suficiente para cualquier vehículo con A/D.
5a. Lista de verificación visible para el jugador (cada construcción de vehículo/vuelo)
Mientras te mueves hacia adelante (velocidad > epsilon pequeño), cámara de persecución detrás:
| Mantener | Debe observarse en ~0.5s |
|---|---|
| A | El morro o la inclinación se mueve a la izquierda en pantalla |
| D | El morro o la inclinación se mueve a la derecha en pantalla |
| W (suelo) | La velocidad aumenta / se mueve en la dirección de la mirada |
| S (suelo) | Frena o reversa (según lo diseñado) |
Si A falla: invierte el signo de dirección/balanceo una vez, vuelve a probar tanto A como D.
5b. Interfaz de prueba mínima (implementa esto)
Expón un pequeño hook para que tú (y el QA automatizado) puedan probar las señales sin adivinar closures privadas:
// p.ej. src/game/controlsTest.ts — solo dev/QA está bien
export type ControlsProbe = {
getYaw: () => number; // radianes; o getHeading()
getSpeed: () => number;
/** Inyecta acciones mantenidas en lugar de teclas reales; ambas permanecen aplicadas hasta que
* las cambies, para que §5c pueda mantener una tecla entre fotogramas y limpiar al final. */
setSteer?: (v: number) => void; // -1..1, mismo signo que producción
setKeys?: (codes: string[]) => void; // mantenidas hasta la siguiente llamada; `[]` limpia
};
declare global {
interface Window {
__controlsTest?: ControlsProbe;
}
}
Conecta window.__controlsTest desde el bucle del juego cuando import.meta.env.DEV o una bandera ?qa=1 esté establecida.
5c. Prueba de humo automatizada (ejecútala)
Conduce la sonda de §5b con el CLI agent-browser preinstalado — ese es el primer paso, no un script escrito a mano. Un eval lanzado sale con código no cero; uno meramente falso no lo hace, así que afirma lanzando. Ejecútalo como un solo batch — una llamada CLI, no una por verbo — tomando JSON en stdin; --bail se detiene en el primer paso fallido y sale con código no cero.
agent-browser batch --bail <<'JSON' # la etiqueta de find distingue mayúsculas: cópiala de `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
Mantén las teclas a través de la sonda, no con keydown — agent-browser keydown no llega al Set de §4, por lo que un juego correcto se leería como roto. ¿No tienes setKeys en tu sonda? Añádelo (§5b), o despacha el evento de tecla tú mismo — la nota Keys de la referencia de QA del navegador tiene el mecanismo y la forma.
La retención se sienta dentro de un solo eval: repartida entre comandos dura todo el tiempo que tardan, y el envoltorio ±π en Math.atan2(Math.sin(d), Math.cos(d)) lee un vehículo que giró más de π como si girara en la otra dirección. La IIFE es lo que hace que el paso se pueda volver a ejecutar — un const d = … desnudo falla la segunda vez con "ya declarado" — y async es lo que permite que la retención se ejecute en tiempo de página. Repite para D con 'KeyD' y ambas comparaciones reflejadas (w > 0.05 está invertido, w >= -0.05 es apenas), con comillas simples para que el JSON no necesite escapes; para aviones afirma roll: A ⇒ inclinación a la izquierda.
A turns RIGHT es el error de signo: invierte un signo y vuelve a ejecutar.
A barely turned no lo es — el vehículo se movió en la dirección correcta, solo que menos de 0.05 rad en 300 ms, que un barco o un rover pesado harán; aumenta la retención, o verifica que la simulación se esté ejecutando, y no inviertas nada. Cualquier otra salida no cero — sin sonda, un demonio atascado — significa que la verificación nunca se ejecutó: lee el mensaje primero. Lee los enlaces AGENTS.md de la referencia de QA del navegador antes de tu primer flujo — verbos, formas de argumentos y el respaldo están allí.
5d. Qué no hacer
- No pruebes solo “D aumenta alguna variable interna.”
- No uses “D → +X cuando mira −Z” de FPS como condición de aprobación del vehículo.
- No inviertas la inclinación de la malla, la cámara y la dirección todo a la vez al corregir — cambia un signo, vuelve a probar.
6. Criterios de finalización (controles)
- Abriste este skill antes de escribir movimiento/dirección/vuelo.
- Mapa de género elegido (§2) y las etiquetas de la pantalla de inicio / HUD coinciden con él.
- Prueba visible para el jugador de A/D en cámara de persecución superada (§5a).
-
window.__controlsTest(o equivalente) disponible en dev/QA y usado una vez. - Ninguna malla de inclinación invertida en relación con la entrada de balanceo/dirección.
- Las teclas se mantienen en estado presionado + escalado por dt; sin empuje pegajoso de un solo toque de Space a menos que sea intencional y esté etiquetado.
Si alguna casilla no está marcada, el juego no está listo.