open-wc/targets/roadmap/02-rendering-and-graphics.md

RND — Rendering and Graphics

Цель

Воспроизвести визуальные правила WoW 3.3.5a и дать opt-in улучшения, сохранив frame pacing на больших мирах Godot.

M04 execution policy

M04 выполняет renderer fidelity до Editor, network и gameplay milestones. M03 facade, ownership, streaming budgets и cache rules сохраняются: fidelity работа расширяет services и shaders, но не возвращает прямой cross-layer доступ к streamer internals.

Authoritative oracle — оригинальный клиент build 12340. Noggit полезен для обзорной композиции, placements и будущего Editor viewport, но не подтверждает точные lighting, shadow, liquid, material или effect semantics.

Pinned Benilla source полезен как secondary implementation reference для pose/palette animation, global sequences, material/pass ordering, shared dynamic effect buffers, M2 particles/ribbons и WMO portal traversal. Поскольку Benilla ориентирован на Vanilla build 5875 и Bevy, каждое заимствованное правило сначала проверяется на build-12340 fixture и адаптируется к существующим Godot/M03 ownership, scheduling и finalization boundaries.

Reference corpus принимает versioned CSV и приватные captures. Для каждой выбранной локации базовый набор содержит две позиции: wide для sky/fog/WDL и общей композиции, ground для terrain/material/M2/WMO. Специализированные water, interior, shadow, character и effect viewpoints добавляются только когда две базовые позиции не покрывают уникальную визуальную policy.

Repository хранит schema, coordinates/camera/settings metadata, SHA-256, comparison metrics, gap classification и human approval. Proprietary image/video bytes остаются вне Git. Неизвестные camera/time/weather/settings поля отмечаются как Unknown; их запрещено угадывать или автоматически считать parity evidence.

Обязательный порядок реализации:

1. reference manifest, validator, paired capture и semantic region diff;
2. deterministic color/gamma/sampling/alpha/fog pipeline;
3. environment/sky/weather и terrain/WDL/MCSH;
4. M2/WMO material passes и indoor/outdoor lighting;
5. graphics-setting-aware shadows и liquids;
6. GPU animation, characters, attachments, equipment и mounts;
7. particles, ribbons, weather и spell visual lifecycle;
8. Enhanced/Racing profile separation, traversal/performance/lifetime closeout.

Полный custom RenderingDevice backend допускается только после bounded spike, доказавшего, что точный critical pass нельзя реализовать Godot spatial/sky/ particle/compositor механизмами в установленном performance budget.

RND-1. Renderer architecture

• WorldRenderFacade принимает focus, environment snapshot и entity presentation commands.
• StreamingTargetPlanner вычисляет desired state без Node creation.
• RenderBudgetScheduler ограничивает main-thread finalize по типам операций.
• Terrain, M2, WMO, liquid, sky, character, effects и debug overlays — отдельные services.
• RenderingServer/RIDs применяются только там, где profiler доказал overhead scene tree.
• Ownership каждого RID и cache entry документируется; world unload проверяет leaks.

RND-2. World streaming

• WDT-driven tile catalog, priority по position/direction/velocity/camera frustum.
• Prewarm, retain и hysteresis исключают churn на ADT boundaries.
• Separate budgets для I/O, parse, mesh/material load, main-thread attach и eviction.
• Cold/warm cache scenarios, teleport, rapid flight и camera rotation stress.
• Cancellation stale jobs при teleport/map change.
• Streaming focus не обязан быть Camera3D: player, spectator, editor viewport, capture tool.

RND-3. Terrain

• Точная 145-vertex MCNK topology, holes, normals и coordinate seams.
• Texture layer order, MCAL alpha variants, animation flags, repeat и mip behavior.
• Control-splat/array implementation как Godot optimization с fidelity tests.
• WDL/distant terrain и hierarchical LOD.
• Terrain collision/query representation отдельно от visual mesh.
• Editing path: sculpt, smooth, flatten, holes, texture paint, seam repair и rebake.

RND-4. M2

• Static geometry, SKIN batches, blend modes, flags, UV transforms и texture lookup.
• Native pivot-based skeletal animation, bone palettes, global sequences и animation lookup.
• Billboards, attachments, key bones, events, cameras и bounding volumes.
• Particles, ribbons, texture animation и material combiners.
• Static doodads группировать spatial MultiMesh cells; animated/interactive entities не смешивать со static batching.
• MultiMesh buffer updates выполнять батчем; cell size выбирать по culling, а не только draw-call minimum.

RND-5. WMO

• Root/group materials, batches, vertex colors, multiple UV sets и doodad sets.
• Portals/rooms, indoor/outdoor, BSP/collision, fog и group visibility.
• MLIQ, skybox, lights и ambient color semantics.
• Lightweight render cache для больших WMO и incremental group attach.
• Editor tools для group/portal/doodad validation.

RND-6. Characters and creatures

• Race/gender/customization from DBC.
• Geosets, skin regions, hair/facial features и composited textures.
• Equipment component models/textures, attachment points, sheath, enchant visuals.
• Animation state resolver: locomotion, combat, casting, emotes, death, swim, mount, vehicle.
• CreatureDisplayInfo/Extra/ModelData, NPC equipment, pets и shapeshift.
• Character preview uses same presenter as world runtime.

RND-7. Liquids

• MH2O/MCLQ layers, existence masks, heights, depth и liquid type.
• Отдельные profiles water/ocean/magma/slime.
• Blizzlike material: texture animation, alpha, lighting и fog behavior.
• Enhanced material: normals, reflections, depth/shore blending — opt-in.
• Liquid collision/swim state принадлежит gameplay/physics query, не shader.

RND-8. Environment

• DBC-driven Light/LightParams/LightIntBand/LightFloatBand interpolation.
• Server time, day/night, zone/subzone transitions.
• Skyboxes, fog, ambient/directional light, weather visual state.
• Blizzlike cheap shadow policy; enhanced selective character/object shadows отдельно.
• Camera far plane, fog и streaming distances согласованы профилем.

RND-9. Effects and presentation

• SpellVisual/SpellVisualKit-driven cast/impact/aura effects.
• Projectiles, decals, dynamic objects, combat text и selection circles.
• Weather particles и world emitters.
• Cinematic/model cameras и loading transitions.
• Effects have pooling, lifetime, visibility и per-frame budgets.

RND-10. Graphical extensions

• Higher-resolution content overlays без модификации originals.
• Anisotropy, extended draw distance, improved water/shadows, post-processing и upscaling.
• Optional PBR approximation only when it does not replace Blizzlike material profile.
• Graphics settings expose measurable cost and fallback.
• Editor comparison viewport: Blizzlike/Enhanced side-by-side, screenshot и metric capture.

Verification

• Paired checkpoints с original 3.3.5a по position/time/weather/camera.
• Material/animation fixtures from independent references.
• Perceptual diff плюс human approval для intentional deviations.
• p50/p95/p99, max hitch, draw calls, visible objects, GPU/CPU memory и RID leak checks.
• D3D12/Vulkan and quality profile matrix.

Gate

Для утверждённой original-client capture matrix отсутствуют неклассифицированные визуально различимые gaps; каждый Verified class имеет fixture, metrics и human approval. Under-foot/near-field quality готова до появления в кадре; temporal effects совпадают по phase/duration/trajectory; long traversal не создаёт recurring hitches/leaks; Enhanced/Racing всегда отключаем и не меняет Blizzlike335 default behavior.