архитектура и цели для агентов

RENDER.md

@@ -580,7 +580,7 @@ Please increase rendering/rendering_device/d3d12/max_resource_descriptors.
 - ограничивать активные high-quality terrain tiles;
 - избегать screen/refraction textures для water.
 
-Если ошибка возвращается, увеличивать project setting `rendering/rendering_device/d3d12/max_resource_descriptors` и одновременно искать, где плодятся уникальные материалы.
+Если ошибка возвращается, увеличивать project setting `rendering/rendering_device/d3d12/max_resource_descriptors` и одновременно искать, где плодятся уникальные материалы. В `project.godot` это должно быть записано внутри секции `[rendering]` как `rendering_device/d3d12/max_resource_descriptors`; вариант с повторным префиксом `rendering/rendering_device/...` внутри секции игнорируется.
 
 ## Caches
 
@@ -607,7 +607,8 @@ res://data/cache/wmo_render_v1
 Версии:
 
 ```text
-Baked terrain required: 4
+Baked terrain required: 5
+Streaming terrain required: 2
 Splat terrain required: 1
 Control splat required: 3
 WMO streaming resource: 2
@@ -659,6 +660,41 @@ $exe = Join-Path $env:TEMP 'godot-4.6.1-openwc\Godot_v4.6.1-stable_win64.exe'
 & $exe --headless --path . --quit
 ```
 
+Renderer material regression smoke:
+
+```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/verify_render_materials.gd
+```
+
+ADT M2 placement probe:
+
+```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/verify_adt_m2_placements.gd -- --map Azeroth --uid 11785 --path-contains waterfall
+```
+
+M2 uniqueId dedupe smoke:
+
+```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/verify_m2_unique_dedupe.gd
+```
+
+Renderer checkpoint capture:
+
+```powershell
+$exe = Join-Path $env:TEMP 'godot-4.6.1-openwc\Godot_v4.6.1-stable_win64.exe'
+& $exe --path . --script res://src/tools/capture_render_checkpoints.gd -- --wait 8 --output user://render_checkpoints
+```
+
+Headless checkpoint dry-run:
+
+```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/capture_render_checkpoints.gd -- --dry-run --wait 0.1
+```
+
 Run scene headless:
 
 ```powershell
@@ -697,7 +733,7 @@ $exe = Join-Path $env:TEMP 'godot-4.6.1-openwc\Godot_v4.6.1-stable_win64.exe'
 - Liquid depth fade/shore blending.
 - LiquidType.dbc based water textures.
 - Better skybox transition validation per zone.
-- Automated renderer regression scenes/screenshots.
+- Automated renderer screenshot scenes. A cheap material regression smoke exists at `src/tools/verify_render_materials.gd`.
 
 ## 2026-07-04 WMO Shader Pass
 
@@ -722,7 +758,7 @@ $exe = Join-Path $env:TEMP 'godot-4.6.1-openwc\Godot_v4.6.1-stable_win64.exe'
 - `.skin` texture unit `priority` is exposed as `priority_plane` for future transparent-pass ordering. This needs the native GDExtension DLL to be rebuilt when the editor is not holding it open.
 - Waterfalls seen near terrain cliffs are usually WMO embedded doodads rather than ADT `MDDF` placements. WMO doodad transforms now use the converted MODD quaternion directly, without the old extra `+90 deg` M2 yaw offset.
 - WMO render/scene caches now carry version guards for this transform path. Rebuild `wmo_render_v1`/`wmo_tscn` after changing WMO doodad placement code; old caches are ignored by runtime.
-- Elwynn/Thunder Falls style outdoor waterfalls are ADT `MDDF` M2 placements. Regular ADT M2 doodads use the native cached Godot-space Euler directly via `Basis.from_euler(rot)`; do not apply a global yaw/order remap, because it flips ordinary props such as wagons, stalls, barrels, fences and trees. `ElwynnCliffRock01/02` are a model-specific exception: these are open-backed shell meshes, so they use a narrow `YZX` placement correction with `rot.y + 180 deg` to push the hollow side into the terrain. The waterfall transform correction is also filename-allowlisted to the actual sheet M2s (`NewWaterfall`, `ElwynnTallWaterfall01`). Sheet M2s keep the calibrated world-space `+90 deg` Godot-Y yaw to anchor the top to the upper pool, plus model-specific twist where needed. Tall waterfall sheets twist around their local fall line with an origin offset so top/bottom anchors stay fixed instead of rotating around the model pivot; `ElwynnTallWaterfall01` uses the opposite twist sign from `NewWaterfall` to face the correct side. Do not apply the raw-M2/WoWee render-space basis here; that double-converts M2 vertices. Do not cull boundary waterfall placements by `floor(world_pos / TILE_SIZE)`: tiles can carry a small cross-border placement that is still the active streamed instance at low M2 radius. Future cross-tile dedupe should use `MDDF.uniqueId` plus an ADT cache format bump/rebake.
+- Elwynn/Thunder Falls style outdoor waterfalls are ADT `MDDF` M2 placements. Regular ADT M2 doodads use the native cached Godot-space Euler directly via `Basis.from_euler(rot)`; do not apply a global yaw/order remap, because it flips ordinary props such as wagons, stalls, barrels, fences and trees. `ElwynnCliffRock01/02` are a model-specific exception: these are open-backed shell meshes, so they use a narrow `YZX` placement correction with `rot.y + 180 deg` to push the hollow side into the terrain. The waterfall transform correction is also filename-allowlisted to the actual sheet M2s (`NewWaterfall`, `ElwynnTallWaterfall01`). Sheet M2s keep the calibrated world-space `+90 deg` Godot-Y yaw to anchor the top to the upper pool, plus model-specific twist where needed. Tall waterfall sheets twist around their local fall line with an origin offset so top/bottom anchors stay fixed instead of rotating around the model pivot; `ElwynnTallWaterfall01` uses the opposite twist sign from `NewWaterfall` to face the correct side. Do not apply the raw-M2/WoWee render-space basis here; that double-converts M2 vertices. Do not cull boundary waterfall placements by `floor(world_pos / TILE_SIZE)`: tiles can carry a small cross-border placement that is still the active streamed instance at low M2 radius. Cross-tile dedupe uses `MDDF.uniqueId`, not geometry ownership.
 - Still missing for true parity: exact shader array entries beyond the common WotLK set, particles/ribbons, full edge-scan tuning, exact guild/color constants and specialized blend-state edge cases.
 
 ## 2026-07-07 World Shader Light Stabilization
@@ -733,6 +769,11 @@ $exe = Join-Path $env:TEMP 'godot-4.6.1-openwc\Godot_v4.6.1-stable_win64.exe'
 - M2/WMO shaders now reduce zone-color strength and clamp final albedo/specular/emissive contribution. Additive/parity edge cases still need exact WoW pass ordering later, but ordinary Elwynn props should no longer produce overexposed or acid-green surfaces.
 - Human building WMO materials such as `HumanTwoStory` and `GoldshireInn` carry strong painted `MOMT.diffColor` values, including green trim colors. Textured WMO surfaces now use this as a soft hue tint instead of multiplying texture albedo by the raw RGB value; untextured WMO surfaces still use a muted material paint color.
 - WMO window materials such as `MM_ELWYNN_WND_EXT__01.BLP` carry high `MOMT.sidnColor`/emissive values. Emissive is texture-masked and capped for window paths so it brightens the pane pattern instead of flooding the whole quad white.
+- WMO window atlas textures use a stable albedo sampler (`filter_linear`, `repeat_disable`) instead of generated-mipmap anisotropic sampling. These textures pack several window variants into one BLP; generated mipmaps can bleed between atlas cells and make the upper-house window shimmer/change along diagonal texture features while the camera moves.
+- WMO window atlas materials use `cull_back` even when they are opaque `blendMode == 0`. The human-house exterior window texture is a real WMO material (`MM_ELWYNN_WND_EXT__01.BLP`, `flags=0x11`), not a transparent glass pass, and two-sided rendering can make nearby interior/exterior pane faces compete as the view angle changes.
+- WMO material flag `0x01` is treated as unlit in the WMO shader. Elwynn window materials use this flag together with emissive color, so they should not receive ordinary per-normal directional lighting across their triangulated panes.
+- WMO alpha discard is now restricted to `blendMode == 1` alpha-key materials. `blendMode == 2` is true alpha blend; treating it as alpha-key caused windows/glass and other translucent WMO surfaces to become cut-out.
+- WMO window/glass texture paths (`/windows/`, `/glass/`, `window`, `glass`, exact `_wnd_` in the file name) are metadata only for opaque materials. Do not use a broad `wnd_` substring: Stormwind texture names such as `MM_STRMWND_WALL_03.BLP` are ordinary wall textures, not windows. Window metadata does not make an opaque WMO material transparent and does not apply glass tint, because many house facades use window-named atlas textures for walls and trim too. The separate glass shader variant and glass tint are only used when the WMO material is also `blendMode == 2`. In the Godot path, glass and other alpha-blend WMO surfaces avoid depth writes; depth-writing glass caused moving-camera flicker/z-fighting on facade window overlays. Glass WMO surfaces also use back-face culling instead of `cull_disabled`, because two-sided transparent facade panes can show the quad's internal triangle split as a moving diagonal seam.
 - Runtime WMO cache material refresh is versioned separately from WMO geometry cache. Shader-only WMO material fixes should bump `WMO_MATERIAL_REFRESH_VERSION` instead of forcing a full `wmo_render_v1` rebake.
 
 ## 2026-07-07 M2 Billboard Pass
@@ -741,10 +782,40 @@ $exe = Join-Path $env:TEMP 'godot-4.6.1-openwc\Godot_v4.6.1-stable_win64.exe'
 - Billboard metadata is resolved per drawn vertex through the skin section bone palette and vertex bone indices. This avoids treating an entire mixed surface as billboard just because the palette contains a billboard bone.
 - `M2Builder` stores billboard pivot/mode in `Mesh.ARRAY_CUSTOM0` as RGBA float data. `CUSTOM0.xyz` is the Godot-space bone pivot; `CUSTOM0.w` is the billboard mode: spherical, lock X, lock Y, or lock Z.
 - `WowM2Material` applies camera-facing billboarding in the vertex shader for marked vertices. This works with grouped ADT M2 `MultiMesh` batches because the shader uses each instance transform.
-- Runtime M2 cache refresh now has `M2_MATERIAL_REFRESH_VERSION`. Old cached `.tscn/.glb` meshes are replaced in memory from raw `.m2` when available, so the billboard/custom-attribute path does not require an immediate cache rebake.
+- Runtime M2 cache refresh now has `M2_MATERIAL_REFRESH_VERSION`. Old cached `.tscn/.glb` meshes are replaced in memory from raw `.m2` only when the raw model actually needs custom billboard attributes or UV-rotation data. Do not rebuild every stale cached M2 during streaming: creating fresh materials for ordinary props can exhaust the D3D12 resource descriptor heap.
 - Verified with `ElwynnGrass1.m2`: native data exposes a billboard batch, the built mesh contains `CUSTOM0`, and the M2 shader compiles with the billboard uniform enabled.
 - Remaining parity work: many Elwynn tree canopy M2s do not carry billboard bone flags, so their flat-looking leaves are a separate material/geometry parity issue, not this bone-billboard path.
 
+## 2026-07-07 M2 UV Transform Pass
+
+- Native `M2Loader` now decodes `M2TextureTransform.rotationTrack` as raw texture-space quaternions, separate from Godot-space bone quaternions.
+- Texture transform dictionaries now expose static UV rotation matrices and approximate Z-rotation speeds, in addition to existing translation, translation speed and scale.
+- `WowM2Material` applies UV rotation and scale around WoW's texture center `(0.5, 0.5)`, then applies translation/scroll. This is closer to the client path shown by `CM2Model::AnimateTextureTransformsMT`.
+- All four M2 texture stages receive UV rotation and rotation-speed uniforms, matching the existing four-stage texture binding path.
+- `M2_MATERIAL_REFRESH_VERSION` and `M2Builder.MATERIAL_FORMAT_VERSION` are bumped to `2`, so cached M2 meshes are rebuilt in memory when raw `.m2` data is available.
+- Verified with `Spells/ArcaneForceShield_Blue.m2`: native data exposes a non-identity UV rotation, the built material receives the stage rotation uniform, and the shader compiles.
+
+## 2026-07-08 Renderer Material Regression Smoke
+
+- Added `src/tools/verify_render_materials.gd` as a cheap headless guard for shader/material regressions.
+- The script checks the D3D12 descriptor heap project setting, opaque WMO window atlas handling, ordinary Stormwind wall detection, WMO glass depth/culling state, M2 alpha depth state, and M2 billboard/UV-rotation shader paths.
+- This is not a visual screenshot regression suite; it catches the material-state mistakes that caused the waterfall/window fixes to regress.
+
+## 2026-07-08 ADT M2 UniqueId Probe
+
+- Native `ADTLoader` now exposes `MDDF.uniqueId` as `unique_id` on M2 placement dictionaries, matching the existing WMO `MODF.unique_id` field.
+- Added `src/tools/verify_adt_m2_placements.gd` to find raw ADT M2 placements by `unique_id` and path substring. The default check targets the Elwynn waterfall placement `uid=11785`.
+- Runtime M2 cross-tile dedupe is enabled through an active `MDDF.uniqueId` registry. It filters duplicate placements before the M2 grouping worker runs, then releases the reservation when the owning tile unloads or leaves the M2 detail radius.
+- Candidate tiles that skipped a duplicate uid are re-queued when the active owner releases it. This avoids the old `floor(world_pos / TILE_SIZE)` ownership trap where boundary props could disappear.
+- `BakedADTTile.FORMAT_VERSION` is now `5` and `StreamingADTTile.FORMAT_VERSION` is now `2`, so old ADT caches without M2 `unique_id` are ignored until rebaked.
+- Added `src/tools/verify_m2_unique_dedupe.gd` as a headless smoke for reserve, skip and release behavior.
+
+## 2026-07-08 Renderer Checkpoint Capture
+
+- Added `src/tools/find_adt_placements.gd` as a diagnostic placement search helper for M2/WMO paths.
+- Added `src/tools/capture_render_checkpoints.gd` to load the Eastern Kingdoms streaming scene, move a dedicated camera to fixed regression viewpoints and save PNGs under `user://render_checkpoints`.
+- Current checkpoints cover the Elwynn waterfall from front/side and Goldshire Inn/Blacksmith windows. Headless runs are dry-run only because the headless display server cannot produce viewport PNGs.
+
 ## 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.