编辑器实体 zIndex 层级

07/29

问题

编辑器中墙段被房间面板覆盖不可见。原因：给房间设 zIndex=1 会创建 stacking context，其内部带背景色/TiledImage 的 floorLayer 作为 paint layer 在合成时盖过了同层级 zIndex=2 的墙段——差距太小不够可靠。

解决：底层不设 zIndex，上层用明显间距

错误做法（zIndex 间距太小 + 给底层也设 zIndex）：

lua
-- ❌ 房间 zIndex=1 创建 stacking context，墙 zIndex=2 差距太小不可靠
-- 房间面板
return UI.Panel { zIndex = 1, ... }
-- 墙段面板
local wallPanel = UI.Panel { zIndex = 2, ... }

正确做法（底层无 zIndex 按 DOM 顺序，上层用高 zIndex 强制浮起）：

lua
-- ✅ 房间不设 zIndex，保持默认 auto/0，按 DOM 文档流在底层
return UI.Panel {
    position = "absolute",
    left = (room.x or 0) * gridScale,
    top = (room.y or 0) * gridScale,
    width = width,
    height = height,
    pointerEvents = "box-none",
    -- 不设 zIndex，默认 DOM 顺序
    children = { floorLayer, interactionLayer },
}

-- ✅ 墙段 zIndex=10，足够高确保浮在房间之上
local wallPanel = UI.Panel {
    position = "absolute",
    left = (segment.x or 0) * gridScale,
    top = (segment.y or 0) * gridScale,
    width = math.max(1, (segment.w or 1) * gridScale),
    height = math.max(1, (segment.h or 1) * gridScale),
    backgroundColor = wallColor,
    zIndex = 10,  -- 关键：不设=2，设=10，和底层拉开足够间距
    borderWidth = selected and 1 or 0,
    ...
}

编辑器固定层级方案

编辑器 campusChildren 实体层级（固定 zIndex，不做 Y-sorting）：

zIndex=0（默认/auto）
  ├── 地面区域 floorAreas
  └── 房间 rooms（含 floorLayer 地面纹理/颜色）
  
zIndex=10
  └── 墙段 wallSegments（房间墙+自由墙，浅灰{190,188,180}/门棕黄{200,155,60}）

zIndex=20
  └── 地面物件 objects（扫把、课桌等）
  
zIndex=30
  └── 人员 characters（老师、保安等）
  
zIndex=50+
  └── 各类拖拽预览（房间框选、墙体拖拽、放置预览等）

关键教训

给元素设 zIndex 会创建 stacking context——其内部有 backgroundColor/TiledImage 的子元素会在该 z 平面上渲染 paint layer
两个兄弟节点 zIndex 差距要大（至少 5-10），差距 1-2 在 Yoga 合成时可能被内部 paint layer 覆盖
底层元素不要设 zIndex——让它按 DOM 文档流在底层，上层元素用高 zIndex 浮起最可靠
编辑器用固定层级不做 Y-sorting——编辑器是俯视布局工具，不需要前后遮挡排序；运行时地图才用 zIndex = Z_TIER + Y 动态 Y-sorting
运行时 vs 编辑器层级方案不同：
运行时（校园地图.lua）：动态 Y-sorting，zIndex = CharZ(y) = 2000 + math.floor(y)
编辑器（地图画布.lua）：固定 zIndex 分层，墙=10 / 物件=20 / 人员=30 / 预览=50