105 lines
9.9 KiB
Markdown
105 lines
9.9 KiB
Markdown
# Локальные reference-проекты
|
||
|
||
Reference-код используется для исследования форматов, поведения и архитектурных вариантов. Он не определяет API OpenWC и не копируется без проверки лицензии, корректности и соответствия Godot.
|
||
|
||
## Основные источники
|
||
|
||
### OpenWC renderer
|
||
|
||
- [`../RENDER.md`](../RENDER.md) — фактическое состояние streaming, terrain, M2/WMO, liquids, sky, caches и performance rules.
|
||
|
||
### WowUnreal
|
||
|
||
- `reference/WowUnreal/specs/overview.md` — системная декомпозиция полного клиента.
|
||
- `networking.md`, `movement.md`, `character.md`, `ui-framexml.md`, `lua-api.md`, `dbc-wrappers.md`, `audio.md`, `water.md` — полезные coverage checklists и acceptance criteria.
|
||
|
||
Используем: полноту feature map и привычку задавать критерии проверки. Не переносим Unreal-specific классы и renderer assumptions.
|
||
|
||
### WoWee
|
||
|
||
- `reference/WoWee/docs/architecture.md` — разделение renderer/network/game/UI/pipeline.
|
||
- `reference/WoWee/tools/editor/FORMAT_SPEC.md` — open formats, coordinates, collision, packaging и SQL export.
|
||
- `reference/WoWee/TESTING.md` — единая точка запуска тестов, fixtures, sanitizers и CI discipline.
|
||
- `reference/WoWee/EXPANSION_GUIDE.md` — protocol/data profile separation.
|
||
|
||
Используем: детерминированные authoring formats, headless parity, adapter profiles и validation-first pipeline. Не принимаем автоматически конкретные форматы или заявленную полноту реализации.
|
||
|
||
### Noggit Red
|
||
|
||
- `reference/noggit-red` — UX и domain concepts специализированного world editor: terrain editing, placements, UIDs и map workflows.
|
||
|
||
Используем: понимание authoring interaction и рисков unique IDs. Целевой UI реализуется только через Godot EditorPlugin API.
|
||
|
||
### open-realm и whoa
|
||
|
||
- `reference/open-realm/games/world-of-warcraft` — format/render pipeline и архитектурные исследования.
|
||
- `reference/whoa` — поведение клиента 3.3.5a и test fixtures.
|
||
|
||
Используем как независимую проверку binary semantics и runtime behavior.
|
||
|
||
### wow.export и Blender WoW Studio
|
||
|
||
Используем для сверки conversion pipeline, материалов, моделей и authoring/export edge cases. Runtime web/Blender architecture не переносится в OpenWC.
|
||
|
||
### Wowser
|
||
|
||
- [`wowserhq/wowser`](https://github.com/wowserhq/wowser) — MIT proof-of-concept браузерного клиента WoW 3.3.5a.
|
||
- [`wowserhq/client`](https://github.com/wowserhq/client) — выделенный web client.
|
||
- [`wowserhq/pipeline`](https://github.com/wowserhq/pipeline) — asset delivery pipeline.
|
||
|
||
Используем как независимый reference для auth → realm → character → world lifecycle, SRP/cryptography, binary packet handling, asset delivery и частичного terrain/model renderer. Особенно полезен для поиска уже разобранных 3.3.5a packet/data edge cases и идей test fixtures.
|
||
|
||
Не переносим напрямую старый browser stack, WebSocket proxy, React/Three.js abstractions или pipeline server. Заявленное поведение проверяем по TrinityCore/AzerothCore и оригинальному клиенту; proof-of-concept не является спецификацией полноты.
|
||
|
||
### recast-rs
|
||
|
||
- [`wowemulation-dev/recast-rs`](https://github.com/wowemulation-dev/recast-rs) — Rust-порт Recast/Detour: navmesh generation, tiled pathfinding, spatial queries, crowd simulation и dynamic obstacles.
|
||
|
||
Планируем использовать как optional offline navigation backend для Godot Editor: визуализация walkability, проверка достижимости quest/encounter targets, patrol paths и dungeon topology. Начальная интеграция выполняется через CLI/build job, а не через renderer или gameplay runtime.
|
||
|
||
Важно: принадлежность к WoW emulation ecosystem не доказывает совместимость с форматами TrinityCore/AzerothCore `.mmap/.mmtile`. Генерация server mmaps разрешается только после отдельного compatibility spike с exact parameter, coordinate, tile и binary/behavior comparison. До этого OpenWC navigation cache и server mmaps считаются разными артефактами.
|
||
|
||
### rilua
|
||
|
||
- [`wowemulation-dev/rilua`](https://github.com/wowemulation-dev/rilua) — написанная на Rust реализация Lua 5.1.1 с embedding API, bytecode, официальным Lua test corpus, fuzzing и oracle comparison с PUC-Rio.
|
||
|
||
Рассматриваем одновременно как кандидата на addon Lua runtime и как headless test oracle. TOC loader, FrameXML, WoW API, events, SavedVariables и secure execution остаются слоями OpenWC. Критический gap — отсутствие готовой WoW taint system; C ABI также намеренно не совместим с PUC-Rio. Production-решение принимается только после сравнения `rilua`, PUC-Rio 5.1.1 и оригинального клиента на WoW-specific corpus.
|
||
|
||
Подробные статусы и evaluation cards ведутся в [`TOOLING_CATALOG.md`](TOOLING_CATALOG.md).
|
||
|
||
### Godot, GdUnit4 и server tooling
|
||
|
||
- [Godot best practices](https://docs.godotengine.org/en/stable/tutorials/best_practices/index.html) — основной источник engine-specific правил; принятые решения собраны в [`GODOT_BEST_PRACTICES.md`](GODOT_BEST_PRACTICES.md).
|
||
- [`godot-gdunit-labs/gdUnit4`](https://github.com/godot-gdunit-labs/gdUnit4) — кандидат для GDScript/scene/Editor/CI тестов.
|
||
- [`azerothcore/Keira3`](https://github.com/azerothcore/Keira3) — reference существующего редактора world DB и SQL generation.
|
||
- [AzerothCore database and module documentation](https://www.azerothcore.org/wiki/documentation-index) — primary reference для AzerothCore adapter/deployment workflow.
|
||
- [WowBench](https://sourceforge.net/projects/wowbench/) — исторический offline WoW XML/Lua API emulator и источник addon test ideas.
|
||
|
||
### Warcraft format ecosystem
|
||
|
||
- [`wowemulation-dev/warcraft-rs`](https://github.com/wowemulation-dev/warcraft-rs) — современный Rust CLI/library set для MPQ/DBC/BLP/ADT/WDT/WDL/M2/WMO и независимый кандидат на format oracle.
|
||
- [`wowdev/WoWDBDefs`](https://github.com/wowdev/WoWDBDefs) — versioned definitions client database tables; полезны для schema generation и coverage.
|
||
- [`gtker/wow_dbc`](https://github.com/gtker/wow_dbc) — независимый 1.12/2.4.3/3.3.5 DBC reader/writer и converter reference.
|
||
|
||
Используем для differential testing текущих native parsers и поиска coverage gaps. Новый Rust dependency не принимается только из-за более широкого списка поддерживаемых форматов: сначала требуются build-specific fixtures и измеренное преимущество.
|
||
|
||
## Правила исследования
|
||
|
||
1. Для protocol semantics приоритет имеют wire fixtures и соответствующая версия server core.
|
||
2. Для бинарных форматов вывод подтверждается минимум двумя независимыми источниками либо fixture-тестом.
|
||
3. Reference implementation не считается спецификацией без проверки edge cases.
|
||
4. Любое заимствование проверяется по лицензии и документируется.
|
||
5. Proprietary data не переносится в fixtures или репозиторий.
|
||
6. Вывод, влияющий на публичный контракт, оформляется ADR или обновлением соответствующей спецификации.
|
||
7. Перед собственной реализацией сложной подсистемы проверить [`TOOLING_CATALOG.md`](TOOLING_CATALOG.md) и добавить найденные решения, даже если они останутся только reference.
|
||
|
||
## Замеченные полезные уроки
|
||
|
||
- Полный клиент требует coverage map; иначе хорошо видимые renderer-функции вытесняют gameplay, UI и recovery paths.
|
||
- Editor нуждается в CLI/headless parity для CI, даже если вся интерактивная работа находится в Godot.
|
||
- Coordinate conversion и ID allocation должны быть централизованы раньше world editing.
|
||
- DB export без canonical model быстро связывает UI с одной версией ядра.
|
||
- Screenshot smoke полезен, но должен дополняться deterministic state, performance и protocol tests.
|
||
- Navmesh-библиотека полезна для authoring validation, но не должна становиться источником authoritative NPC movement на клиенте.
|
||
- Готовая Lua VM сокращает объём работы только на уровне языка; WoW API, FrameXML, addon lifecycle, secure actions и taint всё равно требуют отдельной fidelity-программы.
|