TrinityCore/AGENTS.md

Araxia Online Trinity Core Fork

Agent

This project is a fork of Trinity Core, a World of Warcraft server emulator.

Components

• Trinity Core
• Trinity Core Database
• Eluna

Status

We are currently in the process of getting the Eluna addon working with the master branch.

Documentation with status can be found in ELUNA_INTEGRATION_COMPLETE.md, GLOBAL_ELUNA_PLAN.md, and VALIDATION_SUMMARY.md. Please consult them before tacking any new tasks. All tasks should be tracked in these files.

---

⚠️ NEVER Defer Documentation

Documentation is CRITICAL and must never be skipped or deferred.

Why:

• AI assistants have limited context windows
• Documentation is how future sessions understand past decisions
• Without docs, work gets duplicated or misunderstood
• Code comments, READMEs, and wiki pages are essential deliverables

Every feature/change must include:

1. Code comments explaining non-obvious decisions
2. Updated README if user-facing
3. Wiki/AGENTS.md updates for AI context
4. Inline examples where helpful

---

Code Commenting Guidelines

ALWAYS add comments when modifying C++ code in this project.

Why?

• Context is lost between sessions
• Future AI assistants (and humans) need to understand design decisions
• Prevents reimplementing the same solutions repeatedly
• Code comments stay close to the implementation

What to Comment:

1. File headers - Document the purpose and any important patterns used
2. Non-obvious design decisions - Why did you choose this approach?
3. Integration patterns - How does this code interact with TrinityCore systems?
4. Gotchas and warnings - What mistakes should be avoided?

Example Pattern (MCP GM Commands):

// PREFER ChatHandler::ParseCommands() over reimplementing GM command logic
// This allows ANY existing command to work without custom code
ChatHandler handler(player->GetSession());
handler.ParseCommands(command);

Key Files with Important Comments:

• src/araxiaonline/mcp/ServerTools.cpp - GM command implementation pattern
• src/araxiaonline/mcp/AraxiaMCPServer.cpp - MCP server architecture
• src/araxiaonline/eventbus/AraxiaEvents.h - Event interface and concrete event classes

---

Araxia Event Bus

The Event Bus is a ZeroMQ-based real-time event system that publishes game events to external consumers.

• Documentation: /opt/trinitycore/araxia-content-tools/docs/game_engine/araxia_event_bus.md
• Source: src/araxiaonline/eventbus/
• Port: tcp://*:5555 (configurable)

Supported Events

Category	Events
Player	login, logout, death
Quest	accept, complete, abandon
Combat	enter, leave
Loot	item
Spawn	create, delete
Encounter	start, wipe, end

Quick Test

cd /opt/trinitycore/araxia-content-tools/scripts/zeromq
source .venv/bin/activate
python zmq_subscriber.py

Keep the wiki page updated when adding new event types or changing the event bus architecture.

---

AI Testing with Scarletseer

Scarletseer is a dedicated test character for AI assistants to use for automated testing via MCP.

• Character: Scarletseer (GUID 7, Level 80 Tauren Shaman)
• Location: Pandaria (Map 870) - Halfhill Farm area
• Documentation: See /opt/trinitycore/araxia-content-tools/docs/game_engine/scarletseer.md

Quick Start

mcp_session_create(owner_name="Cascade")
mcp_player_login(session_id=1, character_name="Scarletseer")
mcp_player_status(session_id=1)  # Verify login
# ... run tests ...
mcp_player_logout(session_id=1)

Event Bus Testing

Scarletseer can trigger events for the ZeroMQ event bus:

• Player events: login, logout, death
• Quest events: accept, complete, abandon
• Combat events: enter, leave
• Loot events: item looted
• Encounter events: start, wipe, end (requires dungeon/raid)

Monitor events with: python /opt/trinitycore/araxia-content-tools/scripts/zeromq/zmq_subscriber.py

---

Building the server

• Always use the max number of threads when building the server
• Always use @araxiaonline/cmake_setup.sh to setup the build environment. Modify it if needed.
• Please fix all compile warnings before marking a task as complete.

Pushing changes

• Our working branch is araxia-main and all branches and PRs should be based on this branch.