Persona

打开「捕捉 → 手柄」启用输入并管理配置。每个虚拟形象的移动方式在其自身的「捕捉」区域中设置。

手柄复制锚点链接

捕捉面板底部的手柄区块用于管理游戏控制器。手柄输入支持配置 Live2D 与 VRM 的 参数绑定、逐实例的舞台移动，以及用于 自动化 与 虚拟形象快捷键 的多键组合。手柄输入不依赖捕捉源与形象分配，且不支持直接控制相机机位。

连接手柄复制锚点链接

开启启用手柄开关后连接手柄：

• DualSense、DualSense Edge 与 DualShock 4（v1 与 v2）手柄通过 WebHID 即插即用，无需先聚焦窗口或按下按键即可自动识别，应用重启后也会自动重连。
• 在 Windows 上，Xbox 协议手柄（最多 4 只）通过原生 XInput 读取，同样无需按键唤醒，其他应用窗口在前台时也会持续上报输入。
• 其他手柄遵循浏览器 Gamepad API：先点击舞台使窗口获得焦点，再按下手柄上的任意按键，设备才会出现在列表中。

已连接的控制器实时统计当前在线的设备总数（包含尚未分配配置的手柄）。已连接的手柄配置卡片排在前面，其余配置归档于折叠的已保存的配置列表中。点击卡片只会切换实时监视面板显示的设备，不会改动已有的绑定。

应用设置中保存配置编号、硬件报告的产品名称以及硬件唯一标识符的加密哈希值（不保存原始硬件标识符）。具备唯一硬件标识的设备（如 DualSense 与 DualSense Edge）即使型号完全相同，在调换插入顺序或更换线缆后也能对应各自的绑定。拔掉手柄只会释放它的输入通道，不会删除配置或其绑定。

Xbox、其他系列 PlayStation 以及 Nintendo Switch Pro 手柄遵循 Chromium 的 standard 标准键位映射，依据按键的物理拓扑位置而非表面印字进行识别。无法识别的浏览器非标准映射会被标记为不支持。当前版本暂不支持陀螺仪体感、触控板触摸与滑动、自定义按键重映射以及多手柄合并为一个虚拟控制器。

手柄驱动参数复制锚点链接

在模型的参数编辑器中，每份已保存或已建立过绑定的手柄配置都会对应生成一组输入源。每条绑定规则都可以选用任意一组手柄输入，因此不同手柄可以分别驱动不同的模型或参数。

1 号手柄配置沿用 VTS 的标准输入名称，原有的 .vtube.json 映射可直接加载。2 号及之后的配置会在 Controller 后插入配置编号（如 Controller2StickLeftX、Controller3Cross、Controller12TriggerRight）。这套编号命名是 Persona 的扩展，插件 API 的输入目标也使用相同名称。下表列出的是 1 号配置的 ID：

• 四个方向键输入便于为上下左右分别建参的模型直接绑定，无需把轴向输入范围反转为 0 至 −1。
• PlayStation 手柄的触控板按下支持 DualShock 4、DualSense 与 SCUF Vantage。
• 对拇指而言，0 指十字键（左手）或面板按钮（右手），1 指推动或按下该侧摇杆。只有右手拇指会输出 3：该侧没有其他操作时按下触控板。
• 拇指与食指位置在空闲时保持最后的值，手柄连接时初始为 0。
• 从拇指或食指位置新建绑定时，输入范围默认按每个输出单位对应 1 档设置（如 0..1 参数对应 0..1），摇杆或扳机位置即可直接对应 1。
• 任一左侧按钮、任一右侧按钮、左侧按钮按下数与右侧按钮按下数统计各侧拇指负责的按键：左侧为十字键（每个轴向最多计 1 次）、摇杆按下与选项键，右侧为面板按钮、摇杆按下与选项键。肩键与扳机不计入。
• 手柄倾斜是兼容 VTS 的平滑倾斜偏移：按下左侧按键时为 +0.6，右侧为 −0.6，两侧同时按下则相互抵消，再减去两摇杆 X 平均值的 0.4 倍。

手柄输入直接作用于每个已加载模型自身的绑定，不受面部捕捉总开关或捕捉源分配的影响。手柄输入先经过模型的逐输入 校准，再与面捕输入加权相加，然后进入范围映射、响应曲线与平滑。面捕中断期间，保持的面捕输入仍然有效，手柄输入照常响应。

在参数编辑器中拖动输入滑块时，拖动的值优先于实体手柄输入。手柄绑定采用与帧率无关的指数滤波：平滑度为 0 时立即响应，为 100 时时间常数为 350 毫秒。

拔除单只手柄仅释放该手柄对应的输入组；关闭启用手柄总开关则释放所有控制通道。断开后，若无其他捕捉源驱动对应参数，Live2D 模型的输出值将平滑复位至 Cubism 的初始默认状态。

VRM 上的手柄目标复制锚点链接

在 VRM 虚拟形象 的参数编辑器中，系统生成了一批专为 3D 虚拟形象设计的虚拟绑定目标。这些目标并非源自 Cubism 参数：

角度沿用面部捕捉的坐标系约定，VRM 0.x 与 VRM 1.0 之间的俯仰与翻滚差异由渲染引擎在内部处理。表情名称须与模型内部声明的名称一致，区分大小写。

骨骼与视线偏移叠加在底层的基础动画、姿态捕捉与面部捕捉之上；表情绑定只控制其指向的权重。每帧结束时，驱动器会恢复底层状态，因此偏移不会累积，手动调好的表情权重也不会被覆盖。松开输入或删除绑定后，目标会平滑回到底层图层当前的状态，其他手柄及捕捉源控制的目标不受影响。

绑定规则归属于模型本身，持久化保存在模型同目录的 tracking sidecar 文件中，因此同一模型的多个实例共享这套绑定。若需让同一模型的不同副本独立运动，请使用下述的逐实例舞台移动功能。

舞台移动复制锚点链接

在虚拟形象自身的捕捉设置区中，勾选控制器移动并指定一份已保存的手柄配置。同时须确保启用手柄总开关已开启。舞台移动功能为可选特性，默认处于关闭状态——常规的参数绑定与手柄快捷键均不依赖此功能。

Live2D 的缩放基于当前尺寸等比进行，并遵循模型允许的缩放上下限。

移动按真实经过的时间对滤波后的速度做数值积分，因此在 30、60 与 120 fps 下移动速度保持一致。摇杆回中后，形象会平滑减速，停在新的位置。断开手柄、关闭功能或重新分配设备会立即清空累积速度，重连后不会残留此前的运动惯性。隐藏的虚拟形象不响应移动。

用鼠标直接拖拽摆放、执行位移过渡（如自动化的模型位置动作或插件发起的位移），以及文本输入、快捷键录制或分配手柄期间，舞台移动会暂时停止。

舞台移动将直接修改该实例在场景中的空间坐标，并随场景文件一同持久化保存。

移动时行走复制锚点链接

适用于VRM

在配置中开启移动时行走并从动画资源库中指定一个步行动画切片——可先开启开关，在选定动画切片前该功能不会生效。导入的 VRMA、Mixamo FBX 与 MMD VMD 动画格式与待机动画共享同一套已注册的动画资产列表。

虚拟形象在地面上移动时，步行动画循环播放；停下后平滑过渡回待机动画。

步态速度是该切片以 1.0 倍速播放时的标称地面移动速度（米/秒）。实际播放速率等于实测的地面移动速度除以该标称速度、再除以模型的缩放比例，因此调整移动速度或模型缩放时，步频会自动适配。

• 步行动画中髋关节 (Hips) 的水平（X/Z）位移会被剔除，以场景坐标为准；上下起伏会保留。
• 行走动画层不包含头部、视线与表情轨道，手柄与面捕驱动的姿态不受影响。
• 单次播放的动画优先。全身姿态捕捉（VMC、mocopi 或摄像头）驱动髋部或腿部时，行走会被自动抑制；仅驱动手部的 VMC 可以同时运行。

朝向移动方向选项使形象以设定的旋转速度平滑转向行进方向，与是否指定了步行动画无关；右摇杆的主动旋转优先。行走状态判定基于水平平面上的实际综合位移（包含惯性减速阶段），单纯的高度变化不会触发迈步。该系统属于叠加在直接位移之上的纯动画表现，不包含导航寻路、碰撞检测或复杂地形贴合。

手柄快捷键复制锚点链接

快捷键录制器同时用于自动化的键盘或控制器触发器与 虚拟形象快捷键，可录制同一只手柄上最多 3 个按键的组合。摇杆推到底的方向、十字键、扳机以及 PlayStation 触控板按下都可以录入。

• 录制的快捷键与所属的手柄配置绑定，因此 1 号手柄与 2 号手柄上的同一个实体按键可以触发不同的功能。录制期间在其他手柄上按住的按键不会被录入。
• 快捷键在按下的瞬间触发一次，长按不会重复触发。
• 后台生效同样适用于手柄快捷键，且无需键盘修饰键。
• 录制快捷键或在输入框中输入文本时，快捷键不会触发，输入事件也会被吞掉，因此关闭录制器或离开输入框时仍按住的按键不会延迟触发。

1 号手柄的触发宏沿用 VTS 的 Controller* 标识体系，2 号及后续手柄采用 Persona 扩展的编号标识。手柄快捷键不会注册为操作系统级的全局热键，且不支持手柄按键与键盘按键混按，亦不支持跨多只手柄组合。当不同模块配置了完全相同的按键组合时，自动化优先级高于虚拟形象快捷键。

.persona.json 文件以标准触发字符串格式保存所有手柄快捷键。对于使用 .vtube.json 的模型，带编号的手柄快捷键持久化存储于热键条目的 PersonaControllerTriggers 扩展字段中，同时原生 VTS 触发槽位会被置空，以避免 VTS 因读取未知枚举值而报错。Persona 读取时优先解析该扩展字段；若将该快捷键重新赋值为键盘或 1 号手柄按键，或彻底清空快捷键，该扩展字段将被自动移除。