feat(render): add planar water reflections

2 files changed, 33 insertions, 3 deletions

diff --git a/docs/appendices/knowledge-boundaries.md b/docs/appendices/knowledge-boundaries.md
index 70f6259..a48bec5 100644
--- a/docs/appendices/knowledge-boundaries.md
+++ b/docs/appendices/knowledge-boundaries.md
@@ -73,9 +73,9 @@ MSH-запрос со свободной preview-камерой; это не п�
 среде, перехватить DirectDraw/Direct3D calls и surface flips, сохранить state
 log на минимальных сценах с одним типом материала.
 
-Полигоны Land.msh с флагом `0x8` пока используют обычный terrain shader; их исходные записи во всех LOD считает `terrain_face8_pipeline_unverified`.
-На водоёме «Конструктора» берег близок к оригиналу, а поверхность воды слишком светлая; точные special-pass, UV и combiner остаются открытыми.
-В GOG Terrain.dll подтверждена отдельная камера `REFLECTION`/`REFLECTION_SHIFTED` (инициализация RVA `0x13CF0`, render RVA `0x4EFF0`); Vulkan-проход отражения пока отсутствует.
+Горизонтальные грани Land.msh с флагом `0x20000` используют плоское Vulkan-отражение; shifted-камера, волны и native EMBM combiner остаются заглушкой `planar_reflection_embm_unsupported`.
+Один target отражает ближайшую активную высоту воды; остальные высоты и неплоские грани считаются в `planar_reflection_other_planes_unsupported` и `planar_reflection_nonplanar_unsupported` и сохраняют обычный terrain shader.
+`terrain_face8_pipeline_unverified` теперь считает только исходные грани с `0x8` без `0x20000`; сама семантика оставшихся специальных проходов ещё не установлена.
 
 ## FXID field-level semantics
 
diff --git a/docs/tomes/05-render.md b/docs/tomes/05-render.md
index cfd352a..e374ef0 100644
--- a/docs/tomes/05-render.md
+++ b/docs/tomes/05-render.md
@@ -1138,6 +1138,36 @@ lightmap state передаются в `VulkanStaticMaterial`, а shader пос�
 сэмплирует эти четыре стадии. Animation clock обновляет выбранные фазы и
 коэффициенты без пересборки terrain mesh, сохраняя native type-14 overlay mask.
 
+### Отражение на воде
+
+Поверхность воды нельзя рисовать тем же умножением текстур, что и землю.
+В проходе ландшафта GOG Terrain.dll флаг грани `0x20000` участвует в выборе
+отражения; при включённом EMBM живой водный кадр использует texture mode 10.
+Оригинал создаёт для этого отдельную камеру `REFLECTION_SHIFTED`.
+В [эталонной сборке](../reference/original-binaries.md) выбор грани находится
+в Terrain.dll RVA `0x28A50`, а подготовка EMBM-пакета — в RVA `0x1B540`.
+
+Первый Vulkan-проход строит плоское зеркало. Для горизонтальной воды на
+высоте `h` отражённая координата точки равна `z′ = 2h − z`. Это преобразование
+применяется перед обычной проекцией. Оно меняет порядок вершин треугольника,
+поэтому проход меняет сторону отсечения и отбрасывает геометрию ниже воды.
+Небо и оставшаяся сцена попадают в отдельную цветовую текстуру с собственной
+глубиной. В основном проходе водные треугольники читают её в экранной
+координате: точки самой плоскости не сдвигаются при отражении.
+
+Цветовой target переходит из attachment layout в shader-read layout после
+записи. Следующий зеркальный проход ждёт предыдущего чтения этой текстуры;
+основной и отражённый виды используют разные слоты uniform buffer. Во время
+записи отражения привязан отдельный нейтральный descriptor, чтобы проход
+не читал собственное вложение.
+
+Такое зеркало ещё не повторяет shifted-камеру и EMBM оригинала: искажение
+отражения волнами пока отсутствует и учитывается в
+`planar_reflection_embm_unsupported`. Один target обслуживает ближайшую
+активную высоту воды; другие высоты и негоризонтальные поверхности явно
+считаются как неподдержанные. Это промежуточный водный проход, а не полная
+приёмка воды или лавы.
+
 ## Реализация Vulkan
 
 `LegacyPipelineState` хранит blend, depth, cull и alpha-test. Из этих значений