sindoring/moonwell-core
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
1401e8dfb7546c38dc67a8934dec512ddcb3a2d3
moonwell-core/AGENTS.md
T
sindoring d03e96cc9b AGENTS.md
2026-03-21 11:21:14 +04:00

13 KiB
Raw Blame History

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 View Git Blame Copy Permalink