merge: P29 512 沿河组团化 + 夜景灯光径向光晕（lanternFalloff 二次衰减/桥头与门窗 halo）— Hermes 复验通过

1 files changed, 53 insertions, 0 deletions

diff --git a/docs/维护说明.md b/docs/维护说明.md
index 469dbc6..2997f62 100644
--- a/docs/维护说明.md
+++ b/docs/维护说明.md
@@ -543,6 +543,37 @@ dotnet src/LivingVillage.Headless/bin/Release/net8.0/LivingVillage.Headless.dll
   （512 夜巡真实帧，HUD 在屏、民居/石板路清晰）。白块回归 4 张夜景整图 + 571 张夜巡帧
   0 命中。
 
+## P29：512 聚落组团 + 夜景灯光径向光晕（P28 观感遗留）
+
+- **① 聚落组团（仅大图 mapgen 分支 + 独立 group seed）**：`MapGen.Params` 新增 `ClusterSeed`
+  （`paramsForSize` 仅大图时置 `seed ^^^ 0xC1A57E2`，默认 0 且非大图不进入分支）。512 沿河民居
+  不再沿路随机散点，改为沿横向石板路（主街 + 河岸路）成排成组：组内 2-4 座、组内 1 格间隙、
+  组间留 4-6 格空档，宽度仍按 2/3/4 加权；垂柳改为确定性成丛（2-3 株一丛、丛间 3-5 格空档），
+  与成排民居呼应。组发牌走独立 `clusterRng`，不触碰既有 `structureRng`，桥/路/灯笼坐标不变；
+  民居/树仍只落核心区外草地并做重叠检测，BFS 可达性保持。默认图仍 0 额外民居、不消费 RNG，
+  故 **64x48=6042052、256x192=1284656962 逐字节不变**（`DefaultSizeChecksumsArePinned`）。
+- **② 夜景灯光径向衰减（渲染层纯函数）**：新增 `VillageArt.lanternFalloff distance radius`
+  （半径 0 处 =1，边缘 =0，中间 `1-(d/r)^2` 严格单调、无平台）；`lanternGlowLayers` 改为按该衰减
+  的逐环增量累积 alpha，`drawNightGlows` 对「桥头灯笼 + 民居门窗暖光」（`nightLightTiles`）
+  画半径 4 tile、8 环的柔和径向光晕。整图取证（`drawMapFitted`/`drawMapViewport`）与实机
+  `DrawWorldView` 共用同一套函数；无硬方斑、无白块（`check-no-white-blocks` 11 帧 0 命中）。
+- **③ 取证钩子**：复用 `LV_MAPGEN_SHOT` + `LV_MAPGEN_FIT_WIDTH/HEIGHT`（2/4/8 px per tile）与
+  `LV_MAPGEN_NIGHT=1`（23:30 真实 `WorldTint` + golden/moonlight veil）；夜景帧在原整图流程上
+  叠加与实机一致的灯光光晕。
+- **回归**：Kernel 92 / Desktop 151（+6：`ClusterSeedOnlyEnabledForLargeMaps`、
+  `LargeMapHousesFormClusteredRowsWithControlledGaps`、`LargeMapClusterLayoutChecksumIsEmptyDiffAcrossRuns`、
+  `LargeMapWillowsGrowInGroves`、`LanternFalloffIsMaxAtCoreAndMonotonicWithoutPlateau`、
+  `NightLightTilesCombineBridgeLanternsAndHouseWindows`）全绿；Release 0/0；
+  `final_digest=953775FAEB2F…` 3 次一致、`performance_determinism=PASS`。
+- **取证** `/tmp/opencode/lv-p29/art/`：`p29-map-512x384-seed4242-{day,night}.png`（512 整图
+  3072x2304 真实渲染）、`p29-village-cluster-4x-{day,night}.png`（512x256，4px/tile 桥头沿河组团
+  局部，含成排民居/桥/水面）、`p29-lantern-halo-8x-night.png`（192x192，单灯 8px/tile 特写；
+  径向剖面 191→189→183→167→137→113→96→84 平滑递减）、`p29-variant-pair-ab-4x-{day,night}.png`
+  （512x256，A/B 对照）；
+  源帧 `p29-day/`、`p29-night/`、`p29-day8/`、`p29-night8/`；工作区 `art/` 不入 git。
+- **遗留**：民居总数与 P28 相同（24 座），本轮只做「组团化」未继续提高总密度；河岸垂柳成丛后
+  仍为纯视觉层，不参与通行；默认 64x48/256x192 观感不变。
+
 ## 已验证命令
 
 ```bash
@@ -702,6 +733,23 @@ timeout 220 xvfb-run -a -s "-screen 0 1280x720x24" env LV_AUTOPLAY_SAMPLE=1 \
   dotnet src/LivingVillage.Desktop/bin/Release/net8.0/LivingVillage.Desktop.dll
 # 代表帧 p28-night-10100.png -> art/p28-night-village.png
 
+# P29 512 组团 + 夜景光晕取证（4/8 px per tile；night 走 23:30 tint+veil+径向光晕）
+run_p29 () { # $1=fit_w $2=fit_h $3=night(0/1) $4=out_dir
+  local extra=""; [ "$3" = 1 ] && extra="LV_MAPGEN_NIGHT=1"
+  timeout 300 xvfb-run -a -s "-screen 0 1280x720x24" env LV_MAPGEN_SHOT=1 \
+    LV_MAPGEN_WIDTH=512 LV_MAPGEN_HEIGHT=384 LV_MAPGEN_SEED=4242 \
+    LV_MAPGEN_FIT_WIDTH=$1 LV_MAPGEN_FIT_HEIGHT=$2 $extra LV_RECORD_DIR=$4 \
+    dotnet src/LivingVillage.Desktop/bin/Release/net8.0/LivingVillage.Desktop.dll
+}
+run_p29 2048 1536 0 /tmp/opencode/lv-p29/art/p29-day
+run_p29 2048 1536 1 /tmp/opencode/lv-p29/art/p29-night
+run_p29 4096 3072 0 /tmp/opencode/lv-p29/art/p29-day8
+run_p29 4096 3072 1 /tmp/opencode/lv-p29/art/p29-night8
+# 裁剪（PIL）：整图 p20b-map-*.png -> p29-map-*；组团 4x = 2048 帧裁 tile x278..406 y82..146；
+#   单灯 8x = 4096 帧以桥灯 (113,180) 为中心裁 192x192；
+#   A/B 对照 = 2048 帧裁 tile x228..260 y170..186 后 4x NEAREST -> 512x256
+python3 scripts/check-no-white-blocks.py /tmp/opencode/lv-p29/art/p29-night /tmp/opencode/lv-p29/art/p29-night8
+
 # P20 第三步：默认生成器世界的昼夜巡游录制（真走位，含桥面行走帧；p20c-* 命名）
 for pair in day:12.0 night:20.75; do name=${pair%%:*}; hour=${pair##*:}; \
   timeout 150 xvfb-run -a -s "-screen 0 1280x720x24" env LV_AUTOPLAY_SAMPLE=1 \
@@ -790,4 +838,9 @@ python3 scripts/check-no-white-blocks.py evidence/night-run
   `p28-variant-pair-ab-4x-day.png`/`-night.png` A/B 4x 对照、
   `p28-village-core-4x-day.png`/`-night.png`、`p28-village-density-2x-day.png`/`-night.png`、
   `p28-night-village.png` 夜巡代表帧、`night-raw/` 571 帧；工作区内不入 git）
+- `/tmp/opencode/lv-p29/art/`（P29：`p29-map-512x384-seed4242-{day,night}.png` 512 整图、
+  `p29-village-cluster-4x-{day,night}.png` 512x256 桥头沿河组团 4px/tile、
+  `p29-lantern-halo-8x-night.png` 192x192 单灯 8px/tile 光晕特写、
+  `p29-variant-pair-ab-4x-{day,night}.png` 512x256 A/B 对照；源帧 `p29-day/`、`p29-night/`、
+  `p29-day8/`、`p29-night8/`；工作区 `art/` 不入 git）
 - `artifacts/perf-independent/<TS>/`（digest 3 联测回读）