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:
Code (Java):
// 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:
Code (Java):
// 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:
Code (Java):
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.