Persona

Open Tracking → Controller to enable input and manage profiles. Per-avatar movement is configured in the selected avatar’s Tracking section.

ControllerCopy Anchor Link

The Controller section at the bottom of the Tracking panel manages gamepads and controllers. Controller inputs support Live2D and VRM parameter bindings, per-instance stage movement, and multi-button chords for automations and avatar shortcuts. Controllers operate independently of tracking sources and avatar assignments, and cannot directly control camera positioning.

Connecting a ControllerCopy Anchor Link

Turn on Enable Controller and connect the controller:

• DualSense, DualSense Edge, and DualShock 4 (v1 and v2) controllers connect plug-and-play via WebHID. They need no window focus or first button press, and reconnect automatically after the app restarts.
• On Windows, Xbox-protocol controllers (up to four) are read via native XInput. They also connect without a button press, and keep reporting while another app's window is focused.
• Other gamepads follow the browser Gamepad API: click the stage to focus the window, then press any button on the controller so the device appears in the list.

Connected Controllers displays the total number of currently connected devices (including unassigned controllers). Cards for connected profiles are listed first, while the rest are archived in the collapsible Saved Profiles list. Selecting a card only switches the live monitor; it never alters existing bindings.

Application settings store the profile number, reported product name, and a cryptographic hash of the hardware identity (raw hardware identifiers are never stored). Devices with unique hardware IDs (such as DualSense and DualSense Edge) keep their own bindings when connection order or USB cables change, even when the controllers are identical. Unplugging a controller releases its input channels without deleting the profile or its bindings.

Xbox, other PlayStation models, and Nintendo Switch Pro controllers follow Chromium's standard button mapping, recognizing inputs by physical button layout rather than printed surface labels. Unrecognized non-standard browser layouts are marked as unsupported. Gyroscope sensors, touchpad touches and swipes, custom button remapping, and merging multiple gamepads into a single virtual controller are not supported in this version.

Driving ParametersCopy Anchor Link

In a model's Parameters editor, each saved or bound controller profile provides a dedicated input family. Each binding rule can select any input family, so different controllers can drive different avatars or parameters independently.

Profile #1 uses standard VTS input names, so existing .vtube.json files keep working. Profiles #2 and up insert the profile number after Controller (Controller2StickLeftX, Controller3Cross, Controller12TriggerRight). This numbered naming is a Persona extension, also shared by Plugin API input targets. The IDs below are profile #1's:

• The four D-pad directions let a rig with a separate parameter per direction bind each one directly, without reversing an axis input range to 0 to −1.
• PlayStation Touchpad Click is supported on DualShock 4, DualSense, and SCUF Vantage.
• For a thumb, 0 means the D-pad (left) or face buttons (right), and 1 means its stick is moved or clicked. Only the right thumb reads 3: a touchpad click while nothing else on that side is active.
• Thumb and index finger positions hold their last value while idle, and start at 0 when a controller connects.
• A new binding from a thumb or finger position defaults its input range to one step per output unit (for example, 0..1 for a 0..1 parameter), so the stick or trigger reaches 1 out of the box.
• Any Left Button, Any Right Button, Left Button Count, and Right Button Count track the buttons under each thumb: the D-pad (each axis counts at most once), stick click, and Options on the left; the face buttons, stick click, and Options on the right. Shoulders and triggers are excluded.
• Controller Lean is VTS's eased tilt nudge: +0.6 for left-side presses and −0.6 for right-side presses, cancelling when both sides are pressed, minus 0.4 × the average stick X.

Controller inputs apply directly to each loaded model's bindings, independently of the face tracking switch or source assignments. They pass through the model's per-input calibration, then combine with face inputs by weighted addition before range remapping, response curves, and smoothing. Held face inputs stay intact during tracking drops while controller inputs keep responding.

Scrubbing an input slider in the editor takes precedence over the physical controller. Controller bindings use a frame-rate-independent exponential filter: smoothing 0 responds immediately, and 100 corresponds to a 350 ms time constant.

Unplugging a controller releases only its own input family; turning off Enable Controller releases all controller channels. Once disconnected, any Live2D parameter no longer driven by an active source smoothly resets to its default Cubism value.

VRM TargetsCopy Anchor Link

In the Parameters editor for VRM avatars, Persona provides a set of virtual binding targets tailored for 3D avatars rather than imported Cubism parameters:

Angle values follow face tracking coordinate conventions, and the renderer handles the pitch and roll differences between VRM 0.x and 1.0 internally. Expression names match the model's internal declarations case-sensitively.

Bone and gaze offsets layer additively over the underlying base animation, pose tracking, and face tracking, while expression bindings control only the weights they target. At the end of each frame, the driver restores the underlying state, so offsets do not accumulate and hand-tuned expression weights are preserved. Releasing an input or removing a binding smoothly eases the target back to the underlying layer's state without affecting other controllers or tracking sources.

Bindings belong to the model itself, stored in its tracking sidecar file in the model's folder, and are shared across all instances of that model. To control multiple copies of a model independently, use the per-instance stage movement settings below.

Stage MovementCopy Anchor Link

In an avatar's Tracking section, enable Controller Movement and select a saved controller profile. The Enable Controller master switch must also be active. Stage movement is an optional feature, disabled by default—parameter bindings and shortcuts do not require it.

Live2D scaling is proportional to current size and respects established zoom boundaries.

Movement numerically integrates filtered velocity over elapsed real time, so travel speed stays the same at 30, 60, and 120 fps. Returning the sticks to neutral smoothly eases the avatar to a stop at its new position. Disconnecting, disabling, or reassigning a controller immediately clears accumulated velocity, so no momentum carries over when it reconnects. Hidden avatars do not respond to movement.

Direct mouse dragging, automated Model Position transitions, API moves, text input, shortcut recording, and controller pairing all temporarily pause stage movement.

Stage movement directly updates the avatar instance's world placement coordinates, saving alongside the scene.

Walking While MovingCopy Anchor Link

Applies toVRM

Enable Walk While Moving and select a Walking Animation from the asset inventory—the toggle can be enabled beforehand and becomes active once a clip is chosen. Imported VRMA, Mixamo FBX, and MMD VMD animations share the same registered asset inventory as idle clips.

While the avatar moves across the ground, the walk clip loops; when it stops, the avatar smoothly blends back into the idle animation.

Walk Cycle Speed is the clip's nominal ground speed at 1.0× playback, in meters per second. Playback speed is the measured ground speed divided by this value and by the avatar's scale, so the step rate adapts automatically when move speed or avatar scale changes.

• Horizontal (X/Z) hip translation is stripped from the clip so the scene's coordinates stay authoritative; vertical bobbing is retained.
• The walking layer excludes head, gaze, and expression tracks, preserving controller and face tracking poses.
• One-shot animations take priority. Full-body tracking (VMC, mocopi, or webcam) that controls the hips or legs automatically suppresses walking, while hands-only VMC tracking can run alongside it.

Face Movement Direction rotates the avatar toward its movement vector at Turn Speed, regardless of whether a walking clip is assigned; right-stick turning takes priority. Walking detection evaluates actual horizontal displacement (including deceleration easing), so vertical changes alone do not trigger walking. This system is a pure procedural animation layered over stage movement and does not include pathfinding, collision detection, or terrain snapping.

Controller ShortcutsCopy Anchor Link

The shortcut recorder, used for automation Keyboard or Controller triggers and avatar shortcuts alike, records chords of up to three controls on a single gamepad. Analog stick extremes, D-pad directions, triggers, and PlayStation touchpad clicks all count.

• Recorded shortcuts are bound to their profile, so the same physical button on Controller #1 and Controller #2 can trigger different actions. Inputs held on other controllers during recording are excluded.
• A shortcut fires once on the initial press and does not repeat while held.
• Run in Background applies to controller shortcuts without requiring a keyboard modifier.
• Recording and text input suppress shortcuts and consume the input, so a button still held when you close the recorder or leave an input field never fires late.

Controller #1 macros use standard VTS Controller* identifiers, while Controller #2 and above use numbered Persona tokens. Controller shortcuts do not register as OS-level global hotkeys and do not support mixing keyboard and controller inputs or cross-controller chords. When identical chords are configured across systems, automations take priority over avatar shortcuts.

.persona.json stores all controller shortcuts in standard trigger string format. For models using .vtube.json, numbered controller shortcuts are saved in the hotkey entry's PersonaControllerTriggers extension field while native VTS trigger slots are cleared to prevent VTS from encountering unknown enum values. Persona prioritizes reading this extension; reassigning the shortcut to a keyboard key or Controller #1 button, or clearing the hotkey, automatically removes the extension.