Skip to content

API

Jump to bottom
Loving11ish edited this page Feb 29, 2024 · 10 revisions

API Implementation

Current API Version:

Adding ClansLite To Your Project

To start, you're going to want to add ClansLite as a dependency or soft dependancy to your project. While you could download the jar file and add it as a classpath dependency, we highly recommend using a build system such as Maven or Gradle.

Using Maven

  • Repository
	<repositories>
		<repository>
		    <id>jitpack.io</id>
		    <url>https://jitpack.io</url>
		</repository>
	</repositories>
  • Dependency
	<dependency>
	    <groupId>com.github.CraptiCraft-Development</groupId>
	    <artifactId>ClansLite-API</artifactId>
	    <version>[CURRENT-VERSION]</version>
            <scope>provided</scope>
	</dependency>

Using Gradle

  • build.gralde
	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url 'https://jitpack.io' }
		}
	}
  • Dependency
	dependencies {
	        implementation 'com.github.CraptiCraft-Development:ClansLite-API:[CURRENT-VERSION]'
	}

Getting The API Instance

Once you have added the API to your project, you can start interfacing with it. The first thing you need to do load the instance of the plugin within the onEnable() method in your plugin.

ClansLiteAPI uses the less well known RegisteredServiceProvider system provided by Bukkit for its interfacing with external plugins. The ClansLite plugin itself already registers as the provider for the API, so if the ClansLite plugin is correctly enabled on the server, then the API classes have been successfully registered. Don't forget to add ClansLite as either a soft dependency or a dependency in your plugin.yml too.

  • Here is an example main class for how to get the API instance:
package me.loving11ish.clansliteapitest;

import com.tcoded.folialib.FoliaLib;
import me.loving11ish.clans.api.ClansLiteAPI;
import me.loving11ish.clansliteapitest.commands.Test;
import me.loving11ish.clansliteapitest.listeners.PlayerConnectionListener;
import org.bukkit.Bukkit;
import org.bukkit.event.HandlerList;
import org.bukkit.plugin.RegisteredServiceProvider;
import org.bukkit.plugin.java.JavaPlugin;

public final class ClansLiteAPITest extends JavaPlugin {

    private static ClansLiteAPITest plugin;
    private static FoliaLib foliaLib;

    // ClansLiteAPI - Always null check before using! This must always be null at the start of the plugin!
    private ClansLiteAPI clansLiteAPI = null;

    @Override
    public void onLoad() {
        // Plugin startup logic
        plugin = this;
        foliaLib = new FoliaLib(this);
    }

    @Override
    public void onEnable() {
        // Plugin startup logic

        // Load ClansLiteAPI
        // ClansLiteAPI is a soft-dependency, so we need to check if it's loaded
        // ClansLiteAPI uses a service provider, so we need to check if it's registered by the ClansLite plugin itself
        // If it's not registered, we need to disable the plugins ability to run any ClansLiteAPI code or errors will occur!
        if (!Bukkit.getPluginManager().isPluginEnabled("ClansLite")) {
            getLogger().severe("ClansLite not found!");
            Bukkit.getPluginManager().disablePlugin(this);
            return;
        }

        RegisteredServiceProvider<ClansLiteAPI> rsp = Bukkit.getServicesManager().getRegistration(ClansLiteAPI.class);
        if (rsp != null) {
            clansLiteAPI = rsp.getProvider();
        } else {
            getLogger().severe("ClansLiteAPI not found!");
            Bukkit.getPluginManager().disablePlugin(this);
            return;
        }

        // Register commands
        this.getCommand("test").setExecutor(new Test());

        // Register events
        this.getServer().getPluginManager().registerEvents(new PlayerConnectionListener(), this);

        // Final startup message
        getLogger().info("ClansLiteAPITest has been enabled!");
    }

    @Override
    public void onDisable() {
        // Plugin shutdown logic

        // Unregister listeners
        HandlerList.unregisterAll(this);

        // Final shutdown message
        getLogger().info("ClansLiteAPITest has been disabled!");

        // Nullify plugin
        plugin = null;
        foliaLib = null;
        clansLiteAPI = null;
    }

    public static ClansLiteAPITest getPlugin() {
        return plugin;
    }

    public static FoliaLib getFoliaLib() {
        return foliaLib;
    }

    public ClansLiteAPI getClansLiteAPI() {
        return clansLiteAPI;
    }
}

Using API Methods In Commands

Now that you have the instance of the API available to you, you can now access the available methods to you. In the below example, we make use of a test command to fetch and then display information about a clan back to the player that executed the command:

package me.loving11ish.clansliteapitest.commands;

import com.tcoded.folialib.FoliaLib;
import me.loving11ish.clans.api.ClansLiteAPI;
import me.loving11ish.clans.api.models.Clan;
import me.loving11ish.clans.api.models.ClanPlayer;
import me.loving11ish.clansliteapitest.ClansLiteAPITest;
import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.command.ConsoleCommandSender;
import org.bukkit.entity.Player;
import org.jetbrains.annotations.NotNull;

import java.util.List;

public class Test implements CommandExecutor {

    private final FoliaLib foliaLib = ClansLiteAPITest.getFoliaLib();

    @Override
    public boolean onCommand(@NotNull CommandSender sender, @NotNull Command command, @NotNull String label, @NotNull String[] args) {

        // Check if sender is a player
        if (sender instanceof Player) {
            // Get player and cast to Player object
            Player player = (Player) sender;

            // Check if ClansLiteAPI is loaded
            if (ClansLiteAPITest.getPlugin().getClansLiteAPI() == null) {
                player.sendMessage("ClansLiteAPI not found!");
                return true;
            }

            // Get ClansLiteAPI instance
            ClansLiteAPI clansLiteAPI = ClansLiteAPITest.getPlugin().getClansLiteAPI();

            // Run task at player
            foliaLib.getImpl().runAtEntity(player, (task) -> {
                player.sendMessage("ClansLiteAPI found!");

                // See if player is in a clan, and if so, get the clan
                if (clansLiteAPI.getClanByBukkitPlayer(player) != null) {
                    player.sendMessage("You are in a clan!");
                    Clan clan = clansLiteAPI.getClanByBukkitPlayer(player);
                    player.sendMessage("Your clan: " + clan.getClanFinalName());
                } else {
                    player.sendMessage("You are not in a clan!");
                }

                // Get top clans
                if (clansLiteAPI.getTopClansByClanPointsCache() != null) {
                    List<Clan> topClans = clansLiteAPI.getTopClansByClanPointsCache();
                    for (Clan clan : topClans) {
                        player.sendMessage(clan.getClanFinalName() + " - " + clan.getClanPoints() + " points.");
                    }
                }

                // Get top clan players
                if (clansLiteAPI.getTopClanPlayersByPlayerPointsCache() != null) {
                    List<ClanPlayer> topClanPlayers = clansLiteAPI.getTopClanPlayersByPlayerPointsCache();
                    for (ClanPlayer clanPlayer : topClanPlayers) {
                        player.sendMessage(clanPlayer.getLastPlayerName() + " - " + clanPlayer.getPointBalance() + " points.");
                        player.sendMessage(clanPlayer.getLastPlayerName() + " - " + clanPlayer.getJavaUUID());
                    }
                }


            });

        // If sender is console, let them know they must be a player
        } else if (sender instanceof ConsoleCommandSender) {
            sender.sendMessage("You must be a player to use this command!");
        }

        return true;
    }
}
  • Please note: The use of @TechnicallyCoded's FoliaLib is to show how you can make use of the API methods either on Spigot/Paper or Folia servers. This also demonstrates how that some methods are best to run delayed or in an asynchronous manor for performance/efficiency reasons.

Using API Methods In Events

You can also make use of the API methods in event listeners too. Below is an example using the Bukkit PlayerJoinEvent:

package me.loving11ish.clansliteapitest.listeners;

import com.tcoded.folialib.FoliaLib;
import me.loving11ish.clans.api.ClansLiteAPI;
import me.loving11ish.clans.api.models.Clan;
import me.loving11ish.clansliteapitest.ClansLiteAPITest;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;

public class PlayerConnectionListener implements Listener {

    private final FoliaLib foliaLib = ClansLiteAPITest.getFoliaLib();

    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event) {
        // Get the player
        Player player = event.getPlayer();

        // Check if ClansLiteAPI is found
        if (ClansLiteAPITest.getPlugin().getClansLiteAPI() == null) {
            player.sendMessage("ClansLiteAPI not found!");
            return;
        }

        // Get ClansLiteAPI from the plugin
        ClansLiteAPI clansLiteAPI = ClansLiteAPITest.getPlugin().getClansLiteAPI();

        // Check if the player is in a clan
        if (clansLiteAPI.getClanByBukkitPlayer(player) != null) {
            player.sendMessage("You are in a clan!");
        } else {
            player.sendMessage("You are not in a clan!");
        }

        // Check if the player is in a clan, if not, let's create a clan
        if (clansLiteAPI.getClanByBukkitPlayer(player) != null) {
            player.sendMessage("You are in a clan!");
            Clan clan = clansLiteAPI.getClanByBukkitPlayer(player);
            player.sendMessage("Your clan: " + clan.getClanFinalName());

        } else {

            // Create a clan
            player.sendMessage("You are not in a clan!");
            player.sendMessage("Let's create a clan!");

            // Let's create a clan, but run this task later to avoid world loading lag
            foliaLib.getImpl().runAtEntityLater(player, (task) -> {
                Clan clan = clansLiteAPI.createClan(player, "TestClan");
                if (clan != null) {
                    player.sendMessage("Clan created!");

                    // Get the clan information
                    player.sendMessage("Your clan: " + clan.getClanFinalName());
                    player.sendMessage("Your clan tag: " + clan.getClanPrefix());
                    player.sendMessage("Your clan points: " + clan.getClanPoints());
                    player.sendMessage("Your clan members: " + clan.getClanMembers());
                    player.sendMessage("Your clan allies: " + clan.getClanAllies());
                    player.sendMessage("Your clan enemies: " + clan.getClanEnemies());

                } else {
                    // Failed to create a clan
                    player.sendMessage("Clan not created!");
                }
            }, 20L * 10L); // 10 seconds later

        }
    }
}
  • Please note: If you are doing similar to the above example, ensure that you run your code in a delayed task as trying to run API operations immediately when a player joins a server WILL cause extreme lag due to loading the world around a player and could even crash the server if you try to do too much.

Home Page

Click Here

Clone this wiki locally