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

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 Shader Graph uber shader. Each is keyword-toggled; disabled effects compile out and cost 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 (e.g. luna-fx-yellow) so the tones resolve.

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)

Shine (animated highlight sweep)

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 all descendants carrying the marker class get wired up. No code needed.

Manual install

For raw UIDocument use (no UIView), or to gate which subtrees are eligible:

The marker class must be present before the element enters the panel for auto-pickup. If you toggle the marker after attach, call UIEffectClassDriver.Attach(element) directly.

UIEffectSettings asset (required)

The system needs to find the LunaUIEffect Shader Graph at runtime. Create a UIEffectSettings asset (Assets > Create > CupkekGames/Luna UI/UIEffectSettings) and assign the shader. Without it, Shader.Find("Shader Graphs/LunaUIEffect") is the fallback, which only works if a material in the build references the shader.

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 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 Unlit transparent uber shader with one boolean keyword per effect. Disabled effects are stripped at compile time — zero runtime cost.

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()

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 independent shader-keyword variants. Disabled effects compile out of the variant the element actually uses.
• The state-tween manipulator self-discovers suffix vars on first style-resolve and stays dormant if none are present.
• 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