A scene maintains an ordered list of layers, displayed in the Layers panel on the left column of the Control Panel. Avatar models and multimedia objects are managed in this unified list: whether a Live2D or VRM model, a chat overlay image, a looping video background, or a 3D stage prop, each renders as an individual layer item stacked along a unified Z-axis. Post-processing effects occupy dedicated entries grouped under Scene Effects at the top of the layer list, while Stage is pinned at the bottom of the list to switch to stage properties and clear layer selections.
The list follows standard layer panel conventions, with the top-most row rendering at the very front of the stage. Drag the handle on the left of an entry to reorder its hierarchy vertically.
Guides
Layer Controls
| Element | Description |
|---|---|
| Grip | Drag to reorder layer stacking; the top row renders in the foreground |
| Eye | Toggles layer visibility without removing it from the scene; transitions follow the scene's Show and Hide configuration |
| Name | Custom display name for the model or object |
| Pin | Identifies an item, media, or webpage pinned to a model; hovering displays the target attachment |
| Star | Identifies the primary model for the active scene |
| Warning | Indicates that a local file the layer references is missing |
| Type Icon | Displays a Live2D, VRM, Image, Video, 3D Object, Webpage, Text, or Capture badge; hover to view details |
| Actions Menu | Set as Primary · Swap… · Reset Position · Show in Finder · Remove from Scene |
Clicking Show in Finder (displayed as Show in Explorer on Windows) reveals the physical file in your operating system's file manager. Webpage, text, and capture layers do not correspond to local physical files, so this option is omitted from their context menus.
Clicking a layer row selects it and expands its configuration sections in the detail pane on the right. Clicking the selected row again (or pressing Esc) collapses these sections.
Effect Layers
Global post-processing effects also occupy entries in the layer list, grouped under Scene Effects at the top of the Layers panel. Rows appear only for effects actively enabled in the scene. If no effects are enabled, this group is hidden automatically.
Add effects from the Scene Effects category in the Inventory. An effect already in the scene is marked Added and can't be selected again. While browsing, this category appears only in its own tab, so built-in effects don't clutter the All view. When you search from the top field, the All view shows matching effects as well.
Scene effects apply to every layer in the scene, including 2D images, videos, webpages, and text. The category is disabled with an explanatory tooltip only when the scene is completely empty. For details, see When the Chain Appears.
Effect layer rows share the appearance of standard layers but feature distinct interactions:
| Element | Description |
|---|---|
| Eye | Toggles the effect on or off, ramping smoothly over 0.4 seconds rather than cutting abruptly |
| Name | Standard shader effect name |
| Grip | None; effect execution order is fixed by the shader pipeline and cannot be manually reordered |
| Type Icon | Scene Effect |
| Actions Menu | Reset to Defaults · Remove from Scene |
Row order strictly mirrors the post-processing pipeline order, with the final composited pass displayed at the top.
Clicking an effect row opens the Scene Effect · Name panel in the detail area, exposing all shader parameters. Effect selection uses an isolated selection context, so selecting an effect never activates stage transform handles or interferes with viewport navigation.
Clicking Remove from Scene unbinds the effect from the scene's rendering pipeline while keeping its parameter values; re-adding the effect restores your previous settings. To revert parameters to factory values, click Reset to Defaults.
Built-in effects can also be activated programmatically via
automations or scene.patch API calls.
Regardless of trigger source, matching entries are inserted into the layer
list automatically.
Missing Files
If a model or media file a layer references is moved, renamed, or deleted on disk, the layer row shows a warning icon. Selecting the layer replaces its settings in the detail pane with a File not found alert that lists the original file name and folder, offering the following actions:
- Locate…: Opens a file picker (starting in the nearest existing parent of the original folder) to point the layer at the file's new location. Models require a valid model file of the same format (Live2D or VRM). Relocating a model updates every layer, hotkey, and automation that references it across all scenes; relocating a media file relinks only the current layer and keeps its settings. Bundled assets and catalog downloads do not offer this option.
- Download: When the missing model is offered in the Persona catalog under Downloads (for example, a downloaded model whose install folder was deleted, or a sample model that moved from the app bundle to the catalog), the alert offers a Download button with an inline progress bar. Once downloaded, every layer referencing that model ID relinks automatically.
- Remove from Scene: Removes the layer.
Persona does not watch files continuously; it rechecks them whenever any of its windows gains focus. A file that has been moved away is marked missing, and the mark clears once the file is moved back. The matching Inventory entry is also badged Missing; see Inventory.
Swapping a Layer
Selecting Swap… from a layer row's actions menu reopens the Inventory to perform an in-place swap rather than adding a new layer, with the header indicating the target being replaced.
Inventory browsing automatically narrows to the layer's asset family: model layers can be swapped with other models (Live2D or VRM), and object layers can be swapped with other multimedia sources (including webpages). Stacking hierarchy, spatial transform coordinates, and primary model status are preserved across swaps.
Model swapping respects the scene's configured Show and Hide transition animations (see Swapping Models).
The Primary Model
A scene designates exactly one model with a star badge. This model serves as the default target when invoking model-scoped Plugin API methods without specifying an instance ID, and corresponds to the Primary Model macro in automation rules.
Selecting Set as Primary in a row's actions menu transfers the star. Non-model objects cannot be designated as primary because they lack drivable parameters. Avatar Shortcuts operate independently of the primary model: every model in the scene maintains its own shortcut bindings and responds to triggers, with the primary model listed at the top. Automation avatar actions can explicitly target specific layers, making them compatible with any avatar on stage.
Face tracking is configured independently of primary model designation. Each avatar binds to its own tracking input source, allowing three mobile devices to drive three separate avatars simultaneously regardless of which avatar holds primary status.
Other Object Settings
Video layers support independent playback transport, looping, and sound output. Selecting a video layer reveals the Video settings group:
- Playback: Play and pause toggle button with a scrubbing slider (drag to seek while previewing frames live on stage, arrow keys step 1s, Shift or Page keys step 10s; displays current position and total duration, such as
00:12 / 01:30). Paused state (paused) persists across app relaunches, scene switches, undo/redo, and API edits. - Loop: Automatically restarts the video when reaching the end (enabled by default).
- Volume: Mute toggle button and Volume slider (0–100%; volume remains adjustable while muted). Sound routes through the configured Audio Output Device and is captured by Studio Mode's Stage Audio; if the configured output device is unavailable, video remains muted rather than falling back to the system default.
Image, video, and webpage layers support Chroma Key:
- Enable Chroma Key: Makes one color transparent, like a green screen (disabled by default).
- Key Color: Sets the color to make transparent (defaults to green
#00ff00). - Similarity: Widens the range of colors that turn transparent (1–1000, default 400).
- Smoothness: Softens the edge between transparent and visible areas (1–1000, default 80).
- Spill Reduction: Removes the key color's tint from edges (1–1000, default 100).
Chroma Key implements OBS Studio's Chroma Key filter, calculating BT.709 chroma distance so brightness never counts, allowing darker and lighter shades of the target color to key cleanly.
When an imported 3D object contains embedded light sources, those lights are automatically listed in the Control Panel's Lighting section under the header Built into [Object Name]. Each embedded light can be toggled or dimmed independently without altering the scene's primary lighting configuration.
Last updated on November 3, 2026