claude/bake-ao-single-hierarchy-27AwS

CHANGELOG.md

@@ -26,12 +26,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
   - Assets ▸ Create context menu: `Mesh Lab ▸ Sweep Test Suite` (was always-visible `Lightmap UV Tool/Test Suite` via `[CreateAssetMenu]`).
 - **In-flight gate + `FireAndForget` helper** for fire-and-forget async UI actions. The "Run Full Pipeline" / "Run Repack only" / "Run Transfer only" / "Repack All" / "Transfer All Targets" buttons now sit inside an `EditorGUI.DisabledScope` on `_pipelineInFlight` so a second click can't launch an interleaving run; `FireAndForget` attaches `ContinueWith` on the Unity sync context to log Task faults through `UvtLog.Error`, release the gate, and call `UvProgress.Fail` so a thrown exception can't leave the strip stuck on a stale phase.
 - **Cancel-aware benchmark recording** in `ExecTransferAllImpl` — mirrors the `completedSuccessfully` guard `ExecFullPipelineImpl` already uses. Cancelled transfers no longer emit stale `shellTransferResult` / validation rows that taint sweep aggregates.
+- **Solid Color bake mode.** Fills `mesh.colors32` with a uniform `Color32` across every mesh variant of an entry (`originalMesh`, `repackedMesh`, `transferredMesh`, `fbxMesh`). Collision meshes are skipped via `MeshHygieneUtility.IsCollisionNodeName`. Each write goes through `Undo.RecordObject` + `EditorUtility.SetDirty`.
+- **Batch variant export pipeline.** New `VariantExportPipeline` (`Editor/Tools/VariantExportPipeline.cs`) drives a list of `(Color, suffix)` variants against a source FBX and an optional source prefab. Per variant it paints, exports `{base}_{suffix}.fbx`, instantiates the source prefab, unpacks it (full clone, not a Prefab Variant), swaps `MeshFilter.sharedMesh` to the matching new sub-mesh by name, and saves `{base}_{suffix}.prefab`. Each variant completes its own export → import → clone cycle, with a single `AssetDatabase.Refresh` at the end. Suffixes are validated against `^[A-Za-z0-9_]+$` and duplicates inside a batch are rejected upfront. Conflicts are overwritten — git is the rollback path.
+- **`LightmapTransferTool.ExportVertexColorsToFbxAs(sourceFbxPath, outputFbxPath, entries, uvChannelOverride)`** — public entry point that writes a new FBX next to (or anywhere relative to) the source without mutating the source importer, scene mesh bindings, or working copies.
 
 ### Changed
+- **Vertex AO tab renamed to Vertex Color Baking.** `VertexAOTool` → `VertexColorBakingTool`, `ToolId` `vertex_ao` → `vertex_color_baking`. Asset GUID preserved so existing references stay intact. AO functionality is unchanged and reachable via the new toolbar at the top of the tab.
 - **Default `RepackResolutionMode` is now `AutoFromTexelDensity`** (was `Manual`). Uniform real-world texels-per-meter is the desired outcome for lightmaps; the previous fixed-resolution default produced wildly different texel density per asset depending on world size.
 - **xatlas pack no longer raises a modal progress dialog** (`EditorUtility.DisplayCancelableProgressBar`). Progress now flows through `UvProgress` to the Background Tasks panel and the inline strip; cancel via `UvProgress.CancelRequested`.
 - **Hoisted all late `sourceMesh.*` and `targetMesh.*` reads** in `GroupedShellTransfer.Transfer` up to the initial Mesh-data extraction block. Keeps the algorithm body Unity-API-free so it runs cleanly in `Task.Run`.
 
+### Refactored
+- `LightmapTransferTool.ExportVertexColorsToFbxCore` now accepts an optional `outputFbxPathOverride` and returns `bool` for success. When the override is set and differs from the source path, Phase 1 (source importer mutation), Phase 4 scene relink, and Phase 5 restore are skipped so the source FBX and live scene stay untouched. Existing overwrite and hierarchy-mode callers keep their void-style usage.
+
 ### Removed
 - All `EditorUtility.DisplayProgressBar` / `DisplayCancelableProgressBar` / `ClearProgressBar` calls. Replaced with `UvProgress` everywhere (XatlasRepack, LightmapTransferTool, VertexAOBaker.Cpu, FbxMetricsExporter, LodGenerationTool).
 - `[CreateAssetMenu(menuName = "Lightmap UV Tool/Test Suite")]` from `TestSuiteAsset` — replaced with a gated `[MenuItem("Assets/Create/Mesh Lab/Sweep Test Suite")]`.

Documentation~/EXPERIMENTS.md

@@ -264,6 +264,53 @@
 - `FixMeshStripUvs()` — vertex colors `(0,0,0,0)` может быть валидное AO (полная окклюзия). Авто-стрип colors убран.
 - `SaveAndReimport()` в cleanup — добавлять `bypassPaths` чтобы постпроцессор не вмешался.
 
+---
+
+## External MeshLab (desktop) — Settings to Avoid Artifacts
+
+> Обновлено: 2026-05-02
+>
+> Применимо к FBX, прошедшим через десктопный **MeshLab** (https://www.meshlab.net/) перед импортом в Unity. Не путать с пакетом **UnityMeshLab** — это про внешний инструмент.
+>
+> Программная проверка симптомов: `MeshLabArtifactValidator` (`Editor/MeshLabArtifactValidator.cs`),
+> menu **Tools → Mesh Lab → Validators → Check Imported MeshLab Artifacts** (по выделенному GameObject/asset).
+
+### Filters — что ломает геометрию
+
+1. **Merge Close Vertices** — `Distance` ставить очень маленьким (`1e-6`) или отключать filter.
+   - На дефолтном threshold склеивает per-wedge UV-вершины в одну → **UV seams разъезжаются**, текстура «плывёт» по швам.
+   - Симптом в Unity: `mesh.vertexCount == уникальных позиций`, при том что в сцене заметны видимые швы.
+
+2. **Parameterization (UV1)** — выбирать filter с поддержкой существующих UV seams: `Trivial Per-Triangle Parameterization` или `Iso Parametrization`.
+   - Дефолтный `Parameterization: Flat Plane` ломает развёртку UV1 (весь mesh проецируется в одну плоскость).
+   - Симптом: UV1 — degenerate triangles или всё в `(0,0)`.
+
+3. **Remove Duplicate Faces / Remove Duplicate Vertices** — отключать, если есть split UVs.
+   - В 3ds Max split UVs выглядят как «дубликаты» по позиции (но имеют разные UV/normal).
+   - MeshLab их склеивает → теряются UV seams и smoothing groups.
+
+### Export FBX dialog — обязательные настройки
+
+| Опция | Значение | Зачем |
+|-------|----------|-------|
+| `WedgeAllChannels` | **ON** | Сохраняет per-wedge UV / normal (т.е. split UVs / smoothing seams). |
+| `UseExistingNormals` | **ON** | Не пересчитывает нормали (иначе теряются smoothing groups → flat shading). |
+
+### Симптомы плохих настроек в Unity (что ловит валидатор)
+
+- **No UV seams**: `vertexCount` ≈ числу уникальных позиций при наличии нескольких UV-островов → `Merge Close Vertices` или `Remove Duplicate Vertices` склеили wedge.
+- **Flat-shaded normals**: > 90% треугольников имеют 3 одинаковых vertex-нормали, совпадающих с face-normal → нормали пересчитаны без сохранения smoothing.
+- **Degenerate UV1**: > 5% треугольников UV1 с нулевой площадью — broken parameterization.
+- **UV1 all zero**: все UV1 в `(0,0)` — MeshLab стёр UV1 канал.
+- **UV1 out of unit**: > 5% UV1-вершин вне `[0..1]` — Flat Plane / Iso без нормализации.
+
+### Проверка
+
+Перед импортом FBX из MeshLab в Unity:
+1. Прогнать `Tools → Mesh Lab → Validators → Check Imported MeshLab Artifacts` на корне.
+2. Если warning — пересохранить из MeshLab с правильными настройками.
+3. Если повторяется — отключить проблемный filter и переэкспортировать.
+
 ## Эксперимент 2026-05-13 — Pre-pack snap к integer atlas pixels (отклонено)
 
 **Гипотеза:** xatlas `PackCharts` применяет unconditional per-chart `ceil(extents)` rescale (xatlas.cpp:8345-8362) — sub-pixel-thin шеллы амплифицируются и ломают uniform density. Если pre-snap'ить UV extents per-shell к integer pixel grid до xatlas, ceil() становится no-op'ом и density сохраняется без форка xatlas.