UI Render

Put live 3D characters, particle systems and VFX Graph effects inside your menus — a spinning character in the inventory, GPU sparks bursting over a button, a rotating reward chest in a modal. Any 3D content renders directly onto any UI Toolkit element; Luna handles the cameras, render textures, pooling, and cleanup for you.

The whole API in two lines — drop a RenderElement in your UXML, play a prefab on it:

Scene setup (a dedicated layer + two manager components) is covered in the Quick Start below; how the pipeline works under the hood is in the Architecture Overview.

Features

• Pooled Architecture: Pre-warmed pool of Camera + RenderTexture slots with automatic grow/shrink
• Multiple Content Modes: Prefab instantiation, scene instance borrowing, and in-place observation
• RenderElement: Custom VisualElement with built-in render resolution and convenience API
• PlayOverlay: Layer 3D effects on top of existing UI elements without replacing their visuals
• PlayOverlayInstance: Overlay with an existing scene instance instead of a prefab copy
• Overlay Anchoring: Position overlays at 9 anchor points within the parent element
• Handle Replay: Re-instantiate content in the same slot without pool churn
• Pluggable Effect Handlers: Strategy pattern for particle, VFX, and custom effect lifecycle tracking
• Auto-Release: Slots automatically return to pool when effects finish playing
• Camera Controls: Auto-framing, runtime camera/content transforms, orthographic and perspective modes
• Debug Tools: RT-to-PNG export, detailed logging of camera, bounds, and slot state

Quick Start

Setup

1. Create a dedicated layer: run Tools > CupkekGames > Setup UIRender Layer (names layer 31 UIRender), or name one manually in Edit > Project Settings > Tags and Layers
2. Add UIRenderManager to a GameObject in your scene
3. Make sure a LunaUIManager is also in the scene — it drives UIRenderManager's per-frame tick (see UIRenderManager)
4. Configure pool settings in the Inspector

Using RenderElement (Recommended)

Add a RenderElement to your UXML:

Play a prefab on it from code:

Here root is the visual tree delivered asynchronously by your PanelRenderer's reload callback, or the root passed to UIViewComponent.OnUILoaded(root) — see the examples below.

Using Any VisualElement

You can render onto any VisualElement using the manager API directly:

Architecture Overview

The pipeline is pooled Camera → RenderTexture → UI Toolkit: each UIRenderSlot contains an isolated Camera rendering to its own RenderTexture on a dedicated layer, and the texture lands on your element as its background. The UIRenderHandle is the caller-facing API for stopping, releasing, and adjusting the render at runtime.

Content Modes

The system uses a strategy pattern for content lifecycle. Each mode determines how content is placed into a render slot and what happens on release.

Prefab Mode (Play)

Instantiates a copy of the prefab into the render slot. The copy is destroyed on release. Safe for auto-destroy particles.

Instance Mode (PlayInstance)

Borrows an existing scene GameObject by reparenting it into the render slot and changing its layer. The original parent, position, rotation, scale, and layer are restored on release. The object is not destroyed.

Observe Mode

Watches a scene GameObject in-place without moving, reparenting, or changing its layer. A camera is positioned to render the object where it sits and follows it every frame.

Activate (Generic)

Uses whatever content mode is configured in UIRenderSettings.ContentMode. Useful when the mode is set via the Inspector on a serialized UIRenderSettings asset.

PlayOverlay

PlayOverlay renders 3D effects as an overlay on top of an existing UI element — without replacing the element's background. This is ideal for layering particle effects over icons, buttons, or cards.

How It Works

1. A transparent child VisualElement is created inside the target element (positioned at the configured anchor)
2. The RenderTexture is applied to this overlay child — the original element's visuals remain untouched
3. The overlay's aspect-ratio is set from the RenderTexture dimensions to prevent stretching
4. When the handle is released, the overlay is automatically removed from the hierarchy

Basic Usage

PlayOverlayInstance

PlayOverlayInstance works like PlayOverlay but borrows an existing scene GameObject instead of instantiating a prefab copy. The instance is reparented into the render slot and restored to its original parent on release.

Custom Size

Custom Position

Without Aspect Ratio

Overflow Visible

By default, the overlay is clipped by the parent element's overflow USS property. If the overlay (especially with PreserveAspectRatio) is larger than the parent bounds, it will be cut off. Set OverflowVisible to automatically switch the parent's overflow to Visible while the overlay is active. The original overflow value is restored when the handle is released.

UIOverlaySettings Reference

OverlayAnchor

The OverlayAnchor enum controls where the overlay is positioned relative to its parent:

OffsetX and OffsetY are applied as margin offsets on top of the anchor position.

UIOverlaySettings Builder

Use the fluent Builder for cleaner creation:

Builder Methods

You can also modify existing settings:

SerializedOverlaySettings

SerializedOverlaySettings is an Inspector-serializable class that mirrors UIOverlaySettings. Use it as a [SerializeField] on any MonoBehaviour or ScriptableObject to configure overlay settings from the Inspector. Call Build() at runtime to produce a UIOverlaySettings instance.

Serialized Fields

Convenience presets

Four named-preset methods on UIRenderManager wrap PlayOverlay with common settings combinations. Each replaces a ~10-line builder-chain at the call site with a one-liner.

PlayBurst — fire-and-forget center burst

One-shot particle burst overlaid on target. The slot auto-returns to the pool when the ParticleSystem drains; a 5-second timeout guards against stuck slots. Use for level-up flares, currency-pickup bursts, on-click confetti — any single fire-and-forget effect that needs to spill outside the target's bounds.

Internally equivalent to PlayOverlay with auto-release: true, auto-release timeout: 5s, render-mode: Continuous, overflow-visible: true, preserve-aspect-ratio: true.

PlayBurst also powers the UI Attractor reactions FX hooks: assign a one-shot ParticleSystem prefab to BurstFx / AllArrivedFx on a UIAttractorDefaultReactionsSO asset and the attractor fires it over the burst source / target — no code at the call site.

PlayAmbient — continuous shimmer on small element

Continuous looping overlay sized in pixels, allowed to spill outside the target's bounds (sets target overflow to Visible for the overlay's lifetime). Use for burst-shaped continuous effects on small elements like icons or podiums where the particle envelope is larger than the host. Auto-releases when target detaches from the panel (tab change, modal close, screen pop).

PlayAmbientFill — exact-fit shimmer

Continuous looping overlay that exactly fills target's box — 100% width/height, no overflow mutation, no spillover. Use for surface-shimmer effects on elements that own their own clipping (rounded corners, gradients) and shouldn't have their layout/overflow disturbed. Auto-releases on detach.

PlayAmbientBottomBand — bottom-edge band

Continuous looping overlay pinned to the bottom edge of target, spanning the target's full width. Use for "rising particle" effects (sparkles, embers, confetti) where the emitter should originate at the bottom edge and drift upward through the host. heightPx controls how tall the emitter band is — small values (≤ target height / 3) keep emission near the edge; larger values bleed the spawn area upward into the host. Auto-releases on detach.

Auto-release-on-detach pattern

PlayAmbient, PlayAmbientFill, and PlayAmbientBottomBand all share a DetachFromPanelEvent hook that calls handle.Release() when target leaves the panel. You don't need to track handles or call Release yourself — the overlay cleans up as soon as the target screen is unmounted.

The hook is a one-shot DetachFromPanelEvent callback on the target — the first time the target detaches from its panel (including re-parenting, which detaches transiently), the handle is released.

For one-shot bursts, PlayBurst instead uses auto-release: true with a 5-second timeout — Unity's pool returns the slot when the ParticleSystem reports "no living particles" or the timeout expires, whichever comes first.

No-Code Components

Luna provides two MonoBehaviour components that expose the UIRender system in the Inspector — no C# required. They follow the same target-resolution pattern as TransitionAnimator: assign a UIViewComponent or PanelRenderer, specify an element name, and choose when to activate.

UIRenderActivator

Renders 3D content into a UI element's background. Supports three activation modes:

Inspector Properties

Code API

UIOverlayActivator

Renders 3D content as a transparent overlay on top of a UI element — ideal for fire-and-forget VFX like particle bursts on buttons or cards.

Inspector Properties

Code API

Target Resolution

Both components resolve the target VisualElement using the same priority chain:

1. UIViewComponent → uses ParentElement, then queries by element name
2. PanelRenderer → uses the visual tree delivered by the renderer's reload callback, then queries by element name
3. GetComponent / GetComponentInParent → auto-discovers a PanelRenderer on the same GameObject or parents

PanelRenderer delivers its visual tree asynchronously. On the PanelRenderer path, the component registers a reload callback (RegisterUIReloadCallback) on the resolved renderer and caches the delivered root; the callback fires immediately on registration if the panel is already mounted. If you call Activate() / Play() before the tree has been delivered, the component logs a warning and does nothing — retry after the panel mounts, or drive activation from a UIView fade trigger.

When a UIViewComponent is assigned, the Fade Trigger field appears and Activate On Enable / Panel Renderer are hidden — activation is driven by UIView lifecycle events instead.

UIRenderSettings

Per-request configuration for the render system. Use the Builder for fluent creation or serialize directly in the Inspector.

Builder API

Modify Existing Settings

Settings Reference

Render Modes

UIRenderHandle

The caller-facing handle returned by all activation methods. Controls the lifecycle of a single render instance.

Properties

Lifecycle Methods

Replay

Re-instantiates the content in the same render slot without returning it to the pool. The overlay element (if any) is preserved. Useful for restarting particle effects or VFX without pool churn.

Note: Replay() requires the handle to still be active. It destroys the current content, re-instantiates from the original source, and reapplies the RenderTexture to the target element.

Camera Controls

Events

Debug Methods

IDisposable

UIRenderHandle implements IDisposable for use in using blocks:

RenderElement

Custom VisualElement designed for 3D rendering. Provides UXML attributes for render resolution and convenience methods.

UXML Usage

UXML Attributes

Convenience Methods

When a RenderElement is detached from the panel (removed from the visual tree), it automatically releases any active handle.

UIRenderManager

Singleton manager that owns the render slot pool. Add this to a GameObject in your scene.

Inspector Properties

❗ Important — keep a LunaUIManager in the scene. UIRenderManager's per-frame upkeep (observe-mode camera follow, auto-release when effects finish, auto-release timeouts) runs in UIRenderManager.Tick(float), which is called by LunaUIManager.Update. Without a LunaUIManager alongside UIRenderManager, slots never auto-release.

Layer Setup

The render system requires a dedicated Unity layer to isolate render slot cameras from the main scene:

1. Open Edit > Project Settings > Tags and Layers
2. Assign a name to the layer configured in Default Layer (e.g. layer 31 → UIRender)
3. Ensure your main camera's culling mask excludes this layer

⚠️ URP / HDRP: include the UIRender layer in the renderer's layer mask. On the Universal Render Pipeline (URP) or HD Render Pipeline (HDRP) you must also add the UIRender layer to the Filtering > Opaque/Transparent Layer Mask of your active Universal Renderer Data (or Custom Pass volume for HDRP). The slot cameras render content on this layer — if the renderer asset excludes it, nothing appears in the RenderTexture even though the camera and layer are configured correctly.

Effect Handlers

The system uses pluggable effect handlers to track content lifecycle (e.g. when particles finish). Built-in handlers:

Custom Effect Handlers

Extend UIRenderEffectHandler and register via the static factory:

Example: Particle Effect on UI Icon

PanelRenderer delivers its visual tree asynchronously — query elements inside the reload callback, not in Awake/Start:

Example: 3D Character Preview

Demo Scenes

The Showcase sample includes two demo scenes (under Components/UIRender/):

• UIRenderDemoCharacters.unity: Demonstrates all four content modes (Prefab, Instance, Generic, Observe) with interactive controls for Play, Stop, Replay, Release, Frame, and Debug
• UIRenderDemoOverlay.unity: Showcases the PlayOverlay feature with five configurations — default full-size overlay, custom 50% size, offset position, anchored overlay (TopRight with overflow visible), and an instance overlay using PlayOverlayInstance. Includes a Replay All button to re-trigger all overlays.

Import the Showcase sample to explore these demos.

See also

• UI Attractor — fly-to coin/gem bursts as pure pooled VisualElements, for when you don't need GPU particles or cameras at all.
• Transition Animation — fire UIRender overlays mid-sequence via PlayOverlay nodes, no callback plumbing.
• Coordinate Utilities — screen ↔ world conversion when UI and 3D need to line up.

---

UI Render ships with Luna — get it on the Asset Store.