veitR/mod-playerbots
1
0
Fork 0
mirror of https://github.com/liyunfan1223/mod-playerbots.git synced 2026-06-20 15:39:25 +02:00
Code Issues Packages Projects Releases Wiki Activity
Page: Installation Guide
Pages
Home Installation Guide Playerbot Addons and Sub‐Modules Playerbot Commands Playerbot Configuration Playerbot Macro Collection Playerbot Queries Playerbot Raid Completion Status Playerbot Raid Strategy Guide Troubleshooting
Clone
5
Installation Guide
Keleborn edited this page 2026-06-09 11:23:45 -07:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Installation Guide

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.

Table of Contents

Requirements

The Playerbots AzerothCore Fork

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 Compatibility (Windows)

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

Clean Installation (From Source)

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

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

2. Follow the AzerothCore Installation Guide

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

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.

Playerbots-Specific Build Notes

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.

3. Playerbots Database Setup

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:

bash
# From the azerothcore-wotlk directory

# 1. Import the playerbots additions to acore_characters
for f in modules/mod-playerbots/data/sql/characters/base/*.sql; do
  mysql -u acore -p acore_characters < "$f"
done

# 2. Import the playerbots additions to acore_world
for f in modules/mod-playerbots/data/sql/world/base/*.sql; do
  mysql -u acore -p acore_world < "$f"
done

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.

4. Configure Playerbots

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.

  1. 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.

  2. 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.

5. Start the Server

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.

Migrating From an Existing AzerothCore Installation

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.

Migration Steps

  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:

bash
# From the azerothcore-wotlk directory

# 1. Import the playerbots additions to acore_characters
for f in modules/mod-playerbots/data/sql/characters/base/*.sql; do
  mysql -u acore -p acore_characters < "$f"
done

# 2. Import the playerbots additions to acore_world
for f in modules/mod-playerbots/data/sql/world/base/*.sql; do
  mysql -u acore -p acore_world < "$f"
done
  1. 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 Installation

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

Steps

  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.

Adding Other Modules

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:

Updating Your Installation

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.