docs(M04): prioritize renderer fidelity milestone

Work-Package: M04-RND-FIDELITY-ROADMAP-001 Agent: sindo-main-codex-renderer-roadmap Tests: coordination, documentation, target sequence, old-link and diff gates pass Fidelity: original build-12340 captures are authoritative; Noggit is secondary reference
2026-08-02 17:41:18 +04:00
parent 4369dd3c91
commit f77f50c0f9
28 changed files with 279 additions and 76 deletions
@@ -9,6 +9,12 @@ OpenWC состоит из двух продуктов на общей плат

 Оба продукта используют общие канонические модели, импорт данных и renderer preview, но не разделяют UI, lifecycle и права на изменение данных.

+Планируемый racing fork является третьим потребителем graphics foundation. Он
+может использовать world streaming, materials, lighting, shadows, liquids,
+characters, animation и effects contracts, но не зависит от WoW network,
+gameplay state или proprietary asset repository. Его улучшения выбираются
+отдельным `Racing` graphics profile и не меняют `Blizzlike335`.
+
 ## Архитектурные принципы

 1. Сервер авторитетен для боя, ресурсов, инвентаря, квестового прогресса и общего мира.
@@ -57,6 +63,11 @@ TrinityCore/AzerothCore ◄── Network Adapter ◄── Runtime Client

 Renderer получает `StreamingFocus`, `WorldVisualSnapshot` и presentation-команды. Он НЕ ДОЛЖЕН читать packets, SQL или gameplay input.

+`GraphicsProfile` выбирается на composition boundary и задаёт material,
+lighting, shadow, liquid, effects, distance и post-processing capabilities.
+Внутренние shader/services не смешивают Blizzlike/Enhanced/Racing policy через
+неявные глобальные switches.
+
 ### UI

 Владеет login/realm/character screens, HUD и FrameXML/Lua-compatible presentation. UI читает immutable view models и отправляет intents. Lua API получает capability-based facade; прямой доступ к network, filesystem и editor API запрещён.
@@ -157,6 +168,7 @@ addons/
 - `ServerSchemaAdapter` — inspect, import, diff, generate, validate.
 - `ContentTypeDescriptor` — schema, inspector, validator, compiler.
 - `WorldRenderer` — streaming focus и entity presentation.
+- `GraphicsProfile` — explicit Blizzlike/Enhanced/Racing visual capabilities.
 - `GameplaySystem` — commands/events без scene dependency.
 - `EditorTool` — selection, command creation и gizmo, без прямой записи.
 - `TestFixtureProvider` — обезличенные packets, DB snapshots и content fixtures.
@@ -197,7 +197,7 @@ func request_streaming_tile_load(request: StreamingTileLoadRequest) -> void:
 - Предпочитать именованные predicates длинным boolean expressions.
 - Branch по capability/profile должен быть локальным и типизированным.
 - Не распространять `if core == "azerothcore"` по проекту; использовать adapter/capability.
- Не смешивать Blizzlike и Enhanced branches в каждом shader/service: выбирать profile/strategy на boundary.
+- Не смешивать Blizzlike, Enhanced и Racing branches в каждом shader/service: выбирать profile/strategy на boundary.
 - Pattern/table-driven mapping предпочтительнее сотен одинаковых `if`, если таблица остаётся читаемой и валидируемой.

 ## Comments
@@ -181,7 +181,7 @@ stateDiagram-v2
 - Uniform/global parameter: coordinate/color space, range, units и producer.
 - Material profile: supported WoW shader/blend modes и approximations.
 - Expensive branch/texture dependency имеет cost/fallback note.
- Blizzlike и Enhanced behavior документируются отдельно.
+- Blizzlike, Enhanced и Racing behavior документируются отдельно.

 ### Network codecs

@@ -61,7 +61,7 @@ Gameplay state, network session, renderer world, editor session, caches конк
 - Visibility ranges/HLOD, occlusion и automatic mesh LOD использовать совместно по профилю.
 - Unique materials/textures минимизировать; descriptor/resource counts являются budget metric.
 - RenderingServer RIDs имеют явного владельца и освобождаются в deterministic shutdown test.
- Shader/material profiles разделяют Blizzlike и Enhanced; runtime не компилирует тяжёлые варианты при пересечении ADT boundary.
+- Shader/material profiles разделяют Blizzlike, Enhanced и Racing; runtime не компилирует тяжёлые варианты при пересечении ADT boundary.

 ## EditorPlugin lifecycle

@@ -18,7 +18,20 @@

 Готово, когда render sandbox сохраняет текущее качество, а domain тестируется без scene tree.

-## M1 — Content Project и Editor shell
+## M1 — Renderer fidelity и graphics foundation
+
+- Original-client build-12340 corpus: две базовые позиции выбранной локации,
+  settings/time/weather/camera metadata, static и temporal evidence.
+- Точные color, terrain, M2/WMO material, sky/fog/weather и shadow rules.
+- MH2O/MCLQ/MLIQ liquids, GPU animation, characters, particles и ribbons.
+- Раздельные `Blizzlike335` и opt-in `Enhanced/Racing` graphics profiles.
+- Paired semantic-region comparison, human approval и traversal/GPU budgets.
+
+Готово, когда утверждённая capture matrix не содержит неклассифицированных
+визуально различимых gaps, а общие graphics contracts пригодны клиенту, Editor
+preview и racing fork.
+
+## M2 — Content Project и Editor shell

 - `addons/openwc_editor` с workspace и docks.
 - Content Project schema, stable IDs, save/load/migration.
@@ -28,7 +41,7 @@

 Готово, когда небольшой synthetic project можно создать, изменить, undo, перезапустить Editor и получить идентичное состояние.

-## M2 — Server inspector и adapters
+## M3 — Server inspector и adapters

 - TrinityCore/AzerothCore connection profiles.
 - Schema detection и capabilities.
@@ -38,7 +51,7 @@

 Готово, когда одна сущность round-trip проходит оба поддерживаемых adapter profile без молчаливой потери данных.

-## M3 — World Editor MVP
+## M4 — World Editor MVP

 - Map viewport и coordinate overlays.
 - Server spawn visualization.
@@ -48,7 +61,7 @@

 Готово, когда NPC размещается в Editor и появляется на тестовом core в ожидаемой позиции.

-## M4 — Quest vertical slice
+## M5 — Quest vertical slice

 - Quest form и chain graph.
 - Kill/collect/explore objectives, giver/ender, rewards и localization.
@@ -57,7 +70,7 @@

 Готово, когда созданный в Editor квест полностью проходится клиентом.

-## M5 — Playable network client
+## M6 — Playable network client

 - Auth, realm, character selection и world session.
 - Entity/update fields и world spawn.
@@ -66,7 +79,7 @@

 Готово, когда клиент стабильно входит в мир, перемещается и видит синхронизированные entities.

-## M6 — Core gameplay
+## M7 — Core gameplay

 - Combat/spells/auras/death.
 - Inventory/equipment/loot/vendors.
@@ -76,7 +89,7 @@

 Готово, когда базовый leveling loop проходит без внешнего клиента.

-## M7 — Dungeon authoring
+## M8 — Dungeon authoring

 - DungeonPackage, encounters, triggers, doors и spawn groups.
 - SmartAI/script skeleton generation.
@@ -85,7 +98,7 @@

 Готово, когда custom dungeon собирается, разворачивается и проходится группой на test core.

-## M8 — Compatibility и completeness
+## M9 — Compatibility и completeness

 - Feature matrix WoW 3.3.5a.
 - Addon compatibility tiers.
@@ -98,17 +111,17 @@
 При равной ценности порядок такой:

 1. безопасность данных и воспроизводимость;
-2. корректность протокола и authoritative state;
-3. пользовательский vertical slice;
-4. diagnostics и testability;
-5. frame pacing;
-6. визуальная точность и polish.
+2. original-client renderer fidelity и frame pacing текущего M04;
+3. корректность протокола и authoritative state;
+4. пользовательский vertical slice;
+5. diagnostics и testability;
+6. opt-in визуальные улучшения после Blizzlike evidence.

 ## Не делать раньше времени

 - прямую запись в production DB;
 - универсальный visual scripting для любой C++ механики;
 - массовую реализацию Lua API без работающего UI slice;
- большой rewrite существующего renderer;
+- полный custom renderer до bounded shader/backend spike и profiler evidence;
 - multi-expansion abstraction до устойчивого профиля 3.3.5a;
 - proprietary asset packaging в репозитории.
@@ -44,8 +44,8 @@ ID записывается в claim, ветке, PR/MR и handoff. Нельзя
 ```text
 M01-FND-COORDS-001
 M03-RND-SCHEDULER-001
-M08-NET-SRP-001
-M12-UIA-LUA-SPIKE-001
+M09-NET-SRP-001
+M13-UIA-LUA-SPIKE-001
 ```

 Program codes определены в [`../targets/DEVELOPMENT_ROADMAP.md`](../targets/DEVELOPMENT_ROADMAP.md).
@@ -214,7 +214,7 @@ Merge order:

 ```text
 fnd(M01): add canonical coordinate mapper
-net(M08): decode auth challenge safely
+net(M09): decode auth challenge safely
 rnd(M03): extract streaming target planner
 test(M00): add paired checkpoint manifest
 ```
@@ -71,6 +71,25 @@ tools/verify_render_performance_stability.ps1 -RepeatedSampleComparison <repeate
 только на повторяемой регрессии. Полный контракт и схема evidence описаны в
 [`modules/renderer-closeout-verification.md`](modules/renderer-closeout-verification.md).

+M04 renderer fidelity использует оригинальный клиент build 12340 как
+authoritative visual oracle. Noggit допускается как дополнительный reference
+композиции/placements и Editor UX, но не подтверждает lighting, shadows, liquids,
+materials, animation или effects.
+
+Reference corpus импортируется через versioned CSV manifest. Для каждой
+выбранной локации базово снимаются `wide` и `ground` viewpoints; отдельные
+specialized captures добавляются для уникальных interior, liquid, shadow,
+character и effect policies. Capture metadata фиксирует WoW/server coordinates,
+доступные camera fields, time, weather, graphics profile, viewport, artifact
+name и provenance. Отсутствующее значение хранится как `Unknown`, а не
+восстанавливается предположением.
+
+Proprietary screenshots/video остаются вне Git. Repository evidence включает
+schema, SHA-256, static/temporal metrics, semantic region classification и human
+approval. Static parity требует согласованных geometry/framing и material/light/
+shadow/liquid regions; temporal parity отдельно проверяет phase, duration,
+trajectory, UV motion и emitter lifetime.
+
 ### Navigation compatibility

 - Golden synthetic meshes проверяют slope, climb, radius erosion, holes, tiled seams и off-mesh connections.
@@ -41,7 +41,8 @@ Decision/ADR:
 | StormLib | ADOPTED | MPQ | Чтение архивов через native extension | Version/license/update audit |
 | WowUnreal | REFERENCE | Полный клиент | Coverage, acceptance criteria, networking/UI research | Unreal-specific design |
 | WoWee | REFERENCE | Клиент/editor/formats | Architecture, editor workflows, tests, open formats | Заявления требуют независимой проверки |
-| Noggit Red | REFERENCE | World editor | Terrain/placement UX, UID workflows | Не Godot architecture |
+| Original WoW 3.3.5a build 12340 client | ADOPTED | Visual/behavior oracle | Private static/temporal capture corpus, settings and paired comparison | Proprietary artifacts remain outside Git; camera/settings provenance must be explicit |
+| Noggit Red | REFERENCE | World editor | Terrain/placement UX, UID workflows и secondary render-composition reference | Не Godot architecture; не authoritative lighting/material/shadow/liquid oracle |
 | open-realm | REFERENCE | Formats/runtime | Независимая проверка parsers/render behavior | Другая архитектура и coverage |
 | whoa | REFERENCE | Client behavior | 3.3.5a runtime semantics и fixtures | Лицензия и переносимость отдельных решений |
 | wow.export | REFERENCE | Asset conversion | M2/WMO/material/export edge cases | Web-specific pipeline |
@@ -241,7 +241,7 @@ runtime data migration.
 | Current starter outfit | Partial | Existing resolver reused unchanged | Needs extracted DBC fixture and client comparison |
 | Current skin/geoset composition | Partial | Existing components reused | Full equipment/customization fidelity incomplete |
 | Build-12340 animation semantics | Planned | No original-client fixture | Capture animation IDs/transitions/timing |
-| Runtime equipment/network updates | Planned | No snapshot contract | M08/M09/M12 work |
+| Runtime equipment/network updates | Planned | No snapshot contract | M09/M10/M13 work |

 ## Known gaps and risks

@@ -237,7 +237,7 @@ separate versioned movement snapshot contract.

 - Terrain/collision policy can consume displacement without changing input or velocity ownership.
 - A future server-aware predictor may replace this controller behind the scene composition boundary.
- A typed movement snapshot may expose deterministic replay state when M08/M09 require it.
+- A typed movement snapshot may expose deterministic replay state when M09/M10 require it.
 - A future application profile can map to this narrow capability value without
  coupling the movement controller to the application shell.

@@ -252,8 +252,8 @@ separate versioned movement snapshot contract.
 | Typed sprint/free-flight exclusion | Implemented | Pure and real-scene profile regressions | Application shell must select profile explicitly later |
 | Terrain height query | Implemented | Typed `TerrainQuery` and injected player regression | Ground-snap policy remains scene-owned |
 | Terrain collision movement policy | Planned | Height-only query does not model collision | Add slopes/holes/collision later |
-| Jump/fall/swim | Planned | M02/M09 roadmap | Requires terrain/liquid and server contracts |
-| Prediction/reconciliation | Planned | M08/M09 roadmap | Requires movement snapshot/network contract |
+| Jump/fall/swim | Planned | M02/M10 roadmap | Requires terrain/liquid and server contracts |
+| Prediction/reconciliation | Planned | M09/M10 roadmap | Requires movement snapshot/network contract |

 ## Known gaps and risks

@@ -227,7 +227,7 @@ Existing ADT/native/cache format versions remain unchanged.
 | Renderer loaded-mesh diagnostic backend | Implemented | M03 facade typed sample and detached snapshot contract | Not composed into gameplay; triangle Mesh ray is diagnostic only |
 | Authoritative renderer/physics backend | Planned | Boundary permits replacement | Define holes/slopes/collision/readiness semantics before gameplay composition |
 | Holes/slopes/collision | Planned | Outside height-only contract | Later movement/physics package |
-| Liquid/swim query | Planned | Outside contract | M09/M12 world gameplay |
+| Liquid/swim query | Planned | Outside contract | M10/M13 world gameplay |

 ## Known gaps and risks