# evfbarros/projeto-jogo-code-arena architecture

> Architecture diagram of the GitHub repository evfbarros/projeto-jogo-code-arena, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evfbarros/projeto-jogo-code-arena
- Repository: https://github.com/evfbarros/projeto-jogo-code-arena

## Overview

1. **Visão geral**
   - O repositório implementa um **RPG por turnos em terminal** em Java, com progressão por campanha e batalhas mediadas por perguntas.
   - A arquitetura é separada em três camadas principais: **telas de interação**, **lógica de jogo/quiz** e **modelo de domínio**.

2. **Ponto de entrada e fluxo principal**
   - `src/main/Main.java` inicia a aplicação e aciona o fluxo do jogo.
   - O jogador percorre um ciclo de telas: **Menu → Seleção de personagem → Mapa/campanha → Batalha → Pergunta → Resultado/atributos**.
   - Esse fluxo é orientado por estado, com cada tela responsável por uma etapa da experiência no terminal.

3. **Camada de telas (`src/screens`)**
   - As classes `MenuScreen`, `CharacterSelectionScreen`, `GameScreen`, `BattleScreen`, `QuestionScreen` e `AttributeScreen` representam a interface textual.
   - Elas não concentram regras de combate ou quiz; atuam como **orquestradoras da interação**, coletando entrada do usuário e repassando decisões para a lógica central.
   - `BattleScreen` e `QuestionScreen` são pontos importantes de transição entre combate e avaliação por perguntas.

4. **Orquestração do jogo (`src/logic/game`)**
   - `GameManager` parece ser o núcleo do estado da partida: personagem atual, combate, progresso e transições.
   - `CampaignManager` controla a **campanha linear pelas ilhas**, provavelmente definindo a sequência de fases, inimigos e marcos da história.
   - `Stats` concentra os atributos e evolução do personagem, apoiando o sistema de XP/nível descrito no README.

5. **Mundo e progressão geográfica (`src/world`)**
   - `Island` e `IslandCreator` modelam as ilhas da East Blue e a estrutura da rota da campanha.
   - Esse subsistema separa a **progressão narrativa/geográfica** da lógica de combate, permitindo que cada ilha carregue dificuldade, inimigos e eventos próprios.

6. **Sistema de quiz (`src/logic/quiz`)**
   - O quiz é um subsistema independente, com abstração base `Question` e variações como `MultipleChoiceQuestion`, `TrueFalseQuestion` e `OpenQuestion`.
   - `Difficulty` define a escala de desafio associada às fases/ilhas.
   - `QuestionBank` armazena ou agrupa questões; `QuestionManager` provavelmente seleciona e entrega perguntas para as batalhas.

7. **Carregamento externo de perguntas**
   - `GoogleSheetsQuestionLoader` é a ponte com o conteúdo externo, carregando perguntas a partir de **Google Sheets publicado em CSV**.
   - Isso cria uma dependência de infraestrutura: o jogo funciona no terminal, mas **depende de acesso à internet** para atualizar/carregar o banco de questões.

8. **Modelo de domínio: personagens, inimigos e ações (`src/entities`)**
   - `Character` é a base para `Player`, `Enemy`, `NPC` e `CrewMember`, indicando herança para tipos de entidade no jogo.
   - `GameObject` sugere uma abstração comum para elementos do mundo.
   - `Attack` representa ações ofensivas, enquanto `CharacterCreator` provavelmente centraliza a criação/configuração de personagens e seus atributos.

9. **Habilidades especiais (`src/entities/ability`)**
   - O pacote de habilidades usa uma abstração comum (`CombatAbility`, `SpecialAbility`) e implementações específicas por personagem/inimigo: Luffy, Zoro, Nami, Usopp, Sanji, Buggy, Arlong etc.
   - Isso funciona como uma variação de **Strategy/Polymorphism**, permitindo que cada personagem tenha comportamento único sem espalhar regras especiais pelo restante do código.
   - `DefaultCombatAbility` funciona como comportamento padrão quando não há habilidade especial ativa.

10. **Combate e regras de exceção**
   - O combate inclui limitações explícitas de uso de ações defensivas e especiais, refletidas nas exceções customizadas:
     - `AtaqueIndisponivelException`
     - `AtaqueInvalidoException`
     - `DefesaIndisponivelException`
     - `DesvioIndisponivelException`
   - Essas exceções indicam que o jogo valida estados de turno, recursos e permissões de ação antes de aplicar efeitos.

11. **Dependências entre subsistemas**
   - As **telas** dependem da **lógica de jogo** para executar ações.
   - A **lógica de jogo** consome o **modelo de domínio** (`entities`, `world`) e o **quiz** para resolver batalhas.
   - O **quiz** fornece a mecânica de decisão que impacta diretamente o combate e a progressão.
   - O resultado é um fluxo bem desacoplado entre interface, regras e dados.

12. **Tecnologia e restrições arquiteturais**
   - A aplicação é em **Java 11+** e usa **terminal como interface**, sem camada gráfica.
   - Como o conteúdo de perguntas vem de uma fonte externa e o jogo é guiado por estados de tela, a arquitetura é essencialmente um **jogo single-player local com serviços externos leves** para conteúdo.

Main entry points: [`src/logic/game/GameManager.java`](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/logic/game/GameManager.java) (Game Manager), [`src/screens/GameScreen.java`](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/screens/GameScreen.java) (Game Screen), [`src/entities/Character.java`](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/entities/Character.java) (Character), [`src/screens/BattleScreen.java`](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/screens/BattleScreen.java) (Battle Screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_entry["Entry & UI"]
  node_node_main["Main<br/>entrypoint<br/>[Main.java]"]
  node_node_menu["Menu<br/>screen<br/>[MenuScreen.java]"]
  node_node_char_select["Character Select<br/>screen"]
  node_node_game_screen["Game Screen<br/>[GameScreen.java]"]
  node_node_battle_screen["Battle Screen<br/>[BattleScreen.java]"]
  node_node_question_screen["Question Screen"]
  node_node_attribute_screen["Attributes<br/>screen"]
end

subgraph group_group_game["Game Logic"]
  node_node_game_manager["Game Manager<br/>state orchestrator<br/>[GameManager.java]"]
  node_node_campaign_manager["Campaign Manager<br/>progression flow"]
  node_node_stats["Stats<br/>progression model<br/>[Stats.java]"]
end

subgraph group_group_domain["Domain & Content"]
  node_node_character["Character<br/>base entity<br/>[Character.java]"]
  node_node_player["Player<br/>entity<br/>[Player.java]"]
  node_node_enemy["Enemy<br/>entity<br/>[Enemy.java]"]
  node_node_attack["Attack<br/>combat action<br/>[Attack.java]"]
  node_node_ability_base["Combat Ability<br/>ability abstraction<br/>[CombatAbility.java]"]
  node_node_default_ability["Default Ability<br/>ability fallback"]
  node_node_special_abilities["Special Abilities<br/>ability implementations"]
  node_node_world["Island World<br/>world model<br/>[Island.java]"]
  node_node_island_creator["Island Creator<br/>world factory<br/>[IslandCreator.java]"]
  node_node_question["Question<br/>quiz base<br/>[Question.java]"]
  node_node_question_manager["Question Manager<br/>quiz orchestrator"]
  node_node_question_bank["Question Bank<br/>quiz store<br/>[QuestionBank.java]"]
  node_node_loader["Sheets Loader<br/>external content loader"]
end

node_node_main -->|"starts"| node_node_menu
node_node_menu -->|"new game"| node_node_char_select
node_node_char_select -->|"begin"| node_node_game_screen
node_node_game_screen -->|"encounter"| node_node_battle_screen
node_node_battle_screen -->|"quiz step"| node_node_question_screen
node_node_question_screen -->|"resolve"| node_node_attribute_screen
node_node_attribute_screen -->|"continue"| node_node_game_screen
node_node_game_screen -->|"drives"| node_node_game_manager
node_node_battle_screen -->|"uses"| node_node_game_manager
node_node_game_manager -->|"orchestrates"| node_node_campaign_manager
node_node_game_manager -->|"updates"| node_node_stats
node_node_game_manager -->|"tracks"| node_node_player
node_node_campaign_manager -->|"navigates"| node_node_world
node_node_world -->|"built by"| node_node_island_creator
node_node_player -->|"inherits"| node_node_character
node_node_enemy -->|"inherits"| node_node_character
node_node_character -->|"uses"| node_node_attack
node_node_character -->|"equipped with"| node_node_ability_base
node_node_ability_base -->|"fallback"| node_node_default_ability
node_node_ability_base -->|"specializes"| node_node_special_abilities
node_node_question_manager -->|"serves from"| node_node_question_bank
node_node_question_manager -->|"instantiates"| node_node_question
node_node_loader -->|"loads"| node_node_question_bank
node_node_question_screen -->|"requests"| node_node_question_manager

click node_node_main "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/main/Main.java"
click node_node_menu "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/screens/MenuScreen.java"
click node_node_char_select "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/screens/CharacterSelectionScreen.java"
click node_node_game_screen "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/screens/GameScreen.java"
click node_node_battle_screen "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/screens/BattleScreen.java"
click node_node_question_screen "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/screens/QuestionScreen.java"
click node_node_attribute_screen "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/screens/AttributeScreen.java"
click node_node_game_manager "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/logic/game/GameManager.java"
click node_node_campaign_manager "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/logic/game/CampaignManager.java"
click node_node_stats "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/logic/game/Stats.java"
click node_node_character "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/entities/Character.java"
click node_node_player "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/entities/Player.java"
click node_node_enemy "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/entities/Enemy.java"
click node_node_attack "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/entities/Attack.java"
click node_node_ability_base "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/entities/ability/CombatAbility.java"
click node_node_default_ability "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/entities/ability/DefaultCombatAbility.java"
click node_node_world "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/world/Island.java"
click node_node_island_creator "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/world/IslandCreator.java"
click node_node_question "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/logic/quiz/Question.java"
click node_node_question_manager "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/logic/quiz/QuestionManager.java"
click node_node_question_bank "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/logic/quiz/QuestionBank.java"
click node_node_loader "https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/logic/quiz/GoogleSheetsQuestionLoader.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_main,node_node_menu,node_node_char_select,node_node_game_screen,node_node_battle_screen,node_node_question_screen,node_node_attribute_screen toneBlue
class node_node_game_manager,node_node_campaign_manager,node_node_stats toneAmber
class node_node_character,node_node_player,node_node_enemy,node_node_attack,node_node_ability_base,node_node_default_ability,node_node_special_abilities,node_node_world,node_node_island_creator,node_node_question,node_node_question_manager,node_node_question_bank,node_node_loader toneMint
```

## Components

### Entry & UI

Terminal entry point and screen flow.

- [Main](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/main/Main.java): entrypoint · Starts the terminal game and hands off to the first screen. · `src/main/Main.java`
- [Menu](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/screens/MenuScreen.java): screen · Initial terminal menu and top-level navigation. · `src/screens/MenuScreen.java`
- [Character Select](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/screens/CharacterSelectionScreen.java): screen · Chooses the playable character before the campaign starts. · `src/screens/CharacterSelectionScreen.java`
- [Game Screen](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/screens/GameScreen.java): screen · Coordinates the campaign flow between map, battles, and results. · `src/screens/GameScreen.java`
- [Battle Screen](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/screens/BattleScreen.java): screen · Runs combat turns and transitions into quiz-driven resolution. · `src/screens/BattleScreen.java`
- [Question Screen](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/screens/QuestionScreen.java): screen · Presents quiz questions and collects answers during battle. · `src/screens/QuestionScreen.java`
- [Attributes](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/screens/AttributeScreen.java): screen · Shows stat changes and post-combat feedback. · `src/screens/AttributeScreen.java`

### Game Logic

State, campaign, and progression orchestration.

- [Game Manager](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/logic/game/GameManager.java): state orchestrator · Central runtime state for the current match and transitions. · `src/logic/game/GameManager.java`
- [Campaign Manager](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/logic/game/CampaignManager.java): progression flow · Controls the linear island campaign and its milestones. · `src/logic/game/CampaignManager.java`
- [Stats](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/logic/game/Stats.java): progression model · Stores character attributes, level, and growth state. · `src/logic/game/Stats.java`

### Domain & Content

Characters, combat abilities, world, and quiz content.

- [Character](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/entities/Character.java): base entity · Common base for players, enemies, NPCs, and crew members. · `src/entities/Character.java`
- [Player](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/entities/Player.java): entity · Playable character state and behavior. · `src/entities/Player.java`
- [Enemy](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/entities/Enemy.java): entity · Hostile combatant used in encounters. · `src/entities/Enemy.java`
- [Attack](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/entities/Attack.java): combat action · Represents an offensive action in combat. · `src/entities/Attack.java`
- [Combat Ability](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/entities/ability/CombatAbility.java): ability abstraction · Shared interface for combat and special ability behavior. · `src/entities/ability/CombatAbility.java`
- [Default Ability](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/entities/ability/DefaultCombatAbility.java): ability fallback · Fallback combat behavior when no special ability applies. · `src/entities/ability/DefaultCombatAbility.java`
- **Special Abilities**: ability implementations · Character- and enemy-specific ability variants.
- [Island World](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/world/Island.java): world model · Island-based campaign geography and routing. · `src/world/Island.java`
- [Island Creator](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/world/IslandCreator.java): world factory · Builds the island progression for the campaign. · `src/world/IslandCreator.java`
- [Question](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/logic/quiz/Question.java): quiz base · Abstract base for quiz questions. · `src/logic/quiz/Question.java`
- [Question Manager](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/logic/quiz/QuestionManager.java): quiz orchestrator · Selects and serves questions for battles. · `src/logic/quiz/QuestionManager.java`
- [Question Bank](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/logic/quiz/QuestionBank.java): quiz store · Holds or groups available quiz questions. · `src/logic/quiz/QuestionBank.java`
- [Sheets Loader](https://github.com/evfbarros/projeto-jogo-code-arena/blob/main/src/logic/quiz/GoogleSheetsQuestionLoader.java): external content loader · Loads quiz content from published Google Sheets CSV. · `src/logic/quiz/GoogleSheetsQuestionLoader.java`

## Connections

- Main → Menu: starts · Application bootstraps into the menu.
- Menu → Character Select: new game · Menu advances to character selection.
- Character Select → Game Screen: begin · Chosen character enters the campaign flow.
- Game Screen → Battle Screen: encounter · Campaign flow enters combat scenes.
- Battle Screen → Question Screen: quiz step · Combat resolution depends on answering questions.
- Question Screen → Attributes: resolve · Results update or display attribute changes.
- Attributes → Game Screen: continue · Returns to the main game flow after feedback.
- Game Screen → Game Manager: drives · Screens delegate state transitions to the game manager.
- Battle Screen → Game Manager: uses · Battle actions are coordinated by runtime state.
- Game Manager → Campaign Manager: orchestrates · Campaign progression is managed as a separate flow.
- Game Manager → Stats: updates · Match state updates character attributes and growth.
- Game Manager → Player: tracks · Current playable entity is stored in game state.
- Campaign Manager → Island World: navigates · Campaign advances across islands.
- Island World → Island Creator: built by · Island progression is assembled by a creator/factory.
- Player → Character: inherits · Playable character extends the shared character base.
- Enemy → Character: inherits · Enemies reuse the shared character base.
- Character → Attack: uses · Characters perform attacks as combat actions.
- Character → Combat Ability: equipped with · Characters can delegate combat behavior to abilities.
- Combat Ability → Default Ability: fallback · Default behavior covers missing special cases.
- Combat Ability → Special Abilities: specializes · Specific abilities implement character- or enemy-specific logic.
- Question Manager → Question Bank: serves from · Questions are selected from the bank.
- Question Manager → Question: instantiates · Manager works with the abstract question model and variants.
- Sheets Loader → Question Bank: loads · External CSV content populates the question bank.
- Question Screen → Question Manager: requests · Screen asks the manager for the next question.