Merge pull request #3 from araxiaonline/add-zeromq-event-bus

feat(eventbus): Add ZeroMQ Event Bus with comprehensive game event hooks

Author: james-huston

AGENTS.md

@@ -45,3 +45,72 @@ 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
+```bash
+cd /opt/trinitycore/TrinityCore/src/araxiaonline/tools
+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/TrinityCore/src/araxiaonline/tools/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.

araxiaonline/.env.example

@@ -9,7 +9,7 @@
 DB_HOST=host.docker.internal
 DB_PORT=3306
 DB_USER=trinity
-DB_PASSWORD=trinity
+DB_PASSWORD=<YOUR_SECURE_PASSWORD_HERE>
 DB_AUTH=auth
 DB_CHARACTERS=characters
 DB_WORLD=world

araxiaonline/Dockerfile

@@ -60,9 +60,9 @@ ENV LC_ALL=en_US.UTF-8
 RUN update-alternatives --install /usr/bin/cc cc /usr/bin/clang 100 && \
     update-alternatives --install /usr/bin/c++ c++ /usr/bin/clang++ 100
 
-# Create trinitycore user with sudo privileges
+# Create trinitycore user with sudo privileges (requires password)
 RUN useradd -m -s /bin/bash -G sudo trinitycore && \
-    echo "trinitycore ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
+    echo "trinitycore ALL=(ALL) ALL" >> /etc/sudoers
 
 # Create necessary directories
 RUN mkdir -p \

araxiaonline/ams/AMS_Client/AMS_Client.lua

@@ -119,7 +119,7 @@ local function SendAddonMessage(message)
     if #message <= AMS_MAX_MSG_LENGTH then
         -- Prefix with marker for short message (ID = 0000, parts = 0000, partID = 0000)
         local packet = NumberToHex(0) .. NumberToHex(0) .. NumberToHex(0) .. message
-        -- Use PARTY channel for solo players, fallback to WHISPER if in party
+        -- Use WHISPER channel for solo players, PARTY if in a group
         local channel = IsInGroup() and "PARTY" or "WHISPER"
         local target = channel == "WHISPER" and UnitName("player") or nil
         Debug("Sending via channel:", channel, "target:", target or "none", "prefix:", AMS_PREFIX)
@@ -134,7 +134,7 @@ local function SendAddonMessage(message)
 
     Debug("Splitting message ID", msgID, "into", totalParts, "parts")
 
-    -- Use PARTY channel for solo players, fallback to WHISPER if in party
+    -- Use WHISPER channel for solo players, PARTY if in a group
     local channel = IsInGroup() and "PARTY" or "WHISPER"
     local target = channel == "WHISPER" and UnitName("player") or nil
 

araxiaonline/ams/AMS_Server.lua

@@ -42,8 +42,11 @@ local AMS_MSG_MAX_ID = 65535  -- 16-bit ID
 -- Dependencies
 -- ============================================================================
 
--- Smallfolk for serialization (already in AIO deps)
-local Smallfolk = require("AIO_Server.Dep_Smallfolk.smallfolk")
+-- Smallfolk for serialization (vendored in AMS_Server directory)
+local Smallfolk = require("AMS_Server.smallfolk")
+
+-- Chat channel constants for clarity
+local CHAT_CHANNEL_WHISPER = 7  -- CHAT_MSG_WHISPER
 
 -- ============================================================================
 -- Core AMS Table
@@ -120,7 +123,7 @@ local function SendAddonMessage(player, message)
     if #message <= AMS_MAX_MSG_LENGTH then
         -- Prefix with marker for short message (ID = 0000, parts = 0000, partID = 0000)
         local packet = NumberToHex(0) .. NumberToHex(0) .. NumberToHex(0) .. message
-        player:SendAddonMessage(AMS_PREFIX, packet, 7, player)
+        player:SendAddonMessage(AMS_PREFIX, packet, CHAT_CHANNEL_WHISPER, player)
         return
     end
 
@@ -142,7 +145,7 @@ local function SendAddonMessage(player, message)
                       NumberToHex(partID)
 
         local packet = header .. chunk
-        player:SendAddonMessage(AMS_PREFIX, packet, 7, player)
+        player:SendAddonMessage(AMS_PREFIX, packet, CHAT_CHANNEL_WHISPER, player)
     end
 end
 

araxiaonline/araxia_docs/Dockerfile

@@ -74,7 +74,13 @@ RUN apt-get update && apt-get install -y \
     libbz2-1.0 \
     libreadline8t64 \
     libncurses6 \
-    libboost-all-dev \
+    libboost-system1.83.0 \
+    libboost-filesystem1.83.0 \
+    libboost-thread1.83.0 \
+    libboost-program-options1.83.0 \
+    libboost-iostreams1.83.0 \
+    libboost-regex1.83.0 \
+    libboost-locale1.83.0 \
     ca-certificates \
     && rm -rf /var/lib/apt/lists/*
 

araxiaonline/araxia_docs/docker-compose.yml

@@ -6,10 +6,10 @@ services:
     image: mysql:8.0
     container_name: trinitycore-mysql
     environment:
-      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-trinity}
+      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:?Please set MYSQL_ROOT_PASSWORD in .env}
       MYSQL_DATABASE: ${MYSQL_AUTH_DATABASE:-auth}
       MYSQL_USER: ${MYSQL_USER:-trinity}
-      MYSQL_PASSWORD: ${MYSQL_PASSWORD:-trinity}
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD:?Please set MYSQL_PASSWORD in .env}
     volumes:
       - mysql-data:/var/lib/mysql
       - ./sql:/docker-entrypoint-initdb.d:ro
@@ -19,7 +19,7 @@ services:
       - trinitycore
     command: --default-authentication-plugin=mysql_native_password --max_allowed_packet=512M
     healthcheck:
-      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p${MYSQL_ROOT_PASSWORD:-trinity}"]
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p${MYSQL_ROOT_PASSWORD}"]
       interval: 10s
       timeout: 5s
       retries: 5

araxiaonline/client_addons/AMS_Client/AMS_Client.lua

@@ -119,7 +119,7 @@ local function SendAddonMessage(message)
     if #message <= AMS_MAX_MSG_LENGTH then
         -- Prefix with marker for short message (ID = 0000, parts = 0000, partID = 0000)
         local packet = NumberToHex(0) .. NumberToHex(0) .. NumberToHex(0) .. message
-        -- Use PARTY channel for solo players, fallback to WHISPER if in party
+        -- Use WHISPER channel for solo players, PARTY if in a group
         local channel = IsInGroup() and "PARTY" or "WHISPER"
         local target = channel == "WHISPER" and UnitName("player") or nil
         Debug("Sending via channel:", channel, "target:", target or "none", "prefix:", AMS_PREFIX)
@@ -134,7 +134,7 @@ local function SendAddonMessage(message)
 
     Debug("Splitting message ID", msgID, "into", totalParts, "parts")
 
-    -- Use PARTY channel for solo players, fallback to WHISPER if in party
+    -- Use WHISPER channel for solo players, PARTY if in a group
     local channel = IsInGroup() and "PARTY" or "WHISPER"
     local target = channel == "WHISPER" and UnitName("player") or nil
 

araxiaonline/lua_scripts/AMS_Server/AMS_Server.lua

@@ -42,9 +42,12 @@ local AMS_MSG_MAX_ID = 65535  -- 16-bit ID
 -- Dependencies
 -- ============================================================================
 
--- Smallfolk for serialization
+-- Smallfolk for serialization (vendored in AMS_Server directory)
 local Smallfolk = require("AMS_Server.smallfolk")
 
+-- Chat channel constants for clarity
+local CHAT_CHANNEL_WHISPER = 7  -- CHAT_MSG_WHISPER
+
 -- ============================================================================
 -- Core AMS Table
 -- ============================================================================
@@ -124,7 +127,7 @@ local function SendAddonMessage(player, message)
     if #message <= AMS_MAX_MSG_LENGTH then
         -- Prefix with marker for short message (ID = 0000, parts = 0000, partID = 0000)
         local packet = NumberToHex(0) .. NumberToHex(0) .. NumberToHex(0) .. message
-        player:SendAddonMessage(AMS_PREFIX, packet, 7, player)
+        player:SendAddonMessage(AMS_PREFIX, packet, CHAT_CHANNEL_WHISPER, player)
         return
     end
 
@@ -146,7 +149,7 @@ local function SendAddonMessage(player, message)
                       NumberToHex(partID)
 
         local packet = header .. chunk
-        player:SendAddonMessage(AMS_PREFIX, packet, 7, player)
+        player:SendAddonMessage(AMS_PREFIX, packet, CHAT_CHANNEL_WHISPER, player)
     end
 end
 

dep/CMakeLists.txt

@@ -33,6 +33,7 @@ if(SERVERS)
   add_subdirectory(rapidjson)
   add_subdirectory(efsw)
   add_subdirectory(protobuf)
+  add_subdirectory(zeromq)
 endif()
 
 if(TOOLS)