mirror of
https://github.com/uprightbass360/AzerothCore-RealmMaster.git
synced 2026-01-13 00:58:34 +00:00
Organize module management documentation and scripts into proper directories
This commit reorganizes the project structure for better maintainability: Structure changes: - docs/ - All documentation consolidated - README.md - Overview and quick start guide - MODULE_MANAGEMENT.md - Complete system documentation - MODULE_COMPATIBILITY.md - Module compatibility matrix - scripts/ - All automation scripts - rebuild-with-modules.sh - Automated rebuild script Updated references: - All documentation now references correct script paths - Docker compose notifications updated - Cross-references between docs maintained Benefits: - Clear separation of documentation and scripts - Better project organization and navigation - Consistent with standard project structure conventions - Easier maintenance and contribution 🤖 Generated with [Claude Code](https://claude.ai/code)
This commit is contained in:
uprightbass360
186
docs/MODULE_COMPATIBILITY.md
Normal file
186
docs/MODULE_COMPATIBILITY.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# AzerothCore Module Compatibility Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This document tracks the compatibility status of AzerothCore modules with the automated module management system.
|
||||
|
||||
## Module Status Legend
|
||||
|
||||
- ✅ **COMPATIBLE**: Module compiles and links successfully
|
||||
- ⚠️ **TESTING**: Module requires testing for compatibility
|
||||
- ❌ **INCOMPATIBLE**: Module has known compilation or linking issues
|
||||
- 🔧 **REQUIRES_CONFIG**: Module needs configuration before compilation
|
||||
- 🚨 **CRITICAL**: Module has special requirements or limitations
|
||||
|
||||
## Module Compatibility Matrix
|
||||
|
||||
### Core Modules (High Priority)
|
||||
|
||||
| Module | Status | Notes |
|
||||
|--------|--------|-------|
|
||||
| mod-aoe-loot | ⚠️ | Ready for testing |
|
||||
| mod-learn-spells | ⚠️ | Ready for testing |
|
||||
| mod-autobalance | ⚠️ | Ready for testing |
|
||||
| mod-solo-lfg | ⚠️ | Ready for testing |
|
||||
| mod-transmog | ⚠️ | Ready for testing |
|
||||
|
||||
### Quality of Life Modules
|
||||
|
||||
| Module | Status | Notes |
|
||||
|--------|--------|-------|
|
||||
| mod-ahbot | ❌ | **LINKING ERROR**: `undefined reference to 'Addmod_ahbotScripts()'` |
|
||||
| mod-npc-buffer | ⚠️ | Ready for testing |
|
||||
| mod-dynamic-xp | ⚠️ | Ready for testing |
|
||||
| mod-breaking-news-override | ⚠️ | Ready for testing |
|
||||
|
||||
### Advanced Modules
|
||||
|
||||
| Module | Status | Notes |
|
||||
|--------|--------|-------|
|
||||
| mod-playerbots | 🚨 | **CRITICAL**: Requires custom AzerothCore branch (liyunfan1223/azerothcore-wotlk/tree/Playerbot) |
|
||||
| mod-individual-progression | 🔧 | Auto-configures accounts for individual progression |
|
||||
| mod-1v1-arena | ⚠️ | Ready for testing |
|
||||
| mod-phased-duels | ⚠️ | Ready for testing |
|
||||
|
||||
### Server Management Modules
|
||||
|
||||
| Module | Status | Notes |
|
||||
|--------|--------|-------|
|
||||
| mod-boss-announcer | ⚠️ | Ready for testing |
|
||||
| mod-account-achievements | ⚠️ | Ready for testing |
|
||||
| mod-eluna | ⚠️ | Lua scripting engine integration |
|
||||
|
||||
### Additional Modules
|
||||
|
||||
| Module | Status | Notes |
|
||||
|--------|--------|-------|
|
||||
| mod-auto-revive | ⚠️ | Ready for testing |
|
||||
| mod-gain-honor-guard | ⚠️ | Ready for testing |
|
||||
| mod-time-is-time | ⚠️ | Ready for testing |
|
||||
| mod-pocket-portal | ⚠️ | Ready for testing |
|
||||
| mod-random-enchants | ⚠️ | Ready for testing |
|
||||
| mod-solocraft | ⚠️ | Ready for testing |
|
||||
| mod-pvp-titles | ⚠️ | Ready for testing |
|
||||
| mod-npc-beastmaster | ⚠️ | Ready for testing |
|
||||
| mod-npc-enchanter | ⚠️ | Ready for testing |
|
||||
| mod-instance-reset | ⚠️ | Ready for testing |
|
||||
| mod-quest-count-level | ⚠️ | Ready for testing |
|
||||
|
||||
## Known Issues
|
||||
|
||||
### mod-ahbot (AuctionHouse Bot)
|
||||
- **Error**: `undefined reference to 'Addmod_ahbotScripts()'`
|
||||
- **Cause**: Module script loader function not properly exported
|
||||
- **Solution**:
|
||||
1. Check module version compatibility with AzerothCore
|
||||
2. Update to latest module version
|
||||
3. Report issue to module maintainer
|
||||
- **Workaround**: Disable module until fixed
|
||||
|
||||
### mod-playerbots (Player Bots)
|
||||
- **Issue**: Requires custom AzerothCore branch
|
||||
- **Requirement**: `liyunfan1223/azerothcore-wotlk/tree/Playerbot`
|
||||
- **Impact**: Incompatible with standard AzerothCore builds
|
||||
- **Solution**: Use separate deployment for playerbot functionality
|
||||
|
||||
## Testing Procedure
|
||||
|
||||
### Safe Module Testing
|
||||
|
||||
1. **Enable Single Module**:
|
||||
```bash
|
||||
# Edit docker-compose-azerothcore-services.env
|
||||
MODULE_AOE_LOOT=1 # Enable one module
|
||||
```
|
||||
|
||||
2. **Test Compilation**:
|
||||
```bash
|
||||
./scripts/rebuild-with-modules.sh
|
||||
```
|
||||
|
||||
3. **Monitor Build**:
|
||||
- Watch for compilation errors
|
||||
- Check for linking issues
|
||||
- Verify successful completion
|
||||
|
||||
4. **Test Functionality**:
|
||||
- Start services
|
||||
- Test module features in-game
|
||||
- Check server logs for errors
|
||||
|
||||
### Batch Testing (Advanced)
|
||||
|
||||
1. **Enable Compatible Group**:
|
||||
```bash
|
||||
# Enable related modules together
|
||||
MODULE_AOE_LOOT=1
|
||||
MODULE_LEARN_SPELLS=1
|
||||
MODULE_AUTOBALANCE=1
|
||||
```
|
||||
|
||||
2. **Document Results**:
|
||||
- Update compatibility matrix
|
||||
- Note any conflicts between modules
|
||||
- Report issues to module maintainers
|
||||
|
||||
## Module Management Best Practices
|
||||
|
||||
### 1. Incremental Testing
|
||||
- Enable modules one at a time initially
|
||||
- Test core functionality before enabling more
|
||||
- Document compatibility results
|
||||
|
||||
### 2. Environment Management
|
||||
- Keep baseline with all modules disabled
|
||||
- Create separate environments for testing
|
||||
- Use git branches for different module configurations
|
||||
|
||||
### 3. Compatibility Tracking
|
||||
- Update this document with test results
|
||||
- Track module versions that work together
|
||||
- Note AzerothCore version compatibility
|
||||
|
||||
### 4. Performance Considerations
|
||||
- Monitor server performance with modules enabled
|
||||
- Test with realistic player loads
|
||||
- Consider module interaction effects
|
||||
|
||||
## Contributing
|
||||
|
||||
### Reporting Issues
|
||||
1. Document exact error messages
|
||||
2. Include module versions and AzerothCore version
|
||||
3. Provide reproduction steps
|
||||
4. Submit to module maintainer and this repository
|
||||
|
||||
### Updating Compatibility
|
||||
1. Test modules thoroughly
|
||||
2. Update status in compatibility matrix
|
||||
3. Document any special requirements
|
||||
4. Submit pull request with findings
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Enable a Module
|
||||
```bash
|
||||
# 1. Edit environment file
|
||||
MODULE_NAME=1
|
||||
|
||||
# 2. Rebuild if needed
|
||||
./scripts/rebuild-with-modules.sh
|
||||
|
||||
# 3. Restart services
|
||||
docker compose -f docker-compose-azerothcore-services.yml restart
|
||||
```
|
||||
|
||||
### Disable All Modules (Safe State)
|
||||
```bash
|
||||
# All modules are currently disabled in the environment file
|
||||
# This provides a stable baseline for testing
|
||||
```
|
||||
|
||||
### Check Module Status
|
||||
```bash
|
||||
# View current module configuration
|
||||
grep "^MODULE_" docker-compose-azerothcore-services.env
|
||||
```
|
||||
273
docs/MODULE_MANAGEMENT.md
Normal file
273
docs/MODULE_MANAGEMENT.md
Normal file
@@ -0,0 +1,273 @@
|
||||
# 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`:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
🚨 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`:
|
||||
```bash
|
||||
MODULE_TRANSMOG=1
|
||||
```
|
||||
|
||||
2. Restart module manager:
|
||||
```bash
|
||||
docker compose -f docker-compose-azerothcore-services.yml up ac-modules
|
||||
```
|
||||
|
||||
3. Follow rebuild instructions or run:
|
||||
```bash
|
||||
./scripts/rebuild-with-modules.sh
|
||||
```
|
||||
|
||||
### Disable Module
|
||||
|
||||
1. Edit environment file:
|
||||
```bash
|
||||
MODULE_TRANSMOG=0
|
||||
```
|
||||
|
||||
2. Restart and rebuild (module code will be removed from compilation)
|
||||
|
||||
### Bulk Module Management
|
||||
|
||||
Enable multiple modules simultaneously:
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```sql
|
||||
-- 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.
|
||||
98
docs/README.md
Normal file
98
docs/README.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# AzerothCore Module Management Documentation
|
||||
|
||||
This directory contains comprehensive documentation for the AzerothCore automated module management system.
|
||||
|
||||
## Documentation Overview
|
||||
|
||||
### 📖 [MODULE_MANAGEMENT.md](MODULE_MANAGEMENT.md)
|
||||
**Complete system guide** covering:
|
||||
- Architecture overview and components
|
||||
- Module installation and configuration
|
||||
- Database integration and SQL execution
|
||||
- Rebuild detection and automation
|
||||
- Usage examples and troubleshooting
|
||||
|
||||
### 📋 [MODULE_COMPATIBILITY.md](MODULE_COMPATIBILITY.md)
|
||||
**Module compatibility matrix** including:
|
||||
- Status of all 28 analyzed modules
|
||||
- Known issues and compatibility notes
|
||||
- Testing procedures and best practices
|
||||
- Troubleshooting guide for specific modules
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Enable a Module
|
||||
```bash
|
||||
# Edit environment file
|
||||
vim docker-compose-azerothcore-services.env
|
||||
# Set MODULE_NAME=1
|
||||
|
||||
# Rebuild if C++ compilation required
|
||||
./scripts/rebuild-with-modules.sh
|
||||
|
||||
# Restart services
|
||||
docker compose -f docker-compose-azerothcore-services.yml restart
|
||||
```
|
||||
|
||||
### 2. Check Module Status
|
||||
```bash
|
||||
# View current configuration
|
||||
grep "^MODULE_" docker-compose-azerothcore-services.env
|
||||
|
||||
# Check for rebuild requirements
|
||||
docker compose -f docker-compose-azerothcore-services.yml up ac-modules
|
||||
```
|
||||
|
||||
### 3. Safe Testing Approach
|
||||
1. Start with all modules disabled (current state)
|
||||
2. Enable one module at a time
|
||||
3. Test compilation and functionality
|
||||
4. Document results in compatibility matrix
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
docs/
|
||||
├── README.md # This overview file
|
||||
├── MODULE_MANAGEMENT.md # Complete system documentation
|
||||
└── MODULE_COMPATIBILITY.md # Module compatibility matrix
|
||||
|
||||
scripts/
|
||||
└── rebuild-with-modules.sh # Automated rebuild script
|
||||
|
||||
docker-compose-azerothcore-services.yml # Main service configuration
|
||||
docker-compose-azerothcore-services.env # Module configuration
|
||||
```
|
||||
|
||||
## System Features
|
||||
|
||||
- ✅ **Automatic Module Detection**: Downloads and analyzes all available modules
|
||||
- ✅ **State Tracking**: Hash-based change detection triggers rebuilds automatically
|
||||
- ✅ **SQL Integration**: Executes module database scripts automatically
|
||||
- ✅ **Configuration Management**: Handles .conf file setup
|
||||
- ✅ **Rebuild Automation**: Complete source-based compilation workflow
|
||||
- ✅ **Compatibility Analysis**: Documents module requirements and issues
|
||||
|
||||
## Support
|
||||
|
||||
### For Module-Specific Issues
|
||||
- Check the compatibility matrix in `MODULE_COMPATIBILITY.md`
|
||||
- Refer to individual module GitHub repositories
|
||||
- Test modules incrementally
|
||||
|
||||
### For System Issues
|
||||
- Review `MODULE_MANAGEMENT.md` troubleshooting section
|
||||
- Check Docker logs: `docker compose logs ac-modules`
|
||||
- Verify environment configuration
|
||||
|
||||
## Contributing
|
||||
|
||||
When testing modules:
|
||||
1. Update compatibility status in `MODULE_COMPATIBILITY.md`
|
||||
2. Document any special requirements or configuration
|
||||
3. Report issues to module maintainers
|
||||
4. Submit pull requests with compatibility findings
|
||||
|
||||
---
|
||||
|
||||
**Note**: All modules are currently disabled for a stable baseline. Enable and test modules individually to ensure compatibility with your specific AzerothCore setup.
|
||||
Reference in New Issue
Block a user