mirror of
https://github.com/opentibiabr/canary
synced 2026-08-16 06:26:09 -04:00
No description
de9d7880d9
Add a deterministic profile-aware gameplay content auditor This commit adds a deterministic profile-aware static auditor for Canary gameplay content. The auditor models the repository using the same mutually exclusive datapack profiles used at runtime. The canary profile is built from data, plus the data canary. The otservbr global profile is built from data plus data otservbr global. This keeps definitions from alternative datapacks isolated and prevents one profile from incorrectly satisfying or conflicting with another profile. This is a tooling-only change. It does not modify server runtime behavior. The new auditor is available as a Python CLI through python m tools.canary_audit. It extracts typed gameplay definitions, references, registrations, and unresolved expressions from Lua, XML, and appearance data. The covered areas include items, monsters, NPCs storages actions, movement, events, weapons, and spells. The tool also extracts authoritative item IDs from the data appearances.dat file. This extraction follows the runtime requirements for protobuf ID fields, flags, and the uint16 item ID domain, instead of treating every numeric field as an item definition. Lua analysis is intentionally conservative. The scanner ignores comments and string contents, tracks lexical scope and constructor ownership, and leaves dynamic expressions unresolved instead of guessing. This makes unresolved dynamic coverage visible without fabricating false missing references. XML validation was added for item overrides, creature references, storage ranges, overlapping ranges, and out-of-range values. The XML parser disables external entities and fails closed if the parser cannot enforce that safety setting. The auditor generates deterministic schema-validated artifacts for CI and local review. Generated artifacts • project-index.json • symbol-registry.json • reference-report.json • summary.md Semantic fingerprints are stable and narrowly scoped. Finding fingerprints includes occurrence multiplicity, so a waiver for one known legacy occurrence cannot hide a newly duplicated occurrence later. Baseline waivers are supported for existing known issues. The current shared items.xml contains four reversed item ranges. These produce eight profile-specific error findings and are recorded with individual fingerprints and engineering reasons. The waivers keep the initial CI gate usable while ensuring that any new error-level finding still blocks CI. Main changes included in this commit • Adds the tools.canary_audit Python CLI • Adds profile-aware scanning for the canary datapack profile • Adds profile-aware scanning for the otservbr global datapack profile • Keeps gameplay profiles isolated during extraction and rule evaluation • Adds typed definitions for items, monsters, NPCs, storages, actions, movement, events, weapons, and spells • Adds typed references for gameplay content relationships • Adds typed registrations for action IDs, unique IDs, movement, events, weapons, spells, and related content • Tracks unresolved dynamic Lua expressions instead of guessing their values • Extracts authoritative item IDs from data items appearances.dat • Parses protobuf fields for ID and flags according to runtime requirements • Enforces the uint16 item ID domain • Adds conservative Lua analysis that ignores comments and string contents • Tracks lexical scope during Lua extraction • Tracks constructor ownership during Lua extraction • Adds XML validation for item overrides • Adds XML validation for creature references • Adds XML validation for storage ranges • Adds XML validation for overlapping ranges • Adds XML validation for out-of-range values • Adds deterministic JSON and Markdown audit artifacts • Adds schema validation for generated artifacts • Adds stable semantic fingerprints • Adds narrowly scoped baseline waivers • Adds occurrence multiplicity to fingerprints • Adds a read-only GitHub Actions workflow for audit validation • Adds CI schema validation • Adds CI test execution • Adds CI scans for both supported profiles • Publishes the audit summary in CI • Uploads generated audit artifacts in CI • Adds repository documentation for architecture commands extension points, exit codes, and coverage boundaries Correctness and safety improvements • Keeps canary and otservbr global datapack definitions isolated • Prevents alternative datapack content from satisfying the wrong profile • Prevents alternative datapack content from conflicting with the wrong profile • Uses full protobuf field parsing for appearance data • Avoids treating unrelated numeric fields as item definitions • Disables XML external entities • Fails closed when XML entity hardening cannot be enforced • Confines discovery paths to the repository • Confines output paths to the repository • Rejects symlink escapes • Writes output artifacts atomically per file • Applies limits to Lua tokens • Applies per-file fact limits • Applies total fact limits • Applies diagnostic limits • Applies finding limits • Uses indexed interval lookups for range validation • Uses bounded finding evidence • Uses heap-based overlap sweeps • Uses precomputed Lua delimiter pairs to avoid quadratic behavior Coverage boundaries Binary OTBM maps are not parsed by this auditor. Action ID and unique ID selectors are indexed as registrations, but the auditor does not claim that matching map selectors exist. Dynamic Lua expressions remain visible as unresolved coverage. They are not fabricated as missing references. Validation performed • python m unittest discover s tools canary_audit tests t . p test_*.py v • python m tools.canary_audit validate-schemas • python m tools.canary_audit scan profile all output-dir artifacts canary-audit • python m tools.canary_audit validate input-dir artifacts canary-audit Validation results • 60 unit and integration tests passed • Full two-profile scan completed with exit code 0 • 39311 facts were produced • 2194 findings were produced • 8 legacy errors were waived with exact fingerprints • 0 operational diagnostics • 0 new blocking findings • Generated JSON artifacts passed schema validation No C++ build was run because this change only adds Python tooling documentation, configuration schemas, and CI support. Overall, this commit adds a deterministic profile-aware gameplay content auditor that can be run locally and in CI. It improves repository visibility for unresolved references, duplicate definitions, duplicate registrations, invalid ranges, and profile-specific content issues while keeping runtime behavior unchanged. |
||
|---|---|---|
| .github | ||
| cmake | ||
| data | ||
| data-canary | ||
| data-otservbr-global | ||
| docker | ||
| docs | ||
| metrics | ||
| src | ||
| tests | ||
| tools | ||
| vcproj | ||
| .clang-format | ||
| .cmake-format | ||
| .cmake-lint | ||
| .dockerignore | ||
| .editorconfig | ||
| .gitattributes | ||
| .gitignore | ||
| .luarc.json | ||
| .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
- 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 directly from the repository root using CMake test presets:
# Configure and build tests for your platform
cmake --preset linux-debug && cmake --build --preset linux-debug
# Run all tests
ctest --preset linux-debug
# For other platforms use:
# ctest --preset macos-debug
# ctest --preset windows-debug
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.