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 下载并安装 ViGEmBus Setup 1.22.0。该项目已经归档，因此只建议从官方仓库 下载签名驱动，不要使用第三方重新打包版本。安装完成后建议重启一次 Windows。

2. 安装 Vita Gamepad 电脑端

打开 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 命令行模式

不需要控制面板时可运行：

vitapad

只测试 Vita 网络和按键，不创建 Xbox 虚拟手柄：

vitapad --backend debug

打包 Windows EXE

已提供自动打包脚本。在 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，但该模式不会向游戏创建虚拟手柄。

python3 -m venv .venv
source .venv/bin/activate
pip install -e .
sudo .venv/bin/vitapad

macOS 后端通过 IOHIDUserDevice 尝试创建通用 HID 手柄，需要管理员权限， 且不保证能被当前系统或游戏接受。

使用预编译的 Apple Silicon 接收端时，解压后运行：

sudo ./VitaGamepadReceiver

如果 macOS 阻止首次打开，可在“系统设置 → 隐私与安全性”中允许，或执行：

xattr -dr com.apple.quarantine VitaGamepadReceiver

图形控制面板

预编译的 VitaGamepadDashboard 启动后会自动打开本机控制页面，页面只监听 127.0.0.1。可以在其中：

• 点击“开启使用”创建虚拟手柄并开始自动发现 Vita
• 点击“暂停”立即释放全部按键并停止接收
• 查看运行状态、Vita IP、运行时间和端口
• 在手柄预览中实时检查按键高亮、双摇杆位置和 L2/R2 压力
• 查看连接、断线、重连和错误日志

macOS 需要通过终端以管理员权限启动：

sudo ./VitaGamepadDashboard

关闭浏览器页面不会结束接收程序；需要结束程序时在终端按 Control-C。

仅测试网络，不创建手柄

vitapad --backend debug

收到数据后会在终端显示按键和摇杆状态，适合排查防火墙或 Wi-Fi 隔离问题。

可选参数：

--port 5000             输入端口
--discovery-port 5001   自动发现端口
--bind 0.0.0.0          监听地址
--allow 192.168.1.25    只接受指定 Vita IP
--timeout-ms 300        断线释放时间

PSVita 端构建与安装

需要安装 VitaSDK 和 vita2dlib：

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。它只有固定 20 字节，不执行 远程命令，也不接收来自电脑的代码。自动发现只发送一个固定文本信标。

开发测试

python -m unittest discover -s tests -v