Lua相机跟随：死区围栏的视野收敛

flowchart TD
A[每拍读主角坐标] --> B{主角在死区内}
B -- 是 --> C[镜头原地不动]
B -- 否 --> D[镜头按越界量平移]
D --> E[钳制在世界边界内]
E --> A
C --> A

 fx-camfollow

-- @file CameraFollow.lua
-- 相机跟随 —— 死区围栏的视野收敛

local CameraFollow = {}

local CONST = {
    WORLD_WIDTH   = 2400,
    VIEW_WIDTH    = 660,
    DEAD_LEFT     = 230,
    DEAD_RIGHT    = 430,

    COLOR_ZONE    = "#238636",

    ZORDER_CAMERA = 200,
    AUTOINC_BASE  = 1141000,
}

local _camX       = 0
local _heroX      = 0
local _cameraFx   = nil
local _scheduler  = nil
local _autoInc    = 0

local function GenID(prefix)
    _autoInc = _autoInc + 1
    return string.format("%s_%d", prefix or "CMF",
        CONST.AUTOINC_BASE + _autoInc)
end

local function ShowTip(msg)
    if msg and msg ~= "" then SL:ShowSystemTips(msg) end
end

local function ClampCam(x)
    local maxX = CONST.WORLD_WIDTH - CONST.VIEW_WIDTH
    if x < 0 then return 0 end
    if x > maxX then return maxX end
    return x
end

function CameraFollow.SetHero(x)
    _heroX = x
end

function CameraFollow.CamX()
    return _camX
end

-- 死区判定与钳制输出：每拍读主角，出栏才平移
local function StepCamera()
    local dzL = _camX + CONST.DEAD_LEFT
    local dzR = _camX + CONST.DEAD_RIGHT
    if _heroX < dzL then
        _camX = _camX - (dzL - _heroX)
    elseif _heroX > dzR then
        _camX = _camX + (_heroX - dzR)
    end
    _camX = ClampCam(_camX)
    if _cameraFx and not GUI:Widget_IsNull(_cameraFx) then
        GUI:setPosition(_cameraFx, math.floor(-_camX), 0)
    end
end

if not _scheduler then
    _scheduler = SL:Schedule(function(dt)
        StepCamera()
    end, 0.02)
end

local function SafeRemove(node)
    if node and not GUI:Widget_IsNull(node) then
        GUI:removeFromParent(node)
    end
end

function CameraFollow.Bind(node)
    SafeRemove(_cameraFx)
    _cameraFx = node
end

SL:ScheduleOnce(function()
    CameraFollow.Bind(GUI:GetSceneRoot())
    ShowTip("相机跟随已挂载——主角出栏才见镜头动")
end, 1.0)

function CameraFollow.Unload()
    if _scheduler then SL:Unschedule(_scheduler) end
    SafeRemove(_cameraFx)
    _scheduler = nil
end

return CameraFollow