[Proposal] Add API to create custom animations

[Silthus]

It would be great if custom animations could be added thru the API. I don't know how the underlying system works but some kind of API that allows to create animations with the following events:

• onStart: called when the crate opening starts
  e.g. when the player right clicks a crate with a key or uses the chest in his inventory.
• onTick/onTickAsync: called every tick as long as the animation runs (configured in the config.yml)
  maybe allow two flavors of animations? AsyncAnimation and Animation?
• onEnd: called last, but before the end animation starts

Some additional API methods in an Animation that would be useful are:

• getDuration() - returns the duration of the animation in ticks
• getState() - returns an enum for the current animation state: NOT_STARTED, START, RUNNING, END, ENDED, ABORTED (when the player logs out).
• getCurrentTick() - returns the current time in the animation as ticks starting at 0
• hasNextReward() - returns true if more rewards are eligible
• nextReward() - gets the next reward that was rolled for the player opening the crate
• getAllRewards() - gets a list of all rewards in this crate opening
• getEligableRewards() - gets a list of all possible rewards in this crate (filtered out rewards without permissions)
• getRemainingRewards() - gets a list of all remaining rewards
• getPlayer() - the player that activated the crate
• end() - ends the animation before the time ran out - ending gives out all rewards to the player
• abort() - aborts the animation returning the key to the player not giving out rewards

Implementing such an API would allow for a wide range of additional animations not just limited to displaying items in a chest. With this we could also create animations using armor stands, particles and so on (like other crate plugins). Opening up such an API also increases the community engagement to create and offer various animation types.

Example

public class MyCustomAnimation extends AbstractAnimation {

  public MyCustomAnimation(AnimationContext context) {
    super(context);
  }

  public void onStart() {
  ...
  }

  public void onTick() {
  ...
  }

  public void onEnd() {
  ...
  }
}

public class MyPlugin extends JavaPlugin {
  
  public void onEnable() {
    
    CratePlugin plugin = (CratePlugin) getPluginManager().getPlugin("CrateReloaded");
    if (plugin != null) {
      plugin.getAnimationRegistar().register("custom-animation", context -> new MyCustomAnimation(context));
    }
  }
}

The AnimationContext

I would use this class to hold all relevant information about the player, the rewards, the loot crate and so on. It should be created per animation with all of the relevant data. Using a seperate context allows you to extend the API in the future without breaking existing implementations.

What do think about this proposal?