decoda/docs/docs/crie-suas-atividades/usando-os-exemplos.md

sidebar_position, title

sidebar_position	title
2	Usando os Exemplos

As atividades Exemplo e Exemplo 2 foram criadas especificamente como código de referência comentado para novos desenvolvedores. Elas implementam o fluxo arquitetural completo na sua forma mais simples possível.

Atividade Exemplo — movimento em grade

Rota: /atividades/programacao/exemplo
Código: app/src/atividades/programacao/exemplo/

O aluno move o logo da Decoda em uma grade 5×5 até um alvo verde usando blocos de movimento e repetição.

Conceito ensinado: Sequenciamento + Laços de Repetição
Blocos: mover para DIREITA, mover para BAIXO, repetir N vezes, número
Limite: 6 blocos  →  força o uso de loops em vez de repetição manual
Sucesso: sprite atinge a célula (4,4)
Falha: sprite sai dos limites da grade

O que cada arquivo demonstra

Arquivo	O que ensina ao desenvolvedor
ui/constants.js	Como definir assets, cores e dimensões separados do código de jogo
ui/layout.js	Como criar grade, alvo e sprite em funções isoladas (o game.js fica limpo)
game.js — preload()	Como carregar um asset de /public via URL: this.load.image(chave, "/img/logo.png")
game.js — _checarAlvo()	Como detectar condição de sucesso durante a execução e usar stopInternal()
game.js — _falharSaida()	Como detectar condição de falha e acionar handleFailure() antes que o interpreter termine
hooks/setupExemploAPI.js	Como registrar funções assíncronas no JS-Interpreter via createAsyncFunction
validation/validators.js	Como estender BaseGameValidator e ler estado da cena via sceneRef

Solução de referência

// Solução ótima — exatamente 6 blocos
repetir(4) { moverDireita(); }
repetir(4) { moverBaixo(); }

---

Atividade Exemplo 2 — texto

Rota: /atividades/programacao/exemplo2
Código: app/src/atividades/programacao/exemplo2/

O aluno usa o bloco imprimir com texto (literal ou concatenado) para exibir exatamente "SOBERANIA DIGITAL" no display.

Conceito ensinado: Strings e Concatenação de texto
Blocos: imprimir, texto (literal), juntar texto
Limite: 4 blocos  →  comporta tanto a solução simples quanto a com concatenação
Sucesso: scene.textoAtual === "SOBERANIA DIGITAL"
Falha: qualquer outro texto impresso

O que cada arquivo demonstra

Arquivo	O que ensina ao desenvolvedor
ui/constants.js	Estilos de texto Phaser centralizados (fontes, cores)
ui/layout.js	Como criar um display e retornar a referência para a cena atualizá-la
hooks/setupExemplo2API.js	Como registrar funções síncronas via createNativeFunction, e como extrair valores de string do JS-Interpreter
game.js — imprimir()	Exemplo de API que atualiza estado interno (textoAtual) e visual (textoDisplay) ao mesmo tempo
validation/validators.js	Validação por comparação direta de valor de estado (sem percorrer historico)

Soluções de referência

// Solução simples — 2 blocos
imprimir("SOBERANIA DIGITAL");

// Solução com concatenação — 4 blocos (ensina text_join)
imprimir(juntar("SOBERANIA", " DIGITAL"));

---

Como usar os exemplos como base

Opção A — copiar e renomear

1. Duplique a pasta exemplo/ ou exemplo2/ com o nome da sua atividade.
2. Renomeie os arquivos (ex: ExemploGame.jsx → MeuJogoGame.jsx).
3. Faça um Find & Replace de "exemplo" → "meu-jogo" e ExemploScene → MeuJogoScene em todos os arquivos.
4. Ajuste config.js com os dados da sua atividade.
5. Registre a rota em app/src/App.jsx.

Opção B — seguir o passo a passo

Use os exemplos como resposta de gabarito enquanto segue o Passo a Passo. Cada etapa do guia aponta para o arquivo correspondente no exemplo.

---

Arquivos que NÃO precisam mudar

Estes fazem parte da infraestrutura da plataforma e são herdados automaticamente:

• BaseGameScene — ciclo de execução completo
• BaseGameValidator — checks genéricos (histórico vazio, sequência esperada)
• GameInterpreter — execução segura do código do aluno
• ApiHelpers — utilitários para registrar funções no interpreter
• GameBase, GameEditor, BlocklyEditor — componentes React do shell do jogo
• GameStateProvider / useGameState — contexto de estado (fases, debug, falhas)
• gameEventBus — canal de comunicação Phaser → React