Animating Texts in Kelp

What are TextAnimations?

A TextAnimation basically is a predefined algorithm taking a string and returning a list of many different strings, which - if played one by one - make up an animation.

If we want to create an animation that builds up a text char by char, we would have something like this:

Input:
Hello!

Animation:
H
He
Hel
Hell
Hello
Hello!

This way we can automate the animation of sidebar and inventory titles for example without having to type the animations manually, which also allows us to animate dynamic values such as player names.

How to use TextAnimations

You can create a new TextAnimation instance by using the static factory of the animation type you prefer. A detailed list with all default animations can be found below.

BuildingTextAnimation textAnimation = BuildingTextAnimation.create();

The rest of the setup basically depends on the animation type you chose. In most cases, you have to pass the text you want to animate and you can optionally configure some parameters. You should look at the documentation of the corresponding animation here. Here is an example of how building a text animation could look like:

BuildingTextAnimation.create()
  .text("§6§lWELCOME ON THE SERVER!")
  .ignoreSpaces();

It can then be used in sidebars for example.

If you need to retrieve the final animation of an animation, you can call the states() method, which is inherited by the TextAnimation interface and therefore available in all text animations. The states are not cached in most animations as that might flood the RAM if you store many of them, which is why states() always recalculates it, so be careful if the algorithm contains performance-heavy operations.

textAnimation.states();

Overview of default TextAnimations

Name	Description	Example
BuildingTextAnimation	Builds up the given text char by char. H, He, Hel, Hell, Hello	BuildingTextAnimation.create().text("§6§lWELCOME ON THE SERVER!") .ignoreSpaces();
CustomTextAnimation	Allows to manually write a text animation without a pre-defined algorithm. This is generally not recommened, but might be useful if you only need your animation once or it is too complicated to write an algorithm for it.	CustomTextAnimation.create().setStates("§aHallo", "§2Hallo2", ...);
StaticTextAnimation	Does not animate the text, but return only a single state, which makes the text static. This is mainly used for testing purposes.	StaticTextAnimation.create().text("Static Text");

Creating your own TextAnimation

If you cannot find an animation from the list above that fits your personal taste, you can always create your own text animations. For that you have to create a new class implementing the TextAnimation interface, which provides the states method needed for every animation:

public class TestAnimation implements TextAnimation {
  
  @Override
  public List<String> states() {
    return null;
  }
  
}

From then on it really depends on your animation which methods you want to add, but most times you might want to get a text that should be animated and create a static factory method to create new instances easily. Your class may look something like this:

public class TestAnimation implements TextAnimation {
  
  private String text;
  
  public static TestAnimation create() {
    // optionally inject some dependencies here
    return new TestAnimation();
  }
  
  public TestAnimation text(String text) {
    this.text = text;
    return this;
  }

  @Override
  public List<String> states() {
    List<String> output = Lists.newArrayList();
    
    // do your calculations here
    
    return output;
  }

}

That's it. Creating your own animations can be that simple. If you find your animation to be universal and beneficial to use for others, feel free to create a pull request with it.