OpenWC

Портирование клиента World of Warcraft 3.3.5a (12340) на Godot 4.6.

Текущий фокус проекта: загрузка данных из клиента, разбор форматов WoW и отображение мира в Godot так, чтобы его можно было смотреть и дальше редактировать уже средствами движка.

Сейчас проект уже умеет:

• открывать MPQ-архивы клиента через editor plugin;
• извлекать файлы из MPQ в res://data/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, без модификаций.
• data/extracted/
  • извлечённые из MPQ файлы, с которыми работает Godot.
• data/cache/
  • generated/offline cache: baked terrain, M2 GLB cache, WMO scene cache. Эти файлы не являются исходниками проекта и игнорируются git.
• addons/mpq_extractor/
  • editor plugin и GDScript-сборщики сцен.
• src/native/
  • C++ GDExtension: MPQ, BLP, ADT, WMO.
• src/scenes/
  • готовые сцены для просмотра мира.
• src/tools/
  • bake/conversion scripts.
• src/resources/
  • Godot resources, generated GLB assets and runtime resource scripts.
• reference/
  • external reference sources/tools: Blender WoW Studio, wow.export and Noggit RED. Runtime-project must not depend on this directory.
• reference/noggit-red/
  • Noggit RED source reference for WoW 3.3.5 map editing, ADT/WMO/M2 placement behavior and UID workflows.
  • внешние reference sources и tools для сверки форматов. Runtime-проект не должен зависеть от этой директории.
• third_party/
  • godot-cpp, StormLib и другие зависимости.

Требования

• Windows
• Godot 4.6
• Visual Studio 2022 с C++ workload
• CMake
• клиент WoW 3.3.5a (12340)

Сборка

Собрать GDExtension:

cd src\native
build.bat Release

После успешной сборки DLL появится в:

addons/mpq_extractor/bin/

VS Code/CMake использует src/native как cmake.sourceDirectory.

Подготовка данных

По умолчанию plugin смотрит на клиент в:

res://sources

И извлекает файлы в:

res://data/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 оно пока не подключено.

Export/bake scripts

Все проектные скрипты экспорта и запекания лежат в src/tools/. Скрипты с расширением .gd запускаются через Godot headless и требуют собранный GDExtension, потому что используют ADTLoader, M2Loader и WMOLoader. Перед запуском данные клиента должны быть извлечены в res://data/extracted.

Если godot не добавлен в PATH, используй путь из .vscode/settings.json, например:

& 'c:\Godot 4.6\Godot_v4.6.1-stable_win64.exe' --headless --path . --script res://src/tools/bake_all.gd -- --map Azeroth --force

src/tools/bake_all.gd

Запекает terrain, M2 doodads и WMO objects за один проход.

godot --headless --path . --script res://src/tools/bake_all.gd -- --map Azeroth --force

Основные аргументы:

• --map Azeroth
• --extracted res://data/extracted
• --terrain-output res://data/cache/baked_terrain_v2
• --m2-output res://data/cache/m2_glb
• --wmo-output res://data/cache/wmo_tscn
• --full-texture-size 2048
• --coarse-texture-size 512
• --skip-terrain, --skip-m2, --skip-wmo
• --force

src/tools/bake_adt_terrain_cache.gd

Запекает terrain tiles в .res ресурсы BakedADTTile. Runtime streaming читает их из baked_tile_cache_dir.

godot --headless --path . --script res://src/tools/bake_adt_terrain_cache.gd -- --map Azeroth --output res://data/cache/baked_terrain_v2 --force

Основные аргументы:

• --map Azeroth
• --extracted res://data/extracted
• --output res://data/cache/baked_terrain_v2
• --tile-x 32, --tile-y 48 для одного тайла
• --full-texture-size 2048
• --coarse-texture-size 512
• --texture-size N legacy alias для обоих размеров
• --force

src/tools/bake_m2_cache.gd

Сканирует ADT tiles, собирает уникальные M2 paths и запекает M2 doodads в PackedScene .tscn.

godot --headless --path . --script res://src/tools/bake_m2_cache.gd -- --map Azeroth --output res://data/cache/m2_glb --force

Основные аргументы:

• --map Azeroth
• --extracted res://data/extracted
• --output res://data/cache/m2_glb
• --force

src/tools/bake_wmo_cache.gd

Сканирует ADT tiles, собирает уникальные WMO paths и запекает WMO world objects в PackedScene .tscn.

godot --headless --path . --script res://src/tools/bake_wmo_cache.gd -- --map Azeroth --output res://data/cache/wmo_tscn --force

Основные аргументы:

• --map Azeroth
• --extracted res://data/extracted
• --output res://data/cache/wmo_tscn
• --force

src/tools/collect_world_m2_list.gd

Сканирует ADT tiles и сохраняет список уникальных M2 paths. Полезно перед массовой конвертацией или для оценки объема M2 cache.

godot --headless --path . --script res://src/tools/collect_world_m2_list.gd -- --map Azeroth --output res://data/cache/m2_glb/Azeroth_m2_list.txt

Основные аргументы:

• --map Azeroth
• --extracted res://data/extracted
• --output res://data/cache/m2_glb/Azeroth_m2_list.txt

src/tools/m2_to_gltf.py

Python converter для WoW 3.3.5 M2 v264 в GLTF 2.0 .glb. Также экспортирует texture layers рядом с GLB. Для DXT BLP decoding нужен Pillow.

Один M2:

python src/tools/m2_to_gltf.py data/extracted/Character/BloodElf/Female/BloodElfFemale.M2 src/resources/characters/BloodElf/Female

Рекурсивная конвертация:

python src/tools/m2_to_gltf.py --all data/extracted/Character --out src/resources/characters

Аргументы:

• input путь к одному .M2
• output_dir директория вывода для одного .M2
• --all SEARCH_DIR рекурсивно конвертирует все .M2 под директорией
• --out OUT_ROOT root вывода для --all; по умолчанию src/resources

Reference-only export scripts

В reference/ лежат внешние скрипты и исходники для сверки форматов, включая Blender/WoW export tools из reference/ и reference/wow.export/. Они не являются частью project pipeline, не вызываются runtime-кодом и не должны использоваться как источник project cache без явного переноса в src/tools/.

Найденные reference scripts, связанные с export/conversion:

• reference/blender-wow-studio-3.4-1.1.0_Experimental/io_scene_wmo/m2/export_m2.py
• reference/blender-wow-studio-3.4-1.1.0_Experimental/io_scene_wmo/m2/operations/convert_m2_bones.py
• reference/blender-wow-studio-3.4-1.1.0_Experimental/io_scene_wmo/m2/operations/m2_export_validation.py
• reference/blender-wow-studio-3.4-1.1.0_Experimental/io_scene_wmo/wmo/export_wmo.py
• reference/wow.export/addons/blender/io_scene_wowobj/animation_processor.py
• reference/wow.export/addons/blender/io_scene_wowobj/import_wowobj.py
• reference/wow.export/addons/blender/io_scene_wowobj/__init__.py

toolbar.py files в reference UI directories относятся к Blender UI этих внешних tools и не являются самостоятельными export/bake entrypoints.

reference/noggit-red/ is not an export script collection. It is a source reference for WoW 3.3.5 map editing behavior: ADT/WMO/M2 placement, UID handling, map editing workflows and related editor code.

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 на группу;
• назначить базовые материалы.

Сцены просмотра

src/scenes/streaming/test.tscn

Файл: src/scenes/streaming/test.tscn

Тестовая сцена, которая грузит квадрат тайлов вокруг центра карты.

Скрипт: src/scenes/streaming/test_world_loader.gd

Подходит для:

• быстрой проверки terrain;
• отладки парсинга ADT;
• проверки AABB и координат.

src/scenes/preview/adt_tile_preview.tscn

Файл: src/scenes/preview/adt_tile_preview.tscn

Preview одного ADT прямо в editor.

Скрипт: src/scenes/preview/adt_tile_preview.gd

Полезно для:

• проверки одного конкретного тайла;
• отладки terrain layers;
• проверки воды и дыр по отдельному ADT.

Основные export-поля:

• map_name
• tile_x
• tile_y
• reload_now

src/scenes/streaming/eastern_kingdoms_streaming.tscn

Файл: src/scenes/streaming/eastern_kingdoms_streaming.tscn

Главная сцена для стриминга мира.

Скрипт: src/scenes/streaming/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

Управление камерой

Файл: src/scenes/camera/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. Собрать расширение:

cd src\native
build.bat Release

3. Извлечь данные в res://data/extracted через MPQ Extractor.
4. Открыть одну из сцен:
   • src/scenes/preview/adt_tile_preview.tscn
   • src/scenes/streaming/test.tscn
   • src/scenes/streaming/eastern_kingdoms_streaming.tscn

Если нужен именно просмотр мира в editor по движению камеры, используй:

• src/scenes/streaming/eastern_kingdoms_streaming.tscn
• editor_preview_enabled = true
• editor_follow_view_camera = true