Skip to main content

Working with Guilds API

  • Once you have added Guilds as a dependency in your project, you can start using the Guilds API.

The new API is designed to be more user-friendly and efficient. The previous API was integrated into the jar file of the plugin, which was causing problems in some cases.

The new API is now a separate dependency, which allows for better modularity and flexibility in your projects.

It is based on the GuildAPI class, which has the Provider interfaces.

As you can see, on the Github repository of the GuildsAPI, the GuildAPI class is an interface that provides methods to interact with the guilds system.

We have got the following interfaces:

  • GuildProvider: This interface provides methods to interact with the guilds system.
  • PlayerProvider: This interface provides methods to interact with the players in the guilds system.
  • UtilsProvider: This interface provides utility methods to interact with the guilds system.

GuildProvider is the one that you will use the most, as it provides methods to interact with the guilds system.

You can use methods such as GuildAPI.getGuildProvider() to get the GuildProvider instance (the same for the other interfaces).

We recomment to create a static variable for each provider you use in your project, so you can access it easily.

Example.java
import me.leoo.guilds.api.objects.GuildAPI;
import me.leoo.guilds.api.objects.guild.GuildProvider;

public class Example {
   private static final GuildProvider GUILD_PROVIDER = GuildAPI.getGuildProvider();

   private static final PlayerProvider PLAYER_PROVIDER = GuildAPI.getPlayerProvider();

   private static final UtilsProvider UTILS_PROVIDER = GuildAPI.getUtilsProvider();
}

Once you have the provider instances, you can use them to interact with the guilds system.

Examples​

Here, you will see some example for each provider. We will not explore many methods, you can do that by yourself in two ways:

  • Checking the Github repository of the GuildsAPI, where you can find the source code of the API.
  • Checking the methods when writing your code, as the IDE will show you the methods available in the interfaces.

We will may publish the Javadocs of the API in the future, but for now, you can use the source code to understand how to use the API.

The GuildProvider interface provides methods to interact with the guilds system.

Example methods​

  • GuildView getByUuid(UUID uuid): Returns the guild with the given UUID.

  • GuildView getByName(String name): Returns the guild with the given name.

  • GuildView getByPlayer(Player player): Returns the guild of the player.

  • GuildView getByPlayer(UUID player): Returns the guild of the player with the given UUID.

  • List<GuildView> getGuilds(): Returns a list of all guilds on the server.

Example usage​

ExampleGuild.java
    public GuildView getGuildByPlayer(UUID playerUuid) {
        GuildView guild = GUILD_PROVIDER.getByPlayer(playerUuid);

        if (guild == null) {
            return null; // Player is not in a guild
        }

        return guild;
    }

    public GuildView getGuildByName(String name) {
        GuildView guild = GUILD_PROVIDER.getByName(name);

        if (guild == null) {
            return null; // Guild does not exist
        }

        return guild;
    }

    public List<GuildView> getAllGuilds() {
        return GUILD_PROVIDER.getGuilds();
    }

     // Get guilds with less than 10 members
    public List<GuildView> getUnderfilledGuilds() {
        return GUILD_PROVIDER.getGuilds().stream()
            .filter(guild -> guild.getMembersView().size() < 10)
            .collect(Collectors.toList());
    }