# zunohoang/j2d-engine architecture

> Architecture diagram of the GitHub repository zunohoang/j2d-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zunohoang/j2d-engine
- Repository: https://github.com/zunohoang/j2d-engine

## Overview

##### Main Components
a. Main Entry Point:
- Main.java in the src directory is the launcher that likely initializes the engine.
b. Core Engine (src/engine/core):
- Engine.java, GameLoop.java, GameThread.java – Responsible for orchestrating the game loop, threading, and high-level engine execution.
c. Input Handling:
- Classes such as KeyInput.java and MouseInput.java that capture user interactions.
d. Rendering & Graphics:
- Renderer.java and UILayoutParser.java in the graphics package along with classes in src/engine/components (e.g., SpriteRenderer.java, ColorRenderer.java) handling drawing and image layout.
e. Components & Game Objects:
- A rich set of components (Transform, Rigidbody, Collider classes, UI elements, etc.) under src/engine/components; these illustrate a component-based architecture.
- GameObject.java which is a base for in-game objects.
f. Physics & Collision:
- Physics, CollisionManager, PhysicsSystem in src/engine/physics, showing collision detection and physics simulation.
g. Scenes & Scene Management:
- Scene.java and SceneManager.java under src/engine/scenes, and the concrete scenes (GameScene, MenuScene, OfflineScene) under src/game/scenes.
h. Asset & Local Data Handling:
- Assets are stored in the assets directory (images, layouts, and repositories of JSON config data).
- RepositoryService and related classes for loading games’ settings, characters, and game-specific data.
i. Game-specific Logic:
- Under src/game, there are configurations and scripts that define game behavior like NormalAttack.java and PlayerController.java.

##### Relationships & Interactions
- The Main entry point initializes the Core Engine. The Engine instantiates the Game Loop, which continuously updates and renders the current Scene.
- Input systems (KeyInput/MouseInput) feed events into the Game Loop which interact with the GameObjects via their components.
- Assets (images, layouts) and Repository files (JSON configuration files) are loaded into memory through components in the engine (such as JsonManager and RepositoryService) to provide configuration data to scenes and objects.
- The Renderer interacts with various component renderers (e.g., SpriteRenderer, UI renderers) to organize how objects appear.
- The Physics system is hooked into the update loop, managing collisions (via CollisionManager) and responses (using components like Rigidbody, BoxCollider, and CircleCollider).
- The Scene Manager is responsible for switching between game states (like GameScene, MenuScene, OfflineScene), managing the lifecycle of scenes.
- Game-specific scripts in src/game/scripts are likely attached to game objects within the scenes to define behaviors like normal attacks or player control.

##### Architectural Patterns & Design Principles
- Component-based architecture: Notice how multiple component classes exist (Transform, SpriteRenderer, Collider types, etc.) to be attached to game objects to define behavior modularly.
- Separation of concerns: Distinct separation between the core engine, rendering subsystem, physics engine, and game-specific logic.
- Use of a game loop and scene management: Centralized update and render cycle that drives the game state.
- Event-driven interactions: Input handling (keyboard/mouse) feeding directly into state changes.
- Data-driven design: The use of JSON repository files and layouts (menu.xml) suggests a degree of dynamic configuration.

a. Main Entry (Main.java) at the top.
b. Layer the Core Engine components just below, showing the flow to and from the Game Loop and Game Thread.
c. Branch out the Engine’s sub-systems:
– Left branch: Rendering & Graphics System, linking to various Renderer and UI components.
– Right branch: Physics & Collision subsystem, depicting Physics, CollisionManager, and associated components.
– Lower branch: Input Handling feeding into both systems.
– Game Scenes (GameScene, MenuScene, OfflineScene)
– Although the engine handles core functions, game-specific behaviors are implemented through scripts and configurations.
e. Off to the side or at the base, show the Asset Management module connecting to the repository JSON files, layout XML file, and assets (images).
f. Finally, include overarching external interactions (if any, such as developer tools, logging via Logger) which feed back into the engine’s monitoring and debugging processes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Layer
    subgraph "Main Layer"
        A1["Main Entry (Main.java)"]:::main
    end

    %% Core Engine
    subgraph "Core Engine"
        B1["Engine (Engine.java)"]:::engine
        B2["GameLoop (GameLoop.java)"]:::engine
        B3["GameThread (GameThread.java)"]:::engine
    end

    %% Input Handling
    subgraph "Input Handling"
        C1["KeyInput (KeyInput.java)"]:::input
        C2["MouseInput (MouseInput.java)"]:::input
    end

    %% Rendering & Graphics
    subgraph "Rendering & Graphics"
        D1["Renderer (Renderer.java)"]:::rendering
        D2["UILayoutParser (UILayoutParser.java)"]:::rendering
        D3["BoxRenderer (BoxRenderer.java)"]:::rendering
        D4["Button (Button.java)"]:::rendering
        D5["ColorRenderer (ColorRenderer.java)"]:::rendering
        D6["ImageRenderer (ImageRenderer.java)"]:::rendering
        D7["RectTransform (RectTransform.java)"]:::rendering
        D8["TextRenderer (TextRenderer.java)"]:::rendering
    end

    %% Components & Game Objects
    subgraph "Components & Game Objects"
        E1["Animation (Animation.java)"]:::components
        E2["Animations (Animations.java)"]:::components
        E3["BoxCollider (BoxCollider.java)"]:::components
        E4["CircleCollider (CircleCollider.java)"]:::components
        E5["Component (Component.java)"]:::components
        E6["CoordinateXY (CoordinateXY.java)"]:::components
        E7["Rigidbody (Rigidbody.java)"]:::components
        E8["SpriteRenderer (SpriteRenderer.java)"]:::components
        E9["TopDownRigidbody (TopDownRigidbody.java)"]:::components
        E10["Transform (Transform.java)"]:::components
        E11["GameObject (GameObject.java)"]:::components
    end

    %% Physics & Collision
    subgraph "Physics & Collision"
        F1["CollisionManager (CollisionManager.java)"]:::physics
        F2["Physics (Physics.java)"]:::physics
        F3["PhysicsSystem (PhysicsSystem.java)"]:::physics
    end

    %% Scene Management
    subgraph "Scene Management"
        G1["Scene (Scene.java)"]:::scenes
        G2["SceneManager (SceneManager.java)"]:::scenes
        G3["GameScene (GameScene.java)"]:::scenes
        G4["MenuScene (MenuScene.java)"]:::scenes
        G5["OfflineScene (OfflineScene.java)"]:::scenes
    end

    %% Asset & Local Data Handling
    subgraph "Asset & Local Data"
        H1["Assets"]:::asset
        H2["RepositoryModel (RepositoryModel.java)"]:::asset
        H3["RepositoryService (RepositoryService.java)"]:::asset
        H4["JsonManager (JsonManager.java)"]:::asset
    end

    %% Game-specific Logic
    subgraph "Game-specific Logic"
        I1["GameConfig (GameConfig.java)"]:::gameLogic
        I2["NormalAttack (NormalAttack.java)"]:::gameLogic
        I3["PlayerController (PlayerController.java)"]:::gameLogic
    end

    %% Connections
    A1 -->|"initializes"| B1
    B1 -->|"orchestrates"| B2
    B1 -->|"spawns"| B3
    B1 -->|"handles input"| C1
    B1 -->|"handles input"| C2
    B2 -->|"updates scene"| G2
    G2 -->|"manages"| G3
    G2 -->|"manages"| G4
    G2 -->|"manages"| G5
    
    D1 -->|"renders"| E8
    D1 -->|"renders"| D5
    D1 -->|"renders"| D8
    D2 -->|"parses layout for"| D4
    D2 -->|"parses layout for"| D7
    E11 -->|"aggregates"| E5

    F1 -->|"detects collision"| F2
    F1 -->|"drives physics"| F3
    E3 -->|"triggers collision"| F1
    E4 -->|"triggers collision"| F1

    H3 -->|"loads config"| H4
    H4 -->|"supplies data to"| G2
    H2 -->|"models data for"| H3

    I1 -->|"configures"| G2
    I2 -->|"defines behavior"| G3
    I3 -->|"defines behavior"| G3

    %% Cross Layer Interactions
    C1 -->|"sends input"| B2
    C2 -->|"sends input"| B2
    D1 ---|"interacts with"| E11
    F2 ---|"affects"| E11
    H1 ---|"provides assets to"| D2

    %% Styling
    classDef main fill:#ffdddd,stroke:#cc0000,stroke-width:2px;
    classDef engine fill:#ddffdd,stroke:#009900,stroke-width:2px;
    classDef input fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef rendering fill:#cce5ff,stroke:#0066cc,stroke-width:2px;
    classDef components fill:#e6ccff,stroke:#6600cc,stroke-width:2px;
    classDef physics fill:#ffedcc,stroke:#cc6600,stroke-width:2px;
    classDef scenes fill:#d9f2e6,stroke:#33cc66,stroke-width:2px;
    classDef asset fill:#f2e6d9,stroke:#cc9966,stroke-width:2px;
    classDef gameLogic fill:#f9e6ff,stroke:#cc66cc,stroke-width:2px;

    %% Click Events
    click A1 "https://github.com/zunohoang/j2d-engine/blob/main/src/Main.java"
    click B1 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/core/Engine.java"
    click B2 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/core/GameLoop.java"
    click B3 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/core/GameThread.java"
    click C1 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/core/KeyInput.java"
    click C2 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/core/MouseInput.java"
    click D1 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/graphics/Renderer.java"
    click D2 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/graphics/UILayoutParser.java"
    click D3 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/ui/BoxRenderer.java"
    click D4 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/ui/Button.java"
    click D5 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/ui/ColorRenderer.java"
    click D6 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/ui/ImageRenderer.java"
    click D7 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/ui/RectTransform.java"
    click D8 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/ui/TextRenderer.java"
    click E1 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/Animation.java"
    click E2 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/Animations.java"
    click E3 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/BoxCollider.java"
    click E4 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/CircleCollider.java"
    click E5 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/Component.java"
    click E6 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/CoordinateXY.java"
    click E7 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/Rigidbody.java"
    click E8 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/SpriteRenderer.java"
    click E9 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/TopDownRigidbody.java"
    click E10 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/components/Transform.java"
    click E11 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/objects/GameObject.java"
    click F1 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/physics/CollisionManager.java"
    click F2 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/physics/Physics.java"
    click F3 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/physics/PhysicsSystem.java"
    click G1 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/scenes/Scene.java"
    click G2 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/scenes/SceneManager.java"
    click G3 "https://github.com/zunohoang/j2d-engine/blob/main/src/game/scenes/GameScene.java"
    click G4 "https://github.com/zunohoang/j2d-engine/blob/main/src/game/scenes/MenuScene.java"
    click G5 "https://github.com/zunohoang/j2d-engine/blob/main/src/game/scenes/OfflineScene.java"
    click H1 "https://github.com/zunohoang/j2d-engine/tree/main/assets"
    click H2 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/localdata/RepositoryModel.java"
    click H3 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/localdata/RepositoryService.java"
    click H4 "https://github.com/zunohoang/j2d-engine/blob/main/src/engine/utils/JsonManager.java"
    click I1 "https://github.com/zunohoang/j2d-engine/blob/main/src/game/configs/GameConfig.java"
    click I2 "https://github.com/zunohoang/j2d-engine/blob/main/src/game/scripts/NormalAttack.java"
    click I3 "https://github.com/zunohoang/j2d-engine/blob/main/src/game/scripts/PlayerController.java"
```
