AGENTS.md
This commit is contained in:
@@ -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 <username> <password> --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 <script>`
|
||||
- For compose changes, validate with:
|
||||
- `docker compose config`
|
||||
- For config-generation changes, validate by running:
|
||||
- `./setup-modules.sh --dry-run`
|
||||
- then `./setup-modules.sh`
|
||||
- If you change realm-related settings, run:
|
||||
- `./sync-realmlist.sh`
|
||||
- If you change custom SQL bootstrap, run:
|
||||
- `./import-custom-sql.sh`
|
||||
- with `ac-database` already running
|
||||
|
||||
## C++ And Core Notes
|
||||
|
||||
- This is still a normal AzerothCore source tree under `src/`.
|
||||
- `authserver` and `worldserver` are the two runtime executables.
|
||||
- `modules/` is vendored into this repo. Do not treat it as git submodules.
|
||||
- Keep `src/server/scripts/Custom/custom_script_loader.cpp` present and tracked; removing it breaks linking of `AddCustomScripts()`.
|
||||
|
||||
## What To Change For Common Tasks
|
||||
|
||||
### Change deployment defaults
|
||||
|
||||
- Edit `.env.example`
|
||||
- If the repo default should also change for the current working copy, edit `.env`
|
||||
- Update any helper script that derives behavior from those variables
|
||||
|
||||
### Change module behavior
|
||||
|
||||
- Edit `setup-modules.sh`
|
||||
- Regenerate configs with `./setup-modules.sh`
|
||||
|
||||
### Change auth/world exposure or realm address
|
||||
|
||||
- Edit `.env`
|
||||
- Run `./sync-realmlist.sh`
|
||||
|
||||
### Change account bootstrap behavior
|
||||
|
||||
- Edit `create-account.sh`
|
||||
- Keep SRP/account logic self-contained there
|
||||
|
||||
### Change first-run database bootstrap
|
||||
|
||||
- Edit `import-custom-sql.sh`
|
||||
- Keep imports idempotent
|
||||
|
||||
## Practical Safety Notes
|
||||
|
||||
- Prefer additive, idempotent changes in shell scripts.
|
||||
- Preserve current local server assumptions unless the task explicitly changes them:
|
||||
- solo/small-group friendly tuning
|
||||
- generated config flow
|
||||
- Docker-first operation
|
||||
- If a fix only works by editing generated files under `env/dist`, it is incomplete.
|
||||
Reference in New Issue
Block a user