feat: implement M4 controller input foundation

This commit is contained in:
2026-09-12 13:40:19 +08:00
parent 2e8b8812a6
commit e91de54bad
26 changed files with 1172 additions and 78 deletions
+18 -4
View File
@@ -1,4 +1,4 @@
# NESLite 架构(M3 基线)
# NESLite 架构(M4 基线)
## 边界与线程
@@ -64,9 +64,23 @@ Android 音频焦点丢失会暂停并清输入,重新获得焦点不会自行
GL 线程只在原生侧读取最新缓冲和上传纹理,不经 JNI 逐帧复制图像。默认 4:3、最近邻显示,可切换
原始像素整数缩放;渲染掉帧不减少内核 `retro_run` 次数。
手柄状态在 Android 事件侧合成为 libretro joypad 位掩码,内核每帧按状态采样。后台、失焦和断柄
会清零并请求暂停。M1 的 X5 Lite 实测键码仍须在 G1 回填,因此当前只包含 Android 标准按键及
HAT/主方向轴映射。
M4 输入层按物理来源维护状态,来源键包含本次设备 ID、按键/轴/触屏类别、代码和轴方向。多个来源
映射到同一动作时只合成一次;释放一个来源不会清除仍按住的另一个来源。相反方向同时成立时对应轴
归零。轴使用可配置的按下/释放双阈值,跨向时先释放旧方向再按下新方向,避免边界抖动和瞬时冲突。
标准 Android 手柄使用通用映射:方向键/X-Y 轴控制方向,A/B 对应 NES A/B,X/Y 对应 A/B 软件
连发,Start/Select 保持原义,右摇杆按下切换暂停菜单,RB 按住 2× 快进。暂停和快进只按合成动作
边沿发命令,系统重复 KeyEvent 不会重复切换;Guide、Mode、肩键组合和快速读档均不占用。软件连发
在原生核心线程按模拟秒生成 15 Hz 门控,NTSC/PAL 不依赖墙钟频率,离开 Running 即清零。
自定义设置可逐动作捕获按键或轴方向,冲突必须确认替换,并支持取消、恢复默认、A/B 交换及死区
调整。DataStore 以 VID/PID 加 descriptor(不可用时回退规范化名称)的 SHA-256 指纹保存档案,不写入
临时 deviceId;设备重连后按稳定特征恢复。X5 Lite 专属映射注册只接受 M1 实测的完整签名和事件表,
在该证据缺失时保持空表并使用通用档案,防止按名称误套。
运行态输入送入 JNI 的基础掩码和独立连发掩码。暂停菜单、游戏列表及设置均使用可聚焦原生控件;
非运行态不消费方向导航,手柄 B 可从设置返回、从暂停菜单继续。失焦、暂停、断柄和退出同步清除
来源、轴滞回、基础掩码及连发掩码。
电池存档按 ROM 哈希隔离为 `files/saves/<sha256>/battery/battery.sav`。暂停和正常退出时在内核线程
取得保存内存并以临时文件替换提交,状态通知用 `paused_saved`/`stopped_saved` 报告成功。更完整的
+3 -3
View File
@@ -1,6 +1,6 @@
# NESLite 可复现构建说明
本说明对应 M0~M3 基线。命令使用系统默认 PowerShell 7.6.6(`pwsh`)从仓库根目录执行;不需要手工复制 `.so`、
本说明对应 M0~M4 基线。命令使用系统默认 PowerShell 7.6.6(`pwsh`)从仓库根目录执行;不需要手工复制 `.so`、
FCEUmm 或 Oboe 文件。
## 前置条件
@@ -11,13 +11,13 @@ FCEUmm 或 Oboe 文件。
3. 设置 `ANDROID_HOME`(或在未设置时使用本机记录的 SDK 根目录)。`local.properties` 仅保存
本机 `sdk.dir`,不提交。
4. 首次构建需要访问 Google Maven、Maven Central 与 Gradle 分发服务,以取得已锁定版本。
5. 若 M2/M3 需要上游源码,运行:
5. M2~M4 构建原生内核、音频和输入层前,运行:
```powershell
.\tools\fetch-third-party.ps1
```
该脚本根据 `third_party/manifest.json` 检出固定提交;M3 构建需要 FCEUmm、libretro headers 与 Oboe。
该脚本根据 `third_party/manifest.json` 检出固定提交;M4 构建需要 FCEUmm、libretro headers 与 Oboe。
## 构建调试 APK
+9 -3
View File
@@ -1,14 +1,17 @@
# X5 Lite 实测键位与模式
本文档只登记真实设备结果,不根据按钮字母或网络资料推断 Android 键码。当前尚未连接目标手机和
X5 Lite,因此表格保持“待实测”;完成下述流程并导出诊断 JSON 后回填。
本文档只登记真实设备结果,不根据按钮字母、外观或网络资料推断 Android 键码。2026-09-12 已收到
用户提供的手柄正面和肩部照片;照片确认这是直连 USB-C 的伸缩式布局,并可见十字键、双摇杆、
ABXY、视图/菜单键及左右肩键。当前尚未连接目标手机,照片不能给出 Android VID/PID、descriptor、
键码、轴号或上报模式,因此这些字段仍待诊断 JSON 回填。
## 固定测试条件
- 手柄模式:原生安卓模式,实际切换方法待随设备说明和实测确认。
- 硬件连发:测试前关闭;实际指示状态待实测记录。
- 厂商保留组合:待实测;不得占用“视图+菜单长按”。
- 应用版本:`0.1.3-debug`。
- 照片观察:USB-C 直连、伸缩夹持;可见十字键、双摇杆、ABXY、视图/菜单及肩键。
- 应用版本:M1 采集页基线 `0.1.3-debug`;M4 映射页 `0.4.4-debug`。
- 事件上限:最近 512 条;页面显示最近 30 条。
## 连贯验收步骤
@@ -35,6 +38,9 @@ X5 Lite,因此表格保持“待实测”;完成下述流程并导出诊断
| 厂商保留组合 | 待实测 |
| 诊断 JSON/SHA-256 | 待实测 |
外观照片只作为“物理控件存在”的证据,不作为设备身份或 Android 事件映射证据。M4 在未取得上述
身份字段时使用标准 Android 通用映射,并允许在应用内逐项捕获;X5 Lite 专属签名不会按名称猜测。
## 键位与轴
| 物理控件 | Android KeyEvent/MotionEvent | sources/范围 | 重复上报 | 备注 |
+1 -1
View File
@@ -13,7 +13,7 @@ Gradle 版本锁见 [gradle/libs.versions.toml](../gradle/libs.versions.toml)。
| JSON-java | 20240303 | Maven Central | Public Domain;仅用于 JVM 测试,不打入生产 APK | M1 使用 |
| AndroidX test/Espresso | 1.3.0/3.7.0 | Google Maven | Apache-2.0;测试依赖,不打入生产 APK | M0 使用 |
| Room | 2.7.2 | Google Maven | Apache-2.0;保留 notices | M2 使用 |
| DataStore | 1.1.7 | Google Maven | Apache-2.0;后续 APK notices | M4/M6 预锁定 |
| DataStore Preferences | 1.1.7 | Google Maven | Apache-2.0;保留 notices | M4 使用 |
| FCEUmm | `236ccdfc911e84c60fea6b9d0699c2d440a8de14` | `tools/fetch-third-party.ps1` | GPL-2.0-only;交付完整对应源码、COPYING、修改说明 | M2 使用 |
| libretro.h | `0c9622896333ee62dc4326bbe8784a210ddeb03c` | `tools/fetch-third-party.ps1` | MIT;保留版权及许可 | M2 使用 |
| Oboe | 1.10.0 / `a81bb9f87d4105b84b682685d3bfbb5beca371d1` | `tools/fetch-third-party.ps1` | Apache-2.0;保留 notices | M3 使用 |
+1 -1
View File
@@ -6,7 +6,7 @@
| --- | --- |
| 显示名称 | `NESLite` |
| 正式 application ID/namespace | `org.neslite.app` |
| 当前开发版本 | `0.3.4`,`versionCode = 3004` |
| 当前开发版本 | `0.4.4`,`versionCode = 4004` |
| 调试 application ID | `org.neslite.app.debug` |
| 发布 ABI | `arm64-v8a` |
| min/target SDK | 28/36 |
+42
View File
@@ -0,0 +1,42 @@
# M4 完整手柄操作记录
日期:2026-09-12
构建:`org.neslite.app.debug`,`0.4.4-debug`,versionCode 4004,arm64-v8a
## 已实现
- 标准 Android 通用映射覆盖方向、NES A/B、Start/Select、X/Y 软件连发、右摇杆暂停菜单和 RB
按住快进;Guide/Mode、厂商组合与快速读档不占用,支持 A/B 交换。
- 设备、按键、轴方向和测试触屏来源独立合成;重复来源去重,单来源释放不误清其他来源,相反方向
同时按下归零。
- 可配置按下/释放双死区阈值,跨向时先释放旧方向;设置页可捕获按键或轴、提示并确认冲突、保存、
取消及恢复默认,所有退出路径清输入状态。
- 软件连发由核心线程按模拟时间生成 15 Hz 门控,NTSC/PAL 采用同一时间口径;暂停、退出、失焦和
断柄清除连发。右摇杆暂停及 RB 快进按合成边沿触发,KeyEvent repeat 不重复命令。
- 游戏列表、暂停菜单和手柄设置使用 Android 可聚焦控件;运行时方向送游戏,暂停时方向留给焦点
导航,手柄 B 提供返回路径。
- DataStore 1.1.7 按 VID/PID 和 descriptor 的稳定指纹保存映射、A/B 状态和死区;临时 deviceId 只
出现在当前诊断,不进入持久化档案。
## X5 Lite 证据边界
用户提供的两张照片确认了 USB-C 伸缩夹持、十字键、双摇杆、ABXY、视图/菜单和肩键的物理布局,
详见 `docs/controller-x5lite.md`。照片不能证明 Android VID/PID、descriptor、键码、轴号、重复上报或
硬件连发状态;专属签名表因此保持为空,连接前使用标准 Android 通用映射,可在设置页逐项捕获。
## 本地验证
- 原生 smoke test 覆盖 NTSC 60 帧与 PAL 50 帧各一模拟秒均产生 15 次连发脉冲。
- JVM 测试覆盖通用与精确签名选择、A/B 交换、档案 JSON 往返、设备指纹、双来源按住/释放、
轴键去重、相反方向、死区边界和跨向顺序、暂停/快进边沿、断柄及触屏来源。
- `tools/check.ps1 -Scope Stage`:APK、Windows 原生 smoke test 和 JVM 测试全部通过;JVM 共 23 项,
失败 0、错误 0。Android lint:0 错误、30 个非阻断警告。
- 调试 APK:`app/build/outputs/apk/debug/app-debug.apk`,21,844,231 字节,SHA-256
`DC57D4F6818A0F637264DC8F96328CBEEA2B16302899FE6777EE70737E5DAC00`。包内原生库仅有目标 ABI
`arm64-v8a` 的 `libneslite_jni.so` 与 DataStore 的 `libdatastore_shared_counter.so`。
## 尚未形成门槛证据
当前没有已授权目标手机,也没有 M1 导出的 X5 Lite Android 身份/事件表及合法 ROM。真实专属默认
映射、绑定交互、全手柄启动与菜单路径、NTSC/PAL 实际连发、断柄取消快进和 H-HOT 20 轮插拔尚未
执行。G1~G3 未通过也阻止进入 G4;`todo.md` 中 M4 项与 G4 保持未勾选。
+1 -1
View File
@@ -30,7 +30,7 @@ NDK 与 CMake。该提示不改变产物使用的具体版本,后续升级 SDK
| AndroidX Core KTX | 1.17.0 | Google Maven | Apache-2.0 | M0 已引入 |
| AndroidX Activity KTX | 1.12.0 | Google Maven | Apache-2.0 | M0 已引入 |
| Room | 2.7.2 | Google Maven | Apache-2.0 | M2 已引入 |
| DataStore Preferences | 1.1.7 | Google Maven | Apache-2.0 | 为 M4/M6 锁定,尚未引入 |
| DataStore Preferences | 1.1.7 | Google Maven | Apache-2.0 | M4 已引入 |
| FCEUmm | `236ccdfc911e84c60fea6b9d0699c2d440a8de14` | `libretro/libretro-fceumm` | GPL-2.0-only | M2 已编译并静态链接 |
| libretro.h | `0c9622896333ee62dc4326bbe8784a210ddeb03c` | `libretro/RetroArch` | MIT | M2 已引入 |
| Oboe | tag `1.10.0`, commit `a81bb9f87d4105b84b682685d3bfbb5beca371d1` | `google/oboe` | Apache-2.0 | M3 已编译并静态链接 |