feat: implement M4 controller input foundation
This commit is contained in:
+18
-4
@@ -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
@@ -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
|
||||
|
||||
|
||||
@@ -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/范围 | 重复上报 | 备注 |
|
||||
|
||||
@@ -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
@@ -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 |
|
||||
|
||||
@@ -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
@@ -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 已编译并静态链接 |
|
||||
|
||||
Reference in New Issue
Block a user