pvg

Pedal Visualization of Gamepad.

游戏控制器踏板可视化。

介绍

本项目源于作者直播赛车游戏时编写，采用原生 JavaScript，利用 navigator.getGamepads() 读取手柄等控制器的状态，输出状态到 OBS 等串流软件，方便观众了解主播操作。

通过丰富的参数选项，理论上支持一切控制器和任意控制布局，目前作者仅测试了 Xbox 手柄，更多用法敬请自行挖掘。

由于技术路线所限，不支持读取键盘和鼠标操作，同时目前不支持非串流软件场景使用。

下文中的删除线标记代表将在未来支持。

使用

使用演示网址或将本项目克隆到本地。

关于如何在 OBS 中使用可参见这篇文章。

参数说明

参数名

所有参数均为可选参数，可根据自己需求更改。

显示相关参数

参数名	说明	可选参数值	默认参数值	备注
style	风格	low矮版， high高版	low
opacity	不透明度	0.0 ~ 1.0	1.0	如果使用 OBS 等串流软件，不建议在此处设置
fps	刷新帧率	1 ~ 1000	60	不建议高于 120，否则会导致高CPU占用
display_steering	显示方向盘	0 不显示，1 显示	1
max_angle	方向盘最大角度	0.0 ~ 540.0	90.0	不建议超过 180.0
display_clutch	显示离合器	0 不显示，1 显示	0
display_accelerator	显示油门	0 不显示，1 显示	1
display_break	显示刹车	0 不显示，1 显示	1
display_shifter	档位布局	0 不显示，其他见下表	0	仅当 style=high 时有效
indicator	显示指示灯	0 不显示，1 显示	1	当 style=low 时最多3个，当 style=high 时最多4个
display_paking	显示手刹	0 不显示，1 按下，2 点击切换	1
display_shift	显示加减档	0 不显示，1 按下	1	包含加档和减档两个
display_diff_lock	显示差速器锁（欧卡2&美卡专用）	0 不显示，1 按下，2 点击切换	0
display_track_lift_axle	显示卡车提升桥（欧卡2&美卡专用）	0 不显示，1 按下，2 点击切换	0
display_trailer_lift_axle	显示卡车提升桥（欧卡2&美卡专用）	0 不显示，1 按下，2 点击切换	0
display_hinge	显示换挡和铰链（旋转轮胎系列专用）	0 不显示，1 按下	0	包含换挡和铰链两个
display_couter	显示计数	0 不显示，1 显示	0

在代码逻辑中，非 0 即视为 1。

档位布局 display_shifter

参数值	说明	00	01	10	11
5	五速	1 3 5 ╠══╬══╣ 2 4 R
6	六速	1 3 5 ╠══╬══╬══╗ 2 4 6 R
7	七速	1 3 5 7 ╠══╬══╬══╣ 2 4 6 R
12+2	十二速+二倒挡	1 5 9 ╠══╬══╬══╗ 3 7 11 R1	2 6 10 ╠══╬══╬══╗ 4 8 12 R2
12+4	十二速+四倒挡	1 5 9 R3 ╠══╬══╬══╣ 3 7 11 R1	2 6 10 R4 ╠══╬══╬══╣ 4 8 12 R2

此为显示的档位布局，和实际控制器种类和设置无关。

控制器相关参数

参数名	说明	接收变量	默认按键	默认参数值	备注
steering	方向盘轴	轴变量	LS左摇杆横轴	a0	左负右正
clutch	离合轴	值变量	LB左肩键	v4
accelerator	油门轴	值变量	RT右扳机	v7
break	刹车轴	值变量	LT左扳机	v6
paking	手刹	压变量	RB右肩键	p5
shifter_toggle	档位开关行为	区分于 display_shifter，见下表		0	不适用序列式
shift_up	加档	压变量	B键	p1
shift_down	减档	压变量	A键	p0
diff_lock	差速器	压变量	A键 + B键	p0+p1
track_lift_axle	卡车提升桥	压变量	X键 + Y键	p2+p3
trailer_lift_axle	挂车提升桥	压变量	B键 + X键	p1+p2
hinge	铰链	压变量	A键	p3
shifter	换挡	压变量	LB左肩键	p4

档位开关行为 shifter_toggle

参数值	说明
0	无档位开关

变量

规定压变量、轴变量和值变量，其中：

• 压变量的取值范围为 true 或 false。按钮按下（button.pressed）返回该范围。
• 轴变量的取值范围为 -1.0 至 1.0。轴（axes）返回该范围。
• 值变量的取值范围为 0.0 至 1.0。按钮值（button.value）返回该范围。

参数值的格式为 控制器号 + a/p/v + 索引 + 附加选项(可选)。其中：

• 控制器号代表第几个接入的控制器。如果你只有一个控制器，可写 1 或省略。如果你有多个控制器，则需要填写每个控制器的编号，从 1 开始。
• a/p/v 代表轴（axes）、按钮按下（button.pressed）或按钮值（button.value）
• 索引代表该变量在接口中的索引。
• 附加选项可选，具体见表。

特别地，压变量可以使用 + 连接，意为逻辑与。

若未提供附加选项，则会使用加粗项进行转换。

对于压变量的可选附加选项

选项	说明	运算式	新变量
	无	x	压变量
r	反向	!x	压变量
a	转轴变量	x ? 1.0 : -1.0	轴变量
ar	转轴变量反向	x ? -1.0 : 1.0	轴变量
v	转值变量	x ? 1.0 : 0.0	值变量
vr	转值变量反向	x ? 0.0 : 1.0	值变量

对于轴变量的可选附加选项

选项	说明	运算式	新变量
	无	x	轴变量
r	反向	-x	轴变量
v	规范化	x / 2 + 0.5	值变量
vr	规范化反向	-x / 2 + 0.5	值变量
vp	取正半轴	x > 0.0 ? x : 0.0	值变量
vpr	取正半轴反向	x > 0.0 ? 1.0 - x : 1.0	值变量
vm	取负半轴	x < 0.0 ? -x : 0.0	值变量
vmr	取负半轴反向	x < 0.0 ? x + 1.0 : 1.0	值变量
p	转压变量	x >= 0.0	压变量
pr	转压变量取非	x < 0.0	压变量
p0.0	转压变量，0.0为任意浮点数	x >= 0.0	压变量
pr0.0	转压变量取非，0.0为任意浮点数	x < 0.0	压变量

对于值变量的可选附加选项

选项	说明	运算式	新变量
	无	x	值变量
r	反向	1-x	值变量
	无	x	轴变量
a	规范化	x * 2 - 1.0	轴变量
ar	规范化反向	-x * 2 + 1.0	轴变量
p	转压变量	x >= 0.5	压变量
pr	转压变量取非	x < 0.5	压变量
p0.5	转压变量，0.5为任意浮点数	x >= 0.5	压变量
pr0.5	转压变量取非，0.5为任意浮点数	x < 0.5	压变量

一般来说，v[n]p 等价于 p[n]，v[n] 等价于 p[n]v，其中 [n] 为索引。

TODO

• 完善档位显示功能
• 替换所有图片为SVG位图
• 多语言支持
• 测试方向盘、踏板、排挡等硬件
• 简明网页辅助配置参数
• 非线性支持
• 自定义规范化区间
• 对于触觉硬件的支持

附录

xbox布局手柄的 navigator.getGamepads() 返回值

变量	轴/按键	备注
axes[0]	LS左摇杆横轴	左负右正
axes[1]	LS左摇杆纵轴	上负下正
axes[2]	RS右摇杆横轴	左负右正
axes[3]	RS右摇杆横轴	上负下正
button[0]	A键
button[1]	B键
button[2]	X键
button[3]	Y键
button[4]	LB左肩键
button[5]	RB右肩键
button[6]	LT左扳机键	线性
button[7]	RT右扳机键	线性
button[8]	select/back键
button[9]	start/forward键
button[10]	LS左摇杆按下
button[11]	RS右摇杆按下
button[12]	⇧上方向键
button[13]	⇩下方向键
button[14]	⇦左方向键
button[15]	⇨右方向键
button[16]	home键

致谢

感谢@EchoGitH 为演示页前端设计做出的贡献。