UI按键动画设计

一、本次反复失败的根因（三个坑）

二、三条铁律

1. 静态可见：按钮构建时 scale=1, alpha=1，绝不用动画"让它出现"。动画只做 hover/press 增强。
2. 帧内驱动：动画在 _Render 里用 os.clock() 算 dt + 逐帧 lerp；鼠标事件只写目标值，不直接改显示值。
3. 浮点色：一律 nvgRGBAf(0..1)；文字纯白配深色按钮，不用描边文字。

三、架构：双层状态 + 帧内 lerp

鼠标事件 ──只写目标──▶ AnimState{当前值, 目标值, 旋转相位}
_Render 每帧 ─os.clock()dt──▶ lerp(当前→目标) ──▶ nvgTranslate/Rotate/Scale 绘制

• 分离 X/Y lerp 速度 = GDScript scale:x 0.2s / scale:y 0.35s（Y 慢→拉伸感）
• 旋转两阶段（flick 甩出 → return 弹回）= GDScript 的 rotation→target 再 →0 set_delay
• 随机方向、clamp(WIDTH_FULL_ROT/w,0.5,1.0) 尺寸自适应，原样移植

四、关键代码

lua
local WIDTH_FULL_ROT, LERP_SCALE_X, LERP_SCALE_Y, LERP_ROT, FLICK_DURATION = 300, 0.18, 0.10, 0.25, 0.1
local function lerp(a,b,t) return a+(b-a)*t end
self._anim[i] = { scaleX=1,scaleY=1,rotation=0, targetScaleX=1,targetScaleY=1, rotPhase=0,rotTimer=0,rotImpulse=0 }

lua
local ratio = math.max(0.5, math.min(1.0, WIDTH_FULL_ROT / btn.w))
local dir = (math.random() > 0.5) and 1 or -1
a.targetScaleX, a.targetScaleY = 1.0 + 0.2*ratio, 1.0 + 0.2*ratio
a.rotPhase, a.rotTimer, a.rotImpulse = 1, 0, 5.0*ratio*dir   -- 离开时设 1.0 / rotPhase=0

lua
local dt = os.clock() - self._lastClock; if dt > 0.1 then dt = 0.016 end; self._lastClock = os.clock()
for _,a in ipairs(self._anim) do
    a.scaleX = lerp(a.scaleX, a.targetScaleX, LERP_SCALE_X)   -- X 快
    a.scaleY = lerp(a.scaleY, a.targetScaleY, LERP_SCALE_Y)   -- Y 慢
    if a.rotPhase==1 then a.rotation=lerp(a.rotation,a.rotImpulse,LERP_ROT); a.rotTimer=a.rotTimer+dt; if a.rotTimer>=FLICK_DURATION then a.rotPhase=2 end
    elseif a.rotPhase==2 then a.rotation=lerp(a.rotation,0,LERP_ROT); a.rotTimer=a.rotTimer+dt; if a.rotTimer>=FLICK_DURATION or math.abs(a.rotation)<0.1 then a.rotation,a.rotPhase=0,0 end
    elseif math.abs(a.rotation)>0.01 then a.rotation=lerp(a.rotation,0,LERP_ROT*0.5) else a.rotation=0 end
end
-- 弹跳(scale>1.15)结束后把目标拉回悬停值/1.0
for i,a in ipairs(self._anim) do if self.pressedIdx~=i and a.scaleX<1.15 then
    local st = self.hoveredIdx==i and 1.0+0.2*math.max(0.5,math.min(1.0,WIDTH_FULL_ROT/self.buttons[i].w)) or 1.0
    a.targetScaleX, a.targetScaleY = st, st
end end

lua
nvgSave(vg); nvgTranslate(vg,btn.cx,btn.cy); nvgRotate(vg,a.rotation*math.pi/180); nvgScale(vg,a.scaleX,a.scaleY)
nvgBeginPath(vg); nvgRoundedRect(vg,-halfW,-halfH,btn.w,btn.h,28); nvgFillColor(vg,nvgRGBAf(r,g,b,1.0)); nvgFill(vg)
nvgFillColor(vg,nvgRGBAf(1,1,1,1)); nvgText(vg,0,0,btn.label,nil)   -- 纯白，不描边
nvgRestore(vg)

五、何时仍可用旧的自建补间引擎

• 单文件 Demo（自己掌控 Start+Update 主循环，Update 一定跑）→ 自建 Tween 可用。
• Boot/Router/EventBus 多页面模板（页面 Update 不一定每帧转发）→ 必须用本节 _Render 帧内方案。