UI Effects

Luna's UI Effects system adds composable shader-based visual effects to any UI Toolkit VisualElement — drop shadows, glows, insets, outlines, gradients, shine sweeps, flash pulses, tiled patterns, dissolves. Authoring is USS-driven: an element opts in with the luna-fx marker class, then tier / body / fill classes layer the look. C# exists as an imperative escape hatch but isn't the recommended path.

Quick start

⚠️ Step 0 — assign UIEffectSettings or nothing renders. Set the asset on LunaUIManager's Effect Settings field; without it the filter pipeline stays uninitialised and no effects draw. Create one via Assets > Create > CupkekGames > Luna UI > UI Effect Settings and point it at the Essentials Effects/LunaFilter.asset; full detail in Setup.

From there, authoring is just classes in UXML:

If you have LunaUIManager in the scene with Auto Install Fx enabled (the default), every UIView automatically wires its descendants — no extra setup. The first class is always luna-fx; everything else is composable.

Effect catalog

Eight effects, all running through one hand-written HLSL uber shader (Hidden/Luna/UberFilter). Each effect is gated by an _ActiveEffects bitmask uniform — disabled effects branch out at runtime and cost almost nothing.

The default stack always includes Outer + Outline. The other six are lazy-stacked the first time their marker variable resolves on the element — so a card that only uses luna-fx-shadow-md never pays for the Shine or Tile slots.

Predefined classes

Ship with Luna out of the box. Use them as building blocks; combine freely.

Marker

Tier classes — drop shadow / outer halo

Outer effect. Six tier sizes per family.

Glow tiers also bump strength on :hover automatically.

Tier classes — inner overlay (claymorphic depth)

InnerOverlay effect. Six tier sizes.

Body classes — multi-effect bundles

Each body bundles outer + inner + outline overrides for a typical UI shape.

Fill classes — gradient surface

Gradient effect. Each sets --luna-fx-gradient to a CSS gradient string referencing --luna-fx-grad-tone-1/2/3. Always combine with a color binding — the plain yellow color class on a luna-fx element (the .luna-fx.{color} binding) — so the tones resolve.

Color bindings — .luna-fx.{color}

The palette tones the effects pull from — --luna-fx-grad-tone-1/2/3 plus the glow, inner, shine, and flash colors — are routed by color binding classes in the compound form .luna-fx.{color}: a plain palette word that only activates on elements carrying the luna-fx marker.

The yellow here is the same palette word that drives class="btn btn-solid yellow" elsewhere — one color vocabulary across components and effects. Each binding sets the three gradient tones (with hover/active steps for the state tween) plus the inner-overlay, shine, and flash colors from that ramp.

Where the classes come from:

• Shipped in Essentials — Theme/Colors/component-colors.uss defines .luna-fx.{color} blocks for all 32 chromatic ramps: red, scarlet, crimson, ruby, rose, pink, magenta, fuchsia, purple, violet, lavender, indigo, navy, cobalt, blue, azure, sky, cyan, turquoise, teal, mint, jade, emerald, green, forest, lime, yellow, gold, amber, orange, peach, coral. component-colors-neutral.uss adds the slate / neutral / stone versions.
• Re-exportable via the Palette Generator — the web tool's UIEffect_Colors.uss component template regenerates the same routing for your own custom palette.

See Colors for the full palette system and the export round-trip.

Composable modifiers

Flair classes (Essentials theme)

The Essentials sample ships extra opinionated presets in UIEffect_Flair.uss:

• Multi-stop gradients: luna-fx-rainbow, luna-fx-sunset, luna-fx-aurora, luna-fx-holo, luna-fx-candy, luna-fx-orb, luna-fx-spotlight, luna-fx-vignette
• Animated outlines: luna-fx-rainbow-outline, luna-fx-candy-outline, luna-fx-gold-outline, luna-fx-silver-outline, luna-fx-bronze-outline
• Outline patterns: luna-fx-scan, luna-fx-stripes, luna-fx-dots, luna-fx-hearts, luna-fx-stars, luna-fx-dashed-10, luna-fx-dashed-20

These are sample-side; copy what you like into your project's USS.

USS variables

The full --luna-fx-* vocabulary, by effect. Every variable supports var(), :hover / :active / :disabled selectors, and theme tokens. Suffixed variants (-hover, -active, -disabled) on the animatable scalars are picked up by the auto-attached state-tween for smooth transitions.

Outer (drop shadow / halo)

Outline

InnerOverlay (recessed / embossed)

Gradient (surface fill)

Color value formats. Gradient strings accept hex (#rgb, #rrggbb, #rrggbbaa), rgb()/rgba(), and named colors. One deliberate divergence from the CSS spec: an rgb()/rgba() component ≤ 1 is read as a 0–1 float (Unity Color convention), so rgb(1, 1, 1) is white and rgba(1, 0, 0, 0.5) is half-alpha full red — under strict CSS those would be near-black (1 = 1/255). Components above 1 use the normal 0–255 scale. In practice this only changes the reading of values whose components are all ≤ 1; author 0–255 integers or hex if you are pasting from web CSS. This is a documented contract, not a bug.

Shine (animated highlight sweep)

Every shine cycle has three phases — a fast sweep, one full-surface glint, then rest until the next cycle — the "gold button flourish". cycle-time is the seconds between shines. The shipped luna-fx-shine preset class tunes it for gold CTAs (wide soft band, one flourish every 4 s, brief glint). For a continuous crawl instead, set --luna-fx-shine-sweep-time equal to the cycle time and --luna-fx-shine-glint-opacity: 0.

Flash (pulse / breathe)

Tile (texture overlay)

Dissolve

State-aware authoring

Append -hover, -active, or -disabled to any animatable scalar to declare its target state value. The auto-attached UIEffectStateTween interpolates smoothly:

Pseudo-class selectors (:hover, :active, :enabled, :disabled) work too and snap immediately. luna-fx-btn uses both: suffix vars for the tween, pseudo-class forwarders so non-tweened renderers still snap correctly.

Setup

Auto-install (default)

In LunaUIManager Inspector:

• Auto Install Fx — true by default. Every UIView automatically calls UIEffectPanelHook.Install(view.ParentElement, "luna-fx") on attach, so every descendant carrying the marker class at that moment gets wired up. Luna's own dynamic containers — GridView slots, LunaListView rows, Carousel pages — rescan the children they create, so their fx hosts need no code either.

Manual install

For raw PanelRenderer use (no UIView), or to gate which subtrees are eligible, install inside the renderer's reload callback — PanelRenderer delivers its visual tree asynchronously:

Install is idempotent on the same root, so re-running it on every reload is safe. It also cleans up after itself: when an installed root detaches from its panel the hook auto-uninstalls, and a one-shot re-attach watcher re-installs the same root if it ever returns to a panel — effects self-recover across panel rebuilds without manual Uninstall bookkeeping.

AttachToPanelEvent does not propagate to ancestors, so the install scan cannot see elements you add to the tree later. A subtree your own code builds after install (a runtime-instantiated template, a code-built row) needs one call: UIEffectPanelHook.Rescan(subtree) (schedules a scan of the subtree for marker elements; idempotent). Luna's containers do this for the children they create. If you toggle the marker class on an element that is already attached, call UIEffectClassDriver.Attach(element) directly.

Without a LunaUIManager, you must also register the effect settings yourself — the filter pipeline stays uninitialised until something calls:

LunaUIManager makes this call automatically in Awake when present; only manager-less setups need it.

UIEffectSettings asset (required)

Create a UIEffectSettings asset (Assets > Create > CupkekGames > Luna UI > UI Effect Settings) and assign the Luna FilterFunctionDefinition asset (the Essentials sample ships one: Effects/LunaFilter.asset, which references the Hidden/Luna/UberFilter shader). Then assign the settings asset to LunaUIManager's Effect Settings field — the manager calls UIEffectSettings.SetInstance in Awake. Without it the filter pipeline is uninitialised and no effects render.

Samples

The Showcase sample ships three Effects scenes:

• Components/Effects/EffectsShowcase.unity — gallery of every preset class on every base shape. Browse this first.
• Components/Effects/EffectsPresets.unity — preset cards isolated for screenshot grids.
• Components/Effects/EffectsPlayground.unity — interactive playground. Toggle effects, scrub uniforms, see the shader uniforms update live.

UIEffect_Flair.uss (Samples~/Essentials/Theme/UIEffect_Flair.uss in the imported Essentials sample) is the source for the multi-stop / animated-outline classes listed above — copy what you like.

How it works

• The luna-fx marker class hooks the element into UIEffectClassDriver. The driver builds a default stack (Outer + Outline, both dormant) and registers CustomStyleResolvedEvent to react to USS changes.
• Tier / body / fill classes are pure parameter bundles — they only write --luna-fx-* variables. They never replace the stack, so every combination composes naturally.
• On every style resolve, LunaEffectUSSOverrides reads the resolved --luna-fx-* values from the element's customStyle and writes them into the shader's MaterialPropertyBlock — overriding whatever the C# stack baked. USS is always the final word.
• InnerOverlay / Shine / Flash / Tile / Dissolve are stacked lazily — only when their marker variable resolves. Elements that never need them stay on the minimal Outer + Outline stack.
• Gradient strings (--luna-fx-gradient, --luna-fx-outline-gradient) are parsed once into a retained template; pseudo-state tone shifts re-resolve var() references without re-parsing.
• The shader is one hand-written HLSL transparent uber shader (Hidden/Luna/UberFilter). Each effect is gated by an _ActiveEffects bitmask uniform — disabled effects branch out at runtime and cost almost nothing.

Opacity & visibility

Luna effects respect the standard UITK visibility properties — opacity, visibility, and display — including ancestor inheritance. A faded parent fades its filtered children's gradients, glows, shadows, shines, and every other decorative pass uniformly with the element's own content.

How Luna handles it

Every frame the filter pass runs, Luna walks the target up its hierarchy and folds the result into a single _LunaElementOpacity shader uniform:

• resolvedStyle.opacity on each ancestor is multiplied together (cumulative).
• Any ancestor with display: none or visibility: hidden collapses the value to 0.

The shader multiplies its final composited output by this uniform. Decorative passes (gradient, outer glow/shadow, shine, flash, tile, etc.) don't read element content — they generate pixels directly — so without this multiply they would render at full intensity even when the element's own content is faded by UITK's pre-multiplied opacity.

The walk happens inside the filter pass's per-frame OnApplySettings callback, so:

• Opacity transitions animate correctly. UITK lerps resolvedStyle.opacity natively; Luna picks up the live value every frame and the shader fades smoothly with the element.
• Display flips are free. When the target or an ancestor goes display: none, the filter pass itself is detached (no SetPass cost). GeometryChangedEvent fires on the toggle back, re-attaches automatically.

Gotcha: UITK's native filter: blur() and filter: drop-shadow() (Unity 6000.5 and earlier)

Fixed upstream in Unity 6000.6. On 6000.6 a natively filtered element fades with its ancestors like any other element (verified on 6000.6.0f1: a grayscale(1) card inside a layer set to opacity: 0.25 faded with the layer). Everything below applies to 6000.5 and earlier only.

opacity on an ancestor doesn't reach UITK-filtered subtrees through the cascade. UITK renders each element with style.filter into an isolated pass, and that pass's output is composited back without ancestor opacity propagation. This is UITK behavior, not Luna behavior — Luna's own filter pass works around it via _LunaElementOpacity, but native blur / drop-shadow use Unity's built-in filter pipeline which Luna can't reach.

Symptom: you fade a screen with opacity: 0.1 on a parent, every element fades except one — a stubborn dark rectangle from a blurred backdrop, or a leftover drop-shadow.

Fix: write inline opacity directly on the filtered element, not an ancestor.

Alternative: animate the filter parameter to zero instead of opacity. filter: blur(0px) produces no visible blur. This avoids the isolation entirely.

If you author Luna effects exclusively, you'll never hit this — Luna's pipeline handles ancestor opacity correctly. The gotcha applies only when you mix in UITK's native filter functions.

Imperative C# API (escape hatch)

For dynamic cases that don't fit USS — gameplay-driven effects, pooled VFX overlays, programmatic preview tools — the C# API is unchanged:

Most projects don't need this — the USS path covers static styling, hover/active states, theme swaps, and palette tinting. Reach for C# only when the effect parameters genuinely need to live in code.

Performance

• Default stack is two effects (Outer + Outline). The other six lazy-attach only when their USS marker resolves — pay only for what you author.
• The --luna-fx-* resolved set is cached per element and rebuilt on CustomStyleResolvedEvent. The per-frame write path iterates only the resolved bindings, not the full vocabulary.
• Effects are gated by the _ActiveEffects bitmask uniform in the uber shader. Disabled effects branch out at runtime and cost almost nothing.
• The state-tween manipulator self-discovers suffix vars on first style-resolve and stays dormant if none are present.
• Animated effects (shine sweeps, flash pulses, state tweens, per-frame repaints via UIEffectElement.StartAnimation) are driven by one global Luna ticker at a fixed ~16ms cadence — a single scheduled task fans out to every animated element instead of one scheduler per element. Per-element interval parameters (e.g. StartAnimation(intervalMs)) are retained for API compatibility but ignored.
• Effects self-recover after panel detach/re-attach: an installed root that leaves its panel auto-uninstalls its hook and re-installs when the same root re-attaches — no per-screen lifecycle code needed.
• For purely static decorations (fixed cards, panels, frames), see UI Effect Baking — the editor tool pre-renders the stack to a 9-slice PNG so the element renders as a regular sprite with a single batch.

Troubleshooting

See also

• UI Effect Baking — pre-render static stacks to 9-slice PNGs for one-draw-call cards and panels.
• Colors — the palette system behind the .luna-fx.{color} bindings.
• Transition Animation — the motion layer to pair with these looks: 53 presets + a fluent builder.

---

All eight effects ship with Luna — get it on the Asset Store.