# 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 пока не как в клиенте.

## 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`.

Что делает 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.

## 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: 1
```

## 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.
- 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.

## 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.