1789d5f97f
Keep Canary's active repository instructions concise while moving the complete local build-validation workflow into dedicated documentation. Main changes: - Reduce detailed build procedures in AGENTS.md and route them through docs/building/local-validation.md. - Keep repository-wide build invariants in the always-loaded instruction layer. - Require maintained build entry points to stay synchronized when C++ source or header files are added, removed, or renamed. - Keep the relevant CMakeLists.txt, vcproj/canary.vcxproj, and test CMakeLists.txt registration requirements explicit. - Clarify that local builds remain opt-in unless explicitly requested or authorized at the completion point of a larger task. Local validation documentation: - Add docs/building/local-validation.md. - Document the supported Windows CMake and Visual Studio validation workflow. - Document Visual Studio Developer Command Prompt and Developer PowerShell environment requirements. - Document project-managed VCPKG_ROOT verification before configuring or building. - Document the preferred windows-release preset workflow. - Document how to inspect and reuse existing CMake preset caches. - Document targeted recovery from incompatible or corrupted CMake/Ninja cache state. - Avoid broad cache deletion or creating ad-hoc build directories as a recovery path. - Document maintained Visual Studio solution and generated build entry-point checks. MSVC Ninja dependency tracking: - Document that Ninja requires matching raw cl.exe /showIncludes output to populate .ninja_deps correctly. - Require configure and build steps to use a consistent environment and code page. - Keep compiler launchers disabled for MSVC Ninja validation. - Document diagnosis using rules.ninja, msvc_deps_prefix, raw /showIncludes output, and ninja -t deps. - Clarify that ninja -t recompact cannot recreate missing dependency records. - Document recovery for malformed or empty .ninja_deps without broad-cleaning build state. Instruction budget: - Keep detailed workflows out of the always-loaded AGENTS.md when they can be routed to versioned documentation. - Preserve headroom for global and narrower scoped instructions. - Prefer removing duplicated guidance before increasing instruction byte limits. Validation: - Audited the effective global and repository instruction chain at 18,449 bytes. - Verified it remains below the 24 KiB maintenance target and default Codex instruction cap. - Verified the routed local-validation documentation path exists. - Reviewed the complete committed diff. - Ran Git whitespace validation successfully. - No build was run because this is a documentation-only change and no build was requested. This keeps the active instruction layer smaller while preserving the full Canary build-validation, cache-recovery, and MSVC Ninja dependency-tracking workflow in a dedicated maintained document. |
||
|---|---|---|
| .. | ||
| building | ||
| development | ||
| docker | ||
| lua-api | ||
| maps | ||
| python-scripts | ||
| systems | ||
| architecture.md | ||
| canary-logo-transparent.png | ||
| canary-logo.png | ||
| config.ld.in | ||
| crypto-backend-evaluation.md | ||
| development.md | ||
| Doxyfile.in | ||
| operations.md | ||
| README.md | ||
| release.md | ||
Canary Documentation
This directory is the main documentation hub for the Canary repository.
Documentation Index
This documentation is organized around four primary guides, with specialized references in the surrounding subdirectories:
| Document | Purpose |
|---|---|
README.md |
Project overview and documentation index |
architecture.md |
System design, components and technical architecture |
development.md |
Development environment, coding standards and contribution workflow |
operations.md |
Deployment, monitoring, security, backups and production operations |
systems/content-reference-auditor.md |
Profile-aware gameplay content and identifier auditing |
What is Canary?
Canary is a modern MMORPG server engine that evolved from the OTServBR ecosystem. The project aims to provide a clean, maintainable, and extensible codebase that supports both custom game projects and OpenTibia-based servers. The repository includes support for multiple datapacks, Lua scripting, database persistence, a Docker quickstart for local testing, automated testing and observability tooling.
Key characteristics:
- C++20 core engine
- Lua gameplay scripting
- MariaDB/MySQL persistence
- Docker quickstart support for local testing and LAN demos
- Automated testing
- Metrics and observability
- Optional OpenTelemetry metrics integration
- Multiple datapack support
- Modern build tooling using CMake and vcpkg
Documentation Structure
docs/
├── README.md
├── architecture.md
├── development.md
├── operations.md
├── building/
├── docker/
├── lua-api/
└── systems/
Architecture Guide
The Architecture Guide explains how Canary is built internally.
Topics include:
- High-level system architecture
- Core engine design
- Networking layer
- Protocol handling
- Creature system
- Combat engine
- Map management
- Lua integration
- Database architecture
- Event system
- Scheduler and dispatcher
- Metrics and observability
Read the Architecture Guide.
Recommended for:
- Engine contributors
- System designers
- Technical reviewers
- Advanced server developers
Development Guide
The Development Guide explains how to build, test and contribute to Canary.
Topics include:
- Development environment setup
- Docker development workflow
- Native compilation
- CMake usage
- vcpkg dependency management
- Lua development
- C++ coding standards
- Testing practices
- Pull request workflow
- Debugging techniques
Read the Development Guide.
Recommended for:
- Contributors
- Developers
- Lua scripters
- Engine maintainers
Operations Guide
The Operations Guide focuses on operating Canary safely, including native production deployments and the limits of the local Docker quickstart.
Topics include:
- Infrastructure planning
- Deployment models
- Docker quickstart operations
- Configuration management
- Security practices
- Monitoring and alerting
- Backup strategies
- Disaster recovery
- Upgrade procedures
- Incident response
Read the Operations Guide.
Recommended for:
- Server administrators
- DevOps engineers
- Infrastructure teams
- Community operators
Repository Overview
canary/
│
├── src/ # C++ server source code
├── data/ # Core shared server resources
├── data-canary/ # Minimal Canary datapack
├── data-otservbr-global/ # Global datapack
├── docs/ # Project documentation
├── tests/ # Automated tests
├── docker/ # Local Docker quickstart assets
├── metrics/ # Observability and metrics
│
├── schema.sql # Database schema
├── config.lua.dist # Configuration template
├── CMakeLists.txt # Build configuration
├── CMakePresets.json # Build presets
└── vcpkg.json # Dependency manifest
The project supports both the lightweight data-canary datapack and the larger data-otservbr-global datapack, allowing operators to choose between a minimal engine-focused setup and a more complete game experience.
Typical Lifecycle
The documentation follows the same lifecycle as a Canary deployment:
Architecture
↓
Development
↓
Testing
↓
Deployment
↓
Operations
↓
Monitoring
↓
Maintenance
Technology Stack
Core Technologies
- C++20
- Lua
- MariaDB / MySQL
- CMake
- vcpkg
Infrastructure
- Docker Compose quickstart
- GitHub Actions
- OpenTelemetry-based metrics
- Prometheus and Grafana examples
Supported Platforms
- Linux
- Windows
- macOS
Deployment Options
Canary can be run using:
Docker
Recommended for:
- Local development
- Testing
- LAN demos
The repository Docker Compose stack is a quickstart. It uses the published Canary runtime image, builds the MyAAC quickstart image, and should not be used as a production deployment with default settings. See docker/DOCKER.md for the complete quickstart contract.
Native Installation
Recommended for:
- Production environments
- Custom infrastructure
- Advanced monitoring setups
The repository provides Docker quickstart assets, CMake build presets and operational guidance for these approaches.
Contributing
Contributors are encouraged to:
- Report bugs
- Improve documentation
- Write tests
- Submit pull requests
- Improve Lua systems
- Enhance engine functionality
Before contributing:
- Read
architecture.md - Read
development.md - Follow coding standards
- Run tests locally
- Update documentation when necessary
Additional Resources
Audience Guide
| Role | Recommended Reading |
|---|---|
| New Contributor | README → Development |
| Lua Developer | README → Development |
| Engine Developer | README → Architecture → Development |
| DevOps Engineer | README → Operations |
| Server Administrator | README → Operations |
| Technical Lead | README → Architecture → Operations |
Conclusion
The Canary documentation is organized around three core perspectives:
- Architecture — how the system works
- Development — how the system is built
- Operations — how the system is run
Together, these documents provide a complete reference for understanding, extending, deploying and operating Canary in both development and production environments.