# vcmi/vcmi architecture

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

- Interactive diagram: https://gitdiagram.com/vcmi/vcmi
- Repository: https://github.com/vcmi/vcmi

## Overview

- Engine Core / Library: This central “lib” directory and its submodules contain core game logic, domain models (game state, battle mechanics, map management), file/resource handling, and support for modding and scripting. Also note the “vcmi” include files.
- Client Components: All directories under “client” (plus “clientapp” and “vcmiqt”) comprise the graphical user interface, rendering (SDL-based rendering and other GUI modules), input handling, and audio/video media. Modules under “client/battle”, “client/mapView” and “client/gui” show that the client is split into various subdomains (battle, adventure map, lobby, etc.).
- Server Components: Directories like “server”, “serverapp” and “lobby” contain logic for turn-based processing, networking (queries, NetPacks, processors), and multiplayer state management.
- AI Modules: There are several AI directories (e.g. AI/BattleAI, AI/Nullkiller, AI/StupidAI, AI/VCAI) that encapsulate different strategies and evaluation algorithms. They interact with the engine core to compute game decisions.
- Scripting/Modding and Tools: The “scripting” folders (both for ERM and Lua) provide extensibility points so that behaviors can be injected or modified dynamically. The “mapeditor” and “launcher” directories are separate tools that leverage the engine libraries and graphical interface components.
- Build and Infrastructure: The project is built using CMake scripts, with additional support from Conan, CI/CD configurations, and platform-specific directories (android, ios, osx, win, xcode). Although these are mostly for infrastructure, they are important for showing how the components are built and deployed.

##### Relationships and Interactions Between Components
- The Engine Core acts as a shared library that both Client and Server depend on. This core contains game state management (battle, map, campaign), resource management, file I/O, and core game rules.
- The AI modules integrate with the Engine Core by reading game state and proposing moves/decisions. They form a plug‐in layer where multiple AI strategies can be swapped in.
- Scripting/Modding modules (Lua and ERM) extend the Engine Core, exposing APIs for game objects, events, and spells. These components allow modders to add new functionality without changing the core C++ code.
- Tools like the Launcher and Map Editor depend upon Engine and UI libraries, serving as separate applications that still leverage the same codebase.
- The build system (CMake, Conan, etc.) supports cross-platform compilation and module integration; for documentation, you may show these as auxiliary support systems.

##### Architectural Patterns and Design Principles
- Modularization and Separation of Concerns: The project clearly separates game logic (engine), presentation (client UI), networking (server and lobby), and supplementary services (AI, scripting). Each major folder namespace is dedicated to a specific layer.
- Client-Server Architecture: The multiplayer capabilities are segregated with clear client-side and server-side implementations that communicate via network protocols and “NetPack” messages.
- Plugin/Extension Patterns: The scripting system and modding framework are designed to expose interfaces (via Lua, ERM) that hook into the engine’s functionalities.
- Cross-platform Build Infrastructure: Emphasis on using CMake and various platform-specific folders under android, ios, osx, etc., highlight a design that isolates platform dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Engine Core Cluster
    subgraph "Engine Core"
        ECL["Engine Core (lib)"]:::core
        ECI["VCMI Includes"]:::core
    end

    %% Client Components Cluster
    subgraph "Client Components"
        CC["VCMI Client (GUI, Rendering, Input)"]:::client
    end

    %% Server Components Cluster
    subgraph "Server Components"
        SC["VCMI Server (Turn Processing, Network)"]:::server
    end

    %% AI Modules Cluster
    subgraph "AI Modules"
        AIM["AI Modules"]:::ai
    end

    %% Scripting/Modding Subsystem Cluster
    subgraph "Scripting/Modding Subsystem"
        SM["Scripting/Modding Subsystem"]:::script
    end

    %% Tools Cluster
    subgraph "Tools"
        TL["Tools (Launcher, Map Editor)"]:::tools
    end

    %% Build and Infrastructure Cluster
    subgraph "Build & Infrastructure"
        BI["Build & Infrastructure"]:::build
    end

    %% Relationships between clusters
    CC -->|"dependsOn"| ECL
    CC -->|"dependsOn"| ECI

    SC -->|"dependsOn"| ECL
    SC -->|"dependsOn"| ECI

    AIM -->|"integratesWith"| ECL
    AIM -->|"integratesWith"| ECI

    SM -->|"extends"| ECL
    SM -->|"extends"| ECI

    TL -->|"leverages"| ECL
    TL -->|"usesUI"| CC

    CC <-->|"networkComm"| SC

    %% Click Events for Engine Core / Library
    click ECL "https://github.com/vcmi/vcmi/tree/develop/lib"
    click ECI "https://github.com/vcmi/vcmi/tree/develop/include/vcmi"

    %% Click Events for Client Components
    click CC "https://github.com/vcmi/vcmi/tree/develop/client"
    click CC "https://github.com/vcmi/vcmi/tree/develop/clientapp"
    click CC "https://github.com/vcmi/vcmi/tree/develop/vcmiqt"

    %% Click Events for Server Components
    click SC "https://github.com/vcmi/vcmi/tree/develop/server"
    click SC "https://github.com/vcmi/vcmi/tree/develop/serverapp"
    click SC "https://github.com/vcmi/vcmi/tree/develop/lobby"

    %% Click Events for AI Modules
    click AIM "https://github.com/vcmi/vcmi/tree/develop/AI"

    %% Click Events for Scripting/Modding Subsystem
    click SM "https://github.com/vcmi/vcmi/tree/develop/scripting"
    click SM "https://github.com/vcmi/vcmi/tree/develop/lib/modding"
    click SM "https://github.com/vcmi/vcmi/tree/develop/Mods/vcmi"

    %% Click Events for Tools
    click TL "https://github.com/vcmi/vcmi/tree/develop/mapeditor"
    click TL "https://github.com/vcmi/vcmi/tree/develop/launcher"

    %% Click Events for Build and Infrastructure
    click BI "https://github.com/vcmi/vcmi/blob/develop/CMakeLists.txt"
    click BI "https://github.com/vcmi/vcmi/tree/develop/CI"
    click BI "https://github.com/vcmi/vcmi/tree/develop/android"
    click BI "https://github.com/vcmi/vcmi/tree/develop/ios"
    click BI "https://github.com/vcmi/vcmi/tree/develop/osx"
    click BI "https://github.com/vcmi/vcmi/tree/develop/win"
    click BI "https://github.com/vcmi/vcmi/tree/develop/xcode"
    click BI "https://github.com/vcmi/vcmi/blob/develop/.github"

    %% Style definitions
    classDef core fill:#f9c,stroke:#333,stroke-width:2px;
    classDef client fill:#cff,stroke:#333,stroke-width:2px;
    classDef server fill:#fcf,stroke:#333,stroke-width:2px;
    classDef ai fill:#cfc,stroke:#333,stroke-width:2px;
    classDef script fill:#ccf,stroke:#333,stroke-width:2px;
    classDef tools fill:#ffc,stroke:#333,stroke-width:2px;
    classDef build fill:#efe,stroke:#333,stroke-width:2px;
```
