Lua弹簧跟随：速度累积的阻尼收敛

flowchart TD
A[每一拍读取目标点] --> B[力差 = 目标减当前]
B --> C[速度 = 速度加力差乘劲度]
C --> D[速度乘阻尼衰减]
D --> E[位置加速度推进]
E --> A

 fx-springfollow

-- @file SpringFollow.lua
-- 弹簧跟随 —— 速度累积的阻尼收敛

local SpringFollow = {}

local CONST = {
    STIFFNESS     = 0.08,
    DAMPING       = 0.90,
    STEP_SCALE    = 60,
    SNAP_DIST     = 0.5,

    COLOR_FOLLOW  = "#58a6ff",
    COLOR_TARGET  = "#f0883e",

    ZORDER_FOLLOW = 140,
    AUTOINC_BASE  = 1140000,
}

local _tx, _ty     = 0, 0
local _x, _y       = 0, 0
local _vx, _vy     = 0, 0
local _followFx    = nil
local _scheduler   = nil
local _autoInc     = 0

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

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

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

function SpringFollow.SetTarget(x, y)
    _tx, _ty = x, y
end

function SpringFollow.SetPos(x, y)
    _x, _y = x, y
    _vx, _vy = 0, 0
end

-- 速度累积与阻尼收敛：每拍按时间步长推进
local function StepSpring(dt)
    local step = dt * CONST.STEP_SCALE
    _vx = (_vx + (_tx - _x) * CONST.STIFFNESS * step)
        * math.pow(CONST.DAMPING, step)
    _vy = (_vy + (_ty - _y) * CONST.STIFFNESS * step)
        * math.pow(CONST.DAMPING, step)
    _x = _x + _vx * step
    _y = _y + _vy * step
    local dist = math.sqrt((_tx - _x) ^ 2 + (_ty - _y) ^ 2)
    if dist < CONST.SNAP_DIST
        and math.abs(_vx) + math.abs(_vy) < CONST.SNAP_DIST then
        _x, _y = _tx, _ty
        _vx, _vy = 0, 0
    end
end

function SpringFollow.Bind(node)
    SafeRemove(_followFx)
    _followFx = node
end

if not _scheduler then
    _scheduler = SL:Schedule(function(dt)
        StepSpring(dt)
        if _followFx and not GUI:Widget_IsNull(_followFx) then
            GUI:setPosition(_followFx,
                math.floor(_x), math.floor(_y))
        end
    end, 0.02)
end

SL:ScheduleOnce(function()
    local root = GUI:GetRootWindow()
    SpringFollow.SetPos(300, 200)
    SpringFollow.SetTarget(300, 200)
    SpringFollow.Bind(root)
    ShowTip("弹簧跟随已挂载——改目标看收敛")
end, 1.0)

function SpringFollow.Unload()
    if _scheduler then SL:Unschedule(_scheduler) end
    SafeRemove(_followFx)
    _scheduler = nil
end

return SpringFollow