diff --git a/Installation-Guide.md b/Installation-Guide.md new file mode 100644 index 0000000..dc4e774 --- /dev/null +++ b/Installation-Guide.md @@ -0,0 +1,278 @@ +# 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](#requirements) below. + +--- + +## Table of Contents + +- [Requirements](#requirements) +- [Clean Installation (From Source)](#clean-installation-from-source) + - [1. Clone the Repositories](#1-clone-the-repositories) + - [2. Follow the AzerothCore Installation Guide](#2-follow-the-azerothcore-installation-guide) + - [3. Import Playerbots SQL Files](#3-import-playerbots-sql-files) + - [4. Configure Playerbots](#4-configure-playerbots) + - [5. Start the Server](#5-start-the-server) +- [Migrating From an Existing AzerothCore Installation](#migrating-from-an-existing-azerothcore-installation) +- [Docker Installation](#docker-installation) +- [Adding Other Modules](#adding-other-modules) +- [Updating Your Installation](#updating-your-installation) +- [Next Steps](#next-steps) + +--- + +## 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. + +### MySQL vs MariaDB + +MySQL is strongly recommended. MariaDB users have reported SQL deadlock issues and other database-related problems that do not occur with MySQL. If you must use MariaDB, see the [Troubleshooting](Troubleshooting) page. + +### 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 + +```bash +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](https://www.azerothcore.org/wiki/installation)** for your platform. The guide covers: + +- [Requirements](https://www.azerothcore.org/wiki/requirements) (per platform: [Windows](https://www.azerothcore.org/wiki/windows-requirements), [Linux](https://www.azerothcore.org/wiki/linux-requirements), [macOS](https://www.azerothcore.org/wiki/macos-requirements)) +- [Core Installation](https://www.azerothcore.org/wiki/core-installation) (per platform: [Windows](https://www.azerothcore.org/wiki/windows-core-installation), [Linux](https://www.azerothcore.org/wiki/linux-core-installation), [macOS](https://www.azerothcore.org/wiki/macos-core-installation)) +- [Server Setup](https://www.azerothcore.org/wiki/server-setup) +- [Database Installation](https://www.azerothcore.org/wiki/database-installation) +- [Networking](https://www.azerothcore.org/wiki/networking) +- [Final Server Steps](https://www.azerothcore.org/wiki/final-server-steps) +- [Client Setup](https://www.azerothcore.org/wiki/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. + +#### 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: + +```sql +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 +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. + +### 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:** + ```bash + 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. **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`): + + ```ini + [mysqld] + 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](https://github.com/mod-playerbots/mod-playerbots/wiki/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](https://www.azerothcore.org/wiki/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:** + ```bash + mysqldump -u acore -p acore_auth > auth_backup.sql + mysqldump -u acore -p acore_characters > characters_backup.sql + ``` + +2. **Switch your AzerothCore repository to the Playerbots fork.** From your existing `azerothcore-wotlk` directory, change the remote URL and pull the Playerbot branch: + ```bash + 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: + ```bash + cd modules + git clone https://github.com/mod-playerbots/mod-playerbots.git --branch=master + cd .. + ``` + +4. **Rebuild the server** following the [AzerothCore Installation Guide](https://www.azerothcore.org/wiki/installation) 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:** + ```sql + 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 + 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](#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:** + ```bash + 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: + ```yml + services: + ac-worldserver: + volumes: + - ./modules:/azerothcore/modules:ro + ``` + +3. **Set environment variables** for configuration (optional but recommended): + ```yml + 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): + ```bash + 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: + ```bash + # 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:** + ```bash + docker compose up -d --build + ``` + +For more information, see the [AzerothCore Install With Docker](https://www.azerothcore.org/wiki/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: + +```bash +# 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 +``` + +> **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.