Writing Modules for AzerothCore: A Beginner’s Guide

Introduction to AzerothCore Modules

AzerothCore’s modular architecture is one of its standout features, allowing developers to extend and customize World of Warcraft private servers (version 3.3.5a, Wrath of the Lich King) with ease. Mods (short for modules) in AzerothCore are essentially plugins that add new functionality, tweak existing mechanics, or introduce entirely custom features to your server. Whether you want to implement solo play adjustments, add custom quests, or create unique gameplay mechanics, mods are the way to go. This guide will walk you through how mods work in AzerothCore and how to start creating your own.

How Mods Work in AzerothCore

AzerothCore supports two main types of mods: C++ modules and Lua scripts (via the Eluna engine). This guide focuses on C++ modules, as they offer deeper integration with the core system and better performance for complex features. Here’s a breakdown of how mods function:

• Modular Structure: Each mod is a self-contained project that lives in the modules directory of your AzerothCore source code. When you compile AzerothCore, it automatically detects and builds any mods in this directory.
• Hooking into the Core: Mods interact with AzerothCore by registering scripts (e.g., player scripts, creature scripts) or event handlers that tie into the core game systems. For example, you can hook into events like player login, creature death, or spell casting.
• Configuration: Mods can have their own configuration files (e.g., mod-example.conf) in the conf directory, allowing server admins to toggle features or adjust settings without recompiling.
• Database Integration: Mods often require custom database tables for storing data (e.g., player stats, custom items). You can include SQL files with your mod to set up these tables during installation.
• Community Sharing: Many mods are shared via the AzerothCore Module Catalogue on GitHub, where you can find examples like mod-solocraft (for solo play scaling) or mod-ah-bot (for auction house bots).

Getting Started: Creating a New Mod

Creating a mod for AzerothCore involves setting up a new module, writing your code, and integrating it with the core. Let’s create a simple mod that sends a welcome message to players when they log in.

Prerequisites

• A working AzerothCore server (compiled and running).
• Basic knowledge of C++ and familiarity with AzerothCore’s source code structure.
• Git, Visual Studio 2022 (or another IDE), and CMake installed.

Step 1: Set Up the Mod Directory

Start by cloning or creating a new mod in the modules directory of your AzerothCore source code. If you don’t have a modules directory, create one.

1. Navigate to your AzerothCore source directory (e.g., C:\AzerothCore).
2. Create a new directory: modules/mod-welcome-message.
3. Inside mod-welcome-message, create a src folder for your source code.

Step 2: Create the Mod Files

You’ll need a few files to define your mod: a CMake configuration file, a script loader, and the main script file.

1. Create the CMake File:

   In mod-welcome-message, create a file named CMakeLists.txt with the following content:

   # Define the module
   AC_ADD_SCRIPT("${CMAKE_CURRENT_SOURCE_DIR}/src/welcome_message.cpp")
   AC_ADD_SCRIPT_LOADER("WelcomeMessage" "${CMAKE_CURRENT_SOURCE_DIR}/src/welcome_message.h")
   

2. Create the Script Loader:

   In mod-welcome-message/src, create a file named welcome_message.h:

   #pragma once
   
   void AddSC_WelcomeMessage();
   

3. Create the Main Script:

   In mod-welcome-message/src, create a file named welcome_message.cpp:

   #include "ScriptMgr.h"
   #include "Player.h"
   
   class WelcomeMessage : public PlayerScript
   {
   public:
       WelcomeMessage() : PlayerScript("WelcomeMessage") {}
   
       void OnLogin(Player* player) override
       {
           player->SendSystemMessage("Welcome to the server! Enjoy your adventure!");
       }
   };
   
   void AddSC_WelcomeMessage()
   {
       new WelcomeMessage();
   }
   

   This script uses the PlayerScript class to hook into the player login event and sends a welcome message.

Step 3: Compile the Mod

With the mod files in place, you need to recompile AzerothCore to include your new mod.

1. Navigate to your build directory (e.g., C:\Build).
2. Run CMake again to detect the new module: cmake ...
3. Rebuild the solution in Visual Studio (or your IDE) by building the ALL_BUILD target.
4. Ensure your server binaries (e.g., worldserver.exe) are updated in your runtime directory.

Step 4: Test Your Mod

Start your AzerothCore server (authserver.exe and worldserver.exe), log in with a character, and verify that you receive the welcome message. If it doesn’t work, check the server logs for errors and ensure your mod was compiled correctly.

Step 5: Expand Your Mod

Now that you have a basic mod working, you can expand it by adding more features:

• Add Configuration: Create a mod-welcome-message.conf file to let admins enable/disable the message or customize its text.
• Hook More Events: Use other script types like CreatureScript or SpellScript to add new gameplay mechanics.
• Database Support: If your mod needs custom data (e.g., tracking player logins), create SQL files in a sql directory within your mod and apply them to the database.

Best Practices for Mod Development

• Follow Naming Conventions: Prefix your mod files and scripts with mod- to avoid conflicts (e.g., mod-welcome-message).
• Use Version Control: Host your mod on GitHub and keep it updated. This makes it easier to share with the community and collaborate.
• Test Thoroughly: Test your mod on a local server before deploying to a live environment. Check for performance impacts and compatibility with other mods.
• Document Your Mod: Include a README.md file with installation instructions, features, and any database changes.
• Learn from Existing Mods: Explore the AzerothCore Module Catalogue to study how other mods are structured and implemented.

Conclusion

Writing mods for AzerothCore is a rewarding way to customize your WoW private server and learn more about game development. By leveraging AzerothCore’s modular system, you can create everything from simple quality-of-life features to complex gameplay mechanics. Start with a small project like the welcome message mod, then experiment with more advanced features as you gain confidence. The AzerothCore community is a great resource for support—check out the official website and join the Discord to connect with other developers. Happy modding!