Core Concepts: The Animation Engine

Core Concepts: The Animation Engine

The AnimationEngine is the heart of TimelineFX. It is a central service responsible for managing the entire lifecycle of all animations, from starting them to updating them every tick until they are complete.

The Role of the Engine

• Ticker: The engine runs an asynchronous Bukkit task (runTaskTimerAsynchronously) that ticks at a consistent rate (every server tick).
• State Management: It keeps track of all active animations (Playable instances), updates their state on each tick, and removes them once they are finished.
• Rendering: It coordinates with a ParticleRenderer (by default, an implementation using ParticleNativeAPI) to efficiently display the particles to players.

A Single Instance is Crucial ⚠️

For performance and consistency, it is critical to create and use only one single instance of AnimationEngine for your entire plugin.

Why?

• Resource Management: Each engine starts its own scheduler. Multiple engines would lead to redundant tasks, consuming unnecessary server resources.
• Centralized Control: A single engine provides one point of control for all animations, simplifying debugging and management.

As shown in the Getting Started guide, the best practice is to initialize it in your plugin's onEnable method and provide access to it via a getter.

// In your main plugin class
private AnimationEngine animationEngine;

@Override
public void onEnable() {
    this.animationEngine = new AnimationEngine(this);
}

public AnimationEngine getAnimationEngine() {
    return this.animationEngine;
}

◄ Back to Core Concepts