базовый рендер

docs/RENDER_BASELINE.md

@@ -0,0 +1,76 @@
+# Renderer baseline M00
+
+Этот документ описывает воспроизводимый baseline renderer перед архитектурной декомпозицией. Он не является заявлением о визуальной совместимости `1:1` с WoW 3.3.5a.
+
+## Единый запуск
+
+Из корня репозитория:
+
+```powershell
+.\tools\run_render_baseline.ps1
+```
+
+Скрипт последовательно проверяет headless-загрузку проекта, renderer materials, M2 unique-id dedupe, regression manifest и затем снимает checkpoint-ы. Для CI или быстрой проверки контракта без PNG:
+
+```powershell
+.\tools\run_render_baseline.ps1 -DryRun -WaitSeconds 0.1 -MeasureSeconds 0.1
+```
+
+Если `godot` отсутствует в `PATH`, скрипт использует локальный executable, указанный в `RENDER.md`. Другой executable задаётся через `-GodotPath`.
+
+Результат по умолчанию находится в `user://render_baseline`:
+
+- `report.json` — Godot, OS, CPU, GPU/backend, viewport, revision, cache inventory, cache versions, параметры checkpoint-ов и результаты;
+- `<checkpoint>__cold_process.png` — первый визит в текущем процессе;
+- `<checkpoint>__warm_revisit.png` — повторный визит в том же процессе после обхода контрольных точек.
+
+`cold_process` не означает очищенный Windows filesystem cache. Поле `cache_state` и полный inventory обязаны интерпретироваться вместе с результатом. Удаление или принудительная пересборка cache не входит в baseline-команду. Для отдельного запуска после контролируемой очистки безопасного локального cache следует передать осмысленную метку, например `-CacheState rebuilt-clean`; proprietary source assets команда не изменяет.
+
+## Контрольные точки и детерминизм
+
+Нормативный manifest: `res://src/tools/render_baseline_manifest.json`. Он не содержит proprietary assets и фиксирует семь обязательных классов:
+
+- Elwynn terrain overview;
+- граница ADT около world center;
+- dense M2 в Goldshire;
+- Goldshire Inn как large WMO;
+- Elwynn waterfall как liquid;
+- синтетический native-animation probe `GryphonRoost01.m2`;
+- тот же Elwynn overview в 19:00 для sky transition.
+
+Зафиксированы camera/target/player position, viewport, FOV, quality preset и время мира. Для temporal shader/animation кадров SHA-256 служит идентификатором артефакта, но не pass-критерием: будущая автоматическая визуальная проверка должна использовать perceptual diff и согласованный tolerance. Синтетический animation probe существует только внутри capture tool и не меняет runtime streaming scene.
+
+## Метрики и budget
+
+Каждая точка записывает load/wait time, frame time p50/p95/p99, максимальный frame hitch, static/video memory, draw calls, rendered objects и снимок streaming queues. При сравнении следующего renderer с этим baseline p95, p99, max hitch, load time и memory не должны ухудшаться более чем на 10% без отдельного принятого объяснения и обновления baseline.
+
+Измерение считается неполным, если snapshot показывает незавершённые очереди: это состояние остаётся в `report.json` и не должно скрываться. Значения сравниваются только на одинаковых Godot, backend, hardware/profile, cache state, viewport и manifest revision.
+
+## Cache contract
+
+Manifest фиксирует проверяемые версии и причины invalidation:
+
+| Cache | Version | Invalidate when |
+|---|---:|---|
+| baked terrain | 5 | изменились baked geometry или placement payload |
+| streaming terrain | 2 | изменились streaming geometry или M2 `unique_id` payload |
+| terrain splat | 1 | изменился splat resource payload |
+| terrain control splat | 3 | изменились control atlas, layer map или texture array |
+| WMO streaming | 2 | изменилась WMO render geometry |
+| WMO builder | 2 | изменились scene transform или builder payload |
+| M2 material | 2 | изменились material или custom vertex payload |
+
+`verify_render_baseline_manifest.gd` сравнивает таблицу с runtime constants. Shader-only refresh versions, не изменяющие serialized payload, обновляются по правилам `RENDER.md`; изменение payload требует version bump и rebake.
+
+## Fidelity gaps относительно 3.3.5a
+
+Baseline пока не имеет approved парных кадров оригинального клиента build 12340. До их появления нельзя утверждать parity. Известны следующие классы расхождений:
+
+- неполные M2 animation/skinning, particles и ribbons;
+- приближённые M2/WMO material combiners и pass ordering;
+- отсутствие настоящего WMO portal/room culling;
+- упрощённые liquid depth/shore rules и texture selection;
+- неполная проверка skybox/lighting transition по зонам;
+- возможная смена D3D12 на Vulkan при ошибке descriptor heap — фактический backend всегда берётся из `report.json`.
+
+Парное сравнение с клиентом 3.3.5a должно использовать те же map position, local time и weather. Каждый gap регистрируется как terrain/material, placement, animation, lighting, liquid или culling; baseline сам по себе gap не закрывает.