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 hardware. DualSense and DualSense Edge controllers connect plug-and-play via WebHID without requiring window focus or initial button presses, and automatically reconnect after application restarts. Other gamepads follow the browser Gamepad API: click the stage to focus the window, then press any button on the controller to register the device.

Connected Controllers displays the total number of currently connected devices (including unassigned controllers). Active profiles are listed first, while remaining configurations are archived in the collapsible Saved Profiles list. Selecting a card switches the live monitor display only; 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 retain their respective bindings even when connection order or USB cables change. 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, touchpads, 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 containing 19 independent control channels: Left Stick X/Y, Right Stick X/Y, Stick Clicks (L3/R3), D-pad, four action buttons (A/B/X/Y), shoulder bumpers (L1/R1), triggers (L2/R2), Options, and Home. Analog sticks and the D-pad range from −1 to 1 with positive Y pointing upward; standard buttons and analog triggers range from 0 to 1. Each binding rule can select any input family, allowing different controllers to drive different avatars or parameters independently.

Profile #1 uses standard VTS input naming (ControllerStickLeftX, ControllerCross, etc.) to ensure full compatibility with existing .vtube.json files. Profile #2 and subsequent configurations insert the profile index after Controller (Controller2StickLeftX, Controller3Cross, Controller12TriggerRight). This numbered naming convention is a Persona extension, also shared by Plugin API input targets.

Controller inputs apply directly to each loaded model's binding logic, operating independently of facial tracking switches or source assignments. Controller inputs combine with facial inputs via weighted addition before range remapping, response curves, and smoothing stages—held facial inputs remain intact during tracking drops while controller inputs continue responding. Scrubbing an input slider in the editor takes precedence over physical controller input. Controller bindings use a frame-rate-independent exponential filter: smoothing 0 provides immediate response, while 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 facial tracking coordinate conventions, with VRM 0.x and 1.0 pitch/roll differences handled internally by the renderer; expression names match the model's internal declarations case-sensitively. Bone and gaze offsets layer additively on top of underlying base animations, pose tracking, and face tracking, while expression bindings exclusively control their targeted weights. At the end of each frame, the driver resets 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, 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.

Move Speed is measured in stage heights per second for Live2D and meters per second for VRM (default: 0.5, range: 0–10); it also scales Live2D zoom rate and VRM vertical lift speed. Turn Speed is measured in degrees per second (default: 90, range: 0–720). Response Smoothing sets the velocity filter time constant in seconds (default: 0.12, range: 0–0.5), where 0 gives instantaneous response. Live2D scaling is proportional to current size and respects established zoom boundaries.

Movement dynamics numerically integrate filtered velocity over elapsed real time, ensuring consistent travel speeds across 30, 60, and 120 fps. Returning sticks to neutral smoothly eases the avatar to a stop at its new coordinates. Disconnecting, disabling, or reassigning a controller immediately clears accumulated velocity, preventing residual momentum upon reconnecting. 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

VRM avatars only. 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.

When the avatar moves across the ground, the walk clip loops; upon stopping, it smoothly blends back into the idle animation. Walk Cycle Speed specifies the clip's nominal ground displacement speed at 1.0× playback rate (meters/second); runtime playback speed is dynamically calculated by dividing measured ground speed by this nominal velocity and the avatar's scale—automatically adapting step frequency when move speed or avatar scale changes. Horizontal (X/Z) hip translation is stripped from the animation clip to preserve scene coordinate authority, while 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) controlling the hips or legs automatically suppresses walking, while hands-only VMC tracking can run concurrently.

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—supports chords of up to three controls on a single gamepad, including analog stick extremes, D-pad directions, and triggers. Recorded shortcuts are strictly bound to their profile, allowing identical physical buttons on Controller #1 and Controller #2 to trigger distinct actions; inputs held on other controllers during recording are excluded. Shortcuts trigger once on initial press and do not repeat when held. Run in Background applies to controller shortcuts without requiring keyboard modifiers—recording and text input suppress shortcut activation and consume input events, ensuring held buttons never fire late upon closing the recorder or blurring an input field.

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.