The environment defines the physical and visual context for a scene, configured in the Environment section of the Stage detail pane. It comprises two primary components: an Environment Model (a 3D set that avatars stand inside) and an Environment Map (an equirectangular panorama providing ambient lighting and background scenery). Scenes can use either component independently or combine both. Click Choose Model… to select a 3D Objects model from the Inventory; click Choose Map… to pick from Environment Maps and Images. The trash icon beside each option (Remove Environment Model or Remove Environment Map) removes only that specific asset. Persona ships with built-in defaults: the Japanese Room environment model and the San Giuseppe Bridge environment map. Adding or removing an environment map or 3D set hot-swaps the stage's environment slot without freezing the render loop.
Similar to Camera and Lighting, 3D spatial properties appear only when the scene contains three-dimensional elements (a VRM avatar or a 3D object). In Live2D-only scenes, the panel displays only the post-processing color grading rows at the bottom (see Effects). Show and Hide is housed in the Control Panel's Transitions section, applying globally across all layer types.
Environment Maps
An environment map is an equirectangular image that supplies image-based lighting (IBL) across the entire scene from all directions. High-dynamic-range .hdr files carry physical radiance measurements, while standard PNG, JPEG, and WebP images serve as flat, uniform diffuse fill lights.
Environment Models
An environment model is a standard .glb file representing an architectural interior, stage set, or exterior location. It shares the same loading pipeline, spatial transforms, and shadow casting behavior as a 3D object layer, with identical position, rotation, scale, and opacity controls. Unlike standard object layers, an environment model belongs to the global scene setup and does not occupy an entry in the layer hierarchy.
The Handles toggle below these fields displays 3D manipulation handles in the stage viewport, allowing intuitive direct dragging to position the environment. Handles are automatically disabled in Stream Mode.
| Control | Description |
|---|---|
| Model Lights | Determines whether light sources embedded within the model file are illuminated. Expands to reveal the three child settings below |
| Lights Affect Avatars | Whether embedded model lights illuminate avatars. When disabled, avatars respond exclusively to the scene's primary lights |
| Lights Affect 3D Objects | Controls whether embedded model lights illuminate 3D object layers |
| Apply Environment Lighting | A one-click preset: enables both lighting routes and dims every scene-level light to 0.25, preventing MToon materials from blowing out under combined illumination |
When Lighting Source is set to From Model, Persona generates an ambient lighting probe at the avatar's coordinates. This probe recalculates upon asset load and whenever the model's transform, switches, map, or orientation change, rather than running on every frame. Embedded model lights appear beneath Model Lights and feature the same controls as lights inside 3D objects. Lights intended solely for baked lightmaps default to an intensity of 0 to prevent doubling indirect light already captured in the probe; their intensity can still be adjusted manually.
3D scene files can store embedded presets for fog, tone mapping, exposure, bloom, and color grading. Clicking Apply Environment Look imports and applies these values, replacing current scene fog and post-processing settings. If you have not modified these properties, Persona automatically applies the embedded look when loading the environment model.
Lighting and Skybox
Selecting an environment model or environment map surfaces the following lighting and background controls:
| Control | Description |
|---|---|
| Lighting Source | Available when an environment model is loaded: choose Environment Map or From Model (detailed below) |
| Show Skybox | Renders the panoramic background in the distant view without affecting illumination |
| Skybox Blur | Depth-of-field blur radius applied to the skybox panorama, 0 – 1 |
| Skybox Brightness | Display brightness multiplier for the skybox, 0 – 2 (default 1), without affecting lighting |
| Environment Rotation | Synchronously rotates the panoramic texture and its emitted lighting, −180° – 180° |
| Intensity | Overall ambient lighting irradiance multiplier, 0 – 2 |
| Avatar Intensity | Weight of environment ambient lighting cast onto MToon avatar materials, 0 – 1 |
Environment Map illuminates the scene directly using the panorama texture, falling back to the model's built-in sky when no map is selected. From Model computes ambient illumination from the geometry of the 3D set itself, while the map (or sky) remains visible through windows and in specular reflections. Selecting a map automatically sets Lighting Source to Environment Map. Adding an environment model without a map initializes the source to From Model; adding a model with a map present defaults to Environment Map. Replacing an existing model preserves the current selection, and removing an active map falls back to From Model.
The standard VRM MToon shader specification does not define an ambient lighting term; Persona adds an internal shader extension, modulated by the Avatar Intensity slider. Standard PBR surfaces (including 3D objects and non-MToon materials) always receive full environmental irradiance and ignore this slider.
The skybox renders the active environment map, or the model's embedded sky when no map is assigned, regardless of the active Lighting Source. Dynamically computed irradiance probes cannot be sampled as background visuals; if neither an environment map nor an embedded sky exists, the skybox remains transparent. Skybox Blur and Skybox Brightness appear only when Show Skybox is active.
Fog
Fog blends distant 3D geometry smoothly into a chosen background tint, enhancing depth perception and spatial separation between the avatar and background props.
| Control | Description |
|---|---|
| Fog Color | Target tint that distant geometry fades into |
| Density | Rate of fog accumulation along the view line, 0 – 0.5 |
Fog density attenuates exponentially with the square of camera distance. On metric stages, low density values provide substantial spatial atmospheric occlusion.
Physics
Physics grants 3D objects rigid-body dynamics and gravitational acceleration, allowing them to collide and settle naturally on the floor or on a VRM avatar. This feature is disabled by default in new scenes.
Simulated positions and orientations are never persisted. Toggling Physics off immediately restores every object to its authored spatial coordinates.
What Takes Part
- Only 3D objects participate in dynamics calculations, using their bounding boxes as collision proxies. Image, video, and webpage layers remain static in 3D space, and items pinned to a model remain locked to their parent transforms.
- The floor is an infinite plane aligned to vertical height 0; complex geometry from the Environment Models does not contribute to collision calculations.
- VRM avatars catch falling objects using fitted body capsule colliders, without being moved or tipped over by incoming impacts. Live2D avatars do not participate in physics.
- Hidden objects and avatars are temporarily excluded from simulation calculations.
Placing Objects
Dragging an object with its viewport handles temporarily suspends it from the simulation. Upon releasing the handle, the object resumes falling under gravity from its new position. Directly updating transform numbers in the inspector restarts the simulation from those explicit coordinates.
Spawning from the Plugin API
Using stage.spawn in the Plugin API, external extensions can instantiate batches of dynamic 3D rigid bodies (such as streaming gift props falling into the scene). Spawned clones bypass the layer list, are never saved, and automatically despawn after 30 seconds by default. Unless overridden in the API call, their entry and exit follow the scene's global Show and Hide transition settings.
Show and Hide
Show and Hide defines the entry and exit transitions applied to models, objects, and API-spawned bodies during creation, removal, visibility toggles, and asset replacement. It is located in the Control Panel's Transitions section.
| Style | Description |
|---|---|
| Glitch | Default setting. Dithered dissolve with scanline tears and burn |
| Fade | Smooth alpha transition blending each item as one layer so interior surfaces never show through |
| Pop | Scales in with spring cushioning, then scales down on exit |
| Cut | Instant visibility change without transitional animation |
Duration defines the transition runtime in milliseconds, spanning 0 – 5000 ms (default 300 ms); this field is hidden when Cut is active.
How transitions apply across layer types:
- 3D objects and VRM avatars: Under Fade, the entire item is handed to a dedicated pass that composites it at its alpha while preserving depth sorting, preventing interior surfaces from showing through one another; Glitch tears and burns through a dithered mesh dissolve. A resting placement opacity below 1 continues to use screen-space dithering to avoid self-transparency.
- Live2D avatars: Under Glitch, horizontal row tears and dither run as a pass over the flattened canvas; Fade adjusts the model's overall alpha; Pop scales the avatar.
- Image, video, webpage, and text layers: Under Glitch, the quad mesh divides into horizontal strips that bend row by row; Fade ramps opacity; Pop scales the layer.
- Spawned bodies (
stage.spawn): Automatically pop under Fade, as instances share geometry and cannot be composited as separate layers.
Last updated on October 11, 2026