---
sidebar_position: 6
title: "Entendendo o BaseGameScene"
---

`BaseGameScene` é a classe base que todas as cenas de atividades de programação herdam. Ela centraliza o ciclo de execução, a integração com o interpretador, o gerenciamento de áudio e o highlight de blocos.

Arquivo: `app/src/shared/BaseGameScene.js`

Referência externa (padrão Template Method): https://refactoring.guru/design-patterns/template-method

## Responsabilidades

```mermaid
graph TD
    BSG[BaseGameScene] --> INIT[Inicialização
recebe configFase e gameConfig]
    BSG --> CTRL[Orquestração de execução
setupStandardController]
    BSG --> INTERP[Gerencia GameInterpreter
executa código passo a passo]
    BSG --> AUDIO[Áudio global
win / fail]
    BSG --> HIGH[Highlight de blocos
durante execução]
    BSG --> HOOKS[Hook methods
sobrescritos pelas subclasses]
```

## Hierarquia de herança

```mermaid
classDiagram
    class `Phaser.Scene` {
        +init()
        +preload()
        +create()
        +update()
    }
    class BaseGameScene {
        +init(data)
        +setupStandardController(apiFactory, validatorFunc)
        +highlightBlock(id)
        +playAudio(key)
        +aguardar(segundos)
        +checkRegex(codigo)
        +onInit()
        +onBeforeRun()
        +onReset()
        +onSuccess()
        +onFailure()
    }
    class AspiradorScene {
        +onBeforeRun()
        +onReset()
        +onSuccess()
    }
    class SemaforoScene {
        +onInit()
        +onBeforeRun()
        +onSuccess()
        +onFailure()
    }
    `Phaser.Scene` <|-- BaseGameScene
    BaseGameScene <|-- AspiradorScene
    BaseGameScene <|-- SemaforoScene
```

## Ciclo de execução

```mermaid
sequenceDiagram
    participant GEB as gameEventBus
    participant SC as Cena (subclasse)
    participant BSG as BaseGameScene
    participant INT as GameInterpreter

    GEB->>BSG: executeCode(codigo, workspace)
    BSG->>BSG: validação de regex (se configurada)
    BSG->>SC: onBeforeRun() - hook opcional
    BSG->>INT: executeCode(codigo, apiFactory)
    INT-->>BSG: resultado (ou timeout)
    BSG->>BSG: aguarda delayValidacao (padrão 1s)
    BSG->>BSG: handleValidation(validatorFunc)
    alt validação passou
        BSG->>GEB: emit('gameSuccess')
        BSG->>SC: onSuccess() - hook opcional
    else validação falhou
        BSG->>GEB: emit('gameFailure')
        BSG->>SC: onFailure() - hook opcional
    end
```

## Hook methods disponíveis

São os pontos de extensão que cada atividade implementa. Nenhum é obrigatório - a classe base tem implementações padrão vazias.

| Hook | Quando é chamado | Uso típico |
|---|---|---|
| `onInit(data)` | Durante `init()`, após configurar o interpretador | Inicializar estado interno da atividade |
| `onBeforeRun()` | Antes de executar o código | Resetar posição de sprites, animações iniciais |
| `onReset()` | Ao resetar a atividade | Restaurar estado visual ao ponto inicial |
| `onSuccess()` | Após validação positiva | Animação de vitória, efeitos visuais |
| `onFailure()` | Após validação negativa | Animação de falha, feedback visual |

## setupStandardController

O método que conecta os eventos do `gameEventBus` ao ciclo de execução. Deve ser chamado em `create()` pela subclasse.

```javascript
// Em AspiradorScene.create():
this.setupStandardController(
  (scene) => criarApiAspiradorFase(scene, scene.configFase), // apiFactory
  validarAspiradorFase  // validatorFunc(historico, configFase, gameConfig)
);
```

A `apiFactory` recebe `this` (a cena) e retorna o objeto com as funções que o interpretador expõe ao código do usuário (ex.: `moverFrente()`, `virarEsquerda()`).

A `validatorFunc` recebe o histórico de ações, a configuração da fase e a configuração global da atividade, e retorna `true` para sucesso ou `false` para falha.

## Validação por regex

Se a fase define `configFase.validationRegex`, o código gerado pelo Blockly é testado antes da execução. Se não passar, a falha é emitida imediatamente, sem rodar o interpretador.

```javascript
// configFase.js de uma atividade
{
  validationRegex: /repita\(\d+\)/,  // exige uso de repetição
  mensagens: {
    erroEstrutura: 'Você precisa usar o bloco Repita para resolver esta fase.'
  }
}
```

## Timeout de execução

Cada fase pode definir `configFase.timeout` em segundos (padrão: 15s). Se o interpretador não terminar dentro do prazo, a execução é interrompida e a falha é disparada com a mensagem de timeout.

Isso protege contra loops infinitos no código do usuário.

## Proteção contra execução dupla

Se o usuário clicar em Executar enquanto uma execução ainda está ativa, `BaseGameScene` detecta o estado `isRunning` e força um cleanup antes de iniciar a nova execução. Isso evita que dois interpretadores rodem em paralelo sobre a mesma cena.

## Áudio global

A classe pré-carrega sons de vitória e falha compartilhados entre todas as atividades. Subclasses podem usar `playAudio(key)` e `stopAudio(key)` sem precisar carregar os assets individualmente.

```javascript
// Em onSuccess() de uma subclasse:
this.playAudio('global_win');
```

Referência externa: https://docs.phaser.io/phaser/concepts/audio
