Tokens

• Colors
• Text Speed
• Special Effects
  • Ease
  • Hang
  • Jump
  • Shake
  • Sick
  • Slide
  • Wave
  • Wind
  • Blink
  • Fade
  • Gradient
  • Rainbow
• Default Tokens
• Runtime Events
• Variables
• If Conditionals
• Others
• Complete list
• Combining Effects
• Custom Effects

Introduction

Tokens give you the power to control the text the way you want, and they're really easy to implement. All you need is to include them in your text string, like this:

String text="{COLOR=RED}Hello, {WAIT}{SLOW}world!";
    TypingLabel label=new TypingLabel(text,skin);

Arguments: Note that some tokens make use of one or more arguments, however they are all optional. See each section to see their default values.

---

Tokens

Colors

Color tokens change the text color from that point forward. Use {CLEARCOLOR} to reset the text color, white by default.

Usage: {COLOR=name} or {COLOR=#hexcode}

• name: Sets the color of the text to the given name. See accepted values.
• hexcode: Sets the color of the text to the given hex code. Accepted formats are #RRGGBBAA, where AA is optional and defaults to 0xFF.

Note: Color tokens are just another way of using libGDX's Color Markup Language, and can be replaced by regular markup tokens if you want.

Text Speed

Speed tokens change the text speed to a certain factor, or restores the normal speed if no arguments are used.

Usage: {SPEED=factor}

• distance: Changes the speed of the text to the given factor, relative to the default speed. e.g. 2 makes the text go twice as fast, while 0.1 makes it super slow.

Aliases:

• {SLOWER}: Equivalent to {SPEED=0.5}.
• {SLOW}: Equivalent to {SPEED=0.66}.
• {NORMAL}: Restores the text's default speed. Equivalent to {SPEED=1} or {SPEED}.
• {FAST}: Equivalent to {SPEED=2}.
• {FASTER}: Equivalent to {SPEED=4}.

Special Effects

Make words shake, jump, walk in a sine wave. Perfect to give emphasis to certain words or phrases. All effect tokens allow you to use arguments to control their behavior. Note that all arguments are 1 by default, except for duration which is -1 to indicate an infinite effect.

EASE

Moves the text vertically easing it into the final position. Doesn't repeat itself. Use {ENDEASE} to end this effect.

Usage: {EASE=distance;intensity;elastic}, or just {EASE}

• distance: How far the letters should move from their original position.
• intensity: How fast the letters should move.
• elastic: Whether or not an elastic interpolation should be used. Can be 0, 1, yes, no, true, false.

HANG

Hangs the text in midair and suddenly drops it. Doesn't repeat itself. Use {ENDHANG} to end this effect.

Usage: {HANG=distance;intensity}, or just {HANG}

• distance: How high the letters should be hanged.
• intensity: How fast the letters should move. Higher values stay in midair for a longer time.

JUMP

Makes the text jump and falls back to the original position, as if there was gravity. Use {ENDJUMP} to end this effect.

Usage: {JUMP=distance;frequency;intensity;duration}, or just {JUMP}

• distance: How high the letters should jump. By default they jump a little higher than the line height.
• frequency: How frequently the wave pattern repeats. Longer values mean each letter will jump on their own times, almost like a domino effect, while shorter values will give the impression words are jumping as a whole.
• intensity: How fast the letters should move. Lower values give an impression of low gravity.
• duration: -1 by default (infinite). Determines how long the effect should last after it begins, in seconds.

SHAKE

Shakes the text in a random pattern. Use {ENDSHAKE} to end this effect.

Usage: {SHAKE=distance;intensity;duration}, or just {SHAKE}

• distance: How far the letters should move.
• intensity: How fast the letters should move. Higher values will make them completely random, while lower values will make the movement smooth.
• duration: -1 by default (infinite). Determines how long the effect should last after it begins, in seconds.

SICK

Drips the text in a random pattern, as if the speaker is sick. Use {ENDSICK} to end this effect.

Usage: {SICK=distance;intensity;duration}, or just {SICK}

• distance: How far the letters should move.
• intensity: How fast the letters should move. Higher values will make them completely random, while lower values will make the movement smooth.
• duration: -1 by default (infinite). Determines how long the effect should last after it begins, in seconds.

SLIDE

Moves the text horizontally easing it into the final position. Doesn't repeat itself. Use {ENDSLIDE} to end this effect.

Usage: {SLIDE=distance;intensity;elastic}, or just {SLIDE}

• distance: How far the letters should move from their original position.
• intensity: How fast the letters should move.
• elastic: Whether or not an elastic interpolation should be used. Can be 0, 1, yes, no, true, false.

WAVE

Moves the text vertically in a sine wave pattern. Use {ENDWAVE} to end this effect.

Usage: {WAVE=distance;frequency;intensity;duration}, or just {WAVE}

• distance: How far the letters should move from their original position.
• frequency: How frequently the wave pattern repeats. Longer values mean each letter will move on their own times, almost like a domino effect, while shorter values will give the impression words are moving as a whole.
• intensity: How fast the letters should move.
• duration: -1 by default (infinite). Determines how long the effect should last after it begins, in seconds.

WIND

Simulates a wind effect in the text, as if it was written in a flag. Use {ENDWIND} to end this effect.

Usage: {WIND=distanceX;distanceY;spacing;intensity;duration}, or just {WIND}

• distanceX: How far the letters should move from their original position in the X axis.
• distance: How far the letters should move from their original position in the Y axis.
• spacing: How much space there should be between wind waves. Longer values mean each letter will move on their own times, almost like a domino effect, while shorter values will give the impression words are moving as a whole.
• intensity: How strong the wind should be.
• duration: -1 by default (infinite). Determines how long the effect should last after it begins, in seconds.

BLINK

Blinks the entire text in two different colors at once, without interpolation. Use {ENDBLINK} to end this effect.

Usage: {BLINK=color1;color2;frequency;threshold}, or just {BLINK}

• color1: First color of this effect. Can either be a named color or a hexadecimal value.
• color2: Second color of this effect. Can either be a named color or a hexadecimal value.
• frequency: How frequently the color pattern should move through the text.
• threshold: Interpolation point to switch colors. Defaults to 0.5.

FADE

Fades the text's color from between colors or alphas. Doesn't repeat itself. Use {ENDFADE} to end this effect.

Usage: {FADE=color1;color2;duration}, or just {FADE}

• colorOrAlpha1: First color or alpha of this effect.*
• colorOrAlpha2: Second color or alpha of this effect.*
• duration: Duration of the fade effect, in seconds.

• Note: The colorOrAlpha variables can either be a named color, a hexadecimal value, or just a transparency value from 0 to 1, which will respect the original color of the glyph.

GRADIENT

Tints the text in a gradient pattern. Use {ENDGRADIENT} to end this effect.

Usage: {GRADIENT=color1;color2;distance;frequency}, or just {GRADIENT}

• color1: First color of this effect. Can either be a named color or a hexadecimal value.
• color2: Second color of this effect. Can either be a named color or a hexadecimal value.
• distance: How extensive the rainbow effect should be.
• frequency: How frequently the color pattern should move through the text.

RAINBOW

Tints the text in a rainbow pattern. Use {ENDRAINBOW} to end this effect.

Usage: {RAINBOW=distance;frequency;saturation;brightness}, or just {RAINBOW}

• distance: How extensive the rainbow effect should be.
• frequency: How frequently the color pattern should move through the text.
• saturation: Color saturation, defaults to 1.
• brightness: Color brightness, defaults to 1.

---

Default Tokens

It is possible to configure an effect to be used throughout the entire text without the need of typing it each time. Very useful to create constant effects that are applied all the time:

    String defaultTokens="{EASE=1;1}{WAVE=1;1;1;1}";
    myTypingLabel.setDefaultToken(defaultTokens);

Now all your text will have these effect tokens, even after {RESET} calls.

---

Runtime Events

You can use event tokens to be notified when that exact part of the text is processed. Really handy if you want to spawn fire particles or play a sound when a certain word appears.

Usage: {EVENT=name}

• name: Name of the event that should be passed at runtime. If none, the value will be null.

See more at the Examples page.

Variables

Variable tokens are replaced by any values you assign at runtime. e.g. you can create a text Hello {VAR=name}! and set the variable value with label.setVariable("name", "Mr. Bob").

Usage: {VAR=name}

• name: Name of the variable that should be replaced at runtime.

See more at the Examples page.

If Conditionals

Variables on steroids! This IF token is replaced with the values provided in its parameters themselves according to its variable's value, which is compared with the paramteer keys.

An excellent usage of If Conditionals is gender pronouns in I18N files.

Usage: {IF=name;key1=value1;key2=value2;key3=value3;defaultValue}

• name: Name of the variable to be checked against the parameter keys.
• keys: If the variable's value is equal to this key...
• values: Then this value will be used to replace the token.
• defaultValue: Or else, an optional default value (without a key) is used instead.

See more at the Examples page.

Others

WAIT

Waits a few seconds before showing the rest of the text. The default value is 0.25.

Usage: {WAIT=seconds} or {WAIT}

RESET

Resets the text to the default speed and color, and end all active effects.

Usage: {RESET}

---

Complete List

Token	Description
{WAIT}	Pauses the text for the specified amount of seconds, or 250 milliseconds by default.
{SPEED}	Changes the speed of the text to the given factor, relative to the default speed.
{SLOWER}	Equivalent to {SPEED=0.5}.
{SLOW}	Equivalent to {SPEED=0.66}.
{NORMAL}	Restores the text's default speed. Equivalent to {SPEED=1} or {SPEED}.
{FAST}	Equivalent to {SPEED=2}.
{FASTER}	Equivalent to {SPEED=4}.
{COLOR}	Sets the color of the text to the given name or hexadecimal value (RRGGBB or RRGGBBAA).
{CLEARCOLOR}	Sets the color of the text to the Clear Color value, which can be configured either globally or per label instance. Defaults to white.
{VAR}	Replaces the token with the value assigned to the variable name via label.setVariable(key, value).
{EVENT}	Fires an event with the same name that can be caught with a TypingListener.
{EASE}	Moves the text vertically easing it into the final position.
{ENDEASE}	Ends the ease effect.
{HANG}	Hangs the text in midair and suddenly drops it.
{ENDHANG}	Ends the hang effect.
{JUMP}	Makes the text jump and fall back to the original position, as if there was gravity.
{ENDJUMP}	Ends the jump effect.
{SHAKE}	Shakes the text in a random pattern.
{ENDSHAKE}	Ends the shake effect.
{SICK}	Drips the text in a random pattern, as if the speaker is sick.
{ENDSICK}	Ends the sick effect.
{SLIDE}	Moves the text horizontally easing it into the final position.
{ENDSLIDE}	Ends the slide effect.
{WAVE}	Moves the text vertically in a sine wave pattern.
{ENDWAVE}	Ends the wave effect.
{WIND}	Simulates a wind effect in the text, as if it was written in a flag.
{ENDWIND}	Ends the wind effect.
{BLINK}	Blinks the entire text in two different colors at once, without interpolation.
{ENDBLINK}	Ends the blink effect.
{FADE}	Fades the text's color from between colors or alphas. Doesn't repeat itself.
{ENDFADE}	Ends the fade effect.
{GRADIENT}	Tints the text in a gradient pattern.
{ENDGRADIENT}	Ends the gradient effect.
{RAINBOW}	Tints the text in a rainbow pattern.
{ENDRAINBOW}	Ends the rainbow effect.
{RESET}	Resets the text to the default speed and color, and end all active effects.

---

Combining Effects

Combining tokens is very simple, all you have to do is use more than one per text segment:

new TypingLabel("{EASE}{WAVE}{GRADIENT=#66D9E8;#9C27B0}Hello world{ENDGRADIENT}{ENDWAVE}{ENDEASE}",skin);

However, that can easily lead to a string that's very hard to read and maintain. It's also difficult to modify effect combinations if you want to use the same set of effects in different places. The simplest way to solve this problem is by replacing your effects with global variables:

// Register your global variables when your game starts
TypingConfig.GLOBAL_VARS.put("NEON","{EASE}{WAVE}{GRADIENT=#66D9E8;#9C27B0}");
    TypingConfig.GLOBAL_VARS.put("ENDNEON","{ENDGRADIENT}{ENDWAVE}{ENDEASE}");

// Create your label using variables
    new TypingLabel("{VAR=NEON}Hello world{VAR=ENDNEON}",skin);

This way your strings become much easier to read, and all effects can be changed at the same time in one line.

Custom Effects

It's very simple to extend TypingLabel and include your own effects! All you have to do is create a class and register it. This is how you do it:

1. Create a class that extends the Effect class.
2. Create a constructor that takes two arguments: TypingLabel and String[] for parameters.
3. Override the method onApply and modify the glyph as you want.
4. Register your token with TypingConfig.registerEffect.

Example

Lets create an effect that applies random movement to letters. Our effect has one optional parameter, distance, which controls how much the glyphs should move.

public class RandomEffect extends Effect {
    private static final float DEFAULT_DISTANCE = 0.15f;
    private float distance = 1; // How much of their height they should move

    public EaseEffect(TypingLabel label, String[] params) {
        super(label);

        // Distance
        if(params.length > 0) {
            this.distance = paramAsFloat(params[0], 1);
        }
    }

    @Override
    protected void onApply(TypingGlyph glyph, int localIndex, float delta) {
        // Calculate offset
        float offsetFactor = MathUtils.random() * DEFAULT_DISTANCE * distance;
        float offsetY = getLineHeight() * offsetFactor;

        // Apply changes
        glyph.yoffset += y;
    }
}

Once our class is created, all we have to do is register it:

public class MyGame implements ApplicationListener {
    public void create() {
        TypingConfig.registerEffect("RANDOM", "ENDRANDOM", RandomEffect.class);
    }
}

That's it! Now TypingLabel will understand the RANDOM and ENDRANDOM tokens, and pass the parameters to our class, just like the effects bundled with the library.

The final step is sharing your awesome effects with the world by submitting a Pull Request! It's easy to do and everyone will love it! ❤️