# Каталог готовых инструментов и reference-решений

## Назначение

OpenWC следует принципу `research before build`: перед реализацией сложной подсистемы сначала ищется существующая библиотека, эмулятор, редактор, specification или test corpus. Цель — быстрее находить проверенные решения, сравнивать независимые реализации и не повторять уже проделанную работу.

Каталог не является списком автоматически одобренных dependencies. Любой кандидат проходит проверку лицензии, зрелости, fidelity, безопасности, производительности, поддержки платформ и стоимости интеграции.

## Статусы

- `REFERENCE` — источник идей, поведения, форматов или тестов; код не подключён.
- `CANDIDATE` — возможная dependency; требуется compatibility spike.
- `EVALUATING` — выполняется spike с зафиксированными критериями.
- `ADOPTED` — закреплены версия, boundary, лицензия, tests и update policy.
- `REJECTED` — не подходит; причина сохраняется, чтобы не повторять исследование.
- `REPLACE` — используется временно и имеет согласованный план замены.

## Обязательная карточка кандидата

```text
Name / URL:
Status:
Problem solved:
Planned boundary:
License:
Platforms/toolchain:
Fidelity evidence:
Known gaps:
Security/data risks:
Performance evidence:
Spike and acceptance criteria:
Pinned version/update policy:
Decision/ADR:
```

## Реестр

| Инструмент | Статус | Область | Планируемое использование | Главный риск |
|---|---|---|---|---|
| OpenWC native loaders | ADOPTED | MPQ/BLP/ADT/WDT/M2/WMO | Текущий import/render pipeline | Неполная fidelity форматов |
| StormLib | ADOPTED | MPQ | Чтение архивов через native extension | Version/license/update audit |
| WowUnreal | REFERENCE | Полный клиент | Coverage, acceptance criteria, networking/UI research | Unreal-specific design |
| WoWee | REFERENCE | Клиент/editor/formats | Architecture, editor workflows, tests, open formats | Заявления требуют независимой проверки |
| Noggit Red | REFERENCE | World editor | Terrain/placement UX, UID workflows | Не Godot architecture |
| open-realm | REFERENCE | Formats/runtime | Независимая проверка parsers/render behavior | Другая архитектура и coverage |
| whoa | REFERENCE | Client behavior | 3.3.5a runtime semantics и fixtures | Лицензия и переносимость отдельных решений |
| wow.export | REFERENCE | Asset conversion | M2/WMO/material/export edge cases | Web-specific pipeline |
| Blender WoW Studio | REFERENCE | Authoring/conversion | WMO/M2/ADT authoring knowledge | Blender-specific UI/data model |
| [Wowser](https://github.com/wowserhq/wowser) | REFERENCE | 3.3.5a web client | Auth/realm/character/world protocol, binary parsing, asset pipeline и render research | Старый JS/WebGL proof-of-concept, неполный клиент |
| [warcraft-rs](https://github.com/wowemulation-dev/warcraft-rs) | CANDIDATE | WoW formats/CLI | Independent MPQ/DBC/BLP/ADT/WDT/WDL/M2/WMO validation и conversion oracle | Rust/tool duplication; claims require fixtures |
| [WoWDBDefs](https://github.com/wowdev/WoWDBDefs) | REFERENCE | Client DB schemas | Versioned DBC definitions и typed-code generation input | Definitions still require build-specific validation |
| [wow_dbc](https://github.com/gtker/wow_dbc) | REFERENCE | DBC | 1.12/2.4.3/3.3.5 read/write и SQLite conversion ideas | Older release, Rust integration unnecessary by default |
| [recast-rs](https://github.com/wowemulation-dev/recast-rs) | CANDIDATE | Navigation | Offline navmesh, reachability и dungeon validation | Server mmap compatibility не доказана |
| [rilua](https://github.com/wowemulation-dev/rilua) | CANDIDATE | Lua/addons | Lua 5.1.1 runtime candidate и headless compatibility oracle | Taint/WoW API/FrameXML отсутствуют; Rust bridge |
| PUC-Rio Lua 5.1.1 | CANDIDATE | Lua reference/runtime | Authoritative Lua oracle и альтернативный embedded VM | Нужны WoW sandbox, taint и безопасный C++ boundary |
| [GdUnit4](https://github.com/godot-gdunit-labs/gdUnit4) | CANDIDATE | Godot tests | GDScript, scene, Editor и CI test runner для Godot 4.6 | Plugin/toolchain pin и adoption spike |
| [Keira3](https://github.com/azerothcore/Keira3) | REFERENCE | AzerothCore DB editor | Field semantics, SQL generation и DB editor UX | AGPL; schema-specific web architecture |
| [WowBench](https://sourceforge.net/projects/wowbench/) | REFERENCE | WoW UI/API | Offline XML/Lua API emulation и addon test ideas | Старый и неполный implementation |

## rilua — карточка кандидата

- **Problem solved:** Lua 5.1.1 VM, bytecode, embedding и официальный compatibility corpus для addon runtime.
- **Planned boundary:** реализация внутреннего `LuaRuntime` interface; FrameXML, TOC, WoW API, events и SavedVariables остаются независимыми слоями OpenWC.
- **License:** MIT OR Apache-2.0.
- **Fidelity evidence:** официальный Lua 5.1.1 test suite и oracle comparison с PUC-Rio по заявлениям проекта; OpenWC обязан повторить проверки на pinned revision.
- **Known gaps:** WoW taint/secure execution заявлен как post-1.0; TOC, WoW API stubs и UI находятся вне scope; C ABI не совместим с `lua_State*`; требуется измерение GC/OnUpdate performance.
- **Spike:** сравнить `rilua`, PUC-Rio 5.1.1 и оригинальный клиент на WoW-specific corpus; проверить restricted stdlib, globals, `bit`, errors, coroutines, byte strings, GC defaults, addon load и SavedVariables.
- **Decision policy:** не связывать UI с Rust types и не объявлять addon parity до secure/taint и FrameXML/API tests.

## Wowser — карточка референса

- **Problem studied:** полный путь клиента WoW 3.3.5a в браузере: получение assets, auth/realm/world connections, cryptography, binary packets, workers, audio и WebGL rendering.
- **Useful repositories:** [`wowserhq/wowser`](https://github.com/wowserhq/wowser), выделенные [`wowserhq/client`](https://github.com/wowserhq/client) и [`wowserhq/pipeline`](https://github.com/wowserhq/pipeline).
- **License:** MIT для основного репозитория; лицензии выделенных репозиториев проверяются отдельно перед переносом кода.
- **Fidelity evidence:** заявлена поддержка только WotLK 3.3.5a; реализованы username/password auth, realm list/connection, character list, world join и packet logging. Любая packet semantics всё равно сверяется с server core и fixtures.
- **Useful boundaries:** разделение client и asset pipeline, async/background resource work, typed binary handling, protocol lifecycle и независимый WebGL renderer.
- **Known gaps:** proof-of-concept, неполный gameplay/UI, browser WebSocket proxy вместо native TCP, устаревший JS ecosystem (React 0.14/Three.js 0.77 era), архитектура не переносится напрямую в Godot.
- **Decision policy:** использовать для cross-check и test ideas; не добавлять Node/Web dependencies и не копировать browser-specific abstractions в OpenWC.

## recast-rs — карточка кандидата

- **Problem solved:** Recast navmesh generation, Detour queries, tiled navigation и dynamic obstacles.
- **Planned boundary:** offline CLI/build job и versioned OpenWC navigation artifact.
- **License:** MIT OR Apache-2.0.
- **Known gaps:** совместимость `.mmap/.mmtile` и параметров TrinityCore/AzerothCore не доказана.
- **Spike:** synthetic + one WoW tile comparison с C++ Recast; затем отдельный server mmap compatibility experiment.

## warcraft-rs — карточка кандидата

- **Problem solved:** единый CLI/library set для MPQ, DBC, BLP, ADT, WDT, WDL, M2 и WMO версий 1.12.1–5.4.8, включая заявленную full support 3.3.5a.
- **Planned boundary:** сначала внешний pinned CLI как independent parser/validator oracle; не заменять текущий native pipeline автоматически.
- **License:** MIT OR Apache-2.0.
- **Spike:** сравнить OpenWC и warcraft-rs на synthetic/corrupt/real local fixtures: parsed counts, bounds, flags, alpha, materials, animations и diagnostics.
- **Decision policy:** отдельные crates рассматриваются только если дают доказанное преимущество; Rust runtime/toolchain не вводится ради дублирования работающего C++ parser.

## GdUnit4 — карточка кандидата

- **Problem solved:** Godot 4 GDScript/scene tests, assertions, mocks, input simulation, command-line and JUnit reports.
- **Planned boundary:** development/test plugin only; production export не зависит от test framework.
- **License:** MIT.
- **Spike:** закрепить совместимую с Godot 4.6.1 версию; проверить pure GDScript, scene lifecycle, input, EditorPlugin и headless CI sample; измерить startup overhead.
- **Decision policy:** ADOPTED только после воспроизводимого Windows/headless run и отсутствия конфликта с project plugins.

## Процесс добавления инструмента

1. Добавить карточку со статусом `REFERENCE` или `CANDIDATE`.
2. Указать конкретную проблему и boundary; «полезная библиотека» недостаточно.
3. Проверить лицензию и возможность распространения.
4. Создать bounded spike в соответствующем target, не меняя текущую цель без указания пользователя.
5. Собрать fixtures и сравнить с исходным поведением WoW 3.3.5a или authoritative implementation.
6. После решения обновить статус, pinned version, ADR и regression tests.

Вендорить или добавлять submodule до статуса `ADOPTED` не следует. Для быстро меняющихся проектов pinned commit обязателен.