Warning

Up to and including version FlectonePulse 1.12.2 the artifact was named core. Starting from 1.13.0 it is named api and holds only the public API of the project

The api artifact holds interfaces, models and constants. The implementation lives inside the plugin itself, so your project builds with api and works with real FlectonePulse objects on the server

With the API you can

listen to messages and change them before a player sees them
add your own MiniMessage tags to chat and any other message
send messages through the FlectonePulse pipeline with all formatting, sounds, range and proxy
read and change player data, punishments and chat settings
turn modules on and off, register your own commands and listeners
sync your own data between the servers of a network

Information

The whole API stands on three things. Dependency injection through Google Guice, events with the @Pulse annotation and modules. Once you know them, you can work with any part of the project

Dependency

The artifact is named net.flectone.pulse:api and lives in Maven Central

<dependency>
    <groupId>net.flectone.pulse</groupId>
    <artifactId>api</artifactId>
    <version>1.13.0</version> <!-- Replace with the current version -->
    <scope>provided</scope>
</dependency>

Snapshot versions need a separate repository

<repositories>
    <repository>
        <id>central-snapshots</id>
        <url>https://central.sonatype.com/repository/maven-snapshots/</url>
    </repository>
</repositories>

<dependency>
    <groupId>net.flectone.pulse</groupId>
    <artifactId>api</artifactId>
    <version>1.13.1-SNAPSHOT</version> <!-- Replace with the current version -->
    <scope>provided</scope>
</dependency>

Attention

Add the API as provided or compileOnly. The FlectonePulse file on the server already carries these classes, and putting them into your jar as well gives you a conflict

Adventure and Cloud come along with the dependency, you do not need to add them separately

Soft dependency

Declare FlectonePulse in your plugin description so that it loads first

# plugin.yml
name: MyPlugin
version: 1.0.0
main: com.example.myplugin.MyPlugin
api-version: '1.13'
softdepend:
  - FlectonePulse

Getting the instance

Everything starts with the static method FlectonePulseAPI.getInstance(). It gives you the FlectonePulse interface, and through it you get any component of the project

import net.flectone.pulse.FlectonePulse;
import net.flectone.pulse.FlectonePulseAPI;
import net.flectone.pulse.logging.FLogger;

FlectonePulse flectonePulse = FlectonePulseAPI.getInstance();

// the injector may not be ready yet, so we check
if (flectonePulse != null && flectonePulse.isReady()) {
    FLogger fLogger = flectonePulse.get(FLogger.class);
    fLogger.info("Hello from FlectonePulse");
}

Attention

getInstance() returns null while FlectonePulse has not loaded, and get() throws InjectorNotInitializedException while the injector is not ready

First example

A Bukkit plugin that appends [Modified] to every message

Create a listener class and mark the method with the @Pulse annotation

Return the changed event through return, because events are immutable

package com.example.myplugin;

import net.flectone.pulse.annotation.Pulse;
import net.flectone.pulse.listener.PulseListener;
import net.flectone.pulse.model.event.Event;
import net.flectone.pulse.model.event.message.MessageFormattingEvent;
import net.flectone.pulse.model.event.message.context.MessageContext;

public class MyPulseListener implements PulseListener {

    @Pulse(priority = Event.Priority.NORMAL)
    public Event onMessageFormatting(MessageFormattingEvent event) {
        MessageContext context = event.context();

        // the context is immutable, so we create a copy with new text
        return event.withContext(context.withMessage(context.message() + " [Modified]"));
    }

}

package com.example.myplugin;

import net.flectone.pulse.FlectonePulse;
import net.flectone.pulse.FlectonePulseAPI;
import net.flectone.pulse.platform.registry.ListenerRegistry;
import org.bukkit.Bukkit;
import org.bukkit.plugin.java.JavaPlugin;

public class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        if (!Bukkit.getPluginManager().isPluginEnabled("FlectonePulse")) return;

        FlectonePulse flectonePulse = FlectonePulseAPI.getInstance();
        if (flectonePulse == null || !flectonePulse.isReady()) return;

        ListenerRegistry listenerRegistry = flectonePulse.get(ListenerRegistry.class);

        // registerPermanent survives /flectonepulse reload
        listenerRegistry.registerPermanent(new MyPulseListener());
    }

}

Warning

FlectonePulse drops every listener on reload. Use registerPermanent() in your plugins, otherwise your listener stops working after /flectonepulse reload

Getting started

Dependency

Soft dependency

Getting the instance

First example

What to read next

On this page