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

Added
Convenience methods

• TeamsService.getTeamIds() - returns all team UUIDs for iteration without loading full team objects.
• Team.getOwner() - default method returning the owner's TeamMember record.
• VelocityTeam.getMemberUUIDs() - returns UUIDs of all members.
• VelocityTeam.getOwner() - default method returning the owner's record.

Role prefix reset
New resetPrefixOverride() method on both TeamRole and TeamRoleDefinition clears any active prefix override, restoring the built-in default:

Equivalent to calling setPrefixOverride(null).

• TeamsAPI.API_VERSION updated to 2.5.0.

Changed

• docs/api.md Team lookup section now correctly lists getTeam, getTeamByName, and getPlayerTeam alongside getAllTeams, getTeamCount, and getTeamIds.
• docs/velocity.md updated to document getMemberUUIDs() and getOwner() on VelocityTeam.

Migration
No behavioural changes for existing providers or consumers.

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:

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:

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:

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.

Added

• New optional TeamsChestService interface for team chest access: getChestIds(teamId), getContents(...), setContents(...), addItem(...), and removeItem(...).
• New TeamsAPI chest facade methods: getChestService(), isChestAvailable(), registerChestProvider(plugin, service), registerChestProvider(plugin, service, priority), and unregisterChestProvider(service).
• New API tests: TeamsAPIChestTest for chest provider registration, null-safety, priority registration, and service independence from core TeamsService.
• New docs pages: provider-chests (provider implementation/registration guidance) and consumer-chests (consumer usage patterns and fallback guards).

Changed

• TeamsAPI version bumped from 2.2.0 to 2.3.0 (non-breaking minor release).
• TeamsAPI.API_VERSION bumped to 2.3.0.
• README, API docs, provider/consumer guides, server guide, and public listings updated to include the optional chest capability and 2.3.0 dependency examples.

New: Official Provider Extensions

TeamsAPI 2.2.0 introduces three ready-to-use provider extensions. Each extension is bundled inside the main teams-api-plugin JAR and is automatically provisioned to:

plugins/TeamsAPI/extensions/

on first startup.

BetterTeams
teams-api-extension-betterteams

• Exposes teams, members, invites, warps, and ally/neutral relations through TeamsAPI.
• Invite support: invitePlayer and declineInvite work for offline players.
• acceptInvite requires the invitee to be online at the time of the call.
• Relation support covers ALLY and NEUTRAL.
• BetterTeams does not model enemies or truces.
• Supported relation constants: MEMBER, ALLY, NEUTRAL.

Towny Advanced
teams-api-extension-towny

• Maps Towny towns to TeamsAPI teams.
• Maps residents to members.
• Maps nation relationships such as allies and enemies to TeamsAPI relation constants.
• Claim lookup is fully supported.
• Claim and unclaim mutations are not exposed, because Towny manages its own chunk lifecycle.
• Supported relation constants: MEMBER, ALLY, ENEMY, NEUTRAL.
• TRUCE is normalized to NEUTRAL.

KingdomsX
teams-api-extension-kingdomsx

• Maps KingdomsX kingdoms to TeamsAPI teams.
• Maps KingdomsX members to TeamsAPI members.
• Maps diplomatic relations to TeamsAPI relation constants.
• Claim lookup is supported.
• Claim and unclaim mutations return false, because they require a live KingdomPlayer context that is not available through TeamsAPI.
• Power is read-only.
• getPlayerMaxPower and getTeamMaxPower always return 0.0, because KingdomsX does not expose a per-player power ceiling through its public API.
• Supported relation constants: MEMBER, ALLY, TRUCE, ENEMY, NEUTRAL.
• Relations are applied symmetrically.

New: Extension Management Commands

Command	Permission	Description
/teamsapi install <extension>	teamsapi.install - OP	Copies a bundled extension JAR to plugins/TeamsAPI/extensions/. Valid names: betterteams, towny, kingdomsx.
/teamsapi load <file>.jar	teamsapi.load - OP	Loads and enables an extension from plugins/TeamsAPI/extensions/ without requiring a server restart.

Installation Quick-Start

1. Install TeamsAPI and start the server once.
2. TeamsAPI automatically copies the bundled extension JARs to plugins/TeamsAPI/extensions/.
3. Make sure the matching team plugin is installed, such as BetterTeams, Towny Advanced, or KingdomsX.
4. Run /teamsapi install betterteams, /teamsapi install towny, or /teamsapi install kingdomsx to stage a provider extension.
5. Restart the server, or load the extension immediately with a command such as:
   /teamsapi load teams-api-extension-betterteams-2.2.0.jar

Documentation

Full details, supported features, and the complete provider feature matrix are available in the official Provider Catalog:

https://ez-plugins.github.io/teams-api/provider-catalog.html

Added

• Optional RelationNature enum (FRIENDLY, NEUTRAL, HOSTILE) to the model package. Each TeamRelation constant carries a built-in default nature which may be queried with getDefaultNature().
• Consumer override support: TeamRelation#setNatureOverride(RelationNature) and TeamRelation#getNature() - allows server or provider code to re-categorise a relation at runtime. Passing null to setNatureOverride clears the override and restores the builtin default. Overrides are visible JVM-wide because enum constants are singletons.
• Unit tests: TeamRelationTest covering default natures and override behaviour.

Changed

• TeamsAPI.API_VERSION bumped to 2.1.0.

Migration
No behavioural changes to existing TeamRelation helpers: isFriendly() and isHostile() remain unchanged and existing consumers require no changes. Providers that wish to reclassify relations (for example treating TRUCE as NEUTRAL) may call setNatureOverride(...) during initialisation.

Added

• TeamRelation.MEMBER constant (ordinal 4) representing the same-team relationship. Providers should return MEMBER from getRelation(A, A) when both team UUIDs are equal. Consumers comparing two players on potentially the same team will now receive a dedicated constant instead of NEUTRAL.
• TeamRelation internal hostilityLevel field. isMoreHostileThan() now uses this field instead of ordinal position, correctly placing MEMBER at hostility level -1 (less hostile than ALLY). Results for the original four constants are unchanged.
• isFriendly() now returns true for MEMBER in addition to ALLY and TRUCE.
• TeamsAPI.API_VERSION bumped to 2.0.0.

Changed

• ALLY default color: §a (green / #55FF55) → §b (aqua / #55FFFF). This aligns with the standard Factions color convention where green represents same-team membership.
• TRUCE default color: §6 (gold / #FFAA00) → §e (yellow / #FFFF55). Aligns legacy code character with MiniMessage <yellow>.

Migration
The four original ordinals (ALLY=0, TRUCE=1, NEUTRAL=2, ENEMY=3) are unchanged. Code that does not reference MEMBER and does not depend on the specific color values of ALLY or TRUCE requires no changes.

Consumers that use ALLY or TRUCE default colors (via getLegacyColorCode(), getDefaultHexColor(), or TeamsRelationService.getRelationColor()) should update their color expectations accordingly. Providers that configure their own colors via getRelationColor() overrides are unaffected.

Added

• TeamsPowerHistoryService optional extension interface for reading and managing power-history entries through TeamsAPI.
• New power-history model types: TeamPowerHistoryEntry and TeamPowerHistoryType (GAIN, LOSS, ADJUSTMENT).
• New TeamsAPI power-history facade methods: getPowerHistoryService(), isPowerHistoryAvailable(), registerPowerHistoryProvider(plugin, service), registerPowerHistoryProvider(plugin, service, priority), unregisterPowerHistoryProvider(service).
• New tests: TeamsAPIPowerHistoryTest (service registration/availability/null-safety) and TeamPowerHistoryTypeTest (enum contract coverage).
• TeamsAPI.API_VERSION bumped to 1.8.0.

Added

• TeamRelation.getDisplayName() — returns a human-friendly relation name ("Ally", "Truce", "Neutral", "Enemy").
• TeamRelation.getLegacyColorCode() — returns the legacy Minecraft color code character ('a' green, '6' gold, '7' gray, 'c' red) for use in chat formatting: "§" + relation.getLegacyColorCode().
• TeamRelation.getDefaultHexColor() — returns a #RRGGBB hex string suitable for Adventure / MiniMessage consumers (#55FF55, #FFAA00, #AAAAAA, #FF5555).
• TeamsRelationService.getTeamsInRelation(teamId, relation) — default convenience method that returns all team UUIDs toward which teamId has declared the given relation. Providers may override for a more efficient implementation.
• TeamsRelationService.getRelationColor(relation) — default method that returns the display color for a relation as a #RRGGBB hex string. Providers may override to supply server-configured colors; falls back to TeamRelation.getDefaultHexColor().
• TeamsAPI.API_VERSION bumped to 1.6.1.

Added

• TeamRelation enum (ALLY, TRUCE, NEUTRAL, ENEMY) — models the declared relationship one team holds toward another. Includes isFriendly(), isHostile(), and isMoreHostileThan(other) helpers.
• TeamsRelationService interface: optional extension service for inter-team relation management. Methods: setRelation(fromTeamId, toTeamId, relation, initiatorUUID), getRelation(fromTeamId, toTeamId) (defaults to NEUTRAL), getRelations(teamId) (returns all non-neutral relations as an unmodifiable map), clearRelations(teamId) (for use on team disband). Default methods: areAllies(teamAId, teamBId) (mutual ALLY required), areEnemies(teamAId, teamBId) (either side suffices).
• TeamRelationChangeEvent (cancellable): fired before a team's declared relation toward another changes. Exposes getTargetTeam(), getInitiatorUUID(), getOldRelation(), getNewRelation(), and setNewRelation() so listeners can override the incoming relation before it is persisted.
• TeamsAPI facade methods: getRelationService(), isRelationAvailable(), registerRelationProvider(plugin, service), registerRelationProvider(plugin, service, priority), unregisterRelationProvider(service).
• TeamsAPI.API_VERSION bumped to 1.6.0.

Added

• TeamsSubcommand interface: providers can register custom subcommands under /teamsapi <name> via TeamsAPI.registerSubcommand(plugin, subcommand). Each subcommand declares a getName(), getDescription(), optional getPermission(), and execute(CommandSender, String[]).
• TeamsAPI.registerSubcommand(plugin, subcommand) — registers via Bukkit ServicesManager.
• TeamsAPI.unregisterSubcommand(subcommand) — unregisters; call from onDisable.
• TeamsAPI.getSubcommands() — returns all registered subcommands as a snapshot.
• /teamsapi status — player-accessible (no admin permission required); shows the active provider, team count, and which optional services (invites, warps, claims, power) are registered.
• /teamsapi info now shows all five registered service types (TeamsService, InviteService, WarpService, ClaimService, PowerService) and the registered subcommand count.
• teamsapi.use permission (default: true) — basic access to /teamsapi.
• teamsapi.status permission (default: true) — access to /teamsapi status.
• PowerGainSource enum (PASSIVE, PURCHASE, GAMEPLAY, ADMIN) — identifies the origin of a power gain for use in events and listeners.
• PowerLossCause enum (DEATH, DECAY, ADMIN) — identifies the reason for a power loss.
• TeamPowerGainEvent (cancellable): fired before a player's power is increased. Listeners can modify the gain amount or cancel the event entirely.
• TeamPowerLossEvent (cancellable): fired before a player's power is decreased. Listeners can modify the loss amount or cancel the event entirely.
• TeamsPowerService#addPlayerPower(UUID, double) default method: adds power to a player clamped to their maximum; built on getPlayerPower/setPlayerPower.
• TeamsClaimService#isOverClaimed(UUID) default method: returns true when a team's claim count exceeds its power-gated maximum (power-negative state).
• config.yml in the plugin: opt-in passive-regen (periodic power gain for online players) and power-shop (buy power via /teamsapi power buy <n>).
• /teamsapi power status — shows the sender's current and max power.
• /teamsapi power buy <amount> — purchases power units with Vault economy (requires Vault and power-shop.enabled: true in config).
• teamsapi.power and teamsapi.power.buy permission nodes (default: op).
• Passive regen scheduler: when passive-regen.enabled: true, grants configurable power to every online team member on a configurable interval. Fires TeamPowerGainEvent; skips if cancelled. Folia-compatible via GlobalRegionScheduler.
• Passive regen and power shop are both Folia-compatible. Folia is detected at runtime; GlobalRegionScheduler is used on Folia and BukkitScheduler on Paper / Spigot.

Changed

• /teamsapi now requires teamsapi.use; senders without it receive a permission error instead of the help message.
• /teamsapi status now requires teamsapi.status.
• /teamsapi info now requires teamsapi.admin.
• /teamsapi help (and the bare /teamsapi) only lists subcommands that the sender has permission to execute.

Plugin

• Expanded platform support: Spigot, Purpur, and Folia 1.16+ declared alongside Paper.
• plugin.yml api-version: '1.16' and folia-supported: true.
• Multi-Release JAR: base classes compiled at Java 17; versioned classes at Java 25.
• TeamsAPI.API_VERSION bumped to 1.3.0.
• Publish workflow builds all JARs, deploys API artifact to GitHub Packages, creates a GitHub Release, and uploads to Modrinth.

Velocity Bridge

• New teams-api-velocity module: Velocity proxy bridge. Proxy-side plugins can query team data asynchronously via VelocityTeamsAPI, VelocityTeamsService, VelocityTeam, VelocityTeamMember, and VelocityTeamRole.
• Redis multi-proxy support: optional Redis Pub/Sub bridge (redis.enabled: true in config.yml). Queries that cannot be fulfilled locally are forwarded to another proxy in the network, enabling cross-proxy team queries across multiple Velocity instances behind a shared Redis server.
• config.yml generated on first startup. Configurable: Redis host, port, password, database, key prefix, connection pool sizes, socket timeout, and query timeout.
• Query timeout configurable via query.timeout-seconds (default 5 s).

BungeeCord Bridge

• New teams-api-bungeecord module: BungeeCord / Waterfall proxy bridge. Mirrors the Velocity bridge via BungeeTeamsAPI, BungeeTeamsService, BungeeTeam, BungeeTeamMember, and BungeeTeamRole.
• Redis multi-proxy support: optional Redis Pub/Sub bridge (redis.enabled: true in config.yml). Queries that cannot be fulfilled locally are forwarded to another proxy in the network, enabling cross-proxy team queries across multiple BungeeCord instances behind a shared Redis server.
• config.yml generated on first startup. Configurable: Redis host, port, password, database, key prefix, connection pool sizes, socket timeout, and query timeout.
• Query timeout configurable via query.timeout-seconds (default 5 s).

JitPack does not set the working directory to the project root for install commands, so ./mvnw failed with 'No such file or directory'. Restore the explicit 'cd $HOME/build &&' prefix from the original.

Version: 1.2.1 -> 1.2.2 (patch; build-system fix, no API changes)

jitpack.yml:

• Clone MockBukkit from minecraft/v26 (dev/26.1.1 was deleted)
• Capture dynamic version via git rev-parse and write to /tmp/mb-version.txt
• Pass -Dmockbukkit.version=dev-$(cat /tmp/mb-version.txt) to mvnw so Maven resolves the correct local artifact instead of 0.0.0-unset

Version: 1.2.0 -> 1.2.1 (patch; build-system fix, no API changes)

What's new in 1.1.0 - Team Invite API

New: TeamsInviteService interface

An optional, independent service interface for team invitation flows.

Providers that support invitations register an implementation separately via TeamsAPI.registerInviteProvider(). Existing TeamsService implementations are not required to support it. The API degrades gracefully when no invite provider is registered.

Methods

Method	Returns	Description
invitePlayer(UUID teamId, UUID inviterUUID, UUID inviteeUUID)	boolean	Invites a player to join a team
acceptInvite(UUID teamId, UUID playerUUID)	Optional<Team>	Accepts a pending team invitation
declineInvite(UUID teamId, UUID playerUUID)	boolean	Declines a pending team invitation

New: invite provider management on TeamsAPI

Method	Description
TeamsAPI.getInviteService()	Returns the registered TeamsInviteService, or null
TeamsAPI.isInviteAvailable()	Returns true if an invite provider is registered
TeamsAPI.registerInviteProvider(Plugin, TeamsInviteService)	Registers an invite provider at Normal priority
TeamsAPI.registerInviteProvider(Plugin, TeamsInviteService, ServicePriority)	Registers an invite provider at a custom priority
TeamsAPI.unregisterInviteProvider(TeamsInviteService)	Unregisters the invite provider on plugin disable

All methods follow the existing null-safety contract. Null arguments are silently ignored.

New events

Event	Cancellable	When fired
TeamInviteEvent	Yes	Before an invitation is recorded. Cancel to block it.
TeamInviteAcceptEvent	No	After the player has joined the team.
TeamInviteDeclineEvent	No	After the pending invitation has been removed.