---
sidebar_position: 5
title: "Entendendo o Phaser"
---

O Phaser é o motor usado para renderizar e animar as atividades de programação que precisam de canvas, sprites e lógica de cena. Ele roda dentro do painel direito da interface enquanto o Blockly fica no painel esquerdo.

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

## Como o Phaser se integra ao React

O React não gerencia o Phaser diretamente. A instância Phaser é criada e destruída pelo hook `usePhaser`, que expõe apenas um `ref` de container. Todo o ciclo de vida do Phaser acontece fora da árvore do React.

```mermaid
flowchart TD
    GB[GameBase] -->|gameFactory + config| UP[usePhaser]
    UP -->|new Phaser.Game| PH[Instância Phaser]
    PH -->|monta em| DIV[div#gameContainerRef]
    DIV -->|dentro de| GA[GameArea]
```

Referência externa: https://react.dev/reference/react/useRef

## Hook usePhaser

`app/src/hooks/usePhaser.js`

O hook recebe a `gameFactory` e a configuração da fase atual. Ele:

1. Cria uma nova instância Phaser ao montar ou ao trocar de fase.
2. Destrói a instância anterior antes de criar a nova.
3. Redimensiona o canvas ao alternar entre mobile e desktop.

```mermaid
sequenceDiagram
    participant R as React (GameBase)
    participant H as usePhaser
    participant P as Phaser.Game

    R->>H: currentPhase muda
    H->>P: destroy(true) - destrói instância anterior
    H->>H: aguarda um frame (setTimeout 10ms)
    H->>P: new Phaser.Game(config) - cria instância nova
    P->>P: inicia a cena da fase
```

O timeout de 10ms garante que o DOM processou o cleanup antes da nova instância tentar montar no mesmo container.

### Parâmetros

| Parâmetro | Descrição |
|---|---|
| `gameFactory` | Função que recebe `(container, phaseConfig, customFailureHandler, currentPhase, gameConfig)` e retorna a config Phaser |
| `phaseConfig` | Configuração da fase atual (blocos permitidos, timeout, etc.) |
| `currentPhase` | Número da fase - mudança dispara recriação |
| `customFailureHandler` | Handler opcional para falhas customizadas |
| `gameConfig` | Configuração completa da atividade |

## gameFactory

Cada atividade implementa uma `gameFactory`, uma função que monta a configuração Phaser para aquela atividade e fase específica.

```javascript
// Exemplo simplificado de gameFactory
export const aspiradorFactory = (container, phaseConfig, customFailureHandler, currentPhase, gameConfig) => ({
  type: Phaser.AUTO,
  parent: container,
  scene: [AspiradorScene],
  scale: {
    mode: Phaser.Scale.FIT,
    width: 800,
    height: 600,
  },
  registry: {
    values: { configFase: phaseConfig, gameConfig, customFailureHandler }
  },
});
```

A configuração passa os dados da fase para a cena via `registry.values`, que `BaseGameScene.init()` lê ao inicializar.

## Comunicação Phaser → React

O Phaser não acessa o React diretamente. A comunicação é feita pelo `gameEventBus`:

```mermaid
sequenceDiagram
    participant S as Cena Phaser
    participant B as gameEventBus
    participant GA as GameArea (React)
    participant CTX as GameStateContext

    S->>B: gameEventBus.emit('gameSuccess')
    B->>GA: ouvinte dispara
    GA->>CTX: finalizeWithSuccess()
    CTX->>CTX: estado → SUCESSO
```

A cena Phaser emite `gameSuccess` ou `gameFailure` no barramento. O `GameArea` escuta esses eventos e atualiza o `GameStateContext`.

Arquivos:
- `app/src/utils/gameEvents.js`
- `app/src/components/game/GameArea.jsx`

## Ciclo de vida de uma cena

```mermaid
stateDiagram-v2
    [*] --> init: Phaser.Scene.init()
    init --> preload: carrega assets
    preload --> create: monta sprites e objetos
    create --> idle: aguarda execução
    idle --> running: gameEventBus executeCode
    running --> validating: interpretador termina
    validating --> success: validação passa
    validating --> failure: validação falha
    success --> idle: usuário reseta
    failure --> idle: usuário reseta
```

A transição `idle → running` é acionada pelo `GameArea` ao receber o código do `GameStateContext`. A transição `running → validating` ocorre quando o interpretador termina e `BaseGameScene.setupStandardController` agenda a validação.

Referência externa: https://docs.phaser.io/phaser/concepts/scene-lifecycle
