# mehah/otclient architecture

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

- Interactive diagram: https://gitdiagram.com/mehah/otclient
- Repository: https://github.com/mehah/otclient

## Overview

##### Project Type and Purpose
- The project is an alternative Tibia client (used with OTServers) that uses C++20 for the core engine and Lua scripting to implement game functionalities and a highly customizable user interface.
- Its primary goal is to offer a modular framework for game clients by separating core engine components, graphics, networking, and user interface modules, allowing extensive customization via scripts (using a CSS-like syntax for UI design).

##### Analyzing the File Structure
- Directories such as “src” and “src/framework” contain the core C++ implementation, including modules for graphics, input handling, networking, and platform abstraction.
- The “modules” directory has many separated subdirectories (for game actions, UI widgets, battle, containers, etc.) that represent different game functionalities. These illustrate the modular design principle.
- The “mods” directory offers extended functionality and client modifications that can be loaded on top of the core system.
- The “data” directory holds resource files – images, fonts, UI styles, language files, and sound resources – which are separately managed.
- There are platform‐specific folders such as “android” (mobile integration) and “browser” (browser client support), showing that multiple platforms are supported.
- Build files (CMakeLists.txt, Dockerfile, vc17 folder) and configuration files indicate containerized builds and multi-platform compilation.

##### Identifying Main Components and Their Relationships
- Core Engine (C++ Code): Represented by the “src” and “src/framework” directories.
– Input & Event Dispatching: Components for window events, mouse/keyboard handling, asynchronous dispatchers, and multi-threading coordination.
– Networking Module: Found in “src/framework/net” with protocol parsers/senders for handling game communication.
– Resource Management: Handling files, caching, and resource loading from “assets” and “data”.
- Scripting and UI Subsystem:
– Lua Engine & Scripting: Illustrate how game logic, UI widgets, and interface configurations are implemented via Lua (evident in the “mods”, “modules”, and “init.lua”).
– UI & Styling: Show the use of OTML (a CSS-like language) to style the UI, and how data-driven configuration files (in “data/styles” and locally within modules) affect the client’s look.
- Modular Architecture:
– Modules and Addons: Use “modules” and “mods” to emphasize that most functionality (e.g., battle, inventory, creature info, etc.) is encapsulated in individual components.
– Communication between modules is often done via event dispatchers and shared game state.
- Platform-Specific Layers:
– Mobile/Android Layer: Represent the “android” directory as an adapter layer that includes native Android code and Gradle configurations.
– Browser Support: Include a component for the “browser” folder that wraps the client for web environments.
– Build and Deployment Components: Show build scripts (Dockerfile, CMake files, GitHub workflows) as part of the continuous integration and deployment process.
- External Tools and API Integration:
– Tools folder: Represent tools such as language binding generators and other utilities used during development.

##### Architectural Patterns and Design Principles
- Separation of concerns: The clear split between the engine (real-time game update, rendering, network I/O) and scripting/UI (traditionally running in a separate Lua interpreter and plugins).
- Platform abstraction: Indicate that platform-specific implementations (Android, Browser, Windows, Linux) are abstracted from the core engine with adapter layers.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Engine Subgraph
    subgraph "Core Engine"
        CoreEngine["Core Engine (C++ Code)"]:::engine
        GraphicsEngine["Graphics Engine"]:::engine
        InputDispatcher["Input & Event Dispatching"]:::engine
        NetworkingModule["Networking Module"]:::engine
    end

    %% Resource Management Node
    ResourceManagement["Resource Management (Assets)"]:::resource

    %% Scripting and UI Subsystem Subgraph
    subgraph "Scripting and UI Subsystem"
        LuaEngine["Lua Engine & Scripting"]:::scripting
        UIStyling["UI & Styling (OTML)"]:::scripting
    end

    %% Modular Architecture Subgraph
    subgraph "Modular Architecture"
        ModulesAddons["Modules & Addons"]:::module
    end

    %% Platform-Specific Layers Subgraph
    subgraph "Platform-Specific Layers"
        AndroidLayer["Mobile/Android Layer"]:::platform
        BrowserSupport["Browser Support"]:::platform
    end

    %% Build and Deployment Subgraph
    subgraph "Build and Deployment"
        BuildDeployment["Build & Deployment"]:::build
    end

    %% External Tools & API Integration Subgraph
    subgraph "External Tools & API Integration"
        ExternalTools["External Tools"]:::external
    end

    %% INTERNAL CONNECTIONS WITHIN CORE ENGINE
    CoreEngine -->|"handles_graphics"| GraphicsEngine
    CoreEngine -->|"processes_input"| InputDispatcher
    CoreEngine -->|"manages_networking"| NetworkingModule

    %% RESOURCE MANAGEMENT FEEDS BOTH GRAPHICS AND UI
    ResourceManagement -->|"provides_resources"| GraphicsEngine
    ResourceManagement -->|"provides_assets"| UIStyling

    %% CORE ENGINE TRIGGERS SCRIPTING
    CoreEngine -->|"triggers_scripts"| LuaEngine
    LuaEngine -->|"controls_UI"| UIStyling

    %% MODULAR ARCHITECTURE INTEGRATION
    ModulesAddons -->|"integrates_with"| CoreEngine
    ModulesAddons -->|"extends"| LuaEngine

    %% PLATFORM-SPECIFIC ADAPTERS WRAP THE CORE ENGINE
    AndroidLayer -->|"adapts_core"| CoreEngine
    BrowserSupport -->|"wraps_core"| CoreEngine

    %% BUILD & DEPLOYMENT CONNECTS TO CORE SYSTEM
    BuildDeployment -->|"builds"| CoreEngine
    BuildDeployment -->|"packages"| ModulesAddons

    %% EXTERNAL TOOLS ASSIST DEVELOPMENT & DEPLOYMENT
    ExternalTools -->|"supports_development"| CoreEngine
    ExternalTools -->|"assists_build"| BuildDeployment

    %% LEGEND SUBGRAPH
    subgraph "Legend"
        L1["C++ Components"]:::engine
        L2["Lua/Scripting Components"]:::scripting
        L3["Platform-Specific Layers"]:::platform
        L4["Build & Deployment Elements"]:::build
        L5["External Tools"]:::external
        L6["Resource Management"]:::resource
        L7["Modules & Addons"]:::module
    end

    %% CLICK EVENTS
    click CoreEngine "https://github.com/mehah/otclient/tree/main/src"
    click GraphicsEngine "https://github.com/mehah/otclient/tree/main/src/framework/graphics"
    click InputDispatcher "https://github.com/mehah/otclient/tree/main/src/framework/input"
    click NetworkingModule "https://github.com/mehah/otclient/tree/main/src/framework/net"
    click ResourceManagement "https://github.com/mehah/otclient/tree/main/data"
    click LuaEngine "https://github.com/mehah/otclient/tree/main/src/framework/luaengine"
    click LuaEngine "https://github.com/mehah/otclient/blob/main/init.lua"
    click UIStyling "https://github.com/mehah/otclient/tree/main/data/styles"
    click ModulesAddons "https://github.com/mehah/otclient/tree/main/modules"
    click ModulesAddons "https://github.com/mehah/otclient/tree/main/mods"
    click AndroidLayer "https://github.com/mehah/otclient/tree/main/android"
    click BrowserSupport "https://github.com/mehah/otclient/tree/main/browser"
    click BuildDeployment "https://github.com/mehah/otclient/blob/main/CMakeLists.txt"
    click BuildDeployment "https://github.com/mehah/otclient/tree/main/Dockerfile"
    click BuildDeployment "https://github.com/mehah/otclient/tree/main/.github/workflows"
    click BuildDeployment "https://github.com/mehah/otclient/tree/main/vc17"
    click BuildDeployment "https://github.com/mehah/otclient/blob/main/vcpkg.json"
    click ExternalTools "https://github.com/mehah/otclient/tree/main/tools"

    %% STYLE DEFINITIONS
    classDef engine fill:#ffcccc,stroke:#660000,stroke-width:2px;
    classDef scripting fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef platform fill:#ccccff,stroke:#000066,stroke-width:2px,stroke-dasharray: 5, 5;
    classDef build fill:#ffffcc,stroke:#666600,stroke-width:2px;
    classDef external fill:#ffccff,stroke:#660066,stroke-width:2px;
    classDef resource fill:#e6e6fa,stroke:#4b0082,stroke-width:2px;
    classDef module fill:#d1ffd1,stroke:#008000,stroke-width:2px;
```
