open-wc/docs/TOOLING_CATALOG.md

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

Назначение

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

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

Статусы

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

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

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	REFERENCE	3.3.5a web client	Auth/realm/character/world protocol, binary parsing, asset pipeline и render research	Старый JS/WebGL proof-of-concept, неполный клиент
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	REFERENCE	Client DB schemas	Versioned DBC definitions и typed-code generation input	Definitions still require build-specific validation
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	CANDIDATE	Navigation	Offline navmesh, reachability и dungeon validation	Server mmap compatibility не доказана
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	CANDIDATE	Godot tests	GDScript, scene, Editor и CI test runner для Godot 4.6	Plugin/toolchain pin и adoption spike
Keira3	REFERENCE	AzerothCore DB editor	Field semantics, SQL generation и DB editor UX	AGPL; schema-specific web architecture
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, выделенные wowserhq/client и 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 обязателен.