# API Reference The Lead API allows third-party plugins to create, query, and manage teams programmatically. All public interfaces are defined in the `Lead-API` module under the `gg.lode.leadapi` package. --- ## Adding Lead-API as a Dependency Lead-API is hosted on JitPack via the Lodestones GitHub organization. ### Maven ```xml <repositories> <repository> <id>jitpack.io</id> <url>https://jitpack.io</url> </repository> </repositories> <dependencies> <dependency> <groupId>com.github.Lodestones</groupId> <artifactId>Lead-API</artifactId> <version>1.1.11</version> <scope>provided</scope> </dependency> </dependencies> ``` ### Gradle (Groovy) ```groovy repositories { maven { url 'https://jitpack.io' } } dependencies { compileOnly 'com.github.Lodestones:Lead-API:1.1.11' } ``` ### Gradle (Kotlin DSL) ```kotlin repositories { maven("https://jitpack.io") } dependencies { compileOnly("com.github.Lodestones:Lead-API:1.1.11") } ``` Ensure your `plugin.yml` includes `Lead` in the `depend` or `softdepend` list so Lead loads before your plugin. --- ## Accessing the API The `LeadAPI` class provides a static singleton to access the `ILeadAPI` instance. Lead registers itself during `onLoad`, so the API is available by the time your plugin enables. ```java import gg.lode.leadapi.LeadAPI; import gg.lode.leadapi.ILeadAPI; ILeadAPI api = LeadAPI.getApi(); ``` --- ## ILeadAPI The primary interface for interacting with Lead's team system. All methods are accessible through `LeadAPI.getApi()`. | Method | Return Type | Description | |---|---|---| | `getTeam(UUID member)` | `@Nullable ITeam` | Retrieves the team a player belongs to by their UUID. Returns `null` if the player has no team. | | `getTeam(String name)` | `@Nullable ITeam` | Retrieves a team by its ID. Returns `null` if no team exists with that ID. | | `getTeams()` | `List<ITeam>` | Returns a list of all existing teams. | | `hasTeam(UUID member)` | `boolean` | Checks whether a player belongs to any team. | | `createTeamById(String id)` | `ITeam` | Creates a team with the given ID and a random color. Throws `TeamAlreadyExistsException` if the ID is taken. | | `createTeamWithLeader(String id, UUID leader)` | `ITeam` | Creates a team with the given ID and assigns a leader. Throws `TeamAlreadyExistsException`. | | `createTeamByColor(String id, UUID leader, String color)` | `ITeam` | Creates a team with a specific hex color. Throws `TeamAlreadyExistsException`. | | `createTeamByType(Player player, GeneratorType type)` | `ITeam` | Creates a team using the specified generator type. Throws `MaxTeamLimitException`, `TeamAlreadyExistsException`. | | `createTeamByType(Player player, String name, GeneratorType type)` | `ITeam` | Creates a named team using the specified generator type. Throws `MaxTeamLimitException`, `TeamAlreadyExistsException`. | | `createTeamWithUniqueColor(Player player, String id, String name)` | `ITeam` | Creates a team with a unique color from the connected colors pool. Throws `MaxTeamLimitException`, `TeamAlreadyExistsException`. | | `deleteTeam(String id)` | `ITeam` | Deletes a team by ID. Returns the deleted team. Throws `TeamNotFoundException`. | | `deleteTeam(ITeam team)` | `ITeam` | Deletes the specified team. Returns the deleted team. | | `removePlayerFromTeam(ITeam team, UUID player)` | `void` | Removes a player from the specified team. | | `getAvailableTeamNumber()` | `String` | Returns the next available team number as a string. Behavior depends on the `should_increment` config value. | | `save()` | `void` | Saves all teams to `teams.yml`. | | `update()` | `void` | Refreshes all nametag and scoreboard entries for all teams. | --- ## ITeam Represents a single team. Obtained through `ILeadAPI` methods. | Method | Return Type | Description | |---|---|---| | `getId()` | `String` | Returns the team's internal ID. | | `getName()` | `String` | Returns the team's display name. | | `getColor()` | `String` | Returns the team's hex color (e.g., `#FF0000`). | | `getUniqueId()` | `UUID` | Returns the team's unique identifier. | | `getLeaderUniqueId()` | `@Nullable UUID` | Returns the UUID of the team leader, or `null` if unset. | | `getMembers()` | `List<ITeamMember>` | Returns the list of team members. | | `getInvitations()` | `List<UUID>` | Returns an immutable list of pending invitation UUIDs. | | `getSpawnLocation()` | `@Nullable Location` | Returns the team's spawn location, or `null` if unset. | | `getCollidable()` | `Team.OptionStatus` | Returns the team's collision rule. | | `getNameTagVisibility()` | `Team.OptionStatus` | Returns the team's nametag visibility setting. | | `isFriendlyFireAllowed()` | `boolean` | Returns whether friendly fire is enabled. | | `shouldColorName()` | `boolean` | Returns whether player names are colored by team color. | | `getNameAsNumber()` | `int` | Parses the team name as an integer. Throws `NumberFormatException` if not numeric. | | `containsMember(UUID uniqueId)` | `boolean` | Checks if a player is a member of this team. | | `getMember(UUID uniqueId)` | `@Nullable ITeamMember` | Retrieves a specific member by UUID. | | `setId(String id)` | `void` | Sets the team's internal ID. | | `setName(String name)` | `void` | Sets the team's display name. | | `setColor(String color)` | `void` | Sets the team's hex color. Accepts with or without `#` prefix. | | `setSpawnLocation(Location location)` | `void` | Sets the team's spawn location. Pass `null` to clear. | | `setCollidable(Team.OptionStatus status)` | `void` | Sets the team's collision rule. | | `setNameTagVisibility(Team.OptionStatus status)` | `void` | Sets the team's nametag visibility. | | `setFriendlyFireAllowed(boolean value)` | `void` | Enables or disables friendly fire. | | `setColorName(boolean value)` | `void` | Enables or disables name coloring. | | `addMember(Player player)` | `void` | Adds an online player to the team. | | `addMember(ITeamMember member)` | `void` | Adds a team member object to the team. | | `removeMember(UUID uniqueId)` | `void` | Removes a member by UUID. | | `addInvitation(UUID uniqueId)` | `void` | Adds a pending invitation. | | `removeInvitation(UUID uniqueId)` | `void` | Removes a pending invitation. | | `save(FileConfiguration file)` | `void` | Serializes the team to a YAML configuration. | --- ## ITeamMember Represents a player within a team. | Method | Return Type | Description | |---|---|---| | `getUniqueId()` | `UUID` | Returns the member's UUID. | | `getName()` | `String` | Returns the member's name. | | `isInTeamChat()` | `boolean` | Returns whether the member has team chat toggled on. | | `setInTeamChat(boolean status)` | `void` | Toggles team chat for the member. | --- ## GeneratorType An enum defining how Lead generates team identifiers when `nameable_teams` is `false`. | Value | Description | |---|---| | `NUMBER` | Generates a numeric ID. Up to 1,000 unique teams. Sequential or random based on `should_increment`. | | `NAME` | Picks a random name from the `available_names` list in `random.yml`. | | `COLOR` | Picks a connected color-name pair from `connected_colors` in `random.yml`. Both color and name are unique. | | `UNICODE` | Uses the `unicode` value from `random.yml` as the team symbol. Not unique across teams. | --- ## Events Lead fires custom Bukkit events for all team operations. Events are cancellable where applicable. Listen to these events using the standard Bukkit `@EventHandler` pattern. | Event | Description | |---|---| | `TeamCreateEvent` | Fired when a team is created (any method). Provides `getTeam()` and `@Nullable getPlayer()`. | | `TeamCreateByPlayerEvent` | Fired when a player creates a team via command. | | `TeamDeleteEvent` | Fired when a team is deleted. | | `TeamDisbandEvent` | Fired when a leader disbands their team. | | `TeamJoinEvent` | Fired when a player joins a team via invitation. | | `TeamJoinByPlaceEvent` | Fired when an admin places a player into a team. | | `TeamLeaveEvent` | Fired when a player leaves a team. | | `TeamKickEvent` | Fired when a player is kicked from a team. | | `TeamRemoveEvent` | Fired when a player is removed from a team by an admin. | | `TeamInviteEvent` | Fired when a team invitation is sent. | | `TeamMergeEvent` | Fired when two teams are merged. | | `TeamMessageEvent` | Fired when a team message is sent. | | `TeamPromoteEvent` | Fired when a team member is promoted. | | `TeamTeleportEvent` | Fired when a team is teleported. | | `TeamSetSpawnEvent` | Fired when a team spawn is set. | | `TeamResetSpawnEvent` | Fired when a team spawn is reset. | | `TeamChangeColorEvent` | Fired when a team's color changes. Provides `getOldColor()` and `getNewColor()`. | | `TeamChangeNameEvent` | Fired when a team's display name changes. | | `TeamChangeIdEvent` | Fired when a team's ID changes. | --- ## Exceptions | Exception | Thrown When | |---|---| | `TeamAlreadyExistsException` | A team creation method is called with an ID that already exists. | | `TeamNotFoundException` | `deleteTeam(String id)` is called with an ID that does not exist. | | `MaxTeamLimitException` | A team creation method is called when the maximum team count has been reached. | --- ## Code Examples ### Fetching a Player's Team ```java import gg.lode.leadapi.LeadAPI; import gg.lode.leadapi.ILeadAPI; import gg.lode.leadapi.api.ITeam; import org.bukkit.entity.Player; public void printTeamInfo(Player player) { ILeadAPI api = LeadAPI.getApi(); ITeam team = api.getTeam(player.getUniqueId()); if (team == null) { player.sendMessage("You are not in a team."); return; } player.sendMessage("Team: " + team.getName()); player.sendMessage("Color: " + team.getColor()); player.sendMessage("Members: " + team.getMembers().size()); } ``` ### Creating a Team Programmatically ```java import gg.lode.leadapi.LeadAPI; import gg.lode.leadapi.ILeadAPI; import gg.lode.leadapi.api.ITeam; import gg.lode.leadapi.api.exception.TeamAlreadyExistsException; public ITeam createTeam(String id, Player leader) { ILeadAPI api = LeadAPI.getApi(); try { ITeam team = api.createTeamWithLeader(id, leader.getUniqueId()); team.setName("My Custom Team"); team.setColor("#FF5500"); api.update(); return team; } catch (TeamAlreadyExistsException e) { leader.sendMessage("A team with that ID already exists."); return null; } } ``` ### Listening to Team Events ```java import gg.lode.leadapi.api.event.TeamCreateEvent; import gg.lode.leadapi.api.event.TeamJoinEvent; import org.bukkit.event.EventHandler; import org.bukkit.event.Listener; public class TeamListener implements Listener { @EventHandler public void onTeamCreate(TeamCreateEvent event) { String teamId = event.getTeam().getId(); if (event.getPlayer() != null) { event.getPlayer().sendMessage("Welcome to team " + teamId + "!"); } } @EventHandler public void onTeamJoin(TeamJoinEvent event) { // Notify existing members event.getTeam().getMembers().forEach(member -> { // Process new member joining }); } } ``` ### Listing All Teams ```java import gg.lode.leadapi.LeadAPI; import gg.lode.leadapi.api.ITeam; public void listTeams() { for (ITeam team : LeadAPI.getApi().getTeams()) { System.out.println(String.format( "Team %s (%s) - %d members - Color: %s", team.getName(), team.getId(), team.getMembers().size(), team.getColor() )); } } ``` --- ## Related Pages - [[Lead/Developers/Overview]] — Architecture and build instructions. - [[Lead/Server Owners/Commands]] — Command reference for testing API behavior.