TeamsAPI

The universal bridge between team plugins and everything else.

TeamsAPI is a passive, server-side bridge plugin for Paper, Spigot, Purpur, and Folia servers, inspired by Vault. It provides a single, stable interface for team operations, so any plugin that needs team data can work with any compatible team plugin, without either plugin knowing about the other.

Implemented in our refactored Factions fork: https://modrinth.com/plugin/pvpindex-factions

How it works

• Providers -- faction, clan, guild, or custom team plugins implement TeamsService and register with TeamsAPI during onEnable().
• Consumers -- scoreboard plugins, chat formatters, quest plugins, or any plugin that needs team data call TeamsAPI.getService() and use the returned interface.
• Server owners -- install TeamsAPI.jar and one compatible team plugin. Done.

No two plugins need to know about each other. When the team plugin changes, every consumer plugin keeps working without a recompile.

Features

• Provider-agnostic: works with any team plugin that ships a TeamsService implementation.
• Graceful fallback: if no provider is present, TeamsAPI.isAvailable() returns false; consumers can disable their team features cleanly instead of crashing.
• Read-only snapshots: Team and TeamMember are immutable interfaces; providers own the backing data.
• Role hierarchy: built-in OWNER > ADMIN > MEMBER with outranks() and canManage() helpers.
• Optional invite service: providers can expose TeamsInviteService for invitation workflows.
• Optional warp service: providers can expose TeamsWarpService for named team warps.
• Optional claim service: providers can expose TeamsClaimService for chunk-claim management, including SafeZone and WarZone territory support.
• Optional power service: providers can expose TeamsPowerService for player and team power values.
• Optional power-history service: providers can expose TeamsPowerHistoryService for reading and managing player/team power-history entries.
• Optional relation service: providers can expose TeamsRelationService for inter-team diplomacy (ally/truce/neutral/enemy).
• Optional notification service: providers can expose TeamsNotificationService for cross-plugin player notifications using built-in enum types and custom string types.
• Custom subcommands: any plugin registers a TeamsSubcommand via TeamsAPI.registerSubcommand(); team plugins call TeamsAPI.getSubcommands() in their own command handler to dispatch them, extending the command tree without coupling.
• Cancellable events: fifteen Bukkit events that providers can fire so other plugins can react to or cancel team operations.
• Lightweight: a single shaded JAR with no required runtime dependencies beyond the Bukkit API (optional: Vault for the built-in power shop).
• JitPack-ready: depend on just the API module at compile time; no transitive dependencies leak into your plugin.
• Velocity bridge (experimental): optional teams-api-velocity plugin for querying team data from the Velocity proxy. Supports multi-proxy networks via Redis.
• BungeeCord bridge (experimental): optional teams-api-bungeecord plugin for querying team data from BungeeCord / Waterfall proxies. Supports multi-proxy networks via Redis.

Requirements

Installation (server owners)

1. Download teams-api-plugin-VERSION.jar from the Files tab of this listing or from GitHub Releases.
2. Drop it into your server's plugins/ directory.
3. Install a compatible team plugin that provides a TeamsService implementation.
4. Restart the server.

TeamsAPI has no configuration files.

For developers

Add the API artifact to your project via JitPack:

Maven

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

<dependency>
    <groupId>com.github.ez-plugins</groupId>
    <artifactId>teams-api</artifactId>
    <version>2.1.0</version>
    <scope>provided</scope>
</dependency>

Gradle

repositories {
    maven { url 'https://jitpack.io' }
}
dependencies {
    compileOnly 'com.github.ez-plugins:teams-api:2.1.0'
}

Consumer quick-start

Declare the dependency in plugin.yml (use softdepend if team support is optional):

depend:
  - TeamsAPI

Then use the API at runtime:

@Override
public void onEnable() {
    if (!TeamsAPI.isAvailable()) {
        getLogger().warning("No team plugin found. Team features disabled.");
        return;
    }
    getLogger().info("TeamsAPI found. Team features enabled.");
}

// In a command or listener:
TeamsService teams = TeamsAPI.getService();
Optional<Team> team = teams.getPlayerTeam(player.getUniqueId());
team.ifPresent(t -> player.sendMessage("Your team: " + t.getDisplayName()));

Provider quick-start

Declare a soft-dependency in plugin.yml:

softdepend:
  - TeamsAPI

Register your implementation when the plugin loads:

@Override
public void onEnable() {
    TeamsAPI.registerProvider(this, new MyTeamsService(this));
}

@Override
public void onDisable() {
    TeamsAPI.unregisterProvider(teamsService);
}

API surface

Team lifecycle & lookup

Membership management

Invite service (optional)

Register alongside TeamsService if your plugin supports invitations:

TeamsAPI.registerInviteProvider(this, inviteService);

Consumers check availability with TeamsAPI.isInviteAvailable() before calling TeamsAPI.getInviteService().

Warp service (optional)

Register alongside TeamsService if your plugin supports team warps:

TeamsAPI.registerWarpProvider(this, warpService);

Consumers check availability with TeamsAPI.isWarpAvailable() before calling TeamsAPI.getWarpService().

Claim service (optional)

Register alongside TeamsService if your plugin supports chunk claims:

TeamsAPI.registerClaimProvider(this, claimService);

Consumers check availability with TeamsAPI.isClaimAvailable() before calling TeamsAPI.getClaimService().

Power service (optional)

Register alongside TeamsService if your plugin exposes power values:

TeamsAPI.registerPowerProvider(this, powerService);

Consumers check availability with TeamsAPI.isPowerAvailable() before calling TeamsAPI.getPowerService().

Power history service (optional)

Register alongside TeamsService if your plugin exposes power history:

TeamsAPI.registerPowerHistoryProvider(this, powerHistoryService);

Consumers check availability with TeamsAPI.isPowerHistoryAvailable() before calling TeamsAPI.getPowerHistoryService().

Relation service (optional)

Register alongside TeamsService if your plugin supports inter-team diplomacy:

TeamsAPI.registerRelationProvider(this, relationService);

TeamRelation values with display name, legacy color code, and hex color:

Consumers check availability with TeamsAPI.isRelationAvailable() before calling TeamsAPI.getRelationService().

Notification service (optional)

Register alongside TeamsService if your plugin supports cross-plugin player notifications:

TeamsAPI.registerNotificationProvider(this, notificationService);

Built-in TeamNotificationType values: GENERAL, TEAM_JOIN, TEAM_LEAVE, TEAM_INVITE, TEAM_INVITE_ACCEPT, TEAM_INVITE_DECLINE.

Consumers check availability with TeamsAPI.isNotificationAvailable() before calling TeamsAPI.getNotificationService().

Custom subcommands

Any plugin can register a TeamsSubcommand via TeamsAPI.registerSubcommand(). Team plugins call TeamsAPI.getSubcommands() in their own command executor to dispatch them, extending the command tree without any direct coupling between plugins.

Register in onEnable:

TeamsAPI.registerSubcommand(this, new MySubcommand());

Unregister in onDisable (Bukkit's ServicesManager also handles this automatically on plugin unload):

TeamsAPI.unregisterSubcommand(mySubcommand);

Commands & permissions

Events

All events live in com.skyblockexp.teamsapi.event. Providers are encouraged but not required to fire them.

Roles

Links

• GitHub -- source code & issue tracker
• Developer Guide -- full integration walkthrough
• API Reference -- complete method tables
• JitPack -- Maven / Gradle dependency

MIT License - free to use in any project, open- or closed-source.