# Qivomo
**把键盘鼠标的手感，带回手游里**
安卓端本地输入映射工具 · 不读内存 · 不改游戏文件 · 不联网
| [**⬇️ 下载最新版**](https://gitee.com/weiler_qi/qivomo/releases) | [更新日志](CHANGELOG.md) | [免责声明](DISCLAIMER.md) | [反馈问题](https://gitee.com/weiler_qi/qivomo/issues) |
---
## 📥 下载
| 版本 | 体积 | 系统要求 | 下载 |
| ---------- | ------ | ------------ | -------------------------------------------------------------------------------------------- |
| **v1.4.6** | 1.8 MB | Android 7.0+ | [**点击下载 APK**](https://gitee.com/weiler_qi/qivomo/releases/download/v1.4.6/Qivomo-v1.4.6.apk) |
> 只发布正式签名版。若你拿到的安装包被他人重新打包、重新签名或改动过，它并非来自本项目，请勿安装。
> ⚠️ **从 v1.4.5 升级到 v1.4.6 必须先卸载**：1.4.6 起改用正式签名，与旧版签名不同，系统不允许覆盖安装。升级前请先在旧版「设置 → 通用 → 导出配置」备份，卸载后重装再导入。
> 从 v1.4.6 起所有版本共用同一签名，之后升级可直接覆盖。
> 手机上下载后直接点击安装即可；若提示"来源未知"，在浏览器/文件管理里允许安装未知应用。
> 所有历史版本见 [**发行版页面**](https://gitee.com/weiler_qi/qivomo/releases)。
---
## ✨ 这是什么
Qivomo 是一款运行在 Android 上的**本地输入映射工具**。
它的做法是：经 Shizuku 以 shell 身份部署一个原生守护进程，直接读取物理键鼠 / 手柄的输入设备，再把按键与鼠标位移翻译成屏幕上的触摸事件——于是手机上也能用键盘 WASD 走位、用鼠标转视角。
它只是一层"把按键翻译成手指点击"的转换层：
- ❌ 不修改、替换或注入任何游戏文件与进程内存
- ❌ 不读取、篡改游戏与服务器之间的通信
- ❌ 不提供自动瞄准、透视、加速、脚本挂机等任何外挂性质的功能
- ✅ 功能边界等同于系统自带的辅助功能与外接输入设备支持
> **使用场景**：单人游戏、离线游戏、模拟器、无障碍辅助操作、开发调试与教学演示。
> **明确不推荐**用于 PvP / 排位 / 竞技类游戏，详见 [免责声明](DISCLAIMER.md)。
---
## 🎯 功能特性
### 映射引擎
- **原生守护进程接管**：Shizuku 授权后部署 `qivomod`，以 shell 身份直接读取 `/dev/input`，绕过系统对第三方应用的外设限制
- **9 类控件**：按键、组合键、摇杆、视角滑动、连发、宏、多点触控、滚轮、方向移动
- **组合键**：成员键全部按住才触发，例 `Ctrl + Shift + P`，松开任一键立即抬起
- **按应用自动匹配**：场景绑定包名后，切到该应用自动套用对应配置。前台应用由 Shizuku 以 `dumpsys window` 轮询识别，命中即关闭管道，开销极低
- **参考分辨率**：坐标按屏幕比例保存，同一配置可跨分辨率复用；支持自动读取本机分辨率或手动指定
### 悬浮球就地编辑
- 编辑时**不再有铺满屏幕的编辑界面**，游戏画面全程可见
- 屏幕上只保留半透明控件圆圈，拖动即摆位，点空白处按一下键就完成绑定
- 悬浮球旁的编辑面板管理控件列表、类型与保存，头部固定、表单滚动，横屏也不会把按钮挤出屏幕
### 外设与手感
| 分类 | 可调项 |
| ------- | ------------------------------------------------------------------------------------------------------- |
| 🖱️ 鼠标 | 灵敏度（全局 + XY 单轴，0.2x–3.0x）、回报率（自动 / 125–1000Hz / 不限）、平滑滤波（4 档）、加速曲线（关 / 线性 / 非线性） |
| ⌨️ 键盘 | 重复延迟（100–1500ms）、重复频率（5–60 次/秒）、长按判定（150–2000ms） |
| 🎮 手柄 | 品牌识别（Xbox / 任天堂 / Sony / 飞智 / 北通 / 八位堂…）、摇杆死区、外圈灵敏度、响应曲线（线性 / 缓入 / 缓出 / S 型）、扳机阈值 |
| 📡 外设状态 | 自动扫描输入设备，**只列真实外接设备**（指纹、电源键等板载节点按名字黑名单 + `InputDevice.isExternal()` 双重过滤），显示名称、连接方式（有线 / 蓝牙 / 2.4G）与电量 |
所有参数**运行中即时生效**，不需要重启映射。
### 界面与主题
- Material 3 · Compose 实现，圆形揭示转场（扩散 420ms / 收缩 300ms）
- 底部胶囊导航 + 单个滑块过渡，支持跟手拖动
- 主色 / 辅色 / 字体色 / 描边色四项独立，色轮 + 明度条 + HEX + RGB 三向联动
- 悬浮球形状、尺寸、透明度、锁定位置均可调，隐藏后缩成顶部三个点的细条
- **「关于」页**：应用图标 + 版本号 + 一句话定位，附「检查更新」（指向 Gitee / GitHub 仓库）、「关于开发者」、「免责声明」三个入口
### 配置互通
- **JSON 导入导出**：完整保留配置结构与包名绑定
- **分享码**：导出为 `QVM.xxxxx` 一行文本，粘贴即可导入，兼容旧版 `KM1.` 前缀
- 配置全部保存在**本机**，不上传任何服务器
### 首次启动与权限
- 第一次打开先弹**免责声明**（与应用内「关于 → 免责声明」同一份内容），必须滑到底才点亮「同意」，不同意直接退出
- 同意后才询问「显示在其他应用上层」权限；选「否」也能继续，之后在激活页补授权即可，全程只问一次
- **不申请无障碍服务**：注入只保留一条通道。无障碍读不到鼠标相对位移，其手势指针还会和注入通道抢同号触点、打断正在进行的视角拖动
激活页底部按钮**按顺序引导**，文案随第一个未完成项变化：
| 情况 | 按钮 |
| ----------- | ----------- |
| 未安装 Shizuku | 去下载 Shizuku |
| 服务未运行 | 去启动服务 |
| 未授权 Qivomo | 去授权 |
| 无悬浮窗权限 | 去设置 |
| 四项全正常 | 已全部授权（置灰） |
### 调试
- 指针十字准线、按键事件日志、鼠标回报率采样，仅在开启时挂载叠加层
---
## 📸 界面预览
> 截图存放规范：`assets/screenshots/01-home.png`、`02-edit.png`、`03-settings.png`，建议 1080×2400 竖屏、单张控制在 300 KB 内。
---
## 🚀 快速开始
### 1. 安装
下载上方 APK 安装。首次安装需允许"安装未知来源应用"。
> **最低可安装版本：v1.4.5。** 今后如需回退版本，只能回到 v1.4.5，更早的安装包不再提供；回退必须先卸载（Android 不允许安装 versionCode 更低的包），而卸载会清空本机配置与「已同意免责声明」状态，请提前在设置里导出备份。
### 2. 首次启动
1. 先弹**免责声明**——滑到底部才能点亮「同意」，建议真的读一遍
2. 随后询问是否前往授权「显示在其他应用上层」，点「是」直接跳到授权页
3. 跳过或选「否」也能继续，回头在「激活与权限」页补上
### 3. 准备 Shizuku
Qivomo 通过 Shizuku 获取 shell 权限，**不需要 Root**。
1. 安装 [Shizuku](https://shizuku.rikka.app/)（也可在应用商店搜索）
2. 打开 Shizuku，按引导通过**无线调试**或 **ADB** 启动服务
3. 回到 Qivomo →「激活与权限」页，按底部按钮的指引依次完成：去授权 Shizuku → 去设置悬浮窗
### 4. 建一个场景
1. 首页「新建」→ 选择要绑定的应用（或选「通用配置」）
2. 选择参考分辨率（默认「自动（本机）」即可）
3. 点「在悬浮球上编辑映射」→ 点屏幕空白处 → 按一下键盘上的键 → 圆圈出现，拖到目标位置
4. 「完成」保存 → 点「开始映射」→ 切回游戏
> 详细图文步骤可看 [更新日志](CHANGELOG.md) 中各版本的功能说明。
---
## 📋 系统要求
| 项目 | 要求 |
| ---- | ------------------------------------- |
| 系统版本 | Android 7.0（API 24）及以上 |
| 架构 | arm64-v8a / armeabi-v7a |
| 必需权限 | Shizuku 授权、悬浮窗、通知 |
| 注入通道 | 仅 Shizuku 注入（无无障碍降级；注入器起不来会直接报错并保持停用） |
| 网络 | **不需要**，应用不发起任何联网请求 |
| Root | **不需要** |
**已知限制**
- 手柄震动强度目前只保存设置，力反馈尚未实现（不会报错，但无震感）
- 手柄品牌识别影响扳机行程上限（Xbox 1023 / 任天堂、Sony 255），个别第三方手柄轴范围可能有偏差
- 部分深度定制 ROM 会限制悬浮窗层级，可能需要额外开启"后台弹出界面""自启动"权限
---
## ❓ 常见问题