# OpenWC Full Development Roadmap

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

Этот документ — полная инженерная карта разработки OpenWC. Статусы и последовательность исполняемых milestones остаются в [`README.md`](README.md); детальные subsystem plans находятся в [`roadmap/`](roadmap/). При расхождении текущий target определяет, что делать сейчас, а этот roadmap — как решение должно развиваться целиком.

Godot-specific implementation rules обязательны из [`../docs/GODOT_BEST_PRACTICES.md`](../docs/GODOT_BEST_PRACTICES.md).

## Итоговый продукт

OpenWC должен предоставить четыре согласованных режима:

1. `Blizzlike335` — клиент WoW 3.3.5a build 12340 с максимально точным наблюдаемым поведением.
2. `Enhanced` — opt-in графические, UX и accessibility улучшения, не меняющие wire protocol и server authority без отдельного profile.
3. `AuthoringStudio` — инструменты мира, контента, БД и playtest внутри Godot Editor.
4. `HeadlessTools` — import, validation, bake, packet replay, content build и CI без GUI.

Один кодовый путь должен обслуживать runtime и editor preview через публичные contracts. Generated preview nodes, DB records и caches не являются источником истины.

## Текущее положение

- MPQ/BLP/ADT/WDT/M2/WMO native parsing и renderer vertical slice уже существуют.
- Runtime streaming, terrain quality, MultiMesh M2, WMO caches, liquids, sky и character experiments находятся в рабочем состоянии, но сосредоточены в крупных orchestration scripts.
- Renderer baseline M00 завершён: paired comparison с оригинальным клиентом записывает измеренные gaps без заявления parity, а обязательные diagnostic gaps закрыты или явно классифицированы. Текущая работа M01 вводит coordinate и architecture seams.
- Gameplay domain, network protocol, production UI/Lua, audio orchestration и server adapters в основном предстоит реализовать.
- Editor plugin пока решает extraction/preview задачи, но не является полноценной authoring platform.

## Инженерные программы

| Код | Программа | Детальный план |
|---|---|---|
| FND | Foundation, application и data | [01-foundation-and-data.md](roadmap/01-foundation-and-data.md) |
| RND | Renderer и graphics | [02-rendering-and-graphics.md](roadmap/02-rendering-and-graphics.md) |
| NET | Protocol, session и synchronization | [03-network-and-session.md](roadmap/03-network-and-session.md) |
| GMP | Gameplay systems | [04-gameplay-systems.md](roadmap/04-gameplay-systems.md) |
| UIA | UI, Lua, addons, audio | [05-ui-lua-audio.md](roadmap/05-ui-lua-audio.md) |
| EDT | Godot Editor и content authoring | [06-editor-and-content-tools.md](roadmap/06-editor-and-content-tools.md) |
| SRV | TrinityCore/AzerothCore integration | [07-server-emulator-integration.md](roadmap/07-server-emulator-integration.md) |
| QAR | Fidelity, tests, CI и releases | [08-quality-and-release.md](roadmap/08-quality-and-release.md) |

## Dependency graph

```text
M00 renderer baseline
  └─ M01 coordinates/contracts
      └─ M02 input/movement/camera/presentation split
          └─ M03 renderer facade
              ├─ M04 editor shell → M05 content → M06 server adapters → M07 world editor
              └─ M08 network → M09 gameplay domain → M10 playable client
                                      M07 + M10 → M11 quest end-to-end
                                                       └─ M12 completeness waves
                                                            └─ M13 dungeon authoring
```

M12 не является одним большим этапом. Он выполняется последовательными completeness waves:

1. `C1 Core loop` — combat, spells, auras, death, loot, inventory, quests.
2. `C2 Character` — creation/customization, equipment, animation, pets, mounts.
3. `C3 World` — map/minimap, exploration, taxi, transports, weather, audio.
4. `C4 Services` — gossip, vendors, trainers, bank, mail, auction, professions.
5. `C5 Social` — chat, friends, ignore, party, raid, guild, calendar.
6. `C6 Instances/PvP` — lockouts, LFG, vehicles, battlegrounds, arenas, outdoor PvP.
7. `C7 UI/addons` — FrameXML, Lua 5.1.1, secure execution, default UI, compatibility tiers.
8. `C8 Fidelity/polish` — complete render/material/audio coverage, recovery, accessibility, localization и performance.

Каждая wave должна завершаться работающим gameplay scenario, а не количеством реализованных opcodes или таблиц.

## Milestone delivery matrix

| Milestone | Основные work packages | Обязательный результат |
|---|---|---|
| M00 | RND baseline, QAR metrics/fidelity lab | Воспроизводимые checkpoints и gaps |
| M01 | FND typed coordinates/IDs/contracts | Server/ADT/Godot round-trip и StreamingFocus |
| M02 | FND composition, GMP movement, RND presenters | Player split без visual/control regression |
| M03 | RND facade/planner/scheduler, FND jobs | Renderer доступен через API и сохраняет budgets |
| M04 | EDT plugin shell, QAR editor tests | Reload-safe workspace, commands, undo/recovery |
| M05 | FND content schemas/cache, EDT project | Deterministic Content Project build/migration |
| M06 | SRV environments/snapshots/adapters | Two-core read/diff/dry-run round-trip |
| M07 | EDT world editing/navigation/deploy | NPC placement на dev-core без ручного SQL |
| M08 | NET transport/auth/protocol/entities | Headless auth → world и deterministic replay |
| M09 | GMP world state/movement/targeting | Packet replay → deterministic gameplay snapshot |
| M10 | FND app lifecycle, RND/UIA presentation | Игрок входит, видит entities и перемещается |
| M11 | GMP quests, EDT quest tools, SRV deploy, UIA quest UI | Author → deploy → complete quest своим клиентом |
| M12 C1–C8 | NET/GMP/RND/UIA completeness + QAR | Feature matrix `Compatible/Verified` по waves |
| M13 | EDT dungeon/encounter, SRV modules, GMP instances | Custom dungeon group playtest end-to-end |

## Recommended implementation rhythm

Каждая feature внутри milestone проходит один и тот же цикл:

1. `Research` — original behavior, core expectations, готовые tools/references.
2. `Contract` — owner, types, commands/events, capabilities и error states.
3. `Fixture` — golden input/output или reproducible live scenario до production code.
4. `Pure implementation` — parser/reducer/validator без Node where possible.
5. `Adapter` — network, renderer, UI, Editor или server boundary.
6. `Vertical integration` — минимальный observable player/author outcome.
7. `Failure/recovery` — malformed, cancel, disconnect, rollback, missing asset.
8. `Fidelity/performance` — comparison evidence и budgets.
9. `Documentation` — coverage status, known gaps, tooling decision и target evidence.

## Cross-cutting contracts

- `BuildProfile` — `Blizzlike335`, `Enhanced`, authoring и test capabilities.
- `CoordinateMapper` — единственное преобразование WoW/Godot/ADT/server coordinates.
- `AssetRepository` — original assets, overlays, caches и provenance.
- `ProtocolProfile` — build, opcodes, update fields, codecs и server capabilities.
- `WorldState` — authoritative client-side projection без Node dependencies.
- `WorldRenderFacade` — presentation boundary.
- `ViewModel/Intent` — единственная граница UI с gameplay.
- `LuaRuntime` — заменяемый Lua backend.
- `ContentProject` — stable IDs, schemas, dependencies и user-authored source.
- `ServerSchemaAdapter` — canonical content ↔ core schema/change set.
- `JobScheduler` — bounded background work, cancellation, progress и main-thread finalize.
- `Diagnostic` — code, severity, location, context, suggested fix и correlation ID.

## Архитектурные gates

Перед переходом между крупными фазами обязательны:

- `Architecture gate`: запрещённые зависимости отсутствуют.
- `Fidelity gate`: есть comparison evidence, а gaps зарегистрированы.
- `Data gate`: schema/version/migration и deterministic build проверены.
- `Performance gate`: budgets измерены на cold/warm и stress scenarios.
- `Recovery gate`: failure/reconnect/cancel/rollback проверены.
- `Authoring gate`: изменения можно создать, проверить, diff, undo и воспроизвести.
- `Server gate`: обе схемы не предполагаются одинаковыми, capabilities обнаружены явно.

## Правило улучшений

Современное улучшение допускается, если:

1. исходное поведение `Blizzlike335` уже измерено или gap отмечен;
2. улучшение включается отдельным setting/profile;
3. оно не меняет protocol/server authority скрыто;
4. есть before/after visual/performance/accessibility evidence;
5. Content Project указывает required capability и fallback.

Примеры допустимых opt-in улучшений: modern shadows, higher terrain texture resolution, anisotropy, enhanced water, longer draw distance, FSR/upscaling, color-blind palettes, scalable UI, richer editor diagnostics. Новые gameplay rules требуют server module/profile, а не только client toggle.

## Definition of complete client

Клиент считается полным не тогда, когда перечислены все packet handlers, а когда:

- все строки [`../docs/CLIENT_FEATURES.md`](../docs/CLIENT_FEATURES.md) имеют evidence-backed статус;
- основные сценарии оригинального клиента воспроизводятся end-to-end;
- default UI и выбранные addons проходят compatibility tiers;
- supported TrinityCore/AzerothCore profiles проходят contract matrix;
- renderer, audio, input, localization и recovery имеют утверждённые gaps/budgets;
- AuthoringStudio может создать, проверить, развернуть и протестировать новый quest/location/dungeon package;
- release не содержит proprietary assets и требует легально полученную установку клиента.