first commit

2026-04-20 20:25:10 +04:00
commit 1fe2a72ef1
1926 changed files with 156731 additions and 0 deletions
@@ -0,0 +1,373 @@
+# OpenWC
+
+Портирование клиента **World of Warcraft 3.3.5a (12340)** на **Godot 4.6**.
+
+Текущий фокус проекта: загрузка данных из клиента, разбор форматов WoW и отображение мира в Godot так, чтобы его можно было смотреть и дальше редактировать уже средствами движка.
+
+Сейчас проект уже умеет:
+
+- открывать MPQ-архивы клиента через editor plugin;
+- извлекать файлы из MPQ в `res://extracted`;
+- читать `BLP2` текстуры;
+- читать `ADT`-тайлы terrain;
+- рендерить terrain из `ADT` с текстурными слоями `MCLY/MCAL`;
+- учитывать `holes` в `MCNK`;
+- читать и рендерить воду из `MH2O`;
+- стримить мир чанками с LOD в runtime;
+- стримить мир в **editor preview** по мере движения камеры в 3D viewport;
+- читать `WMO` в отдельный `Dictionary` и собирать его в `Node3D` вручную.
+
+Что пока не доведено до полноценного world renderer:
+
+- автоматическая подстановка `WMO` и `M2` в мир из `ADT/WDT`;
+- вода без простого базового материала: нет нормального water shader, depth fade, shoreline blending, анимации;
+- world-level `WDT` loader;
+- импорт обратно в форматы WoW;
+- полноценные инструменты редактирования мира в editor.
+
+## Текущее состояние
+
+### Реализовано
+
+- `MPQManager`
+  - открытие клиентских архивов;
+  - список архивов по приоритету;
+  - listing/extract по фильтру.
+- `BLPLoader`
+  - чтение `BLP2` из файла или из байтов;
+  - поддержка основных сжатых форматов, достаточная для terrain textures.
+- `ADTLoader`
+  - `MTEX`, `MMDX/MMID`, `MWMO/MWID`;
+  - `MDDF`, `MODF`;
+  - `MCVT`, `MCNR`, `MCLY`, `MCAL`;
+  - `holes`;
+  - `MH2O`.
+- `ADTBuilder`
+  - сборка terrain в `Node3D`;
+  - terrain material с 4 слоями;
+  - legacy/big/compressed alpha;
+  - chunk-level LOD;
+  - первый проход рендера воды.
+- `StreamingWorld`
+  - runtime streaming тайлов и чанков;
+  - editor streaming вокруг камеры viewport;
+  - отдельные `ADT`-узлы под `Terrain` в дереве сцены.
+
+### Частично реализовано
+
+- `WMOLoader`
+  - root/group parsing есть;
+  - `WMOBuilder` собирает mesh по группам;
+  - в общий world streaming пока не интегрировано.
+
+### Не реализовано
+
+- `M2` renderer;
+- `WDT` streaming metadata;
+- сохранение terrain/liquid/object placement обратно в WoW-форматы;
+- редакторские инструменты изменения ADT/WMO данных.
+
+## Структура проекта
+
+- `sources/`
+  - исходный клиент WoW 3.3.5a, без модификаций.
+- `extracted/`
+  - извлечённые из MPQ файлы, с которыми работает Godot.
+- `addons/mpq_extractor/`
+  - editor plugin и GDScript-сборщики сцен.
+- `gdextension/`
+  - C++ GDExtension: MPQ, BLP, ADT, WMO.
+- `maps/`
+  - готовые сцены для просмотра мира.
+- `scenes/`
+  - скрипты streaming/preview/camera.
+- `thirdparty/`
+  - `godot-cpp`, `StormLib` и другие зависимости.
+
+## Требования
+
+- Windows
+- Godot `4.6`
+- Visual Studio 2022 с C++ workload
+- CMake
+- клиент **WoW 3.3.5a (12340)**
+
+## Сборка
+
+Собрать GDExtension:
+
+```bat
+cd gdextension
+build.bat Release
+```
+
+После успешной сборки DLL появится в:
+
+```text
+addons/mpq_extractor/bin/
+```
+
+## Подготовка данных
+
+По умолчанию plugin смотрит на клиент в:
+
+```text
+res://sources
+```
+
+И извлекает файлы в:
+
+```text
+res://extracted
+```
+
+### Через editor plugin
+
+1. Открой проект в Godot.
+2. Убедись, что plugin `MPQ Extractor` включён.
+3. Внизу editor открой панель `MPQ Extractor`.
+4. Укажи путь к клиенту WoW 3.3.5a.
+5. Выбери locale.
+6. Нажми `Open Client Archives`.
+7. Для полной распаковки используй фильтр `*` и `Extract`.
+
+Для terrain/world обычно нужны как минимум:
+
+- `World/Maps/...`
+- `Textures/...`
+- `World/wmo/...`
+- `DBFilesClient/...` если позже понадобится работа с DBC
+
+## Основные классы GDExtension
+
+### `MPQManager`
+
+Доступен из GDScript. Основные методы:
+
+- `open_client(base_path, locale)`
+- `list_files(filter="*")`
+- `extract_files(filter, output_dir)`
+- `read_file(internal_path)`
+
+### `BLPLoader`
+
+Читает WoW `BLP2` и возвращает `Image`.
+
+Основные методы:
+
+- `load_image(path)`
+- `load_image_from_bytes(bytes)`
+
+### `ADTLoader`
+
+Читает `ADT` и возвращает `Dictionary` с terrain, texture layers, placements и liquid.
+
+Основные поля результата:
+
+- `textures`
+- `m2_names`
+- `wmo_names`
+- `m2_placements`
+- `wmo_placements`
+- `chunks`
+
+Каждый chunk содержит:
+
+- `index_x`, `index_y`
+- `origin`
+- `heights`
+- `normals`
+- `holes`
+- `layers`
+- `alpha_maps`
+- `liquids`
+
+### `WMOLoader`
+
+Читает root/group файлы `WMO` и возвращает `Dictionary` с `materials` и `groups`.
+
+Это уже можно использовать вручную, но в world streaming оно пока не подключено.
+
+## GDScript-сборщики
+
+### `ADTBuilder`
+
+Файл: `addons/mpq_extractor/loaders/adt_builder.gd`
+
+Умеет:
+
+- собрать весь `ADT` в `Node3D`;
+- собрать отдельный chunk с нужным LOD;
+- собрать water root для тайла;
+- создать layered terrain material;
+- загрузить BLP-текстуры через `BLPLoader`.
+
+### `WMOBuilder`
+
+Файл: `addons/mpq_extractor/loaders/wmo_builder.gd`
+
+Умеет:
+
+- собрать `Node3D` из данных `WMOLoader`;
+- создать по одному `MeshInstance3D` на группу;
+- назначить базовые материалы.
+
+## Сцены просмотра
+
+### `maps/test.tscn`
+
+Файл: `maps/test.tscn`
+
+Тестовая сцена, которая грузит квадрат тайлов вокруг центра карты.
+
+Скрипт: `scenes/test_world_loader.gd`
+
+Подходит для:
+
+- быстрой проверки terrain;
+- отладки парсинга `ADT`;
+- проверки AABB и координат.
+
+### `maps/adt_tile_preview.tscn`
+
+Файл: `maps/adt_tile_preview.tscn`
+
+Preview одного `ADT` прямо в editor.
+
+Скрипт: `scenes/adt_tile_preview.gd`
+
+Полезно для:
+
+- проверки одного конкретного тайла;
+- отладки terrain layers;
+- проверки воды и дыр по отдельному `ADT`.
+
+Основные export-поля:
+
+- `map_name`
+- `tile_x`
+- `tile_y`
+- `reload_now`
+
+### `maps/eastern_kingdoms_streaming.tscn`
+
+Файл: `maps/eastern_kingdoms_streaming.tscn`
+
+Главная сцена для стриминга мира.
+
+Скрипт: `scenes/streaming_world_loader.gd`
+
+Умеет:
+
+- находить все доступные `ADT` тайлы в `World/Maps/Azeroth`;
+- загружать/выгружать тайлы по мере перемещения;
+- строить chunk mesh по LOD;
+- отдельно добавлять воду на тайл;
+- работать и в runtime, и в editor.
+
+## Editor streaming
+
+`StreamingWorld` теперь умеет подгружать мир прямо в editor по мере движения камеры viewport.
+
+Ключевые export-поля:
+
+- `editor_preview_enabled`
+- `editor_follow_view_camera`
+- `editor_preview_center_x`
+- `editor_preview_center_y`
+- `editor_preview_tile_radius`
+- `editor_reload_now`
+
+Логика такая:
+
+- `editor_preview_center_x/y` задают anchor, который сдвигается к `origin`, чтобы мир было удобно смотреть в Godot;
+- при `editor_follow_view_camera = true` стриминг идёт вокруг положения editor camera в 3D viewport;
+- тайлы и их children появляются под `Terrain` в Scene Tree.
+
+Это нужно, чтобы визуально проверить, что мир действительно собирается по мере перемещения по карте, а не только как статичный превью-блок.
+
+## Runtime streaming и LOD
+
+В runtime `StreamingWorld`:
+
+- подгружает `ADT` тайлы по расстоянию;
+- для terrain использует chunk-level LOD;
+- хранит дальний мир на грубом chunk LOD;
+- отдельно создаёт воду на тайл.
+
+Основные параметры:
+
+- `tiles_per_tick`
+- `chunk_ops_per_tick`
+- `lod0_radius_chunks`
+- `lod1_radius_chunks`
+- `lod2_radius_chunks`
+- `lod2_tile_radius`
+
+## Управление камерой
+
+Файл: `scenes/fly_camera.gd`
+
+Управление:
+
+- `RMB` удерживать для обзора;
+- `WASD` движение;
+- `Q/E` вниз/вверх;
+- `Shift` ускорение.
+
+## Что именно уже исправлено в terrain pipeline
+
+По сравнению с самым ранним состоянием проекта уже поправлены:
+
+- layout `MCNKHeader`;
+- offsets внутри `MCNK`;
+- чтение `MCVT`;
+- чтение `MCNR`;
+- legacy `MCAL`;
+- big alpha / compressed alpha;
+- корректные local coordinates внутри `ADT`-узла;
+- holes;
+- chunk winding/culling;
+- editor preview одного тайла;
+- streaming всего `Azeroth`;
+- первый проход `MH2O`.
+
+## Ограничения текущей версии
+
+- terrain текстурирование уже рабочее, но ещё не 1:1 как в клиенте/Noggit во всех edge cases;
+- water renderer сейчас базовый, без настоящих WoW water materials;
+- `WMO` читается отдельно, но world placement пока не подключён;
+- `M2` placements из `ADT` парсятся, но renderer нет;
+- `WDT` ещё не управляет составом мира;
+- проект сейчас ориентирован на просмотр и исследование данных, а не на полный round-trip import/export.
+
+## Ближайшие логичные шаги
+
+1. Подключить `WDT`, чтобы мир собирался не по сканированию папки, а по данным карты.
+2. Интегрировать `WMO` placement в `StreamingWorld`.
+3. Добавить `M2` loader/renderer.
+4. Довести water shader.
+5. Начать editor-side инструменты для редактирования terrain/liquid/object placement.
+6. Подготовить формат сохранения обратно в WoW-совместимые структуры.
+
+## Быстрый старт
+
+1. Положить клиент WoW 3.3.5a в `sources/` или указать путь через plugin.
+2. Собрать расширение:
+
+```bat
+cd gdextension
+build.bat Release
+```
+
+3. Извлечь данные в `res://extracted` через `MPQ Extractor`.
+4. Открыть одну из сцен:
+   - `maps/adt_tile_preview.tscn`
+   - `maps/test.tscn`
+   - `maps/eastern_kingdoms_streaming.tscn`
+
+Если нужен именно просмотр мира в editor по движению камеры, используй:
+
+- `maps/eastern_kingdoms_streaming.tscn`
+- `editor_preview_enabled = true`
+- `editor_follow_view_camera = true`