module setup process

2026-02-03 02:43:50 +00:00 · 2025-11-17 02:23:53 -05:00
parent ea908dbbcf
commit d3484a3aea
30 changed files with 7685 additions and 430 deletions
--- a/docs/MODULE_DBC_FILES.md
+++ b/docs/MODULE_DBC_FILES.md
@@ -0,0 +1,141 @@
+# Module DBC File Handling
+
+## Overview
+
+Some AzerothCore modules include binary `.dbc` (Database Client) files that modify game data. These files serve two purposes:
+
+1. **Server-side DBC files**: Override base game data on the server
+2. **Client-side DBC files**: Packaged in MPQ patches for player clients
+
+## Server DBC Staging
+
+### How It Works
+
+The module staging system (`scripts/bash/stage-modules.sh`) automatically deploys server-side DBC files to `/azerothcore/data/dbc/` in the worldserver container.
+
+### Enabling DBC Staging for a Module
+
+Add the `server_dbc_path` field to the module's entry in `config/module-manifest.json`:
+
+```json
+{
+  "key": "MODULE_WORGOBLIN",
+  "name": "mod-worgoblin",
+  "repo": "https://github.com/heyitsbench/mod-worgoblin.git",
+  "type": "cpp",
+  "server_dbc_path": "data/patch/DBFilesClient",
+  "description": "Enables Worgen and Goblin characters with DB/DBC adjustments",
+  "category": "customization"
+}
+```
+
+### Manifest Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `server_dbc_path` | Optional | Relative path within module to server-side DBC files |
+| `notes` | Optional | Additional installation notes (e.g., client patch requirements) |
+
+### Example Directory Structures
+
+**mod-worgoblin:**
+```
+mod-worgoblin/
+└── data/
+    └── patch/
+        └── DBFilesClient/          ← server_dbc_path: "data/patch/DBFilesClient"
+            ├── CreatureModelData.dbc
+            ├── CharSections.dbc
+            └── ...
+```
+
+**mod-arac:**
+```
+mod-arac/
+└── patch-contents/
+    └── DBFilesContent/             ← server_dbc_path: "patch-contents/DBFilesContent"
+        ├── CharBaseInfo.dbc
+        ├── CharStartOutfit.dbc
+        └── SkillRaceClassInfo.dbc
+```
+
+## Important Distinctions
+
+### Server-Side vs Client-Side DBC Files
+
+**Server-Side DBC Files:**
+- Loaded by worldserver at startup
+- Must have valid data matching AzerothCore's expectations
+- Copied to `/azerothcore/data/dbc/`
+- Specified via `server_dbc_path` in manifest
+
+**Client-Side DBC Files:**
+- Packaged in MPQ patches for WoW clients
+- May contain empty/stub data for UI display only
+- **NOT** deployed by the staging system
+- Must be distributed to players separately
+
+### Example: mod-bg-slaveryvalley
+
+The mod-bg-slaveryvalley module contains DBC files in `client-side/DBFilesClient/`, but these are **CLIENT-ONLY** files (empty stubs). The actual server data must be downloaded separately from the module's releases.
+
+**Manifest entry:**
+```json
+{
+  "key": "MODULE_BG_SLAVERYVALLEY",
+  "name": "mod-bg-slaveryvalley",
+  "notes": "DBC files in client-side/DBFilesClient are CLIENT-ONLY. Server data must be downloaded separately from releases."
+}
+```
+
+## Workflow
+
+1. **Module enabled** → `.env` has `MODULE_NAME=1`
+2. **Staging runs** → `./scripts/bash/stage-modules.sh`
+3. **Manifest check** → Reads `server_dbc_path` from `config/module-manifest.json`
+4. **DBC copy** → Copies `*.dbc` files to worldserver container
+5. **Server restart** → `docker restart ac-worldserver` to load new DBC data
+
+## Current Modules with Server DBC Files
+
+| Module | Status | server_dbc_path | Notes |
+|--------|--------|----------------|-------|
+| mod-worgoblin | Disabled | `data/patch/DBFilesClient` | Requires client patch |
+| mod-arac | Enabled | `patch-contents/DBFilesContent` | Race/class combinations |
+| mod-bg-slaveryvalley | Enabled | *Not set* | DBC files are client-only |
+| prestige-and-draft-mode | Enabled | *Not set* | Manual server DBC setup required |
+
+## Troubleshooting
+
+### DBC Field Count Mismatch
+
+**Error:**
+```
+/azerothcore/data/dbc/AreaTable.dbc exists, and has 0 field(s) (expected 36).
+```
+
+**Cause:** Client-only DBC file was incorrectly deployed to server
+
+**Solution:** Remove `server_dbc_path` from manifest or verify DBC files contain valid server data
+
+### DBC Files Not Loading
+
+**Check:**
+1. Module is enabled in `.env`
+2. `server_dbc_path` is set in `config/module-manifest.json`
+3. DBC directory exists at specified path
+4. Worldserver was restarted after staging
+
+## Best Practices
+
+1. **Only set `server_dbc_path` for modules with valid server-side DBC files**
+2. **Test DBC deployments carefully** - invalid DBC data causes worldserver crashes
+3. **Document client patch requirements** in the `notes` field
+4. **Verify DBC field counts** match AzerothCore expectations
+5. **Keep client-only DBC files separate** from server DBC staging
+
+## Related Documentation
+
+- [Module Management](./ADVANCED.md#module-management)
+- [Database Management](./DATABASE_MANAGEMENT.md)
+- [Troubleshooting](./TROUBLESHOOTING.md)