ThordekkCore/REFACTORING_CONTINUATION_PLAN.md

REFACTORING CONTINUATION PLAN - Post Phase 1

Executive Summary

Phase 1 (State Machine Foundation) is COMPLETE. This document outlines the continuation plan that harmonizes with the EXISTING Phase 2 infrastructure (BehaviorManager, IdleStrategy, CombatMovementStrategy) that was completed previously.

Critical Understanding:

• ✅ OLD Phase 2 (BehaviorManager infrastructure) = ALREADY DONE
• ✅ NEW Phase 1 (State Machine) = JUST COMPLETED
• 🔄 Next: Continue with behavior priority and combat fixes

---

ARCHITECTURE HARMONIZATION

What We Now Have (Phase 1 + Old Phase 2)

┌─────────────────────────────────────────────────────────────┐
│                    COMPLETED LAYERS                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  NEW Phase 1: State Machine Layer (JUST COMPLETED)   │  │
│  │  ────────────────────────────────────────────────────│  │
│  │  • BotStateMachine (lifecycle management)            │  │
│  │  • BotInitStateMachine (fixes Issue #1)              │  │
│  │  • SafeObjectReference (fixes Issue #4)              │  │
│  │  • Event system skeleton                              │  │
│  └──────────────────────────────────────────────────────┘  │
│                           ↓ uses                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  OLD Phase 2: Infrastructure Layer (ALREADY DONE)    │  │
│  │  ────────────────────────────────────────────────────│  │
│  │  • BehaviorManager (throttled updates, atomics)      │  │
│  │  • IdleStrategy (observer pattern)                   │  │
│  │  • CombatMovementStrategy (role positioning)         │  │
│  │  • QuestManager, TradeManager, etc. (refactored)     │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    REMAINING WORK                            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Phase 2: Behavior Priority System (70 hours)               │
│  ────────────────────────────────────────────────────────── │
│  • EXTEND existing BehaviorManager with priority logic      │
│  • Fix combat target acquisition (Issue #2)                 │
│  • Fix LeaderFollowBehavior relevance during combat (#2/#3) │
│  • Implement mutual exclusion rules                         │
│                                                              │
│  Phase 3: Safe References - PARTIALLY DONE (20 hours)       │
│  ────────────────────────────────────────────────────────── │
│  • SafeObjectReference already created in Phase 1 ✅        │
│  • Just need: Apply to all remaining raw pointers           │
│  • ReferenceValidator utilities                             │
│  • Integration with ObjectCache                             │
│                                                              │
│  Phase 4: Event System Full Implementation (70 hours)       │
│  ────────────────────────────────────────────────────────── │
│  • Expand BotEventTypes.h skeleton from Phase 1             │
│  • BotEventSystem dispatcher                                │
│  • Group/Combat/World event observers                       │
│  • Convert polling to event-driven                          │
│                                                              │
│  Phase 5: Integration & Testing (50 hours)                  │
│  ────────────────────────────────────────────────────────── │
│  • Validate all 4 issues fixed                              │
│  • Performance testing                                      │
│  • Production deployment                                    │
│                                                              │
└─────────────────────────────────────────────────────────────┘

TOTAL REMAINING: ~210 hours (reduced from 365 because Phase 1 done + Phase 3 partially done)

---

PHASE 2: BEHAVIOR PRIORITY SYSTEM (70 hours)

Objective

Fix Issues #2 & #3 by implementing behavior priority and combat coordination.

What EXISTS (Don't Recreate)

• ✅ BehaviorManager base class (AI/BehaviorManager.h)
• ✅ Throttling system with atomic flags
• ✅ Template method pattern for updates
• ✅ IdleStrategy observer pattern
• ✅ CombatMovementStrategy framework

What's MISSING (Must Create)

• ❌ Priority-based behavior selection
• ❌ Mutual exclusion rules between behaviors
• ❌ Combat target acquisition robustness
• ❌ Follow behavior combat relevance fix

Components to Build

2.1 BehaviorPriorityManager.h/cpp (NEW - 400 lines)

// EXTENDS the existing BehaviorManager, doesn't replace it
namespace Playerbot {

enum class BehaviorPriority : uint8_t {
    DEAD = 0,
    CRITICAL_ERROR = 10,
    COMBAT = 100,        // Highest operational priority
    FLEEING = 90,
    FOLLOW = 50,         // Mid - only when not in combat
    GATHERING = 40,
    TRADING = 30,
    IDLE = 10            // Lowest
};

class BehaviorPriorityManager {
public:
    // Select the highest priority ACTIVE behavior
    Strategy* SelectActiveBehavior(std::vector<Strategy*>& strategies);

    // Check if two behaviors can run simultaneously
    bool CanCoexist(Strategy* a, Strategy* b);

    // Register mutual exclusion rules
    void AddExclusionRule(BehaviorPriority a, BehaviorPriority b);

private:
    std::map<BehaviorPriority, std::vector<BehaviorPriority>> m_exclusionRules;
};

} // namespace

2.2 Update LeaderFollowBehavior.cpp (MODIFY - 50 lines)

// FIX FOR ISSUES #2 & #3
float LeaderFollowBehavior::GetRelevance(BotAI* ai) const {
    Player* bot = ai->GetBot();
    if (!bot || !bot->IsAlive())
        return 0.0f;

    // CRITICAL FIX: ZERO relevance during combat
    // This prevents follow from interfering with combat positioning
    if (bot->IsInCombat()) {
        TC_LOG_TRACE("module.playerbot.follow",
            "Bot {} in combat - follow behavior disabled (FIX FOR ISSUE #2 & #3)",
            bot->GetName());
        return 0.0f;  // Changed from 10.0f to 0.0f
    }

    // Normal follow logic when not in combat
    // ... existing code ...
}

2.3 Update ClassAI.cpp - Target Acquisition (MODIFY - 80 lines)

// FIX FOR ISSUE #2: Robust target acquisition
void ClassAI::OnCombatUpdate(uint32 diff) {
    if (!GetBot() || !GetBot()->IsAlive())
        return;

    // CRITICAL FIX: Ensure we have a target before doing anything
    if (!_currentCombatTarget || !_currentCombatTarget->IsAlive()) {
        // Priority 1: Bot's current victim
        _currentCombatTarget = GetBot()->GetVictim();

        // Priority 2: Group leader's target
        if (!_currentCombatTarget) {
            if (Group* group = GetBot()->GetGroup()) {
                Player* leader = ObjectAccessor::FindPlayer(group->GetLeaderGUID());
                if (leader && leader->IsInCombat()) {
                    _currentCombatTarget = leader->GetVictim();
                }
            }
        }

        // Priority 3: Nearest enemy
        if (!_currentCombatTarget) {
            _currentCombatTarget = GetNearestHostileTarget(40.0f);
        }

        // If still no target, return and wait
        if (!_currentCombatTarget) {
            TC_LOG_DEBUG("module.playerbot.classai",
                "Bot {} in combat but no valid target found - waiting",
                GetBot()->GetName());
            return;
        }

        TC_LOG_DEBUG("module.playerbot.classai",
            "Bot {} acquired combat target: {} (FIX FOR ISSUE #2)",
            GetBot()->GetName(), _currentCombatTarget->GetName());
    }

    // Verify target is still valid
    if (!_currentCombatTarget->IsAlive() || !_currentCombatTarget->IsInWorld()) {
        _currentCombatTarget = nullptr;
        return;
    }

    // Now continue with combat logic (existing code)
    UpdateCombatMovement(diff);
    UpdateRotation(diff);
    UpdateDefensives(diff);
    UpdateBuffs(diff);
}

// FIX FOR ISSUE #3: Explicit facing
void ClassAI::UpdateCombatMovement(uint32 diff) {
    if (!_currentCombatTarget)
        return;

    float currentDistance = GetBot()->GetDistance(_currentCombatTarget);
    float optimalRange = GetOptimalCombatRange();
    float rangeTolerance = 2.0f;

    if (currentDistance > optimalRange + rangeTolerance) {
        BotMovementUtil::ChaseTarget(GetBot(), _currentCombatTarget, optimalRange);
        GetBot()->SetFacingToObject(_currentCombatTarget); // FIX: Explicit facing
    } else if (currentDistance < optimalRange - rangeTolerance && IsRangedClass()) {
        BotMovementUtil::MoveAwayFrom(GetBot(), _currentCombatTarget, optimalRange);
        GetBot()->SetFacingToObject(_currentCombatTarget); // FIX: Maintain facing
    } else {
        // In optimal range - just face the target
        GetBot()->SetFacingToObject(_currentCombatTarget); // FIX: Always face target
    }
}

2.4 Integration with BotAI.cpp (MODIFY - 100 lines)

void BotAI::UpdateAI(uint32 diff) {
    // Phase 1 already added: State machine initialization
    if (!m_initStateMachine || !m_initStateMachine->IsReady()) {
        return; // Skip until initialized
    }

    // NEW: Behavior priority selection
    if (!m_behaviorPriorityManager) {
        m_behaviorPriorityManager = std::make_unique<BehaviorPriorityManager>();
        ConfigurePriorityRules();
    }

    // Collect all active strategies
    std::vector<Strategy*> activeStrategies;
    for (auto& strategy : m_strategies) {
        if (strategy->IsActive()) {
            activeStrategies.push_back(strategy.get());
        }
    }

    // Select highest priority behavior that can run
    Strategy* activeBehavior = m_behaviorPriorityManager->SelectActiveBehavior(activeStrategies);

    if (activeBehavior) {
        activeBehavior->Update(diff);
    }

    // Managers always update (they have their own throttling)
    UpdateManagers(diff);
}

void BotAI::ConfigurePriorityRules() {
    // Combat and Follow are mutually exclusive
    m_behaviorPriorityManager->AddExclusionRule(
        BehaviorPriority::COMBAT,
        BehaviorPriority::FOLLOW
    );

    // Fleeing overrides everything except critical errors
    m_behaviorPriorityManager->AddExclusionRule(
        BehaviorPriority::FLEEING,
        BehaviorPriority::COMBAT
    );

    // ... more rules as needed
}

Task Breakdown

Task	Description	Hours	Agent
2.1	Create BehaviorPriorityManager.h/cpp	12	cpp-architecture-optimizer
2.2	Update LeaderFollowBehavior.cpp	4	general-purpose
2.3	Update ClassAI.cpp target acquisition	8	wow-mechanics-expert
2.4	Update ClassAI.cpp combat movement	6	wow-mechanics-expert
2.5	Integrate with BotAI.cpp	8	cpp-architecture-optimizer
2.6	Add mutual exclusion rules	6	general-purpose
2.7	Create unit tests	12	test-automation-engineer
2.8	Integration testing	8	test-automation-engineer
2.9	Performance validation	4	general-purpose
2.10	Documentation	2	general-purpose

Total: 70 hours

---

PHASE 3: SAFE REFERENCES COMPLETION (20 hours)

Status: 70% Complete from Phase 1

Phase 1 already created:

• ✅ SafeObjectReference template (fixes Issue #4)
• ✅ Thread-safe caching
• ✅ ObjectGuid validation
• ✅ Unit tests

Remaining Work (20 hours)

3.1 Apply to All Remaining Raw Pointers (12 hours)

// Replace ALL occurrences of:
Player* m_target;           // UNSAFE
Player* m_groupLeader;      // UNSAFE (already fixed in Phase 1 for BotAI)
Creature* m_followTarget;   // UNSAFE

// With:
SafePlayerReference m_target;
SafePlayerReference m_groupLeader;
SafeCreatureReference m_followTarget;

Files to update (~15 files):

• All ClassAI files (13 classes)
• All specialization files
• Movement behaviors
• Combat strategies

3.2 ReferenceValidator Utilities (4 hours)

class ReferenceValidator {
public:
    // Batch validation for multiple references
    static bool ValidateAll(std::vector<SafeObjectReference<Player>*> refs);

    // Validate reference with logging
    static Player* ValidateAndLog(SafePlayerReference& ref, const char* context);

    // Clean up invalid references
    static void CleanupInvalidReferences(BotAI* ai);
};

3.3 Integration & Testing (4 hours)

• Update all reference usage sites
• Add validation tests
• Performance regression tests

---

PHASE 4: EVENT SYSTEM FULL IMPLEMENTATION (70 hours)

Status: Skeleton exists from Phase 1

Phase 1 created:

• ✅ BotEventTypes.h skeleton
• ✅ BotEvent structure
• ✅ IEventObserver interface
• ✅ Forward declarations

Remaining Work (70 hours)

4.1 BotEventSystem.h/cpp (20 hours)

class BotEventSystem {
public:
    // Register observer for specific event types
    void RegisterObserver(IEventObserver* observer, std::vector<EventType> interests);

    // Dispatch event to all interested observers
    void DispatchEvent(const BotEvent& event);

    // Priority-based event queue
    void QueueEvent(const BotEvent& event, EventPriority priority);

    // Process queued events
    void ProcessEvents();

private:
    std::map<EventType, std::vector<IEventObserver*>> m_observers;
    std::priority_queue<BotEvent> m_eventQueue;
};

4.2 Group Event Observer (15 hours)

class GroupEventObserver : public IEventObserver {
public:
    void OnEvent(const BotEvent& event) override;

private:
    void HandleGroupJoin(const BotEvent& event);
    void HandleGroupLeave(const BotEvent& event);
    void HandleLeaderChange(const BotEvent& event);
    void HandleLeaderLogout(const BotEvent& event); // FIX FOR ISSUE #4
};

4.3 Combat Event Observer (15 hours)

4.4 World Event Observer (10 hours)

4.5 Integration & Testing (10 hours)

---

PHASE 5: FINAL INTEGRATION & TESTING (50 hours)

5.1 Issue Validation (15 hours)

• ✅ Issue #1: Bot in group at login (validate fix works)
• ✅ Issue #2: Ranged combat (validate target acquisition + relevance fix)
• ✅ Issue #3: Melee facing (validate facing fix)
• ✅ Issue #4: Logout crash (validate SafeObjectReference works)

5.2 Performance Testing (15 hours)

• 5000 bot stress test
• Memory leak testing
• Thread safety validation
• CPU profiling

5.3 Production Deployment (10 hours)

• Build verification
• Database migration scripts
• Configuration guide
• Deployment documentation

5.4 Final Documentation (10 hours)

• Architecture overview
• Developer guide
• API documentation
• Migration guide

---

CRITICAL SUCCESS FACTORS

1. Harmonization Checklist

• ✅ Don't recreate BehaviorManager (already exists)
• ✅ Don't recreate IdleStrategy (already exists)
• ✅ Don't recreate CombatMovementStrategy (already exists)
• ✅ EXTEND existing components, don't replace
• ✅ Use Phase 1's state machine for initialization
• ✅ Use Phase 1's SafeObjectReference for safety

2. Integration Points

• BehaviorPriorityManager EXTENDS BehaviorManager
• ClassAI updates USE CombatMovementStrategy
• Event system NOTIFIES existing strategies
• State machine COORDINATES with existing managers

3. No Breaking Changes

• Existing Phase 2 code continues to work
• Phase 1 components integrate seamlessly
• All new features are additive
• Backward compatibility maintained

---

ESTIMATED COMPLETION

Phase	Hours	Status
Phase 1 (State Machine)	85	✅ COMPLETE
Phase 2 (Behavior Priority)	70	🔄 NEXT
Phase 3 (Safe Refs Complete)	20	⏳ After Phase 2
Phase 4 (Event System)	70	⏳ After Phase 3
Phase 5 (Integration)	50	⏳ After Phase 4

Total Remaining: 210 hours (~5.3 weeks @ 40hrs/week)

---

NEXT IMMEDIATE STEPS

1. Start Phase 2.1: Create BehaviorPriorityManager.h/cpp
2. Update LeaderFollowBehavior: Fix relevance to 0.0f during combat
3. Update ClassAI: Fix target acquisition and facing
4. Integrate with BotAI: Priority-based strategy selection
5. Test: Validate Issues #2 & #3 are fixed

Ready to begin Phase 2 implementation.

---

Continuation Plan Created: 2025-10-06 Current Status: Phase 1 Complete, Phase 2 Ready Total Project: 295 hours (85 done + 210 remaining)