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. |
||
|---|---|---|
| .github | ||
| cmake | ||
| data | ||
| data-canary | ||
| data-otservbr-global | ||
| docker | ||
| docs | ||
| metrics | ||
| src | ||
| tests | ||
| tools | ||
| vcpkg-registry | ||
| vcproj | ||
| .clang-format | ||
| .cmake-format | ||
| .cmake-lint | ||
| .dockerignore | ||
| .editorconfig | ||
| .gitattributes | ||
| .gitignore | ||
| .luarc.json | ||
| .mise.toml | ||
| .reviewdog.yml | ||
| .sonarcloud.properties | ||
| .yamllint.yaml | ||
| AGENTS.md | ||
| apply.patch | ||
| canary.rc | ||
| CMakeLists.txt | ||
| CMakePresets.json | ||
| CODE_OF_CONDUCT.md | ||
| config.lua.dist | ||
| CONTRIBUTING.md | ||
| gdb_debug | ||
| GitVersion.yml | ||
| Jenkinsfile | ||
| key.pem | ||
| LICENSE | ||
| package.json | ||
| README.md | ||
| recompile.sh | ||
| schema.sql | ||
| start.sh | ||
| start_gdb.sh | ||
| vcpkg-configuration.json | ||
| vcpkg.json | ||
Canary
Canary is a free and open-source MMORPG server emulator for the OpenTibia community, written in C++20 and Lua. It is a fork of the OTServBR-Global project. The repository includes the server core, datapacks, Lua scripts, database schema, build presets, automated tests and development tooling used by the project.
Getting Started
- Wiki.
Docker Quickstart
Canary includes a lightweight Docker quickstart for running a local test server
without compiling Canary locally. The stack starts MariaDB, the published Canary
runtime image, MyAAC as the website/admin AAC, and opentibiabr/login-server as
the client login webservice.
This quickstart is for local development, testing, and LAN demos. Do not expose it directly to the public Internet with the default test accounts and passwords.
Run from the docker directory:
cp .env.dist .env
docker compose up -d --build
The docker directory also provides guarded start scripts that start the stack
and clean safe Docker leftovers without removing database volumes:
.\up.ps1
sh ./up.sh
Default local endpoints:
- Website/admin:
http://localhost:8080 - Client login webservice:
http://localhost:8088/login - Game port:
7172
MyAAC's login.php is intentionally removed from the quickstart image. Clients
should use login-server only. See docs/docker/quickstart-for-beginners.md
for a beginner guide and docker/DOCKER.md for the full setup,
environment variables, test account, and troubleshooting guide.
Documentation
- Shared build cache for worktrees and forks.
- Docker beginner quickstart.
- Multiprotocol runtime profiles. Covers the current, 11.00, and 8.60 runtime contracts, port layout, client preparation, and validation checklist.
- System documentation.
- Lua API reference and VSCode IntelliSense stubs. Canary generates these files from the C++ Lua bindings during startup when
generateLuaApiDocsis enabled. The repository.luarc.jsonalready addsdocs/lua-apito the Lua Language Server workspace library; for VSCode workspace settings, runtools/setup_vscode_lua_api.ps1.
Recommended Tools and Clients
- Assets Editor. Use this as the
single asset source of truth, then export legacy-compatible
.dat/.sprpackages for 8.60 clients from the same current asset set. - Remere's Map Editor.
- OTClient Redemption.
- Tibia Extended Client Library. Use this to prepare compatible 8.60/11.00 CipSoft clients with extended limits, config-driven login redirect, and per-client local state.
- Game Client.
Nightly Packages
Development builds can be downloaded from GitHub Actions artifacts. They are useful for testing recent changes from the main branch, but may include behavior that is not present in stable releases yet.
Running Tests
Tests can be run from the repository root using the tool versions and tasks
pinned in .mise.toml:
mise install
mise run configure linux-debug
mise run build linux-debug
mise run test linux-debug
# Replace linux-debug with macos-debug or windows-debug as needed.
For detailed testing information including adding tests and framework usage, see tests/README.md.
Support & Community
For real-time support, join the OpenTibiaBR Discord.
The GitHub issue tracker should be used for bugs, improvements and technical project tasks. It is not a support forum.
Contributing
Contributions are welcome. You can help in several ways:
- Report bugs through the Issue Tracker.
- Submit improvements through Pull Requests.
- Improve tests, documentation, scripts, datapacks, or C++ code.
- Validate releases, nightly builds and recent changes.
Before contributing, read the Code of Conduct and the project Contributing guide.
Sponsorship
Canary is maintained by community contributors. To support development, visit the OpenTibiaBR sponsors page.
Acknowledgements
Thanks to all contributors of Canary, OTServBR-Global and the OpenTibia community.
License
This project is distributed under the GPL-2.0 license.