---
sidebar_position: 4
title: "Game Design Pedagógico"
---

Esta página não é sobre tecnologia — é sobre **como pensar antes de escrever código**. Uma atividade tecnicamente perfeita pode ser um fracasso pedagógico se o aluno não aprender nada ou desistir frustrado antes de terminar.

:::warning
**Premissa inegociável**: Toda atividade da Decoda existe para **ensinar ou reforçar um conceito de programação**. Entretenimento é um meio, não o fim. Se a atividade for divertida mas o aluno não aprender nada de programação, ela não pertence à plataforma.
:::

---

## Princípio 1 — Uma fase, um conceito

Cada fase deve ter **um único objetivo de aprendizagem**. Não "aprender loops e condicionais ao mesmo tempo" — ou loops, ou condicionais.

```
✅  Fase 1: O aluno aprende a usar o bloco "repetir N vezes"
✅  Fase 2: O aluno aprende a combinar repetição com condicionais
❌  Fase 1: O aluno aprende repetição, condicionais, variáveis e sensores
```

Isso não significa que a atividade deve ser trivial. Significa que a **novidade cognitiva** introduzida por fase deve ser uma coisa de cada vez.

**Como implementar:** o campo `allowedBlocks` em `config.js` é o seu mecanismo. Libere blocos novos progressivamente conforme as fases avançam.

```javascript
// Fase 1 — só movimento
allowedBlocks: ["mover_direita", "mover_baixo"]

// Fase 2 — adiciona repetição
allowedBlocks: ["controls_repeat_ext", "math_number", "mover_direita", "mover_baixo"]

// Fase 3 — adiciona condicionais
allowedBlocks: ["controls_whileUntil", "robo_if", "sensor_frente", "mover_direita", "mover_baixo"]
```

---

## Princípio 2 — A curva de dificuldade

A progressão de dificuldade deve seguir uma curva suave: o aluno nunca deve sentir um salto abrupto entre duas fases consecutivas.

```
Dificuldade
    │
  5 │                              ╭──── Fase 5
  4 │                     ╭───────╯
  3 │            ╭────────╯
  2 │   ╭────────╯
  1 │───╯
    └──────────────────────────────── Fase
       1    2    3    4    5
```

Se a curva tiver um degrau vertical, o aluno vai travar. Isso gera frustração, não aprendizado.

**Sinais de que a curva está errada:**
- Alunos em teste completam a Fase N facilmente e travam na Fase N+1 por mais de 5 minutos sem progresso.
- A Fase N+1 exige um conceito que nunca foi apresentado antes.
- O `maxBlocks` da Fase N+1 é incompatível com a solução esperada.

**Regra prática:** a Fase N+1 deve ser solucionável por alguém que acabou de completar a Fase N sem ajuda.

---

## Princípio 3 — O `maxBlocks` como professor, não como punição

O limite de blocos é uma **diretriz pedagógica**, não uma punição. Seu papel é impedir que o aluno resolva o problema "na força bruta" sem aprender o conceito esperado.

```javascript
// ❌ Errado: maxBlocks tão alto que qualquer solução serve
{ maxBlocks: 50, allowedBlocks: ["controls_repeat_ext", "mover_direita"] }
// → O aluno coloca 10 blocos "mover_direita" sem usar o loop. Não aprende nada.

// ✅ Correto: maxBlocks força o loop
{ maxBlocks: 4, allowedBlocks: ["controls_repeat_ext", "math_number", "mover_direita"] }
// → Solução: repetir(4) { moverDireita() }  ← exatamente 3 blocos. Ensina loops.
```

**Como calcular o `maxBlocks` ideal:**
1. Escreva a solução ótima (que usa o conceito da fase).
2. Conte os blocos dessa solução.
3. Some 1 ou 2 blocos de margem para pequenas variações.
4. Esse é o seu `maxBlocks`.

---

## Princípio 4 — Mensagens de erro que ensinam

A mensagem de falha é um **momento de aprendizado**. Ela não pode ser genérica, técnica ou intimidadora.

```javascript
// ❌ Errado
mensagens: {
  falha: "Erro: validação falhou.",
  timeout: "Execution timeout exceeded."
}

// ✅ Correto
mensagens: {
  semMovimento: "Seu robô está parado! Use o bloco 'mover' para sair do lugar.",
  saiu: "Ops! O personagem saiu da tela. Verifique quantos passos ele deu.",
  timeoutExcedido: "Tempo esgotado! Seu programa parece estar em loop infinito. Verifique a condição de parada.",
  naoAlcancou: "Quase lá! O personagem não chegou ao destino. Tente ajustar o número de passos."
}
```

**Checklist de mensagem de erro:**
- [ ] Está em português, sem jargão técnico
- [ ] Diz **o que aconteceu** (não apenas "erro")
- [ ] Dá uma **dica** do que verificar (sem entregar a resposta)
- [ ] Usa linguagem de encorajamento ("quase lá", "tente de novo")

---

## Princípio 5 — O ciclo de feedback imediato

O aluno deve receber feedback **visual e imediato** para cada ação que executa. Isso é o que diferencia um jogo educativo de uma tarefa de casa.

```mermaid
flowchart LR
    A[Aluno executa blocos] --> B[Personagem anima]
    B --> C{Condição de fim?}
    C -->|Sucesso| D[Animação de vitória\n+ Modal de parabéns]
    C -->|Falha| E[Animação de erro\n+ Modal com dica]
    C -->|Continua| B
```

**Na prática:**

1. **Toda ação deve ter animação.** Se o personagem "teletransporta" sem transição, o aluno perde a referência do que aconteceu.

2. **`onSuccess()` deve celebrar.** Use tweens, partículas, mudança de cor — qualquer efeito que transmita conquista. O modal de sucesso aparece *depois* da animação.

3. **`onFailure()` deve ser empático, não assustador.** Um leve tremor, uma cor vermelha por um instante. Nada que desanime o aluno.

4. **O highlight de blocos é obrigatório.** Sempre chame `configurarGerador()` em `blocks.js`. Ver o bloco iluminado enquanto executa ajuda o aluno a conectar o bloco visual com a ação no jogo.

---

## Princípio 6 — Projetar contra a frustração

A frustração acontece quando o aluno **não sabe o que fazer a seguir**. Projete a atividade para eliminar esse estado.

### O que causa frustração

| Causa | Como evitar |
|---|---|
| Fase impossível sem conhecimento prévio | Introduza o conceito na fase anterior, ou no texto da fase |
| `timeout` curto demais | Calcule o tempo da execução correta e multiplique por 3 |
| Mensagem de erro genérica | Escreva uma mensagem por condição de falha possível |
| `maxBlocks` abaixo da solução ótima | Sempre teste a solução antes de publicar |
| Fase sem saída (loop inevitável) | Teste com `timeout` ativado; se travar, redesenhe o mapa |
| Salto de dificuldade abrupto | Adicione uma fase de transição |

### A regra dos 5 minutos

Se um aluno iniciante trava em uma fase por mais de 5 minutos sem nenhum progresso visível, a fase está mal projetada. Não é o aluno que está errado.

---

## Princípio 7 — O jogo deve ser jogável sem o enunciado

O texto de `descricao` em `config.js` aparece na interface. Mas o jogo deve fazer sentido mesmo sem que o aluno o leia. O layout visual, os blocos disponíveis e o cenário devem comunicar o objetivo por si mesmos.

```
✅  Um robô no canto superior esquerdo de uma grade, com sujeira espalhada 
    e o cursor piscando no bloco "mover" → o objetivo é óbvio.

❌  Uma tela escura com um ponto e texto dizendo 
    "mova o objeto para a posição de destino" → nada é óbvio.
```

**Dicas de design visual:**
- Use **verde** para o alvo/destino (convenção universal de "vá aqui").
- Use **vermelho** apenas para erro ou perigo.
- A posição inicial do personagem deve estar **visivelmente separada** do alvo.
- O tamanho do personagem deve ser proporcional à grade (não pequeno demais).

---

## Checklist de Game Design

Antes de finalizar uma atividade, valide:

**Pedagogia**
- [ ] Cada fase tem exatamente um conceito principal a ensinar
- [ ] Os blocos disponíveis são os mínimos necessários para o conceito da fase
- [ ] A progressão entre fases é gradual (sem saltos abruptos)
- [ ] A solução ótima usa o conceito que a fase pretende ensinar

**Jogabilidade**
- [ ] `timeout` é pelo menos 3× o tempo da execução da solução correta
- [ ] `maxBlocks` é suficiente para a solução ótima + 1-2 blocos de margem
- [ ] `onSuccess()` tem uma animação de celebração
- [ ] `onFailure()` tem feedback visual empático (tremor, cor)
- [ ] O highlight de blocos está funcionando durante a execução

**Comunicação com o aluno**
- [ ] Cada condição de falha tem sua própria mensagem específica
- [ ] As mensagens usam linguagem de encorajamento
- [ ] O objetivo da fase é visualmente óbvio no cenário
- [ ] O texto de `descricao` é curto, motivador e sem jargão técnico

---

## Referências de boas práticas nas atividades existentes

| Atividade | O que observar |
|---|---|
| **Aspirador** | Progressão pedagógica exemplar: 10 fases com curva gradual de sequência → loops → condicionais → variáveis → algoritmos |
| **Aspirador Fase 1** | `maxBlocks: 3` força o aluno a usar `while` logo na primeira fase |
| **Semáforo** | Uso de `expectedSequence` em `config.js` para validação por sequência exata de ações |
| **Puzzle** | Exemplo de atividade onde a validação ocorre por estado final, não por sequência |