felwell-core/plans/00-arguscore-analysis-and-roadmap.md

ArgusCore — Analysis & Implementation Plan

Generated: 2026-05-30 Source of truth: ROADMAP.md + live codebase scan

---

Phase 0 — Documentation Discovery (Findings)

Sources consulted:

• ROADMAP.md — full phase-by-phase plan with per-task status
• README.md — build requirements and config layout
• CMakeLists.txt — build system structure and module wiring
• modules/cmake/AddModule.cmake — add_argus_module() API
• .github/workflows/build-linux.yml / build-windows.yml — CI pipeline
• src/server/scripts/ — content script structure
• logs/ — reference codebase inventory

Current Phase Status:

Phase	Title	Status
1	Safe Rebranding	Validated
2	Custom Script Integration	Complete
3	Build System Cleanup	Validated
4	Dependency Updates	Validated (MariaDB pending)
5	Code Modernization	Complete
6	CI, Testing, Profiling	Complete
7	Modular System	In progress
8	Safe Async Systems	Complete
9	Map Threading Research	Complete
10	World Layering	Complete (design only)
11	NPC Gameplay Systems	In progress
12	Class Spell Restoration	In progress

---

Architecture Overview

ArgusCore/
├── src/
│   ├── common/          Networking (Asio), crypto, config, logging, threading, collision
│   ├── server/
│   │   ├── bnetserver/  Auth + realm selection (port 3724)
│   │   ├── worldserver/ Main game server (port 8085)
│   │   ├── game/        Core game logic (~52 subsystems: Units, Spells, Maps, AI, Handlers…)
│   │   ├── scripts/     Content scripts — organized by zone and class
│   │   │   ├── Spells/  spell_dk.cpp, spell_monk.cpp, spell_dh.cpp …
│   │   │   ├── BrokenIsles/, Argus/, Northrend/ …  zone content
│   │   │   └── Custom/  standalone features (now empty — scripts moved to modules)
│   │   ├── database/    DB abstraction + schema updater (UpdateFetcher, DBUpdater)
│   │   └── shared/      Shared packet/network/realm code between servers
│   └── tools/
├── modules/             AzerothCore-style external module system
│   ├── cmake/AddModule.cmake  add_argus_module() helper
│   └── (mod-* subdirs auto-discovered at configure time)
├── sql/
│   ├── base/            Initial schema (DO NOT modify post-import)
│   ├── updates/<db>/master/   RELEASED updates (committed)
│   ├── pending/<db>/    PENDING (WIP/pre-review, not committed)
│   ├── custom/<db>/     CUSTOM (server-local, never committed)
│   └── old/             ARCHIVED legacy
├── logs/                Reference codebases (read-only)
│   ├── LegionCore-7.3.5-merged/  Primary Phase 12 spell source
│   ├── TrinityCore-master/
│   ├── TrinityCore-Cata/
│   └── SkyFire_548-main/
└── .github/workflows/
    ├── build-linux.yml  4 jobs: Debug+tests, ASAN, UBSAN, Profile
    └── build-windows.yml  MSVC RelWithDebInfo + artifact ZIP

Module wiring: modules/ → add_argus_module() → global ARGUS_MODULE_LIBRARIES property → root CMakeLists.txt links into worldserver + generates modules_loader.cpp calling Add<NAME>Scripts().

Script registration: Each script class calls RegisterSpellScript(ClassName) (or similar) inside an AddSC_*() function, which is declared in the relevant *_script_loader.cpp.

SQL update states: RELEASED | ARCHIVED | CUSTOM | MODULE | PENDING — tracked in UpdateFetcher::State (src/server/database/).

---

Phase 7 — Modular System (Remaining Work)

What's done: Module infrastructure (CMake helper, auto-discovery, script loader generation, DB state enum expansion, sql/pending/ and sql/custom/ directories with .gitkeep).

One task remaining:

7A — Module SQL Auto-Discovery in DBUpdater

Goal: At startup, DBUpdater scans modules/mod-*/sql/<db>/ and registers discovered directories as MODULE-state include paths — no manual updates_include entries needed per module.

File to edit: src/server/database/Database/DBUpdater.cpp

Pattern to follow: Look at how sql/updates/<db>/master/ is registered as RELEASED; replicate the scan logic but walk modules/mod-*/sql/<db>/ via filesystem iteration.

Verification:

• Create a test module with a sql/world/ migration file
• Start server — confirm the migration is applied without any manual DB row insertion
• Confirm updates table shows state = MODULE
• No existing RELEASED updates affected

Anti-pattern: Do not hardcode module names — use directory glob/scan.

---

Phase 11 — NPC Gameplay Systems (Remaining Work)

Pathfinding and obstacle-jumping are done. All three power-type levels are unstarted.

11A — Level 1: Display (SQL only)

Goal: Set correct unit_class in creature_template for humanoid NPCs so the right power bar displays. No code changes.

Steps:

1. Query creature_template for unit_class = 0 on humanoid-type entries where class should not be 0
2. Write SQL update → sql/pending/world/rev_<timestamp>.sql
3. Validate in-game: mage NPC shows mana bar, warrior shows rage bar

Tool: tools/create_sql.ps1 generates the pending file.

Verification:

• Named humanoid NPCs display correct power bar type

11B — Level 2: Resource Consumption (Code)

Goal: NPC spells actually consume mana/rage/energy. A mage NPC can run OOM.

Steps:

1. Grep src/server/game/Spells/ for where spell cost checks are bypassed for non-player units
2. Remove or conditionalize the bypass — NPCs with unit_class != 0 pay spell costs
3. Run full compile + boot test
4. Validate: mage NPC mana depletes; no existing boss script regressions

Critical guard: Boss scripts that rely on infinite resources must not break. Audit any script in src/server/scripts/ that sets UNIT_FLAG_PACIFIED or adjusts power before casting.

Verification:

• NPC mana drains under sustained cast pressure
• All boss scripts in existing raid/dungeon directories unaffected

11C — Level 3: AI Resource Management (Code + AI)

Goal: NPCs regenerate resources naturally, build rage on hit, and adjust ability priority based on current resource level.

Steps:

1. Implement class-appropriate regen rates per unit_class in the creature update path
2. Expose GetPowerPercent() helper on creature AI base class
3. Add resource-gated ability priority to key humanoid NPC scripts (opt-in per script)

Anti-pattern: Do NOT apply globally — Level 3 is opt-in per creature script to avoid AI overhead regression.

Verification:

• Warrior NPCs generate rage on hit/damage
• Mage NPCs use filler spells when low mana
• No measurable AI update time regression (check with profiling build)

---

Phase 12 — Class Spell Restoration (Remaining Work)

Source: logs/LegionCore-7.3.5-merged/src/server/scripts/Spells/ Target: src/server/scripts/Spells/ Rule: One struct per commit. Compile + in-game test before next. Commit format: feat(scripts/spell): port spell_<name> from LegionCore

12A — Blocked DK Spells (Requires API Extension First)

These 4 DK spells cannot be ported until the following hooks are added to ArgusCore's spell system:

Hook needed	Spells blocked
DoCalcMaxDuration	spell_dk_bonestorm
GetRndEffectTarget()	spell_dk_blood_mirror, spell_dk_breath_of_sindragosa
AddEffectTarget()	spell_dk_breath_of_sindragosa
ClearSpellTargets / AddDelayedEvent / ExistSpellTarget / AddSpellTargets	spell_dk_glacial_advance, spell_dk_glacial_advance_damage

Decision required: Either add these hooks to the spell script system (see TrinityCore-master for reference implementations), or design workarounds that achieve the same behavior using available hooks.

Verification before unblocking:

• New hook compiles cleanly
• Existing spell scripts using related hooks still pass CI

12B — Monk (30 spells — all pending)

All 30 Monk spells in logs/LegionCore-7.3.5-merged/src/server/scripts/Spells/spell_monk.cpp are unported. Port in this suggested order (simpler first):

1. spell_monk_disable — movement impair, simple
2. spell_monk_zen_pilgrimage / spell_monk_zen_pilgrimage_return — teleport pair
3. spell_monk_transcendence / spell_monk_transcendence_transfer — spirit copy pair
4. spell_monk_zen_flight_check / spell_monk_remove_zen_flight
5. spell_monk_flying_serpent_kick
6. spell_monk_expel_harm
7. spell_monk_zen_pulse
8. spell_monk_chi_wave / spell_monk_chi_wave_dummy / spell_monk_chi_wave_filter
9. spell_monk_power_strikes
10. spell_monk_hurricane_strike
11. spell_monk_whirling_dragon_punch_activater / spell_monk_whirling_dragon_punch_activated
12. spell_monk_storm_earth_and_fire / spell_monk_storm_earth_and_fire_clone_visual / spell_monk_clone_cast
13. spell_monk_gift_of_the_ox
14. spell_monk_guard
15. spell_monk_purifying_brew / spell_monk_purified_healing
16. spell_monk_enveloping_mist
17. spell_monk_sheiluns_gift
18. spell_monk_touch_of_karma
19. spell_monk_touch_of_death
20. spell_monk_dampen_harm
21. spell_monk_diffuse_magic

12C — Paladin (24 spells — all pending)

Port order (simpler/isolated first):

1. spell_pal_lay_on_hands
2. spell_pal_divine_shield
3. spell_pal_hand_of_protection
4. spell_pal_divine_intervention
5. spell_pal_divine_steed
6. spell_pal_zeal
7. spell_pal_holy_wrath
8. spell_pal_divine_storm
9. spell_pal_holy_shock
10. spell_pal_shield_of_the_righteous
11. spell_pal_shield_of_vengeance
12. spell_pal_ardent_defender
13. spell_pal_light_of_the_protector
14. spell_pal_last_defender / spell_pal_at_last_defender
15. spell_pal_at_aura_of_sacrifice
16. spell_pal_at_devotion_aura
17. spell_pal_greater_blessing_of_kings
18. spell_pal_holy_shield
19. spell_pal_holy_prism / spell_pal_holy_prism_effect / spell_pal_holy_prism_heal / spell_pal_holy_prism_damage
20. spell_pal_lights_hammer

12D — Warlock (16 spells — all pending)

Port order:

1. spell_warl_banish
2. spell_warl_burning_rush
3. spell_warl_demon_skin
4. spell_warl_soul_harvest
5. spell_warl_doom_bolt
6. spell_warl_corruption
7. spell_warl_unstable_affliction / spell_warl_unstable_affliction_R2
8. spell_warl_streten_insanity
9. spell_warl_seed_of_corruption_dota
10. spell_warl_demonic_circle_summon / spell_warl_demonic_circle_teleport
11. spell_warl_demonic_gateway / spell_warl_demonic_gateway_cast / spell_warl_demonic_gateway_duration / spell_warl_demonic_gateway_at

12E — Hunter (15 spells — all pending)

1. spell_hun_tame_beast
2. spell_hun_pet_heart_of_the_phoenix
3. spell_hun_ancient_hysteria
4. spell_hun_masters_call
5. spell_hun_fireworks / spell_hun_fetch
6. spell_hun_kill_command
7. spell_hun_dire_beast
8. spell_hun_cobra_shot
9. spell_hun_beast_cleave
10. spell_hun_flanking_strike
11. spell_hun_a_murder_of_crows
12. spell_hun_explosive_shot / spell_hun_explosive_shot_detonate
13. spell_hun_explosive_trap

12F — Warrior (12 spells — all pending)

1. spell_warr_charge_check_cast / spell_warr_charge_drop_fire
2. spell_warr_intercept
3. spell_war_intervene
4. spell_warr_shield_block
5. spell_warr_revenge
6. spell_warr_execute
7. spell_warr_bloodthirst
8. spell_warr_heroic_leap
9. spell_warr_fervor_of_battle
10. spell_warr_ravager / spell_warr_ravager_visual

12G — Druid (12 spells — all pending)

1. spell_dru_cat_form
2. spell_dru_travel_form / spell_dru_travel_form_remove
3. spell_dru_incarnation / spell_dru_incarnation_tree_of_life
4. spell_dru_lifebloom
5. spell_dru_rake
6. spell_dru_shred
7. spell_dru_rip
8. spell_dru_thrash
9. spell_dru_ferocious_bite
10. spell_dru_ashamanes_frenzy

12H — Mage (8 spells — all pending)

1. spell_elem_invisibility
2. spell_mage_displacement
3. spell_mage_illusion
4. spell_mage_flameglow
5. spell_mage_cauterize
6. spell_mage_erosion
7. spell_mage_arcane_barrage
8. spell_mage_flurry

12I — DH Blocked Spells (Requires API Extension)

Requires GetAreaObjectList (6 spells) and GetAura()->GetRndEffectTarget() / m_whoHasMyAuras (4 spells). Same decision as 12A — add hooks or design workarounds.

12J — Rogue (1 spell)

1. spell_rog_shadowy_duel_main — verify no m_whoHasMyAuras dependency before porting

---

Phase 13 — Outstanding CI / Stability (Recommended Addition)

From Phase 6 outstanding items:

• Server profiling investigation — server is "noticeably slow"; run with InfluxDB metrics (map update times, DB latency, session update times) and profile before any optimization work
• 24h+ uptime test — CI only verifies compile + unit tests; a 24h stability run under load would validate Phase 8/9 async work
• 48h+ uptime test — required to close Phase 8 validation

---

Phase 14 — MariaDB LTS (Deferred)

From Phase 4: MariaDB LTS not yet tested. Floor stays 10.6.3 until a build is validated.

• Test MariaDB 11.x LTS on a Linux build
• Update minimum version in README.md and cmake/ find scripts if needed

---

Phase 15 — Docker/CI Image (Deferred)

From Phase 1: Docker/container names still use upstream TrinityCore images. Needs own CI image build.

• Build ArgusCore-branded CI Docker image
• Push to Docker Hub or GHCR
• Update build-linux.yml to pull custom image

---

Execution Rules (from ROADMAP.md — apply to all phases)

• Every change: SMALL, ISOLATED, COMPILE, BOOT, TEST IN-GAME
• Never combine gameplay refactors with threading changes
• Never rewrite large systems at once
• Never optimize before profiling
• Stability > modernization speed
• Maintain backward compatibility

---

Immediate Next Steps (Priority Order)

1. Phase 7A — Module SQL auto-discovery (unblocks all future modules from needing manual DB setup)
2. Phase 12B–J — Continue spell ports class by class (simple spells first, blocked ones after API hooks are added)
3. Phase 12A / 12I — Design API hook additions needed to unblock DK and DH remaining spells
4. Phase 11A — NPC power type display (SQL only, low risk, high gameplay impact)
5. Phase 13 — Profiling investigation (blocking any future performance work)
6. Phase 11B — NPC resource consumption (after profiling baseline established)