Umbriel 是一款支持滚动、dwindle 与 master 布局、模糊、阴影和流式动画的独立 Wayland 合成器。它的"丝滑感"来自两层可深度调校的机制：[animation]下的弹簧曲线（spring curve）控制窗口、工作区和总览的过渡节奏；触控板手势的惯性物理决定三指切换、四指总览松手后如何自然滑行。本文用最少配置带你把这两层调到手感最佳。

一、动画配置速览：每个事件都有一条独立时间轴

Umbriel 的动画设置集中在[animation]中。顶层提供默认值，每个动画事件都能单独覆盖enabled、duration_ms和curve：

[animation] enabled = true duration_ms = 250 curve = "easeout" [animation.windows_in] # 窗口打开 enabled = true curve = "spring:1,900" style = "popin" scale = 0.5

各事件对应的过渡效果如下：

完整字段说明见 docs/user/animation.md。

💡 重要提示：弹簧曲线会自己决定时长——配置了spring曲线的事件，duration_ms对它不生效，这正是"弹簧手感"与普通缓动最大的区别。

二、如何设置弹簧曲线：spring:damping,stiffness参数详解

除了内置的linear、ease、easeout、snappy、bounce、elastic和自定义贝塞尔曲线（如curve = "0.05,0.9,0.1,1.0"），Umbriel 推荐的丝滑方案是弹簧曲线：

curve = "spring:1,1000" # spring:<阻尼>,<刚度>

两个参数的直觉含义：

• damping（阻尼）：小于 1 会产生回弹过冲；等于 1 精确到达不越界；大于 1 则更缓慢地逼近目标。取值范围 0.01–5.0。
• stiffness（刚度）：越大，弹簧"越硬"，动画越快收住。取值范围 1–10000。

常用组合的手感参考：

参数解析与合法性校验位于 src/config/fields_animation.cpp，弹簧求解器与时长推导在 src/core/animation.h 中实现。

复用命名弹簧：[animation.springs]注册表

如果多个事件共用同一手感，先注册再引用，改一处即全局生效：

[animation.springs] snappy = { damping = 1.0, stiffness = 900 } floaty = { damping = 0.8, stiffness = 300 } [animation.windows_in] curve = "snappy" [animation.workspaces] curve = "floaty"

三、触控板手势物理：三指切换为什么能"甩出去"

Umbriel 的三指工作区切换、四指总览开合、总览内胶片条滚动，共用同一套手势物理：

• 跟手：内容直接跟随手指位移实时渲染，每切换一个工作区约 300 逻辑像素（kSwipeWorkspacePx，见 src/input/swipe_tracker.h）。
• 无阈值判定：松手瞬间没有"过了多少就切换"的硬性分界线，而是把位移和速度一起"投影"到惯性停止点，再吸附到最近的工作区。轻轻一拖会弹回，快速一甩则跨过去。
• 弹簧接力：松手时的速度会带入弹簧动画继续滑行（settleSpring），而不是停住后重新起步；推到边界外的行程有橡皮筋阻尼，不会把整屏"甩飞"。
• 中途可叠加：切换还在收束时再次三指滑动，会从屏幕当前位置继续，而不是硬切到终点。

这套决策逻辑集中在 src/input/gesture_physics.h，设计细节在 docs/design/touchpad-gestures.md。

想让手势的滑行节奏与动画一致，可以为对应事件单独配置弹簧曲线——三指切换用[animation.workspaces].curve，四指总览用[animation.overview].curve，胶片条用overview.workspace_curve：

[animation.workspaces] style = "slide" curve = "spring:1,800" [animation.overview] enabled = true curve = "spring:1,800" workspace_curve = "spring:1,1000"

触控板本身的灵敏度与方向在[input.touchpad]中调节（natural_scroll、sensitivity、scroll_factor、accel_profile等），总览内的手势灵敏度另有[overview] scroll_factor_horizontal / scroll_factor_vertical。完整输入说明见 docs/user/input.md。

四、窗口拖拽弹性物理：windows_drag physics

想让拖动窗口像"弹性薄膜"一样在指针下弯曲、松手后晃动复位，只需一行：

[animation.windows_drag] physics = true

开启后窗口内容会拖尾形变、静止或松手时自然回弹，边框与窗口特效会跟随形变继续渲染；拖到一半关闭窗口也会保持形状淡出。该功能依赖动画总开关enabled = true，形变求解器实现在 src/view/drag_physics.h。

五、一份丝滑的 Umbriel 动画手势参考配置

综合以上调校思路，一份开箱即顺手的参考片段：

[animation] enabled = true duration_ms = 250 curve = "easeout" [animation.springs] settle = { damping = 1.0, stiffness = 900 } # 干脆不越界 drift = { damping = 0.9, stiffness = 400 } # 绵长带一点弹 [animation.windows_in] curve = "settle" style = "popin" scale = 0.5 [animation.windows_out] curve = "settle" style = "popin" scale = 0.8 [animation.windows_move] curve = "settle" [animation.workspaces] style = "slide" curve = "drift" [animation.overview] curve = "drift" workspace_curve = { damping = 1.0, stiffness = 1000 } [animation.windows_drag] physics = true

把这段加入你的~/.config/umbriel/config.toml（可参考 examples/config.toml），保存后即时生效；用umbriel config validate可校验语法。

六、调校清单：如何一步步找到最佳手感

1. 先定主曲线：给windows_in试spring:1,900，刚度从 800 起每 100 步进，选"刚好收住"的值。
2. 再分事件微调：关闭动画通常比打开略快（stiffness 提高 400–500）。
3. 手势曲线单独慢一档：工作区切换比窗口动画略"软"，手指跟感更自然。
4. 需要回弹感就降阻尼：damping从 1.0 降到 0.7–0.8，观察是否有轻微越界回弹。
5. 最后开拖拽物理：physics = true会让移动动画叠加形变，确认整体节奏不冲突。
6. 验证配置：保存后运行umbriel config validate，异常曲线会给出诊断提示。

⚠️ 注意：[animation.<事件>]选择弹簧后，不要再为其设置duration_ms——它会静默失效并产生配置诊断。

按这套"弹簧 + 手势惯性"的组合调校，Umbriel 的窗口过渡、工作区切换与总览操作会形成统一的速度语言，这正是丝滑体验的核心：动画不只好看，而是永远顺着你的手指继续运动。