This guide covers installing mod-playerbots on a clean setup or migrating an existing AzerothCore installation. Supported platforms are Ubuntu, Windows, and macOS.

Important: mod-playerbots requires a custom fork of AzerothCore — the standard AzerothCore repository will not work. This is the single most common installation mistake. See Requirements below.

• Requirements
• Clean Installation (From Source)
  • 1. Clone the Repositories
  • 2. Follow the AzerothCore Installation Guide
  • 3. Import Playerbots SQL Files
  • 4. Configure Playerbots
  • 5. Start the Server
• Migrating From an Existing AzerothCore Installation
• Docker Installation
• Adding Other Modules
• Updating Your Installation
• Next Steps

You must use the Playerbots fork of AzerothCore. The standard azerothcore-wotlk repository will not work — you will get hundreds of compilation errors if you try to build mod-playerbots against the standard core.

The correct repository is:

https://github.com/mod-playerbots/azerothcore-wotlk (branch: Playerbot)

Why a fork? mod-playerbots requires modifications to the AzerothCore base code that cannot be implemented as a standard drop-in module. The fork includes these core changes and is regularly updated from upstream AzerothCore.

Boost 1.87+ is known to be incompatible with some AzerothCore builds. Use Boost 1.78–1.83 for best results.

git clone https://github.com/mod-playerbots/azerothcore-wotlk.git --branch=Playerbot
cd azerothcore-wotlk/modules
git clone https://github.com/mod-playerbots/mod-playerbots.git --branch=master

This gives you the correct AzerothCore fork with the mod-playerbots module inside the modules/ directory.

From this point, follow the standard AzerothCore Installation Guide for your platform. The guide covers:

• Requirements (per platform: Windows, Linux, macOS)
• Core Installation (per platform: Windows, Linux, macOS)
• Server Setup
• Database Installation
• Networking
• Final Server Steps
• Client Setup

Follow all steps using the Playerbots fork you cloned in Step 1 (not the standard AzerothCore repo). The build process is identical — the only difference is the source repository.

Compiler warnings: The build will produce many "unused parameter" and other warnings. These are cosmetic and do not affect functionality. To suppress them and speed up recompilation, add -DCMAKE_CXX_FLAGS="-w" or -DWITH_WARNINGS=0 to your cmake command.

Windows — Visual Studio memory: If Visual Studio runs out of memory during compilation, go to Tools > Options > Projects and Solutions > Build and Run and set "maximum number of parallel project builds" to 4.

DBC language: Use enUS DBC files on the server side. The bot spell system relies on enUS spell names. Your game client language can be anything — only the server-side DBC files matter.

The playerbots module uses its own database (acore_playerbots) in addition to the standard AzerothCore databases. After completing the AzerothCore database setup, create the playerbots database and grant permissions:

CREATE DATABASE IF NOT EXISTS acore_playerbots;
GRANT ALL PRIVILEGES ON acore_playerbots.* TO 'acore'@'localhost';
FLUSH PRIVILEGES;

The server's auto-updater will populate most tables on first run. However, playerbots SQL files may need to be imported manually if the auto-updater does not pick them up:

# From the azerothcore-wotlk directory
mysql -u acore -p acore_characters < modules/mod-playerbots/sql/characters/base/playerbots_characters.sql
mysql -u acore -p acore_world < modules/mod-playerbots/sql/world/base/playerbots_world.sql

Check: If you see errors like Table 'playerbots_random_bots' doesn't exist or Unknown database 'acore_playerbots' when starting the server, ensure the database was created and the SQL files were imported as shown above.

After building and installing, a playerbots.conf.dist file will be in your server's config directory (under etc/modules/ or configs/modules/ depending on platform).

1. Copy the dist file to create your config:

   cp playerbots.conf.dist playerbots.conf

2. Edit playerbots.conf — key settings to get started:

Critical: Always edit the .conf file in your server's install/config directory, not the .conf.dist file in the module source folder. Changes to .conf.dist or to files in the source modules/ directory have no effect on the running server. Both the .conf.dist and .conf files must be present for the module to work.

3. Increase map update threads in worldserver.conf. This is the single most impactful performance setting for playerbots:

   MapUpdate.Threads = 4
   

   Set this to 4–6 for most systems (roughly number of CPU cores minus 2). AzerothCore performance is heavily dependent on single-core performance, and you are unlikely to see any benefit from using more than 8 threads. Setting this to 12, 16, or higher does not improve performance — it can actually increase overhead.

4. Tune MySQL for playerbots. The default MySQL configuration is not adequate for use with playerbots and will lead to increased disk activity and decreased performance. Key settings to add to your MySQL config (my.cnf or my.ini):

   [mysqld]
   skip-log-bin                    # Disables binary logging — reduces disk writes by 75-90%. Safe for single-server setups that don't need replication.
   innodb_buffer_pool_size = 4G    # Set to ~50% of total RAM
   innodb_io_capacity = 500
   innodb_io_capacity_max = 2500
   transaction_isolation = READ-COMMITTED

   See the Playerbot Configuration wiki page for full MySQL tuning recommendations, bot activity profiles, hardware requirements, and detailed worldserver.conf / playerbots.conf settings.

Start the auth server and world server as described in the AzerothCore Final Server Steps.

On first start, the server will create bot accounts and begin logging in bots. This may take several minutes. You will see bot login messages in the console — this is normal.

If you already have a working AzerothCore server and want to add mod-playerbots, you cannot simply drop the module into your existing installation. The playerbots fork includes core modifications that are not present in standard AzerothCore.

1. Back up your existing databases:

   mysqldump -u acore -p acore_auth > auth_backup.sql
   mysqldump -u acore -p acore_characters > characters_backup.sql

   Tip: If you only need to back up specific characters rather than the entire database, you can use the .pdump write and .pdump load commands in-game. For example, .pdump write dump.sql <character_name> exports a single character, and .pdump load dump.sql <account_name> imports it. This is a quick option if you don't need a full database backup.

2. Switch your AzerothCore repository to the Playerbots fork. From your existing azerothcore-wotlk directory, change the remote URL and pull the Playerbot branch:

   cd azerothcore-wotlk
   git remote set-url origin https://github.com/mod-playerbots/azerothcore-wotlk.git
   git fetch origin
   git checkout Playerbot

3. Clone the playerbots module into the modules/ directory:

   cd modules
   git clone https://github.com/mod-playerbots/mod-playerbots.git --branch=master
   cd ..

4. Rebuild the server following the AzerothCore Installation Guide for your platform. Since the source has changed, a full rebuild is recommended (delete your build/ directory and re-run cmake).

5. Create the playerbots database and grant permissions:

   CREATE DATABASE IF NOT EXISTS acore_playerbots;
   GRANT ALL PRIVILEGES ON acore_playerbots.* TO 'acore'@'localhost';
   FLUSH PRIVILEGES;

6. Import playerbots SQL files if the auto-updater doesn't handle them:

   mysql -u acore -p acore_characters < modules/mod-playerbots/sql/characters/base/playerbots_characters.sql
   mysql -u acore -p acore_world < modules/mod-playerbots/sql/world/base/playerbots_world.sql

7. Update your configuration files. New .conf.dist files may contain additional settings after the rebuild. Compare them with your existing .conf files and merge any new entries. Then follow Step 4: Configure Playerbots above.

Note: Your existing extracted data (maps, vmaps, mmaps, dbc) and database connection settings in worldserver.conf can be kept as-is. The auto-updater will apply any necessary schema changes on first start.

Docker installations have with limited support. Previous Docker experience is recommended.

1. Clone the repositories:

   git clone https://github.com/mod-playerbots/azerothcore-wotlk.git --branch=Playerbot
   cd azerothcore-wotlk/modules
   git clone https://github.com/mod-playerbots/mod-playerbots.git --branch=master
   cd ..

2. Create docker-compose.override.yml in the azerothcore-wotlk root:

   services:
     ac-worldserver:
       volumes:
         - ./modules:/azerothcore/modules:ro

3. Set environment variables for configuration (optional but recommended):

   services:
     ac-worldserver:
       environment:
         AC_AI_PLAYERBOT_RANDOM_BOT_AUTOLOGIN: "1"
         AC_AI_PLAYERBOT_MIN_RANDOM_BOTS: "50"
         AC_AI_PLAYERBOT_MAX_RANDOM_BOTS: "200"
       volumes:
         - ./modules:/azerothcore/modules:ro

   Config settings are converted to environment variables by uppercasing, replacing . with _, and prefixing with AC_. For example: AiPlayerbot.RandomBotAutologin = 1 becomes AC_AI_PLAYERBOT_RANDOM_BOT_AUTOLOGIN: "1".

4. Set up the .env file (recommended):

   cp conf/dist/env.docker .env

   Edit .env to set the database password and Docker user/group if needed. Permissions issues are the most common cause of Docker installation problems.

5. Handle SQL imports for the module. The Docker db-import container may not automatically import module SQL files. If you encounter Unknown database 'acore_playerbots' or missing table errors:

   # Copy module SQL files to the custom SQL import directories
   cp modules/mod-playerbots/sql/characters/base/*.sql data/sql/custom/db_characters/
   cp modules/mod-playerbots/sql/world/base/*.sql data/sql/custom/db_world/

6. Build and run:

   docker compose up -d --build

For more information, see the AzerothCore Install With Docker page.

When using third-party modules alongside mod-playerbots, keep in mind:

• The playerbots AzerothCore fork may lag behind the latest upstream AzerothCore. Modules that target the very latest AC version may fail to compile. In this case, find an older commit/release of the module that is compatible.

Clone additional modules into the modules/ directory and rebuild:

To update both the core and the module:

# Update the core
cd azerothcore-wotlk
git pull

# Update the module
cd modules/mod-playerbots
git pull

# Update any other modules
cd ../mod-other-module
git pull

# Rebuild
cd ../../build
cmake ..
make -j $(nproc)
make install

Note: If you are only pulling updates (no new cmake options or module additions), you can skip the cmake .. step and just run make -j $(nproc) && make install. Re-running cmake is only necessary when you change build options, add/remove modules, or do a fresh build.

Important: Always update both the core and the module together. Running a newer module against an older core (or vice versa) can cause compilation errors or runtime crashes.