Construindo Jogos
Construa um jogo de navegador jogável e correto — não uma captura de tela estática. Um jogo é
apenas uma rota React com um <canvas> (ou <Canvas> para R3F) mais uma interface DOM sobreposta.
Estilize a sobreposição (tela inicial, HUD, menus) com a skill design-ui; esta skill
é responsável pelo loop de jogo e pelo mundo.
Controles / A/D invertido: abra .grok/skills/controls/SKILL.md antes
de escrever código de WASD, direção ou voo. Demonstrações de veículos/voo geralmente vêm com
A/D trocado se você ler apenas este arquivo ou um playbook de um único gênero.
Nota de escopo — single-player, bots ou co-op P2P pequeno:
- Entregue single-player ou single-player + IA/bots por padrão.
- Cooperativo casual em tempo real para 2–8 jogadores (cursores compartilhados, jogos de festa, ação
casual entre amigos) é suportado — use a skill
multiplayer-p2p(malha WebRTC, sinalizada em/api/rtc). Leia o modelo de confiança dela primeiro. - P2P é o único multiplayer suportado no momento. Não construa pela metade sockets que não conseguem conectar.
Referências (carregue sob demanda):
- Skill
controls(../controls/) — obrigatória para movimento/direção/voo: A/D visível ao jogador, anti-padrão de direção invertida, ailerons de voo, auto-teste obrigatóriowindow.__controlsTest. Não opcional para veículos/aviões.
references/threejs-foundational.md— a referência aprofundada de 3D/loop/perf. Leia para 3D.references/3d-libs.md— uso de three.js + @react-three/fiber + drei + rapier.- Skill
threejs(../threejs/) — dump oficial completo da API Three.js + TSL (llms-full.txt). Carregue para materiais/shaders/WebGPU/loaders avançados; não para jogos 2D simples em canvas. references/babylon.md— Babylon.js, a alternativa de engine 3D com baterias inclusas.references/phaser.md— Phaser 3, a engine padrão para jogos 2D.references/ecs-architecture.md— estrutura entidade-componente-sistema para jogos maiores.references/genres/*.md— playbooks por gênero (fps, plataforma-2d, corrida-kart, puzzle-match3-tetris, voxel-minecraft, endless-runner, topdown-twin-stick, tower-defense, board-card-chess). Arquivos de gênero não substituemcontrols.references/game-feel-juice.md,input.md,audio.md,collision-physics.md,save-persistence.md,procedural-generation.md,ai-pathfinding.md.game-asset-core(+game-animation-frames/game-tilesets/game-character-consistency/game-ui-icons) — padrões de arte 2D prontos para engine e verificação ao gerar sprites, folhas, tiles ou UI (veja §6).
Escolha a referência específica de gênero/tópico para a construção; este arquivo é o núcleo
universal para loop/mundo. Sinais de entrada → controls. Arte 2D → game-asset-core.
1. Loop de jogo e temporização (o problema #1 de correção)
- Conduza o loop com o loop RAF da engine (
renderer.setAnimationLoop,useFramedo R3F, ourequestAnimationFramepara canvas 2D). Nunca usesetInterval/setTimeout/Date.now()para temporização de jogo. - Escalone TODO movimento/animação pelo delta time (em segundos) para que a velocidade seja
independente da taxa de quadros (60Hz vs 144Hz). Calcule o delta uma vez por quadro e reutilize-o.
- three.js: use
THREE.Timer(nãoClock—Clock.getDelta()retorna ~0 em uma segunda chamada no mesmo quadro, um bug clássico de congelamento).
- three.js: use
- Limite o delta (
min(delta, 0.1)) para que uma aba em segundo plano não teleporte as coisas. - Passo de tempo fixo para física/jogabilidade: acumule delta e simule em etapas a uma taxa fixa (ex.: 1/60) enquanto renderiza na taxa de exibição — evita tunelamento e não-determinismo.
2. Controles (delegue à skill controls)
Abra .grok/skills/controls/SKILL.md antes de implementar qualquer código WASD / direção /
Voo. Essa skill é a fonte da verdade para:
- A = esquerda / D = direita visível ao jogador (câmera chase, enquanto move para frente)
- Por que
KeyA → steer−+yaw += steer * +rateinverte (bug mais comum) - Veículo vs FPS (strafe ≠ steer), ailerons de asa fixa, notas de helicóptero/drone
- Auto-teste obrigatório + sonda
window.__controlsTest
Não trate genres/racing-kart.md como o único lugar onde os sinais de steer vivem —
aviões, jetskis e mechs nunca o abrem.
Lembrete rápido (detalhes completos em controls):
// Rotação do corpo do veículo (câmera chase): A deve aumentar o yaw com esta base
forward = (-sin(yaw), 0, -cos(yaw))
// KeyA → steer = +1; yaw += steer * turnRate * speedFactor * dt
// ERRADO (envia invertido): KeyA → steer = -1; yaw += steer * turnRate * dt
- Pointer lock: apenas mouse-look — implemente WASD você mesmo; sobreposição clique-para-jogar; dispense ao travar.
- Rastreie teclas com estado pressionado + dt; unifique dispositivos via
references/input.md. - Finalize: execute a lista de verificação da skill
controls. Apenas captura de tela é insuficiente para veículos/voo.
3. Orientação 3D e objetos do mundo (os bugs "de lado/para trás")
- three.js é destro, +Y para cima: +X direita, +Y cima, +Z em direção ao espectador. Malhas encaram +Z; câmeras olham −Z (a pegadinha clássica de "câmera para trás").
- Primitivas como
Cone/Cylinderapontam +Y por padrão → gire para alinhar uma ponta com a frente (geo.rotateX(Math.PI/2)). - Orientando uma malha para encarar
forward(malhas encaram +Z): a forma correta mais simples émesh.lookAt(mesh.position.clone().add(forward)). Para construir a base manualmente, defina a coluna +Z comoforwarde escolha o eixo x que mantenha uma rotação propriamente destra (det = +1):xAxis = normalize(cross(up, forward)), entãomakeBasis(xAxis, up, forward). Note que isto écross(up, forward)— não oright = cross(forward, up)do movimento da §2. Mirar +Z (em vez do −Z de uma câmera) inverte o sinal do eixo x de modo quexAxis × up = forward; o quadro permanece destro (sem espelhamento). Não usemakeBasis(xAxis, up, -forward)para uma malha — isso mira −forward (a convenção da câmera) então a malha encara para trás. - Orientando uma câmera para olhar ao longo de
forward(câmeras olham −Z): defina a coluna +Z como-forward—xAxis = normalize(cross(forward, up)), entãomakeBasis(xAxis, up, -forward)(ou apenascamera.lookAt(target)). - Mantenha um
upconsistente do mundo para que os objetos fiquem na vertical; apenas gire primitivas planas para ficarem em pé. - Verifique a orientação de importação glTF; depure com
AxesHelper/ArrowHelper. Auto-teste vertical: personagens ficam no chão, não deitados/afundados.
4. Câmera deve concordar com o movimento
- Mantenha
moveForward/moveRightdedicados para movimento, calculados uma vez e nunca mutados pelo código da câmera (aliasing de um vetor temporário compartilhado faz a câmera e o movimento discordarem — um bug real reproduzível). - Seguir em terceira pessoa:
desired = playerPos + up*height + moveForward*(-followDist); interpole a câmera em direção a ele (use suavização exponencial, escalonada por delta),lookAt(player). - Ordem de depuração isolando a camada: (1) teclas registram → (2) sinais de movimento corretos → (3) câmera concorda. Corrija nessa ordem.
5. Desempenho
- Minimize chamadas de draw (
renderer.info.render.calls, alvo <100): compartilhe materiais,InstancedMesh/BatchedMeshpara objetos repetidos, atlas. - Descarte recursos GPU você mesmo (
geometry/material/texture.dispose()) ao mudar de nível — three.js não faz GC neles. Pool balas/inimigos/partículas. - Sem alocações por quadro (reutilize vetores temporários). Comprima texturas; LOD para distância.
6. Assets (evite a armadilha da foto gerada)
- Elementos 3D interativos (viewmodels de armas, personagens, adereços, projéteis) → construa a partir de geometria 3D / glTF, não de uma imagem gerada. Um JPG foto-realista plano de uma arma nas mãos usado como viewmodel de FPS parece errado, não pode animar e (JPG não tem alpha) renderiza como uma caixa preta. Pairote um viewmodel 3D real à câmera como uma camada de renderização sobreposta.
- Reserve geração de imagem para assets 2D planos apenas (texturas, fundos de céu/menu,
sprites 2D, arte de UI). Nunca use uma foto gerada como malha 3D,
viewmodel ou substituto de personagem — construa-os em geometria 3D / glTF.
Defina
crossOrigin="anonymous"em imagens desenhadas em canvas/texturas. Veja a skillimagine-grok-build(apenas 2D — ferramentas de imagem não podem produzir 3D real). - Doutrina de arte de jogo pronta para engine → abra
game-asset-core(../game-asset-core/) para padrões + verificação cega + disciplina de repetição, então o especialista correspondente:game-animation-frames(leis de loop/movimento),game-tilesets,game-character-consistency,game-ui-icons. Estas são QC/doutrina, não o pipeline de exportação. Não entregue placeholders de palito quando arte real é esperada. - Sprites 2D / folhas de animação de jogo → execute
generate2dsprite(.grok/skills/generate2dsprite/SKILL.md): folhas magenta sólidas#FF00FFimagine_text_to_image+ scripts de pós-processamento chroma (magenta é obrigatório para o processador). Gere PNGs/GIFs transparentes no Canvas/Phaser. Ainda apliquegame-asset-core(+ especialistas de animação/personagem quando relevante). - Mapas 2D / níveis / pacotes de adereços → abra
generate2dmap(.grok/skills/generate2dmap/SKILL.md). Prefira base apenas com fundação + adereços separados/colisão para mapas jogáveis. Padrão do navegador:raw_canvas/ Phaser. Chão/paredes com tile → tambémgame-tilesetspara verificações de emenda 2×2. - Locomoção mais densa opcional → execute
video2dsprite(Grokimagine_image_to_video+ scripts de sandbox; base magenta). Prefiragenerate2dspritepara heróis nítidos de produção. Usegame-animation-framespara leis de loop/teste de flip; prefiravideo2dspriteem vez de colheita ad-hoc apenas com ffmpeg neste sandbox.
7. Áudio, salvamento, feel
- Áudio: desbloqueie
AudioContextno primeiro gesto do usuário (toque para iniciar) senão o iOS fica mudo; retome emvisibilitychange. (references/audio.md) - Salvamento:
localStorage/IndexedDB com um campoversion+ migrações. - Juice: shake de tela, hit-stop, tweens suavizados, partículas — barato, enorme aumento de qualidade percebida. Mantenha apresentação separada da simulação.
8. Mobile
- Diferencie o tamanho do buffer do canvas do tamanho CSS; respeite
devicePixelRatio. touch-action: none, ajuste letterbox para uma resolução base, lide com orientação.- Controles de toque (joystick virtual + botões de ação), alvos ≥44px.
Stack / escolha da engine
- 3D → three.js, idealmente via @react-three/fiber + drei (encaixa no app
React; drei fornece pointer-lock/controls/loaders) + @react-three/rapier para
física/controladores de personagem. Veja
references/3d-libs.md. - 2D → Canvas 2D nativo é suficiente para snake/tetris/flappy/platformer; recorra ao Phaser apenas quando o gênero precisar.
- Essas dependências de jogo não estão pré-instaladas — instale-as com
npm install(e certifique-se de que estejam empackage.jsonpara que o build do Vercel as tenha).
Critérios de conclusão (antes de "pronto")
- Carrega sem erros no console; jogabilidade visível (não um canvas em branco).
- Auto-teste da skill
controlspassou (A = esquerda / D = direita da câmera chase enquanto move para frente; inverta um sinal se estiver invertido). Não apenas captura de tela. - Auto-testes de vertical 3D e concordância da câmera passam (§3, §4).
- Funciona em viewport mobile com controles de toque.
- Build de produção (
npm run build) renderiza a saída construída, não apenas dev. - Compartilhar / cartão X: abra a skill
og—public/og.jpgpersonalizado e"type": "x:game"emsrc/lib/og/site.json. X usaog:type="x:game"para apresentar o unfurl como um cartão de jogo; não usetwitter:cardnem inventex:typepara isso.browser-smoke/brand-checkavisam quando apps canvas omitem o camposite.json.