# TrinityCore PlayerBot - Build System Guide

## Claude Code Web - Iterative Compilation Environment

This guide explains how to use the build system for iterative development and compilation of the PlayerBot module in Claude Code Web.

---

## 🎯 Quick Start

### 1. Quick Syntax Check (Fastest - 10-30 seconds)

Check recently modified files:
```bash
./check-playerbot-syntax.sh recent
```

Check all PlayerBot files:
```bash
./check-playerbot-syntax.sh all
```

Check only git-staged files:
```bash
./check-playerbot-syntax.sh staged
```

Check specific file:
```bash
./check-playerbot-syntax.sh src/modules/Playerbot/Social/UnifiedLootManager.cpp
```

### 2. Full Build (Slower - 5-15 minutes)

First time setup and build:
```bash
./build-playerbot.sh
```

### 3. Error Analysis & Fixes

After a failed build, analyze errors:
```bash
./fix-playerbot-errors.sh
```

---

## 📋 Available Scripts

### `build-playerbot.sh` - Full Compilation

**Purpose**: Complete CMake configuration and compilation of PlayerBot module

**What it does**:
1. ✅ Checks all build dependencies (cmake, g++, libraries)
2. ✅ Configures CMake with PlayerBot enabled
3. ✅ Builds the game library (includes PlayerBot)
4. ✅ Generates detailed build logs
5. ✅ Reports compilation statistics

**Output**:
- `build-playerbot/` - CMake build directory
- `build-playerbot/cmake-config.log` - CMake configuration output
- `build-playerbot/build.log` - Full compilation log
- `build-playerbot/compile_commands.json` - Compilation database for IDE integration

**Typical execution time**: 5-15 minutes (first run), 1-5 minutes (incremental)

**Usage**:
```bash
./build-playerbot.sh
```

---

### `check-playerbot-syntax.sh` - Fast Syntax Validation

**Purpose**: Quick syntax-only checks without full compilation

**What it does**:
1. ✅ Runs g++ syntax-only compilation (`-fsyntax-only`)
2. ✅ Checks include paths and header availability
3. ✅ Detects syntax errors, type errors, missing includes
4. ❌ Does NOT detect linker errors or missing implementations

**Modes**:
- `recent` - Check files modified in last 24 hours (default)
- `all` - Check all .cpp files in PlayerBot module
- `staged` - Check only git-staged files
- `<file>` - Check specific file

**Typical execution time**: 10-30 seconds

**Usage**:
```bash
# Check recent changes (fast iteration)
./check-playerbot-syntax.sh recent

# Check everything before committing
./check-playerbot-syntax.sh all

# Check only staged changes
./check-playerbot-syntax.sh staged

# Check specific file
./check-playerbot-syntax.sh src/modules/Playerbot/Dungeon/DungeonBehavior.cpp
```

**Use cases**:
- ✅ Rapid iteration during development
- ✅ Pre-commit validation
- ✅ Checking if includes are correct
- ✅ Verifying syntax before full build

---

### `fix-playerbot-errors.sh` - Error Analysis & Suggestions

**Purpose**: Analyze compilation errors and suggest fixes

**What it does**:
1. ✅ Categorizes errors by type (includes, undeclared, members, types, etc.)
2. ✅ Counts errors per category
3. ✅ Shows most problematic files
4. ✅ Suggests specific fixes for common errors
5. ✅ Provides file paths for editing

**Error categories detected**:
- 🔴 **Missing includes**: Suggests which headers to add
- 🔴 **Undeclared identifiers**: Suggests includes or forward declarations
- 🔴 **Missing members**: Indicates wrong class/method name
- 🔴 **Type errors**: Missing type definitions
- 🟡 **Ambiguous references**: Suggests namespace qualification
- 🔴 **Undefined references**: Linker errors (missing implementations)

**Typical execution time**: < 5 seconds

**Usage**:
```bash
# Run after a failed build
./build-playerbot.sh
./fix-playerbot-errors.sh
```

**Example output**:
```
Error Summary:
  Undefined references: 3
  Missing members: 5
  Undeclared identifiers: 12
  Missing includes: 8
  Type errors: 2
  Ambiguous references: 1

════════════════════════════════════════
MISSING INCLUDE FILES (8 errors)
════════════════════════════════════════

  Missing: GroupCoordinator.h
  Add: #include "../Advanced/GroupCoordinator.h"

  Missing: Random.h
  Add: #include "Random.h"
```

---

## 🔄 Iterative Development Workflow

### Recommended workflow for fixing compilation errors:

```bash
# 1. Make code changes in Claude Code

# 2. Quick syntax check (10-30 seconds)
./check-playerbot-syntax.sh recent

# 3. If syntax is OK, do full build (5-15 minutes)
./build-playerbot.sh

# 4. If build fails, analyze errors
./fix-playerbot-errors.sh

# 5. Fix errors based on suggestions

# 6. Repeat from step 2 until successful
```

### Fast iteration cycle (for rapid development):

```bash
# Edit files...

# Quick check
./check-playerbot-syntax.sh recent

# Fix errors

# Quick check again
./check-playerbot-syntax.sh recent

# Once syntax is clean, do full build
./build-playerbot.sh
```

---

## 📦 Dependencies

### Required packages:

**Build Tools** (already installed in Claude Code Web):
- ✅ `cmake` (3.28.3+)
- ✅ `g++` (13.3.0+) - C++20 support
- ✅ `make`
- ✅ `ninja` (optional, faster builds)

**System Libraries** (already installed in Claude Code Web):
- ✅ `libboost-dev` (1.83.0)
- ✅ `libssl-dev` (OpenSSL 3.0)
- ✅ `libreadline-dev`
- ✅ `libmysqlclient-dev` (if available)

**PlayerBot Enterprise Dependencies** (automatically initialized via SessionStart hook):
- 🔄 **Intel TBB** (Threading Building Blocks) - Vendored via git submodule
- 🔄 **phmap** (Parallel Hashmap) - Vendored via git submodule
- 🔄 **MySQL 9.0.1** (Client Library) - Built from source (~10-15 min first session)
- 🔄 **Boost 1.83.0** (Required libraries) - Built from source (~5-10 min first session)

> **Note**: All dependencies are **automatically set up** when you start a Claude Code Web session via the SessionStart hook. On first session, this takes ~17-28 minutes. Subsequent sessions validate in < 10 seconds.

### Automatic Dependency Initialization:

On first session start, the SessionStart hook will:
1. **TBB & phmap**: Initialize from git submodules (~2-3 min, ~50-100MB)
2. **MySQL 9**: Download and build client library from source (~10-15 min, ~500MB)
3. **Boost 1.83.0**: Download and build required libraries from source (~5-10 min, ~300MB)
4. Export environment variables (MYSQL_INCLUDE_DIR, MYSQL_LIBRARY, BOOST_ROOT)
5. Persist variables for all subsequent bash commands in the session

**Subsequent sessions**: Dependencies are validated instantly (< 10 seconds)

**First-time run example**:
```bash
./build-playerbot.sh

# Output:
# [INFO] Checking PlayerBot enterprise dependencies (TBB, phmap)...
# [WARNING] ⚠️  TBB not found - will initialize git submodules
# [WARNING] ⚠️  phmap not found - will initialize git submodules
# [INFO] Initializing PlayerBot vendored dependencies (TBB, phmap)...
# [SUCCESS] ✅ Git submodules initialized successfully!
# [SUCCESS] ✅ TBB and phmap are now available (zero system installation required)
```

### Check dependencies:

```bash
./build-playerbot.sh
# Will check all dependencies and initialize git submodules if needed
# Fails fast with clear error messages if critical dependencies are missing
```

---

## 🐛 Common Errors & Fixes

### 1. Missing Include Errors

**Error**:
```
error: 'GetBotAI' was not declared in this scope
```

**Fix**:
```cpp
#include "Core/PlayerBotHelpers.h"
```

---

### 2. Missing GroupCoordinator

**Error**:
```
error: 'GroupCoordinator' has not been declared
```

**Fix**:
```cpp
#include "../Advanced/GroupCoordinator.h"
```

Or add namespace:
```cpp
Advanced::GroupCoordinator* coord = ...
```

---

### 3. Missing TacticalCoordinator

**Error**:
```
error: 'TacticalCoordinator' was not declared
```

**Fix**:
```cpp
#include "../Advanced/TacticalCoordinator.h"
```

---

### 4. urand not found

**Error**:
```
error: 'urand' was not declared in this scope
```

**Fix**:
```cpp
#include "Random.h"
```

---

### 5. ObjectAccessor errors

**Error**:
```
error: 'ObjectAccessor' has not been declared
```

**Fix**:
```cpp
#include "ObjectAccessor.h"
```

---

### 6. Undefined reference (linker error)

**Error**:
```
undefined reference to `Playerbot::UnifiedLootManager::HandleMasterLoot(...)`
```

**Cause**: Method declared in .h but not implemented in .cpp

**Fix**: Implement the method in the .cpp file

---

### 7. Ambiguous reference

**Error**:
```
error: reference to 'LootRoll' is ambiguous
```

**Fix**: Use fully qualified name:
```cpp
Playerbot::LootRoll roll;
```

---

## 📊 Build Output Explanation

### Successful Build:

```
[INFO] ============================================
[INFO] Step 1: Checking build dependencies...
[INFO] ============================================
[SUCCESS] All dependencies found!
[INFO] CMake version: cmake version 3.28.3

[INFO] ============================================
[INFO] Step 2: Configuring CMake...
[INFO] ============================================
[INFO] Running CMake configuration...
[SUCCESS] CMake configuration complete!

[INFO] ============================================
[INFO] Step 4: Starting incremental compilation...
[INFO] ============================================
[INFO] Using 4 cores for parallel build
[INFO] Building game library with PlayerBot module...
[SUCCESS] Build completed successfully!

[INFO] ============================================
[INFO] Step 5: Analyzing build results...
[INFO] ============================================
[INFO] Compilation statistics:
[INFO]   - Errors: 0
[INFO]   - Warnings: 23
[SUCCESS] ============================================
[SUCCESS] BUILD SUCCESSFUL!
[SUCCESS] ============================================
```

### Failed Build:

```
[ERROR] ============================================
[ERROR] BUILD FAILED - Error Summary:
[ERROR] ============================================

[INFO] First 20 compilation errors:
error: 'GetBotAI' was not declared in this scope
error: 'GroupCoordinator' has not been declared
error: 'urand' was not declared in this scope
...

[INFO] Full error log saved to: /home/user/TrinityCore/build-playerbot/build.log
[INFO] To view full errors: cat /home/user/TrinityCore/build-playerbot/build.log | grep -A 3 'error:'
```

---

## 🎓 Advanced Usage

### View compile commands (for IDE integration):

```bash
cat build-playerbot/compile_commands.json | jq '.[0]'
```

### Rebuild from scratch:

```bash
rm -rf build-playerbot/
./build-playerbot.sh
```

### Check specific error in detail:

```bash
cat build-playerbot/build.log | grep -A 10 "UnifiedLootManager.cpp"
```

### Count errors per file:

```bash
grep "error:" build-playerbot/build.log | \
    grep -oP '/home/user/TrinityCore/[^:]+' | \
    sort | uniq -c | sort -rn
```

---

## 💡 Tips for Claude Code Web

### 1. Use syntax checks during development

Don't wait for full builds - use `check-playerbot-syntax.sh` frequently:

```bash
# After editing a file
./check-playerbot-syntax.sh src/modules/Playerbot/Social/UnifiedLootManager.cpp
```

### 2. Fix errors in batches

Use `fix-playerbot-errors.sh` to identify all instances of the same error type and fix them together.

### 3. Test incremental changes

Build after each logical change rather than making many changes at once:

```bash
# Make one change
# Quick syntax check
./check-playerbot-syntax.sh recent
# Full build if syntax OK
./build-playerbot.sh
```

### 4. Monitor warnings

Even if build succeeds, review warnings:

```bash
cat build-playerbot/build.log | grep "warning:" | head -20
```

### 5. Use grep for specific errors

```bash
# Find all "undefined reference" errors
grep "undefined reference" build-playerbot/build.log

# Find errors in specific file
grep "UnifiedLootManager" build-playerbot/build.log | grep "error:"
```

---

## 📝 Build System Internals

### CMake Configuration

Location: `build-playerbot/`

Key CMake variables:
- `CMAKE_BUILD_TYPE=Debug` - Debug symbols enabled
- `CMAKE_CXX_STANDARD=20` - C++20 standard
- `BUILD_PLAYERBOT=1` - PlayerBot module enabled
- `TOOLS=0` - Skip tool compilation
- `SCRIPTS=1` - Include script modules
- `WITH_WARNINGS=1` - Enable all warnings

### Compilation Database

Generated at: `build-playerbot/compile_commands.json`

Used by:
- IDEs (VSCode, CLion)
- Linters (clang-tidy)
- Static analyzers

### Parallel Builds

Default: Uses all CPU cores (`nproc`)

Override:
```bash
CORES=2 ./build-playerbot.sh
```

---

## 🔧 Troubleshooting

### Script won't run

```bash
chmod +x build-playerbot.sh check-playerbot-syntax.sh fix-playerbot-errors.sh
```

### CMake cache issues

```bash
rm -rf build-playerbot/CMakeCache.txt
./build-playerbot.sh
```

### Missing dependencies

```bash
# Check what's missing
./build-playerbot.sh

# Install (if needed, may require sudo)
sudo apt-get install cmake g++ make libboost-dev libssl-dev libreadline-dev
```

### Build hangs

- Kill process: `Ctrl+C`
- Check system resources
- Reduce parallel jobs: Edit `CORES` in script

---

## 📖 Related Documentation

- `PHASE7_GROUP_OPERATIONS_COMPLETE.md` - Phase 7 implementation details
- `GROUP_OPERATIONS_REVISED.md` - Coordinator architecture
- `LEGACY_CALL_MIGRATION_COMPLETE.md` - Migration documentation

---

*Last Updated: 2025-01-19*
*For use with Claude Code Web iterative development*