# For Developers

## API

```java
// Obtain the UltimateGuilds instance
UltimateGuilds ultimateGuilds = UltimateGuildsProvider.get();
```

```java
public interface UltimateGuilds {

    @NonNull
    UserManager getUserManager();

    @NonNull
    GuildManager getGuildManager();

    @NonNull
    PluginMetadata getPluginMetadata();

    @NonNull
    EventBus getEventBus();

}
```

### UserManager

{% code fullWidth="false" %}

```java
/**
 * 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);

}
```

{% endcode %}

```java
/**
 * 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

```java
/**
 * 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);

}
```

```java
/**
 * 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

```java
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

```java
/**
 * 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

```java
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.GuildCreateEvent
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ohalee.com/products/ultimateguilds/for-developers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.