Skip to content

ZelTeams

Developer API

🎬 Getting Started

I) Adding ZelTeams as a Dependency

Maven:

<repository>
	<id>jitpack.io</id>
	<url>https://jitpack.io</url>
</repository>

<dependency>
	  <groupId>com.github.Zeltuv</groupId>
	  <artifactId>zelteams-api</artifactId>
	  <version>3.4.0</version>
</dependency>

Gradle:

repositories {
	mavenCentral()
	maven { url 'https://jitpack.io' }
}

dependencies {
	compileOnly 'com.github.Zeltuv:zelteams-api:3.4.0'
}

II) Accessing the API

import com.zeltuv.teams.api.ZelTeamsAPI;
import com.zeltuv.teams.api.ITeamPlugin;

ITeamPlugin api = ZelTeamsAPI.getInstance();

🩵 Core Managers

I) Team Manager

The TeamManager handles all team-related operations including creation, retrieval, and management.

Getting the TeamManager:

ITeamManager teamManager = api.getTeamManager();

Common Operations:

// Get a player's team
Player player = Bukkit.getPlayer("PlayerName");
Team team = teamManager.getTeam(player);

// Check if player has a team
boolean hasTeam = teamManager.hasTeam(player);

// Get team by name
Team team = teamManager.getTeamByName("TeamName");

// Get team by tag
Team team = teamManager.getByTag("[TAG]");

// Check if name is in use
boolean tagInUse = teamManager.isTagInUse("[TAG]");

// Disband a team
teamManager.disbandTeam(team);

// Get all cached teams
Map<UUID, Team> teams = teamManager.getCachedTeams();

// Get offline user data
OfflineUser offlineUser = teamManager.getOfflineOrOnlineUser(playerUUID);

// Get team by offline player UUID
Team team = teamManager.getOfflinePlayerTeam(playerUUID);

II) Leaderboard Manager

Manages team leaderboards and rankings.

ILeaderboardManager leaderboardManager = api.getLeaderboardManager();

// Open leaderboard GUI for a player
leaderboardManager.open(player);

// Get leaderboard data
ILeaderboard leaderboard = leaderboardManager.getLeaderboard();
List<Team> topTeams = leaderboard.getLeaderboardTeams();

👬 Working with Teams

I) ITeam Interface

The ITeam interface provides access to all team data and operations.

Basic Team Information:

Team team = teamManager.getTeam(player);

// Get team UUID
UUID teamUUID = team.getTeamUUID();

// Get team tag (both returns tag only)
String tag = team.getTag();
String displayName = team.getDisplayName();

// Set name and tag
team.setTag("[NEW]");

// Check name/tag
boolean hasName = team.hasName("TeamName");
boolean hasTag = team.hasTag("[TAG]");

String key   = team.getColorKey();   // selected color's config key, or null
team.setColorKey("red");             // set by config key
String color = team.getColor();      // resolved color code, "" if none
team.save();                         // setColorKey does NOT auto-save — call save()

Team Owner:

// Get owner
Owner owner = team.getOwner();
UUID ownerUUID = owner.getUuid();
String ownerName = owner.getUsername();

// Check if player is owner
boolean isOwner = team.isOwner(offlinePlayer);
boolean isOwnerByUuid = team.isOwnerByUuid(playerUUID);

Team Members:

// Get all members (including owner)
List<Member> allMembers = team.getAllMembers();

// Get members only (excluding owner)
List<Member> members = team.getMemberOnlyList();

// Get specific member
Member member = team.getMember(playerUUID);

// Check if team has member
boolean hasMember = team.hasMember(playerUUID);

// Add member
User user = api.getUserDatas().get(playerUUID);
team.addMember(user);

// Remove member
OfflineUser offlineUser = teamManager.getOfflineOrOnlineUser(playerUUID);
team.removeMember(offlineUser);

// Change member role
team.setRole(member, newRole);

// Check if team has online members
boolean hasOnline = team.hasOnlineMembers();

Member Roles and Permissions:

Member member = team.getMember(playerUUID);

// Get member's role
Role role = member.getRole();
String roleName = role.getName();
int priority = role.getPriority(); // Higher = more permissions, -1 = owner

// Check permissions
boolean canManageMembers = member.hasPermission(RolePermission.MANAGE_MEMBERS);
boolean canAccessBank = member.hasPermission(RolePermission.ACCESS_BANK);
boolean canSetHome = member.hasPermission(RolePermission.SET_HOME);

// Check promotion/demotion rights
Member targetMember = team.getMember(targetUUID);
boolean canPromote = member.canPromote(targetMember);
boolean canDemote = member.canDemote(targetMember);

Available Role Permissions:

  • MANAGE_MEMBERS - Invite/kick members, manage roles
  • MANAGE_ALLIANCE - Create/break alliances
  • ACCESS_BANK - Deposit/withdraw from team bank
  • ACCESS_ENDERCHEST - Access team shared inventory
  • USE_HOME - Teleport to team home
  • SET_HOME - Set team home location
  • SWITCH_FRIENDLY_FIRE - Toggle friendly fire

Team Alliances:

// Get ally list
List<UUID> allyUUIDs = team.getAllyList();
List<Team> allyTeams = team.getAllyTeams(); // This will retrieve the instances using the UUID

// Add alliance
Team otherTeam = teamManager.getByTag("[OTHER]");
team.addAlly(otherTeam); // Bidirectional

// Remove alliance
team.removeAlly(otherTeam); // Bidirectional

// Check if allied
boolean isAllied = team.isAlliedWith(otherTeam);

Team Bank:

// Get bank balance
double balance = team.getBankBalance();

// Set bank balance
team.setBankBalance(10000.0);

// Deposit to bank
boolean success = team.depositToBank(player, 500.0);

// Withdraw from bank
boolean success = team.withdrawFromBank(player, 250.0);

Team Home:

// Default home (still works)
Location home = team.getHome();
team.setHome(player.getLocation());
team.setHome(null);                 // remove the default home

// Named multi-homes
Map<String, Location> homes = team.getHomes();
Location base = team.getHome("base");
boolean added = team.addHome("base", player.getLocation()); // false if at the limit
team.removeHome("base");
int max = team.getMaxHomes();
boolean full = team.isHomesFull();

Team Inventory (Shared Enderchest):

// Get inventory
Inventory inventory = team.getInventory();

// Get as map
Map<Integer, ItemStack> items = team.getInventoryAsMap();
Map<Integer, ItemStack> enderchest = team.getEnderchestAsMap();

// Open for player
team.openEnderchest(player);

// Reload inventory
team.reloadInventory();

Team Statistics:

// Get total kills/deaths
int totalKills = team.getTotalKills();
int totalDeaths = team.getTotalDeaths();

// Get team rank and score
int rank = team.getRank(); // -1 if unranked
double score = team.getScore(); // -1 if no score

Team Settings:

// Friendly fire
boolean ffEnabled = team.isFriendlyFireEnabled();
team.setFriendlyFireEnabled(true);

// Check if team is closed/disbanded
boolean isClosed = team.isClosed();

// Save team data
team.save();

👨‍💻 Working with Users

I) User Statistics

OfflineUser user = teamManager.getOfflineOrOnlineUser(playerUUID);

// Get custom statistics
int kills = user.getStats(CustomStatistics.KILLS);
int deaths = user.getStats(CustomStatistics.DEATHS);
int blocksPlaced = user.getStats(CustomStatistics.BLOCKS_PLACED);
int blocksBroken = user.getStats(CustomStatistics.BLOCKS_BROKEN);
int mobsKilled = user.getStats(CustomStatistics.MOBS_KILLED);
int level = user.getStats(CustomStatistics.LEVEL);

// Modify statistics
user.addStats(CustomStatistics.KILLS, 1);
user.setStats(CustomStatistics.LEVEL, 50);

II) User Invitations

// Get pending team invitations
Map<Player, Long> mailbox = user.getMailbox();

// Get pending ally invitations
Map<Player, Long> allyMailbox = user.getAllyMailbox();

// Remove invitation
user.removeMailbox(inviterPlayer);
user.removeAllyMailbox(inviterPlayer);

// Get max team members
int maxMembers = user.getMaxMembers();

❤️‍🩹 Best Practices

  1. Always check for null: Teams and members can be null if they don't exist
  2. Do not use save(): You don’t need to use it in 99% of cases since all the set operations in ITeam are already saved.
  3. Handle closed teams: Check isClosed() before operating on teams
  4. Thread safety: Most operations are thread-safe, but use caution with concurrent modifications

🛠️ Support

For additional support or questions, contact us on our discord.