BongoCat 桌宠教程：3 步让桌面猫咪跟着键盘和手柄动起来
【免费下载链接】BongoCat🐱 跨平台互动桌宠 BongoCat，为桌面增添乐趣！项目地址: https://gitcode.com/gh_mirrors/bong/BongoCat
BongoCat 是一款跨平台互动桌宠，常驻 macOS、Windows 与 Linux 桌面，实时捕捉键盘、鼠标和手柄输入，让猫咪同步做出敲击、抓握等动作。全程本地运行，无需联网。
安装与启动步骤
- 获取安装包：从项目 Releases 下载对应平台的安装包（Windows 为 nsis 安装程序，macOS 为 dmg，Linux 为 AppImage/deb）。想从源码构建，可执行：
git clone https://gitcode.com/gh_mirrors/bong/BongoCat cd BongoCat && pnpm install && pnpm tauri dev - 启动并授权：首次运行按提示授权。macOS 需到「系统设置 → 隐私与安全性 → 输入监控」添加 BongoCat 后重启应用；Windows 建议以管理员身份运行，部分系统级按键才能稳定捕获。
- 验证效果：桌面上出现透明猫咪窗口，直接打字或移动鼠标，爪子会随之落下、抬起，说明事件监听已生效。
核心功能拆解
🐱 键盘与鼠标实时同步
- 解决什么问题：普通桌宠只会播放固定动画，和你正在做的事毫无关系。
- 如何触发：默认的标准模式下无需任何配置。应用在后端逐键监听系统输入事件（监听逻辑见
src/composables/useDevice.ts），每次键入都会映射到模型对应的按键位置；鼠标移动经阻尼插值后平滑跟随，不会抖动。 - 实际效果：写代码、做表格时，猫爪与你同步敲击；不按任何键时猫咪保持待机姿态。
标准模式内置模型：爪部区域与键位一一对应
键盘模式设置
- 解决什么问题：标准模式下鼠标移动会让猫爪跟随，纯打字场景里这反而显得多余。
- 如何配置：切换内置的键盘模式模型，并在「猫咪设置」中打开忽略鼠标事件，模型不再响应鼠标输入，只保留键盘映射。
- 实际效果：打字时爪子精准起落，其余操作不影响画面，适合长时间编码或写作。
键盘模式模型：黑白配色，按键区域布局清晰
🎮 手柄模式设置
- 解决什么问题：游戏时只盯着屏幕，桌宠沦为背景板。
- 如何配置：使用手柄模式模型，插入手柄即自动进入监听；按键事件经
GAMEPAD_CHANGED事件转发到前端，方向键、肩键、十字键均有独立贴点。 - 实际效果：按下手柄按键，猫咪同步按下对应按钮位置，左右摇杆可驱动抓握动作，录屏或直播时画面更有互动感。
手柄模式模型：左侧按键区与游戏手柄布局对应
📦 自定义模型导入
- 解决什么问题：内置形象只有三套，想换成自己的画风没有入口。
- 如何配置：打开「偏好设置 → 模型管理」，点击或拖入模型文件夹即可导入。文件夹必须包含
*.model3.json主配置文件（内附.moc3模型数据、.cdi3.json碰撞配置与贴图片），缺失主文件会提示"未找到模型主配置文件"。模型源文件位于src-tauri/assets/models/，可参照其目录结构组织。 - 实际效果：导入成功后可删除、重命名，并独立配置该模型的动作与表情。
导入的自定义模型按帧加载贴图片，替换后整体形象随之更新
快捷键与性能调节
- 全局快捷键：为"显示/隐藏猫咪""切换镜像模式""窗口穿透""窗口置顶"录制组合键，配置入口见
src/stores/shortcut.ts。 - 窗口穿透：开启后猫咪窗口不拦截鼠标，可以直接点击它身后的应用。
- 最大帧率：调低渲染帧率可明显减少 CPU/GPU 占用，适合低配机器或长时间挂机。
- 按键自动释放延迟：Windows 下部分按键捕获不到释放事件，可调大延迟兜底。
- 常驻与外观：支持开机自启、托盘图标、不透明度、窗口圆角与"鼠标移入自动隐藏"。
常见问题
Q1：macOS 上猫咪对按键没有反应？未授予输入监控权限。删除旧授权记录后重新添加 BongoCat，并重启应用使其生效。
Q2：Windows 上某些按键按下后不松开？系统级按键的释放事件可能被拦截。尝试以管理员身份运行，或在猫咪设置中调大"按键自动释放延迟"。
Q3：Linux 上装不了？项目目前仅支持 x11 桌面环境，Wayland 下键盘事件无法被全局捕获，暂不可用。
Q4：导入模型提示失败？确认文件夹内存在*.model3.json文件且贴图路径完整；导入时模型会被复制到应用数据目录，源文件夹后续可随意移动。
Q5：如何用 OBS 把猫咪加进直播画面？在「通用设置」中开启"显示任务栏图标"，OBS 即可通过窗口捕获选中该窗口。
结尾
按上文装好后可以直接体验；使用中发现问题，可到仓库提交 Issue，或先点个 Star 支持项目。
【免费下载链接】BongoCat🐱 跨平台互动桌宠 BongoCat，为桌面增添乐趣！项目地址: https://gitcode.com/gh_mirrors/bong/BongoCat
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
