SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场console-controller

console-controller

智能体与模型

查看项目

更新于 10-23 10:58

技能介绍

用途

console-controller 用于 PS2Recomp 重编译项目中的手柄输入映射。重编译后的游戏通过 ps2xRuntime/src/lib/ps2_pad.cpp 中的 PSPadBackend::readState 每秒多次读取手柄状态，原版文件把 raylib 的手柄 0 和一套固定键盘布局映射到 32 字节的 DualShock 2 报文。该技能用根据 console/controls.json 生成的同名文件替换它，使任何 raylib 能识别的手柄都表现为 DualShock 2，并可按用户偏好重新映射。运行时其它部分不变，因此重建是增量式的。

主要能力

  • 以预设布局快速起步：init --layout 支持 playstation、xbox、switch、switch-labels、keyboard。raylib 按位置报告手柄，底面按键在所有手柄上都对应 Cross（Xbox A、Nintendo B）；switch-labels 则匹配任天堂印字字母（右侧的 A 对应 Cross）。
  • 在 controls.json 中应用自定义：buttons 覆盖、键盘按键、deadzone（径向，默认 0.15）、invert_y（true 表示右摇杆，多数游戏中的镜头）、stick_swap、trigger_threshold（从模拟扳机轴读取 L2/R2）、players: 2（端口 2 使用第二只手柄），以及 Android 触摸区域。
  • 校验：padmap.py check 检查每个 DS2 按键是否已绑定、有无冲突；ERROR 需全部修复，警告会提示 Escape 退出游戏（raylib 默认退出键，运行时不改变）以及桌面调试构建中 F1 打开调试面板。
  • 生成与安装：gen 写出 console/ps2_pad.cpp（可加 --replay 配合脚本化运行）；install --repo <PS2Recomp 检出目录> 会先把原文件备份到 console/backups/ps2_pad.cpp.orig，再复制新文件；restore 可还原原版文件。
  • 辅助输出：presets 列出以上预设；table 输出 DS2 位表；check --script console/inputs/menu.txt 校验回放脚本。
  • 回放脚本：设置 PS2X_INPUT_RECORD=console/inputs/run1.txt 录制一段操作，退出后用 PS2X_INPUT_SCRIPT 回放；帧号按游戏读取手柄端口 0 的次数计数，脚本与游戏进度同步而非挂钟时间。

使用方式

  1. 确认使用者的手柄型号、连接方式（USB 或蓝牙）、操作系统、单人还是双人，以及是否需要键盘或触摸。若某按键错位，询问按了哪个物理键、游戏做了什么。
  2. 用 init --layout 按预设生成 console/controls.json。
  3. 在 controls.json 中应用用户改动，保持其为映射配置，不写入游戏代码。
  4. 运行 padmap.py check 修复错误并阅读警告。
  5. 运行 padmap.py gen 生成文件（需要脚本化测试时加 --replay）。
  6. 运行 padmap.py install --repo <检出目录>，随后执行常规增量构建（cmake --build <build 目录>）；只有一个 .cpp 变化，无需清理构建。
  7. 手持手柄测试：在响应所有按键的菜单或游戏的控制器测试界面逐个按键；若错误，修改 controls.json 后重新 gen、install、构建，并把结果记录到 console/STATE.md。

命令行选项包括 --config FILE（默认 console/controls.json，缺失时仅用预设）、--layout NAME、--out FILE（- 表示标准输出）、--json、--strict（警告也会导致 check 失败）、--backups DIR（默认 console/backups）。退出码：0 正常、1 check 发现问题、2 输入有误。

写入的文件

  • console/controls.json：映射配置（布局加覆盖项），完整格式见 reference/controls-json.md。
  • console/ps2_pad.cpp：由 gen 生成的替换用文件。
  • <PS2Recomp>/ps2xRuntime/src/lib/ps2_pad.cpp：仅在传入 --repo 时由 install 替换。
  • console/backups/ps2_pad.cpp.orig：原版文件，只保存一次且不被覆盖；后续安装还会保留带时间戳的副本。
  • templates/menu-walk.txt：示例输入回放脚本，可复制修改。

已知限制

  • 震动：运行时未接入，Kernel/Stubs/Pad.cpp 中的 scePadSetActDirect 与 scePadSetActAlign 返回 1 且不做任何事（scePadInfoAct 报告两个马达）。添加震动属于运行时 C++ 工作，不属于映射范畴。
  • 压力感应按键：按数字处理，游戏开启压力模式后，按下的按键报告 0xFF，否则为 0。
  • 模拟模式：由游戏通过 scePadSetMainMode 切换；摇杆值始终发送，数字模式下游戏会忽略。
  • Android 触摸：ps2_android_runtime.cpp 中仅有屏幕覆盖层的 TODO，原版移植无触摸控制；触摸区域作为不可见区域生效，更好的方案是蓝牙手柄。
  • 双人：原版文件把同一只手柄送入两个端口；生成文件在 players: 2 时给端口 2 分配独立手柄。

适用场景与边界

适用于为 PS2Recomp 重编译游戏配置手柄、键盘或触摸输入，并进行按键校验与脚本化回放测试。使用时须自备合法拥有的游戏（从自己的光盘导出），不得下载或协助寻找 ISO、ELF 或 BIOS 文件；PS2Recomp 无需 BIOS。游戏光盘、ELF、IRX 模块、素材和重编译的 runner/*.cpp 均保留在本地，不对外发布；controls.json、生成的 ps2_pad.cpp 和自写的回放脚本可分享。install 会拒绝非本技能生成的文件来源，从不覆盖 .orig 备份，只操作指定的检出目录；不要编辑头文件（包括 ps2_pad.h：头文件变化会触发所有生成文件重建），不要清理构建。与 Sony 无关联，PlayStation 和 DualShock 是 Sony Interactive Entertainment 的商标，DualSense、Xbox 和 Nintendo Switch 归各自所有者。后续可交由 console-tester 用回放脚本运行移植版本，console-anywhere 为手柄目标设备（Steam Deck、Android、Vita）构建，console-backend 在游戏需要震动或运行时未实现的 pad 调用时处理。