控制器输入¶
VTube Studio 在桌面版（Steam 版）中支持游戏控制器输入。你可以使用控制器驱动 Live2D 模型的 追踪参数（例如，让你的模型手持的 Live2D 控制器动起来），也可以用来 触发快捷键（例如，按下控制器按钮切换按键表情）。
⚠️ 重要提示： 如果你的控制器在 VTube Studio 中未显示或无法接收输入，请尝试 为 VTube Studio 关闭 Steam Input。
支持的控制器¶
VTube Studio 使用 Rewired 处理控制器输入，因此支持 广泛的控制器，包括：
- PlayStation – DualShock 4、DualSense（PS5）、DualSense Edge（PS5）
- Xbox – Xbox One、Xbox Series X/S 控制器
- Nintendo – Switch Pro 控制器
- 通用型 – 大多数兼容 DirectInput 和 XInput 的游戏手柄
扩展支持（触控板、方向/陀螺仪数据）目前仅适用于 DualShock 4、DualSense 和 DualSense Edge 控制器。
大多数控制器应能开箱即用，但部分控制器可能需要在 VTube Studio 中手动运行控制器设置。
控制器小部件¶
控制器小部件会实时 可视化 你的控制器状态。当你按下按钮、移动摇杆或扳动扳机时，屏幕上的控制器模型会同步动画。
通过控制器小部件，你还可以选择要使用的控制器，并查看所有受支持控制器参数及其当前值的详细列表。
选择控制器¶
使用控制器小部件顶部的 下拉菜单 选择要使用的控制器。选项包括：
| 选项 | 说明 |
|---|---|
| 无控制器 (No Controller) | 禁用控制器输入。 |
| 所有控制器 (All Controllers) | 合并所有已连接控制器的输入。 |
| 特定控制器 (Specific controller) | 仅使用该特定控制器的输入。 |
如果所选控制器 断开连接，小部件上将显示警告标识。重新连接后，系统会自动重新识别。
当选择 “所有控制器” 时，若存在多个 DualShock/DualSense 控制器，其扩展数据（如陀螺仪）将从第一个检测到的 DualShock/DualSense 控制器读取。
运行控制器设置¶
大多数控制器在 VTube Studio 中无需额外设置即可正常工作。但某些小众控制器可能无法开箱即用。
对于这类控制器，你可以运行控制器按键设置（“Button Config”），在 VTube Studio 中手动配置按键映射，从而让几乎所有控制器都能使用。
设置步骤如下：
-
确保下拉菜单中已选择 某个特定控制器。
-
点击 “Button Config”。
-
VTube Studio 将逐项引导你完成设置。屏幕上的控制器模型会高亮提示你需要按下的按钮或轴。
-
在物理控制器上 按下对应的按钮/轴，或点击 “Skip” 跳过该项。
-
所有输入映射完成后，设置即自动保存。
你可随时 取消 设置。若取消，将恢复之前的映射配置。
控制器映射保存在 VTube Studio 配置文件夹中的 vts_controller_settings.json 文件内。删除该文件即可重置所有手动设置。
提示： 如果新连接的控制器按键错乱，只需运行一次设置即可。你也可以点击 “Reset Setup” 清除自定义映射，恢复默认配置。
控制器快捷键¶
控制器按钮可作为 快捷键触发器，功能与键盘按键相同。你可以在快捷键设置中将控制器输入分配给任意快捷键，甚至与键盘按键组合使用。
设置快捷键时，控制器输入会与键盘按键一同出现在绑定列表中。所有按钮输入和方向摇杆输入均可作为快捷键触发器。
在 DualShock 4 和 DualSense 控制器上，触控板滑动手势也可触发快捷键：
| 快捷键输入 | 说明 |
|---|---|
| Swipe Left | 在触控板上向左滑动 |
| Swipe Right | 在触控板上向右滑动 |
| Swipe Up | 在触控板上向上滑动 |
| Swipe Down | 在触控板上向下滑动 |
滑动检测采用方向阈值判定。滑动必须明显为水平或垂直方向（不能为对角线）才能被识别。一旦某次手指触碰锁定了滑动方向，在手指抬起前该方向将保持激活。
控制器参数¶
当控制器处于激活状态时，VTube Studio 会提供一组 追踪参数，可映射到你的 Live2D 模型参数（类似面部追踪参数）。这些参数每帧都会根据控制器当前状态更新。
点击控制器小部件中的 “Show Parameter List” 按钮，即可实时查看所有参数值。这将打开一个浮动文本面板，实时显示每个参数及其当前数值。
摇杆（Sticks）¶
| 参数 | 范围 | 说明 |
|---|---|---|
ControllerStickLeftX |
-1 到 1 | 左摇杆水平（左 = -1，右 = 1） |
ControllerStickLeftY |
-1 到 1 | 左摇杆垂直（下 = -1，上 = 1） |
ControllerStickRightX |
-1 到 1 | 右摇杆水平 |
ControllerStickRightY |
-1 到 1 | 右摇杆垂直 |
ControllerStickPressLeft |
0 或 1 | 左摇杆按下（L3） |
ControllerStickPressRight |
0 或 1 | 右摇杆按下（R3） |
方向键（D-Pad）¶
| 参数 | 范围 | 说明 |
|---|---|---|
ControllerDPadX |
-1, 0, 或 1 | 方向键水平（左 = -1，右 = 1） |
ControllerDPadY |
-1, 0, 或 1 | 方向键垂直（下 = -1，上 = 1） |
面部按钮（Face Buttons）¶
| 参数 | 范围 | 说明 |
|---|---|---|
ControllerTriangle |
0 或 1 | Triangle / Y 按钮 |
ControllerCross |
0 或 1 | Cross / A 按钮 |
ControllerSquare |
0 或 1 | Square / X 按钮 |
ControllerCircle |
0 或 1 | Circle / B 按钮 |
肩键（Shoulder Buttons）¶
| 参数 | 范围 | 说明 |
|---|---|---|
ControllerShoulderLeft |
0 或 1 | 左肩键 / L1 / LB |
ControllerShoulderRight |
0 或 1 | 右肩键 / R1 / RB |
扳机键（Triggers）¶
| 参数 | 范围 | 说明 |
|---|---|---|
ControllerTriggerLeft |
0.0 到 1.0 | 左扳机（模拟量） |
ControllerTriggerRight |
0.0 到 1.0 | 右扳机（模拟量） |
功能按钮（Option Buttons）¶
| 参数 | 范围 | 说明 |
|---|---|---|
ControllerOptionLeft |
0 或 1 | Select / Share 按钮 |
ControllerOptionRight |
0 或 1 | Start / Options 按钮 |
ControllerHome |
0 或 1 | Home / PS 按钮 |
ControllerTouchPadPress |
0 或 1 | 触控板按下 |
特殊 / 聚合值（Special / Aggregated Values）¶
| 参数 | 范围 | 说明 |
|---|---|---|
ControllerButtonsAnyLeft |
0 或 1 | 任意左侧按钮按下时为 1 |
ControllerButtonsAnyRight |
0 或 1 | 任意右侧按钮按下时为 1 |
ControllerButtonCountLeft |
0+ | 当前按下的左侧按钮数量 |
ControllerButtonCountRight |
0+ | 当前按下的右侧按钮数量 |
ControllerLean |
-1 到 1 | 计算得出的“倾斜/轻推”值，基于哪一侧按钮被按下及摇杆位置 |
手指位置（估算）（Finger Position）¶
这些参数根据当前激活的按钮，估算用户拇指和食指的位置：
| 参数 | 值 | 说明 |
|---|---|---|
ControllerThumbPosLeft |
0–3 | 左拇指：0 = 按钮区，1 = 摇杆，2 = 功能键，3 = 触控板 |
ControllerThumbPosRight |
0–3 | 右拇指位置（映射相同） |
ControllerFingerPosLeft |
0–2 | 左食指：0 = 肩键，1 = 扳机，2 = 两者都按 |
ControllerFingerPosRight |
0–2 | 右食指位置（映射相同） |
DualShock 4 / DualSense 扩展参数¶
仅在连接 DualShock 4 或 DualSense 控制器时可用：
| 参数 | 范围 | 说明 |
|---|---|---|
ControllerTouchPadTouchCount |
0–2 | 当前触控板上的手指数量 |
ControllerTouchPadFingerLeftActive |
0 或 1 | 左侧/第一根手指是否在触控板上 |
ControllerTouchPadFingerRightActive |
0 或 1 | 右侧/第二根手指是否在触控板上 |
ControllerTouchPadFingerLeftX |
0.0 到 1.0 | 左手指在触控板上的 X 位置 |
ControllerTouchPadFingerLeftY |
0.0 到 1.0 | 左手指在触控板上的 Y 位置 |
ControllerTouchPadFingerRightX |
0.0 到 1.0 | 右手指在触控板上的 X 位置 |
ControllerTouchPadFingerRightY |
0.0 到 1.0 | 右手指在触控板上的 Y 位置 |
ControllerOrientationX |
-60.0 到 60.0 | 控制器方向 X（欧拉角，偏航） |
ControllerOrientationY |
-60.0 到 60.0 | 控制器方向 Y（欧拉角，俯仰） |
ControllerOrientationZ |
-60.0 到 60.0 | 控制器方向 Z（欧拉角，滚转） |
DualShock 4 / DualSense 扩展支持¶
当连接 DualShock 4（PS4）或 DualSense/DualSense Edge（PS5）控制器时，VTube Studio 可读取其他控制器不具备的额外数据。
触控板¶
DualShock 4 和 DualSense 控制器配备支持 最多两个同时触点 的触控板。VTube Studio 会追踪：
- 每根手指（左/右）当前是否接触触控板。
- 每根手指的 X 和 Y 位置（归一化到 0–1 范围）。
- 触控板上的手指总数。
- 滑动手势（左、右、上、下），可用于触发快捷键。
方向 / 陀螺仪¶
DualSense 和 DualShock 4 控制器内置陀螺仪。VTube Studio 会读取控制器的 方向，并以三个欧拉角参数（ControllerOrientationX、ControllerOrientationY、ControllerOrientationZ）输出。
你可以通过物理倾斜控制器来倾斜或移动你的模型。
重置方向¶
由于陀螺仪可能随时间漂移，你可能需要 重置方向，使控制器当前的物理姿态被视为“中立”。
有两种重置方式：
- 在控制器小部件中点击 “Reset Orientation” 按钮。
- 在控制器上 长按组合键：同时按住 L1 + R1 + L2 + R2 + Triangle 约 2 秒。控制器会短暂震动以确认重置。
重置后，控制器当前的姿态即成为新的“零”方向。
Steam 控制器输入¶
VTube Studio 通过 Steam 启动，而 Steam 自带 控制器输入系统（Steam Input），可在信号到达应用程序前拦截并重映射控制器输入。在某些情况下，这会干扰 VTube Studio 的控制器识别，或导致按键映射错误。
如果你遇到控制器输入问题，或控制器未在 VTube Studio 中显示，可尝试 为 VTube Studio 单独禁用 Steam 输入：
在 Steam 库中右键点击 VTube Studio → 属性 → 控制器 → 将覆盖设置为 “禁用 Steam 输入”。