🏛️ Architecture Overview: Dinosaur Exploder

[Last updated: 7th May 2026]

1. High-Level Architecture

The system follows a Layered MVC + ECS pattern:

• Bootstrap Layer: Handles the dual-target (Desktop/Web) launch logic.
• UI & Menu Layer: A chain of specialized menus managing game configuration state.
• Controller Layer: Orchestrates the physics engine, entity spawning, and game lifecycle.
• Domain & Services: Persistent data, achievement logic, and global utilities.
• ECS Layer: The core "Engine" where behaviors are decoupled into reusable components.

---

2. Complete Architecture Diagram

flowchart TD
    %% --- STYLING ---
    classDef bootstrap fill:#bbdefb,stroke:#1976d2,stroke-width:2px,color:#0d47a1
    classDef ui fill:#e1bee7,stroke:#7b1fa2,stroke-width:2px,color:#4a148c
    classDef logic fill:#ffe0b2,stroke:#f57c00,stroke-width:2px,color:#e65100
    classDef domain fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#1b5e20
    classDef ecs fill:#f5f5f5,stroke:#455a64,stroke-width:1px,color:#263238
    classDef interface fill:#ffffff,stroke:#455a64,stroke-dasharray: 5 5

    %% --- 1. BOOTSTRAP LAYER ---
    subgraph Layer_1 [1. Bootstrap & Entrypoints]
        direction LR
        DApp[DinosaurApp]:::bootstrap
        DWApp[DinosaurWebApp]:::bootstrap
        DGUI[DinosaurGUI]:::bootstrap
    end

    %% --- 2. VIEW LAYER ---
    subgraph Layer_2 [2. UI & Scene Management]
        direction TB
        M_Main[DinosaurMenu]:::ui
        M_Pause[PauseMenu]:::ui
        M_Set[SettingsMenu]:::ui
        M_Ship[ShipSelectionMenu]:::ui
        M_Wep[WeaponSelectionMenu]:::ui
        M_Spec[SpecialtyMenu]:::ui
        M_Diff[DifficultySelectionMenu]:::ui
        M_Over[GameOverMenu]:::ui
        U_Helper[MenuHelper]:::ui
    end

    %% --- 3. CONTROLLER LAYER ---
    subgraph Layer_3 [3. Controller & Runtime Logic]
        direction TB
        Ctrl[DinosaurController]:::logic
        Init[GameInitializer]:::logic
        Act[GameActions]:::logic
        Reg[CollisionRegistry]:::logic
        
        subgraph Spawners [Automated Spawners]
            S_En[EnemySpawner]:::logic
            S_Ast[AsteroidsSpawner]:::logic
            S_Boss[BossSpawner]:::logic
            S_Coin[CoinSpawner]:::logic
        end
    end

    %% --- 4. DOMAIN & SERVICES ---
    subgraph Layer_4 [4. Domain Services & Persistence]
        direction TB
        subgraph Managers [Global Services]
            LvlM[LevelManager]:::domain
            AchM[AchievementManager]:::domain
            SpecM[SpecialtyManager]:::domain
            AudM[AudioManager]:::domain
            LangM[LanguageManager]:::domain
            SetP[SettingsProvider]:::domain
        end

        subgraph Models [Data & State]
            GData[GameData]:::domain
            GSet[Settings]:::domain
            HScore[HighScore]:::domain
            TCoins[TotalCoins]:::domain
            GStats[GameOverStats]:::domain
            CHand[CollisionHandler]:::domain
        end
        
        subgraph Achievement_Core [Achievement System]
            Ach[Achievement]:::domain
            AchEv[AchievementEvent]:::domain
        end
    end

    %% --- 5. ECS LAYER ---
    subgraph Layer_5 [5. ECS - Entities & Components]
        direction TB
        Fact[GameEntityFactory]:::ecs
        
        subgraph Comp_Actors [Entity Behaviors]
            C_Player[PlayerComponent]:::ecs
            C_GDino[GreenDinoComponent]:::ecs
            C_RDino[RedDinoComponent]:::ecs
            C_ODino[OrangeDinoComponent]:::ecs
            C_Ast[AsteroidsComponent]:::ecs
            C_Ally[AllyComponent]:::ecs
            C_ADrop[AllyDropComponent]:::ecs
        end

        subgraph Comp_UI [HUD & Logic Components]
            C_Life[LifeComponent]:::ecs
            C_Bomb[BombComponent]:::ecs
            C_Score[ScoreComponent]:::ecs
            C_Heat[WeaponHeatComponent]:::ecs
            C_Prog[LevelProgressBarComponent]:::ecs
            C_Shield[ShieldUIComponent]:::ecs
            C_Coin[CoinComponent]:::ecs
            C_Heart[Heart]:::ecs
            C_ColCoin[CollectedCoinsComponent]:::ecs
        end

        subgraph IFaces [Domain Interfaces]
            I_Pl[[Player]]:::interface
            I_Di[[Dinosaur]]:::interface
            I_Li[[Life]]:::interface
            I_Sc[[Score]]:::interface
            I_Bo[[Bomb]]:::interface
            I_As[[Asteroids]]:::interface
            I_CC[[CollectedCoins]]:::interface
            I_SE[[SpecialtyEffect]]:::interface
            I_CH[[CollisionHandlerInterface]]:::interface
        end
    end

    %% --- RELATIONSHIPS ---
    DWApp -.->|JPro Wrapper| DApp
    DApp --> DGUI
    DApp --> Ctrl
    DApp --> AchM

    M_Main --> M_Ship --> M_Wep --> M_Spec --> M_Diff
    M_Diff -->|Trigger fireNewGame| Ctrl

    Ctrl --> Init
    Ctrl --> Reg
    Init --> Spawners
    Init --> Fact
    Init --> LvlM
    
    Fact --> Comp_Actors
    Fact --> Comp_UI
    
    C_Player -.-> I_Pl
    C_GDino -.-> I_Di
    C_Life -.-> I_Li
    CHand -.-> I_CH

Loading

3. Layer Breakdown & Responsibilities

🚀 Bootstrap (App Layer)

• DinosaurApp: The core entry point for Desktop. Extends GameApplication to configure FXGL settings, input bindings, and high-level game logic.
• DinosaurWebApp: A JPro wrapper that allows the game to render via a web browser while maintaining parity with the desktop version.
• DinosaurGUI: Manages the custom SceneFactory, mapping logical menu states to specific view classes.

🎮 View (Menu Layer)

• Menu Chain: Selection flows linearly to set up the game state: Main Menu -> Ship Selection -> Weapon Selection -> Specialty Selection -> Difficulty Selection.
• FXGLMenu Subclasses: Every menu (e.g., PauseMenu, SettingsMenu, GameOverMenu) inherits from FXGLMenu to leverage engine-level UI management.
• MenuHelper: Provides utility methods for consistent UI styling, language localization, and button generation across all menus.

🧠 Logic (Controller Layer)

• DinosaurController: The orchestrator. It registers physics/collisions via the CollisionRegistry and triggers the GameInitializer.
• GameInitializer: Handles the session "startup," including spawning the player, HUD entities, and configuring the level-specific spawners.
• GameActions: Centralizes runtime state transitions such as handling player damage, level completion, and game-over triggers.
• Spawners: Individual classes (EnemySpawner, BossSpawner, AsteroidsSpawner, CoinSpawner) manage the logic and timing of dynamic entity creation.

👾 ECS (The Engine)

• GameEntityFactory: Uses @Spawns annotations to decouple entity creation from game logic. It is the sole provider for all actors, projectiles, and powerups.
• Components: Encapsulate data and specific behavior.
  • Actors: PlayerComponent, GreenDinoComponent, OrangeDinoComponent, AllyComponent.
  • Logic: WeaponHeatComponent (overheating), LifeComponent (health management), ShieldUIComponent (invulnerability).
• Interfaces: Provide domain abstraction (e.g., Player, Dinosaur, Life), allowing components to interact without knowing concrete implementation details.

🛠️ Domain Services & Persistence

• Managers: Global singletons that persist across the entire application lifecycle:
  • LevelManager: Tracks progression and level scaling.
  • AchievementManager: Monitors events to unlock player rewards.
  • AudioManager / LanguageManager: Handle cross-cutting concerns like SFX and internationalization.
• Data & Persistence:
  • HighScore / TotalCoins: Handle reading/writing session data to disk.
  • GameData / Settings: Store volatile runtime configurations and user preferences.
  • CollisionHandler: Encapsulates the domain logic for what happens when specific entity types collide (e.g., damage math or score updates).