open-wc/README.md

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:

cd gdextension
build.bat Release

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

addons/mpq_extractor/bin/

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

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

res://sources

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

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. Собрать расширение:

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