AzerothCore-RealmMaster/docs/MODULE_MANAGEMENT.md

AzerothCore Module Management System

This document describes the automated module management system for AzerothCore Docker deployments.

Overview

The module management system provides:

• ✅ Automated Git-based module installation
• ✅ Automatic database script execution (SQL imports)
• ✅ Configuration file management (.conf.dist → .conf)
• ✅ Module state tracking and rebuild detection
• ✅ Comprehensive rebuild automation
• ✅ Pre-compilation configuration analysis

Architecture

Components

1. Module Manager Container (ac-modules)

   • Handles module downloading, SQL execution, and state tracking
   • Runs as one-time setup during stack initialization
   • Monitors module configuration changes

2. Rebuild Detection System

   • Tracks module enable/disable state changes
   • Automatically detects when compilation is required
   • Provides detailed rebuild instructions

3. Automated Rebuild Script (scripts/rebuild-with-modules.sh)

   • Orchestrates full compilation workflow
   • Integrates with source-based Docker builds
   • Handles module synchronization

Module Types

Pre-built Compatible

None currently available - All 28 analyzed modules require C++ compilation.

Compilation Required

All current modules require source-based compilation:

• mod-playerbots (🚨 CRITICAL: Requires custom AzerothCore branch)
• mod-aoe-loot (⚠️ Ready for testing)
• mod-learn-spells (⚠️ Ready for testing)
• mod-fireworks-on-level (⚠️ Ready for testing)
• mod-individual-progression (🔧 Auto-configures accounts)
• mod-ahbot (❌ KNOWN ISSUE: Linking error - disabled)
• All other modules (⚠️ Ready for testing)

See MODULE_COMPATIBILITY.md for detailed compatibility status.

Configuration

Environment Variables

Modules are controlled via environment variables in docker-compose-azerothcore-services.env:

# Enable/disable modules (1 = enabled, 0 = disabled)
MODULE_PLAYERBOTS=1
MODULE_AOE_LOOT=1
MODULE_LEARN_SPELLS=1
# ... etc

Critical Module Requirements

mod-playerbots

• INCOMPATIBLE with standard AzerothCore
• Requires custom branch: liyunfan1223/azerothcore-wotlk/tree/Playerbot
• Will not function with standard compilation

mod-individual-progression

• Auto-configures new accounts for individual progression
• Requires account creation after server setup

Database Integration

Automatic SQL Execution

The system automatically executes SQL scripts for enabled modules:

# SQL execution locations searched:
/modules/mod-name/data/sql/world/*.sql    → acore_world database
/modules/mod-name/data/sql/auth/*.sql     → acore_auth database
/modules/mod-name/data/sql/characters/*.sql → acore_characters database
/modules/mod-name/data/sql/*.sql          → acore_world database (fallback)
/modules/mod-name/sql/*.sql               → acore_world database (alternative)

Error Handling

• ✅ Uses proper MySQL client with SSL verification disabled
• ✅ Implements exit code checking (not stderr redirection)
• ✅ Provides detailed success/failure feedback
• ✅ Continues processing if optional scripts fail

Rebuild System

Detection Logic

1. Module State Tracking

   • Creates hash of all module enable/disable states
   • Stores in /modules/.modules_state
   • Compares current vs previous state on each run

2. Change Detection

   # First run
   📝 First run - establishing module state baseline
   
   # No changes
   ✅ No module changes detected
   
   # Changes detected
   🔄 Module configuration has changed - rebuild required
   

Rebuild Requirements

When modules are enabled, the system provides:

🚨 REBUILD REQUIRED 🚨
Module configuration has changed. To integrate C++ modules into AzerothCore:

1. Stop current services:
   docker compose -f docker-compose-azerothcore-services.yml down

2. Build with source-based compilation:
   docker compose -f /tmp/acore-dev-test/docker-compose.yml build
   docker compose -f /tmp/acore-dev-test/docker-compose.yml up -d

3. Or use the automated rebuild script (if available):
   ./scripts/rebuild-with-modules.sh

Automated Rebuild Script

The rebuild-with-modules.sh script provides:

1. Pre-flight Checks

   • Verifies source repository availability
   • Counts enabled modules
   • Confirms rebuild necessity

2. Build Process

   • Stops current services
   • Syncs modules to source build
   • Executes docker compose build --no-cache
   • Starts services with compiled modules

3. Error Handling

   • Build failure detection
   • Service startup verification
   • Detailed status reporting

Usage Examples

Enable New Module

1. Edit docker-compose-azerothcore-services.env:

   MODULE_TRANSMOG=1
   

2. Restart module manager:

   docker compose -f docker-compose-azerothcore-services.yml up ac-modules
   

3. Follow rebuild instructions or run:

   ./scripts/rebuild-with-modules.sh
   

Disable Module

1. Edit environment file:

   MODULE_TRANSMOG=0
   

2. Restart and rebuild (module code will be removed from compilation)

Bulk Module Management

Enable multiple modules simultaneously:

# Edit .env file with multiple changes
MODULE_AUTOBALANCE=1
MODULE_TRANSMOG=1
MODULE_SOLO_LFG=1

# Single rebuild handles all changes
./scripts/rebuild-with-modules.sh

Troubleshooting

Common Issues

1. SQL Execution Failures

   • Check MySQL container health
   • Verify database credentials
   • Review specific SQL script syntax

2. Build Failures

   • Ensure adequate disk space (>10GB recommended)
   • Check module compatibility
   • Review Docker build logs

3. Module Not Loading

   • Verify module appears in compilation output
   • Check worldserver logs for load errors
   • Confirm configuration files copied correctly

Performance Considerations

• Build Time: 15-45 minutes depending on system performance
• Storage: Source builds require ~5-10GB additional space
• Memory: Compilation may require 4GB+ RAM
• CPU: Multi-core systems significantly faster

Technical Implementation

Module Installation Flow

1. Environment Variable Check → Module Enabled?
   ↓
2. Git Clone/Pull → Download Latest Module Source
   ↓
3. SQL Script Discovery → Find Database Scripts
   ↓
4. Database Connection → Execute Scripts with Error Handling
   ↓
5. Configuration Files → Copy .conf.dist to .conf
   ↓
6. State Tracking → Update Module State Hash
   ↓
7. Rebuild Detection → Compare Previous vs Current State
   ↓
8. User Notification → Provide Rebuild Instructions

Database Script Execution

-- Example execution pattern:
mysql --skip-ssl-verify -h ac-database -P 3306 -u root -p"password" acore_world < module.sql

-- Success detection via exit codes:
if [ $? -eq 0 ]; then
    echo "✅ Successfully executed $(basename $sql_file)"
else
    echo "❌ Failed to execute $sql_file"
fi

Future Enhancements

• Support for pure configuration modules (no compilation)
• Module dependency resolution
• Incremental compilation for faster rebuilds
• Integration with CI/CD pipelines
• Module version management and rollback
• Health checks for module functionality

Support

For issues with specific modules, refer to their individual GitHub repositories. For system-level issues, check Docker Compose logs and module manager output.