🖥️For Developers

UltimateGuilds ships an api module (com.ohalee.ultimateguilds.api) that exposes a stable, read/write interface to guild data. Add UltimateGuilds to your plugin.yml (depend or softdepend) so the API is loaded before your plugin.

Obtaining the API

The entry point is UltimateGuildsProvider. Call it once the UltimateGuilds plugin has enabled (for example inside your own onEnable), not from a constructor.

Accessing the API

UltimateGuilds api = UltimateGuildsProvider.get();
GuildManager guildManager = api.getGuildManager();

UltimateGuildsProvider.get() throws an IllegalStateException if the API is not yet loaded. This usually means UltimateGuilds isn't installed/enabled, or your plugin doesn't declare a dependency on it.

public interface UltimateGuilds {

    /**
     * The manager responsible for all guild operations.
     */
    @NotNull GuildManager getGuildManager();

}

GuildManager

GuildManager is the main service. Its methods fall into a few groups:

• Database lookups — blocking I/O that queries the database (e.g. loadGuild, find, getLogs, hasGuild).

• Asynchronous modification — non-blocking writes returning CompletableFuture (e.g. createGuild, renameGuild, addMember, banPlayer).

• Server cache retrieval — in-memory, non-blocking reads (e.g. getLoadedGuild, getCached, getLoadedGuilds).

• Cosmetics & messaging — suffix refreshing and cross-server message delivery.

Methods annotated @Blocking (and the loadGuild/find lookups) touch the database. Never call them on the main server thread — use the cache methods there, or run the lookup asynchronously.

GuildManager (selected methods)

public interface GuildManager {

    // --- Database lookups (blocking / async) ---
    CompletableFuture<Optional<Guild>> loadGuild(int guildId);
    CompletableFuture<Optional<Guild>> loadGuild(UUID memberUniqueId);
    CompletableFuture<Optional<Pair<Guild, GuildMember>>> find(UUID memberUniqueId);
    CompletableFuture<Optional<Pair<Guild, GuildMember>>> find(String memberUsername);
    CompletableFuture<Optional<Guild>> findByName(String name);

    @Blocking boolean hasGuild(UUID uniqueId);
    @Blocking boolean isNameUnique(String name);
    @Blocking boolean isTagUnique(String tag);

    List<Log> getLogs(int guildId, int page, int pageSize);
    CompletableFuture<List<Log>> getLogsAsync(int guildId, int page, int pageSize);

    // --- Asynchronous modification ---
    CompletableFuture<Guild> createGuild(String name, String tag, int maxMembers,
                                         UUID leaderUuid, String leaderUsername);
    CompletableFuture<Void> renameGuild(Guild guild, String newName);
    CompletableFuture<Void> updateTag(Guild guild, String newTag, String hexTagColor);
    CompletableFuture<Void> updateDescription(Guild guild, String description);
    CompletableFuture<Void> addMember(Guild guild, UUID uuid, String username, GuildRank rank);
    CompletableFuture<Void> removeMember(Guild guild, UUID uuid);
    CompletableFuture<Void> updateMemberRank(Guild guild, UUID uuid, GuildRank newRank);
    CompletableFuture<Void> banPlayer(Guild guild, UUID targetUuid, String targetUsername,
                                      UUID bannedByUuid, String bannedByUsername);
    CompletableFuture<Void> unbanPlayer(Guild guild, UUID targetUuid);
    CompletableFuture<Void> disbandGuild(Guild guild);
    CompletableFuture<Void> updateGuildStats(Guild guild);

    // --- Server cache retrieval ---
    Optional<Guild> getLoadedGuild(int guildId);
    Optional<Guild> getLoadedGuild(UUID memberUniqueId);
    @Nullable Guild getCached(int guildId);
    @Nullable Guild getCachedByPlayer(UUID uniqueId);
    Set<Guild> getLoadedGuilds();
    void invalidateLocalCache(int guildId);

    // --- Invites, bans & members ---
    Set<GuildInvite> getInvites(int guildId);
    boolean hasInvite(UUID targetId);
    Set<GuildMember> getOnlineMembers(int guildId);
    CompletableFuture<List<GuildBan>> getBans(int guildId);

    // --- Cosmetics & messaging ---
    void refreshSuffixes(Guild guild);
    void sendMessage(UUID uniqueId, Component message);
    void broadcastMessage(Guild guild, Component message);
    void insertLog(int guildId, Log... logs);
}

Guild

A Guild is the mutable model returned by the manager. It exposes the guild's identity, progression and roster.

public interface Guild {

    int id();
    String name();
    void name(String name);

    @Nullable String tag();
    void tag(@Nullable String tag);
    String tagColor();               // hex string, e.g. "#FFFFFF"
    void tagColor(String tagColor);

    @Nullable String description();
    void description(@Nullable String description);

    int level();      void level(int level);
    int xp();         void xp(int xp);        void addXp(int amount);
    double multiplier();  void multiplier(double multiplier);
    int maxMembers(); void maxMembers(int maxMembers);
    long createdAt();

    void addMember(GuildMember member);
    void removeMember(UUID uuid);
    void updateMemberRank(UUID uuid, GuildRank newRank);

    Collection<GuildMember> members();
    List<GuildMember> getMembersByRank(GuildRank rank);
    Optional<GuildMember> getMember(UUID uniqueId);
    Optional<GuildMember> getMember(String username);
    boolean isMember(UUID uniqueId);

    void broadcast(Component component);
}

Models

GuildMember, GuildRank, GuildBan and GuildInvite are lightweight, immutable models.

// A member of a guild.
public record GuildMember(UUID uniqueId, String username, GuildRank rank,
                          long joined, long lastSeen) {}

// The five ranks, ordered from highest (ordinal 0) to lowest.
public enum GuildRank {
    GUILD_MASTER, CO_LEADER, MODERATOR, MEMBER, RECRUIT;

    public static GuildRank getRank(int id);
    public GuildRank nextRank();      // the rank above (null past CO_LEADER)
    public GuildRank previousRank();  // the rank below
    public Component displayName();
}

// A ban entry.
public record GuildBan(UUID targetUuid, String targetUsername,
                       UUID bannedByUuid, String bannedByUsername, long timestamp) {}

// A pending invite.
public record GuildInvite(UUID targetUuid, String username,
                          String invitedByUsername, long createdAt) {}

GuildRank is ordered so that a lower ordinal means a higher rank — GUILD_MASTER is 0 and RECRUIT is the last value. Keep this in mind when comparing ranks (rank().ordinal() <= other.ordinal() means "at least as senior").