---
sidebar_position: 3
title: "Extensibilidade"
---

Esta página descreve como estender especificamente as atividades de programação.

## Visão geral

```mermaid
graph TB
    subgraph NOVA["Nova Atividade de Programação"]
        BASE[BaseGameScene
herança obrigatória]
        CONFIG[config/
fases e parâmetros]
        BLOCKS[blocks/
blocos customizados]
        VALID[validation/
validadores de fase]
    end
    subgraph BLOCOS["Novos Blocos Blockly"]
        DEF[Definição JSON
ou registerBlockType]
        GEN[Gerador JavaScript
produz código executável]
        TOOL[Toolbox
categorias e posição]
    end
    BASE --> CONFIG
    CONFIG --> BLOCKS
    BLOCKS --> VALID
    DEF --> GEN
    GEN --> TOOL
```

## Criando uma nova atividade de programação

### Estrutura de pastas

Cada atividade de programação segue a mesma convenção de organização:

```text
app/src/atividades/programacao/<nova-atividade>/
  <NovaAtividade>.jsx   ← componente de entrada
  game.js               ← runtime Phaser
  blocks/               ← blocos específicos desta atividade
  config/               ← fases, parâmetros e configuração
  hooks/                ← setup do interpretador
  validation/           ← regras de sucesso e falha por fase
  assets/               ← mídias da atividade
```

### Herança de BaseGameScene

Toda atividade de programação estende `BaseGameScene` e implementa os hook methods necessários:

```javascript
// app/src/shared/BaseGameScene.js
// Pontos de extensão disponíveis:

onBeforeRun()    // chamado antes de iniciar execução
onReset()        // chamado ao resetar a atividade
onSuccess()      // chamado quando a fase é concluída
onFailure()      // chamado quando a execução falha
```

Referência externa: https://refactoring.guru/design-patterns/template-method

### Registro da atividade

Após criar a estrutura, registre a atividade em `app/src/config/gameRegistry.js`:

```javascript
// Exemplo de entrada no registry
{
  id: 'nova-atividade',
  title: 'Nome da Atividade',
  component: () => import('../atividades/programacao/nova-atividade/NovaAtividade.jsx'),
  // ... outros metadados
}
```

Referência externa: https://martinfowler.com/eaaCatalog/registry.html

## Criando novos blocos Blockly

### Estrutura de um bloco customizado

```mermaid
flowchart LR
    DEF["Definição
(JSON ou registerBlockType)"] --> GEN["Gerador
(produz JavaScript)"]
    GEN --> TOOL["Toolbox
(adiciona ao painel)"]
    TOOL --> INT["Interpretador
(expõe API)"]
```

Um bloco customizado tem três partes:

1. **Definição**: descreve aparência e conexões do bloco.
2. **Gerador**: define o código JavaScript que o bloco produz ao ser executado.
3. **Toolbox**: posiciona o bloco na categoria correta do painel lateral.

Referências externas:

- Blockly custom blocks: https://developers.google.com/blockly/guides/create-custom-blocks/overview
- Blockly code generators: https://developers.google.com/blockly/guides/create-custom-blocks/generating-code/overview

### Expondo APIs para o interpretador

Blocos que precisam interagir com o runtime Phaser ou com o estado da atividade devem expor funções via `hooks/interpreterSetup`:

```javascript
// Exemplo: expor função para o interpretador
interpreterInstance.setProperty(
  globalObject,
  'minhaFuncao',
  interpreter.createNativeFunction(function (arg) {
    // lógica nativa disponível para o código do usuário
  })
);
```

Referência externa: https://github.com/NeilFraser/JS-Interpreter

## Extensão do sistema de blocos globais

Blocos compartilhados entre atividades ficam em `app/src/blockly/`. Alterações ali afetam todas as atividades que os utilizam, portanto:

- Sempre valide em mais de uma atividade antes de publicar.
- Mantenha retrocompatibilidade de interface quando possível.

Referência externa: https://developers.google.com/blockly/guides/overview
