josh/ThordekkCore
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a23ab5203a1261f32f746ef5ea444200893a877c
ThordekkCore/PLAYERBOT_GAME_SYSTEMS_ARCHITECTURE.md
T
luis 5e6911ccb4 Init source part 1
2026-01-20 21:33:16 -03:00

44 KiB
Raw Blame History

PlayerBot Game System Integration Architecture

Version 1.0 - Enterprise-Grade Design for 5000+ Concurrent Bots

Table of Contents

  1. Executive Summary
  2. System Architecture Overview
  3. Module Structure Design
  4. Class Architecture
  5. Bot Lifecycle Integration
  6. Update Loop Integration
  7. Configuration System
  8. Performance Optimization Strategy
  9. Error Handling Strategy
  10. Thread Safety Architecture
  11. Implementation Roadmap

Executive Summary

This architecture document defines the complete integration strategy for Quest, Inventory, Trade, and Auction systems within the PlayerBot module, targeting 5000+ concurrent bots with <10% total CPU impact.

Key Design Principles

  • Zero Core Modifications: All implementations within src/modules/Playerbot/
  • Performance First: Every system designed for minimal CPU/memory footprint
  • Scalability: Linear performance scaling to 5000+ bots
  • Maintainability: Clear separation of concerns with modular design
  • Thread Safety: All operations thread-safe through Player object synchronization

System Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     BotAI Core System                        │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Update Loop Coordinator                 │   │
│  │  Priority Queue | Throttling | CPU Budget Manager   │   │
│  └────────────────────────┬────────────────────────────┘   │
│                           │                                  │
│  ┌────────────┬──────────┼──────────┬──────────────┐      │
│  ▼            ▼          ▼          ▼              ▼      │
│┌──────┐ ┌──────────┐ ┌──────┐ ┌─────────┐ ┌──────────┐   │
││Quest │ │Inventory │ │Trade │ │ Auction │ │  Combat  │   │
││ Mgr  │ │ Manager  │ │ Mgr  │ │ Manager │ │  System  │   │
│└──────┘ └──────────┘ └──────┘ └─────────┘ └──────────┘   │
│   │          │          │          │            │          │
│   └──────────┴──────────┴──────────┴────────────┘          │
│                           │                                  │
│                    ┌──────▼──────┐                          │
│                    │ Player API  │                          │
│                    │(Thread-Safe)│                          │
│                    └──────────────┘                          │
└─────────────────────────────────────────────────────────────┘

Module Structure Design

Directory Structure

src/modules/Playerbot/
├── Game/                           # Core game system integration
│   ├── Quest/
│   │   ├── QuestManager.h          # Main quest management
│   │   ├── QuestManager.cpp
│   │   ├── QuestStrategy.h         # Quest selection AI
│   │   ├── QuestStrategy.cpp
│   │   ├── QuestCache.h           # Performance optimization
│   │   ├── QuestCache.cpp
│   │   ├── QuestActions.h         # Quest-related actions
│   │   └── QuestActions.cpp
│   │
│   ├── Inventory/
│   │   ├── InventoryManager.h     # Item and bag management
│   │   ├── InventoryManager.cpp
│   │   ├── LootManager.h          # Loot distribution logic
│   │   ├── LootManager.cpp
│   │   ├── EquipmentOptimizer.h   # Gear optimization AI
│   │   ├── EquipmentOptimizer.cpp
│   │   ├── ItemCache.h            # Performance cache
│   │   └── ItemCache.cpp
│   │
│   └── SystemCoordinator.h        # Cross-system coordination
│       └── SystemCoordinator.cpp
│
├── Social/                         # Social interaction systems
│   ├── Trade/
│   │   ├── TradeManager.h         # Trade system integration
│   │   ├── TradeManager.cpp
│   │   ├── TradePolicy.h          # Trade rules and security
│   │   ├── TradePolicy.cpp
│   │   ├── TradeActions.h         # Trade-specific actions
│   │   └── TradeActions.cpp
│   │
│   └── SocialCoordinator.h        # Social system coordination
│       └── SocialCoordinator.cpp
│
├── Economy/                        # Economic systems
│   ├── Auction/
│   │   ├── AuctionManager.h       # Auction house integration
│   │   ├── AuctionManager.cpp
│   │   ├── AuctionStrategy.h      # Market analysis AI
│   │   ├── AuctionStrategy.cpp
│   │   ├── PriceAnalyzer.h        # Price trend analysis
│   │   ├── PriceAnalyzer.cpp
│   │   ├── AuctionCache.h         # Cached auction data
│   │   └── AuctionCache.cpp
│   │
│   ├── EconomyCoordinator.h       # Economic system coordination
│   └── EconomyCoordinator.cpp
│
└── Performance/                    # Performance monitoring
    ├── SystemMetrics.h             # Performance tracking
    ├── SystemMetrics.cpp
    ├── UpdateScheduler.h           # Update scheduling
    └── UpdateScheduler.cpp

Class Architecture

Base System Manager

namespace Playerbot {

// Base class for all game system managers
class SystemManager {
public:
    explicit SystemManager(Player* bot, BotAI* ai);
    virtual ~SystemManager() = default;

    // Core interface
    virtual void Initialize() = 0;
    virtual void Update(uint32 diff) = 0;
    virtual void Reset() = 0;
    virtual void Shutdown() = 0;

    // Performance monitoring
    virtual float GetCPUUsage() const = 0;
    virtual size_t GetMemoryUsage() const = 0;
    virtual uint32 GetUpdatePriority() const = 0;

    // State management
    virtual bool IsEnabled() const = 0;
    virtual void SetEnabled(bool enabled) = 0;

protected:
    Player* m_bot;
    BotAI* m_ai;
    bool m_enabled;

    // Performance tracking
    std::chrono::microseconds m_lastUpdateTime;
    std::chrono::microseconds m_totalUpdateTime;
    uint32 m_updateCount;

    // Throttling
    uint32 m_updateInterval;
    uint32 m_timeSinceLastUpdate;
};

}

Quest Manager Architecture

namespace Playerbot {

class QuestManager : public SystemManager {
public:
    explicit QuestManager(Player* bot, BotAI* ai);
    ~QuestManager() override;

    // SystemManager interface
    void Initialize() override;
    void Update(uint32 diff) override;
    void Reset() override;
    void Shutdown() override;

    // Quest-specific interface
    bool CanAcceptQuest(uint32 questId) const;
    bool AcceptQuest(uint32 questId);
    bool CompleteQuest(uint32 questId);
    bool TurnInQuest(uint32 questId);

    // Quest selection AI
    uint32 SelectBestQuest(std::vector<uint32> const& availableQuests);
    float CalculateQuestPriority(Quest const* quest) const;

    // Quest tracking
    std::vector<uint32> GetActiveQuests() const;
    std::vector<uint32> GetCompletableQuests() const;
    QuestStatus GetQuestStatus(uint32 questId) const;

    // Performance optimizations
    void UpdateQuestCache();
    void InvalidateCache();

private:
    // Internal state
    enum class QuestPhase {
        SCANNING,       // Looking for quests
        ACCEPTING,      // Accepting new quests
        PROGRESSING,    // Working on quests
        COMPLETING,     // Turning in quests
        IDLE           // No quest activity
    };

    QuestPhase m_currentPhase;
    uint32 m_phaseTimer;

    // Quest cache for performance
    struct QuestCache {
        std::unordered_map<uint32, QuestStatus> statusCache;
        std::vector<uint32> activeQuests;
        std::vector<uint32> completableQuests;
        uint32 lastUpdateTime;
        bool isDirty;
    } m_cache;

    // Quest selection strategy
    std::unique_ptr<QuestStrategy> m_strategy;

    // Performance metrics
    struct Metrics {
        uint32 questsAccepted;
        uint32 questsCompleted;
        uint32 questsFailed;
        float avgTimePerQuest;
    } m_metrics;

    // Internal methods
    void UpdateQuestPhase(uint32 diff);
    void ProcessScanningPhase();
    void ProcessAcceptingPhase();
    void ProcessProgressingPhase();
    void ProcessCompletingPhase();

    // Helper methods
    bool IsQuestGiverNearby() const;
    Creature* FindNearestQuestGiver() const;
    bool MoveToQuestGiver(Creature* questGiver);
};

}

Inventory Manager Architecture

namespace Playerbot {

class InventoryManager : public SystemManager {
public:
    explicit InventoryManager(Player* bot, BotAI* ai);
    ~InventoryManager() override;

    // SystemManager interface
    void Initialize() override;
    void Update(uint32 diff) override;
    void Reset() override;
    void Shutdown() override;

    // Inventory management
    bool HasSpace(uint32 itemCount = 1) const;
    uint32 GetFreeSlots() const;
    bool SortInventory();
    bool OptimizeBags();

    // Item management
    bool EquipItem(Item* item);
    bool UnequipItem(uint8 slot);
    bool UseItem(Item* item);
    bool DestroyItem(Item* item);
    bool SellItem(Item* item);

    // Loot management
    void HandleLoot(Loot* loot);
    bool CanLootItem(LootItem const& item) const;
    float CalculateItemValue(ItemTemplate const* proto) const;

    // Equipment optimization
    bool OptimizeEquipment();
    float CalculateGearScore() const;
    bool IsUpgrade(Item* item) const;

    // Food/Water management
    bool NeedsFood() const;
    bool NeedsWater() const;
    Item* GetBestFood() const;
    Item* GetBestWater() const;
    bool UseConsumable(Item* item);

private:
    // Internal state
    enum class InventoryTask {
        NONE,
        SORTING,
        EQUIPPING,
        SELLING,
        DESTROYING,
        BANKING
    };

    InventoryTask m_currentTask;
    uint32 m_taskTimer;

    // Item cache
    struct ItemCache {
        std::unordered_map<uint32, Item*> items;
        std::vector<Item*> equipmentUpgrades;
        std::vector<Item*> consumables;
        std::vector<Item*> tradeGoods;
        uint32 totalValue;
        uint32 lastUpdateTime;
        bool isDirty;
    } m_cache;

    // Loot distribution
    std::unique_ptr<LootManager> m_lootManager;

    // Equipment optimizer
    std::unique_ptr<EquipmentOptimizer> m_equipmentOptimizer;

    // Performance metrics
    struct Metrics {
        uint32 itemsLooted;
        uint32 itemsEquipped;
        uint32 itemsSold;
        uint32 itemsDestroyed;
        uint32 bagsOptimized;
    } m_metrics;

    // Internal methods
    void UpdateInventoryTask(uint32 diff);
    void ProcessSortingTask();
    void ProcessEquippingTask();
    void ProcessSellingTask();
    void ProcessDestroyingTask();

    // Cache management
    void UpdateItemCache();
    void InvalidateCache();

    // Helper methods
    bool IsVendorNearby() const;
    Creature* FindNearestVendor() const;
    bool MoveToVendor(Creature* vendor);
};

}

Trade Manager Architecture

namespace Playerbot {

class TradeManager : public SystemManager {
public:
    explicit TradeManager(Player* bot, BotAI* ai);
    ~TradeManager() override;

    // SystemManager interface
    void Initialize() override;
    void Update(uint32 diff) override;
    void Reset() override;
    void Shutdown() override;

    // Trade initiation
    bool InitiateTrade(Player* target);
    bool AcceptTradeRequest(Player* from);
    bool DeclineTradeRequest(Player* from);

    // Trade operations
    bool AddItemToTrade(Item* item, uint8 slot);
    bool RemoveItemFromTrade(uint8 slot);
    bool SetTradeGold(uint32 gold);
    bool AcceptTrade();
    bool CancelTrade();

    // Trade policy
    bool CanTradeWith(Player* player) const;
    bool IsItemTradeable(Item* item) const;
    bool IsFairTrade() const;
    float CalculateTradeValue() const;

    // Group trading
    void DistributeLoot(std::vector<Item*> const& items);
    void ShareQuestItems();
    void ShareConsumables();

private:
    // Trade state
    enum class TradeState {
        IDLE,
        REQUESTING,
        NEGOTIATING,
        CONFIRMING,
        COMPLETED,
        CANCELLED
    };

    TradeState m_currentState;
    Player* m_tradePartner;
    uint32 m_stateTimer;

    // Trade policy
    std::unique_ptr<TradePolicy> m_policy;

    // Trade data
    struct TradeData {
        std::array<Item*, TRADE_SLOT_COUNT> myItems;
        std::array<Item*, TRADE_SLOT_COUNT> theirItems;
        uint32 myGold;
        uint32 theirGold;
        bool accepted;
        bool theirAccepted;
    } m_tradeData;

    // Trade history
    struct TradeHistory {
        struct Entry {
            ObjectGuid partner;
            uint32 timestamp;
            float value;
            bool successful;
        };
        std::deque<Entry> entries;
        uint32 totalTrades;
        uint32 successfulTrades;
    } m_history;

    // Performance metrics
    struct Metrics {
        uint32 tradesInitiated;
        uint32 tradesCompleted;
        uint32 tradesCancelled;
        float avgTradeTime;
        uint32 totalValue;
    } m_metrics;

    // Internal methods
    void UpdateTradeState(uint32 diff);
    void ProcessRequestingState();
    void ProcessNegotiatingState();
    void ProcessConfirmingState();

    // Trade validation
    bool ValidateTrade() const;
    bool CheckTradeDistance() const;
    bool CheckTradeSecurity() const;

    // Helper methods
    void RecordTrade(bool successful);
    void ClearTradeData();
};

}

Auction Manager Architecture

namespace Playerbot {

class AuctionManager : public SystemManager {
public:
    explicit AuctionManager(Player* bot, BotAI* ai);
    ~AuctionManager() override;

    // SystemManager interface
    void Initialize() override;
    void Update(uint32 diff) override;
    void Reset() override;
    void Shutdown() override;

    // Auction operations
    bool CreateAuction(Item* item, uint32 bid, uint32 buyout, uint32 duration);
    bool BidOnAuction(uint32 auctionId, uint32 bidAmount);
    bool BuyoutAuction(uint32 auctionId);
    bool CancelAuction(uint32 auctionId);

    // Auction search
    std::vector<AuctionEntry*> SearchAuctions(ItemTemplate const* proto);
    std::vector<AuctionEntry*> GetMyAuctions() const;
    std::vector<AuctionEntry*> GetMyBids() const;

    // Market analysis
    uint32 CalculateMarketPrice(uint32 itemId) const;
    float CalculatePriceTrend(uint32 itemId) const;
    bool IsProfitableItem(uint32 itemId) const;

    // Auction strategy
    uint32 CalculateBidPrice(AuctionEntry* auction) const;
    uint32 CalculateSellPrice(Item* item) const;
    bool ShouldBuyItem(AuctionEntry* auction) const;
    bool ShouldSellItem(Item* item) const;

private:
    // Auction state
    enum class AuctionPhase {
        IDLE,
        SCANNING,      // Scanning for deals
        BUYING,        // Purchasing items
        SELLING,       // Creating auctions
        COLLECTING,    // Collecting mail
        ANALYZING      // Market analysis
    };

    AuctionPhase m_currentPhase;
    uint32 m_phaseTimer;
    uint32 m_nextScanTime;

    // Market analysis
    std::unique_ptr<AuctionStrategy> m_strategy;
    std::unique_ptr<PriceAnalyzer> m_priceAnalyzer;

    // Auction cache
    struct AuctionCache {
        std::unordered_map<uint32, std::vector<AuctionEntry*>> itemAuctions;
        std::unordered_map<uint32, uint32> marketPrices;
        std::unordered_map<uint32, float> priceTrends;
        std::vector<uint32> profitableItems;
        uint32 lastUpdateTime;
        bool isDirty;
    } m_cache;

    // Active auctions tracking
    struct ActiveAuctions {
        std::vector<uint32> myAuctions;
        std::vector<uint32> myBids;
        uint32 totalInvested;
        uint32 potentialProfit;
    } m_activeAuctions;

    // Performance metrics
    struct Metrics {
        uint32 auctionsCreated;
        uint32 auctionsWon;
        uint32 auctionsCancelled;
        uint32 totalProfit;
        uint32 totalLoss;
        float avgROI;
    } m_metrics;

    // Internal methods
    void UpdateAuctionPhase(uint32 diff);
    void ProcessScanningPhase();
    void ProcessBuyingPhase();
    void ProcessSellingPhase();
    void ProcessCollectingPhase();
    void ProcessAnalyzingPhase();

    // Market analysis
    void UpdateMarketData();
    void AnalyzePriceTrends();
    void IdentifyProfitableItems();

    // Helper methods
    bool IsAuctionHouseNearby() const;
    Creature* FindNearestAuctioneer() const;
    bool MoveToAuctioneer(Creature* auctioneer);
    void UpdateAuctionCache();
};

}

Bot Lifecycle Integration

Integration Points in BotAI

// Modified BotAI class with game system integration
class BotAI {
public:
    // ... existing members ...

    // Game system managers
    std::unique_ptr<QuestManager> m_questManager;
    std::unique_ptr<InventoryManager> m_inventoryManager;
    std::unique_ptr<TradeManager> m_tradeManager;
    std::unique_ptr<AuctionManager> m_auctionManager;

    // System coordinator
    std::unique_ptr<SystemCoordinator> m_systemCoordinator;

    // Initialize game systems
    void InitializeGameSystems() {
        m_questManager = std::make_unique<QuestManager>(m_bot, this);
        m_inventoryManager = std::make_unique<InventoryManager>(m_bot, this);
        m_tradeManager = std::make_unique<TradeManager>(m_bot, this);
        m_auctionManager = std::make_unique<AuctionManager>(m_bot, this);
        m_systemCoordinator = std::make_unique<SystemCoordinator>(this);

        // Initialize all systems
        m_questManager->Initialize();
        m_inventoryManager->Initialize();
        m_tradeManager->Initialize();
        m_auctionManager->Initialize();
    }

    // Update game systems (called from UpdateAI)
    void UpdateGameSystems(uint32 diff) {
        // Coordinator handles priority and throttling
        m_systemCoordinator->Update(diff);
    }
};

System Lifecycle Hooks

namespace Playerbot {

// Lifecycle event definitions
enum class BotLifecycleEvent {
    BOT_SPAWNED,           // Bot entity created
    BOT_LOGGED_IN,         // Bot logged into world
    BOT_JOINED_GROUP,      // Bot joined a group
    BOT_LEFT_GROUP,        // Bot left a group
    BOT_ENTERED_COMBAT,    // Bot entered combat
    BOT_LEFT_COMBAT,       // Bot left combat
    BOT_DIED,              // Bot died
    BOT_RESURRECTED,       // Bot resurrected
    BOT_TELEPORTED,        // Bot changed map/zone
    BOT_LEVEL_UP,          // Bot gained level
    BOT_LOGGED_OUT,        // Bot logging out
    BOT_DESPAWNING         // Bot entity destroying
};

// Lifecycle integration for game systems
class SystemLifecycleManager {
public:
    void HandleLifecycleEvent(BotLifecycleEvent event, Player* bot) {
        switch (event) {
            case BotLifecycleEvent::BOT_LOGGED_IN:
                OnBotLoggedIn(bot);
                break;
            case BotLifecycleEvent::BOT_ENTERED_COMBAT:
                OnBotEnteredCombat(bot);
                break;
            case BotLifecycleEvent::BOT_LEFT_COMBAT:
                OnBotLeftCombat(bot);
                break;
            case BotLifecycleEvent::BOT_JOINED_GROUP:
                OnBotJoinedGroup(bot);
                break;
            // ... other events
        }
    }

private:
    void OnBotLoggedIn(Player* bot) {
        // Initialize quest cache
        bot->GetBotAI()->GetQuestManager()->UpdateQuestCache();

        // Check inventory state
        bot->GetBotAI()->GetInventoryManager()->OptimizeBags();

        // Update auction data
        bot->GetBotAI()->GetAuctionManager()->UpdateMarketData();
    }

    void OnBotEnteredCombat(Player* bot) {
        // Pause non-combat systems
        bot->GetBotAI()->GetQuestManager()->SetEnabled(false);
        bot->GetBotAI()->GetAuctionManager()->SetEnabled(false);
        bot->GetBotAI()->GetTradeManager()->SetEnabled(false);
    }

    void OnBotLeftCombat(Player* bot) {
        // Resume non-combat systems
        bot->GetBotAI()->GetQuestManager()->SetEnabled(true);
        bot->GetBotAI()->GetAuctionManager()->SetEnabled(true);
        bot->GetBotAI()->GetTradeManager()->SetEnabled(true);

        // Handle loot
        bot->GetBotAI()->GetInventoryManager()->HandlePendingLoot();
    }

    void OnBotJoinedGroup(Player* bot) {
        // Enable group trading features
        bot->GetBotAI()->GetTradeManager()->EnableGroupTrading();

        // Share quest progress
        bot->GetBotAI()->GetQuestManager()->ShareGroupQuests();
    }
};

}

Update Loop Integration

Priority-Based Update Scheduler

namespace Playerbot {

// System update priorities (lower = higher priority)
enum class UpdatePriority : uint8 {
    CRITICAL = 0,      // Combat, survival
    HIGH = 1,          // Movement, targeting
    NORMAL = 2,        // Questing, inventory
    LOW = 3,           // Trading, social
    IDLE = 4           // Auction, analysis
};

class SystemCoordinator {
public:
    explicit SystemCoordinator(BotAI* ai);

    void Update(uint32 diff) {
        m_frameTime += diff;

        // Update CPU budget
        UpdateCPUBudget();

        // Process systems by priority
        ProcessCriticalSystems(diff);

        if (HasCPUBudget(UpdatePriority::HIGH))
            ProcessHighPrioritySystems(diff);

        if (HasCPUBudget(UpdatePriority::NORMAL))
            ProcessNormalPrioritySystems(diff);

        if (HasCPUBudget(UpdatePriority::LOW))
            ProcessLowPrioritySystems(diff);

        if (HasCPUBudget(UpdatePriority::IDLE))
            ProcessIdleSystems(diff);

        // Track performance
        UpdateMetrics();
    }

private:
    BotAI* m_ai;
    uint32 m_frameTime;

    // CPU budget management
    struct CPUBudget {
        std::chrono::microseconds allocated;
        std::chrono::microseconds used;
        float utilizationPercent;
    } m_cpuBudget;

    // System update tracking
    struct SystemUpdateInfo {
        SystemManager* system;
        UpdatePriority priority;
        uint32 updateInterval;
        uint32 timeSinceUpdate;
        std::chrono::microseconds lastUpdateDuration;
    };

    std::vector<SystemUpdateInfo> m_systems;

    void ProcessCriticalSystems(uint32 diff) {
        // Always update combat and survival systems
        // These bypass CPU budget restrictions
    }

    void ProcessHighPrioritySystems(uint32 diff) {
        // Movement and targeting updates
        // Run every frame if CPU available
    }

    void ProcessNormalPrioritySystems(uint32 diff) {
        // Quest system - Update every 5 seconds
        if (ShouldUpdate(m_ai->GetQuestManager(), diff, 5000)) {
            auto start = std::chrono::high_resolution_clock::now();
            m_ai->GetQuestManager()->Update(diff);
            auto duration = std::chrono::high_resolution_clock::now() - start;
            RecordSystemUpdate(m_ai->GetQuestManager(), duration);
        }

        // Inventory system - Update every 2 seconds
        if (ShouldUpdate(m_ai->GetInventoryManager(), diff, 2000)) {
            auto start = std::chrono::high_resolution_clock::now();
            m_ai->GetInventoryManager()->Update(diff);
            auto duration = std::chrono::high_resolution_clock::now() - start;
            RecordSystemUpdate(m_ai->GetInventoryManager(), duration);
        }
    }

    void ProcessLowPrioritySystems(uint32 diff) {
        // Trade system - Update every 1 second when active
        if (m_ai->GetTradeManager()->IsActive()) {
            if (ShouldUpdate(m_ai->GetTradeManager(), diff, 1000)) {
                auto start = std::chrono::high_resolution_clock::now();
                m_ai->GetTradeManager()->Update(diff);
                auto duration = std::chrono::high_resolution_clock::now() - start;
                RecordSystemUpdate(m_ai->GetTradeManager(), duration);
            }
        }
    }

    void ProcessIdleSystems(uint32 diff) {
        // Auction system - Update every 60 seconds
        if (ShouldUpdate(m_ai->GetAuctionManager(), diff, 60000)) {
            auto start = std::chrono::high_resolution_clock::now();
            m_ai->GetAuctionManager()->Update(diff);
            auto duration = std::chrono::high_resolution_clock::now() - start;
            RecordSystemUpdate(m_ai->GetAuctionManager(), duration);
        }
    }

    bool HasCPUBudget(UpdatePriority priority) const {
        // Calculate available CPU based on priority
        float budgetPercent = 0.0f;
        switch (priority) {
            case UpdatePriority::CRITICAL: budgetPercent = 100.0f; break;
            case UpdatePriority::HIGH: budgetPercent = 50.0f; break;
            case UpdatePriority::NORMAL: budgetPercent = 30.0f; break;
            case UpdatePriority::LOW: budgetPercent = 15.0f; break;
            case UpdatePriority::IDLE: budgetPercent = 5.0f; break;
        }

        return m_cpuBudget.utilizationPercent < budgetPercent;
    }

    bool ShouldUpdate(SystemManager* system, uint32 diff, uint32 interval) {
        // Find system info
        auto it = std::find_if(m_systems.begin(), m_systems.end(),
            [system](SystemUpdateInfo const& info) { return info.system == system; });

        if (it == m_systems.end())
            return false;

        it->timeSinceUpdate += diff;
        if (it->timeSinceUpdate >= interval) {
            it->timeSinceUpdate = 0;
            return true;
        }

        return false;
    }
};

}

Configuration System

playerbots.conf Configuration

###################################################################################################
# GAME SYSTEM INTEGRATION CONFIGURATION
###################################################################################################

###################################################################################################
# QUEST SYSTEM
###################################################################################################

# Enable quest system for bots
Playerbot.Quest.Enable = 1

# Automatically accept quests from NPCs
Playerbot.Quest.AutoAccept = 1

# Automatically accept quests shared by group members
Playerbot.Quest.AutoAcceptShared = 1

# Automatically turn in completed quests
Playerbot.Quest.AutoComplete = 1

# Quest system update interval in milliseconds
Playerbot.Quest.UpdateInterval = 5000

# Maximum number of quests bot will accept (1-25)
Playerbot.Quest.MaxActiveQuests = 20

# Quest selection strategy (simple, optimal, group)
Playerbot.Quest.SelectionStrategy = optimal

# Prioritize group quests over solo quests
Playerbot.Quest.PrioritizeGroup = 1

# Maximum distance to travel for quest (yards)
Playerbot.Quest.MaxTravelDistance = 1000

# Quest cache update interval (milliseconds)
Playerbot.Quest.CacheUpdateInterval = 30000

###################################################################################################
# INVENTORY SYSTEM
###################################################################################################

# Enable inventory management for bots
Playerbot.Inventory.Enable = 1

# Automatically loot corpses and objects
Playerbot.Inventory.AutoLoot = 1

# Loot filter quality threshold (0=gray, 1=white, 2=green, 3=blue, 4=epic)
Playerbot.Inventory.LootQualityThreshold = 1

# Automatically equip better items
Playerbot.Inventory.AutoEquip = 1

# Equipment optimization strategy (simple, statweight, simulation)
Playerbot.Inventory.EquipStrategy = statweight

# Automatically sell gray/white items to vendors
Playerbot.Inventory.AutoSell = 1

# Items to always keep (comma-separated item IDs)
Playerbot.Inventory.ProtectedItems = 6948,6265,2901

# Automatically destroy items below threshold when bags full
Playerbot.Inventory.AutoDestroy = 0

# Minimum free bag slots to maintain
Playerbot.Inventory.MinFreeSlots = 5

# Inventory sort interval (milliseconds, 0 to disable)
Playerbot.Inventory.SortInterval = 300000

# Food/water management
Playerbot.Inventory.AutoBuyFood = 1
Playerbot.Inventory.AutoBuyWater = 1
Playerbot.Inventory.MinFoodCount = 20
Playerbot.Inventory.MinWaterCount = 20

# Inventory update interval (milliseconds)
Playerbot.Inventory.UpdateInterval = 2000

###################################################################################################
# TRADE SYSTEM
###################################################################################################

# Enable trading between bots and players
Playerbot.Trade.Enable = 1

# Automatically accept trades from group members
Playerbot.Trade.AutoAcceptGroup = 1

# Automatically accept trades from guild members
Playerbot.Trade.AutoAcceptGuild = 0

# Automatically accept trades from friends list
Playerbot.Trade.AutoAcceptFriends = 0

# Never accept trades from strangers
Playerbot.Trade.BlockStrangers = 1

# Trade value threshold for auto-accept (0 to disable)
Playerbot.Trade.AutoAcceptValueThreshold = 0

# Enable trade security checks
Playerbot.Trade.SecurityChecks = 1

# Maximum gold difference allowed in trades
Playerbot.Trade.MaxGoldDifference = 100

# Trade timeout in seconds
Playerbot.Trade.Timeout = 60

# Enable loot distribution in groups
Playerbot.Trade.GroupLootDistribution = 1

# Loot distribution method (need, greed, master)
Playerbot.Trade.LootMethod = need

# Share quest items with group members
Playerbot.Trade.ShareQuestItems = 1

# Share consumables with group members
Playerbot.Trade.ShareConsumables = 1

# Trade update interval (milliseconds)
Playerbot.Trade.UpdateInterval = 1000

###################################################################################################
# AUCTION SYSTEM
###################################################################################################

# Enable auction house usage for bots
Playerbot.Auction.Enable = 1

# Maximum number of active auctions per bot
Playerbot.Auction.MaxActiveAuctions = 10

# Maximum number of active bids per bot
Playerbot.Auction.MaxActiveBids = 10

# Auction house scan interval (milliseconds)
Playerbot.Auction.ScanInterval = 300000

# Market analysis update interval (milliseconds)
Playerbot.Auction.MarketUpdateInterval = 600000

# Auction creation strategy (simple, market, aggressive)
Playerbot.Auction.SellStrategy = market

# Auction bidding strategy (conservative, normal, aggressive)
Playerbot.Auction.BuyStrategy = normal

# Minimum profit margin for purchases (percent)
Playerbot.Auction.MinProfitMargin = 20

# Maximum investment per item (gold)
Playerbot.Auction.MaxInvestmentPerItem = 100

# Maximum total investment (gold)
Playerbot.Auction.MaxTotalInvestment = 1000

# Undercut percentage when creating auctions
Playerbot.Auction.UndercutPercent = 5

# Auction duration preference (1=12h, 2=24h, 3=48h)
Playerbot.Auction.DefaultDuration = 2

# Enable price trend analysis
Playerbot.Auction.EnableTrendAnalysis = 1

# Price history retention (days)
Playerbot.Auction.PriceHistoryDays = 7

# Auction system update interval (milliseconds)
Playerbot.Auction.UpdateInterval = 60000

###################################################################################################
# PERFORMANCE CONFIGURATION
###################################################################################################

# CPU budget allocation per system (percentage)
Playerbot.Performance.Quest.CPUBudget = 10
Playerbot.Performance.Inventory.CPUBudget = 15
Playerbot.Performance.Trade.CPUBudget = 5
Playerbot.Performance.Auction.CPUBudget = 5

# Memory limits per system (MB)
Playerbot.Performance.Quest.MemoryLimit = 50
Playerbot.Performance.Inventory.MemoryLimit = 100
Playerbot.Performance.Trade.MemoryLimit = 20
Playerbot.Performance.Auction.MemoryLimit = 200

# Cache configuration
Playerbot.Performance.EnableCaching = 1
Playerbot.Performance.CacheSize = 100
Playerbot.Performance.CacheTTL = 300000

# System update staggering (prevent all bots updating simultaneously)
Playerbot.Performance.StaggerUpdates = 1
Playerbot.Performance.StaggerInterval = 100

###################################################################################################
# DEBUG CONFIGURATION
###################################################################################################

# Enable debug logging for game systems
Playerbot.Debug.Quest = 0
Playerbot.Debug.Inventory = 0
Playerbot.Debug.Trade = 0
Playerbot.Debug.Auction = 0

# Performance profiling
Playerbot.Debug.ProfileSystems = 0
Playerbot.Debug.ProfileInterval = 10000

Performance Optimization Strategy

CPU Budget Allocation (5000 Bots)

namespace Playerbot {

class PerformanceManager {
public:
    // Target: <10% total CPU for 5000 bots
    // Per-bot budget: 0.002% CPU (0.00002 of total)

    struct SystemBudget {
        float questSystem = 0.0002f;      // 0.02% per bot
        float inventorySystem = 0.0003f;  // 0.03% per bot
        float tradeSystem = 0.0001f;      // 0.01% per bot
        float auctionSystem = 0.00005f;   // 0.005% per bot
        float totalBudget = 0.00065f;     // 0.065% per bot
    };

    // With 5000 bots:
    // Total Quest CPU: 1.0%
    // Total Inventory CPU: 1.5%
    // Total Trade CPU: 0.5%
    // Total Auction CPU: 0.25%
    // Total Game Systems: 3.25% CPU
};

}

Memory Optimization

namespace Playerbot {

// Memory pools for frequent allocations
template<typename T>
class ObjectPool {
public:
    explicit ObjectPool(size_t initialSize = 1000);

    T* Acquire();
    void Release(T* obj);

private:
    std::stack<std::unique_ptr<T>> m_available;
    std::vector<std::unique_ptr<T>> m_all;
};

// Flyweight pattern for shared data
class QuestDataFlyweight {
public:
    static QuestDataFlyweight* GetQuest(uint32 questId);

private:
    static std::unordered_map<uint32, std::unique_ptr<QuestDataFlyweight>> s_quests;
};

// Memory targets per bot:
// Quest system: 2MB
// Inventory system: 3MB
// Trade system: 0.5MB
// Auction system: 1MB
// Total per bot: 6.5MB
// Total for 5000 bots: 32.5GB

}

Cache Strategy

namespace Playerbot {

template<typename Key, typename Value>
class LRUCache {
public:
    explicit LRUCache(size_t maxSize);

    bool Get(Key const& key, Value& value);
    void Put(Key const& key, Value const& value);
    void Clear();

private:
    size_t m_maxSize;
    std::list<std::pair<Key, Value>> m_items;
    std::unordered_map<Key, typename std::list<std::pair<Key, Value>>::iterator> m_index;
};

// Shared caches for all bots
class GlobalCacheManager {
public:
    static GlobalCacheManager& Instance();

    // Quest caches
    LRUCache<uint32, Quest const*> questCache{10000};
    LRUCache<uint32, QuestObjective> objectiveCache{50000};

    // Item caches
    LRUCache<uint32, ItemTemplate const*> itemCache{20000};
    LRUCache<uint32, float> itemValueCache{20000};

    // Auction caches
    LRUCache<uint32, uint32> marketPriceCache{10000};
    LRUCache<uint32, float> priceTrendCache{10000};
};

}

Error Handling Strategy

Comprehensive Error Handling

namespace Playerbot {

enum class SystemError {
    NONE,
    QUEST_NOT_AVAILABLE,
    QUEST_PREREQUISITES_NOT_MET,
    QUEST_INVENTORY_FULL,
    INVENTORY_FULL,
    ITEM_NOT_FOUND,
    TRADE_PARTNER_OFFLINE,
    TRADE_DISTANCE_TOO_FAR,
    AUCTION_THROTTLED,
    AUCTION_INSUFFICIENT_FUNDS,
    SYSTEM_DISABLED,
    PERFORMANCE_THROTTLED
};

class SystemErrorHandler {
public:
    struct ErrorContext {
        SystemError error;
        std::string message;
        uint32 timestamp;
        uint32 retryCount;
        uint32 maxRetries;
    };

    void HandleError(SystemError error, SystemManager* system) {
        switch (error) {
            case SystemError::QUEST_NOT_AVAILABLE:
                HandleQuestNotAvailable(system);
                break;
            case SystemError::INVENTORY_FULL:
                HandleInventoryFull(system);
                break;
            case SystemError::TRADE_DISTANCE_TOO_FAR:
                HandleTradeDistance(system);
                break;
            case SystemError::AUCTION_THROTTLED:
                HandleAuctionThrottle(system);
                break;
            case SystemError::PERFORMANCE_THROTTLED:
                HandlePerformanceThrottle(system);
                break;
            // ... other errors
        }
    }

private:
    void HandleQuestNotAvailable(SystemManager* system) {
        // Mark quest as unavailable in cache
        // Schedule retry in 30 seconds
        // Try alternative quest
    }

    void HandleInventoryFull(SystemManager* system) {
        // Trigger inventory cleanup
        // Sell/destroy low-value items
        // Move to vendor if necessary
    }

    void HandleTradeDistance(SystemManager* system) {
        // Move closer to trade partner
        // Cancel trade if movement fails
        // Notify partner of issue
    }

    void HandleAuctionThrottle(SystemManager* system) {
        // Exponential backoff
        // Reduce auction activity
        // Cache results for longer
    }

    void HandlePerformanceThrottle(SystemManager* system) {
        // Reduce update frequency
        // Disable non-critical features
        // Log performance metrics
    }
};

}

Error Recovery Patterns

namespace Playerbot {

// Retry with exponential backoff
class RetryPolicy {
public:
    explicit RetryPolicy(uint32 maxRetries = 3, uint32 baseDelay = 1000);

    bool ShouldRetry() const;
    uint32 GetDelayMs() const;
    void RecordAttempt();
    void Reset();

private:
    uint32 m_maxRetries;
    uint32 m_baseDelay;
    uint32 m_attempts;
};

// Circuit breaker pattern
class CircuitBreaker {
public:
    enum class State {
        CLOSED,     // Normal operation
        OPEN,       // Failing, block calls
        HALF_OPEN   // Testing recovery
    };

    explicit CircuitBreaker(uint32 threshold = 5, uint32 timeout = 30000);

    bool CanExecute() const;
    void RecordSuccess();
    void RecordFailure();

private:
    State m_state;
    uint32 m_failureCount;
    uint32 m_threshold;
    uint32 m_timeout;
    uint32 m_lastFailureTime;
};

}

Thread Safety Architecture

Thread Safety Guarantees

namespace Playerbot {

// All game system operations are thread-safe through Player object
// Player operations are synchronized on map thread

class ThreadSafetyGuarantees {
public:
    // Rule 1: All Player API calls must be on map thread
    static bool IsOnMapThread(Player* player) {
        return player->GetMap()->IsInWorld();
    }

    // Rule 2: No shared mutable state between bots
    // Each bot has its own manager instances

    // Rule 3: Global caches use read-write locks
    template<typename T>
    class ThreadSafeCache {
    public:
        bool Get(uint32 key, T& value) const {
            std::shared_lock<std::shared_mutex> lock(m_mutex);
            auto it = m_cache.find(key);
            if (it != m_cache.end()) {
                value = it->second;
                return true;
            }
            return false;
        }

        void Put(uint32 key, T const& value) {
            std::unique_lock<std::shared_mutex> lock(m_mutex);
            m_cache[key] = value;
        }

    private:
        mutable std::shared_mutex m_mutex;
        std::unordered_map<uint32, T> m_cache;
    };

    // Rule 4: Database operations use async transactions
    static void AsyncDatabaseOperation(std::function<void()> operation) {
        CharacterDatabase.Execute(operation);
    }
};

}

Lock-Free Data Structures

namespace Playerbot {

// Lock-free queue for inter-system communication
template<typename T>
class LockFreeQueue {
public:
    void Push(T item) {
        Node* newNode = new Node{std::move(item), nullptr};
        Node* prevTail = m_tail.exchange(newNode);
        prevTail->next.store(newNode);
    }

    bool TryPop(T& item) {
        Node* head = m_head.load();
        Node* next = head->next.load();

        if (next == nullptr)
            return false;

        item = std::move(next->data);
        m_head.store(next);
        delete head;
        return true;
    }

private:
    struct Node {
        T data;
        std::atomic<Node*> next;
    };

    std::atomic<Node*> m_head;
    std::atomic<Node*> m_tail;
};

}

Implementation Roadmap

Phase 1: Foundation (Week 1-2)

  1. Create directory structure
  2. Implement base SystemManager class
  3. Create SystemCoordinator
  4. Implement configuration loading
  5. Set up performance monitoring

Phase 2: Quest System (Week 3-4)

  1. Implement QuestManager
  2. Create QuestStrategy
  3. Implement QuestCache
  4. Integrate with BotAI
  5. Test with 100 bots

Phase 3: Inventory System (Week 5-6)

  1. Implement InventoryManager
  2. Create LootManager
  3. Implement EquipmentOptimizer
  4. Add ItemCache
  5. Test with 500 bots

Phase 4: Trade System (Week 7)

  1. Implement TradeManager
  2. Create TradePolicy
  3. Add group trading features
  4. Test trade scenarios
  5. Validate security

Phase 5: Auction System (Week 8-9)

  1. Implement AuctionManager
  2. Create PriceAnalyzer
  3. Implement market strategies
  4. Add auction caching
  5. Test with 1000 bots

Phase 6: Integration & Optimization (Week 10-11)

  1. Full system integration testing
  2. Performance optimization
  3. Memory optimization
  4. Load testing with 5000 bots
  5. Documentation completion

Phase 7: Polish & Deployment (Week 12)

  1. Bug fixes
  2. Final optimizations
  3. Stress testing
  4. Deployment preparation
  5. Release documentation

Key Design Decisions

1. Module-Only Implementation

  • All code in src/modules/Playerbot/
  • Zero core modifications required
  • Uses existing Player APIs

2. Performance-First Design

  • Aggressive caching
  • Update throttling
  • CPU budget management
  • Memory pooling

3. Scalability Architecture

  • O(1) operations where possible
  • Shared caches for common data
  • Lock-free communication
  • Async database operations

4. Error Resilience

  • Comprehensive error handling
  • Retry policies
  • Circuit breakers
  • Graceful degradation

5. Configuration Flexibility

  • Extensive configuration options
  • Runtime adjustable parameters
  • Per-system enable/disable
  • Performance tuning knobs

Success Metrics

Performance Targets (5000 Bots)

  • Total CPU usage: <10%
  • Memory per bot: <10MB
  • Update latency: <10ms
  • Database queries/sec: <1000

Quality Metrics

  • Zero crashes
  • Zero memory leaks
  • 100% API compliance
  • Complete error handling

Feature Completeness

  • Full quest automation
  • Intelligent inventory management
  • Secure trading system
  • Profitable auction strategies

Conclusion

This architecture provides a comprehensive, scalable, and performant solution for integrating game systems into the PlayerBot module. The design prioritizes performance, maintainability, and extensibility while adhering to all constraints specified in CLAUDE.md.

The modular architecture allows for independent development and testing of each system, while the coordinator ensures efficient resource utilization across all systems. With proper implementation following this design, the system will easily handle 5000+ concurrent bots with minimal performance impact.

Reference in New Issue View Git Blame Copy Permalink