BongoCat 跨平台互动桌宠上手指南：响应键盘、鼠标与手柄的 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 小猫待在桌面上，眼神与爪子跟随鼠标移动，你按下的每个键盘按键、鼠标键和手柄按键都会触发对应动画。它支持 Windows 与 macOS，可离线运行，不收集用户数据。
一、最快上手路径：克隆、编译与运行步骤
- 克隆仓库：
git clone https://gitcode.com/gh_mirrors/bong/BongoCat- 项目在 rust-toolchain.toml 中固定 Rust 1.97.1，rustup 会按该文件自动拉取工具链。
- 执行
just dev进入开发模式启动完整应用，官方插件由脚本从独立的 BongoCat-Plugins 仓库获取。 - 不想进入完整应用时，可先运行
just preview standard 30做一次确定性的 Live2D 预览。 - 生成当前平台的发布产物用
just build，所有任务定义见 justfile。
二、它解决什么实际问题：编码、输入与手柄场景
编码与写作时
程序员或文字工作者开着这只互动桌宠时，每次按键都会同步触发对应按键动画；叠加窗口默认置顶，也可以开启 click-through 让点击穿透，不挡前台操作。外观、输入、快捷键的默认值都在 shared/config/fixtures/default.json。
键盘重度输入
键盘模型自带成套按键贴图资源，逐键响应更直接，适合长时间以键盘为主的场景。
手柄场景 🎮
接上手柄后，游戏手柄模型会对应每个按键与摇杆做出动画，配置里为摇杆和扳机提供独立死区（默认 0.15 / 0），摇杆漂移不会误触发。
三、它是怎么实现的：全局输入与 Live2D 渲染
全局输入管线。输入侧通过 Windows Raw Input 与 macOS CGEventTap 捕获键鼠边沿事件，映射为平台中立的 HID usage 词汇，比如 Apple 的 Fn/globe 键位于厂商自定义页，被折进同一套词汇统一处理。macOS 首次使用需要系统"输入监控"权限，权限状态只做只读查询、从不持久化，逻辑见 crates/bongocat-platform/src/startup_permission.rs。
Live2D 渲染。应用通过窄 FFI 边界调用官方 Cubism Core 加载 .moc3 模型，原始指针不离开 wrapper 层，参数、动作、表情、物理与状态全部留在 Rust 模块；模型切换按 prepare/validate/commit 执行，失败时保留当前模型。入口在 crates/bongocat-live2d/src/lib.rs。
四、进阶与定制：模型导入与配置调优参数
- 自定义模型导入：支持导入 Live2D 模型包目录；文件夹内嵌套多个模型时会自动扫描、弹框选择并按顺序逐个导入，封面从实际渲染中截取，细节见 docs/adr/ 下的 ADR-0087。
- 叠加窗口参数：maximum_fps（默认 60）、opacity_percent、corner_radius_percent、hide_on_idle 等都在配置的 overlay 命名空间下，字段契约由 shared/config/config.schema.json 定义。
五、边界与局限：平台与权限依赖
- Linux 不在当前支持矩阵内，项目明确将其列为首发后评估项，Wayland 等桌面环境的能力需逐一验证。
- 全局输入依赖系统授权：macOS 未授予"输入监控"权限时键鼠捕获不工作；Windows 部分场景需要提升令牌。
- Live2D 渲染依赖官方按平台分发的 Cubism Core 二进制，项目负责版本与错误边界管理，并非纯 Rust 渲染器。
想深入参与，请读 CONTRIBUTING.zh-CN.md；各关键决策均有 docs/adr/ 下的 ADR 可查。
【免费下载链接】BongoCat🐱 BongoCat — A cross-platform interactive desktop pet that brings fun to your desktop!项目地址: https://gitcode.com/gh_mirrors/bong/BongoCat
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
