diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6020d50 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,401 @@ +# AGENTS.md + +Project-specific instructions for coding agents working in this repository. + +## Scope + +These instructions apply to the whole repository rooted at this directory. + +## Project Shape + +- This repo is an AzerothCore 3.3.5a server with local custom deployment glue. +- It is run primarily through Docker Compose, not through direct host binaries. +- The important local customizations live in: + - `.env` and `.env.example` + - `setup-modules.sh` + - `start-server.sh` + - `create-account.sh` + - `sync-realmlist.sh` + - `import-custom-sql.sh` + - `lua_scripts/` + - `sql/` + - vendored modules in `modules/` + +## Source Of Truth + +- Treat `.env` plus the helper scripts as the source of truth for deployment behavior. +- Do not hand-edit `env/dist/etc/*` as a permanent fix. Those files are generated runtime config. +- If a change must persist, make it in `.env`, `.env.example`, or the generating shell script. +- Keep `.env.example` aligned with `.env` defaults when changing deployment settings. + +## Generated And Ignored Paths + +- `env/dist/*` is generated and gitignored. +- `var/*` is generated and gitignored. +- `.env` is local and gitignored. +- `src/server/scripts/Custom/*` is ignored except for: + - `src/server/scripts/Custom/README.md` + - `src/server/scripts/Custom/custom_script_loader.cpp` +- Do not rely on generated files being committed. + +## Docker Workflow + +Prefer the local wrapper scripts over raw compose commands when they already encode repo-specific logic. + +### Primary commands + +- Full startup: + - `./start-server.sh` + - `./start-server.sh --no-build` + - `./start-server.sh --logs` +- Regenerate module and world configs: + - `./setup-modules.sh` + - `./setup-modules.sh --dry-run` +- Sync realm address and gamebuild into auth DB: + - `./sync-realmlist.sh` +- Create or update an account: + - `./create-account.sh --gmlevel 0` +- Import custom SQL that is outside the normal module update path: + - `./import-custom-sql.sh` + +### Useful raw compose commands + +- `docker compose ps` +- `docker compose logs -f ac-worldserver ac-authserver` +- `docker compose stop` +- `docker compose down` + +## Compose And Runtime Conventions + +- `docker-compose.yml` is upstream-style base config. Prefer local changes in `docker-compose.override.yml`. +- Service names used by local scripts: + - `ac-database` + - `ac-db-import` + - `ac-client-data-init` + - `ac-authserver` + - `ac-worldserver` +- The deployment expects Docker Compose v2 (`docker compose`, not `docker-compose`). + +## Config Layering Rules + +### World config + +- `setup-modules.sh` manages selected keys in `env/dist/etc/worldserver.conf`. +- If you need a persistent world config change, add it to `setup-modules.sh` and usually expose it through `.env`. + +### Module config + +- This repo must write effective module overrides to `env/dist/etc/modules/*.conf.dist`. +- Do not introduce a parallel `*.conf` override layer for modules here. +- AzerothCore loads module config files from the compiled module config list, and in this repo that list resolves to `*.conf.dist`. +- If you change module defaults, update the corresponding writer function in `setup-modules.sh`. + +### Playerbots + +- `mod-playerbots` is supported here, but it is a fragile area. +- Keep the repo default conservative: + - no random bot autologin + - no random bot startup population + - small addclass pool +- Do not accidentally reintroduce the old broken pattern where only `playerbots.conf` was written. +- Be careful with Docker environment overrides that map to `AiPlayerbot.*`; they can silently override file config. + +## Active Module Map + +Use this as the fast path before opening upstream module READMEs. + +### `mod-autobalance` + +- Purpose: + - scales dungeon and raid mobs for solo, duo, and undersized groups +- Source config: + - `modules/mod-autobalance/conf/AutoBalance.conf.dist` +- Effective generated config: + - `env/dist/etc/modules/AutoBalance.conf.dist` +- Managed by: + - `setup-modules.sh` +- Current repo intent: + - solo-friendly PvE tuning + - `MinPlayers = 1` for dungeons and raids + - softened raid boss health and damage for incomplete groups +- Useful diagnostics: + - `.ab mapstat` + - `.ab creaturestat` + +### `mod-individual-progression` + +- Purpose: + - per-character expansion and tier progression on a WotLK client +- Source config: + - `modules/mod-individual-progression/conf/individualProgression.conf.dist` +- Effective generated config: + - `env/dist/etc/modules/individualProgression.conf.dist` +- Managed by: + - `setup-modules.sh` +- Hard prerequisites already encoded in this repo: + - `EnablePlayerSettings = 1` + - `DBC.EnforceItemAttributes = 0` +- Important behavior: + - touches visibility, quest flow, content gating, item stats, restored legacy content, and progression unlocks +- Caveat: + - optional SQL under this module is not automatically imported unless explicitly wired in + +### `mod-playerbots` + +- Purpose: + - addclass bots, alt bots, and optional random world bots +- Source config: + - `modules/mod-playerbots/conf/playerbots.conf.dist` +- Effective generated config: + - `env/dist/etc/modules/playerbots.conf.dist` +- Managed by: + - `setup-modules.sh` +- Separate database: + - `acore_playerbots` +- Repo-specific caveat: + - upstream documents a custom `Playerbot` AzerothCore branch, but this repo carries local compatibility work on top of the current tree + - treat changes here as high risk +- Current repo intent: + - playerbots available for solo/small-group support + - random bot population disabled by default + - small addclass pool +- Fragile points: + - Docker environment overrides can silently beat file config + - avoid reintroducing large random bot defaults + - if startup crashes occur around bot creation, inspect effective `playerbots.conf.dist` first + +### `mod-eluna` + +- Purpose: + - Lua scripting engine used by local custom packages in `lua_scripts/` +- Source config: + - `modules/mod-eluna/conf/mod_eluna.conf.dist` +- Effective generated config: + - `env/dist/etc/modules/mod_eluna.conf.dist` +- Managed by: + - `setup-modules.sh` +- Important note: + - this repo uses AzerothCore `mod-eluna`, not original Eluna compatibility mode + - do not assume third-party Eluna scripts are portable + +### `mod-aoe-loot` + +- Purpose: + - area looting QoL +- Source config: + - `modules/mod-aoe-loot/conf/mod_aoe_loot.conf.dist` +- Effective generated config: + - `env/dist/etc/modules/mod_aoe_loot.conf.dist` +- Managed by: + - `setup-modules.sh` +- Extra SQL: + - module strings are imported by `import-custom-sql.sh` +- Caveat: + - if `module_string` rows are missing, world logs show `Module string module mod-aoe-loot id 1 not found in DB` + +### `mod-quest-loot-party` + +- Purpose: + - grouped quest-loot quality of life +- Source config: + - `modules/mod-quest-loot-party/conf/mod-quest-loot-party.conf.dist` +- Effective generated config: + - `env/dist/etc/modules/mod-quest-loot-party.conf.dist` +- Managed by: + - `setup-modules.sh` + +### `mod-learnspells` + +- Purpose: + - auto-grants class spells, talents, proficiencies, and optional riding/quest spells +- Source config: + - `modules/mod-learnspells/conf/mod_learnspells.conf.dist` +- Effective generated config: + - `env/dist/etc/modules/mod_learnspells.conf.dist` +- Managed by: + - `setup-modules.sh` +- Current repo intent: + - class/proficiency/quest spell automation enabled + - riding automation deliberately conservative in the local `.env` + +## Local Lua Package Map + +These packages are part of the active customization layer and are more important than generic upstream documentation. + +### `lua_scripts/AIO_Server` + +- Purpose: + - shared AIO transport/UI layer for Lua client-server addons +- Consumers in this repo: + - `MythicPlus` + - `Store_System` +- If AIO breaks, those packages effectively break too + +### `lua_scripts/MythicPlus` + +- Purpose: + - Mythic+ gameplay, scoring, keys, affixes, vault, AIO UI +- Data dependencies: + - character tables: + - `character_mythic_history` + - `character_mythic_keys` + - `character_mythic_rating` + - `character_mythic_vault` + - `character_mythic_weekly_affixes` + - world tables: + - `world_mythic_loot` + - `world_vault_loot` +- Bootstrap: + - handled by `import-custom-sql.sh` +- Extra world bootstrap: + - repairs creature/item/gameobject entries around `900001`, `900100`, `900000` +- Caveat: + - missing bootstrap often shows up as `Couldn't find a creature with (ID: 900001)!` + - empty `world_vault_loot` is non-fatal but means no vault rewards + +### `lua_scripts/Store_System` + +- Purpose: + - AIO-based in-game store UI and purchase handling +- Data dependencies: + - separate MySQL schema `store` +- Bootstrap: + - handled by `import-custom-sql.sh` + - imports `sql/Store.sql` +- Caveat: + - if `store` database is missing, Lua throws SQL errors and the store becomes unusable + +### `lua_scripts/StartZoneRaceTeleporters` + +- Purpose: + - race-specific start-zone teleporter NPCs +- Files: + - Lua logic: + - `lua_scripts/StartZoneRaceTeleporters/start_zone_race_teleporters.lua` + - base SQL: + - `lua_scripts/StartZoneRaceTeleporters/sql/world/start_zone_race_teleporters.sql` +- Bootstrap: + - imported automatically by `setup-modules.sh` when `ac-database` is already running +- Caveat: + - base SQL does not create all world spawns automatically + - example/manual spawn SQL still needs to be added per start zone + +### `lua_scripts/Battlepass` + +- Current state: + - present in tree but effectively empty +- Guidance: + - do not assume it is an active, wired gameplay system until code and bootstrap are actually added + +### `lua_scripts/hello_world.lua` + +- Current state: + - simple local script/example +- Guidance: + - low-risk when testing Eluna loading, not a core gameplay system + +## Operational Feature Map + +This repo is not just “AzerothCore plus random modules”. The intended gameplay stack is: + +- solo/small-group PvE: + - `mod-autobalance` + - softened elite HP/damage in `worldserver.conf` +- progression playthrough: + - `mod-individual-progression` +- optional bot-assisted party filling: + - `mod-playerbots` +- QoL: + - `mod-aoe-loot` + - `mod-quest-loot-party` + - `mod-learnspells` +- custom Lua systems: + - `MythicPlus` + - `Store_System` + - `StartZoneRaceTeleporters` + +When making a change, identify which layer you are actually modifying: + +- core C++ behavior +- module config generation +- custom SQL bootstrap +- Eluna Lua logic +- Docker/deployment behavior + +## Custom SQL Rules + +- Normal AzerothCore/module SQL is handled by `ac-db-import`. +- This repo also has custom SQL outside standard module paths. That logic lives in `import-custom-sql.sh`. +- At the time of writing, this includes bootstrap/import logic for: + - MythicPlus SQL under `sql/Mythic+/` + - Store SQL under `sql/Store.sql` + - `mod-aoe-loot` module strings +- If you add a new Lua package or custom SQL tree outside the standard module import layout, extend `import-custom-sql.sh`. + +## Local Lua And Custom Content + +- `lua_scripts/` contains active server-side custom Lua packages. +- Some Lua features depend on SQL bootstrap outside the normal module importer. +- If you add or rename a Lua package that requires DB state, update both: + - the file tree + - `import-custom-sql.sh` + +## Build And Edit Guidance + +- Do not rebuild the whole core unless the change actually requires it. +- For shell-script changes, validate with: + - `bash -n