# avirar/mod-playerbots architecture

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

- Interactive diagram: https://gitdiagram.com/avirar/mod-playerbots
- Repository: https://github.com/avirar/mod-playerbots

## Overview

##### Project type and purpose
- This is a C++ “module” plugin for the AzerothCore MMORPG server (WorldServer) named **mod-playerbots**.
- Its purpose is to add AI-driven, player-like bots to the game world by hooking into the server’s event loop, chat system, and database layer.

##### High-level architectural components
a. **AzerothCore WorldServer** (host application)
- Loads the module at startup via CMake/C++ plugin mechanism.
- Provides core game loop, networking, scripting engine, and event hooks.
b. **Playerbots Module** (our code under `src/`)
- **Module Loader** (`playerbots_loader.cpp`)
- **Configuration** (`conf/playerbots.conf.dist`)
- **Database schema and migrations** (`data/sql/...`)
- **Core services**:
- AiFactory
- PlayerbotMgr
- PlayerbotAI / PlayerbotAIBase
- PlayerbotDbStore
- CommandServer
- Helpers (ChatHelper, TravelMgr, Security, PerformanceMonitor, etc.)
- **Strategy Engine** (`src/strategy/`):
- *Core engine* (StrategyContext, AiObjectContext, Engine, EventContext)
- *Actions* (one file per action in `actions/`)
- *Triggers* (in `triggers/`)
- *Values* (in `values/`)
- *Class-specific, dungeon, raid, generic sub-folders*
- **Factory subsystem** (`src/factory/`):
- PlayerbotFactory, StatsCollector, StatsWeightCalculator, RandomPlayerbotFactory
c. **MySQL Database**
- Stores persistent bot data, account links, guild tasks, dungeon suggestions, etc.
- Module includes DDL/DML scripts to create and update schemas under `data/sql`.
d. **Clients & External Tools**
- In-game Chat (players send commands to bots via chat)
- Optional UI Add-Ons (Multibot, Unbot) calling ChatCommandServer APIs

##### Relationships and data flow
- On startup, **WorldServer** loads **Module Loader**, reads **Configuration**, applies **SQL migrations** to the **Database**.
- **WorldServer** triggers events (e.g., on player login, on tick, on chat). The module’s **hooks** (ChatFilter, ServerFacade) intercept these.
- **PlayerbotMgr** spawns bot entities; each bot is backed by a **PlayerbotAI** instance.
- **AiFactory** + **Factory subsystem** create and configure bot AIs (class, spec, equipment).
- During each tick:
1. **PlayerbotAI** calls the **Strategy Engine**
2. **Engine** queries **Triggers** (am I low HP?), **Values** (who is nearest?), then picks **Actions** (cast heal, move, loot).
3. **Engine** executes selected Actions via **ServerFacade** (which makes in-game API calls).
- **CommandServer** listens for chat commands (e.g., “!bot follow”) routes them to appropriate in-module handlers.
- **PlayerbotDbStore** reads/writes bot state to the **Database** when persistence is needed.
- **Helpers** like TravelMgr, ChatHelper abstract world-server APIs for reuse.

##### Important architectural patterns and principles
- **Plugin/Module** pattern: decouples bot logic from core server.
- **Factory** pattern: abstracts bot creation and stat weighting.
- **Strategy** pattern: encapsulates per-class, per-scenario behavior (generic, dungeon, raid, class).
- **Separation of concerns**:
- Configuration vs. code vs. data/schema
- Core AI loop vs. class-specific strategies
- Database persistence vs. in-memory logic

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    WorldServer["AzerothCore WorldServer"]:::external
    Clients["Clients & External Tools"]:::external
    Database["MySQL Database"]:::external

    %% Module Container
    subgraph "mod-playerbots Module"
        direction TB

        %% Loader & Config & Data
        Loader["Module Loader"]:::core
        Config["Configuration"]:::config
        Migrations["Database Schema & Migrations"]:::config

        %% Core Services
        subgraph "Core Services"
            direction TB
            PlayerbotMgr["PlayerbotMgr"]:::core
            AiFactory["AiFactory"]:::core
            DbStore["PlayerbotDbStore"]:::core
            CommandServer["CommandServer"]:::core
            ChatFilter["Chat Filter Hook"]:::core
            ServerFacade["Server Facade"]:::core
        end

        %% Helpers
        subgraph "Helpers"
            direction TB
            ChatHelper["ChatHelper"]:::core
            TravelMgr["TravelMgr"]:::core
            Security["PlayerbotSecurity"]:::core
            PerformanceMonitor["PerformanceMonitor"]:::core
            BroadcastHelper["BroadcastHelper"]:::core
        end

        %% Strategy Engine
        subgraph "Strategy Engine" 
            direction TB
            subgraph "Engine Core"
                direction TB
                Engine["Engine"]:::strategy
                StrategyContext["StrategyContext"]:::strategy
                AiObjectContext["AiObjectContext"]:::strategy
                EventContext["EventContext"]:::strategy
            end
            subgraph "Subsystems"
                direction TB
                Actions["Actions"]:::strategy
                Triggers["Triggers"]:::strategy
                Values["Values"]:::strategy
            end
        end

        %% Factory Subsystem
        subgraph "Factory Subsystem"
            direction TB
            PlayerbotFactory["PlayerbotFactory"]:::core
            StatsCollector["StatsCollector"]:::core
            StatsWeightCalculator["StatsWeightCalculator"]:::core
            RandomFactory["RandomPlayerbotFactory"]:::core
        end

        %% Additional Managers
        DungeonSuggestion["DungeonSuggestionMgr"]:::core
        GuildTaskMgr["GuildTaskMgr"]:::core
        RandomItemMgr["RandomItemMgr"]:::core
    end

    %% Relationships
    WorldServer -->|loads| Loader
    Loader --> Config
    Loader --> Migrations
    Loader --> PlayerbotMgr
    PlayerbotMgr --> AiFactory
    AiFactory --> StrategyContext
    StrategyContext --> Engine
    Engine -->|queries| Triggers
    Engine -->|computes| Values
    Engine -->|selects| Actions
    Actions -->|executes via| ServerFacade
    ServerFacade --> WorldServer
    ChatFilter --> CommandServer
    Clients -->|chat commands| ChatFilter
    CommandServer --> PlayerbotMgr
    DbStore --> Database
    Loader --> DbStore
    Configuration -->|bootstrap| Migrations

    %% Click Events
    click Loader "https://github.com/avirar/mod-playerbots/blob/master/src/playerbots_loader.cpp"
    click Config "https://github.com/avirar/mod-playerbots/blob/master/conf/playerbots.conf.dist"
    click Migrations "https://github.com/avirar/mod-playerbots/tree/master/data/sql/playerbots"
    click AiFactory "https://github.com/avirar/mod-playerbots/blob/master/src/AiFactory.cpp"
    click PlayerbotMgr "https://github.com/avirar/mod-playerbots/blob/master/src/PlayerbotMgr.cpp"
    click DbStore "https://github.com/avirar/mod-playerbots/blob/master/src/PlayerbotDbStore.cpp"
    click CommandServer "https://github.com/avirar/mod-playerbots/blob/master/src/PlayerbotCommandServer.cpp"
    click ChatFilter "https://github.com/avirar/mod-playerbots/blob/master/src/ChatFilter.cpp"
    click ServerFacade "https://github.com/avirar/mod-playerbots/blob/master/src/ServerFacade.cpp"
    click ChatHelper "https://github.com/avirar/mod-playerbots/blob/master/src/ChatHelper.cpp"
    click TravelMgr "https://github.com/avirar/mod-playerbots/blob/master/src/TravelMgr.cpp"
    click Security "https://github.com/avirar/mod-playerbots/blob/master/src/PlayerbotSecurity.cpp"
    click PerformanceMonitor "https://github.com/avirar/mod-playerbots/blob/master/src/PerformanceMonitor.cpp"
    click BroadcastHelper "https://github.com/avirar/mod-playerbots/blob/master/src/BroadcastHelper.cpp"
    click Engine "https://github.com/avirar/mod-playerbots/blob/master/src/strategy/Engine.cpp"
    click StrategyContext "https://github.com/avirar/mod-playerbots/blob/master/src/strategy/StrategyContext.h"
    click AiObjectContext "https://github.com/avirar/mod-playerbots/blob/master/src/strategy/AiObjectContext.cpp"
    click EventContext "https://github.com/avirar/mod-playerbots/blob/master/src/strategy/Event.cpp"
    click Actions "https://github.com/avirar/mod-playerbots/tree/master/src/strategy/actions/"
    click Triggers "https://github.com/avirar/mod-playerbots/tree/master/src/strategy/triggers/"
    click Values "https://github.com/avirar/mod-playerbots/tree/master/src/strategy/values/"
    click PlayerbotFactory "https://github.com/avirar/mod-playerbots/blob/master/src/factory/PlayerbotFactory.cpp"
    click StatsCollector "https://github.com/avirar/mod-playerbots/blob/master/src/factory/StatsCollector.cpp"
    click StatsWeightCalculator "https://github.com/avirar/mod-playerbots/blob/master/src/factory/StatsWeightCalculator.cpp"
    click RandomFactory "https://github.com/avirar/mod-playerbots/blob/master/src/RandomPlayerbotFactory.cpp"
    click DungeonSuggestion "https://github.com/avirar/mod-playerbots/blob/master/src/PlayerbotDungeonSuggestionMgr.cpp"
    click GuildTaskMgr "https://github.com/avirar/mod-playerbots/blob/master/src/GuildTaskMgr.cpp"
    click RandomItemMgr "https://github.com/avirar/mod-playerbots/blob/master/src/RandomItemMgr.cpp"

    %% Styles
    classDef external fill:#88c070,stroke:#333,stroke-width:1px
    classDef core fill:#70a0c0,stroke:#333,stroke-width:1px
    classDef strategy fill:#e0d070,stroke:#333,stroke-width:1px
    classDef config fill:#cccccc,stroke:#333,stroke-width:1px
```
