# dtom-ass/rok_combat_game architecture

> Architecture diagram of the GitHub repository dtom-ass/rok_combat_game, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dtom-ass/rok_combat_game
- Repository: https://github.com/dtom-ass/rok_combat_game

## Overview

1. **Overall shape**
   - This is a Java turn-based combat game built around an MVC split.
   - The repo currently contains **two presentation paths**: a legacy console view and an in-progress **JavaFX GUI migration**.
   - The architecture centers on a small domain model, a set of controllers that drive game flow, and scene-based UI screens.

2. **Application entry and bootstrap**
   - `app/Main.java` is the main application entry point in the tree.
   - The README also mentions a JavaFX test launcher (`view/GUI/guitest.java`) used during migration, but the file tree shows the GUI work now lives under `src/view/scenes` and `src/controller`.
   - JavaFX dependencies are vendored locally in `lib/`, which means the runtime is part of the repository’s operational boundary.

3. **Domain model boundary**
   - `src/model` contains the game’s core data and combat entities.
   - `Warrior.java` and `Culture.java` look like the two foundational abstractions: one for combat units, one for faction/selection context.
   - Concrete implementations are organized under:
     - `src/model/Warriors/` for unit types such as `Archer`, `Fighter`, `Healer`, `Lancer`, `Tank`
     - `src/model/Cultures/` for faction variants such as `AztecaCulture`, `IncaCulture`, `MayaCulture`, `MuiscaCulture`
   - This suggests the game builds combatants by combining a culture and a warrior type, with stats/abilities encoded in subclasses.

4. **Game flow controllers**
   - `src/controller` is the orchestration layer between UI and model.
   - `SelectionController` likely handles initial choice of culture/warrior and feeds the selection into the game state.
   - `BattleController` likely owns turn resolution, attack/heal actions, and win/loss checks.
   - `PlayerController` and `PlayerPanel` suggest a split between player-specific logic and UI-facing state handling.
   - `EnemyBot` is the AI/opponent decision layer and is part of the battle subsystem rather than the model.

5. **Battle subsystem**
   - The combat loop is probably centered in `BattleController`, which mediates turns between player and `EnemyBot`.
   - The battle logic depends on the domain objects in `model` and emits state updates to the view.
   - Because the project is turn-based, the controller layer is the critical boundary where domain state changes are validated and propagated to the UI.

6. **Scene-based GUI structure**
   - `src/view/scenes` contains the JavaFX screens that make up the user journey:
     - `WelcomeScene`
     - `SelectionScene`
     - `BattleScene`
     - `EndScene`
   - This indicates a screen-driven flow rather than a single-page UI.
   - Each scene likely maps to a distinct phase of the game: start, choose units, fight, then final result.

7. **UI components and presentation helpers**
   - `src/controller/indicators/stats.java` suggests a small UI helper for showing combat statistics.
   - `PlayerPanel` likely renders player state in the battle screen.
   - These components sit at the boundary between controller state and visible scene content, translating model values into screen elements.

8. **Legacy console path**
   - `src/view/console/ConsoleLog.java` shows the original console interface still exists.
   - The README states the console version remains functional while the JavaFX migration proceeds.
   - Architecturally, this means the project preserves the combat/game logic while swapping presentation layers, which is a classic MVC migration pattern.

9. **Styling and JavaFX assets**
   - Each scene has its own stylesheet under `src/view/scenes/styles/`:
     - `welcome.css`
     - `Selection.css`
     - `Battle.css`
     - `End.css`
   - Styling is separated from scene logic, so visual design is controlled independently from flow/control code.

10. **Data flow through the game**
    - The expected flow is: app launch → welcome screen → selection screen → battle screen → end screen.
    - Player choices are captured by `SelectionController`, converted into model objects, then consumed by `BattleController`.
    - During combat, state changes from the model are pushed back into scene components like `PlayerPanel` and stats indicators, while `EnemyBot` supplies opponent actions.

11. **External/runtime dependencies**
    - The only material external technology here is **JavaFX**, packaged locally in `lib/`.
    - The `.vscode` launch config in the README implies the app is run with explicit module-path and JavaFX module flags, so the GUI runtime setup is part of the project’s architecture rather than an external service.

12. **Architecture takeaway for diagramming**
    - Draw three main layers: **model** at the bottom, **controllers** in the middle, and **views/scenes** at the top.
    - Show a parallel **console view** path alongside the JavaFX scenes to reflect the migration state.
    - Emphasize the game’s phase-based UI flow and the battle loop, since those are the core runtime behaviors of the repository.

Main entry points: [`src/controller/BattleController.java`](https://github.com/dtom-ass/rok_combat_game/blob/main/src/controller/BattleController.java) (BattleCtrl), [`src/controller/SelectionController.java`](https://github.com/dtom-ass/rok_combat_game/blob/main/src/controller/SelectionController.java) (SelectionCtrl), [`lib`](https://github.com/dtom-ass/rok_combat_game/tree/main/lib) (JavaFX Lib), [`src/view/scenes/WelcomeScene.java`](https://github.com/dtom-ass/rok_combat_game/blob/main/src/view/scenes/WelcomeScene.java) (Welcome)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App"]
  node_app_main(("Main<br/>entrypoint<br/>[Main.java]"))
end

subgraph group_model["Model"]
  node_culture["Culture<br/>domain base<br/>[Culture.java]"]
  node_warrior["Warrior<br/>domain base<br/>[Warrior.java]"]
  node_cultures["Cultures<br/>faction variants"]
  node_warriors["Warriors<br/>unit variants"]
end

subgraph group_controller["Controllers"]
  node_selection_ctrl["SelectionCtrl<br/>flow controller"]
  node_battle_ctrl["BattleCtrl<br/>battle controller"]
  node_player_ctrl["PlayerCtrl<br/>player logic"]
  node_enemy_bot["EnemyBot<br/>ai opponent<br/>[EnemyBot.java]"]
  node_player_panel["PlayerPanel<br/>ui bridge<br/>[PlayerPanel.java]"]
  node_stats["Stats<br/>ui helper<br/>[stats.java]"]
end

subgraph group_view["Views"]
  node_welcome_scene["Welcome<br/>scene<br/>[WelcomeScene.java]"]
  node_selection_scene["Selection<br/>scene"]
  node_battle_scene["Battle<br/>scene<br/>[BattleScene.java]"]
  node_end_scene["End<br/>scene<br/>[EndScene.java]"]
  node_console_log["Console<br/>legacy view<br/>[ConsoleLog.java]"]
end

subgraph group_runtime["Runtime"]
  node_javafx_lib[("JavaFX Lib<br/>runtime deps")]
end

node_app_main -->|"launches"| node_welcome_scene
node_app_main -.->|"also supports"| node_console_log
node_welcome_scene -->|"next"| node_selection_scene
node_selection_scene -->|"captures input"| node_selection_ctrl
node_selection_ctrl -->|"creates"| node_culture
node_selection_ctrl -->|"creates"| node_warrior
node_selection_ctrl -->|"starts battle"| node_battle_ctrl
node_culture -.->|"implemented by"| node_cultures
node_warrior -.->|"implemented by"| node_warriors
node_battle_ctrl -->|"coordinates"| node_player_ctrl
node_battle_ctrl -->|"opposes"| node_enemy_bot
node_battle_ctrl -->|"updates"| node_battle_scene
node_player_ctrl -->|"renders"| node_player_panel
node_player_panel -->|"shows"| node_stats
node_battle_scene -->|"finishes to"| node_end_scene
node_welcome_scene -.->|"runs on"| node_javafx_lib
node_selection_scene -.->|"runs on"| node_javafx_lib
node_battle_scene -.->|"runs on"| node_javafx_lib
node_end_scene -.->|"runs on"| node_javafx_lib
node_console_log -.->|"reuses"| node_battle_ctrl

click node_app_main "https://github.com/dtom-ass/rok_combat_game/blob/main/app/Main.java"
click node_culture "https://github.com/dtom-ass/rok_combat_game/blob/main/src/model/Culture.java"
click node_warrior "https://github.com/dtom-ass/rok_combat_game/blob/main/src/model/Warrior.java"
click node_cultures "https://github.com/dtom-ass/rok_combat_game/tree/main/src/model/Cultures"
click node_warriors "https://github.com/dtom-ass/rok_combat_game/tree/main/src/model/Warriors"
click node_selection_ctrl "https://github.com/dtom-ass/rok_combat_game/blob/main/src/controller/SelectionController.java"
click node_battle_ctrl "https://github.com/dtom-ass/rok_combat_game/blob/main/src/controller/BattleController.java"
click node_player_ctrl "https://github.com/dtom-ass/rok_combat_game/blob/main/src/controller/PlayerController.java"
click node_enemy_bot "https://github.com/dtom-ass/rok_combat_game/blob/main/src/controller/EnemyBot.java"
click node_player_panel "https://github.com/dtom-ass/rok_combat_game/blob/main/src/controller/PlayerPanel.java"
click node_stats "https://github.com/dtom-ass/rok_combat_game/blob/main/src/controller/indicators/stats.java"
click node_welcome_scene "https://github.com/dtom-ass/rok_combat_game/blob/main/src/view/scenes/WelcomeScene.java"
click node_selection_scene "https://github.com/dtom-ass/rok_combat_game/blob/main/src/view/scenes/SelectionScene.java"
click node_battle_scene "https://github.com/dtom-ass/rok_combat_game/blob/main/src/view/scenes/BattleScene.java"
click node_end_scene "https://github.com/dtom-ass/rok_combat_game/blob/main/src/view/scenes/EndScene.java"
click node_console_log "https://github.com/dtom-ass/rok_combat_game/blob/main/src/view/console/ConsoleLog.java"
click node_javafx_lib "https://github.com/dtom-ass/rok_combat_game/tree/main/lib"

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_app_main toneBlue
class node_culture,node_warrior,node_cultures,node_warriors toneAmber
class node_selection_ctrl,node_battle_ctrl,node_player_ctrl,node_enemy_bot,node_player_panel,node_stats toneMint
class node_welcome_scene,node_selection_scene,node_battle_scene,node_end_scene,node_console_log toneRose
class node_javafx_lib toneIndigo
```

## Components

### App

Application entry and launch wiring

- [Main](https://github.com/dtom-ass/rok_combat_game/blob/main/app/Main.java): entrypoint · Application startup entry · `app/Main.java`

### Model

Core combat entities and faction types

- [Culture](https://github.com/dtom-ass/rok_combat_game/blob/main/src/model/Culture.java): domain base · Faction or selection abstraction · `src/model/Culture.java`
- [Warrior](https://github.com/dtom-ass/rok_combat_game/blob/main/src/model/Warrior.java): domain base · Combat unit abstraction · `src/model/Warrior.java`
- [Cultures](https://github.com/dtom-ass/rok_combat_game/tree/main/src/model/Cultures): faction variants · Concrete culture implementations · `src/model/Cultures`
- [Warriors](https://github.com/dtom-ass/rok_combat_game/tree/main/src/model/Warriors): unit variants · Concrete warrior implementations · `src/model/Warriors`

### Controllers

Game flow, battle orchestration, and UI-state bridging

- [SelectionCtrl](https://github.com/dtom-ass/rok_combat_game/blob/main/src/controller/SelectionController.java): flow controller · Handles initial player choices · `src/controller/SelectionController.java`
- [BattleCtrl](https://github.com/dtom-ass/rok_combat_game/blob/main/src/controller/BattleController.java): battle controller · Runs turn resolution and combat flow · `src/controller/BattleController.java`
- [PlayerCtrl](https://github.com/dtom-ass/rok_combat_game/blob/main/src/controller/PlayerController.java): player logic · Player-facing game state coordination · `src/controller/PlayerController.java`
- [EnemyBot](https://github.com/dtom-ass/rok_combat_game/blob/main/src/controller/EnemyBot.java): ai opponent · Opponent decision layer · `src/controller/EnemyBot.java`
- [PlayerPanel](https://github.com/dtom-ass/rok_combat_game/blob/main/src/controller/PlayerPanel.java): ui bridge · Battle UI state and player display · `src/controller/PlayerPanel.java`
- [Stats](https://github.com/dtom-ass/rok_combat_game/blob/main/src/controller/indicators/stats.java): ui helper · Combat statistics indicator helper · `src/controller/indicators/stats.java`

### Views

JavaFX scenes and legacy console presentation

- [Welcome](https://github.com/dtom-ass/rok_combat_game/blob/main/src/view/scenes/WelcomeScene.java): scene · Start screen · `src/view/scenes/WelcomeScene.java`
- [Selection](https://github.com/dtom-ass/rok_combat_game/blob/main/src/view/scenes/SelectionScene.java): scene · Culture and warrior selection screen · `src/view/scenes/SelectionScene.java`
- [Battle](https://github.com/dtom-ass/rok_combat_game/blob/main/src/view/scenes/BattleScene.java): scene · Turn-based combat screen · `src/view/scenes/BattleScene.java`
- [End](https://github.com/dtom-ass/rok_combat_game/blob/main/src/view/scenes/EndScene.java): scene · Result screen · `src/view/scenes/EndScene.java`
- [Console](https://github.com/dtom-ass/rok_combat_game/blob/main/src/view/console/ConsoleLog.java): legacy view · Console presentation path · `src/view/console/ConsoleLog.java`

### Runtime

Vendored JavaFX dependencies

- [JavaFX Lib](https://github.com/dtom-ass/rok_combat_game/tree/main/lib): runtime deps · Vendored JavaFX runtime jars · `lib`

## Connections

- Main → Welcome: launches · Starts the scene-driven UI flow
- Main → Console: also supports · Legacy console presentation path
- Welcome → Selection: next · Moves from start to selection
- Selection → SelectionCtrl: captures input · User choices are handled by controller
- SelectionCtrl → Culture: creates · Builds selected faction context
- SelectionCtrl → Warrior: creates · Builds selected combat unit
- SelectionCtrl → BattleCtrl: starts battle · Hands chosen state into combat flow
- Culture → Cultures: implemented by · Concrete culture variants
- Warrior → Warriors: implemented by · Concrete warrior variants
- BattleCtrl → PlayerCtrl: coordinates · Delegates player-side state handling
- BattleCtrl → EnemyBot: opposes · Uses AI opponent decisions
- BattleCtrl → Battle: updates · Pushes combat state to the UI
- PlayerCtrl → PlayerPanel: renders · Feeds player state into battle panel
- PlayerPanel → Stats: shows · Displays combat statistics
- Battle → End: finishes to · Transitions after combat ends
- Welcome → JavaFX Lib: runs on · JavaFX scene runtime
- Selection → JavaFX Lib: runs on · JavaFX scene runtime
- Battle → JavaFX Lib: runs on · JavaFX scene runtime
- End → JavaFX Lib: runs on · JavaFX scene runtime
- Console → BattleCtrl: reuses · Shares combat/game logic through MVC boundary
