open-wc/docs/REFERENCES.md

Локальные reference-проекты

Reference-код используется для исследования форматов, поведения и архитектурных вариантов. Он не определяет API OpenWC и не копируется без проверки лицензии, корректности и соответствия Godot.

Актуальные branches и pinned commits локальных Git-референсов зафиксированы в reference/README.md. Gitlinks точно фиксируют ревизию, а .gitmodules задаёт canonical remote и ветку для контролируемого обновления.

Основные источники

OpenWC renderer

• ../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

• Исследование обновлено до master commit 8456c236b57140e98667d6d8188f5cd1cc226daf (2026-08-12), относительно прежнего pin 626243e937fb93965fa583a6507ed5a1aa7dda4b.
• 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.

Особенно полезны: WotLK M2 track/footstep fixtures, liquid mask/surface-grid tests, shader-interface checks, retained widget tree, единый XML→Lua CreateFrame path, поэлементный takeover default UI и большая система headless/static FrameXML/Lua audits. Не переносим монолитный Lua/game binding, unknown-API fallback, Vulkan-specific ownership или native-padding .w* formats. Particle/render rules, placement rotations и UI semantics требуют независимых build-12340 fixtures; часть real-asset tests WoWee пропускает отсутствие assets как success. Лицензия содержит дополнительный запрет commercial-game use, поэтому WoWee остаётся research-only reference без копирования или вендоринга кода. Полная evaluation card: TOOLING_CATALOG.md.

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 — MIT proof-of-concept браузерного клиента WoW 3.3.5a.
• wowserhq/client — выделенный web client.
• 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 не является спецификацией полноты.

Benilla

• reference/benilla (upstream) — pinned research submodule с независимым клиентом WoW 1.12.1 build 5875 на Rust/Bevy; исследование OpenWC зафиксировано на commit 9f3de200fb4a239809acd3641671d63146098a91.
• Renderer references: M2 pose/palette animation, global sequences, material/pass ordering, общий dynamic-effect stream, particles, model particles, ribbons, WMO portal visibility, lighting, sky/weather и streaming.
• UI references: отдельный engine-free TOC/FrameXML/Lua core, template/layout/widget model, deterministic event/OnUpdate ordering, legacy+modern handler arguments, sandbox, SavedVariables и большой набор compatibility tests.

Используем decomposition, algorithms, diagnostics и test ideas. Не переносим Bevy/ECS architecture и не считаем Vanilla behavior доказательством WotLK: M2/DBC/layout/API/security differences повторно проверяются по WoW 3.3.5a build 12340. Benilla пока не является oracle для third-party addons или secure/taint semantics; его Lua 5.1 runtime содержит compatibility work для Lua 5.0 target. Полная evaluation card находится в TOOLING_CATALOG.md.

recast-rs

• 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 — написанная на 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.

Godot, GdUnit4 и server tooling

• Godot best practices — основной источник engine-specific правил; принятые решения собраны в GODOT_BEST_PRACTICES.md.
• godot-gdunit-labs/gdUnit4 — кандидат для GDScript/scene/Editor/CI тестов.
• azerothcore/Keira3 — reference существующего редактора world DB и SQL generation.
• AzerothCore database and module documentation — primary reference для AzerothCore adapter/deployment workflow.
• WowBench — исторический offline WoW XML/Lua API emulator и источник addon test ideas.

Warcraft format ecosystem

• wowemulation-dev/warcraft-rs — современный Rust CLI/library set для MPQ/DBC/BLP/ADT/WDT/WDL/M2/WMO и независимый кандидат на format oracle.
• wowdev/WoWDBDefs — versioned definitions client database tables; полезны для schema generation и coverage.
• 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 и добавить найденные решения, даже если они останутся только 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-программы.