大厅校准模式

一、整体架构

二、关键设计经验

lua
lobbyCalibrationMode_ = false,            -- 是否在校准模式
lobbyCalibrationDrag_ = nil,              -- 当前拖拽上下文
lobbyCalibrationSlots_ = nil,             -- { window={[i]={x,y,w,h}}, cannon={[key]={...}} }
lobbyCalibrationRestorePending_ = true,   -- 云存档未到达前阻塞大厅渲染
lobbyCalibrationSaveStatus_ = "未保存",
isAdmin_ = false,
LOBBY_CALIBRATION_PATH = "friendship_boat_lobby_calibration.pref",

• 所有槽位用 0~1 相对 shipSize（船体基准边长）存储。
• 炮孔按钮使用 inset=0.10 内缩，通过 ResolveInsetSlot 在「可拖动逻辑框」和「实际按钮渲染框」之间换算：

lua
ResolveInsetSlot = function(slot)
    local inset = slot.inset or 0
    local x = slot.x + slot.w * inset
    local y = slot.y + slot.h * inset
    local w = slot.w * (1 - inset * 2)
    local h = slot.h * (1 - inset * 2)
    return x, y, w, h
end

lua
local function AttachCalibrationHandlers(widget, calibrationHandlers)
    if not calibrationHandlers then return widget end
    local baseDown, baseMove, baseUp, baseCancel =
        widget.OnPointerDown, widget.OnPointerMove, widget.OnPointerUp, widget.OnPointerCancel
    function widget:OnPointerDown(event)
        if baseDown then baseDown(self, event) end
        calibrationHandlers.down(event, self)
    end
    function widget:OnPointerMove(event)
        if baseMove then baseMove(self, event) end
        calibrationHandlers.move(event, self)
    end
    function widget:OnPointerUp(event)
        if baseUp then baseUp(self, event) end
        calibrationHandlers.up(event, self)
    end
    function widget:OnPointerCancel(event)
        if baseCancel then baseCancel(self, event) end
        calibrationHandlers.up(event, self)  -- cancel 走 up 收尾，避免残留拖拽
    end
    return widget
end

lua
local function BeginCalibrationDrag(kind, key, slot, event, widget)
    if not lobbyCalibrationMode_ then return end
    local startX, startY = GetCalibrationPointerBasePosition(event, widget)
    lobbyCalibrationDrag_ = {
        kind=kind, key=key,
        startX=startX, startY=startY,
        slotX=slot.x, slotY=slot.y, slotW=slot.w, slotH=slot.h,
        inset=slot.inset, widget=widget,
    }
end

local function UpdateCalibrationDrag(event, widget)
    local drag = lobbyCalibrationDrag_
    if not lobbyCalibrationMode_ or not drag then return end
    local currentX, currentY = GetCalibrationPointerBasePosition(event, widget or drag.widget)
    local dx = (currentX - drag.startX) / shipSize
    local dy = (currentY - drag.startY) / shipSize
    local nextSlot = {
        x = Clamp(drag.slotX + dx, 0, 1 - drag.slotW),
        y = Clamp(drag.slotY + dy, 0, 1 - drag.slotH),
        w = drag.slotW, h = drag.slotH,
    }
    SetCalibrationSlot(drag.kind, drag.key, nextSlot)
    -- cannon 要反向 inset 换算回按钮真实坐标
    local leftSlot = nextSlot
    if drag.kind == "cannon" then
        local xNorm, yNorm = ResolveInsetSlot({ x=nextSlot.x, y=nextSlot.y, w=nextSlot.w, h=nextSlot.h, inset=drag.inset })
        leftSlot = { x=xNorm, y=yNorm }
    end
    drag.widget:SetStyle({
        left = math.floor(shipSize * leftSlot.x),
        top  = math.floor(shipSize * leftSlot.y),
    })
end

local function EndCalibrationDrag()
    if lobbyCalibrationDrag_ then FillAllCalibrationSlots() end
    lobbyCalibrationDrag_ = nil
end

• GetCalibrationPointerBasePosition 先尝试 UI.Input.GetPointer（DPR/scale 一致的全局坐标），失败再回落到 widget:GetAbsoluteLayout() + event.xy，兼容触摸与鼠标。
• Clamp(..., 0, 1 - size) 防止按钮被拖出船体；尺寸 w/h 保持不变（只支持平移，不支持缩放，简化心智）。
• 拖拽结束不自动保存（本次 UX 修复点），只把当前 UI 位置回灌进 lobbyCalibrationSlots_，等用户点「保存」。

lua
local function MakeCalibrationHandlers(kind, key, slot)
    if not lobbyCalibrationMode_ then return nil end
    return {
        down = function(event, widget) BeginCalibrationDrag(kind, key, slot, event, widget) end,
        move = function(event, widget) UpdateCalibrationDrag(event, widget) end,
        up   = function() EndCalibrationDrag() end,
    }
end

lua
children[#children + 1] = CreateRoomWindow(lobbyRooms_[i], i, slot, shipSize,
    SendCreateRoom, SendJoinRoom, MakeCalibrationHandlers("window", i, slot))
...
children[#children + 1] = CreateShipActionButton(createSlot, SendCreateRoom, nil,
    MakeCalibrationHandlers("cannon", "create", createSlot))
children[#children + 1] = CreateShipActionButton(ticketSlot, ..., MakeCalibrationHandlers("cannon", "ticket", ticketSlot))
children[#children + 1] = CreateShipActionButton(aiSlot, ...,     MakeCalibrationHandlers("cannon", "ai", aiSlot))
children[#children + 1] = CreateShipActionButton(refreshSlot, ...,MakeCalibrationHandlers("cannon", "refresh", refreshSlot))
children[#children + 1] = CreateShipActionButton(shopSlot, ...,   MakeCalibrationHandlers("cannon", "shop", shopSlot))

lua
local function SerializeLobbyCalibrationSlots(slots)
    slots = slots or {}
    local lines = {}
    if slots.window then
        local indices = {}
        for index in pairs(slots.window) do indices[#indices+1] = index end
        table.sort(indices, function(a,b) return tonumber(a) < tonumber(b) end)
        for _, index in ipairs(indices) do
            local s = slots.window[index]
            if s then lines[#lines+1] = table.concat({"window", tostring(index),
                tostring(s.x), tostring(s.y), tostring(s.w), tostring(s.h)}, "|") end
        end
    end
    if slots.cannon then
        local keys = { "create", "ticket", "ai", "refresh", "shop" }  -- ← bug 就是漏了 "shop"
        for _, key in ipairs(keys) do
            local s = slots.cannon[key]
            if s then lines[#lines+1] = table.concat({"cannon", key,
                tostring(s.x), tostring(s.y), tostring(s.w), tostring(s.h)}, "|") end
        end
    end
    return table.concat(lines, "\n")
end

lua
function Client.LoadLobbyCalibration()
    lobbyCalibrationRestorePending_ = true
    -- 1) 本地 pref 立即生效，避免云存档慢导致闪默认位置
    if fileSystem and fileSystem:FileExists(LOBBY_CALIBRATION_PATH) then
        local file = File(LOBBY_CALIBRATION_PATH, FILE_READ)
        if file and file:IsOpen() then
            ApplyLobbyCalibrationText(file:ReadString(), "local"); file:Close()
        end
    end
    -- 2) 服务端 serverCloud 后到，覆盖本地（跨设备同步）
end

function Client.SaveLobbyCalibration()
    local text = SerializeLobbyCalibrationSlots(lobbyCalibrationSlots_)
    local file = File(LOBBY_CALIBRATION_PATH, FILE_WRITE)  -- 写本地
    if file and file:IsOpen() then file:WriteString(text); file:Close() end
    if serverConnection_ then
        local data = VariantMap()
        data["Text"] = Variant(text)
        serverConnection_:SendRemoteEvent(Shared.EVENTS.SAVE_LOBBY_CALIBRATION, true, data)  -- 上行云存档
    end
end

• 本地优先：进大厅先用 pref 定位，云存档到达后再覆盖。
• 恢复门控：lobbyCalibrationRestorePending_=true 期间渲染 CreateLobbyCalibrationLoadingPanel()，防止默认位置先闪一下再跳。
• 服务端只在管理员 UID 写云 key（Server.lua 硬编码 ADMIN_UIDS["1051336128"]=true），普通玩家的保存只写本地，避免互相覆盖全局模板。

1. 拖拽结束 ≠ 保存：EndCalibrationDrag 只做 FillAllCalibrationSlots()，不调 Save。用户必须点「保存」才提交，避免误碰一下就写脏。
2. 设置面板不自动关闭：开启校准、保存、重置都不要 layoutSettingsOpen_ = false，让用户能"拖→看效果→再拖→保存"循环操作。
3. 文案两态自解释：
4. 开启："校准模式已开启：拖动船舱窗口和右侧按钮调整位置，完成后点击「保存」。"
5. 关闭："校准已关闭：点击「开启校准」后可拖动船舱窗口和右侧按钮自定义位置。"

lua
local function GetWindowSlot(index)
    local override = lobbyCalibrationSlots_ and lobbyCalibrationSlots_.window and lobbyCalibrationSlots_.window[index]
    return ApplySlotOverride(SHIP_WINDOW_SLOTS[index], override)
end

lua
onClick = function()
    if calibrationHandlers then return end  -- 校准模式下点击不生效
    Client.PlaySfx("click")
    ...
end,

三、踩坑清单（已修）