企业官网建设流程全解析

QtScrcpy 自定义按键映射实战：从零配好一套手游键鼠映射脚本

【免费下载链接】QtScrcpyAndroid real-time display control software项目地址: https://gitcode.com/GitHub_Trending/qt/QtScrcpy

在电脑上用键盘鼠标玩手游，体验差距往往体现在"移动、瞄准、拾取"这些高频操作上。QtScrcpy 的按键映射（KeyMap）功能正是解决这个问题的：你只需写一份 JSON 脚本，把键盘按键、鼠标按键映射到屏幕上的手指点击、拖拽或"方向盘"滑动，之后 WASD 就能移动人物、鼠标移动就能转视角、一键完成多点连点。本文带你从连接好手机的 QtScrcpy 开始，一步步产出一份可以上手的映射脚本，最终效果参考仓库自带的 和平精英映射示例——20 多个按键点位 + 鼠标转视角 + WASD 移动，全部由一份 JSON 驱动。

准备工作：连接设备并认识三种脚本

开始前确认三件事：

1. 已安装 QtScrcpy 并成功投屏（USB 或无线均可）。
2. 你的设备支持投屏控制，主界面能正常操作鼠标点击。
3. 仓库或程序目录下有现成的keymap/目录可参考，内含 5 个官方示例：gameforpeace.json（FPS 完整映射）、FRAG.json（Frag Pro Shooter）、identityv.json（第五人格，含拖拽节点）、tiktok.json（滑屏刷视频）、test.json（最小测试脚本，适合起步）。

主界面上有一个"游戏脚本"下拉框，旁边是"刷新脚本"和"应用脚本"两个按钮——这就是整套映射的入口：脚本放在 keymap 目录 → 刷新脚本让它出现在下拉框 → 选中后应用脚本下发到设备。

另外理解一个核心概念：映射文件里的switchKey是一个切换键。未切换时是普通映射（鼠标直接控制手机），按下该键后进入自定义映射，再按一次切回。所有示例脚本都用Key_QuoteLeft（键盘左上角的`键）作为切换键。

第 1 步：搞清楚脚本该放哪个目录

新增的映射文件必须放在keymap目录中才能被识别，这是唯一的硬性规则。

• 程序默认从可执行文件所在目录下的keymap/读取脚本（即本仓库根目录的 keymap/ 里那批示例）。
• 你也可以通过环境变量QTSCRCPY_KEYMAP_PATH指定自己的目录，适合不想动安装目录的用户；未设置时程序会回退到用户数据目录下的keymap/，并把默认脚本复制一份过去。
• 逻辑见 dialog.cpp 中的getKeyMapPath()与initializeKeyMapDirectory()。

⚠️ 常见困惑：改完文件下拉框里没有？点一下"刷新脚本"。刷新会重新扫描两个 keymap 目录下的*.json（不含子目录与符号链接），两个目录都没有时控制台会输出keymap directory not find。

最省事的做法：直接复制keymap/test.json一份改个文件名（比如mygame.json），以它为骨架开始改。

第 2 步：用一次点击"抄"到你要的坐标

映射里所有坐标都是相对坐标：把屏幕宽和高都归一化为 1，(0.5, 0.5)就是屏幕正中心。好处是同一份脚本在不同分辨率的手机上都能用，坏处是你得知道每个按钮在屏幕的哪个相对位置。

不用拿尺子量。QtScrcpy 内置了调试开关：鼠标左键单击投屏画面，控制台会直接打印该位置对应的相对坐标，形如"pos": {"x": 0.86, "y": 0.72}，复制即可（实现在 videoform.cpp）。

辅助手段：在安卓开发者选项中打开"显示指针位置"和"触摸坐标显示"，手机屏幕上会直接标出触摸点的像素坐标，除以屏幕分辨率就是相对坐标。

第 3 步：写一份最小映射，先跑通链路

以 test.json 为底，写一份最简脚本：按F键点击屏幕中心，按J键从下往上拖拽一截（模拟滑动）。

{ "switchKey": "Key_QuoteLeft", "keyMapNodes": [ { "comment": "测试点击", "type": "KMT_CLICK", "key": "Key_F", "pos": { "x": 0.5, "y": 0.5 }, "switchMap": false }, { "comment": "测试拖拽", "type": "KMT_DRAG", "key": "Key_J", "startPos": { "x": 0.5, "y": 0.7 }, "endPos": { "x": 0.5, "y": 0.3 } } ] }

顶层就三个可选项：

按键码一律用Qt 按键枚举：Key_A、Key_Space、Key_Tab、Key_F1，鼠标是LeftButton/RightButton，方向键是Key_Up等。完整清单可在 Qt 官方文档的 "The key names used by Qt" 一节查到，identityv.json 首行也贴心地留了这个提示注释。

第 4 步：应用脚本并验证

1. 把 JSON 文件放进 keymap 目录。
2. 主界面点"刷新脚本"，下拉框里应能看到mygame.json。
3. 选中它，点"应用脚本"。内部流程是Dialog::on_applyScriptBtn_clicked()读取文件内容后通过device->updateScript(...)下发到当前选中设备（见 dialog.cpp）。
4. 启动投屏会话，按下`进入自定义映射模式，按F、J验证。

⚠️ 注意区分两种"应用"：应用脚本是把文件内容推给设备；但映射只在switchKey 切换后的自定义模式下生效。如果按下按键没反应，先检查自己是否按了切换键。

第 5 步：按场景选对映射类型

keyMapNodes里每个节点必须带type，共五种。按你的使用场景对号入座：

各类型的专有字段：

KMT_CLICK：key按键码、pos触摸位置、switchMap是否在点击后释放鼠标（见后文避坑）。

KMT_CLICK_TWICE：key、pos，无其他字段。

KMT_CLICK_MULTI：外层是key，内嵌clickNodes数组，每项含delay（延迟多少毫秒后再模拟这次触摸）和pos。test.json 的示例：按一次空格，先等 500ms 点(0.5,0.5)，再等 500ms 点(0.8,0.8)。

KMT_DRAG：key、startPos、endPos、dragSpeed（拖动速度，0~1，默认 1.0，越大越快）、startDelay（可选，开始拖动前额外等待的毫秒数）。tiktok.json 里方向键上下左右四个KMT_DRAG节点就是"滑屏刷视频"的实现。

KMT_STEER_WHEEL：centerPos方向盘中心点，leftKey/rightKey/upKey/downKey四个方向键，以及leftOffset/rightOffset/upOffset/downOffset四个偏移量——按下某方向键后，手指会从中心点拖到偏该方向对应 offset 处。gameforpeace.json 中 WASD 以(0.16,0.75)为中心，上下偏移 0.27/0.2，恰好覆盖游戏屏幕左下角的原生虚拟摇杆。

每个节点都建议加一个comment字段，后续维护和换设备时一眼能认出点位用途。

进阶：鼠标转视角与"释放鼠标"

鼠标移动映射（mouseMoveMap）是 FPS 体验的关键：把鼠标移动映射为"从startPos出发、沿鼠标移动方向的手指拖动"，开启后鼠标被隐藏、移动范围受限。以 gameforpeace.json 为模板：

"mouseMoveMap": { "startPos": { "x": 0.57, "y": 0.26 }, "speedRatioX": 3.25, "speedRatioY": 1.25, "smallEyes": { "type": "KMT_CLICK", "key": "Key_Alt", "pos": { "x": 0.8, "y": 0.31 }, "switchMap": false }, "speedRatio": 10 }

• speedRatioX/speedRatioY：X/Y 轴灵敏度，都至少要 0.001；数值越大越不灵敏。横竖屏比例不同，通常两个轴要设不同值。
• speedRatio：单一比例参数，必须大于 0.00225，Y 轴按 2.25 比率平移；若 X/Y 单独设置，这个参数就不必纠结。
• smallEyes：一个内嵌的KMT_CLICK节点（此处是 Alt 键）。按住它后，鼠标拖动改从smallEyes.pos（准星小眼睛按钮）出发，也就是"开镜观察"手感。

switchMap 的作用：部分点位点下去后需要继续用鼠标在弹出的界面里操作，比如打开地图后点选落点、背包里点装备。把这类节点的switchMap设为true，点击的同时会释放鼠标控制。和平精英映射里地图（M）、背包（Tab）、投掷物/药物菜单（F1/F2）都这么处理；普通点击点位保持false。

常见问题与避坑清单

• ⚠️脚本放错目录：不在 keymap 目录（或QTSCRCPY_KEYMAP_PATH指向的目录）里的文件永远刷不出来。
• ⚠️没按切换键：忘了按switchKey（默认`键）时，所有按键仍走普通映射，看起来像"映射完全无效"。
• ⚠️灵敏度下限：speedRatio必须大于 0.00225，speedRatioX/Y至少 0.001，dragSpeed只在 0~1 之间取值，越界行为不符合预期。
• 坐标拿不准：多用"左键点一下看控制台"的方式抄坐标，别估算；拿不准就用开发者选项的指针位置对照。
• 菜单类点位没释放鼠标：点了地图/背包后鼠标还"粘"在虚拟手指上，点不了落点——把switchMap改成true。
• 想换绑切换键：switchKey也可以是鼠标键，identityv.json 就用RightButton当切换键。
• 不想手写 JSON：可以用可视化映射工具（QuickAssistant、ScrcpyKeyMapper 等第三方工具）拖拽布点、实时测试并导出 JSON，导出结果同样是 keymap 目录下的 JSON 文件。下面是可视化工具配置游戏映射的典型界面：

收尾

把test.json复制一份，抄几个坐标改成你的游戏点位，刷新、应用、按`切换——一套键鼠映射就上线了；之后照着 和平精英完整映射 补齐方向盘和视角映射即可。更多字段细节可查阅仓库内的 官方键位映射说明，跨设备换分辨率也不用重新调点。

【免费下载链接】QtScrcpyAndroid real-time display control software项目地址: https://gitcode.com/GitHub_Trending/qt/QtScrcpy