moonwell-core/AGENTS.md

# 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.

## graphify

This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.

When the user types `/graphify` or `$graphify`, use the local `graphify` CLI before doing anything else.

Rules:
- Team-shared Graphify outputs are `graphify-out/graph.json`, `graphify-out/GRAPH_REPORT.md`, and `graphify-out/graph.html`; local cache, manifest, cost, lock, and `.graphify_*` files stay ignored.
- For gameplay/deployment mechanic questions, first consult `doc/MechanicsIndex.md` and `doc/mechanics.index.json`. Use `graphify explain "<mechanics JSON key>"` for a clean anchor list; use `graphify query "<mechanics JSON key>"` only when you want neighboring mechanics too.
- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
- Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).