Controles (sinais visíveis para o jogador — não envie invertido)
Leia isto do início ao fim antes de escrever código de movimento/direção/voom para qualquer jogo que use WASD, setas, câmera de perseguição ou uma aeronave. Não pule isto e abra apenas racing-kart ou fps — esses arquivos de gênero assumem que você já conhece esses sinais. A/D invertido é o bloqueador de envio mais comum em demonstrações de veículos e voo.
Combine com building-games (loop, câmera, orientação 3D) e building-games/references/input.md (estado de tecla pressionada, gamepad, toque). Esta skill é responsável por o que esquerda/direita/cima significam para o jogador e como você prova isso.
0. Regras rígidas (falhe a construção se quebrado)
- Esquerda/direita visível para o jogador é lei. De uma câmera de perseguição / atrás enquanto a nave se move para frente:
- A / ← → o nariz (ou inclinação) vira para a esquerda na tela
- D / → → o nariz (ou inclinação) vira para a direita na tela
- Nunca reutilize o strafe de FPS como direção de veículo. FPS “D → +vetor direito” é posição no plano do chão. A/D de veículo é taxa de guinada (ou rolamento), não um deslocamento de strafe. Misturá-los é a causa nº 1 de A/D invertido.
- Você deve executar um auto-teste de controle (§5) antes de dizer que está pronto. A garantia de qualidade apenas com captura de tela não é suficiente. Se A virar para a direita, inverta o sinal de direção/rolagem, reteste, então envie — não invente uma nova história de coordenadas.
1. Base 3D compartilhada (use isso em todos os lugares)
three.js: destro, +Y para cima, malhas voltadas para +Z, câmeras olham para −Z.
Direção apenas de guinada no XZ (veículos terrestres, andadores, a maioria das naves de arcade):
// guinada = 0 está voltado para −Z do mundo; +guinada é CCW sobre +Y (nariz se move em direção a −X)
frente = (-sin(yaw), 0, -cos(yaw))
direita = ( cos(yaw), 0, -sin(yaw)) // = normalize(cross(frente, mundoCima))
Com uma câmera de perseguição atrás da nave (câmera perto de posicao - frente * dist):
| O jogador vê | Mundo (esta base) | Entrada |
|---|---|---|
| Nariz para a esquerda | +guinada | A / ← deve produzir +guinada (ou inclinação para a esquerda equivalente para aviões) |
| Nariz para a direita | −guinada | D / → deve produzir −guinada |
Se sua base for diferente, mantenha um par consistente — mas a linha visível para o jogador acima é obrigatória.
2. Mapas de gênero
2a. FPS / a pé (strafe, não direção)
W = +frente, S = −frente, D = +direita, A = −direita // posição, não guinada
mouse: guinada -= movimentoX * sens; arfagem -= movimentoY * sens; limitar arfagem
Guinada do corpo para olhar; movimento usa apenas guinada (não aplique arfagem para andar).
2b. Veículo terrestre / aquático (kart, bicicleta, jet ski, barco, tanque, rover, moto de neve)
Corpo de arcade com direcao/guinada e velocidade para frente:
// Entrada (teclas pressionadas → ações uma vez por quadro)
let direcao = 0; // -1..+1, visível para o jogador
if (keys.has('KeyA') || keys.has('ArrowLeft')) direcao += 1; // ESQUERDA
if (keys.has('KeyD') || keys.has('ArrowRight')) direcao -= 1; // DIREITA
// Opcional: direcao = clamp(direcao + gamepadX, -1, 1) com a mesma convenção de sinal
// Integrar (fatorVelocidade ~ 0..1 de |velocidade|)
const reverso = velocidade >= 0 ? 1 : -1; // roda-esquerda ainda parece esquerda em ré
guinada += direcao * taxaDeGiro * fatorVelocidade * reverso * dt;
// Mover ao longo da direção
const fx = -Math.sin(guinada), fz = -Math.cos(guinada);
posicao.x += fx * velocidade * dt;
posicao.z += fz * velocidade * dt;
Erro canônico (não copie):
// ERRADO — é isso que envia A/D invertido no mundo real
if (KeyA) direcao -= 1;
if (KeyD) direcao += 1;
guinada += direcao * taxaDeGiro * dt; // A → −guinada → nariz DIREITO na câmera de perseguição
Se você já escreveu KeyA → direcao--, ou troque o mapeamento de tecla ou negue uma vez na integração (guinada += -direcao * …) — então execute §5. Não inverta duas vezes (teclas + integração + malha de inclinação).
2c. Voo de asa fixa (avião, planador, aeromodelo RC)
| Entrada | Ação | Expectativa do jogador |
|---|---|---|
| A / ← | Rolar para a esquerda (aileron) | Asa esquerda para baixo / inclinar para a esquerda |
| D / → | Rolar para a direita | Asa direita para baixo / inclinar para a direita |
| W / ↑ | Arfagem (escolha um esquema e rotule o HUD) | Geralmente nariz para baixo ou puxar para cima — seja consistente |
| S / ↓ | Arfagem oposta | |
| Q / E | Guinada / leme (opcional) | Q esquerda, E direita |
- A/D não são strafe e não são “direção terrestre com sinais de FPS.”
- Aplique a rolagem no eixo local para frente da nave com um sinal que corresponda a inclinar para a esquerda em A. Se a malha inclinar na direção errada, inverta um sinal na aplicação da rolagem (ou no mapeamento A/D → rolagem), não a base inteira.
- Curva coordenada: a inclinação positiva deve produzir uma curva que corresponda à direção da inclinação sob a câmera de perseguição/externa.
2d. Helicóptero / drone / 6DOF
Documente o esquema em uma sobreposição inicial. Mínimo:
- Acelerador/altitude em teclas discretas não deve grudar “sempre para cima” após um pressionamento (use estado pressionado ou para cima/para baixo explícito).
- Strafe/guinada: A esquerda, D direita no quadro horizontal da nave (visível para o jogador).
2e. Side-scroller 2D / plataforma
D / → move-se para a direita na tela; A / ← move-se para a esquerda. Gravidade apenas invertida se o gênero for explicitamente de cabeça para baixo.
3. A câmera deve concordar
- Câmera de perseguição:
desejada = posicaoNave + cima*altura + frente*(-distanciaSeguimento); lerp;olharPara(nave). - Calcule a
direcao(frente) uma vez tanto para o movimento quanto para a câmera — não reconstrua com sinal de guinada oposto no caminho da câmera. - Ordem de depuração: (1) teclas registram → (2) sinais corretos (§5) → (3) câmera concorda.
4. Encanação de entrada (breve)
- Rastreie teclas com um
Setemkeydown/keyupusandoevent.code; limpe emblur/visibilitychange. Mova no loop do jogo com dt, não no manipulador de teclas. - Unifique teclado + toque + gamepad em ações (
acelerador,direcao,arfagem,rolagem, …). Vejabuilding-games/references/input.md. - Toque: stick esquerdo = mover/direção, direito = ações; alvos ≥44px.
5. Auto-teste de controle obrigatório (antes de "pronto")
Apenas captura de tela não é suficiente para qualquer nave com A/D.
5a. Lista de verificação visível para o jogador (cada construção de veículo / voo)
Enquanto se move para frente (velocidade > pequeno epsilon), câmera de perseguição atrás:
| Segure | Deve observar dentro de ~0.5s |
|---|---|
| A | Nariz ou inclinação move-se para a esquerda na tela |
| D | Nariz ou inclinação move-se para a direita na tela |
| W (terrestre) | Velocidade aumenta / move-se ao longo do que está enfrentando |
| S (terrestre) | Freios ou ré (conforme projetado) |
Se A falhar: inverta o sinal de direção/rolagem uma vez, reteste A e D.
5b. Interface de teste mínima (implemente isto)
Exponha um pequeno gancho para que você (e QA automatizado) possa provar sinais sem adivinhar closures privadas:
// ex.: src/game/controlsTest.ts — dev/QA apenas é suficiente
export type ControlsProbe = {
getYaw: () => number; // radianos; ou getHeading()
getSpeed: () => number;
/** Injete ações pressionadas em vez de teclas reais; ambas permanecem aplicadas até que você
* as altere, para que §5c possa segurar uma tecla entre quadros e limpar no final. */
setSteer?: (v: number) => void; // -1..1, mesmo sinal da produção
setKeys?: (codes: string[]) => void; // pressionado até a próxima chamada; `[]` limpa
};
declare global {
interface Window {
__controlsTest?: ControlsProbe;
}
}
Conecte window.__controlsTest do loop do jogo quando import.meta.env.DEV ou uma bandeira ?qa=1 estiver definida.
5c. Teste de fumaça automatizado (execute-o)
Dirija a sonda §5b com o CLI agent-browser pré-instalado — esse é o primeiro movimento, não um script escrito à mão. Um eval lançado sai com status não-zero; um meramente falso não sai, então afirme lançando. Execute-o como um batch — uma chamada CLI, não uma por verbo — recebendo JSON no stdin; --bail para no primeiro passo falho e sai com status não-zero.
agent-browser batch --bail <<'JSON' # o rótulo do find é sensível a maiúsculas/minúsculas: copie-o de `snapshot -i`
[["open","http://127.0.0.1:8080/"],
["find","text","Start","click"],
["eval","if (!window.__controlsTest?.setKeys) throw Error('sem sonda §5b: adicione setKeys')"],
["eval","__controlsTest.setKeys(['KeyW'])"],
["wait","600"],
["eval","if (__controlsTest.getSpeed() <= 0.1) throw Error('W: sem movimento')"],
["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 vira para DIREITA — invertido, obteve ' + w.toFixed(2)); if (w <= 0.05) throw Error('A mal virou (' + w.toFixed(2) + ') — segure por mais tempo ou verifique se a sim está rodando'); return 'A ok' })()"],
["eval","__controlsTest.setKeys([])"],
["screenshot","/workspace/screenshots/controls.png"],
["close"]]
JSON
Segure teclas através da sonda, não com keydown — agent-browser keydown não atinge o Set da §4, então um jogo correto é lido como quebrado. Sem setKeys na sua sonda? Adicione-a (§5b), ou despache o evento de tecla você mesmo — a nota Keys da referência de QA do navegador tem o mecanismo e a forma.
A espera fica dentro de uma eval: espalhada por comandos, dura o tempo que eles levarem, e o wrap ±π em Math.atan2(Math.sin(d), Math.cos(d)) lê uma nave que virou mais de π como se estivesse virando para o outro lado. A IIFE é o que mantém o passo re-executável — um const d = … puro falha na segunda vez com "já declarado" — e async é o que permite que a espera execute no tempo da página. Repita para D com 'KeyD' e ambas as comparações espelhadas (w > 0.05 é invertido, w >= -0.05 é mal), entre aspas simples para que o JSON não precise de escapes; para aviões, afirme rolagem: A ⇒ inclinar para a esquerda.
A vira para DIREITA é o erro de sinal: inverta um sinal e re-execute.
A mal virou não é — a nave se moveu na direção certa, apenas menos de 0,05 rad em 300 ms, o que um barco ou um rover pesado fará; aumente a espera, ou verifique se a sim está rodando, e não inverta nada. Qualquer outra saída não-zero — sem sonda, um daemon travado — significa que a verificação nunca foi executada: leia a mensagem primeiro. Leia os links AGENTS.md da referência de QA do navegador antes do seu primeiro fluxo — os verbos, as formas dos argumentos e o fallback estão lá.
5d. O que não fazer
- Não teste apenas “D aumenta alguma variável interna.”
- Não use FPS “D → +X quando voltado para −Z” como condição de aprovação do veículo.
- Não inverta malha de inclinação, câmera e direção todos de uma vez ao corrigir — mude um sinal, reteste.
6. Critérios de conclusão (controles)
- Abriu esta skill antes de escrever movimento/direção/voom.
- Mapa de gênero escolhido (§2) e os rótulos da tela inicial / HUD correspondem a ele.
- Teste visível para o jogador da câmera de perseguição A/D passou (§5a).
-
window.__controlsTest(ou equivalente) disponível em dev/QA e usado uma vez. - Nenhuma malha de inclinação invertida em relação à entrada de rolagem/direção.
- Teclas são estado pressionado + escaladas por dt; nenhum empuxo pegajoso de um único toque de Espaço, a menos que intencional e rotulado.
Se alguma caixa não estiver marcada, o jogo não está pronto.