202 lines
6.3 KiB
Markdown
202 lines
6.3 KiB
Markdown
# Vita Gamepad
|
||
|
||
把一台已安装 HENkaku/enso 的 PlayStation Vita 通过局域网变成 Windows 或
|
||
macOS 游戏手柄。
|
||
|
||
## 功能
|
||
|
||
- 同一 Wi-Fi 下自动发现电脑，无需在 Vita 上输入 IP
|
||
- 约 120 Hz 的 UDP 输入传输
|
||
- 双摇杆、方向键、四个动作键、L1/R1、Start/Select
|
||
- 后触摸板左右半区模拟 L2/R2
|
||
- 前触摸板底部左右角模拟 L3/R3
|
||
- 断线 300 ms 后自动释放全部按键，避免卡键
|
||
- Windows 输出标准 Xbox 360/XInput 虚拟手柄
|
||
- macOS 提供实验性通用 HID 后端；新版系统可能受 entitlement 限制
|
||
|
||
## 按键映射
|
||
|
||
| PS Vita | Xbox 游戏内名称 | PlayStation 名称 |
|
||
|---|---|---|
|
||
| × | A | Cross |
|
||
| ○ | B | Circle |
|
||
| □ | X | Square |
|
||
| △ | Y | Triangle |
|
||
| L / R | LB / RB | L1 / R1 |
|
||
| 后触摸板左 / 右 | LT / RT | L2 / R2 |
|
||
| Select / Start | Back / Start | Share / Options |
|
||
| 前触摸板左下 / 右下 | LS / RS | L3 / R3 |
|
||
|
||
## 电脑端
|
||
|
||
需要 Python 3.10 或更高版本。建议先创建虚拟环境。
|
||
|
||
### Windows
|
||
|
||
支持 Windows 10/11，电脑端会创建标准 Xbox 360/XInput 虚拟手柄。
|
||
|
||
#### 1. 安装虚拟手柄驱动
|
||
|
||
从 [ViGEmBus 官方 Releases](https://github.com/nefarius/ViGEmBus/releases)
|
||
下载并安装 `ViGEmBus Setup 1.22.0`。该项目已经归档，因此只建议从官方仓库
|
||
下载签名驱动，不要使用第三方重新打包版本。安装完成后建议重启一次 Windows。
|
||
|
||
#### 2. 安装 Vita Gamepad 电脑端
|
||
|
||
打开 PowerShell，进入本项目目录后运行：
|
||
|
||
```powershell
|
||
py -3 -m venv .venv
|
||
Set-ExecutionPolicy -Scope Process Bypass
|
||
.\.venv\Scripts\Activate.ps1
|
||
python -m pip install --upgrade pip
|
||
pip install -e ".[windows]"
|
||
vitapad-gui
|
||
```
|
||
|
||
程序会自动打开 `http://127.0.0.1:8765/` 控制面板。首次运行出现 Windows
|
||
防火墙提示时，只需允许“专用网络”访问，不建议开放公用网络。
|
||
|
||
#### 3. 连接与测试
|
||
|
||
1. 确保 Windows 电脑和 PSVita 连接同一个 Wi-Fi。
|
||
2. 在控制面板点击“开启使用”。
|
||
3. 打开 Vita Gamepad，等待页面显示 Vita IP。
|
||
4. 按 Vita 按键，页面中的对应按键会实时亮起；双摇杆和 L2/R2 也会跟随。
|
||
5. 按 `Win + R`，输入 `joy.cpl`，应能看到 `Controller (XBOX 360 For Windows)`。
|
||
6. 在该设备的“属性”页面可进一步检查 Windows 收到的按键和摇杆输入。
|
||
|
||
点击控制面板的“暂停”会立即释放按键、停止网络接收并移除虚拟手柄。
|
||
|
||
#### Windows 命令行模式
|
||
|
||
不需要控制面板时可运行：
|
||
|
||
```powershell
|
||
vitapad
|
||
```
|
||
|
||
只测试 Vita 网络和按键，不创建 Xbox 虚拟手柄：
|
||
|
||
```powershell
|
||
vitapad --backend debug
|
||
```
|
||
|
||
#### 打包 Windows EXE
|
||
|
||
已提供自动打包脚本。在 PowerShell 中运行：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File scripts\build_windows.ps1
|
||
```
|
||
|
||
生成文件位于 `dist\windows\VitaGamepadDashboard.exe`。目标电脑仍需先安装
|
||
ViGEmBus 驱动。
|
||
|
||
#### Windows 常见问题
|
||
|
||
- 提示“无法创建虚拟手柄”：确认已安装 ViGEmBus，并在设备管理器的“系统设备”
|
||
中检查 `Nefarius Virtual Gamepad Emulation Bus`，然后重启电脑。
|
||
- 控制页面没有自动打开：手动访问 `http://127.0.0.1:8765/`。
|
||
- 一直等待 Vita：确认网络类型为“专用网络”，允许 Python 或
|
||
`VitaGamepadDashboard.exe` 通过防火墙，并检查路由器没有开启 AP/客户端隔离。
|
||
- PowerShell 禁止运行激活脚本：重新执行
|
||
`Set-ExecutionPolicy -Scope Process Bypass`，它只影响当前窗口。
|
||
- `5000` 端口被占用：关闭其他 Vita Gamepad 实例或占用该端口的程序；当前
|
||
Vita 端固定使用 UDP 5000。
|
||
|
||
### macOS
|
||
|
||
> [!WARNING]
|
||
> macOS 没有正式、稳定的系统级虚拟游戏手柄 API。当前实验性
|
||
> `IOHIDUserDevice` 后端在旧版系统上可尝试通过管理员权限运行，但在
|
||
> macOS 26 等新版系统上可能仍被 entitlement/签名策略拒绝。控制面板和实时
|
||
> 按键测试可以使用 `--backend debug`，但该模式不会向游戏创建虚拟手柄。
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -e .
|
||
sudo .venv/bin/vitapad
|
||
```
|
||
|
||
macOS 后端通过 `IOHIDUserDevice` 尝试创建通用 HID 手柄，需要管理员权限，
|
||
且不保证能被当前系统或游戏接受。
|
||
|
||
使用预编译的 Apple Silicon 接收端时，解压后运行：
|
||
|
||
```bash
|
||
sudo ./VitaGamepadReceiver
|
||
```
|
||
|
||
如果 macOS 阻止首次打开，可在“系统设置 → 隐私与安全性”中允许，或执行：
|
||
|
||
```bash
|
||
xattr -dr com.apple.quarantine VitaGamepadReceiver
|
||
```
|
||
|
||
### 图形控制面板
|
||
|
||
预编译的 `VitaGamepadDashboard` 启动后会自动打开本机控制页面，页面只监听
|
||
`127.0.0.1`。可以在其中：
|
||
|
||
- 点击“开启使用”创建虚拟手柄并开始自动发现 Vita
|
||
- 点击“暂停”立即释放全部按键并停止接收
|
||
- 查看运行状态、Vita IP、运行时间和端口
|
||
- 在手柄预览中实时检查按键高亮、双摇杆位置和 L2/R2 压力
|
||
- 查看连接、断线、重连和错误日志
|
||
|
||
macOS 需要通过终端以管理员权限启动：
|
||
|
||
```bash
|
||
sudo ./VitaGamepadDashboard
|
||
```
|
||
|
||
关闭浏览器页面不会结束接收程序；需要结束程序时在终端按 `Control-C`。
|
||
|
||
### 仅测试网络，不创建手柄
|
||
|
||
```bash
|
||
vitapad --backend debug
|
||
```
|
||
|
||
收到数据后会在终端显示按键和摇杆状态，适合排查防火墙或 Wi-Fi 隔离问题。
|
||
|
||
可选参数：
|
||
|
||
```text
|
||
--port 5000 输入端口
|
||
--discovery-port 5001 自动发现端口
|
||
--bind 0.0.0.0 监听地址
|
||
--allow 192.168.1.25 只接受指定 Vita IP
|
||
--timeout-ms 300 断线释放时间
|
||
```
|
||
|
||
## PSVita 端构建与安装
|
||
|
||
需要安装 [VitaSDK](https://vitasdk.org/) 和 `vita2dlib`：
|
||
|
||
```bash
|
||
cd vita
|
||
python3 assets/generate_assets.py # 仅在需要重新生成 LiveArea 图片时运行
|
||
cmake -S . -B build
|
||
cmake --build build
|
||
```
|
||
|
||
将 `build/vita-gamepad.vpk` 传到 Vita 并用 VitaShell 安装。启动电脑端
|
||
`vitapad` 后再打开 Vita Gamepad；两台设备必须在同一局域网，且路由器不能启用
|
||
客户端/AP 隔离。
|
||
|
||
Vita 界面显示电脑 IP 和已发送包数。按住 `Start + Select` 两秒可退出。
|
||
|
||
## 网络协议
|
||
|
||
协议说明见 [docs/protocol.md](docs/protocol.md)。它只有固定 20 字节，不执行
|
||
远程命令，也不接收来自电脑的代码。自动发现只发送一个固定文本信标。
|
||
|
||
## 开发测试
|
||
|
||
```bash
|
||
python -m unittest discover -s tests -v
|
||
```
|