92 lines
8.5 KiB
Markdown
92 lines
8.5 KiB
Markdown
# Каталог готовых инструментов и 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, неполный клиент |
|
||
| [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 |
|
||
|
||
## 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.
|
||
|
||
## Процесс добавления инструмента
|
||
|
||
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 обязателен.
|