Click New Expression at the top of the Expressions panel to create an .exp3.json expression file in the model's directory. The dropdown menu beside each expression button provides Edit… and Duplicate… actions; for standalone files not declared in the model settings, Rename… and Delete… are also available.
The expression editor is exclusive to Live2D models. Once saved, expression files appear immediately in the Expressions list without requiring a model reload.
The Editor
The left side of the dialog configures the expression file's general settings; the right side lists every available parameter on the model with its own control row.
| Control | What It Does |
|---|---|
| Name | File name, with the file extension fixed on the right. When editing existing files, the name is locked—use Rename… to rename it |
| Fade In, Fade Out | Transition durations saved to the file (0 to 5 seconds). If omitted in the file, Cubism defaults to 1 second |
| Solo | Enabled by default. Temporarily mutes all other active expressions on stage while editing |
| Show Physics | Shows parameters driven by physics simulation in the list, disabled by default |
| Active at Top | Sorts enabled parameter rows to the top of the list |
| Filter Parameters | Filters parameters by name or parameter ID. Displays total and active counts on the right |
| Shortcut | See Shortcut |
| Capture Pose | See Capture Pose |
| Revert | Discards all changes made during the current editing session and restores the file's saved content |
The toggle on each row determines whether that parameter is included in the expression. Enabling a row reveals a Blend mode dropdown and a numeric slider. Each row displays the parameter's group and ID, and physics-driven parameters display a Physics badge.
Click Save to write changes to disk. Click Cancel to discard edits—the button turns an alert color whenever unsaved modifications are present.
Shortcut
The Shortcut section lets you bind a hotkey to toggle the expression directly, streamlining creation and hotkey assignment into a single workflow. Click Add Shortcut to create a binding; the field beside the heading records key combinations using the same recorder as Set Shortcut… under Avatar Shortcuts.
| Control | What It Does |
|---|---|
| Hold to Activate | The expression remains active only while holding the shortcut keys, deactivating on release |
| Fade Time | Custom fade duration used by this shortcut. Choosing Default uses the file's native Fade In and Fade Out |
| Turn Off After | Automatically deactivates the expression after the specified delay. Selecting Never keeps it active until toggled |
These options represent the shortcut's playback options, matching the context menu in the automations list. When Fade Time is set to a custom duration (rather than Default), triggering the shortcut overrides the file's native fade values; clicking UI buttons, calling the Plugin API, or running automated tasks continues to use the file's native fade settings.
This section only displays and edits the primary shortcut attached to the expression file. If multiple shortcuts are assigned, the interface indicates the total count and directs you to Automations—where you can toggle Run in Background, delete shortcuts, and configure secondary keybindings. Newly created or duplicated files start with no shortcuts assigned.
Shortcuts are committed to disk upon clicking Save, immediately following file creation (bound by the saved file name). Only fields modified during the session are written, ensuring bindings modified in Automations or via the Plugin API while the dialog was open are not overwritten. If a shortcut was deleted externally in the interim, the editor reports that the shortcut could not be saved while still preserving the expression file itself.
Blend Modes
| Mode | What the File Stores | Slider Range |
|---|---|---|
| Add | Relative delta offset from the parameter's default value. Multiple expressions sum additively (default for new rows) | Parameter's native range |
| Overwrite | Absolute parameter value. When multiple expressions conflict, the most recently applied takes precedence | Parameter's native range |
| Multiply | Multiplication scaling factor. Multiple expressions multiply together | -3 to 3 (matching VTube Studio) |
The slider always reflects the final computed position of the parameter on the model. In Add mode, the slider presents the absolute preview value, which is automatically converted to a relative delta before writing to the file.
Switching blend modes preserves configured values independently for each mode, allowing you to toggle between modes without losing adjustments.
VTube Studio interprets Overwrite as an offset relative to default values, whereas the official Cubism engine and Persona interpret it as an absolute value. To ensure an expression file behaves identically across both applications, use Add mode.
Preview
While the editor is open, parameter adjustments render live on the stage model. The preview pipeline runs after all inputs and tracking drivers, ensuring parameter adjustments remain visible even while face tracking is actively moving the model (matching the behavior of VTube Studio's expression editor).
The expression currently being edited is automatically muted: it retains its active state and fade timings but pauses its original parameter contributions, preventing preview adjustments from stacking onto existing values. The Solo toggle simultaneously mutes all other active expressions on stage. Disabling Solo layers the edited values over other active expressions, showing the final composite result.
Muting is distinct from disabling. While the editor is open, shortcuts, automations, and the Plugin API continue toggling and saving active expressions in the background, requiring no state restoration when closing the editor.
Parameters driven by physics simulation do not participate in live previews, as they are computed dynamically by the physics engine at runtime. Toggling Show Physics simply allows them to be edited and saved to the file.
At runtime, active expressions rank above face tracking: on tracked parameters, Overwrite replaces the tracked value, while Add and Multiply compose over it. Parameters injected through the Plugin API still write over both. The preview always shows your edits so you can visualize adjustments even while tracking is active.
Capture Pose
Capture Pose samples all parameters on the model in the current frame—incorporating tracking, motions, and idle animations—and enables all parameters deviating from their defaults as Add rows.
If all parameters are currently at their default values, clicking the button displays Nothing to capture and creates no rows.
Where Files Are Saved
Newly created or duplicated expression files are saved to the model's root folder (the standard expression directory used by VTube Studio). If a listed expression already exists in a subfolder with that name, new files are saved beside it. Editing an existing file always writes back to its original path.
Saved files update immediately: new files appear as new entries under Expressions, and existing files update in place. Active expressions adopt changes immediately without fading in.
File names that collide with existing expressions are rejected, as shortcuts and Remembering Expressions bind strictly by file name. If a physical file with the same name already exists on disk, the editor asks Replace the existing file? for confirmation.
Expressions cannot be saved if the model folder is read-only (such as the bundled sample model). In this scenario, load a custom model from a writable local directory.
Renaming and Deleting
Only standalone expression files not declared in .model3.json can be renamed or deleted. Built-in expressions declared in the model manifest are protected against modification (Persona never alters model configuration files). Built-in expressions can still be modified using Edit… or cloned using Duplicate…, which creates a standalone copy.
Rename…: Renames the file on disk and updates bound avatar shortcuts and remembered expressions automatically. Active expressions remain enabled under the new name.
Delete…: Moves the file to system Trash and removes all associated shortcuts, with the confirmation dialog stating how many shortcuts are affected.
Both operations ensure transactional consistency: shortcut bindings and remembered states are updated before altering the file on disk. If sidecar file writes fail (e.g., read-only or malformed JSON), the entire operation aborts, leaving the original file untouched.
File Compatibility
Persona maintains robust file compatibility: all original settings in expression files are preserved, including fade durations, disabled parameters, and non-standard vendor fields (such as VTube Studio's IsModelCustomizationExpression). When saving, these are preserved intact, avoiding issues where VTube Studio strips unrecognized fields.
Multiple entries for the same parameter sharing a blend mode collapse into a single editor row: Add entries sum, Multiply entries multiply, and Overwrite entries take the final value, matching runtime composition algorithms. A single row represents the complete effect on that parameter, and disabling the row removes the effect entirely.
If an expression file references parameters not present on the current model (common when sharing files across models), Persona preserves them intact on save, displaying the count of hidden entries at the bottom of the list. When entries for a single parameter mix different blend modes, preceding runs remain in the underlying data structure and participate in playback and file writing only while the row is enabled.
Last updated on October 11, 2026