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 offers Edit…, Duplicate…, and Set Shortcut…. For standalone files not declared in the model settings, it also offers Rename… and Delete….
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 is highlighted whenever there are unsaved changes).
Shortcut
The Shortcut section lets you bind a hotkey to toggle the expression directly, streamlining creation and hotkey assignment into a single workflow (if you only want to bind or change a shortcut on an existing expression, you can also choose Set Shortcut… directly from that expression button's dropdown menu in the Expressions panel). 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 are the shortcut's playback options, the same ones found in its context menu in the automations list. When Fade Time is set to a duration rather than Default, toggling the expression with this shortcut uses that duration instead of the file's own Fade In and Fade Out. Clicking UI buttons, calling the Plugin API, or running automations still uses the file's own fade settings. If the expression is a member of an enabled expression group, its Fade Time in that group applies instead, however it is switched.
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 links to Automations, where you can toggle Run in Background, delete shortcuts, and manage additional 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 runs through the same expression pipeline as the saved expression: rows are parsed as the saved file would be, blended with other active expressions after auto-blink and before breathing and physics, and layered over face-tracked parameters exactly as during playback. What you preview is therefore what the saved expression does; if the model drives its head or eyes through physics, the preview also shows the post-physics result.
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 are hidden by default and listed only when Show Physics is on. Once enabled, such a row takes part in preview and saving like any other parameter, and physics then overrides its value according to that output's weight, just as during playback.
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. On eye parameters, Overwrite holds the eyes at the set value and stops auto-blink, while Add and Multiply compose over the blink. A playing motion (other than the idle) outranks Overwrite and Add on the parameters it animates, while Multiply still applies on top. The preview follows the same rules.
Capture Pose
Capture Pose samples all parameters on the model in the current frame (including tracking, motions, and idle animations, while excluding expressions and Plugin API overrides) and enables every parameter that differs from its default as an Add row. Active random pulse firings are ignored automatically (sampling the underlying parameter value before the pulse), and clicking mid-blink waits for the eyes to reopen before capturing so auto-blink is never recorded into the expression (if the model is paused mid-blink, the capture leaves out eye parameters).
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, Remembering Expressions, and expression groups 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, remembered expressions, and expression group members automatically. Active expressions remain enabled under the new name.
Delete…: Moves the file to system Trash, removes all associated shortcuts, and takes it out of any expression group, with the confirmation dialog stating how many shortcuts are affected.
In both operations, shortcut bindings, remembered states, and expression groups are updated before the file on disk is changed. If sidecar file writes fail (for example, if the file is read-only or contains malformed JSON), the entire operation aborts and leaves the original file untouched.
File Compatibility
Persona preserves all original settings in expression files, including fade durations, disabled parameters, and non-standard vendor fields (such as VTube Studio's IsModelCustomizationExpression), avoiding issues where VTube Studio strips unrecognized fields on save.
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 November 3, 2026