Developer API

CocoGuild provides a comprehensive API for developers to integrate guild functionality into their plugins.

Getting the API

import me.upoka.CocoGuild.api.CocoGuildAPI;
import org.bukkit.Bukkit;
import org.bukkit.plugin.RegisteredServiceProvider;

public class YourPlugin extends JavaPlugin {
    private CocoGuildAPI cocoGuildAPI;

    @Override
    public void onEnable() {
        RegisteredServiceProvider<CocoGuildAPI> provider = 
            Bukkit.getServicesManager().getRegistration(CocoGuildAPI.class);
        
        if (provider != null) {
            cocoGuildAPI = provider.getProvider();
        }
    }
}

Maven/Gradle Dependency

Maven

<dependency>
    <groupId>me.upoka</groupId>
    <artifactId>CocoGuild</artifactId>
    <version>LATEST</version>
    <scope>provided</scope>
</dependency>

Gradle

compileOnly 'me.upoka:CocoGuild:LATEST'

API Methods

Player & Guild Methods

Method	Description
getPlayerGuild(UUID)	Get guild name by player UUID
getPlayerGuild(Player)	Get guild name by player
getGuildMembers(String)	Get all guild members as OfflinePlayer list
getGuildOnlineMembers(String)	Get online guild members
getGuildAllies(String)	Get list of allied guild names

Guild Profile Methods

Method	Description
getGuildProfile(String)	Get GuildProfile by guild name
getGuildProfile(UUID)	Get GuildProfile by player UUID
getGuildProfile(Player)	Get GuildProfile by player
getGuildProfileAsync(String)	Get GuildProfile asynchronously
getAllGuildProfiles()	Get all guild profiles
getAllGuildProfilesAsync()	Get all guild profiles asynchronously

Invite & Statistics Methods

Method	Description
getPendingInvites(UUID)	Get pending invites for a player
getSentInvites(String)	Get invites sent by a guild
getGuildStatistics(String)	Get guild statistics (kills, deaths, KDR)

Level System Methods

Method	Description
getGuildLevel(String)	Get guild's current level
getGuildXp(String)	Get guild's current XP
setGuildLevel(String, int)	Set guild's level
setGuildXp(String, int)	Set guild's XP
addGuildXp(String, int)	Add XP to a guild
removeGuildXp(String, int)	Remove XP from a guild
addGuildLevels(String, int)	Add levels to a guild
removeGuildLevels(String, int)	Remove levels from a guild
getXpToNextLevel(String)	Get XP required for next level
getLevelProgress(String)	Get level progress as percentage (0.0-1.0)
getLevelName(String)	Get level display name
getMaxLevel()	Get maximum possible level
isLevelSystemEnabled()	Check if level system is enabled

Data Models

GuildProfile

public record GuildProfile(
    String name,
    Instant createdAt,
    UUID ownerUuid,
    GuildLevelSnapshot level,
    GuildLimits limits,
    GuildStatistics statistics,
    List<GuildMemberInfo> members,
    List<String> allies,
    List<GuildInviteInfo> pendingInvites
) { }

GuildStatistics

public record GuildStatistics(
    int kills,
    int deaths,
    double kdr
) { }

GuildMemberInfo

public record GuildMemberInfo(
    UUID uuid,
    String name,
    String rank,
    boolean online
) { }

Events

CocoGuild fires various Bukkit events that you can listen to:

Event	Description
GuildCreateEvent	Fired when a guild is created
GuildDisbandEvent	Fired when a guild is deleted
GuildPreDisbandEvent	Fired before a guild is deleted (cancellable)
GuildRenameEvent	Fired when a guild is renamed
GuildMemberJoinEvent	Fired when a player joins a guild
GuildMemberLeaveEvent	Fired when a player leaves a guild
GuildLeaderTransferEvent	Fired when leadership is transferred
GuildRankChangeEvent	Fired when a member's rank changes
GuildAllianceEvent	Fired when guilds form an alliance
GuildInviteSentEvent	Fired when an invite is sent
GuildInviteResponseEvent	Fired when an invite is accepted/denied

Event Example

import me.upoka.CocoGuild.api.events.GuildCreateEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class GuildListener implements Listener {
    
    @EventHandler
    public void onGuildCreate(GuildCreateEvent event) {
        String guildName = event.getGuildName();
        Player owner = event.getOwner();
        
        owner.sendMessage("Welcome to your new guild: " + guildName);
    }
}

Example Usage

Check if player is in a guild

public boolean isInGuild(Player player) {
    return cocoGuildAPI.getPlayerGuild(player) != null;
}

Get guild information

public void printGuildInfo(String guildName) {
    GuildProfile profile = cocoGuildAPI.getGuildProfile(guildName);
    if (profile != null) {
        System.out.println("Guild: " + profile.name());
        System.out.println("Level: " + profile.level().level());
        System.out.println("Members: " + profile.members().size());
        System.out.println("Kills: " + profile.statistics().kills());
    }
}

Award XP to a guild

public void awardXpForQuest(Player player, int xpAmount) {
    String guildName = cocoGuildAPI.getPlayerGuild(player);
    if (guildName != null) {
        cocoGuildAPI.addGuildXp(guildName, xpAmount);
    }
}