🖥️For Developers
API
// Obtain the UltimateGuilds instance
UltimateGuilds ultimateGuilds = UltimateGuildsProvider.get();public interface UltimateGuilds {
@NonNull
UserManager getUserManager();
@NonNull
GuildManager getGuildManager();
@NonNull
PluginMetadata getPluginMetadata();
@NonNull
EventBus getEventBus();
}UserManager
/**
* Represents the object responsible for managing {@link User} instances.
*
* <p>Note that User instances are automatically loaded for online players.
* It's likely that offline players will not have an instance pre-loaded.</p>
*
* <p>All blocking methods return {@link CompletableFuture}s, which will be
* populated with the result once the data has been loaded/saved asynchronously.
* Care should be taken when using such methods to ensure that the main server
* thread is not blocked.</p>
*
* <p>Methods such as {@link CompletableFuture#get()} and equivalent should
* <strong>not</strong> be called on the main server thread. If you need to use
* the result of these operations on the main server thread, register a
* callback using {@link CompletableFuture#thenAcceptAsync(Consumer, Executor)}.</p>
*/
public interface UserManager {
/**
* Loads a user from the plugin's storage provider into memory.
*
* @param uniqueId the uuid of the user
* @param username the username, if known
* @return the resultant user
* @throws NullPointerException if the uuid is null
*/
CompletableFuture<User> loadUser(UUID uniqueId, String username);
/**
* Loads a user from the plugin's storage provider into memory.
*
* @param uniqueId the uuid of the user
* @return the resultant user
* @throws NullPointerException if the uuid is null
*/
default CompletableFuture<User> loadUser(UUID uniqueId) {
return loadUser(uniqueId, null);
}
/**
* Uses the UltimateGuilds cache to find a uuid for the given username.
*
* <p>This lookup is case insensitive.</p>
*
* @param username the username
* @return a uuid, could be null
* @throws NullPointerException if either parameters are null
* @throws IllegalArgumentException if the username is invalid
*/
CompletableFuture<UUID> lookupUniqueId(String username);
/**
* Uses the UltimateGuilds cache to find a username for the given uuid.
*
* @param uniqueId the uuid
* @return a username, could be null
* @throws NullPointerException if either parameters are null
* @throws IllegalArgumentException if the username is invalid
*/
CompletableFuture<String> lookupUsername(UUID uniqueId);
/**
* Gets a set all unique user UUIDs.
*
* @return a set of uuids
*/
CompletableFuture<Set<UUID>> getUniqueUsers();
/**
* Gets a loaded user.
*
* @param uniqueId the uuid of the user to get
* @return a {@link User} object, if one matching the uuid is loaded, or null if not
* @throws NullPointerException if the uuid is null
*/
User getUser(UUID uniqueId);
/**
* Gets a loaded user.
*
* @param username the username of the user to get
* @return a {@link User} object, if one matching the uuid is loaded, or null if not
* @throws NullPointerException if the name is null
*/
User getUser(String username);
/**
* Gets a set of all loaded users.
*
* @return a {@link Set} of {@link User} objects
*/
Set<User> getLoadedUsers();
/**
* Check if a user is loaded in memory
*
* @param uniqueId the uuid to check for
* @return true if the user is loaded
* @throws NullPointerException if the uuid is null
*/
boolean isLoaded(UUID uniqueId);
}/**
* Represents a user on the platform.
*/
public interface User {
/**
* Gets the user's ID
*
* @return the user's ID
*/
int getId();
/**
* Gets the users unique ID
*
* @return the users Mojang assigned unique id
*/
UUID getUniqueId();
/**
* Gets the users username
*
* <p>Returns null if no username is known for the user.</p>
*
* @return the users username
*/
String getUsername();
}
GuildManager
/**
* The GuildManager interface provides methods to manage guilds.
*/
public interface GuildManager {
/**
* Loads a guild with the given guildId asynchronously.
*
* @param guildId The id of the guild to be loaded.
* @return A CompletableFuture that completes with the loaded Guild.
*/
@NonNull CompletableFuture<Guild> loadGuild(int guildId);
/**
* Returns the Guild associated with the given guildId.
*
* @param guildId the ID of the Guild
* @return the Guild object corresponding to the guildId
*/
Guild getGuild(int guildId);
/**
* Retrieves the Guild object based on the specified guild ID.
*
* @param user The user to get the guild for.
* @return The Guild object associated with the specified guild ID, or null if the guild ID is not found.
*/
Guild getGuild(@NonNull User user);
/**
* Retrieves the set of loaded guilds.
*
* @return A set of Guild objects representing the loaded guilds.
*/
Set<Guild> getLoadedGuilds();
/**
* Checks if a specific guild with the given ID is loaded.
*
* @param guildId The ID of the guild to check.
* @return {@code true} if the guild is loaded, {@code false} otherwise.
*/
boolean isLoaded(int guildId);
}/**
* The Guild interface represents a guild.
* It provides methods to manage members, invites, bans, and experience points.
*/
public interface Guild {
/**
* Adds a new member to the system.
*
* @param user the User object representing the member to be added
*/
void addMember(User user);
/**
* Removes an existing member from the system.
*
* @param user the User object representing the member to be removed
*/
void removeMember(User user);
/**
* Updates an existing member in the system.
*/
void updateMember(User user, Rank rank);
/**
* Adds a new invite to the system.
*
* @param user the User object representing the invite to be added
*/
void addInvite(User user, Source source);
/**
* Removes an invite from the system.
*
* @param user the User object representing the invite to be removed
*/
void removeInvite(User user);
/**
* Removes the invite for a specific user.
*
* @param userId the ID of the user whose invite is to be removed
*/
void removeInvite(int userId);
/**
* Adds a ban for a user in the system.
*
* @param user the User object representing the user to be banned
*/
void addBan(User user, Source source);
/**
* Removes the ban for a specific user.
*
* @param user the User object representing the user whose ban is to be removed
*/
void removeBan(User user);
/**
* Removes the ban of a user with the given user ID.
*
* @param userId the ID of the user whose ban is to be removed
*/
void removeBan(int userId);
/**
* Checks if a user with the given user ID is banned.
*
* @param userId the ID of the user to be checked for banning
* @return true if the user is banned, false otherwise
*/
boolean isBanned(int userId);
/**
* Checks if a user is invited.
*
* @param userId the ID of the user to check
* @return true if the user is invited, false otherwise
*/
boolean isInvited(int userId);
/**
* Gets the member with the specified userId.
*
* @param userId the unique identifier of the member
* @return an Optional<User> object representing the member with the specified userId,
* or an empty Optional if no member is found
*/
Optional<User> getMember(int userId);
/**
* Checks if the given user is a member in the system.
*
* @param user the User object to check for membership
* @return {@code true} if the user is a member, {@code false} otherwise
*/
boolean containsMember(User user);
/**
* Checks if a member with the specified userId exists in the system.
*
* @param userId the userId of the member to check
* @return true if a member with the specified userId exists, false otherwise
*/
boolean containsMember(int userId);
/**
* Increases the experience points (xp) of the user by the specified amount.
*
* @param amount the amount of xp to be added
*/
void addXp(int amount);
/**
* Applies the specified multiplier to the value.
*
* @param multiplier the value to multiply with
*/
void multiplier(double multiplier);
}PluginMetadata
public interface PluginMetadata {
/**
* Gets the plugin version
*
* @return the version of the plugin running on the platform
*/
@NonNull
String getVersion();
/**
* Gets the API version
*
* @return the version of the API running on the platform
*/
@NonNull
String getApiVersion();
}EventBus
/**
* The UltimateGuilds event bus.
*
* <p>Used to subscribe (or "listen") to UltimateGuilds events.</p>
*/
public interface EventBus {
/**
* Registers a new subscription to the given event.
*
* @param eventClass the event class
* @param handler the event handler
* @param <T> the event class
* @return an event handler instance representing this subscription
*/
<T extends UltimateGuildsEvent> EventSubscription<T> subscribe(Class<T> eventClass, Consumer<? super T> handler);
/**
* Registers a new subscription to the given event.
*
* @param <T> the event class
* @param plugin a plugin instance to bind the subscription to.
* @param eventClass the event class
* @param handler the event handler
* @return an event handler instance representing this subscription
*/
<T extends UltimateGuildsEvent> EventSubscription<T> subscribe(Object plugin, Class<T> eventClass, Consumer<? super T> handler);
}Events
it.ohalee.ultimateguilds.api.event.user.UserLoadEvent
it.ohalee.ultimateguilds.api.event.user.UserCacheLoadEvent
it.ohalee.ultimateguilds.api.event.guild.GuildLoadEvent
it.ohalee.ultimateguilds.api.event.guild.GuildBanEvent
it.ohalee.ultimateguilds.api.event.guild.GuildKickEvent
it.ohalee.ultimateguilds.api.event.guild.GuildCreateEventLast updated