Getting Started

Getting Started

This guide will walk you through the process of setting up TimelineFX in your project, from installing dependencies to creating and playing your first animation.

1. Prerequisites: Install ParticleNativeAPI

TimelineFX uses ParticleNativeAPI to handle particle spawning efficiently and across multiple server versions. Before you can use TimelineFX, you must add ParticleNativeAPI to your project.

It is a powerful, high-performance particle library that TimelineFX is built upon.

• GitHub Repository: Fierioziy/ParticleNativeAPI
• Setup Guide: Follow their official installation instructions to add it to your build system.

For a quick Maven setup, add the following to your pom.xml:

<dependency>
    <groupId>com.github.fierioziy.particlenativeapi</groupId>
    <artifactId>ParticleNativeAPI-core</artifactId>
    <version>4.4.0</version>
    <scope>compile</scope>
</dependency>

2. Add TimelineFX to Your Project

Now, add the TimelineFX dependency to your pom.xml file.

<dependency>
    <groupId>com.github.amatheo</groupId>
    <artifactId>timelinefx</artifactId>
    <version>1.0.0</version>
</dependency>

3. Initialize the Animation Engine

The AnimationEngine is the core component that manages and plays all your animations. To ensure proper performance and resource management, you should only create one instance of the engine per plugin and reuse it throughout your code.

A good practice is to initialize it in your main plugin class's onEnable() method.

import com.github.amatheo.timelinefx.core.AnimationEngine;
import org.bukkit.plugin.java.JavaPlugin;

public final class YourPlugin extends JavaPlugin {

    private AnimationEngine animationEngine;

    @Override
    public void onEnable() {
        // Initialize the engine once and store the instance
        this.animationEngine = new AnimationEngine(this);
    }

    public AnimationEngine getAnimationEngine() {
        return animationEngine;
    }
}

By creating a single instance, you ensure that all animations are ticked by a single, centralized scheduler, which is crucial for performance.

4. Your First Animation: A Simple Circle

Now that the setup is complete, let's create a simple animation. We'll make a particle circle that appears and disappears.

Step 1: Build a Timeline

A Timeline defines how properties of an effect change over time. We'll create a timeline for a radius property that goes from 0 to 1 and back to 0.

import com.github.amatheo.timelinefx.animation.timeline.Timeline;
import com.github.amatheo.timelinefx.animation.timeline.TimelineProperty;
import com.github.amatheo.timelinefx.animation.Keyframe;

// Define a property for the circle's radius
TimelineProperty<Double> radiusProperty = TimelineProperty.of("circle.radius");

// Create a timeline that animates this property
Timeline circleTimeline = Timeline.builder()
    .doubles(radiusProperty, track -> track
        .segment(0.0, channel -> channel
            // Animate from radius 0 to 1 over 2 seconds
            .add(Keyframe.of(0.0, 0.0))
            .add(Keyframe.of(2.0, 1.0))
            // Hold radius at 1 for 1 second
            .add(Keyframe.of(3.0, 1.0))
            // Animate back to 0 over 2 seconds
            .add(Keyframe.of(5.0, 0.0))
        )
    )
    .build();

Step 2: Create an EffectClip

An EffectClip connects a Timeline to a visual Effect. It binds the animated properties from the timeline to the fields of the effect instance.

import com.github.amatheo.timelinefx.core.EffectClip;
import com.github.amatheo.timelinefx.effect.impl.CircleEffect;
import com.github.fierioziy.particlenativeapi.api.particle.type.ParticleType;
import org.bukkit.entity.Player;
import java.util.List;

// Assume 'players' is a List<Player> and 'particleType' is a valid ParticleType
List<Player> players = /* ... */;
ParticleType particleType = /* ... */;

EffectClip circleClip = EffectClip.builder()
    .timeline(circleTimeline)
    .layer(layer -> layer
        .effect(new CircleEffect(particleType))
        .bindings(b -> b.bindParameter("radius", radiusProperty))
    )
    .players(players)
    .build();

Step 3: Play the Animation

Finally, use a SequenceBuilder to create a Playable show and give it to the AnimationEngine to run.

import com.github.amatheo.timelinefx.orchestration.SequenceBuilder;
import com.github.amatheo.timelinefx.core.Playable;

Playable show = new SequenceBuilder()
    .then(circleClip)
    .build();

// Get the engine instance from your main plugin class and play the show
yourPlugin.getAnimationEngine().play(show);

And that's it! You've just created a particle circle that animates its radius over 5 seconds for the specified players.

You are now ready to explore the Core Concepts to learn more about what you can do with TimelineFX.