mod-ale/docs/MERGING.md

🔀 Advanced ALE Integration

Customizing and extending ALE for your specific needs

---

Important

ALE is distributed as an AzerothCore module. Unlike traditional forks, you don't need to merge code. However, this guide covers advanced integration scenarios for custom AzerothCore builds.

📋 Table of Contents

• Standard Installation
• Custom AzerothCore Builds
• Maintaining Custom Changes
• Updating ALE
• Contributing Back
• Troubleshooting

✅ Standard Installation

For most users, installing ALE is straightforward:

# Navigate to modules directory
cd <azerothcore-path>/modules

# Clone ALE
git clone https://github.com/azerothcore/mod-ale.git

# Rebuild AzerothCore
cd <azerothcore-build-directory>
cmake ../ -DLUA_VERSION=luajit
make -j$(nproc)

Tip

If you're using the standard AzerothCore setup, see the Installation Guide instead. This guide is for advanced scenarios only.

🔧 Custom AzerothCore Builds

Working with Forked AzerothCore

If you maintain a fork of AzerothCore with custom modifications:

Step 1: Add ALE as a Submodule (Recommended)

cd <your-azerothcore-fork>

# Add ALE as a submodule
git submodule add https://github.com/azerothcore/mod-ale.git modules/mod-ale

# Initialize and update
git submodule init
git submodule update

# Commit the submodule addition
git add .gitmodules modules/mod-ale
git commit -m "Add mod-ale as submodule"

Benefits:

• Easy updates with git submodule update
• Tracks specific ALE versions
• Clean separation between your code and ALE

Step 2: Configure Build

Your CMake configuration should automatically detect the module:

cd build
cmake ../ -DLUA_VERSION=luajit
make -j$(nproc)

Alternative: Clone Directly

If you prefer not to use submodules:

cd <your-azerothcore-fork>/modules
git clone https://github.com/azerothcore/mod-ale.git

Warning

Not Recommended: Avoid adding the modules/mod-ale directory to your fork's git repository. It makes updates more difficult.

Add to your .gitignore:

modules/mod-ale/

🛠️ Maintaining Custom Changes

Modifying ALE for Your Server

If you need to customize ALE:

Option 1: Fork ALE (Recommended)

1. Fork the repository on GitHub
2. Clone your fork instead of the official repository:

   cd modules
   git clone https://github.com/YOUR_USERNAME/mod-ale.git
   

3. Make your changes in a feature branch
4. Keep in sync with upstream:

   git remote add upstream https://github.com/azerothcore/mod-ale.git
   git fetch upstream
   git merge upstream/master
   

Option 2: Patch Files

For small changes, create patch files:

# Make your changes to ALE
cd modules/mod-ale

# Create a patch
git diff > ../../patches/ale-custom-changes.patch

# Apply the patch after updating
git pull
git apply ../../patches/ale-custom-changes.patch

Recommended Approach: Extension Scripts

Instead of modifying ALE core, create extension scripts:

File: lua_scripts/extensions/custom_functions.lua

-- Extend existing classes with custom methods
function Player:CustomMethod()
    -- Your custom functionality
end

function Creature:CustomBehavior()
    -- Your custom functionality
end

Benefits:

• No ALE core modifications needed
• Easy to update ALE
• Clean separation of custom code
• Portable across ALE versions

🔄 Updating ALE

Standard Update Process

For standard installations:

cd modules/mod-ale
git pull
cd ../../build
make -j$(nproc)

Updating with Submodules

If you added ALE as a submodule:

# Update to latest ALE
git submodule update --remote modules/mod-ale

# Or update all submodules
git submodule update --remote

# Commit the update
git add modules/mod-ale
git commit -m "Update mod-ale to latest version"

Updating with Custom Changes

If you maintain a fork:

cd modules/mod-ale

# Fetch upstream changes
git fetch upstream

# Merge or rebase your changes
git merge upstream/master
# or
git rebase upstream/master

# Resolve any conflicts
# Then rebuild
cd ../../build
make -j$(nproc)

Version Pinning

To pin a specific ALE version:

cd modules/mod-ale

# List available tags
git tag

# Checkout specific version
git checkout v1.2.3

# Or specific commit
git checkout abc123def

Tip

Pin versions in production environments for stability. Use latest in development for new features.

🤝 Contributing Back

If you've made improvements that could benefit others:

Preparing a Contribution

1. Ensure it's generic: Your change should be useful for the broader community
2. Follow coding standards: See Contributing Guide
3. Test thoroughly: Verify your changes don't break existing functionality
4. Document changes: Add comments and update documentation

Submission Process

1. Fork the official repository
2. Create a feature branch:

   git checkout -b feature/my-improvement
   

3. Make your changes
4. Push to your fork:

   git push origin feature/my-improvement
   

5. Open a Pull Request on GitHub

See the Contributing Guide for detailed instructions.

🔧 Troubleshooting

Merge Conflicts

If you encounter conflicts when updating:

# Check which files have conflicts
git status

# Edit conflicting files to resolve
# Look for conflict markers: <<<<<<<, =======, >>>>>>>

# Mark as resolved
git add <resolved-file>

# Complete the merge
git merge --continue

Module Not Loading

Check CMake configuration:

cd build
cmake ../ -DLUA_VERSION=luajit

Look for output like:

-- ALE module found: /path/to/modules/mod-ale

Verify module directory structure:

modules/
└── mod-ale/
    ├── CMakeLists.txt
    ├── src/
    │   └── LuaEngine/
    └── conf/

Build Errors After Update

Clean build recommended:

cd build
rm -rf *
cmake ../ -DLUA_VERSION=luajit
make -j$(nproc)

Submodule Issues

Submodule not initialized:

git submodule init
git submodule update

Submodule in detached HEAD state:

cd modules/mod-ale
git checkout master
git pull

🎯 Advanced Scenarios

Multiple ALE Versions

Testing with different ALE versions:

# Clone to different directories
cd modules
git clone https://github.com/azerothcore/mod-ale.git mod-ale-stable
git clone https://github.com/azerothcore/mod-ale.git mod-ale-dev

# Switch between them
ln -sf mod-ale-stable mod-ale  # Use stable
ln -sf mod-ale-dev mod-ale      # Use dev

Custom Lua Version

Using a custom Lua installation:

cmake ../ \
  -DLUA_VERSION=custom \
  -DLUA_INCLUDE_DIR=/path/to/lua/include \
  -DLUA_LIBRARIES=/path/to/lua/lib/liblua.a

Automated Updates

Create an update script:

File: scripts/update-ale.sh

#!/bin/bash

cd modules/mod-ale || exit 1

echo "Fetching latest ALE..."
git fetch upstream

echo "Current version: $(git rev-parse --short HEAD)"
echo "Latest version: $(git rev-parse --short upstream/master)"

read -p "Update to latest? (y/n) " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
    git merge upstream/master
    cd ../../build
    make -j$(nproc)
    echo "ALE updated successfully!"
fi

📚 Additional Resources

• Installation Guide - Standard installation process
• Contributing Guide - How to contribute changes
• Usage Guide - Getting started with scripting
• AzerothCore Documentation - Core documentation

Getting Help

• GitHub Issues: Report problems
• Discord: Join our community
• AzerothCore Discord: Get support

---

🌟 Acknowledgements

ALE is built upon the foundation of the Eluna Lua Engine. We acknowledge and thank the Eluna team for their pioneering work in Lua scripting for World of Warcraft server emulators.

• Original Eluna Repository
• Eluna Discord Community

---

_{Developed with ❤️ by the AzerothCore and ALE community}

⬆ Back to Top