BongoCat 桌宠完整指南：5 步养好一只会敲键盘的 Live2D 小猫

【免费下载链接】BongoCat🐱 BongoCat — A cross-platform interactive desktop pet that brings fun to your desktop!项目地址: https://gitcode.com/gh_mirrors/bong/BongoCat

BongoCat 是一款纯 Rust 编写的跨平台交互桌宠：一只 Live2D 小猫住在你的屏幕角落，目光和爪子跟着鼠标走，你敲下的每个键、手柄上按下的每枚按钮，它都会做出对应的动作。装上它，写代码、打游戏、做 PPT 的过程会多一份即时反馈，而且全程离线运行、不收集任何数据。

在 Windows 和 macOS 上安装 BongoCat 的完整步骤

这一节解决"怎么把这只猫跑起来"。仓库是一个 Cargo workspace（见根目录 Cargo.toml），当前产品版本面向 macOS 与 Windows 两个平台，Linux 属于计划中的后续目标，暂不覆盖。

• 普通用户：从项目的 release 渠道下载对应系统的安装包，双击完成安装，无需任何运行环境。
• 源码构建：先安装 Rust 工具链和任务管理工具just，然后：

git clone https://gitcode.com/gh_mirrors/bong/BongoCat just build

仓库里的 justfile 把常用动作都做成了 recipe：just dev启动开发版，just preview standard 30可以单独跑一个确定性的 Live2D 预览窗口，just test与just check则是完整的测试与质量门禁。它对你意味着什么：改任何代码之前，先跑一遍门禁就能确认没把渲染或配置逻辑改坏。

BongoCat 桌宠的三大输入模式与核心功能一览

这一节用一张表说清楚"它能干什么、谁会用得上"。

键盘模型的键位图层，覆盖完整键位词表

手柄模型的按键图层，左右各 6 枚

完整功能清单见 README.md。

桌宠外观、模型切换与 8 个关键配置项建议值

这一节解决"怎么把它调成自己喜欢的样子"。所有外观与模型设置最终落在本地config.json，字段全集和取值范围见 shared/config/config.schema.json，语义解释见 shared/config/contract.md。

• overlay.opacity_percent：窗口不透明度，默认 100；猫窗口本身是透明的，日常建议保持 100，想更低调时降到 70~90。
• overlay.maximum_fps：目标帧率，范围 15~240，默认 60；核显或集显本可降到 30~45，省下的功耗立刻能感觉到。
• overlay.corner_radius_percent：窗口圆角，范围 0~50；取 10~25 时边缘最柔和，0 为直角。
• overlay.scale_percent：模型缩放，默认 100；小屏笔记本建议 80 左右，避免挡住任务栏。
• model.play_motion_audio：动作音效开关，默认关闭；需要"敲键盘有声音"的氛围感时再打开。
• model.random_behavior.mode+interval_seconds：无人操作时随机播放表情或动作，默认 off；想让它"自己活起来"就设成expressions、间隔 30 秒。
• input.gamepad.stick_dead_zone：摇杆死区，默认 0.15；手柄摇杆漂移误触时可调到 0.2~0.3。
• appearance.language：界面语言，支持简体中文在内的 8 种语言，默认system跟随系统。

模型切换在设置窗口的模型页完成：三个内置模型（standard、keyboard、gamepad）各是一张卡片，可重命名。喜欢手柄玩法的话，还可以打开model.gamepad_auto_switch，插上手柄自动切到手柄模型、拔下再切回来，不用手动点。

导入自定义 Live2D 模型与开发者扩展的入口

这一节回答"怎么换一只自己的猫"以及"想改代码从哪里下手"。

• 导入模型：在设置窗口里选一个完整模型文件夹即可，里面需要.model3.json、.moc3、.cdi3.json与 PNG 纹理，内置包的结构可以参考 resources/models/ 下 standard 目录的排布。导入时必须选定交互模式：standard（鼠标 + 键盘）、keyboard（仅键盘）或gamepad（仅手柄）；模式判定依据是模型里左/右手键位图（left-keys/right-keys）的排布，判定失败会直接拒绝导入，不会给你留下一只"半残"的猫。
• 动作层行为：导入后可以按需开启allow_motion_overlap（多段动作叠加播放）、remember_last_expression（切回模型时恢复上次的表情），语义细节都在 shared/config/contract.md 里写明了。

如果你打算写代码，仓库按 Cargo crate 切分，职责边界清晰：

• crates/bongocat-input/：键盘、鼠标与手柄的原始采集和状态对齐，是所有动作的源头。
• crates/bongocat-live2d-playback/：动作与表情的播放调度，想让"新行为"按你的规则触发，改这里。
• crates/bongocat-config/：配置的读写、原子提交、备份与损坏恢复，任何新增设置项都从这里的 Rust 类型出发。
• 插件体系：官方插件放在独立仓库，通过环境变量BONGOCAT_PLUGINS_ROOT指向本地 checkout，再跑just dev即可随应用一起构建加载；插件以独立进程运行，单个插件崩溃不会带崩主应用。

贡献规范见 CONTRIBUTING.zh-CN.md，提交前跑一遍just check是硬性要求。

调低帧率、修好卡键与 4 个高频问题避坑

这一节收集最容易踩的坑，先给三条实用技巧：

• 高刷屏 + 显卡较弱：把maximum_fps从默认 60 降到 30~45，帧间隔按截止时间计算，帧率降了但动作节拍不乱。
• 全屏游戏里猫不跟手：多数游戏会捕获并"钉住"光标，此时绝对坐标不动。打开input.mouse.force_move改为按设备报告的相对位移累加，猫就能继续跟随；代价是程序化移动指针（比如自动定位）不再被感知，所以默认是关的。
• 想让猫"隐身"：开启hide_on_idle并设 10 秒延迟，手一停它就淡出并临时穿透；再开hold_modifier_to_interact配一个修饰键，需要拖窗口时按住该键即可把它"抓回来"。

常见问题：

Q：猫卡着某个键不放怎么办？A：不会发生。释放只由真实的 KeyUp、平台状态校正或生命周期 Reset 触发，项目刻意不用"超时自动松手"来区分慢帧和卡键。

Q：导入自定义模型失败？A：先核对文件是否齐全（.model3.json、.moc3、.cdi3.json、纹理），再确认交互模式与键位图排布匹配——判定失败会直接拒绝，而不是导入后无法使用。

Q：运行会上传数据吗？A：不会。核心功能完全离线，配置与窗口状态都写在本机，更新检查默认也是关闭的。

Q：Linux 上能用吗？A：当前正式发行只覆盖 macOS 与 Windows，Linux 支持见仓库的 ADR 文档，暂不可用。

关键资源与上手清单

继续深入时按这份路径走：

• 配置字段全集：shared/config/config.schema.json
• 每个字段的语义与边界：shared/config/contract.md
• 内置模型源码结构：resources/models/
• 开发者任务脚本：justfile
• 贡献指南：CONTRIBUTING.zh-CN.md

上手清单：

1. 下载安装包（或just build），让猫先在屏幕角落出现。
2. 把窗口拖到顺眼的位置，设置scale_percent与corner_radius_percent。
3. 按使用场景挑一个内置模型，游戏玩家顺手打开gamepad_auto_switch。
4. 导入自己的 Live2D 模型，选对交互模式。
5. 想动手改代码：读justfile，跑just check，从crates/bongocat-input开始顺藤摸瓜。

【免费下载链接】BongoCat🐱 BongoCat — A cross-platform interactive desktop pet that brings fun to your desktop!项目地址: https://gitcode.com/gh_mirrors/bong/BongoCat