Tokens
- Colors
- Text Speed
- Special Effects
- Default Tokens
- Runtime Events
- Variables
- Others
- Complete list
- Combining Effects
- Custom Effects
Tokens give you the power to control the text the way you want, and they're really easy to add to a TypingLabel. 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.
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.
- Color names should usually not contain punctuation or be the same as a style name, but if they do, you can start a name with
|to ensure the name refers to a color, rather than a style. Color names are case-sensitive, and sometimes a lowercase name refers to a different value than an UPPERCASE name.- You can describe colors by mixing two or more names, such as "blue green", and can also add in descriptors, colors like "lighter dull red orange".
- The main descriptors are "light", "dark", "rich", and "dull". The first two affect lightness, the last two affect saturation.
- There are other descriptors that combine two main descriptors; "bright", "pale", "deep", and "weak". The first two are lighter, the second two are darker, "bright" and "deep" increase saturation, while "pale" and "weak" reduce saturation.
- You can add suffixes to these descriptors: "er", "est", and "most" make the effect stronger, strongest, and... strongmost. Effectively just putting on more letters makes the descriptor more powerful; the actual letters you use don't matter. Note that "pale" becomes "paler", "palest", and "palemost" (or equivalently here, "palemax"), rather than "paleer" and "paleest".
- 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.
There's a difference between plain Color Markup Language and what TextraTypist uses: [] clears the text color to the default, but here also removes any styles currently in use, such as bold or underline.
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}.
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 arguments are usually 1 by default, except for duration which is -1 to indicate an infinite effect, and for colors, which
typically use white for the first color and some other value for any other colors that are needed.
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. Defaults to -2, which starts from below.
- 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.
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.
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.
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.
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.
See also CROWD for a similar effect, which can be combined here.
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.
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.
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.
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. Defaults to fully transparent, or the hex color
#00000000.- frequency: How frequently the color pattern should move through the text.
- threshold: Interpolation point to switch colors. Defaults to 0.5.
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.
*Defaults to fully transparent, or the hex color#00000000.- 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.
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. Defaults to gray,
#888888FF- distance: How wide each span of color should be.
- frequency: How frequently the color pattern should move through the text.
Tints the text in a rainbow pattern. Use {ENDRAINBOW} to end this effect.
Usage:
{RAINBOW=distance;frequency;saturation;lightness}, 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.
- lightness: Color lightness, defaults to 0.5. This uses HSL, so if lightness is 1, the only color is white, and if lightness is 0, the only color is black. 0.5 is where the "boldest" colors are.
Shakes random glyphs and changes their color. Use {ENDJOLT} to end this effect.
Usage:
{JOLT=distance;intensity;duration;likelihood;basecolor;joltcolor}, or just{JOLT}
- distance: How far the glyphs should move, defaults to 1.
- intensity: How fast the glyphs should move, defaults to 1.
- duration: Duration of the jolt effect, in seconds.
- likelihood: How likely it is that each glyph will shake, defaults to .05f; repeatedly checked.
- basecolor: The normal color of text, defaults to white.
- joltcolor: The jolted color of text, defaults to yellow, or
#FFFF88FF.
Moves the text in a spiral pattern inward to their final position.
Usage:
{SPIRAL=distance;intensity;rotations}, or just{SPIRAL}
- distance: How fast the glyphs should move, defaults to 1.
- intensity: How frequently the color pattern should move through the text, defaults to 1.
- rotations: How many times the glyph should circle before stopping, defaults to 1. If positive, this circles counter-clockwise; if negative, this circles clockwise.
Rotates the text then eases it into the final position. This looks something like the text is rolling into place, especially if combined with SLIDE.
Usage:
{SPIN=intensity;rotations;elastic}, or just{SPIN}
- intensity: How fast the glyphs should move, defaults to 1.
- rotations: How many times the glyph should circle before stopping, defaults to 1.
- elastic: True if the glyphs have an elastic movement, defaults to false.
Rotates and moves each glyph slightly back and forth, with each glyph shifting from side to side independently of other glyphs.
Usage:
{CROWD=distance;intensity;duration}, or just{CROWD}
- distance: How many degrees a glyph can rotate, clockwise or counterclockwise, defaults to 15.
- intensity: How fast the glyphs should move, defaults to 1.
- duration: Duration of the crowd effect, in seconds.
Resizes the text from large to the final size. Works well with FADE, so the initially-large glyphs don't fully cover anything.
Usage:
{SHRINK=distance;intensity;elastic}, or just{SHRINK}
- distance: How much of their height they should start expanded by, defaults to 1.
- intensity: How fast the glyphs should move, defaults to 1.
- elastic: True if the glyphs have an elastic movement, defaults to false.
Stretches the text from the baseline to full height.
Usage:
{EMERGE=intensity;elastic}, or just{EMERGE}
- intensity: How fast the glyphs should move, defaults to 0.25 (rather slow).
- elastic: True if the glyphs have an elastic movement, defaults to false.
Resizes text both horizontally and vertically in a rhythmic tempo (two beats, then a gap, then two beats, and so on).
Usage:
{HEARTBEAT=distance;frequency}, or just{HEARTBEAT}
- distance: How much of their height they should move, defaults to 1.
- frequency: How frequently the wave pattern repeats, defaults to 1.
Scales the text horizontally and inverses it to appear to be spinning in place.
Usage:
{CAROUSEL=frequency}, or just{CAROUSEL}
- frequency: How frequently the carousel pattern repeats, defaults to 1.
(No image yet.)
Permanently scales the text by the given amount, either giving one value to scale uniformly, or two values to scale x and y independently. Note that this doesn't round to multiples of 25% like the [%125] style of sizing tag, and you can use arbitrary scales.
Usage:
{SCALE=x,y}, or{SCALE=both}
- x: A multiplier for the width of the text; defaults to 1 if no parameters are given.
- y: A multiplier for the height of the text; defaults to 2 if no parameters are given, or if exactly one parameter is given, then this will be the same as x.
(No image yet.)
Permanently rotates the text by the given amount in degrees.
Usage:
{ROTATE=rotation}, or{ROTATE}
- rotation: A counter-clockwise rotation in degrees; defaults to 90 if no parameters are given.
(No image yet.)
When the mouse is over the affected text, either the glyph under the mouse cursor or all of the affected text will change in a rainbow pattern.
Usage:
{HIGHLIGHT=basecolor,distance;frequency;saturation;lightness;all}, or just{HIGHLIGHT}
- basecolor: The color to use when the rainbow is not taking effect; the default is white.
- distance: How extensive the rainbow effect should be; the default is 1.
- frequency: How frequently the color pattern should move through the text; the default is 1.
- saturation: Color saturation; the default is 1.
- lightness: Color lightness, defaults to 0.5. This uses HSL, so if lightness is 1, the only color is white, and if lightness is 0, the only color is black. 0.5 is where the "boldest" colors are.
- all: If true, all of the text will change to the rainbow if any glyph is under the cursor, or if false, only the glyph under the cursor will change. The default is false (affecting only one glyph).
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.
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.
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.
Waits a few seconds before showing the rest of the text. The default value is 0.25.
Usage:
{WAIT=seconds}or{WAIT}
Resets the text to the default speed and color, and end all active effects.
Usage:
{RESET}
| 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. |
| {JOLT} | Shakes random glyphs and changes their color |
| {ENDJOLT} | Ends the jolt effect. |
| {SPIRAL} | Moves the text in a spiral pattern inward to their final position. |
| {ENDSPIRAL} | Ends the spiral effect. |
| {SPIN} | Rotates the text then eases it into the final position. |
| {ENDSPIN} | Ends the spin effect. |
| {CROWD} | Rotates and moves each glyph slightly back and forth. |
| {ENDCROWD} | Ends the crowd effect. |
| {SHRINK} | Resizes the text from large to the final size. |
| {ENDSHRINK} | Ends the shrink effect. |
| {EMERGE} | Stretches the text from the baseline to full height. |
| {ENDEMERGE} | Ends the emerge effect. |
| {HEARTBEAT} | Resizes text horizontally and vertically with a rhythmic tempo. |
| {ENDHEARTBEAT} | Ends the heartbeat effect. |
| {SQUASH} | Vertically scales down/horizontally scales out the text partially and then returns to normal size. |
| {ENDSQUASH} | Ends the squash effect. |
| {CAROUSEL} | Scales the text horizontally and inverses it to appear to be spinning in place. |
| {ENDCAROUSEL} | Ends the carousel effect. |
| {RESET} | Resets the text to the default speed, style, and color, and ends all active effects. |
There are a few more that are aliases, like {STYLE=BOLD}; STYLE is equivalent to COLOR internally, but more clearly indicates that it changes a text style, instead of a color.
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.
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:
- Create a class that extends the
Effectclass. - Create a constructor that takes two arguments: TypingLabel and String[] for parameters.
- Override the method
onApplyand modify the glyph (or multiple glyphs) as you want. - Register your token with
TypingConfig.registerEffect.
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 RandomEffect(TypingLabel label, String[] params) {
super(label);
// Distance
if(params.length > 0) {
this.distance = paramAsFloat(params[0], 1);
}
}
@Override
protected void onApply(long glyph, int localIndex, int globalIndex, float delta) {
// Calculate offset
float move = label.getLineHeight(globalIndex) * distance * MathUtils.random() * DEFAULT_DISTANCE;
// Apply changes
// `globalIndex << 1` is customary to indicate the x offset or x sizing change for the glyph at `globalIndex`
label.offsets.incr(globalIndex << 1, move);
// `globalIndex << 1 | 1` is customary to indicate the y offset or y sizing change for the glyph at `globalIndex`
label.offsets.incr(globalIndex << 1 | 1, move);
}
}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! ❤️