Teams API

Non-breaking additions. No changes required for existing providers or consumers.

Added

Role prefix overrides

Consumers can now customise the display prefix for any built-in TeamRole constant at runtime:

// Override a single role
TeamRole.OWNER.setPrefixOverride("[Lord]");

// Read back: returns override when set, default otherwise
String prefix = TeamRole.OWNER.getPrefix(); // "[Lord]"

// Original default is always available
String def = TeamRole.OWNER.getDefaultPrefix(); // "Owner"

// Clear the override
TeamRole.OWNER.setPrefixOverride(null);

For bulk operations two static helpers are available:

// Apply multiple overrides at once (null value clears that role's override)
TeamRole.applyPrefixes(Map.of(
    TeamRole.OWNER, "[Lord]",
    TeamRole.ADMIN, "[Officer]"
));

// Clear all overrides for every built-in role
TeamRole.resetAllPrefixes();

New methods on TeamRole:

• getDefaultPrefix() - compile-time default prefix, unaffected by any override
• setPrefixOverride(String) - sets or clears (null) a JVM-wide prefix override
• applyPrefixes(Map<TeamRole, String>) - bulk-sets overrides from a map
• resetAllPrefixes() - clears overrides on every built-in role constant

getPrefix() now returns the override when set, otherwise the compile-time default. Existing calls to getPrefix() require no changes.

Custom role definitions and registry

Providers that model roles beyond the three built-in constants (OWNER, ADMIN, MEMBER) can now publish them through a server-wide registry:

// In your provider plugin's onEnable()
TeamRoleDefinition coOwner = new TeamRoleDefinition("co_owner", 75, "Co-Owner");
TeamsAPI.registerCustomRole(this, coOwner);

// In onDisable()
TeamsAPI.unregisterCustomRole("co_owner");

Consumers can look up or enumerate registered definitions:

// Look up by key
Optional<TeamRoleDefinition> role = TeamsAPI.getCustomRole("co_owner");

// Iterate all custom roles (sorted highest priority first)
for (TeamRoleDefinition def : TeamsAPI.getCustomRoles()) {
    getLogger().info(def.getKey() + " - priority " + def.getPriority());
}

// Test presence
if (TeamsAPI.isCustomRoleRegistered("co_owner")) { ... }

TeamRoleDefinition also supports prefix overrides via setPrefixOverride(String), matching the same pattern as TeamRole.

New methods on TeamsAPI:

• registerCustomRole(Plugin, TeamRoleDefinition) - publishes a custom role
• unregisterCustomRole(String) - removes a custom role by key
• getCustomRole(String) - looks up a definition by key, returns Optional
• getCustomRoles() - snapshot sorted by descending priority
• isCustomRoleRegistered(String) - tests presence by key

TeamMember.getRoleDefinition()

TeamMember now has a default method getRoleDefinition() that returns a TeamRoleDefinition wrapping the member's current built-in role:

TeamMember member = ...;
TeamRoleDefinition def = member.getRoleDefinition();
// def.getKey()      -> "owner" / "admin" / "member"
// def.getPriority() -> 100 / 50 / 10

Providers that register custom roles should override this method to return the precise custom definition for the member.

• TeamsAPI.API_VERSION updated to 2.4.0.

Migration

No behavioural changes for existing providers or consumers. getPrefix() still returns the same defaults ("Owner", "Admin", "Member") unless a plugin explicitly calls setPrefixOverride(...). The new getDefaultPrefix() method gives a stable, always-available fallback. The custom role registry starts empty; absence of a registered definition for a role key is a valid state.