743 lines
39 KiB
Markdown
743 lines
39 KiB
Markdown
# Renderer Notes
|
||
|
||
Цель renderer-работы в этом проекте: добиться ощущения производительности оригинального клиента WoW 3.3.5a в Godot, без видимых фризов при переходе ADT -> ADT и без постоянного отката видимых участков к низкому качеству.
|
||
|
||
Этот документ фиксирует текущее состояние рендера, сделанные оптимизации и практические правила дальнейшей работы.
|
||
|
||
## Главный принцип
|
||
|
||
Оригинальный клиент WoW выживал на слабых CPU за счет агрессивного сокращения CPU work:
|
||
|
||
- мало draw calls;
|
||
- крупные батчи terrain;
|
||
- instancing/батчинг повторяющихся props;
|
||
- ленивое и заранее подготовленное подключение деталей;
|
||
- отдельные LOD/visibility решения для terrain, M2 и WMO;
|
||
- заранее подготовленные mipmaps и компактные texture formats.
|
||
|
||
В Godot мы идем тем же путем: runtime не должен строить тяжелую геометрию, декодировать много текстур или инстанцировать большие сцены в момент, когда игрок пересекает границу ADT.
|
||
|
||
## Основные файлы
|
||
|
||
- `src/scenes/streaming/streaming_world_loader.gd` - главный runtime streamer мира.
|
||
- `src/scenes/streaming/eastern_kingdoms_streaming.tscn` - текущая сцена для проверки Azeroth/Eastern Kingdoms.
|
||
- `addons/mpq_extractor/loaders/adt_builder.gd` - сборка ADT terrain, control splat материалов и MH2O liquids.
|
||
- `addons/mpq_extractor/loaders/m2_builder.gd` - сборка статического M2 mesh/material.
|
||
- `addons/mpq_extractor/loaders/wmo_builder.gd` - сборка WMO group meshes, doodads и MLIQ liquids.
|
||
- `addons/mpq_extractor/loaders/wow_liquid_material.gd` - общий shader material для ADT/WMO жидкостей.
|
||
- `src/scenes/sky/wow_sky_controller.gd` - DBC-based outdoor lighting/sky controller.
|
||
- `src/scenes/player/third_person_wow_controller.gd` - тестовый third-person controller.
|
||
- `src/native/src/adt_loader.cpp` - ADT/MH2O parsing.
|
||
- `src/native/src/blp_loader.cpp` - BLP decoding.
|
||
- `src/native/src/m2_loader.cpp` / `.h` - M2/SKIN parsing.
|
||
- `src/native/src/wmo_loader.cpp` - WMO/MLIQ parsing.
|
||
|
||
## Runtime Streaming
|
||
|
||
`StreamingWorldLoader` строит мир вокруг focus/camera/player. Карта берется из `WDT`, поэтому для Azeroth загружается реальный список ADT tiles, например:
|
||
|
||
```text
|
||
StreamingWorld: loaded 687 ADT tiles from WDT for Azeroth
|
||
```
|
||
|
||
Важные runtime очереди:
|
||
|
||
- `tile` - загрузка/парсинг ADT tile.
|
||
- `terrainup` - upgrade terrain до полного качества.
|
||
- `terrainctl` - подключение control splat terrain cache.
|
||
- `terrainsplat` - legacy/high quality splat path, сейчас не основной путь.
|
||
- `detail` - запуск деталей tile.
|
||
- `m2task` - background grouping M2 placements.
|
||
- `m2mesh` - загрузка/финализация M2 mesh resource.
|
||
- `m2build` - создание MultiMesh групп.
|
||
- `wmobuild` - подключение WMO instances.
|
||
- `wmogroups` - подключение render-cache групп WMO.
|
||
- `lod+` / `lod-` - создание/удаление tile LOD.
|
||
- `chunk+` / `chunk-` - legacy chunk mesh ops.
|
||
|
||
Фриз-профили пишутся строками вида:
|
||
|
||
```text
|
||
HITCH 22.75ms refresh=false queues[...] terrainup=21.99 terrainq=0.28 m2build=0.08
|
||
```
|
||
|
||
Главный смысл этих логов: если hitch больше порога, смотреть самый большой named section. Мы уже находили так bottlenecks:
|
||
|
||
- `details=4000-5800ms` - тяжелая синхронная сборка деталей.
|
||
- `m2build=20-75ms` - слишком крупные MultiMesh записи за один frame.
|
||
- `wmobuild=300-1100ms` - тяжелое инстанцирование WMO `.tscn`.
|
||
- `terrainsplat=150-220ms` - runtime high-quality splat generation.
|
||
- `terrainup=20-45ms` - слишком дорогой upgrade terrain за frame.
|
||
|
||
## Quality Presets And Budgets
|
||
|
||
Главные настройки находятся в `streaming_world_loader.gd`:
|
||
|
||
- `quality_preset`: `Performance`, `Balanced`, `High`, `Custom`.
|
||
- `tiles_per_tick`
|
||
- `max_concurrent_tile_tasks`
|
||
- `tile_finalize_ops_per_tick`
|
||
- `terrain_upgrade_finalize_ops_per_tick`
|
||
- `terrain_control_splat_cache_finalize_ops_per_tick`
|
||
- `m2_build_groups_per_tick`
|
||
- `m2_multimesh_batch_size`
|
||
- `m2_mesh_finalize_ops_per_tick`
|
||
- `wmo_build_instances_per_tick`
|
||
- `wmo_render_group_ops_per_tick`
|
||
|
||
Практическое правило: если новая оптимизация возвращает hitch, сначала уменьшать per-frame budgets, а не отключать качество целиком. Видимое качество должно приходить заранее, вне поля зрения игрока.
|
||
|
||
## Terrain Rendering
|
||
|
||
### Старый подход
|
||
|
||
Изначально terrain мог быть слишком мелко разбитым:
|
||
|
||
- много chunk/node операций;
|
||
- отдельные материалы/меши;
|
||
- слабый контроль над моментом upgrade;
|
||
- низкое качество или мыло при возврате в уже посещенный участок.
|
||
|
||
Это приводило к CPU overhead и видимому popping.
|
||
|
||
### Текущий подход
|
||
|
||
Основной путь качества сейчас - `ControlSplatADTTile`:
|
||
|
||
- geometry хранится как готовый tile mesh;
|
||
- texture set собирается в `Texture2DArray`;
|
||
- alpha maps собираются в один atlas;
|
||
- layer ids хранятся в layer index map;
|
||
- material подключается через `ADTBuilder.apply_control_splat_material`;
|
||
- runtime должен только загрузить cache resource и применить material, а не пересобирать splat texture на лету.
|
||
|
||
Кеш:
|
||
|
||
```text
|
||
res://data/cache/terrain_control_splat_v3/<Map>/<Map>_<x>_<y>.res
|
||
```
|
||
|
||
Формат:
|
||
|
||
```text
|
||
ControlSplatADTTile.FORMAT_VERSION = 3
|
||
StreamingWorldLoader.REQUIRED_CONTROL_SPLAT_TILE_FORMAT_VERSION = 3
|
||
```
|
||
|
||
Команда bake:
|
||
|
||
```powershell
|
||
$exe = Join-Path $env:TEMP 'godot-4.6.1-openwc\Godot_v4.6.1-stable_win64.exe'
|
||
& $exe --headless --path . --script res://src/tools/build_adt_control_splat_cache.gd -- --map Azeroth --jobs auto --texture-size 256 --lod 0 --force
|
||
```
|
||
|
||
Важно: `--force` пересобирает cache. Не запускать его случайно, если задача не про bake.
|
||
|
||
### Texture Quality
|
||
|
||
Что было сделано:
|
||
|
||
- перешли от baked albedo как основного visible quality к control splat;
|
||
- оставили baked/streaming terrain как fallback и warm path;
|
||
- добавили/используем full quality terrain радиус;
|
||
- добавили retention/cache для full-quality meshes, чтобы возврат в tile не сбрасывал видимый участок обратно в низкое качество;
|
||
- добавили логи `TERRAIN_QUALITY`, чтобы понимать, когда видимый набор tile действительно готов.
|
||
|
||
Ключевые настройки:
|
||
|
||
- `terrain_full_quality_enabled`
|
||
- `terrain_full_quality_radius_tiles`
|
||
- `terrain_control_splat_quality_enabled`
|
||
- `terrain_control_splat_primary`
|
||
- `terrain_control_splat_radius_tiles`
|
||
- `max_active_terrain_control_splat_tiles`
|
||
- `terrain_quality_mesh_cache_limit`
|
||
- `prewarm_tile_margin`
|
||
- `retain_tile_margin`
|
||
- `full_lod_prewarm_tiles`
|
||
- `boundary_prefetch_threshold`
|
||
|
||
Правило для High: игрок не должен видеть low-res terrain под ногами или прямо перед собой. Low quality допустим только далеко или вне видимости.
|
||
|
||
### Texture Seams
|
||
|
||
Была проблема видимых стыков и неправильного повторения texture pattern между чанками. Исправление в shader control splat:
|
||
|
||
- terrain texture sample теперь использует continuous `chunk_uv`, а не `local_uv`;
|
||
- alpha atlas sample clamp'ится внутри 64x64 chunk alpha cell;
|
||
- это уменьшает видимые seams на границах MCNK.
|
||
|
||
Файл: `addons/mpq_extractor/loaders/adt_builder.gd`, `_get_control_splat_shader()`.
|
||
|
||
## ADT Baking
|
||
|
||
Были ускорены bake scripts. Главный рабочий bake для качества terrain:
|
||
|
||
```text
|
||
src/tools/build_adt_control_splat_cache.gd
|
||
```
|
||
|
||
Что важно:
|
||
|
||
- параллельные workers;
|
||
- cache resource на ADT tile;
|
||
- не пересобирать в runtime;
|
||
- incomplete tile считается ошибкой worker и выводится warning;
|
||
- cache лежит в `data/cache` и не должен попадать в git.
|
||
|
||
Пример успешного результата:
|
||
|
||
```text
|
||
Starting parallel ADT control splat cache: jobs=15
|
||
Parallel control splat cache finished. jobs=15 failed_workers=0 elapsed=...
|
||
```
|
||
|
||
Если один worker падает:
|
||
|
||
```text
|
||
WARNING: Control splat produced incomplete tile: ...
|
||
failed_workers=1
|
||
```
|
||
|
||
Такой tile надо перезапечь отдельно или проверить исходный ADT.
|
||
|
||
## M2 Rendering
|
||
|
||
Цель: тысячи props не должны быть тысячами независимых Node3D/MeshInstance3D.
|
||
|
||
Текущий подход:
|
||
|
||
- ADT `MDDF` placements группируются по M2 path;
|
||
- для каждого M2 path создается один или несколько `MultiMeshInstance3D`;
|
||
- transforms пишутся батчами через `m2_multimesh_batch_size`;
|
||
- mesh/resource finalization ограничен `m2_mesh_finalize_ops_per_tick`;
|
||
- build групп ограничен `m2_build_groups_per_tick`.
|
||
|
||
Это убрало большие `m2build` фризы, где раньше один frame мог тратить 20-75ms только на M2.
|
||
|
||
Кеш:
|
||
|
||
```text
|
||
res://data/cache/m2_glb
|
||
```
|
||
|
||
Скрипты:
|
||
|
||
```text
|
||
src/tools/bake_m2_cache.gd
|
||
src/tools/collect_world_m2_list.gd
|
||
src/tools/m2_to_gltf.py
|
||
```
|
||
|
||
Что улучшали:
|
||
|
||
- M2 parser читает дополнительные material/texture/batch данные;
|
||
- BLP alpha fixes улучшили прозрачность листвы/декора;
|
||
- `M2Builder` улучшен для texture/material setup;
|
||
- runtime M2 строится через MultiMesh, а не как дерево отдельных props.
|
||
|
||
Ограничения:
|
||
|
||
- M2 animation/skinning пока не полноценные;
|
||
- particles/ribbons не реализованы;
|
||
- WoW material flags не полностью совпадают;
|
||
- billboards/leaf bones пока не как в клиенте.
|
||
|
||
### M2 Animation Research
|
||
|
||
Проверка по `reference/whoa`, `reference/open-realm` и `reference/wow.export` показала, что анимации M2 нельзя надежно тащить как обычный Godot/glTF skeletal mesh.
|
||
|
||
Оригинальная схема M2:
|
||
|
||
- для каждой кости считается матрица через pivot transform: translation/rotation/scale вокруг `bone.pivot`;
|
||
- parent chain считается вручную;
|
||
- каждый skin section использует свой bone palette через `bone_combo_index`;
|
||
- vertex bone indices интерпретируются относительно palette текущего skin section.
|
||
|
||
Именно так делают:
|
||
|
||
- `reference/whoa/src/model/CM2Model.cpp` - расчет `m_boneMatrices`;
|
||
- `reference/whoa/src/model/CM2SceneRender.cpp` - upload bone palette из `boneCombos`;
|
||
- `reference/open-realm/games/world-of-warcraft/renderer/m2/r_m2.c` - `M2_CalculateBoneMatrices` и `M2_UploadBatchBones`;
|
||
- `reference/wow.export/src/js/3D/renderers/M2RendererGL.js` - ручной pivot-based runtime skinning.
|
||
|
||
Вывод: старый экспериментальный путь через cached GLB ломал композитные doodad M2, потому что анимировал node с bind-pivot translation напрямую. Конвертер переведен на схему `pivot node -> animated bone node`, аналогичную wow.export `modelsExportWithBonePrefix`.
|
||
|
||
Runtime принимает для M2-анимаций только GLB с меткой:
|
||
|
||
```text
|
||
asset.extras.openwc_m2_anim_schema = pivot_prefix_v1
|
||
```
|
||
|
||
Это защищает мир от старых битых GLB cache. Точечно пересобраны тестовые animated M2:
|
||
|
||
```text
|
||
data/cache/m2_glb/GryphonRoost01.glb
|
||
data/cache/m2_glb/Fish.glb
|
||
data/cache/m2_glb/eagle.glb
|
||
```
|
||
|
||
Ограничение runtime:
|
||
|
||
```text
|
||
enable_m2_animated_instances = true
|
||
m2_animated_max_primitives = 3
|
||
m2_animated_denylist_patterns = ["gryphonroost"]
|
||
m2_animated_allowlist_patterns = ["creature/fish/", "creature/eagle/", "world/critter/"]
|
||
```
|
||
|
||
`GryphonRoost` stays out of the animated GLB path. The cached GLB has `Stand`
|
||
tracks, but the current converter/runtime breaks its composite skin/material layout.
|
||
Use the native M2 runtime path for this class of doodad; the old GLB animation
|
||
path remains disabled for `gryphonroost`.
|
||
|
||
Native M2 animation first pass for composite doodads:
|
||
|
||
- `M2Loader.load_m2_animated()` parses M2 bones, Stand track keys, `.skin` bone lookup/palette data, and expanded skinned surfaces.
|
||
- `M2NativeAnimatedBuilder` builds a regular `ArrayMesh` and keeps the original per-surface skin data.
|
||
- `M2NativeAnimator` evaluates the selected Stand sequence and applies WoW-style bone matrices:
|
||
`T(pivot + translation) * R * S * T(-pivot) * parent`.
|
||
- Vertex influences are resolved through `.skin` local bone indices and the M2 `boneCombos` palette, matching the original section/batch renderer model used by WoW/whoa.
|
||
- `StreamingWorldLoader` routes only `gryphonroost` through this native path; simple critters still use the existing GLB allowlist and most M2 world props stay on static MultiMesh.
|
||
- Current implementation rebuilds the animated `ArrayMesh` on CPU. This is correct enough for the problematic rare doodads and gives us the same data layout that can later move to shader/GPU skinning.
|
||
|
||
Причина: композитные doodad вроде `GryphonRoost` снова ломают визуал при GLB-анимации. До M2-native renderer все world placement M2 должны оставаться статическими. GLB-анимация оставлена только как вручную включаемый debug experiment через allowlist.
|
||
|
||
Дополнительно static M2 cache lookup ищет both original-case and lowercase paths. Это важно для ADT paths вроде `world/GENERIC/...`, потому что запеченный nested cache лежит lowercase. Static path также не использует GLB с `pivot_prefix_v1`, чтобы animated test cache не мог подменить корректный `.tscn`.
|
||
|
||
Полноценный M2-native animation renderer/cache все еще остается правильным долгосрочным решением для 1:1 поведения, particles/ribbons и производительности на большом количестве animated props.
|
||
|
||
### Blizzlike Shader Research
|
||
|
||
Идея для следующего visual fidelity слоя: уходить от Godot `StandardMaterial3D` для WoW assets к собственным WoW-style `ShaderMaterial`.
|
||
|
||
Что видно по whoa:
|
||
|
||
- M2 использует маленькие shader permutations вроде `Diffuse_T1`, `Diffuse_T2`, `Diffuse_Env`, `Combiners_Mod`, `Combiners_Add`, `Combiners_Mod2x`;
|
||
- material state задается отдельно: blend mode, alpha ref, culling, depth test/write;
|
||
- light model старый и ручной: ambient + diffuse + emissive + fog constants, а не PBR;
|
||
- texture stages учитывают wrap/clamp, texture transform matrices и env/sphere map.
|
||
|
||
Практический вывод для проекта:
|
||
|
||
- terrain уже ближе к WoW, потому что использует `ShaderMaterial` и ручной light/fog;
|
||
- M2/WMO пока используют `StandardMaterial3D`, поэтому выглядят не совсем blizzlike;
|
||
- следующий шаг - `wow_m2_material` / `wow_wmo_material` с WoW blend modes, alpha ref, combiners и ручным fog/light.
|
||
|
||
### M2 ShaderMaterial First Pass
|
||
|
||
Implemented file: `addons/mpq_extractor/loaders/wow_m2_material.gd`.
|
||
|
||
`M2Builder._build_material()` now returns a WoW-style `ShaderMaterial` instead of `StandardMaterial3D`. The same path is reused by `M2NativeAnimatedBuilder`, so static M2 batches and the native animated `gryphonroost` path share material behavior.
|
||
|
||
Current M2 shader layer:
|
||
|
||
- maps M2 blend modes 0..6 to Godot shader variants: opaque, alpha-key, alpha blend, additive, mod and mod2x approximation;
|
||
- uses alpha reference values observed in `reference/whoa/src/model/CM2SceneRender.cpp`: 0 for opaque, about 0.878 for alpha-key, 1/255 for blended passes;
|
||
- applies M2 render flags for unlit (`0x01`), two-sided/culling (`0x04`), depth test (`0x08`) and depth write (`0x10`);
|
||
- keeps BLP mipmap generation and anisotropic sampler hints;
|
||
- respects M2 texture wrap flags by compiling repeat/clamp shader variants;
|
||
- `M2Loader` exposes UV2, `texture_coord_combos`, `texture_combiner_combos`, `m2_flags`, batch `shader_id`, `texture_count` and texture-coordinate combo indices;
|
||
- `M2Loader` also exposes `m2_colors`, `texture_weights`, `texture_transforms`, `texture_weight_combos` and `texture_transform_combos`;
|
||
- `M2Builder` now resolves the first two texture stages from texture combos and passes combiner state into `WowM2Material`;
|
||
- `WowM2Material` has a first-pass implementation for combiner ops: opaque, mod, decal/fade, add, mod2x, mod2xNA/addNA and a cheap env-map UV approximation;
|
||
- static M2 color/alpha tracks and texture weight tracks are applied to `mesh_color`, matching the `whoa` render path where batch alpha is multiplied by color alpha and texture weight;
|
||
- static texture transform translation/scale is applied per texture stage through shader UV transform uniforms;
|
||
- animated texture transform translation tracks are approximated as GPU UV scroll (`translation_speed * TIME`) per texture stage, without per-frame CPU material updates;
|
||
- native animated M2 rebuild path preserves UV2 and the same material combiner state.
|
||
- uses a simple old-client-style ambient + diffuse light model and disables PBR/specular behavior.
|
||
|
||
Known limits:
|
||
|
||
- only the first two texture stages are represented;
|
||
- texture transform translation animation is supported as linear UV scroll; rotation/scale texture animation and time-varying color/weight tracks are still future work;
|
||
- exact env/sphere map math, model emissive tracks and full WoW render-state parity are still future work;
|
||
- WMO has a matching first-pass shader layer, but still needs full material flag parity.
|
||
|
||
### WMO ShaderMaterial First Pass
|
||
|
||
Implemented file: `addons/mpq_extractor/loaders/wow_wmo_material.gd`.
|
||
|
||
`WMOBuilder._build_material()` now returns a WoW-style `ShaderMaterial` instead of `StandardMaterial3D`. WMO group meshes already carry `Mesh.ARRAY_COLOR` from group vertex colors, so the shader treats WMO as mostly baked-lit geometry:
|
||
|
||
- blend modes 0..2 map to opaque, alpha-key and alpha blend variants;
|
||
- alpha-key uses discard instead of transparent sorting;
|
||
- texture repeat stays enabled for WMO wall/floor tiling;
|
||
- BLP mipmap generation and anisotropic sampler hints are preserved;
|
||
- shader is `unshaded` and multiplies texture color by WMO vertex color with a small ambient floor;
|
||
- DBC zone light is applied as a soft tint only, so baked WMO vertex colors and texture albedo stay readable;
|
||
- `color2` is passed as a secondary/detail tint, and `texture2` is used as a fallback detail texture when `texture1` is absent;
|
||
- `WMOLoader` exposes MOMT `diffuse_color`, `emissive_color`, `texture1`, `texture2`, `flags2` and `color2`;
|
||
- `WMOBuilder` loads `texture1` as a conservative secondary detail/multiply layer and passes MOMT diffuse/emissive colors into the shader;
|
||
- culling is disabled like the previous WMO material path, which avoids missing interior/backface geometry.
|
||
|
||
Known limits:
|
||
|
||
- deeper MOMT shader semantics, exact secondary texture mode and `texture2` usage are still approximate;
|
||
- WMO fog/light constants are not wired into this material yet;
|
||
- this first pass prioritizes matching old-client baked lighting behavior over physical lighting.
|
||
|
||
## WMO Rendering
|
||
|
||
Цель: WMO не должны фризить сцену при догрузке, особенно большие здания/города.
|
||
|
||
Что сделано:
|
||
|
||
- `WMOLoader` читает root/group WMO данные и MLIQ;
|
||
- `WMOBuilder` строит group meshes;
|
||
- runtime registry дедуплицирует WMO по `unique_id`;
|
||
- WMO на границе ADT не дублируются;
|
||
- большие WMO не должны инстанцироваться как тяжелые `.tscn` во время движения;
|
||
- добавлен lightweight render-cache path для WMO groups;
|
||
- `wmo_render_group_ops_per_tick` ограничивает подключение WMO groups по кадрам;
|
||
- `wmo_max_runtime_scene_mb` защищает от тяжелого runtime `.tscn` instantiate.
|
||
|
||
Кеши:
|
||
|
||
```text
|
||
res://data/cache/wmo_tscn
|
||
res://data/cache/wmo_render_v1
|
||
```
|
||
|
||
Скрипты:
|
||
|
||
```text
|
||
src/tools/bake_wmo_cache.gd
|
||
src/tools/build_wmo_streaming_cache.gd
|
||
```
|
||
|
||
Что улучшали по качеству:
|
||
|
||
- включен texture repeat для WMO materials;
|
||
- улучшены BLP alpha/texture decode проблемы;
|
||
- WMO liquid mesh получает нормали/UV;
|
||
- WMO liquids используют общий `WowLiquidMaterial`.
|
||
|
||
Ограничения:
|
||
|
||
- portal/room based visibility WMO пока не повторяет клиент;
|
||
- occluders не являются полноценной заменой WoW portal culling;
|
||
- часть WMO material flags еще требует сверки с клиентом.
|
||
|
||
## Liquids
|
||
|
||
Open-realm не дал готовую реализацию water shader: в его docs liquid rendering отмечен как future pass. Поэтому добавлен собственный легкий Godot shader.
|
||
|
||
Файл:
|
||
|
||
```text
|
||
addons/mpq_extractor/loaders/wow_liquid_material.gd
|
||
```
|
||
|
||
Подключение:
|
||
|
||
- ADT `MH2O` через `ADTBuilder.build_tile_water_scene`;
|
||
- WMO `MLIQ` через `WMOBuilder._build_group_liquid`.
|
||
- Для cached terrain tiles (`streaming_tile`/`baked_tile`) вода не хранится в terrain cache: `StreamingWorldLoader` запускает отдельную background ADT load task только для `MH2O`, затем на main thread прикрепляет `Water` node к уже созданному tile root.
|
||
|
||
Что делает shader:
|
||
|
||
- один общий `ShaderMaterial` cache для ADT/WMO;
|
||
- world-space animated ripples;
|
||
- fresnel highlight;
|
||
- отдельные цвета/параметры для water, magma, slime;
|
||
- без screen texture/refraction, чтобы не раздувать GPU cost;
|
||
- shadows у liquid mesh выключены.
|
||
|
||
Почему так:
|
||
|
||
- дешево;
|
||
- не грузит дополнительные textures;
|
||
- не создает D3D12 descriptor pressure;
|
||
- дает рабочую визуальную воду уже сейчас.
|
||
|
||
Ограничения:
|
||
|
||
- нет настоящего depth fade;
|
||
- нет shoreline foam/blending;
|
||
- LiquidType.dbc texture selection пока не используется;
|
||
- waterfalls/flowing water требуют отдельного M2/material path.
|
||
|
||
## Shared WoW Shader Globals
|
||
|
||
Current terrain/M2/WMO/liquid shaders are intentionally `unshaded`: Godot lighting is not a good match for old WoW material rules, M2 blend modes, WMO baked vertex colors and control-splat terrain. To keep them visually tied to the active zone without updating every material instance, `WowSkyController` owns a shared global shader state:
|
||
|
||
```text
|
||
wow_ambient_color
|
||
wow_light_color
|
||
wow_light_dir
|
||
wow_fog_color
|
||
wow_fog_range
|
||
wow_fog_density
|
||
wow_sun_elevation
|
||
```
|
||
|
||
These parameters are registered through `RenderingServer.global_shader_parameter_add` and updated from `Light.dbc` / `LightParams.dbc` sampling in `src/scenes/sky/wow_sky_controller.gd`.
|
||
|
||
Consumers:
|
||
|
||
- `addons/mpq_extractor/loaders/adt_builder.gd`: control-splat, fallback layered terrain and single-texture terrain.
|
||
- `addons/mpq_extractor/loaders/wow_m2_material.gd`: M2 combiner material uses zone ambient/diffuse light and distance fog.
|
||
- `addons/mpq_extractor/loaders/wow_wmo_material.gd`: WMO material keeps baked vertex lighting, but tints it by zone light and applies distance fog.
|
||
- `addons/mpq_extractor/loaders/wow_liquid_material.gd`: liquids use the shared fog color/range/density.
|
||
|
||
The fog distance is computed from view-space position passed from `vertex()` to `fragment()`. This avoids per-camera material updates and keeps shader code compatible with Godot 4.6's spatial shader parser.
|
||
|
||
## Sky And Lighting
|
||
|
||
Добавлен `WowSkyController`:
|
||
|
||
```text
|
||
src/scenes/sky/wow_sky_controller.gd
|
||
```
|
||
|
||
Что он делает:
|
||
|
||
- читает DBC данные для light profiles;
|
||
- определяет текущую area/zone по позиции;
|
||
- выбирает lighting/fog profile;
|
||
- логирует `SKY_LIGHT`;
|
||
- поддерживает LightSkybox model loading;
|
||
- двигает skybox model за камерой/player.
|
||
|
||
Пример лога:
|
||
|
||
```text
|
||
SKY_LIGHT time=13.00 map=0 area=279:... zone=36:... profiles=[...] skybox=0 fog=614..31556 density=0.500
|
||
SKYBOX_MODEL id=... path=...
|
||
```
|
||
|
||
Ограничения:
|
||
|
||
- зона/skybox transitions еще требуют ручной сверки с клиентом;
|
||
- не все outdoor skybox models используются на всех локациях;
|
||
- lighting пока приближение, а не 1:1 с fixed-function клиентом.
|
||
|
||
## Shadows
|
||
|
||
Цель по производительности сейчас важнее полного совпадения dynamic shadows.
|
||
|
||
Текущее правило:
|
||
|
||
- terrain shadows выключены;
|
||
- M2 shadows выключены;
|
||
- WMO shadows выключены;
|
||
- liquid shadows выключены.
|
||
|
||
Настройки:
|
||
|
||
```text
|
||
terrain_cast_shadows
|
||
m2_cast_shadows
|
||
wmo_cast_shadows
|
||
```
|
||
|
||
Почему:
|
||
|
||
- old WoW 3.3.5a использовал очень дешевую модель теней;
|
||
- полноценные Godot realtime shadows на большом мире быстро создают лишний GPU/CPU cost;
|
||
- сначала нужна стабильная streaming performance, затем можно добавлять selective blob/projected shadows.
|
||
|
||
Для будущего: если брать идеи Cataclysm, делать не full dynamic shadows everywhere, а ограниченные character/near-object shadows с жестким distance budget.
|
||
|
||
## Third Person Controller
|
||
|
||
Добавлен тестовый контроллер для оценки рендера "с земли":
|
||
|
||
```text
|
||
src/scenes/player/third_person_wow_controller.gd
|
||
```
|
||
|
||
Зачем:
|
||
|
||
- свободная камера плохо показывает реальные проблемы игрока;
|
||
- нужен WoW-like темп перемещения;
|
||
- sprint нужен для стресс-теста ADT boundary streaming.
|
||
|
||
Модель сейчас не важна, используется простая capsule.
|
||
|
||
## Texture/BLP Work
|
||
|
||
Что сделано:
|
||
|
||
- BLP loader улучшен для alpha handling;
|
||
- texture mipmaps генерируются для runtime ImageTexture там, где texture создается из decoded BLP;
|
||
- для WMO/M2 материалов включается anisotropic/mipmap filtering там, где texture подключается;
|
||
- включен repeat для WMO материалов.
|
||
|
||
Важная проблема Godot/D3D12:
|
||
|
||
```text
|
||
Cannot create uniform set because there's not enough room in the RESOURCES descriptor heap.
|
||
Please increase rendering/rendering_device/d3d12/max_resource_descriptors.
|
||
```
|
||
|
||
Это возникает, когда renderer создает слишком много уникальных texture/uniform resources. Наши меры:
|
||
|
||
- кешировать materials/textures;
|
||
- не создавать уникальный heavy shader/material на каждый chunk;
|
||
- использовать `Texture2DArray` для terrain control splat;
|
||
- ограничивать активные high-quality terrain tiles;
|
||
- избегать screen/refraction textures для water.
|
||
|
||
Если ошибка возвращается, увеличивать project setting `rendering/rendering_device/d3d12/max_resource_descriptors` и одновременно искать, где плодятся уникальные материалы.
|
||
|
||
## Caches
|
||
|
||
Активные cache directories:
|
||
|
||
```text
|
||
res://data/cache/baked_terrain_v2
|
||
res://data/cache/baked_terrain_stream_v1
|
||
res://data/cache/terrain_control_splat_v3
|
||
res://data/cache/terrain_splat_v1
|
||
res://data/cache/m2_glb
|
||
res://data/cache/wmo_tscn
|
||
res://data/cache/wmo_render_v1
|
||
```
|
||
|
||
Правила:
|
||
|
||
- cache не коммитить;
|
||
- при изменении resource format bump'ать `FORMAT_VERSION`;
|
||
- при изменении shader/material без изменения cached resource иногда достаточно restart scene;
|
||
- при изменении baked geometry/resource payload нужен rebake;
|
||
- WMO render cache нужен для больших WMO, иначе будут `wmobuild` фризы.
|
||
|
||
Версии:
|
||
|
||
```text
|
||
Baked terrain required: 4
|
||
Splat terrain required: 1
|
||
Control splat required: 3
|
||
WMO streaming resource: 2
|
||
```
|
||
|
||
## Debug Logs
|
||
|
||
Важные логи:
|
||
|
||
```text
|
||
HITCH ...
|
||
PERF ...
|
||
TERRAIN_QUALITY ...
|
||
SKY_LIGHT ...
|
||
SKYBOX_MODEL ...
|
||
```
|
||
|
||
Как читать `HITCH`:
|
||
|
||
- если большой `terrainup` - full-quality terrain подключается слишком тяжело;
|
||
- если большой `terrainctl` - control splat cache финализация слишком дорогая;
|
||
- если большой `terrainsplat` - runtime splat path не должен быть включен для обычной игры;
|
||
- если большой `m2mesh` - mesh resource finalization надо сильнее дробить;
|
||
- если большой `m2build` - уменьшить `m2_build_groups_per_tick` или `m2_multimesh_batch_size`;
|
||
- если большой `wmobuild` - использовать render cache, уменьшить `wmo_build_instances_per_tick`;
|
||
- если большой `wmogroups` - уменьшить `wmo_render_group_ops_per_tick`.
|
||
|
||
## Reference Findings
|
||
|
||
По open-realm:
|
||
|
||
- полезен как документация форматов/пайплайна;
|
||
- terrain/ADT/WMO/M2 идеи можно сверять;
|
||
- полноценный liquid rendering там не реализован;
|
||
- skybox/liquid не стоит напрямую переносить как готовый код.
|
||
|
||
По WoW 3.3.5a:
|
||
|
||
- старый клиент не рендерил все как modern physically based renderer;
|
||
- он агрессивно экономил CPU;
|
||
- основная цель для нас - frame pacing и отсутствие hitch, а не дорогие эффекты.
|
||
|
||
## Commands
|
||
|
||
Headless smoke:
|
||
|
||
```powershell
|
||
$exe = Join-Path $env:TEMP 'godot-4.6.1-openwc\Godot_v4.6.1-stable_win64.exe'
|
||
& $exe --headless --path . --quit
|
||
```
|
||
|
||
Run scene headless:
|
||
|
||
```powershell
|
||
$exe = Join-Path $env:TEMP 'godot-4.6.1-openwc\Godot_v4.6.1-stable_win64.exe'
|
||
& $exe --headless --path . src/scenes/streaming/eastern_kingdoms_streaming.tscn --quit
|
||
```
|
||
|
||
Build native GDExtension:
|
||
|
||
```powershell
|
||
cd src\native
|
||
.\build.bat Release
|
||
```
|
||
|
||
Build ADT control splat cache:
|
||
|
||
```powershell
|
||
$exe = Join-Path $env:TEMP 'godot-4.6.1-openwc\Godot_v4.6.1-stable_win64.exe'
|
||
& $exe --headless --path . --script res://src/tools/build_adt_control_splat_cache.gd -- --map Azeroth --jobs auto --texture-size 256 --lod 0 --force
|
||
```
|
||
|
||
Build WMO render cache:
|
||
|
||
```powershell
|
||
$exe = Join-Path $env:TEMP 'godot-4.6.1-openwc\Godot_v4.6.1-stable_win64.exe'
|
||
& $exe --headless --path . --script res://src/tools/build_wmo_streaming_cache.gd -- --map Azeroth
|
||
```
|
||
|
||
## Current Known Gaps
|
||
|
||
- M2 animation/skinning.
|
||
- M2 particles/ribbons.
|
||
- Full WoW material flag parity. Current first pass covers common M2 combiners and WMO shader ids 0, 3, 5, 6, 8, 9, 12, 13, 15, 16, 17 approximately.
|
||
- True WMO portal/room culling.
|
||
- Selective cheap dynamic shadows.
|
||
- Liquid depth fade/shore blending.
|
||
- LiquidType.dbc based water textures.
|
||
- Better skybox transition validation per zone.
|
||
- Automated renderer regression scenes/screenshots.
|
||
|
||
## 2026-07-04 WMO Shader Pass
|
||
|
||
- WMO materials now consume shared `wow_light_dir` and `wow_sun_elevation` shader globals.
|
||
- Cached WMO meshes are refreshed at attach time, so already baked render-cache meshes can receive the latest WMO material shader without immediately rebuilding the whole WMO cache.
|
||
- The WMO shader now uses normals for a cheap WoW-style ambient + directional lighting term instead of relying only on texture * vertex color.
|
||
- Added approximate pixel shader branches for common WMO modes: diffuse, env, env metal, two-layer diffuse, terrain-style two-layer, diffuse emissive and mod2x variants.
|
||
- Still missing for true parity: second/third WMO vertex color streams, extra WMO texture coordinate sets, third+ texture samplers, exact env-map coordinate generation and portal/room visibility.
|
||
|
||
## 2026-07-04 M2 Shader Mapping Pass
|
||
|
||
- M2 material build now maps raw skin `shaderID` through the same vertex/pixel shader selection rules used by `wow.export`.
|
||
- `WowM2Material` receives `vertex_shader_id` and `pixel_shader_id` uniforms instead of relying only on generic two-stage ops.
|
||
- Vertex shader ids 0..18 now drive UV source selection, UV2 use, environment coordinates and edge-fade modes.
|
||
- Pixel shader ids 0..29 have first-pass two-texture combiner behavior for the common opaque/mod/add/mod2x/alpha cases.
|
||
- M2 materials now load and bind up to four texture combo entries. This enables first-pass support for glow/specular/crossfade/guild/const combiner cases that need `tex3` or `tex4`.
|
||
- Texture weight combos are exposed to the shader as `tex_sample_alpha`, matching the common WoW combiner weight slots.
|
||
- Native animated M2 surfaces use the same `_build_material()` path, so this also applies to runtime-animated M2 objects.
|
||
- Debug metadata is stored on materials: raw `wow_m2_shader_id`, mapped `wow_m2_vertex_shader_id`, and mapped `wow_m2_pixel_shader_id`.
|
||
- Transparent M2 passes such as waterfalls now avoid depth writes/prepass (`depth_draw_never`). This prevents layered alpha planes from self-occluding into white/solid webbing while keeping cutout foliage on the opaque-depth path.
|
||
- Scrolling alpha-blend M2 models with `waterfall` in the path get a conservative soft-alpha profile: lower opacity, stronger alpha falloff and UV-edge fade. This hides the rectangular card edges without changing normal foliage/cutout props.
|
||
- `.skin` texture unit `priority` is exposed as `priority_plane` for future transparent-pass ordering. This needs the native GDExtension DLL to be rebuilt when the editor is not holding it open.
|
||
- Waterfalls seen near terrain cliffs are usually WMO embedded doodads rather than ADT `MDDF` placements. WMO doodad transforms now use the converted MODD quaternion directly, without the old extra `+90 deg` M2 yaw offset.
|
||
- WMO render/scene caches now carry version guards for this transform path. Rebuild `wmo_render_v1`/`wmo_tscn` after changing WMO doodad placement code; old caches are ignored by runtime.
|
||
- Elwynn/Thunder Falls style outdoor waterfalls are ADT `MDDF` M2 placements. Regular ADT M2 doodads use the native cached Godot-space Euler directly via `Basis.from_euler(rot)`; do not apply a global yaw/order remap, because it flips ordinary props such as wagons, stalls, barrels, fences and trees. `ElwynnCliffRock01/02` are a model-specific exception: these are open-backed shell meshes, so they use a narrow `YZX` placement correction with `rot.y + 180 deg` to push the hollow side into the terrain. The waterfall transform correction is also filename-allowlisted to the actual sheet M2s (`NewWaterfall`, `ElwynnTallWaterfall01`). Sheet M2s keep the calibrated world-space `+90 deg` Godot-Y yaw to anchor the top to the upper pool, plus model-specific twist where needed. Tall waterfall sheets twist around their local fall line with an origin offset so top/bottom anchors stay fixed instead of rotating around the model pivot; `ElwynnTallWaterfall01` uses the opposite twist sign from `NewWaterfall` to face the correct side. Do not apply the raw-M2/WoWee render-space basis here; that double-converts M2 vertices. Do not cull boundary waterfall placements by `floor(world_pos / TILE_SIZE)`: tiles can carry a small cross-border placement that is still the active streamed instance at low M2 radius. Future cross-tile dedupe should use `MDDF.uniqueId` plus an ADT cache format bump/rebake.
|
||
- Still missing for true parity: exact shader array entries beyond the common WotLK set, particles/ribbons, full edge-scan tuning, exact guild/color constants and specialized blend-state edge cases.
|
||
|
||
## 2026-07-07 World Shader Light Stabilization
|
||
|
||
- DBC sky colors remain the source for `Environment` and sky rendering, but material shader globals now receive desaturated/neutralized ambient, diffuse and fog colors. This prevents Elwynn daylight profiles from tinting all ADT/M2/WMO albedo cyan or green.
|
||
- ADT terrain shaders now transform normals with `MODEL_NORMAL_MATRIX` before comparing them against the world-space `wow_light_dir`. Using fragment `NORMAL` directly made terrain lighting depend on the local surface basis and produced blue/green patches on slopes and roads.
|
||
- ADT, M2 and WMO material fog clamps `wow_fog_density` before mixing into `ALBEDO`; fog should add distance haze, not repaint nearby assets.
|
||
- M2/WMO shaders now reduce zone-color strength and clamp final albedo/specular/emissive contribution. Additive/parity edge cases still need exact WoW pass ordering later, but ordinary Elwynn props should no longer produce overexposed or acid-green surfaces.
|
||
- Human building WMO materials such as `HumanTwoStory` and `GoldshireInn` carry strong painted `MOMT.diffColor` values, including green trim colors. Textured WMO surfaces now use this as a soft hue tint instead of multiplying texture albedo by the raw RGB value; untextured WMO surfaces still use a muted material paint color.
|
||
- WMO window materials such as `MM_ELWYNN_WND_EXT__01.BLP` carry high `MOMT.sidnColor`/emissive values. Emissive is texture-masked and capped for window paths so it brightens the pane pattern instead of flooding the whole quad white.
|
||
- Runtime WMO cache material refresh is versioned separately from WMO geometry cache. Shader-only WMO material fixes should bump `WMO_MATERIAL_REFRESH_VERSION` instead of forcing a full `wmo_render_v1` rebake.
|
||
|
||
## Practical Rule For Future Work
|
||
|
||
If something improves quality but creates visible hitch, it is not done. Move it to bake/cache/background work, split finalization over frames, or prewarm it before the player can see it.
|
||
|
||
High quality must appear before the player arrives, not after crossing the ADT boundary.
|