Luna UI Documentation

Luna UI's Text Effects system allows you to add dynamic animations to text using rich text tags. The system provides 12 different animation effects that can be applied to text using simple XML-like syntax.

Text Effects

Features

12 Different Effects: Pendulum, Dangle, Fade, Rainbow, Rotate, Bounce, Slide, Swing, Wave, Increase Size, Shake, and Wiggle
Rich Text Tags: Simple XML-like syntax for easy integration
Automatic Integration: Works seamlessly with DialogueController
Standalone Component: Can be used independently with TextEffectComponent
Effect Nesting: Combine multiple effects for complex animations
Text Reveal Support: Effects coordinate with text reveal animations

Quick Start

Basic Syntax

All text effects use the same basic syntax:

xml

<effectname parameter="value">Your text here</effectname>

Example:

xml

<wave startoffset="-10" endoffset="10">Wavy Text</wave>

Simple Example

xml

Hello <rainb durationperchar="1.0">World</rainb>!

This creates a rainbow effect on the word "World" while keeping "Hello" and "!" normal.

Usage with Dialogue System

The Dialogue System automatically supports text effects. Simply include effect tags in your dialogue text, and they will be parsed and applied automatically.

Setup

No additional setup is required! The DialogueController automatically:

Parses effect tags from dialogue text
Initializes text effects
Coordinates effects with text reveal
Removes tags from displayed text

Example with Ink Dialogue

ink

Character: This text has a <pend startangle="-20" endangle="20">pendulum</pend> effect!
Character: Watch this <rainb durationperchar="1.0">rainbow</rainb> text cycle through colors!

Example with Code

csharp

string dialogueText = "This text will <shake maxxamplitude=\"5\" maxyamplitude=\"5\">shake</shake>!";
dialogueController.Continue(dialogueText, false);

Usage with TextEffectComponent

To use text effects on static labels (not in dialogue), use the TextEffectComponent.

Setup Steps

Add TextEffectComponent to your GameObject
- Select the GameObject with your UIDocument
- Add Component → TextEffectComponent
Configure the Component
- UIDocument: Reference to your UIDocument (auto-detected if on same GameObject)
- Label Selector: Configure which labels should have effects applied
  - Type: Select "Name" to target by name, "Class" for USS classes, etc.
  - Value: Enter the name/class/value to match
Add Effect Tags to Your Label Text
- Set the label's text property with effect tags
- Effects are applied automatically when the component starts

Example in Code

csharp

using UnityEngine;
using UnityEngine.UIElements;
using CupkekGames.Luna.TextAnimation;

public class MyUI : MonoBehaviour
{
    private UIDocument uiDocument;
    private TextEffectComponent effectComponent;

    void Start()
    {
        uiDocument = GetComponent<UIDocument>();
        effectComponent = GetComponent<TextEffectComponent>();

        // Set text with effects
        Label titleLabel = uiDocument.rootVisualElement.Q<Label>("TitleLabel");
        titleLabel.text = "Welcome to <rainb durationperchar=\"1.0\">Luna UI</rainb>!";

        // Apply effects (or they'll be applied automatically in Start)
        effectComponent.ApplyEffects();
    }
}

Dynamic Text Updates

When you change a label's text at runtime, call ApplyEffects() to re-apply effects:

csharp

// Update text
myLabel.text = "New <wave>text</wave> with effects";

// Re-apply effects
textEffectComponent.ApplyEffects();

Available Effects

Pendulum (`<pend>`)

Creates a swinging pendulum motion where text rotates around its top center point.

Parameter	Default	Description
startangle	-15	Starting rotation angle in degrees
endangle	15	Ending rotation angle in degrees
damping	0.05	Damping factor (0 = no damping)
centeroffsetx	0	Horizontal offset of rotation center
centeroffsety	-40	Vertical offset of rotation center
durationperchar	0.5	Duration of animation per character
animationtype	pingpong	Animation type

xml

<pend startangle="-20" endangle="20">Swinging Text</pend>

Dangle (`<dangle>`)

Creates a spring-like dangle motion where text oscillates vertically with gravity effects.

Parameter	Default	Description
startoffset	-10	Starting vertical offset in pixels
endoffset	10	Ending vertical offset in pixels
speed	1.0	Speed of oscillation
gravity	9.8	Gravity effect strength
damping	0.9	Damping factor (0-1)
durationperchar	0.5	Duration per character
timebetweenchars	0.05	Delay between characters

xml

<dangle startoffset="-12" endoffset="12">Dangling Text</dangle>

Fade (`<fade>`)

Smoothly fades text opacity between minimum and maximum values.

Parameter	Default	Description
startalpha	0.0	Starting alpha (0-1)
endalpha	1.0	Ending alpha (0-1)
durationperchar	0.5	Duration of fade cycle
timebetweenchars	0.05	Delay between characters
animationtype	pingpong	Animation type

xml

<fade startalpha="0.3" endalpha="1.0">Fading Text</fade>

Rainbow (`<rainb>`)

Cycles text through colors with multiple color modes.

Parameter	Default	Description
durationperchar	0.5	Duration of color cycle
colormode	0	0=Rainbow, 1=Gradient, 2=Two Colors, 3=Alpha Only
speed	1.0	Speed of color cycling (Rainbow mode)
saturation	1.0	Color saturation 0-1
brightness	1.0	Color brightness 0-1
color1-4	-	Custom colors for Gradient/TwoColors modes
startalpha	0	Starting alpha for Alpha mode
endalpha	1	Ending alpha for Alpha mode

Rainbow Mode:

xml

<rainb durationperchar="1.0">Rainbow Text</rainb>

Custom Gradient:

xml

<rainb colormode="1" color1="FF0000" color2="00FF00" color3="0000FF">Gradient</rainb>

Two Colors:

xml

<rainb colormode="2" color1="red" color2="blue">Two Colors</rainb>

Rotate (`<rot>`)

Rotates text around its center point.

Parameter	Default	Description
startangle	-15	Starting rotation angle
endangle	15	Ending rotation angle
loop	0	If > 0.5, continuous rotation
centeroffsetx	0	Horizontal offset of center
centeroffsety	0	Vertical offset of center
durationperchar	0.5	Duration per character
animationtype	pingpong	Animation type

xml

<rot startangle="0" endangle="360" animationtype="loop" loop="1" durationperchar="2.0">Rotating</rot>

Bounce (`<bounce>`)

Creates an upward bouncing motion with decay.

Parameter	Default	Description
startoffset	0	Starting vertical offset
endoffset	-10	Ending vertical offset (negative = up)
decay	0.8	Decay factor (0-1)
speed	2.0	Bounce frequency
durationperchar	0.5	Duration per character
timebetweenchars	0.05	Delay between characters

xml

<bounce startoffset="0" endoffset="-10" decay="0">Bouncing Text</bounce>

Slide (`<slideh>`)

Slides text horizontally or vertically.

Parameter	Default	Description
startoffsetx	-10	Starting horizontal offset
endoffsetx	0	Ending horizontal offset
startoffsety	0	Starting vertical offset
endoffsety	0	Ending vertical offset
durationperchar	0.5	Duration per character
timebetweenchars	0.05	Delay between characters
animationtype	pingpong	Animation type

xml

<slideh startoffsetx="-10">Sliding Text</slideh>

Swing (`<swing>`)

Creates an arc-like swinging motion combining horizontal and vertical movement.

Parameter	Default	Description
startangle	-15	Starting swing angle
endangle	15	Ending swing angle
amplitude	20.0	Maximum swing distance
durationperchar	0.5	Duration per character
timebetweenchars	0.05	Delay between characters
animationtype	pingpong	Animation type

xml

<swing startangle="-15" endangle="15">Swinging Text</swing>

Wave (`<wave>`)

Creates a smooth sine wave motion that propagates through the text.

Parameter	Default	Description
startoffset	-10	Starting vertical offset
endoffset	10	Ending vertical offset
frequency	1.0	Wave frequency
durationperchar	0.5	Duration per character
timebetweenchars	0.05	Delay between characters
animationtype	pingpong	Animation type

xml

<wave startoffset="-10" endoffset="10" frequency="1.5">Wavy Text</wave>

Increase Size (`<incr>`)

Pulsates text size between minimum and maximum scale values.

Parameter	Default	Description
startscale	0.8	Starting scale (1.0 = normal)
endscale	1.2	Ending scale
durationperchar	0.5	Duration per character
timebetweenchars	0.05	Delay between characters
animationtype	pingpong	Animation type

xml

<incr startscale="0.8" endscale="1.2">Pulsing Text</incr>

Shake (`<shake>`)

Applies random shaking motion to each character independently.

Parameter	Default	Description
maxxamplitude	5.0	Maximum horizontal shake
maxyamplitude	5.0	Maximum vertical shake
minwait	0.1	Minimum time between updates
maxwait	0.15	Maximum time between updates
speed	10.0	Frequency of updates

xml

<shake maxxamplitude="5" maxyamplitude="5">Shaking Text</shake>

Wiggle (`<wiggle>`)

Creates small, smooth wiggling motions using sine and cosine waves.

Parameter	Default	Description
startoffsetx	-3	Starting horizontal offset
startoffsety	-2	Starting vertical offset
endoffsetx	3	Ending horizontal offset
endoffsety	2	Ending vertical offset
frequency	2.0	Wiggle frequency
durationperchar	0.5	Duration per character
timebetweenchars	0.05	Delay between characters
animationtype	pingpong	Animation type

xml

<wiggle startoffsetx="-3" startoffsety="-2" endoffsetx="3" endoffsety="2">Wiggling Text</wiggle>

Common Parameters

Timing Parameters

Parameter	Default	Description
durationperchar	0.5	Duration of animation per character in seconds
timebetweenchars	0.05	Delay between characters starting animation
nodelayforchars	false	If true, all characters start animating simultaneously

Animation Type

Value	Description
pingpong / 0	Oscillates back and forth (default)
loop / 1	Loops continuously in one direction
onetime / 2	Plays once from start to end
loopfixedduration / 3	Loops with fixed duration

Combining Effects

You can nest effects to combine multiple animations on the same text.

Basic Nesting

xml

<wave durationperchar="0.67"><rainb durationperchar="1.0">Wavy Rainbow</rainb></wave>

Multiple Nested Effects

xml

<shake maxxamplitude="3" maxyamplitude="3">
  <wave durationperchar="0.67">Shaky Wavy</wave>
</shake>

Complex Combinations

Animated Logo:

xml

<wave durationperchar="0.5">
  <rainb colormode="1" color1="FF0000" color2="00FF00" color3="0000FF">My Game</rainb>
</wave>

Dramatic Text:

xml

<shake maxxamplitude="4" maxyamplitude="4">
  <incr startscale="0.7" endscale="1.3">WARNING!</incr>
</shake>

Note: Inner effects are applied first, then outer effects. Be careful with conflicting transformations and performance with many nested effects.

Example Use Cases

Dialogue

csharp

// Emotional speech
dialogueController.Continue("I'm <shake maxxamplitude=\"3\" maxyamplitude=\"3\">angry</shake>!", false);
dialogueController.Continue("This is <rainb durationperchar=\"1.0\">amazing</rainb>!", false);
dialogueController.Continue("I'm <bounce endoffset=\"-10\">excited</bounce>!", false);

UI Labels

Attention-Grabbing Button:

xml

<incr startscale="0.9" endscale="1.1">Click Me!</incr>

Status Indicator:

xml

Status: <fade startalpha="0.3" endalpha="1.0">Online</fade>

Troubleshooting

Effects Not Appearing

Check that effect tags are properly closed: <effect>text</effect>
Verify parameter names are correct (case-insensitive)
For TextEffectComponent: Ensure the component targets the correct label
Call ApplyEffects() after changing text at runtime

Effects Too Fast/Slow

Adjust durationperchar - lower = faster, higher = slower
Adjust timebetweenchars for wave propagation speed

Performance Issues

Limit the number of nested effects
Use simpler effects (fade, rainbow) instead of complex ones (shake, wiggle)
Avoid applying effects to very long text strings

Text Effects

Features

Quick Start

Basic Syntax

Simple Example

Usage with Dialogue System

Setup

Example with Ink Dialogue

Example with Code

Usage with TextEffectComponent

Setup Steps

Example in Code

Dynamic Text Updates

Available Effects

Pendulum (<pend>)

Dangle (<dangle>)

Fade (<fade>)

Rainbow (<rainb>)

Rotate (<rot>)

Bounce (<bounce>)

Slide (<slideh>)

Swing (<swing>)

Wave (<wave>)

Increase Size (<incr>)

Shake (<shake>)

Wiggle (<wiggle>)

Common Parameters

Timing Parameters

Animation Type

Combining Effects

Basic Nesting

Multiple Nested Effects

Complex Combinations

Example Use Cases

Dialogue

UI Labels

Troubleshooting

Effects Not Appearing

Effects Too Fast/Slow

Performance Issues

Pendulum (`<pend>`)

Dangle (`<dangle>`)

Fade (`<fade>`)

Rainbow (`<rainb>`)

Rotate (`<rot>`)

Bounce (`<bounce>`)

Slide (`<slideh>`)

Swing (`<swing>`)

Wave (`<wave>`)

Increase Size (`<incr>`)

Shake (`<shake>`)

Wiggle (`<wiggle>`)