Files

T

2026-01-20 21:33:16 -03:00

34 KiB

Raw Blame History

TrinityCore Playerbot User Guide

Version: WoW 11.2 Compatible Target Audience: Server administrators, developers, and power users Module: Optional TrinityCore enhancement

Introduction
Getting Started
Configuration Guide
Chat Commands
Common Use Cases
Troubleshooting
Advanced Topics
FAQ

Introduction

What is TrinityCore Playerbot?

TrinityCore Playerbot is an optional module that adds AI-controlled player characters (bots) to your World of Warcraft server. It enables:

Single-Player Experience: Play the full MMORPG without other human players
Dungeon Practice: Run dungeons with AI-controlled party members
Testing: Test raid mechanics, quests, and game systems
Population Enhancement: Add life to low-population servers

Key Features

5000 Bot Capacity: Designed to support up to 5000 concurrent bots
13 Classes Supported: All WoW classes with specialized AI
Smart Following: Bots automatically follow group leaders
Combat Assistance: Bots engage in combat when group members fight
Quest Automation: Bots can pickup and complete quests (when idle)
Group Coordination: Proper role-based positioning and targeting
Performance Optimized: <10% server impact with proper configuration

System Requirements

Minimum:

TrinityCore 11.2+ (master branch)
8 GB RAM (for ~100 bots)
4 CPU cores
MySQL 9.4+

Recommended (500+ bots):

32 GB RAM
8+ CPU cores
SSD storage
MySQL 9.4+ with optimized configuration

Getting Started

Step 1: Compilation

The Playerbot module is optional and disabled by default. To enable it:

Windows (Visual Studio)

# Navigate to build directory
cd C:\TrinityCore\build

# Generate with Playerbot enabled
cmake .. -DBUILD_PLAYERBOT=1

# Open solution and build
start TrinityCore.sln
# Build → Build Solution (F7)

Linux/Mac (Make)

# Navigate to build directory
cd ~/TrinityCore/build

# Generate with Playerbot enabled
cmake .. -DBUILD_PLAYERBOT=1

# Compile
make -j$(nproc)

# Install
make install

Verification:

# Check if module compiled
ls -la server/game/libplayerbot.a  # Linux/Mac
dir server\game\playerbot.lib      # Windows

Step 2: Configuration File

The Playerbot module uses a separate configuration file from worldserver.conf.

Create Configuration File

Locate Template:
```
etc/playerbots.conf.dist
```

Copy to Active Config:

# Linux/Mac
cp etc/playerbots.conf.dist etc/playerbots.conf

# Windows
copy etc\playerbots.conf.dist etc\playerbots.conf

Edit Configuration: Open etc/playerbots.conf in your preferred text editor.

Essential Settings

###################################################################################################
# ESSENTIAL SETTINGS - Must Configure
###################################################################################################

# Enable the playerbot system
Playerbot.Enable = 1

# Maximum bots allowed globally (adjust based on RAM)
# Guideline: 100 bots ≈ 1 GB RAM
Playerbot.GlobalMaxBots = 100

# Maximum bots per player account
Playerbot.MaxBotsPerAccount = 5

# Bot-to-player ratio (2.0 = 2 bots per real player)
# Set to 0 to disable dynamic spawning
Playerbot.BotToPlayerRatio = 2.0

# Enable dynamic spawning (auto-spawn based on player count)
Playerbot.EnableDynamicSpawning = 1

Step 3: Database Setup

The Playerbot module can use either:

Existing characters database (recommended)
Separate playerbot database (advanced)

Option 1: Use Existing Characters Database (Recommended)

No additional setup required. Bots will be stored in the standard characters database.

Option 2: Create Separate Database (Advanced)

-- Create database
CREATE DATABASE `playerbot_characters` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- Grant permissions
GRANT ALL PRIVILEGES ON `playerbot_characters`.* TO 'trinity'@'localhost';
FLUSH PRIVILEGES;

Update Configuration:

Playerbot.Database.Name = "playerbot_characters"

Step 4: First Launch

Start worldserver:
```
./worldserver
```

Check Logs: Look for initialization messages:

[INFO] PlayerbotConfig: Successfully loaded from ./etc/playerbots.conf
[INFO] BotSpawner initialized - Max Total: 100, Max Per Zone: 10, Max Per Map: 50
[INFO] Playerbot: Module loaded successfully

Login to Game: Use your GM account (security level 3+)
Verify Module: Type in-game:
```
.bot
```
You should see available bot commands.

Configuration Guide

Core Configuration

###################################################################################################
# CORE SETTINGS
###################################################################################################

# Enable/disable entire playerbot system
# Values: 0 (disabled), 1 (enabled)
# Default: 0
Playerbot.Enable = 1

# Global maximum bots (server-wide)
# Higher values require more RAM
# Guideline: 100 bots ≈ 1 GB RAM, 1000 bots ≈ 10 GB RAM
# Default: 500
# Recommended: 100 (low-end), 500 (mid-range), 1000 (high-end)
Playerbot.GlobalMaxBots = 500

# Maximum bots per player account
# Default: 10
# Recommended: 5-10 for normal play, 50+ for testing
Playerbot.MaxBotsPerAccount = 10

Performance Tuning

###################################################################################################
# PERFORMANCE SETTINGS
###################################################################################################

# Bot update interval (milliseconds)
# Lower = more responsive, higher = better performance
# Range: 50-1000 ms
# Default: 100
# Recommended: 100 (smooth), 200 (balanced), 500 (performance)
Playerbot.UpdateInterval = 100

# AI decision time limit (milliseconds)
# Maximum time AI can spend per decision
# Prevents lag from complex AI calculations
# Default: 50
# Recommended: 50 (normal), 100 (complex AI)
Playerbot.AIDecisionTimeLimit = 50

# Spawn batch size (bots spawned per batch)
# Larger batches = faster spawning but brief lag spikes
# Default: 10
# Recommended: 5 (smooth), 10 (balanced), 20 (fast)
Playerbot.SpawnBatchSize = 10

# Delay between spawn batches (milliseconds)
# Higher values = smoother spawning
# Default: 100
# Recommended: 100-500
Playerbot.SpawnBatchDelay = 100

Dynamic Spawning

###################################################################################################
# DYNAMIC SPAWNING
###################################################################################################

# Enable dynamic spawning (auto-spawn based on players)
# Values: 0 (disabled), 1 (enabled)
# Default: 1
Playerbot.EnableDynamicSpawning = 1

# Bot-to-player ratio
# How many bots to spawn per real player
# 0.0 = no automatic spawning
# 2.0 = 2 bots per player (recommended)
# 5.0 = 5 bots per player (crowded)
# Default: 2.0
Playerbot.BotToPlayerRatio = 2.0

# Minimum bots per zone (even with 0 players)
# Keeps zones populated for testing
# Default: 10
Playerbot.MinimumBotsPerZone = 5

# Maximum bots per zone
# Prevents overcrowding
# Default: 50
Playerbot.MaxBotsPerZone = 50

# Maximum bots per map
# Global limit per continent/instance
# Default: 200
Playerbot.MaxBotsPerMap = 200

Database Configuration

###################################################################################################
# DATABASE SETTINGS
###################################################################################################

# Database connection timeout (seconds)
# Default: 30
Playerbot.Database.Timeout = 30

# Enable connection pooling (recommended)
# Improves performance for many bots
# Default: 1
Playerbot.Database.EnablePooling = 1

# Maximum database connections for bot operations
# Higher = better performance with many bots
# Too high = MySQL connection limit issues
# Default: 10
# Recommended: 5 (< 100 bots), 10 (100-500 bots), 20 (500+ bots)
Playerbot.Database.MaxConnections = 10

Logging Configuration

###################################################################################################
# LOGGING SETTINGS
###################################################################################################

# Log level (higher = more detailed)
# 0 = Disabled
# 1 = Fatal errors only
# 2 = Errors
# 3 = Warnings
# 4 = Info (recommended for normal use)
# 5 = Debug (for troubleshooting)
# 6 = Trace (very detailed, huge logs)
# Default: 4
Playerbot.Log.Level = 4

# Log file path (relative to worldserver binary)
# Default: "Playerbot.log"
Playerbot.Log.File = "Playerbot.log"

# Enable timestamp in logs
# Default: 1
Playerbot.Log.Timestamp = 1

# Separate log files by category
# Creates files like Playerbot_AI.log, Playerbot_Combat.log
# Useful for debugging specific systems
# Default: 0
Playerbot.Log.SeparateCategories = 0

Security Settings

###################################################################################################
# SECURITY SETTINGS
###################################################################################################

# Prevent direct login to bot accounts
# Bots can only be controlled via commands
# Recommended: 1
# Default: 1
Playerbot.Security.PreventBotLogin = 1

# Log all bot actions for audit trail
# Creates large logs, use only for debugging
# Default: 0
Playerbot.Security.LogBotActions = 0

# Maximum gold a bot can carry (prevents exploits)
# Default: 1000 (in copper, = 10 gold)
# 0 = no limit
Playerbot.Security.MaxGoldPerBot = 100000

AI Behavior

###################################################################################################
# AI BEHAVIOR SETTINGS
###################################################################################################

# Follow distance (yards)
# How far behind leader bots should follow
# Default: 5.0
Playerbot.AI.FollowDistance = 5.0

# Combat assist range (yards)
# Distance at which bots assist group members in combat
# Default: 30.0
Playerbot.AI.CombatAssistRange = 30.0

# Auto-loot enabled
# Bots automatically loot corpses
# Default: 1
Playerbot.AI.AutoLoot = 1

# Auto-accept group invites
# Bots automatically accept group invitations
# Default: 1
Playerbot.AI.AutoAcceptGroupInvites = 1

# Quest automation enabled (when idle)
# Bots pickup and complete quests when not in combat/following
# Default: 0 (disabled for now - experimental)
Playerbot.AI.EnableQuestAutomation = 0

Chat Commands

Command Prefix

All bot commands start with .bot or .pbot:

.bot <subcommand> [arguments]
.pbot <subcommand> [arguments]

Basic Commands

`.bot spawn <class> <race> <gender> <name>`

Creates a new bot character and spawns it.

Parameters:

class - Character class name (warrior, paladin, hunter, rogue, priest, shaman, mage, warlock, druid, deathknight, monk, demonhunter, evoker)
race - Race name (human, orc, dwarf, nightelf, undead, tauren, gnome, troll, bloodelf, draenei, worgen, goblin, pandaren, etc.)
gender - Gender (male, female)
name - Character name (must be unique)

Examples:

.bot spawn warrior human male BotWarrior
.bot spawn priest nightelf female HealBot
.bot spawn mage bloodelf female Fireblast
.bot spawn paladin dwarf male HolyTank

What Happens:

Creates new character in database
Spawns character in starting zone
Bot immediately enters world
Character appears in .bot list

`.bot add <characterName>`

Adds an existing character as a bot.

Parameters:

characterName - Name of existing character on your account

Example:

.bot add MyExistingMage

Requirements:

Character must exist in database
Character must belong to your account
Character must not already be logged in

Use Case: Convert your alt characters to bots

`.bot remove <name|all>`

Removes one or all bots.

Parameters:

name - Specific bot name
all - Remove all your bots

Examples:

.bot remove BotWarrior    # Remove specific bot
.bot remove all           # Remove all your bots

What Happens:

Bot logs out gracefully
Removes from active bot list
Character remains in database (can re-add later)

`.bot list`

Lists all your active bots.

Output:

Your active bots (3):
  - BotWarrior (Level 80 Warrior)
  - HealBot (Level 70 Priest)
  - Fireblast (Level 60 Mage)

Shows:

Bot name
Level
Class

`.bot info <name>`

Displays detailed bot information.

Example:

.bot info BotWarrior

Output:

Bot Information: BotWarrior
  Class: Warrior
  Race: Human
  Level: 80
  Specialization: Arms
  Health: 45000 / 50000 (90%)
  Resource: 80 / 100 Rage
  AI State: FOLLOWING
  Group: [GroupName] (Tank role)
  Current Action: Following [YourCharacter]
  Active Strategies: follow, group_combat
  Performance:
    - Average Update Time: 0.8ms
    - Actions Executed: 1523
    - Total Updates: 15234

`.bot stats`

Shows global bot statistics.

Output:

Playerbot System Statistics:
  Total Spawned: 150
  Currently Active: 45
  Peak Concurrent: 52
  Failed Spawns: 2
  Success Rate: 98.7%
  Average Spawn Time: 125ms
  Total Despawned: 105

Performance Metrics:
  Average Update Time: 1.2ms
  Total Memory Usage: ~450MB
  Database Queries/sec: 42

Control Commands

`.bot follow`

Makes all your bots follow you.

Example:

.bot follow

Effect:

All your bots activate "follow" strategy
Bots move to follow distance behind you
Bots maintain formation based on role

Note: Bots automatically follow when invited to your group

`.bot stay`

Makes all your bots stop following.

Example:

.bot stay

Effect:

Deactivates "follow" strategy
Bots stop moving
Bots stay at current location

`.bot attack`

Makes all your bots attack your current target.

Example:

.bot attack

Requirements:

You must have a target selected
Target must be attackable

Effect:

Bots engage your target
Uses appropriate class rotation
Continues attacking until target dies or combat ends

`.bot defend`

Makes bots defend you from attackers.

Example:

.bot defend

Effect:

Bots attack anything attacking you
Prioritizes threats to you
Stays near you for protection

`.bot heal`

Makes healer bots focus on healing.

Example:

.bot heal

Effect:

Healer bots prioritize healing
Focus on lowest health targets
Uses efficient healing rotation

Note: Only affects healer classes (Priest, Paladin, Shaman, Druid, Monk, Evoker)

Debug Commands

`.bot debug <name> <on|off>`

Enables detailed logging for specific bot.

Example:

.bot debug BotWarrior on   # Enable debug
.bot debug BotWarrior off  # Disable debug

Output Location: Playerbot.log with DEBUG level entries

Use Case: Troubleshooting AI behavior, combat issues, movement problems

Common Use Cases

Solo Dungeon Practice

Goal: Practice dungeon mechanics with AI party.

Setup:

Spawn a balanced group:

.bot spawn warrior human male Tank         # Tank
.bot spawn priest nightelf female Healer   # Healer
.bot spawn mage human female DPS1          # DPS
.bot spawn rogue human male DPS2           # DPS

Invite to group:
- Use standard group invitation (/invite BotName)
- Bots auto-accept and start following
Enter dungeon:
- Queue for dungeon or enter manually
- Bots follow and engage in combat when you fight

Tips:

Ensure "follow" strategy is active (.bot follow)
Pull carefully - bots will assist but may not kite
Healer bots prioritize lowest health ally
Tank bots use threat abilities when spec supports it

Testing Raid Mechanics

Goal: Test raid encounter mechanics with bots.

Setup:

Spawn raid-sized group:

# Use a script to spawn 10-25 bots
for i in {1..10}; do
    .bot spawn warrior human male Tank$i
    .bot spawn priest human female Healer$i
    .bot spawn mage human male DPS$i
done

Form raid:
- Create raid group
- Invite all bots
- Assign roles in raid frames
Enter raid instance:
- Bots follow raid leader
- Engage when raid leader attacks

Limitations:

Bots may not handle complex mechanics (don't move from fire, etc.)
Best for testing basic encounter flow
Advanced mechanics require manual control

Leveling with Bots

Goal: Level with AI companions.

Setup:

Spawn appropriate level bots:

.bot spawn hunter human male BowBot
.bot spawn priest human female HealyBot

Invite to group:
- Standard group invitation
- Bots follow and assist in combat
Quest together:
- Bots help kill quest mobs
- Share quest completion credit
- Healers keep you alive

Tips:

Bots scale to nearby player levels (if enabled in config)
Bring a healer bot for safety
Bots automatically loot if configured

Populating Low-Pop Server

Goal: Add life to empty zones.

Configuration:

# In playerbots.conf
Playerbot.EnableDynamicSpawning = 1
Playerbot.BotToPlayerRatio = 5.0
Playerbot.MinimumBotsPerZone = 20
Playerbot.GlobalMaxBots = 500

Effect:

Bots spawn automatically in popular zones
When players login, more bots spawn (ratio 5:1)
Zones feel populated even with few players
Bots despawn when players logout to conserve resources

Management:

Monitor via .bot stats
Adjust ratio based on performance
Use lower ratios on weaker servers

Testing New Content

Goal: Test quest chains, dungeons, raids with bots.

Setup:

Create test characters:

.bot spawn warrior human male TestTank
.bot spawn priest human female TestHeal

Set to max level (GM command):

.character level TestTank 80
.character level TestHeal 80

Gear them:
```
.additem [item_id]
```
Test content:
- Invite to group
- Run through quest chains
- Enter dungeons/raids
- Observe bot behavior

Benefits:

Fast iteration on encounter design
No need for human testers
Consistent testing environment

Troubleshooting

Bot Not Spawning

Symptoms:

Command completes but bot doesn't appear
Error message: "Failed to spawn bot"

Diagnosis:

# Check logs
tail -f Playerbot.log

# Check active bots
.bot stats

Common Causes:

Global bot limit reached

# In playerbots.conf
Playerbot.GlobalMaxBots = 500  # Increase this

Account bot limit reached

Playerbot.MaxBotsPerAccount = 10  # Increase this

Database connection failure
- Check Playerbot.log for database errors
- Verify MySQL is running
- Check database credentials in worldserver.conf
Invalid character data
- Ensure race/class combination is valid
- Check name doesn't already exist
- Verify character creation limits

Solutions:

# Increase limits
vi etc/playerbots.conf
# Edit GlobalMaxBots and MaxBotsPerAccount

# Restart worldserver
killall worldserver
./worldserver

# Verify database
mysql -u trinity -p
> USE characters;
> SELECT COUNT(*) FROM characters WHERE account = [your_account_id];

Bots Not Following

Symptoms:

Bots invited to group but don't move
Bots stay in one place
Message: "Bot is following" but no movement

Diagnosis:

.bot info BotName

Check "Active Strategies" - should include "follow"

Common Causes:

Follow strategy not activated
```
.bot follow  # Manually activate
```
Bot stuck in combat state
- Kill all nearby mobs
- Wait for combat to end
- Bot should resume following
Pathfinding failure
- Bot can't find path to you
- Teleport closer: .appear BotName
- Or teleport bot to you: .summon BotName
Group not properly formed
- Re-invite bot to group
- Check bot appears in group frames
- Verify group leader is set

Solutions:

# Force follow activation
.bot follow

# Summon bot if stuck
.summon BotName

# Re-invite to group
/invite BotName

# Check AI state
.bot info BotName
# AI State should be: FOLLOWING

Bots Not Attacking

Symptoms:

Bots follow but don't engage in combat
Bots stand idle while you fight

Diagnosis:

.bot info BotName

Check "Active Strategies" - should include "group_combat"

Common Causes:

Combat strategy not activated
- Happens if bot joined group before system was ready
- Solution: Re-invite bot or restart worldserver

Bot out of range

Check combat assist range in config

Playerbot.AI.CombatAssistRange = 30.0  # Increase if needed

No valid target
- Bot needs clear line of sight
- Remove obstacles between bot and enemy
Class-specific issues
- Mages may be out of mana
- Melee may be too far from target
- Healers prioritize healing over DPS

Solutions:

# Manually command attack
.bot attack

# Check combat range
vi etc/playerbots.conf
# Increase Playerbot.AI.CombatAssistRange

# Summon bot closer
.summon BotName

# Re-invite to refresh strategies
/invite BotName

Performance Issues / Lag

Symptoms:

Server lag with many bots
High CPU usage
Slow response times

Diagnosis:

# Check server stats
.server info

# Check bot stats
.bot stats

# Monitor CPU
top -p $(pgrep worldserver)

# Check memory
free -h

Common Causes:

Too many bots for hardware
- Reduce Playerbot.GlobalMaxBots
- Lower Playerbot.BotToPlayerRatio

Update interval too low

# In playerbots.conf
Playerbot.UpdateInterval = 100  # Increase to 200-500

Database bottleneck
- Increase connection pool size
- Optimize MySQL configuration
- Use SSD for database
Memory exhaustion
- Each bot uses ~10 MB
- 500 bots = ~5 GB minimum
- Check with free -h

Solutions:

Quick Fix (Reduce Load):

# In playerbots.conf
Playerbot.GlobalMaxBots = 50        # Reduce from 500
Playerbot.UpdateInterval = 200      # Increase from 100
Playerbot.SpawnBatchSize = 5        # Reduce from 10

Database Optimization:

-- In MySQL
SET GLOBAL max_connections = 200;
SET GLOBAL innodb_buffer_pool_size = 2G;
SET GLOBAL query_cache_size = 128M;

System Tuning:

# Increase file descriptors
ulimit -n 65536

# Use performance CPU governor
cpupower frequency-set -g performance

Monitoring:

# Watch resource usage
watch -n 1 'free -h && ps aux | grep worldserver | head -n 1'

Database Errors

Symptoms:

Errors in Playerbot.log
"Failed to execute query"
"Database connection timeout"

Diagnosis:

# Check Playerbot.log
tail -n 100 Playerbot.log | grep -i "error\|failed"

# Test MySQL connection
mysql -u trinity -p -h localhost

Common Errors:

"Too many connections"

-- In MySQL
SHOW VARIABLES LIKE 'max_connections';
SET GLOBAL max_connections = 500;

"Prepared statement failed"
- Outdated database schema
- Missing table indexes
- Corrupted prepared statements
Solution:
```
# Re-run database updates
mysql -u trinity -p world < sql/updates/world/*.sql
```

"Lock wait timeout exceeded"

Database deadlock
Too many concurrent queries

Solution:

# In playerbots.conf
Playerbot.Database.Timeout = 60  # Increase from 30
Playerbot.Database.MaxConnections = 20  # Increase pool

"Access denied"

Wrong database credentials
Missing permissions

Solution:

GRANT ALL PRIVILEGES ON characters.* TO 'trinity'@'localhost';
GRANT ALL PRIVILEGES ON world.* TO 'trinity'@'localhost';
FLUSH PRIVILEGES;

Compilation Errors

Symptoms:

Build fails with Playerbot-related errors
Linker errors mentioning Playerbot classes

Common Errors:

"BUILD_PLAYERBOT not defined"

# Solution: Add flag to cmake
cmake .. -DBUILD_PLAYERBOT=1

"Cannot find playerbots.conf"

Module compiled but config missing

# Copy config file
cp etc/playerbots.conf.dist etc/playerbots.conf

Linker errors (unresolved symbols)

Incomplete compilation

# Clean and rebuild
make clean
cmake .. -DBUILD_PLAYERBOT=1
make -j$(nproc)

CMake errors

CMake Error: The following variables are used but not set:
  BUILD_PLAYERBOT

Solution:

# Explicitly set
cmake .. -DBUILD_PLAYERBOT=ON

Advanced Topics

Creating Custom AI Strategies

For developers who want to extend bot behavior:

1. Create Strategy Class:

// src/modules/Playerbot/AI/Strategy/MyCustomStrategy.h
#include "Strategy.h"

namespace Playerbot {

class MyCustomStrategy : public Strategy {
public:
    std::string GetName() const override {
        return "my_custom";
    }

    bool IsActive(BotAI const* ai) const override {
        // Determine when strategy should be active
        return true;
    }

    void UpdateBehavior(BotAI* ai, uint32 diff) override {
        // Implement custom behavior
        Player* bot = ai->GetBot();
        // ... custom logic
    }
};

} // namespace Playerbot

2. Register Strategy:

// In BotAI.cpp or custom initializer
void InitializeCustomStrategies(BotAI* ai) {
    auto customStrategy = std::make_unique<MyCustomStrategy>();
    ai->AddStrategy(std::move(customStrategy));
    ai->ActivateStrategy("my_custom");
}

3. Use Strategy:

# In-game (if added to commands)
.bot strategy activate my_custom

Performance Profiling

Enable Detailed Logging:

# In playerbots.conf
Playerbot.Log.Level = 5  # Debug level
Playerbot.Performance.EnableMonitoring = 1

Analyze Performance:

// Access performance metrics
SpawnStats const& stats = sBotSpawner->GetStats();
TC_LOG_INFO("module.playerbot", "Performance Report:");
TC_LOG_INFO("module.playerbot", "  Average Update: {:.2f}ms", stats.GetAverageSpawnTime());
TC_LOG_INFO("module.playerbot", "  Peak Concurrent: {}", stats.peakConcurrent.load());

Monitor in Real-Time:

# Watch Playerbot.log for performance entries
tail -f Playerbot.log | grep "Performance\|Update Time"

Contributing to Playerbot

Development Workflow:

Fork Repository:

git clone https://github.com/YourUsername/TrinityCore.git
cd TrinityCore
git checkout playerbot-dev  # Development branch

Create Feature Branch:
```
git checkout -b feature/my-improvement
```
Make Changes:
- Edit files in src/modules/Playerbot/
- Follow existing code style
- Add comments and documentation

Test Changes:

# Rebuild
cmake .. -DBUILD_PLAYERBOT=1
make -j$(nproc)

# Test in-game
./worldserver
# ... test your changes

Submit Pull Request:

git add .
git commit -m "Add feature: improved bot targeting"
git push origin feature/my-improvement
# Create PR on GitHub

Code Style:

Follow TrinityCore C++ coding standards
Use namespace Playerbot
Add logging with TC_LOG_* macros
Include comprehensive error handling

MySQL Optimization for High Bot Counts

For 500+ bots, optimize MySQL:

1. Configuration (my.cnf or my.ini):

[mysqld]
# Connection limits
max_connections = 500

# Buffer pool (set to 50-70% of available RAM)
innodb_buffer_pool_size = 4G

# Query cache
query_cache_size = 256M
query_cache_limit = 2M

# Threads
thread_cache_size = 100

# Temporary tables
tmp_table_size = 128M
max_heap_table_size = 128M

# InnoDB settings
innodb_log_file_size = 512M
innodb_log_buffer_size = 64M
innodb_flush_log_at_trx_commit = 2  # Faster, slightly less safe

# Query optimization
join_buffer_size = 4M
sort_buffer_size = 4M

2. Index Optimization:

-- Add indexes for bot queries
ALTER TABLE characters
ADD INDEX idx_bot_account_online (account, online);

ALTER TABLE characters
ADD INDEX idx_bot_level_class (level, class);

-- Optimize tables periodically
OPTIMIZE TABLE characters;
OPTIMIZE TABLE item_instance;

3. Monitoring:

-- Check connection usage
SHOW STATUS LIKE 'Threads_connected';
SHOW STATUS LIKE 'Max_used_connections';

-- Check slow queries
SHOW VARIABLES LIKE 'slow_query_log';
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 1;  # Log queries > 1 second

FAQ

General Questions

Q: How many bots can I run on my server?

A: Depends on hardware:

Low-end (4 GB RAM, 2 cores): 50-100 bots
Mid-range (8 GB RAM, 4 cores): 200-500 bots
High-end (16+ GB RAM, 8+ cores): 500-1000 bots
Server-grade (32+ GB RAM, 16+ cores): 1000-5000 bots

Rule of thumb: 100 bots ≈ 1 GB RAM

Q: Can bots do quests automatically?

A: Partially. Bots can:

✅ Pick up quests (when idle)
✅ Kill quest mobs
✅ Turn in quests
❌ Navigate complex quest chains
❌ Use quest items properly
❌ Complete escort quests

Currently experimental. Enable with:

Playerbot.AI.EnableQuestAutomation = 1

Q: Do bots work in PvP/Battlegrounds?

A: Limited support:

✅ Can enter battlegrounds
✅ Will attack enemy players
✅ Follow group in BGs
❌ Don't understand objectives (flags, bases)
❌ Limited tactical awareness
❌ May not use PvP abilities optimally

Best for testing, not competitive PvP.

Q: Can I make money (gold) with bots?

A: Not recommended:

Bots can farm mobs (slowly)
Auction house automation is disabled by default
Exploiting bots for gold is against spirit of module
Security limits prevent excessive gold accumulation

Intended use: Enhancing gameplay, not gold farming.

Q: Will bots work with my custom scripts/modules?

A: Usually yes:

Bots use standard TrinityCore APIs
Compatible with most server modifications
May conflict with other AI systems
Test thoroughly before production use

Q: How do I update bots after server restart?

A: Bots persist in database:

-- Bots remain in characters table
SELECT name, class, level FROM characters WHERE account IN (
    SELECT account_id FROM playerbot_accounts
);

After restart:

Worldserver starts
Playerbot module initializes
Bots automatically log back in (if dynamic spawning enabled)
Or manually re-add: .bot add BotName

Technical Questions

Q: Are bots visible to other players?

A: Yes:

Bots appear as normal players
Other players can:
- See bots in world
- Target bots
- Trade with bots (if enabled)
- Invite bots to groups
- Communicate with bots (limited responses)

Q: Do bots use resources (bandwidth, CPU) like real players?

A: Partially:

CPU: Yes, ~0.1% per bot (AI calculations)
Memory: Yes, ~10 MB per bot (Player objects)
Bandwidth: No (socketless, no network packets sent)
Database: Yes (queries for character data, updates)

Bots are much lighter than real players (no network overhead).

Q: Can bots learn from player behavior?

A: Experimental:

Machine learning module exists
Pattern recognition for player movements
Adaptive difficulty based on player skill
Currently disabled by default

Enable with:

Playerbot.Experimental.BehaviorLearning = 1

Warning: Very CPU-intensive, not recommended for production.

Q: How do I backup bot data?

# Backup characters database (includes bots)
mysqldump -u trinity -p characters > characters_backup.sql

# Backup specific bot accounts
mysqldump -u trinity -p characters --where="account IN (SELECT account_id FROM playerbot_accounts)" > bots_backup.sql

# Restore
mysql -u trinity -p characters < characters_backup.sql

Q: Can I control individual bot abilities?

A: Not directly via commands (yet). But you can:

Modify AI scripts in src/modules/Playerbot/AI/ClassAI/
Create custom strategies (see Advanced Topics)
Use debug mode to see what abilities bots use
Disable certain abilities in class AI code

Q: Why do my bots keep dying?

A: Common reasons:

No healer in group - Add a healer bot
Pulling too many mobs - Bots have limited survival instincts
Undergeared - Equip bots with appropriate gear
Wrong spec - Check bot specialization matches role
Not using cooldowns - Some class AIs need tuning

Debug:

.bot info BotName  # Check health, buffs, spec
.bot debug BotName on  # Enable detailed combat logging

Getting Help

Official Channels

GitHub Issues: https://github.com/TrinityCore/TrinityCore/issues
Discord: TrinityCore Discord server (#playerbot-module channel)
Forum: TrinityCore forums (Module Development section)

Reporting Bugs

Include:

TrinityCore version/commit hash
Playerbot module version
Server specs (RAM, CPU, OS)
Number of bots when issue occurred
Relevant log excerpts from Playerbot.log
Steps to reproduce
Expected vs actual behavior

Example:

**Bug:** Bots not following after group invite

**Environment:**
- TrinityCore: 11.2.0 (commit ae80d8c)
- Playerbot: Latest (commit ae80d8c)
- Server: Ubuntu 22.04, 16 GB RAM, 8 cores
- Bots: 45 active

**Steps:**
1. Spawn bot: .bot spawn warrior human male TestBot
2. Invite to group: /invite TestBot
3. Bot accepts but doesn't move

**Logs:**
[2025-10-03 14:23:45] BotAI: OnGroupJoined() called for TestBot
[2025-10-03 14:23:45] Strategy "follow" activated
[2025-10-03 14:23:45] ERROR: LeaderFollowBehavior - No group leader found

**Expected:** Bot should follow me
**Actual:** Bot stands still

Conclusion

The TrinityCore Playerbot module provides a powerful way to enhance your World of Warcraft server experience with AI-controlled players. Whether you're running a solo server, testing content, or adding life to a low-population realm, the Playerbot system offers flexible, performant bot management.

Remember:

Start with low bot counts and scale up
Monitor performance regularly
Keep logs for troubleshooting
Report bugs to help improve the module
Have fun!

Happy Botting!

Document Version: 1.0 Last Updated: 2025-10-03 For: TrinityCore 11.2 + Playerbot Module

34 KiB Raw Blame History

TrinityCore Playerbot User Guide

Table of Contents

Introduction

What is TrinityCore Playerbot?

Key Features

System Requirements

Getting Started

Step 1: Compilation

Windows (Visual Studio)

Linux/Mac (Make)

Step 2: Configuration File

Create Configuration File

Essential Settings

Step 3: Database Setup

Option 1: Use Existing Characters Database (Recommended)

Option 2: Create Separate Database (Advanced)

Step 4: First Launch

Configuration Guide

Core Configuration

Performance Tuning

Dynamic Spawning

Database Configuration

Logging Configuration

Security Settings

AI Behavior

Chat Commands

Command Prefix

Basic Commands

.bot spawn <class> <race> <gender> <name>

.bot add <characterName>

.bot remove <name|all>

.bot list

.bot info <name>

.bot stats

Control Commands

.bot follow

.bot stay

.bot attack

.bot defend

.bot heal

Debug Commands

.bot debug <name> <on|off>

Common Use Cases

Solo Dungeon Practice

Testing Raid Mechanics

Leveling with Bots

Populating Low-Pop Server

Testing New Content

Troubleshooting

Bot Not Spawning

Bots Not Following

Bots Not Attacking

Performance Issues / Lag

Database Errors

Compilation Errors

Advanced Topics

Creating Custom AI Strategies

Performance Profiling

Contributing to Playerbot

MySQL Optimization for High Bot Counts

FAQ

General Questions

Technical Questions

Getting Help

Official Channels

Reporting Bugs

Conclusion

34 KiB

Raw Blame History

`.bot spawn <class> <race> <gender> <name>`

`.bot add <characterName>`

`.bot remove <name|all>`

`.bot list`

`.bot info <name>`

`.bot stats`

`.bot follow`

`.bot stay`

`.bot attack`

`.bot defend`

`.bot heal`

`.bot debug <name> <on|off>`