快速了解 hypr-dynamic-cursors

hypr-dynamic-cursors是一款 Hyprland 插件，核心功能正是Shake to Find（晃动查找光标）：当你在屏幕上快速来回晃动鼠标时，光标会瞬间放大数倍，晃得越久越大，让你在一堆窗口中一眼锁定鼠标位置。这个体验类似 KDE Plasma 和 macOS 的光标放大功能，但它是为 Wayland 下的 Hyprland 专门打造的。

除了找光标，它还附带了"拟真光标"玩法：光标准会像真实物体一样在rotate（旋转）、tilt（倾斜）、stretch（拉伸）三种模式下随着移动方向产生形变。如果只想用放大功能，把mode设为none即可。

为什么你需要 Shake to Find 功能？

🤔 在 Hyprland 这种窗口自由摆放的窗口管理器里，找光标尤其困难：

• 深色壁纸 + 深色光标 = 完全隐身
• 多显示器场景下，光标可能跑到另一块屏幕上
• 小尺寸光标在大分辨率屏幕上占比极小

Shake to Find 让你只需一个自然的"急晃"动作，光标就会从原来的尺寸放大到默认4 倍，并且持续晃动还会继续增大，直到停止晃动后 2 秒自动恢复。整个过程无需记忆任何快捷键。

一键安装步骤（hyprpm 方式）

⚠️ 插件仅支持x86_64架构，且要求 Hyprland 版本 ≥v0.41.2。

官方推荐通过hyprpm安装，只需两条命令：

hyprpm add https://github.com/virtcode/hypr-dynamic-cursors hyprpm enable dynamic-cursors

安装后重启会话即可生效。如果你使用NixOS或Gentoo，仓库也提供了专门的安装途径，详见 README.md 中"installation"一节的 Nix flake / Gentoo overlay 说明。

配置安全提示

把插件相关配置放进if判断中，避免插件未加载时报配置错误：

if hl.plugin.dynamic_cursors then hl.config { plugin = { dynamic_cursors = { shake = { enabled = true } }}} end

最快配置方法：shake 参数逐项解析

Shake to Find 的全部配置位于plugin.dynamic_cursors.shake区块。默认配置即可直接用，下面是各参数的含义和调优建议：

灵敏度怎么调？

检测算法会记录光标轨迹：当轨迹的总路程与活动范围对角线的比值超过threshold，且活动范围对角线大于 100 像素时，判定为"晃动"。简单说就是——原地快速画圈或左右快速甩动最容易触发。

如果总觉得不灵敏，按这个顺序调：

1. 把threshold从6.0降到4.0左右
2. 把timeout加大到3000以上，给更多寻找时间
3. 确认晃动时鼠标确实停留了足够范围（≥100px）

核心检测逻辑可以在 src/other/Shake.cpp 中查看，其中trail / diagonal的计算正是 KDE KWin 同款思路。

放大更清晰：hyprcursor 高分辨率支持

默认光标贴图分辨率有限，放大 4 倍后可能发虚。该插件支持通过hyprcursor预加载高分辨率 SVG 贴图，让放大后的光标依然锐利。相关实现在 src/highres.cpp 中。

启用条件（默认全部满足）：

• plugin.dynamic_cursors.hyprcursor.enabled为true
• Hyprland 的cursor.enable_hyprcursor为true
• 你正在使用基于SVG的 hyprcursor 主题

两个常见"翻车"场景：

• XWayland 应用内依然模糊：这类应用使用客户端光标，无法替换为高清贴图。可用hyprcursor.fallback指定一个替代形状（如fallback = "left_ptr"）
• 放大到极致后发糊：高清贴图是按固定尺寸预加载的，超过该尺寸就糊了。用hyprcursor.resolution调高预加载分辨率（-1表示按光标尺寸 × shake.base计算），代价是稍高的内存和加载时间

不想晃鼠标？用快捷键直接放大

除了晃动触发，插件还内置了dispatcher可以让你用键盘一键放大光标，适合演示或临时找光标场景：

hl.bind("SUPER", "F2", "plugin.dynamic_cursors.dsp_magnify", { duration = 2000, size = 6.0 })

• duration：保持放大的毫秒数（可选）
• size：放大倍数（可选）

这样设置后按SUPER + F2，光标立即放大 6 倍并保持 2 秒。触发实现在 src/cursor.cpp 的shake.force()调用中。

进阶：监听晃动事件（IPC）

如果你想在晃动触发时联动其他脚本（比如弹通知、切焦点），可以开启 IPC 事件：

shake = { ipc = true }

开启后，Hyprland 事件 socket 会推送三类事件：

• shakestart：晃动被检测到
• shakeupdate：晃动中每帧触发，附带坐标、轨迹强度、当前缩放倍数
• shakeend：晃动结束（timeout 之后）

⚠️ 注意晃动期间事件量很大，平时建议保持关闭。

只想放大，不要"花哨光标"？

如果你完全不需要 tilt/rotate 的拟真效果，只需要 Shake to Find，这样配置即可：

if hl.plugin.dynamic_cursors then hl.config { plugin = { dynamic_cursors = { enabled = true, mode = "none", -- 关闭所有拟真形变 shake = { enabled = true } }}} end

三种模式简介（来自 README.md）：

• rotate：光标像一根被拖动的杆子，朝移动方向旋转，最逼真
• tilt：按水平速度倾斜，模拟空气阻力，默认模式
• stretch：按速度拉伸变形，漫画感拉满

性能与兼容性注意事项

📌 使用前请留意这几点（详见 README.md 的 performance / compatibility 章节）：

• 软件光标：无额外性能损耗
• 硬件光标：有中等性能损耗；放大时会自动临时切换回软件光标
• NVIDIA 显卡：因驱动限制，插件会自动强制使用软件光标
• XWayland 应用：光标形变规则（shape rules）对其无效
• 项目仍处于早期开发阶段，作者不承诺长期维护，欢迎贡献代码

常见问题速查（FAQ）

Q：晃鼠标没有反应，光标不放大？A：检查shake.enabled是否为true；确认在 Hyprland 会话内而非 X11 会话；把threshold调低；确认晃动幅度大于 100 像素。

Q：如何彻底关闭 Shake to Find？A：设置shake.enabled = false即可，插件其余功能不受影响。

Q：放大倍数上限怎么设？A：默认limit = 0.0即无上限（持续晃会一直变大）。想封顶就设limit = 8.0之类的值，注意低于 1 的值会被视为禁用上限。

Q：配置改完不生效？A：改完hyprland.lua（或对应配置文件）后重新加载配置或重启会话；插件配置支持热重载，但若配置语法错误会被忽略，可用hyprctl检查报错。

总结

hypr-dynamic-cursors 用不到 10 行配置就为 Hyprland 补上了 Wayland 世界长期缺失的Shake to Find体验：晃一下，光标放大 4 倍起步，越晃越大，停晃 2 秒后自动还原。配合 hyprcursor 高清贴图和 dispatcher 快捷键，找光标这件事从此彻底消失。装上它，你的 Hyprland 会立刻好用一个档次 ✨