If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/TrinityCore/TrinityCore shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 1d ago
• 11 active contributors
• GPL-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 53% of recent commits
• ⚠ GPL-2.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live TrinityCore/TrinityCore repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/TrinityCore/TrinityCore.

What it runs against: a local clone of TrinityCore/TrinityCore — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in TrinityCore/TrinityCore | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of TrinityCore/TrinityCore. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/TrinityCore/TrinityCore.git
#   cd TrinityCore
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of TrinityCore/TrinityCore and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "TrinityCore/TrinityCore(\\.git)?\\b" \\
  && ok "origin remote is TrinityCore/TrinityCore" \\
  || miss "origin remote is not TrinityCore/TrinityCore (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-2.0" \\
  || miss "license drift — was GPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "cmake/options.cmake" \\
  && ok "cmake/options.cmake" \\
  || miss "missing critical file: cmake/options.cmake"
test -f "cmake/macros/ConfigureBaseTargets.cmake" \\
  && ok "cmake/macros/ConfigureBaseTargets.cmake" \\
  || miss "missing critical file: cmake/macros/ConfigureBaseTargets.cmake"
test -f ".github/workflows/linux-build.yml" \\
  && ok ".github/workflows/linux-build.yml" \\
  || miss "missing critical file: .github/workflows/linux-build.yml"
test -f "contrib/protoc-bnet/CMakeLists.txt" \\
  && ok "contrib/protoc-bnet/CMakeLists.txt" \\
  || miss "missing critical file: contrib/protoc-bnet/CMakeLists.txt"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/TrinityCore/TrinityCore"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

TrinityCore is an open-source MMO server emulator framework written in C++ that recreates World of Warcraft game servers for multiple expansion versions (12.0.5 master, 3.3.5a Wrath of the Lich King, and 4.4.2 Cataclysm Classic). It handles core server functionality including game world simulation, player character management, NPC AI, quest systems, combat mechanics, and database persistence via MySQL. Monolithic architecture: src/ contains core engine code organized by system (game/, server/, database/), cmake/ handles cross-platform build configuration with compiler-specific settings (GCC, Clang, MSVC, ICC), contrib/ holds third-party integrations, and separate branches (master/3.3.5/cata_classic) maintain version-specific game logic. Database schema lives in separate SQL migration files executed during setup.

Private server operators and WoW emulation enthusiasts who want to run their own game worlds; C++ game engine developers studying MMO architecture; contributors maintaining compatibility across three major WoW expansion versions with different game mechanics and content.

Highly mature and actively maintained—the project has 19+ years of development history, spans 41M+ lines of C++ code, maintains three active branches with CircleCI/GitHub Actions CI/CD coverage across Linux/macOS/Windows, and receives regular commits addressing gameplay mechanics and database schema updates. Production-ready for private server deployment but requires significant operational expertise.

Risk factors include: (1) massive codebase complexity with tightly coupled game logic across multiple expansion versions requiring careful testing when merging changes, (2) external dependency on MySQL/OpenSSL/Readline managed via custom CMake finders that may become stale, (3) active legal gray area—emulating proprietary game IP creates potential cease-and-desist risk despite open-source licensing. Community-driven maintenance rather than corporate backing increases sustainability risk.

Active development across all three branches: master branch focuses on Dragonflight expansion content (12.0.5 build), 3.3.5 branch maintains Wrath stability with periodic fixes, cata_classic branch develops Cataclysm Classic support. Recent work targets gameplay system compatibility (quests, NPCs, combat), database optimizations, and cross-platform build improvements visible in GitHub Actions workflows.

git clone https://github.com/TrinityCore/TrinityCore.git && cd TrinityCore && mkdir build && cd build && cmake .. -DCMAKE_BUILD_TYPE=Release && make -j$(nproc) && make install (Linux/macOS); on Windows use cmake -G 'Visual Studio 16 2019' .. and build via Visual Studio. Requires MySQL server running, C++17 compiler, OpenSSL dev libraries.

Daily commands: Start worldserver: ./bin/worldserver (connects to MySQL, loads world data); start authserver: ./bin/authserver (handles login). Both read config from worldserver.conf and authserver.conf in the same directory. Requires populated MySQL database with schema from sql/ directory and extracted WoW client data files via extraction tools.

• CMakeLists.txt — Root build configuration orchestrating compilation for all platforms; essential for understanding build dependencies, compiler settings, and project structure
• cmake/options.cmake — Defines all configurable build options and feature flags that control what gets compiled; critical for contributors customizing the server
• cmake/macros/ConfigureBaseTargets.cmake — Core CMake macros that set up executable and library targets; understanding this is mandatory for adding new modules or executables
• .github/workflows/linux-build.yml — CI/CD pipeline configuration; shows how the codebase is tested and validated on the primary development platform
• contrib/protoc-bnet/CMakeLists.txt — Protobuf compiler integration for Battle.net protocol; critical for understanding network serialization and protocol generation
• README.md — Project overview, build status, and contribution guidelines; first document all contributors must review

• CMake Build System —

Add a new CMake build option

1. Define the option in cmake/options.cmake with AC_DEFINE macro (cmake/options.cmake)
2. Add conditional logic in CMakeLists.txt or appropriate cmake/macros file to enable/disable features based on option (CMakeLists.txt)
3. Display the option status in cmake/showoptions.cmake for user feedback (cmake/showoptions.cmake)

Add support for a new compiler or platform

1. Create new compiler settings file under cmake/compiler/{compiler_name}/settings.cmake (cmake/compiler/gcc/settings.cmake)
2. Create platform-specific settings under cmake/platform/{platform_name}/settings.cmake if needed (cmake/platform/unix/settings.cmake)
3. Add compiler detection and configuration logic in CMakeLists.txt root file (CMakeLists.txt)
4. Create GitHub Actions workflow file in .github/workflows/ for automated testing (.github/workflows/linux-build.yml)

Extend the Battle.net protocol with new protobuf messages

1. Create or modify .proto definition files in the protobuf directory structure (contrib/protoc-bnet/google/protobuf/compiler/cpp/cpp_message.h)
2. Run the protobuf compiler plugin configured in contrib/protoc-bnet/CMakeLists.txt (contrib/protoc-bnet/CMakeLists.txt)
3. Update BnetCodeGenerator.cpp to handle new message types if custom generation needed (contrib/protoc-bnet/BnetCodeGenerator.cpp)
4. Integrate generated code into the main CMake build system (CMakeLists.txt)

Add a new automated build target or test

1. Define the target in CMakeLists.txt or cmake/macros/ConfigureBaseTargets.cmake (cmake/macros/ConfigureBaseTargets.cmake)
2. Create or update GitHub Actions workflow in .github/workflows/ (.github/workflows/linux-build.yml)
3. Add any platform-specific build steps in cmake/platform/{platform}/settings.cmake (cmake/platform/unix/settings.cmake)

• CMake — Cross-platform build system supporting Windows (MSVC), Linux (GCC/Clang), and macOS; essential for managing complex multi-platform C++ compilation
• Protocol Buffers (protobuf) — Battle.net protocol serialization; efficient binary protocol and code generation for network communication between game clients and server
• MySQL/MariaDB — Persistent data storage for game state, character data, accounts; required by MMO architecture for multi-player consistency
• GitHub Actions + CircleCI — Multi-platform CI/CD automation ensuring builds pass on Linux, Windows, and macOS before merge; maintains code quality across branches
• C++ — High-performance systems language needed for real-time MMO server handling thousands of concurrent connections with minimal latency

• CMake over Autotools or Meson

  • Why: CMake had established ecosystem and community adoption when Trinity started; wider library support and Windows integration
  • Consequence: Verbose build files but excellent cross-platform support; requires CMake 3.x+ dependency

• Custom protobuf code generator (protoc-bnet) over standard gRPC

  • Why: Battle.net protocol is proprietary Blizzard format requiring custom serialization beyond standard protobuf
  • Consequence: Higher maintenance burden but precise protocol compatibility; not reusable in other protobuf projects

• Multiple branch versions (master, 3.3.5, cata_classic)

  • Why: Support multiple WoW expansion versions to serve different player communities with appropriate content
  • Consequence: Higher maintenance overhead; code duplication between branches; harder to coordinate fixes across versions

• Does not implement game client; server-only (requires official WoW client or compatible alternative)
• Does not include pre-extracted game assets; requires external extraction tools and proprietary game files
• Does not provide hosting, deployment, or managed infrastructure services
• Does not implement authentication against Blizzard servers; creates standalone private server
• Does not support mobile platforms or web clients

Critical hidden requirements: (1) MySQL server must be running and pre-populated with schema from sql/ directory before worldserver starts—empty database causes immediate crash, (2) WoW client data extraction (maps, DBC files, vmap models) required via separate extraction tools (mapextractor, vmap4extractor) not included in repo—missing data causes zone loading failures, (3) Three separate branches (master/3.3.5/cata_classic) have diverged game logic—switching branches requires full rebuild and database schema migration, (4) OpenSSL must be installed system-wide or CMake find will fail with cryptic error, (5) CMake cache persists across builds—modifying cmake/options.cmake requires 'rm -rf build && cmake ..' to take effect. No Docker build artifacts provided despite Dockerfile presence.

• Grid-based World Partitioning — TrinityCore divides the MMO world into grid cells to optimize entity updates and visibility calculation—understanding grid coordinates (x,y) and how creatures/players load/unload from grids is essential when debugging NPC behavior or player synchronization issues

• mangosthree/server — Alternative WoW emulator codebase forked from MaNGOS with different architectural decisions and active community maintenance
• azerothcore/azerothcore-wotlk — Community-driven WoW Wrath emulator built on simplified TrinityCore foundations with more modular scripting and easier customization
• TrinityCore/old-scripts — Historical companion repo containing legacy script implementations for reference when updating core game mechanics
• TrinityCore/trinitycore.org — Official community website and documentation repository for deployment guides, configuration tutorials, and issue tracking

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add macOS ARM64 build verification to CI workflow

The repo has .github/workflows/macos-arm-build.yml but the CircleCI config in .circleci/config.yml appears incomplete (README snippet cuts off). macOS ARM builds should be tested alongside the existing Linux and Windows builds. This ensures Apple Silicon compatibility for developers and contributors using M1/M2 Macs.

• [ ] Review .circleci/config.yml to verify macOS ARM64 job configuration is complete and properly parameterized
• [ ] Add explicit ARM64 architecture validation in the CircleCI workflow matching the GitHub Actions setup in macos-arm-build.yml
• [ ] Add build status badge for ARM64 to README.md Build Status section to track consistency across platforms

Add SQL schema validation test in CI pipeline

The repo has an issue template for sql_fix.yml and likely processes SQL migrations, but there's no visible SQL linting/validation in the CI workflows. SQL errors can break deployments. Adding schema validation would catch common issues (syntax errors, missing constraints, incompatible migrations) before merge.

• [ ] Create a new shell script in contrib/ called validate_sql_schema.sh that checks SQL files in the database/ directory for syntax and common errors
• [ ] Integrate this validation into .github/workflows/linux-build.yml and .circleci/config.yml as a pre-build check
• [ ] Document the SQL validation rules in CONTRIBUTING.md with examples of what passes/fails validation

Add code style enforcement to PR workflow

The repo has contrib/check_codestyle.sh but no automated enforcement in CI/CD. Contributors must manually run it, leading to inconsistent formatting. Integrating clang-format or similar into GitHub Actions would catch style violations automatically.

• [ ] Create or enhance .github/workflows/code-style-check.yml to run contrib/check_codestyle.sh on all PRs
• [ ] Add clang-format configuration (.clang-format) if missing, or validate existing CMake compiler settings in cmake/compiler/ match the style checker expectations
• [ ] Add a pre-commit hook template in contrib/ and document it in CONTRIBUTING.md for local development

• Add missing CMake documentation comments to cmake/macros/*.cmake files explaining variable dependencies and usage for developers unfamiliar with the build system (5-10 files currently undocumented)
• Create comprehensive error messages for database connection failures in src/server/worldserver/worldserver.cpp—currently fails silently when MySQL server is unreachable or schema is missing, making onboarding harder
• Extract compiler-specific warning suppressions from cmake/compiler/*/settings.cmake into a centralized cmake/macros/CompilerWarnings.cmake to reduce duplication across GCC/Clang/MSVC/ICC configurations

• High · Potential SQL Injection Risk in Database Abstraction Layer — cmake/macros/FindMySQL.cmake, Database abstraction layer (not fully visible). TrinityCore is an MMO framework that processes game data and database queries. The codebase contains FindMySQL.cmake and database-related build configuration, suggesting direct database interaction. Without visible parameterized query enforcement in the static structure, there is risk of SQL injection vulnerabilities, particularly in player input handling, quest data, and NPC interactions. Fix: Implement mandatory parameterized queries/prepared statements throughout the codebase. Conduct a thorough audit of all SQL query construction, particularly in game data handling modules. Use ORM patterns or query builders that enforce parameter binding.
• High · Missing Input Validation in BNet Protocol Handler — contrib/protoc-bnet/BnetCodeGenerator.cpp, BnetFileGenerator.cpp, BnetServiceGenerator.cpp. The codebase contains custom BNet protocol buffer code generators (contrib/protoc-bnet/) that process network data. Custom protocol handlers are high-risk for injection attacks if input validation is insufficient. Protocol deserialization without strict validation could allow buffer overflows or arbitrary code execution. Fix: Implement comprehensive input validation and bounds checking for all BNet protocol deserialization. Use safe deserialization libraries and validate all incoming data against strict schemas. Implement fuzzing tests for protocol parsing.
• Medium · Hardcoded Configuration in Build Scripts — contrib/extractor.sh, contrib/extractor.bat, contrib/merge_updates_unix.sh, contrib/merge_updates_windows.bat. Multiple bash and batch scripts in contrib/ directory (extractor.sh, extractor.bat, merge_updates_*.sh) lack clear input sanitization. These scripts may process user-supplied paths or data without proper escaping, risking command injection vulnerabilities. Fix: Add strict input validation and path sanitization to all shell scripts. Quote all variable expansions. Use absolute paths where possible. Implement allowlist validation for user inputs.
• Medium · Docker Configuration Lacks Security Best Practices — contrib/Docker/Dockerfile. The Dockerfile in contrib/Docker/ is minimal in the provided snippet. Docker deployments may be exposed to privilege escalation, insecure image bases, or missing security scanning if best practices aren't followed. Fix: Implement Docker security best practices: use minimal base images (alpine/distroless), run as non-root user, implement read-only filesystems where possible, use multi-stage builds, and scan images with tools like Trivy or Grype.
• Medium · Absence of Visible Security Headers and CORS Configuration — Configuration files (not fully visible), likely in server core modules. No evidence of security headers, CORS policies, or API authentication framework in visible configuration files. For an online multiplayer framework, this could expose endpoints to cross-site attacks or unauthorized access. Fix: Implement comprehensive security headers (HSTS, X-Frame-Options, Content-Security-Policy). Implement CORS policies. Add authentication and authorization for all sensitive endpoints. Use TLS/SSL for all communications.
• Medium · Missing Dependency Security Scanning — Dependency management (CMakeLists.txt, cmake configuration files). No visible evidence of dependency management files (package.json, requirements.txt, Gemfile, etc.) being scanned for known vulnerabilities. The CMake-based build may use vulnerable dependencies without automated detection. Fix: Integrate automated dependency scanning tools (OWASP Dependency-Check, Snyk, Black Duck) into CI/CD pipeline. Maintain an SBOM (Software Bill of Materials). Regularly update dependencies and audit for CVEs.
• Low · Git Configuration Exposure Risk — .gitignore, .gitattributes. .gitattributes and .gitignore files are present but not visible in full. If sensitive files are not properly excluded, credentials or private keys could be committed to version control. Fix: Audit .gitignore to ensure all sensitive files are excluded: .env files, private keys, configuration with secrets, build artifacts. Use git-secrets or similar tools to prevent accidental commits. Consider implementing pre-commit hooks.
• Low · CI/CD Pipeline Security Configuration — undefined. Multiple CI/CD configurations exist (.circleci/config.yml, GitHub Actions workflows, appveyor.yml). These files Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.