SPIDERWORKS

Bastidores

Bastidores: como criamos tutoriais guiados que ensinam jogando

Por Fernando Capanema, SpiderWorks · Publicado em

Telas de regras são lidas por poucos jogadores. Nos jogos do lote preparado em outubro de 2026, trocamos o cartão de instruções por um tutorial que acontece dentro da primeira partida: o jogo aponta onde tocar, espera a jogada de verdade e só então avança. Este texto descreve como esse módulo funciona e o que mudou depois de testá-lo em um celular.

Por que ensinar jogando

O caminho mais simples é mostrar um cartão com as regras na primeira vez em que a pessoa toca em Jogar. O cartão continua existindo, acessível pelo menu de pausa, mas como primeira experiência ele tem um problema: pede para ler antes de deixar jogar. Quem fecha o cartão sem ler chega à mesa sem saber, por exemplo, que no Spider só se movem juntas cartas do mesmo naipe.

A alternativa foi um tutorial guiado dentro da partida real. Ele está presente no Spider Solitaire, no FreeCell, no Pirâmide e TriPeaks, no Caça-Palavras, no Mato Minado, no Tile Match Mahjong, no Block Puzzle 8x8 e no Jardim Mágico. O núcleo comum mantém o comportamento antigo como alternativa: um jogo sem tutorial guiado abre o cartão de regras uma vez.

Um tutorial descrito como lista de passos

O código fica em um único arquivo compartilhado, copiado para cada jogo por um script de sincronização. Cada jogo descreve seu tutorial como uma lista de passos. Um passo diz qual elemento destacar, qual texto mostrar, se aparece uma mão animada e qual acontecimento do jogo faz o tutorial avançar:

GameCore.coach.run('first', [
  { target: '#gift', text: 'Toque no presente', hand: 'tap', wait: 'spawn' },
  { target: () => el, to: () => el2, text: 'Arraste...', hand: 'drag', wait: 'merge' },
  { text: 'Pronto!', wait: 'next' }   // mostra um botão "Continuar"
]);

O alvo pode ser um seletor fixo ou uma função. A função é o que permite tutoriais construídos a partir da partida real: no FreeCell, o alvo é a carta que a lógica de dicas escolheu como boa jogada naquela distribuição; na Pirâmide, é um par livre que soma 13 naquela mesa. Se não houver par livre, o tutorial pede para tocar no monte e tenta de novo, até algumas vezes.

Destaque com máscara SVG

O efeito visual é uma camada escura sobre a tela com “buracos” sobre o que importa. Muitos passos precisam de dois buracos ao mesmo tempo: a carta e o destino, a bomba e o número que a denuncia.

Um recurso comum para esse efeito é um elemento com uma sombra enorme ao redor, mas ele só produz um buraco. A solução adotada foi uma máscara SVG. A camada escura é um retângulo do tamanho da tela com uma máscara branca; cada área destacada é um retângulo preto, com cantos arredondados, desenhado dentro da máscara. Onde a máscara é preta, a camada escura some. Dois retângulos sobrepostos continuam transparentes, sem sombras somadas. Sobre cada buraco fica um contorno amarelo pulsante; o segundo contorno é tracejado, para indicar o destino.

A posição dos buracos é recalculada a cada 200 ms a partir das coordenadas reais dos elementos. Isso cobre cartas que se movem, rotação de tela e mudanças de layout sem que cada jogo precise avisar o tutorial. A camada também se esconde sozinha quando algum diálogo, como a pausa, está aberto.

A mão que toca e arrasta

Texto explica o quê; a mão mostra o como. Ela tem duas animações em CSS: “tocar”, um pulso sobre o alvo, e “arrastar”, um deslocamento da origem ao destino, repetido em ciclo. As coordenadas de início e fim são passadas como variáveis CSS, então a mesma animação serve para qualquer distância e direção.

O balão de texto é posicionado na borda da tela oposta ao alvo. Se, mesmo assim, ele cobrir a área destacada, vai para o lado com mais espaço. Parece detalhe, mas um balão sobre as casas vizinhas no campo minado esconde exatamente os números que o texto está explicando.

Passos que esperam a jogada real

A decisão central é que a maioria dos passos não tem botão “Próximo”. O passo declara um nome de evento, e o jogo avisa o tutorial quando a ação acontece de verdade. O tutorial só avança se o evento recebido é o que o passo atual espera:

event(name) {
  if (index < 0 || !steps[index] || steps[index].wait !== name) return false;
  index++;
  setTimeout(show, steps[index - 1].delay ?? 350);
  return true;
}

Isso tem duas vantagens. O jogador aprende fazendo, e não lendo; e o tutorial não precisa simular nada, porque a jogada é processada pelas mesmas regras de sempre. A pequena espera antes do próximo passo deixa a animação da jogada terminar antes de o destaque mudar de lugar.

Há também passos que se pulam sozinhos. Se o jogador já ligou o botão de marcar bandeiras antes de o tutorial pedir, o passo correspondente detecta isso ao começar e avança, em vez de pedir uma ação que já foi feita.

Pular, rever e não insistir

Todo tutorial tem um botão “Pular tutorial”, exceto no último passo, em que ele não faz mais sentido. Concluir ou pular marca o tutorial como visto, e ele não aparece de novo. Uma interrupção causada pelo próprio jogo, como trocar de modo no meio da explicação, não marca como visto: o tutorial volta na próxima oportunidade.

SituaçãoMarca como visto?O que acontece depois
Jogador conclui todos os passosSimNão aparece mais
Jogador toca em “Pular tutorial”SimNão aparece mais
Jogo interrompe (troca de modo, fim da fase)NãoVolta na próxima partida
Jogador toca em “Rever tutorial” no menuApaga o registroVolta na próxima partida

O botão “Rever tutorial” fica no menu inicial de cada jogo. Ele não abre o tutorial na hora; apaga o registro e avisa que o tutorial voltará na próxima partida, porque os passos dependem de uma mesa recém-distribuída.

O caso do Mato Minado

O tutorial do Mato Minado foi o que mais mudou. Campo minado é o jogo do lote com mais conceitos novos de uma vez: números que se referem às vizinhas, bandeiras, um botão que muda o efeito do toque e vidas. A primeira versão do tutorial, testada em um celular, se mostrou confusa, e foi reescrita do zero com uma regra simples: cada passo ensina uma coisa e, sempre que possível, pede um toque.

A versão atual tem sete passos curtos:

  1. Tocar na moita central, que é sempre segura.
  2. Ver um número destacado junto da moita que, comprovadamente, tem bomba.
  3. Ligar o botão Marcar.
  4. Tocar na moita da bomba para pôr a bandeira.
  5. Desligar o botão Marcar.
  6. Roçar uma moita segura ao lado do número que já tem sua bomba marcada.
  7. Saber que cada bomba custa uma das três vidas e que existe a dica.

Um cuidado importante foi que cada frase do tutorial fosse literalmente verdadeira naquela mesa. A bomba mostrada no passo 2 é escolhida entre os números cujas moitas fechadas são exatamente tantas quanto o próprio número, e o jogo prefere um 1 que toca uma única moita. A casa segura do passo 6 é escolhida ao lado de um número cujas bombas já estão todas marcadas e confirmadas pela lógica. Assim, o tutorial ensina a dedução real, e não apenas “confie em mim, toque aqui”. Quando a mesa não oferece um exemplo tão limpo, o texto muda para uma formulação mais modesta.

Proteções específicas de cada jogo

Um tutorial que deixa o jogador errar no meio da explicação ensina a coisa errada. Por isso, alguns jogos acrescentam proteções que só valem enquanto o tutorial está ativo. No Mato Minado, a bomba que está sendo explicada não pode ser roçada por engano: o toque é recusado com o aviso “Cuidado: aí tem bomba!”, e nenhuma vida é perdida. No passo de marcar, só a moita destacada aceita bandeira.

function coachGuard(i, flag) {
  const w = coachWait();
  if (!w || !state.cells || plan.mine < 0) return false;
  if (!flag && i === plan.mine && ['next', 'markOn', 'flagMine', 'markOff'].includes(w)) {
    say('Cuidado: aí tem bomba! Use o 🚩 Marcar.', 'bad'); return true;
  }
  if (flag && w === 'flagMine' && i !== plan.mine && !state.cells[i].flagged) {
    say('Marque a moita destacada.'); return true;
  }
  return false;
}

Escolher a casa segura também evita outro problema: se ela abrisse a última área da fase, o jogador venceria no meio do tutorial. O jogo dá preferência a casas que não encerram a fase.

Lições