> For the complete documentation index, see [llms.txt](https://wiki.helpch.at/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.helpch.at/glares-plugins/guilds/developer-api.md). # Developer API ## Build Tool Stuff

Sonatype Nexus (Releases)

{% tabs %} {% tab title="Maven" %} ```markup glares-repo https://repo.glaremasters.me/repository/public/ me.glaremasters guilds VERSION ``` {% endtab %} {% tab title="Gradle" %} ```groovy repositories { maven { url = 'https://repo.glaremasters.me/repository/public/' } } dependencies { compileOnly 'me.glaremasters:guilds:VERSION' } ``` {% endtab %} {% tab title="Kotlin" %} ```kotlin repositories { maven("https://repo.glaremasters.me/repository/public/") } dependencies { compileOnly("me.glaremasters:guilds:VERSION") } ``` {% endtab %} {% endtabs %} ## Hooking Into the API Obtaining the instance of the API is pretty simple by using the singleton that provides static access to the class. You can obtain the instance of the API through the main `Guilds` class. ```java GuildsAPI api = Guilds.getApi(); ``` The API object is only created at the very end of the plugin's startup. `getApi()` returns `null` for most of that window, so null-check it before you use it if your plugin might load early. ## Packages Everything you need is under `me.glaremasters.guilds.api`. There are two sub-packages worth knowing about: | Import | Holds | | ---------------------------------------------- | ----------------------------------------- | | `me.glaremasters.guilds.api` | `GuildsAPI`, the entry point | | `me.glaremasters.guilds.api.events` | Most events | | `me.glaremasters.guilds.api.events.base` | `GuildEvent`, which all the others extend | | `me.glaremasters.guilds.api.events.challenges` | The guild war events | Supporting types live outside that package: `Guild`, `GuildMember`, `GuildRole`, `GuildTier` and `GuildHandler` are all in `me.glaremasters.guilds.guild`, and `GuildBuff` is in `me.glaremasters.guilds.conf.objects`. ## Using the API The API can be used for obtaining a bunch of information from the plugin. You can browse over the following section to see what all is provided. ### Getting a Guild object We provide a few ways to obtain a Guild object, so feel free to use what is easiest for you. {% tabs %} {% tab title="OfflinePlayer" %} ```kotlin /** * * Get the guild of a player * @param player the players you're getting the guild of * @return the guild that the player is in */ fun getGuild(player: OfflinePlayer): Guild? { return guildHandler.getGuild(player) } ``` {% endtab %} {% tab title="Guild UUID" %} ```kotlin /** * Get a guild by it's uuid * @param uuid uuid of the guild * @return the guild the uuid belong to */ fun getGuild(uuid: UUID): Guild? { return guildHandler.getGuild(uuid) } ``` {% endtab %} {% tab title="Guild Name" %} ```kotlin /** * Get a guild by it's name * @param name the name of the guild * @return the guild object */ fun getGuild(name: String): Guild? { return guildHandler.getGuild(name) } ``` {% endtab %} {% tab title="Player UUID" %} ```kotlin /** * Get a guild by a player's uuid * * @param uuid the uuid of the player * @return the guild of the player or null */ fun getGuildByPlayerId(uuid: UUID): Guild? { return guildHandler.getGuildByPlayerId(uuid) } ``` {% endtab %} {% endtabs %} ### Getting a GuildMember object ```kotlin /** * Get a guild member by their uuid * * @param uuid the uuid of the player * @return the guild member instance or null */ fun getGuildMember(uuid: UUID): GuildMember? { return guildHandler.getGuildMember(uuid) } ``` ### Getting a Guild Vault ```kotlin /** * Get a copy of one of a guild's vaults * @param guild the guild to get the vault of * @param vaultNumber which vault to get * @return guild vault */ fun getGuildVault(guild: Guild, vaultNumber: Int): Inventory { return guildHandler.getGuildVault(guild, vaultNumber) } ``` ### Getting a GuildRole ```kotlin /** * Get the role of a player * @param player role * @return the role of a player */ fun getGuildRole(player: Player): GuildRole? { return getGuild(player)?.getMember(player.uniqueId)?.role } ``` ### Getting the GuildHandler The GuildHandler will give you access to anything you might need in the plugin. Please use caution with this method as the content it lets you access to can break the plugin if you use it incorrectly. ```java /** * Get the guild handler * @return guild handler */ GuildHandler guildHandler = api.getGuildHandler(); ``` ### Getting the CooldownHandler The CooldownHandler holds the command cooldowns for every guild. It is exposed on the same API instance. ```java CooldownHandler cooldownHandler = api.getCooldownHandler(); ``` ## Custom Events In the plugin we offer a bunch of custom events that you can listen to and modify as you see fit. ### Base GuildEvent `GuildEvent` lives in `me.glaremasters.guilds.api.events.base` and every guild event below extends it. It extends Bukkit's `PlayerEvent`, so `getPlayer()` comes for free. Every `GuildEvent` implements `Cancellable`. Calling `setCancelled(true)` in your listener stops the action the event was fired for. ```kotlin /** * Base guild event * @param player player in event * @param guild guild in the event */ open class GuildEvent(player: Player, val guild: Guild) : PlayerEvent(player), Cancellable { var isCancelled: Boolean = false override fun isCancelled(): Boolean = isCancelled override fun setCancelled(cancelled: Boolean) { isCancelled = cancelled } override fun getHandlers(): HandlerList = handlerList companion object { @JvmStatic val handlerList = HandlerList() } } ``` ### GuildAddAllyEvent ```java /** * This event takes place when two guilds ally each other * @param player player who accepted * @param guild guild one * @param ally guild two */ public GuildAddAllyEvent(Player player, Guild guild, Guild ally) { super(player, guild); this.ally = ally; } ``` ### GuildBuffEvent The buff on this event is mutable, so a listener can replace it with `setBuff(GuildBuff)` before the purchase is processed. ```kotlin /** * Called when a guild purchases a buff * @param player the player purchasing the buff * @param guild the guild the player is in * @param buff the buff being purchased */ class GuildBuffEvent(player: Player, guild: Guild, var buff: GuildBuff) : GuildEvent(player, guild) ``` ### GuildCreateEvent ```java /** * Called when people create a guild * @param player player creating the guild * @param guild the guild being created */ public GuildCreateEvent(Player player, Guild guild) { super(player, guild); } ``` ### GuildDepositMoneyEvent ```java /** * Base guild event * @param player player in event * @param guild guild in the event * @param amount the amount to deposit */ public GuildDepositMoneyEvent(Player player, Guild guild, double amount) { super(player, guild); this.amount = amount; } ``` ### GuildInviteEvent ```java /** * Called when a player gets invited to a guild * @param player the player inviting other to guild * @param guild the guild player will be joining * @param invitedPlayer the player being invited */ public GuildInviteEvent(Player player, Guild guild, Player invitedPlayer) { super(player, guild); this.invitedPlayer = invitedPlayer; } ``` ### GuildJoinEvent ```java /** * Called when a player joins a guild * @param player the player joining a guild * @param guild the guild the player will be joining */ public GuildJoinEvent(Player player, Guild guild) { super(player, guild); } ``` ### GuildLeaveEvent ```java /** * Called a when a player leaves the guild * @param player the player leaving the guild * @param guild the guild the player was leaving */ public GuildLeaveEvent(Player player, Guild guild) { super(player, guild); } ``` ### GuildKickEvent ```kotlin /** * Called when a player is kicked from the guild * @param player the player executing the event * @param kicked the player being kicked from the guild * @param cause the cause for being kicked */ class GuildKickEvent(player: Player, guild: Guild, val kicked: OfflinePlayer, val cause: Cause) : GuildEvent(player, guild) { enum class Cause { PLAYER_KICKED, ADMIN_KICKED } } ``` ### GuildPrefixEvent ```java private String prefix; /** * Base guild event * @param player player in event * @param guild guild in the event * @param prefix */ public GuildPrefixEvent(Player player, Guild guild, String prefix) { super(player, guild); this.prefix = prefix; } public String getPrefix() { return prefix; } ``` ### GuildRemoveAllyEvent ```java /** * Called when a guild removes an ally * @param player the player calling the removal * @param guild the guild calling the removal * @param ally the guild being removed */ public GuildRemoveAllyEvent(Player player, Guild guild, Guild ally) { super(player, guild); this.ally = ally; } ``` ### GuildRemoveEvent ```java /** * Called when a guild is removed * @param player the player removing the guild * @param guild the guild getting removed * @param cause the reason for the guild being removed */ public GuildRemoveEvent(Player player, Guild guild, Cause cause) { super(player, guild); this.cause = cause; } public Cause getCause() { return cause; } public enum Cause { MASTER_LEFT, PLAYER_DELETED, ADMIN_DELETED } ``` The `Cause` enum is a nested type, so from Java you reference it as `GuildRemoveEvent.Cause`. ### GuildRenameEvent ```java /** * @param player player in event * @param guild guild in the event */ public GuildRenameEvent(Player player, Guild guild, String newName) { super(player, guild); this.name = newName; } public String getName() { return name; } ``` ### GuildSetHomeEvent ```kotlin /** * Called when a guild sets their home * @param player the player setting the home * @param guild the guild the player is in * @param location the location the home is being set at */ class GuildSetHomeEvent(player: Player, guild: Guild, val location: Location) : GuildEvent(player, guild) ``` ### GuildTransferEvent `newMaster` is an `OfflinePlayer`, so check `isOnline()` before assuming you have a `Player` instance. ```kotlin /** * Base guild event * @param player player in event * @param guild guild in the event * @param newMaster the guild's new master */ class GuildTransferEvent(player: Player, guild: Guild, val newMaster: OfflinePlayer) : GuildEvent(player, guild) ``` ### GuildWithdrawMoneyEvent ```java /** * @param player player in event * @param guild guild in the event * @param amount the amount to withdraw */ public GuildWithdrawMoneyEvent(Player player, Guild guild, double amount) { super(player, guild); this.amount = amount; } ``` ### GuildUpgradeEvent ```java /** * Called when a guild upgrades their tier * @param player the player upgrading the tier * @param guild the guild the player is in * @param tier the new guild tier for the guild */ public GuildUpgradeEvent(Player player, Guild guild, GuildTier tier) { super(player, guild); this.tier = tier; } ``` ### GuildWarAcceptEvent ```kotlin /** * Called when a guild war has been accepted * @param player the player that accepted the war challenge * @param challenger the challenging guild for the war * @param defender the defending guild for the war */ class GuildWarAcceptEvent(player: Player, val challenger: Guild, val defender: Guild) : GuildEvent(player, defender) ``` `getGuild()` returns the defending guild here, since this event is fired from the accepting side. ### GuildWarChallengeEvent ```kotlin /** * Called when a guild war challenge has been sent from one guild to another * @param player the player that sent the war challenge * @param challenger the challenging guild for the war * @param defender the defending guild for the war */ class GuildWarChallengeEvent(player: Player, val challenger: Guild, val defender: Guild) : GuildEvent(player, challenger) ``` ### GuildWarDeclineEvent ```kotlin /** * Called when a guild war has been declined * @param player the player that declined the challenge * @param challenger the challenging guild for the war * @param defender the defending guild for the war */ class GuildWarDeclineEvent(player: Player, val challenger: Guild, val defender: Guild) : GuildEvent(player, defender) ``` ### GuildWarEndEvent ```kotlin /** * Called when a guild war has ended * @param challenger the challenging guild for the war * @param defender the defending guild for the war * @param winner the winner of the guild war */ class GuildWarEndEvent(val challenger: Guild, val defender: Guild, val winner: Guild) : Event() { override fun getHandlers(): HandlerList { return handlerList } companion object { val handlerList = HandlerList() } } ``` ### GuildWarStartEvent ```kotlin /** * Called when a guild war has started * @param challenger the challenging guild for the war * @param defender the defending guild for the war */ class GuildWarStartEvent(val challenger: Guild, val defender: Guild) : Event() { override fun getHandlers(): HandlerList { return handlerList } companion object { @JvmStatic val handlerList = HandlerList() } } ``` ### GuildWarPlayerJoinEvent This one fires when a player joins a war, not when the war is set up. It extends Bukkit's `Event` directly rather than `GuildEvent`, so it is not cancellable. ```kotlin /** * Called when a player joins a guild war * @param challenger the guild who initiated the request * @param defender the guild the request was sent to * @param player the player who joined the war * @param side the side the player joined */ class GuildWarPlayerJoinEvent(val challenger: Guild, val defender: Guild, val player: Player, val side: String): Event() { override fun getHandlers(): HandlerList { return handlerList } companion object { @JvmStatic val handlerList = HandlerList() } } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://wiki.helpch.at/glares-plugins/guilds/developer-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.