
团队插件与其他一切之间的通用桥梁。
TeamsAPI 是一个被动的、服务端桥接插件,适用于 Paper、Spigot、Purpur 和 Folia 服务器,灵感源自 Vault。它提供了一个单一且稳定的接口来处理团队操作,因此任何需要团队数据的插件都可以与任何兼容的团队插件配合工作,而无需这两个插件互相知晓对方。
在我们的重构版 Factions fork 中实现:
工作原理

- Providers(提供方) - 派系、氏族、公会或自定义团队插件
implement TeamsService
并在 onEnable() 期间向 TeamsAPI 注册。
- Consumers(消费方) - 记分板插件、聊天格式化器、任务插件或任何需要
团队数据的插件调用
TeamsAPI.getService() 并使用返回的接口。
- Server owners(服务器管理员) - 安装
TeamsAPI.jar 和一个兼容的团队插件。完成。
两个插件之间无需互相了解。当团队插件发生变化时,每个
消费方插件都能继续正常工作,无需重新编译。
功能特性
- 官方扩展:提供现成的提供方桥接插件,包括 BetterTeams、Towny Advanced 和 KingdomsX,打包在主 JAR 内。在游戏中使用
/teamsapi install <name> 安装。
- Provider-agnostic(提供方无关性):可与任何附带
TeamsService 实现的团队插件配合使用。
- 优雅降级:如果没有提供方存在,
TeamsAPI.isAvailable() 返回 false;消费方可以干净地禁用其团队功能,而不是崩溃。
- 只读快照:
Team 和 TeamMember 是不可变接口;提供方拥有底层数据。
- 角色层级:内置
OWNER > ADMIN > MEMBER 以及 outranks() 和 canManage() 辅助方法。
- 可选邀请服务:提供方可以暴露
TeamsInviteService 以支持邀请工作流程。
- 可选传送点服务:提供方可以暴露
TeamsWarpService 以支持命名团队传送点。
- 可选箱子服务:提供方可以暴露
TeamsChestService 以支持团队箱子内容和添加/移除操作。
- 可选领地服务:方块可以暴露
TeamsClaimService 以支持区块管理,包括 SafeZone 和 WarZone 领土支持。
- 可选战力服务:提供方可以暴露
TeamsPowerService 以支持玩家和团队的战力值。
- 可选战力历史服务:提供方可以暴露
TeamsPowerHistoryService
以读取和管理玩家/团队的战力历史记录条目。
- 可选关系服务:提供方可以暴露
TeamsRelationService 以支持团队间的外交关系(盟友/休战/中立/敌人)。
- 可选通知服务:提供方可以暴露
TeamsNotificationService 以支持
跨插件的玩家通知,使用内置枚举类型和自定义字符串类型。
- 自定义子命令:任何插件都通过
TeamsAPI.registerSubcommand() 注册一个 TeamsSubcommand;团队插件在自己的命令处理器中调用 TeamsAPI.getSubcommands() 来分发它们,从而在不耦合的情况下扩展命令树。
- 可取消事件:十五个 Bukkit 事件,提供方可以触发这些事件,以便其他插件可以响应或取消团队操作。
- 轻量级:单个阴影 JAR,除了 Bukkit API 外没有所需的运行时依赖项(可选:Vault 用于内置战力商店)。
- JitPack 就绪:仅在编译时依赖 API 模块;没有传递性依赖泄漏到你的插件中。
- Velocity 桥接 (实验性):可选的
teams-api-velocity 插件,用于从 Velocity 代理查询团队数据。支持通过 Redis 的多代理网络。
- BungeeCord 桥接 (实验性):可选的
teams-api-bungeecord 插件,用于从 BungeeCord / Waterfall 代理查询团队数据。支持通过 Redis 的多代理网络。
要求
| 要求 |
值 |
| 服务器软件 |
Paper / Spigot / Purpur / Folia 1.16+ |
| Java |
17+ (推荐 25) |
| 插件依赖 |
无 (可选:Vault 用于战力商店) |
安装(服务器管理员)
- 从此列表的 Files 选项卡或 GitHub Releases 下载
teams-api-plugin-VERSION.jar。
- 将其放入服务器的
plugins/ 目录中。
- 安装一个兼容的团队插件。官方扩展包括
BetterTeams、
Towny Advanced 和
KingdomsX,已打包在
TeamsAPI 内部。在游戏中运行
/teamsapi install betterteams(或 towny / kingdomsx),
或者让 TeamsAPI 自动将它们配置到 plugins/TeamsAPI/extensions/。
- 重启服务器。
TeamsAPI 没有配置文件。
对于开发者
通过 JitPack 将 API 工件添加到你的项目中:
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.3.0</version>
<scope>provided</scope>
</dependency>
Gradle
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
compileOnly 'com.github.ez-plugins:teams-api:2.3.0'
}
消费者快速入门
在 plugin.yml 中声明依赖(如果团队支持是可选的,请使用 softdepend):
depend:
- TeamsAPI
然后在运行时使用 API:
@Override
public void onEnable() {
if (!TeamsAPI.isAvailable()) {
getLogger().warning("未找到团队插件。团队功能已禁用。");
return;
}
getLogger().info("找到 TeamsAPI。团队功能已启用。");
}
// 在命令或监听器中:
TeamsService teams = TeamsAPI.getService();
Optional<Team> team = teams.getPlayerTeam(player.getUniqueId());
team.ifPresent(t -> player.sendMessage("你的团队: " + t.getDisplayName()));
提供者快速入门
在 plugin.yml 中声明软依赖:
softdepend:
- TeamsAPI
在插件加载时注册你的实现:
@Override
public void onEnable() {
TeamsAPI.registerProvider(this, new MyTeamsService(this));
}
@Override
public void onDisable() {
TeamsAPI.unregisterProvider(teamsService);
}
API 接口
团队生命周期与查找
| 方法 |
返回类型 |
描述 |
createTeam(name, ownerUUID) |
Optional<Team> |
创建新团队 |
deleteTeam(teamId) |
boolean |
通过 UUID 删除团队 |
getTeam(teamId) |
Optional<Team> |
通过 UUID 查找团队 |
getTeamByName(name) |
Optional<Team> |
通过名称查找团队 |
getPlayerTeam(playerUUID) |
Optional<Team> |
返回玩家当前的团队 |
getAllTeams() |
Collection<Team> |
返回所有已注册的团队 |
getTeamCount() |
int |
团队总数 |
成员管理
| 方法 |
返回类型 |
描述 |
addMember(teamId, playerUUID, role) |
boolean |
添加具有特定角色的玩家 |
removeMember(teamId, playerUUID) |
boolean |
从团队中移除玩家 |
setMemberRole(teamId, playerUUID, role) |
boolean |
更改成员的职位 |
getMemberRole(teamId, playerUUID) |
Optional<TeamRole> |
返回成员当前的职位 |
邀请服务(可选)
如果你的插件支持邀请功能,请将其与 TeamsService 一起注册:
TeamsAPI.registerInviteProvider(this, inviteService);
| 方法 |
返回类型 |
描述 |
invitePlayer(teamId, inviterUUID, inviteeUUID) |
boolean |
发送邀请 |
acceptInvite(teamId, playerUUID) |
Optional<Team> |
接受邀请并加入团队 |
declineInvite(teamId, playerUUID) |
boolean |
拒绝邀请 |
调用 TeamsAPI.getInviteService() 之前,消费者应使用 TeamsAPI.isInviteAvailable() 检查可用性。
传送点服务(可选)
如果你的插件支持团队传送点,请将其与 TeamsService 一起注册:
TeamsAPI.registerWarpProvider(this, warpService);
| 方法 |
返回类型 |
描述 |
setWarp(teamId, name, location, creatorUUID) |
boolean |
创建或更新命名传送点 |
removeWarp(teamId, name) |
boolean |
通过名称删除传送点 |
getWarp(teamId, name) |
Optional<TeamWarp> |
通过名称查找传送点 |
getWarps(teamId) |
Collection<TeamWarp> |
返回团队的所有传送点 |
调用 TeamsAPI.getWarpService() 之前,消费者应使用 TeamsAPI.isWarpAvailable() 检查可用性。
箱子服务(可选)
如果你的插件支持团队箱子操作,请将其与 TeamsService 一起注册:
TeamsAPI.registerChestProvider(this, chestService);
| 方法 |
返回类型 |
描述 |
getChestIds(teamId) |
Collection<String> |
返回团队可用的箱子标识符 |
getContents(teamId) |
Collection<ItemStack> |
返回默认箱子的内容 |
getContents(teamId, chestId) |
Collection<ItemStack> |
返回特定箱子标识符的内容 |
setContents(teamId, contents) |
boolean |
替换默认箱子的内容 |
setContents(teamId, chestId, contents) |
boolean |
替换特定箱子标识符的内容 |
addItem(teamId, item) |
boolean |
向默认箱子添加一个物品堆 |
addItem(teamId, chestId, item) |
boolean |
向特定箱子标识符添加一个物品堆 |
removeItem(teamId, item) |
boolean |
从默认箱子移除一个匹配的物品堆 |
removeItem(teamId, chestId, item) |
boolean |
从特定箱子标识符移除一个匹配的物品堆 |
调用 TeamsAPI.getChestService() 之前,消费者应使用 TeamsAPI.isChestAvailable() 检查可用性。
领地服务(可选)
如果你的插件支持区块认领,请将其与 TeamsService 一起注册:
TeamsAPI.registerClaimProvider(this, claimService);
| 方法 |
返回类型 |
描述 |
claimChunk(teamId, playerUUID, world, x, z) |
boolean |
为团队认领一个区块 |
unclaimChunk(teamId, playerUUID, world, x, z) |
boolean |
取消认领 |
unclaimAll(teamId) |
boolean |
移除团队的所有认领 |
getClaimAt(world, x, z) |
Optional<TeamClaim> |
返回指定区块的认领信息(如果有) |
getTeamClaims(teamId) |
Collection<TeamClaim> |
团队的所有认领 |
getClaimCount(teamId) |
int |
已认领的区块数量 |
isClaimed(world, x, z) |
boolean |
该区块是否被任何人认领 |
isClaimedBy(teamId, world, x, z) |
boolean |
该区块是否被此团队认领 |
getTerritoryTypeAt(world, x, z) |
ClaimTerritoryType |
返回 WILDERNESS(荒野)、TEAM(团队)、SAFE_ZONE(安全区)或 WAR_ZONE(战争区) |
isSafeZone(world, x, z) |
boolean |
该区块是否为安全区 |
isWarZone(world, x, z) |
boolean |
该区块是否为战争区 |
getTeamMaxClaims(teamId) |
int |
认领上限(-1 表示无限制) |
消费者在调用 TeamsAPI.getClaimService() 之前,应先使用 TeamsAPI.isClaimAvailable() 检查可用性。
能量服务(可选)
如果您的插件提供能量值,请与 TeamsService 一同注册:
TeamsAPI.registerPowerProvider(this, powerService);
| 方法 |
返回值 |
描述 |
getPlayerPower(playerUUID) |
double |
玩家当前的能量值 |
getPlayerMaxPower(playerUUID) |
double |
玩家能持有的最大能量值 |
setPlayerPower(playerUUID, power) |
boolean |
设置玩家的能量值 |
getTeamPower(teamId) |
double |
所有团队成员的能量总和 |
getTeamMaxPower(teamId) |
double |
团队能持有的最大能量总和 |
消费者在调用 TeamsAPI.getPowerService() 之前,应先使用 TeamsAPI.isPowerAvailable() 检查可用性。
能量历史记录服务(可选)
如果您的插件提供能量历史记录,请与 TeamsService 一同注册:
TeamsAPI.registerPowerHistoryProvider(this, powerHistoryService);
| 方法 |
返回值 |
描述 |
getPlayerPowerHistory(playerUUID, limit) |
Collection<TeamPowerHistoryEntry> |
玩家最近的记录,按时间倒序排列。 |
getPlayerPowerHistory(playerUUID, fromInclusive, toExclusive, limit) |
Collection<TeamPowerHistoryEntry> |
指定时间窗口内的玩家记录,按时间倒序排列。 |
getTeamPowerHistory(teamId, limit) |
Collection<TeamPowerHistoryEntry> |
与特定团队关联的最近记录。 |
addPowerHistoryEntry(entryId, playerUUID, teamId, delta, type, reason, actorUUID, occurredAt, details) |
boolean |
插入一条历史记录。 |
updatePowerHistoryEntry(entryId, delta, type, reason, actorUUID, occurredAt, details) |
boolean |
更新现有记录。 |
removePowerHistoryEntry(entryId) |
boolean |
通过 ID 删除一条记录。 |
clearPlayerPowerHistory(playerUUID) |
int |
删除该玩家的所有记录;返回被删除的数量。 |
clearTeamPowerHistory(teamId) |
int |
删除与该团队相关的所有记录;返回被删除的数量。 |
消费者在调用 TeamsAPI.getPowerHistoryService() 之前,应先使用 TeamsAPI.isPowerHistoryAvailable() 检查可用性。
关系服务(可选)
如果您的插件支持团队间的外交关系,请与 TeamsService 一同注册:
TeamsAPI.registerRelationProvider(this, relationService);
| 方法 |
返回值 |
描述 |
setRelation(fromTeamId, toTeamId, relation, initiatorUUID) |
boolean |
声明一个团队对另一个团队的关系。触发 TeamRelationChangeEvent;如果被取消则返回 false。设置为 NEUTRAL 将移除该关系。 |
getRelation(fromTeamId, toTeamId) |
TeamRelation |
返回已声明的关系(如果未设置,默认为 NEUTRAL)。 |
getRelations(teamId) |
Map<UUID, TeamRelation> |
该团队声明的所有非中立关系。 |
clearRelations(teamId) |
boolean |
移除由该团队声明或指向该团队的所有关系(解散团队时使用)。 |
areAllies(teamAId, teamBId) |
boolean |
当两个团队互相声明为 ALLY 时返回 true。 |
areEnemies(teamAId, teamBId) |
boolean |
当任一团队向另一团队声明为 ENEMY 时返回 true。 |
getTeamsInRelation(teamId, relation) |
Collection<UUID> |
返回 teamId 声明了给定关系的所有团队 UUID。通过对 getRelations(teamId) 的结果按值过滤实现;提供者可能为了效率而重写此方法。 |
getRelationColor(relation) |
String |
关系的 #RRGGBB 十六进制颜色代码。默认返回 relation.getDefaultHexColor();提供者可以重写以提供服务器配置的颜色。 |
TeamRelation 枚举值及其显示名称、旧版颜色代码和十六进制颜色:
| 常量 |
显示名称 |
旧版颜色代码 |
十六进制颜色 |
ALLY |
"Ally" |
§a (绿色) |
#55FF55 |
TRUCE |
"Truce" |
§6 (金色) |
#FFAA00 |
NEUTRAL |
"Neutral" |
§7 (灰色) |
#AAAAAA |
ENEMY |
"Enemy" |
§c (红色) |
#FF5555 |
消费者在调用 TeamsAPI.getRelationService() 之前,应先使用 TeamsAPI.isRelationAvailable() 检查可用性。
通知服务(可选)
如果您的插件支持跨插件的玩家通知功能,请与 TeamsService 一同注册:
TeamsAPI.registerNotificationProvider(this, notificationService);
| 方法 |
返回值 |
描述 |
sendNotification(senderPlugin, recipientUUID, type, message) |
boolean |
使用内置的 TeamNotificationType 发送通知。 |
sendNotification(senderPlugin, recipientUUID, notificationType, message) |
boolean |
使用自定义字符串类型(非空、非空白)发送通知。 |
isNotificationEnabled(playerUUID, type) |
boolean |
该内置通知类型是否对该玩家启用。 |
isNotificationEnabled(playerUUID, notificationType) |
boolean |
该自定义字符串通知类型是否对该玩家启用。 |
setNotificationEnabled(playerUUID, type, enabled) |
boolean |
为该玩家启用或禁用某个内置通知类型。 |
setNotificationEnabled(playerUUID, notificationType, enabled) |
boolean |
为该玩家启用或禁用某个自定义字符串通知类型。 |
内置 TeamNotificationType 枚举值:
GENERAL, TEAM_JOIN, TEAM_LEAVE, TEAM_INVITE,
TEAM_INVITE_ACCEPT, TEAM_INVITE_DECLINE.
消费者在调用 TeamsAPI.getNotificationService() 之前,应先使用 TeamsAPI.isNotificationAvailable() 检查可用性。
自定义子命令
任何插件都可以通过 TeamsAPI.registerSubcommand() 注册一个 TeamsSubcommand。团队插件在其自身的命令执行器中调用 TeamsAPI.getSubcommands() 来分发这些子命令,从而扩展命令树,且插件之间无需直接耦合。
在 onEnable 中注册:
TeamsAPI.registerSubcommand(this, new MySubcommand());
在 onDisable 中注销(Bukkit 的 ServicesManager 也会在插件卸载时自动处理此操作):
TeamsAPI.unregisterSubcommand(mySubcommand);
| 方法 |
返回值 |
描述 |
getName() |
String |
与 args[0] 进行不区分大小写的匹配 |
getDescription() |
String |
帮助输出中的可选描述 |
getPermission() |
String |
所需权限,若为 null 则无需检查 |
execute(sender, args) |
boolean |
当子命令被分发时调用;返回 false 以显示用法提示 |
getUsage() |
String |
当 execute 返回 false 时发送的用法提示 |
tabComplete(sender, args) |
List<String> |
Tab 补全建议;默认:空列表 |
命令与权限
| 子命令 |
权限 |
默认值 |
描述 |
/teamsapi / /teamsapi help |
teamsapi.use |
everyone |
列出发送者可以使用的命令 |
/teamsapi version |
teamsapi.use |
everyone |
打印插件和 API 版本 |
/teamsapi status |
teamsapi.status |
everyone |
当前活动提供者、队伍数量、已注册服务 |
/teamsapi info |
teamsapi.admin |
op |
完整的内部诊断信息 |
/teamsapi power status |
teamsapi.power |
op |
发送者当前的及最大力量值 |
/teamsapi power buy <n> |
teamsapi.power.buy |
disabled |
默认禁用;需在 config.yml 中设置 power-shop.enabled: true 启用。需要 Vault。 |
/teamsapi install <extension> |
teamsapi.install |
op |
将捆绑的扩展 JAR 文件复制到 plugins/TeamsAPI/extensions/。有效名称:betterteams、towny、kingdomsx。 |
/teamsapi load <file>.jar |
teamsapi.load |
op |
从 plugins/TeamsAPI/extensions/ 加载并启用一个扩展,无需重启服务器。 |
事件
所有事件位于 com.skyblockexp.teamsapi.event 包下。提供者可自行选择是否触发这些事件。
| 事件 |
可取消 |
触发时机 |
TeamCreateEvent |
是 |
在创建队伍之前 |
TeamDeleteEvent |
是 |
在删除队伍之前 |
TeamJoinEvent |
是 |
在玩家加入队伍之前 |
TeamLeaveEvent |
是 |
在玩家离开队伍之前 |
TeamRoleChangeEvent |
是 |
在成员角色变更之前 |
TeamInviteEvent |
是 |
在发送邀请之前 |
TeamInviteAcceptEvent |
否 |
在玩家接受邀请之后 |
TeamInviteDeclineEvent |
否 |
在玩家拒绝邀请之后 |
TeamWarpSetEvent |
是 |
在创建或更新传送点之前 |
TeamWarpDeleteEvent |
是 |
在删除传送点之前 |
TeamClaimEvent |
是 |
在占领区块之前 |
TeamUnclaimEvent |
是 |
在放弃占领区块之前 |
角色
| 角色 |
优先级 |
描述 |
OWNER |
100 |
完全控制权;不能被他人移除 |
ADMIN |
50 |
可以管理优先级较低成员的权限 |
MEMBER |
10 |
普通队员 |
链接
MIT 许可证 - 可在任何项目(开源或闭源)中自由使用。

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:
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
- Official extensions: ready-to-use provider bridges for BetterTeams, Towny Advanced, and KingdomsX, bundled inside the main JAR. Install in-game with
/teamsapi install <name>.
- 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 chest service: providers can expose
TeamsChestService for team chest contents and add/remove operations.
- 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
| Requirement |
Value |
| Server software |
Paper / Spigot / Purpur / Folia 1.16+ |
| Java |
17+ (25 recommended) |
| Plugin dependencies |
None (optional: Vault for power shop) |
Installation (server owners)
- Download
teams-api-plugin-VERSION.jar from the Files tab of this listing or
from GitHub Releases.
- Drop it into your server's
plugins/ directory.
- Install a compatible team plugin. Official extensions for
BetterTeams,
Towny Advanced, and
KingdomsX are bundled
inside TeamsAPI. Run
/teamsapi install betterteams (or towny / kingdomsx)
in-game, or let TeamsAPI provision them automatically to plugins/TeamsAPI/extensions/.
- 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.3.0</version>
<scope>provided</scope>
</dependency>
Gradle
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
compileOnly 'com.github.ez-plugins:teams-api:2.3.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
| Method |
Returns |
Description |
createTeam(name, ownerUUID) |
Optional<Team> |
Creates a new team |
deleteTeam(teamId) |
boolean |
Deletes a team by UUID |
getTeam(teamId) |
Optional<Team> |
Looks up a team by UUID |
getTeamByName(name) |
Optional<Team> |
Looks up a team by name |
getPlayerTeam(playerUUID) |
Optional<Team> |
Returns the player's current team |
getAllTeams() |
Collection<Team> |
Returns every registered team |
getTeamCount() |
int |
Total number of teams |
Membership management
| Method |
Returns |
Description |
addMember(teamId, playerUUID, role) |
boolean |
Adds a player with a given role |
removeMember(teamId, playerUUID) |
boolean |
Removes a player from the team |
setMemberRole(teamId, playerUUID, role) |
boolean |
Changes a member's role |
getMemberRole(teamId, playerUUID) |
Optional<TeamRole> |
Returns the member's current role |
Invite service (optional)
Register alongside TeamsService if your plugin supports invitations:
TeamsAPI.registerInviteProvider(this, inviteService);
| Method |
Returns |
Description |
invitePlayer(teamId, inviterUUID, inviteeUUID) |
boolean |
Sends an invitation |
acceptInvite(teamId, playerUUID) |
Optional<Team> |
Accepts the invitation and joins the team |
declineInvite(teamId, playerUUID) |
boolean |
Declines an invitation |
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);
| Method |
Returns |
Description |
setWarp(teamId, name, location, creatorUUID) |
boolean |
Creates or updates a named warp |
removeWarp(teamId, name) |
boolean |
Deletes a warp by name |
getWarp(teamId, name) |
Optional<TeamWarp> |
Looks up a warp by name |
getWarps(teamId) |
Collection<TeamWarp> |
Returns all warps for a team |
Consumers check availability with TeamsAPI.isWarpAvailable() before calling TeamsAPI.getWarpService().
Chest service (optional)
Register alongside TeamsService if your plugin supports team chest operations:
TeamsAPI.registerChestProvider(this, chestService);
| Method |
Returns |
Description |
getChestIds(teamId) |
Collection<String> |
Returns available chest identifiers for the team |
getContents(teamId) |
Collection<ItemStack> |
Returns the default chest contents |
getContents(teamId, chestId) |
Collection<ItemStack> |
Returns contents for a specific chest identifier |
setContents(teamId, contents) |
boolean |
Replaces the default chest contents |
setContents(teamId, chestId, contents) |
boolean |
Replaces contents for a specific chest identifier |
addItem(teamId, item) |
boolean |
Adds one item stack to the default chest |
addItem(teamId, chestId, item) |
boolean |
Adds one item stack to a specific chest identifier |
removeItem(teamId, item) |
boolean |
Removes one matching item stack from the default chest |
removeItem(teamId, chestId, item) |
boolean |
Removes one matching item stack from a specific chest identifier |
Consumers check availability with TeamsAPI.isChestAvailable() before calling TeamsAPI.getChestService().
Claim service (optional)
Register alongside TeamsService if your plugin supports chunk claims:
TeamsAPI.registerClaimProvider(this, claimService);
| Method |
Returns |
Description |
claimChunk(teamId, playerUUID, world, x, z) |
boolean |
Claims a chunk for the team |
unclaimChunk(teamId, playerUUID, world, x, z) |
boolean |
Removes the claim |
unclaimAll(teamId) |
boolean |
Removes all claims for the team |
getClaimAt(world, x, z) |
Optional<TeamClaim> |
Returns the claim at a chunk, if any |
getTeamClaims(teamId) |
Collection<TeamClaim> |
All claims for the team |
getClaimCount(teamId) |
int |
Number of claimed chunks |
isClaimed(world, x, z) |
boolean |
Whether the chunk is claimed by anyone |
isClaimedBy(teamId, world, x, z) |
boolean |
Whether the chunk is claimed by this team |
getTerritoryTypeAt(world, x, z) |
ClaimTerritoryType |
Returns WILDERNESS, TEAM, SAFE_ZONE, or WAR_ZONE |
isSafeZone(world, x, z) |
boolean |
Whether the chunk is a SafeZone |
isWarZone(world, x, z) |
boolean |
Whether the chunk is a WarZone |
getTeamMaxClaims(teamId) |
int |
Claim limit (-1 means unlimited) |
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);
| Method |
Returns |
Description |
getPlayerPower(playerUUID) |
double |
Current power of the player |
getPlayerMaxPower(playerUUID) |
double |
Maximum power the player can hold |
setPlayerPower(playerUUID, power) |
boolean |
Sets the player's power |
getTeamPower(teamId) |
double |
Combined power of all team members |
getTeamMaxPower(teamId) |
double |
Maximum combined power the team can hold |
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);
| Method |
Returns |
Description |
getPlayerPowerHistory(playerUUID, limit) |
Collection<TeamPowerHistoryEntry> |
Recent entries for a player, newest first. |
getPlayerPowerHistory(playerUUID, fromInclusive, toExclusive, limit) |
Collection<TeamPowerHistoryEntry> |
Player entries in a time window, newest first. |
getTeamPowerHistory(teamId, limit) |
Collection<TeamPowerHistoryEntry> |
Recent entries linked to a team. |
addPowerHistoryEntry(entryId, playerUUID, teamId, delta, type, reason, actorUUID, occurredAt, details) |
boolean |
Inserts a history entry. |
updatePowerHistoryEntry(entryId, delta, type, reason, actorUUID, occurredAt, details) |
boolean |
Updates an existing entry. |
removePowerHistoryEntry(entryId) |
boolean |
Deletes one entry by ID. |
clearPlayerPowerHistory(playerUUID) |
int |
Deletes all player entries; returns removed count. |
clearTeamPowerHistory(teamId) |
int |
Deletes all team-linked entries; returns removed count. |
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);
| Method |
Returns |
Description |
setRelation(fromTeamId, toTeamId, relation, initiatorUUID) |
boolean |
Declares a relation from one team toward another. Fires TeamRelationChangeEvent; returns false if cancelled. Setting NEUTRAL removes the relation. |
getRelation(fromTeamId, toTeamId) |
TeamRelation |
Returns the declared relation (defaults to NEUTRAL if none is set). |
getRelations(teamId) |
Map<UUID, TeamRelation> |
All non-neutral relations declared by the team. |
clearRelations(teamId) |
boolean |
Removes all relations declared by or toward the team (use on disband). |
areAllies(teamAId, teamBId) |
boolean |
Returns true when both teams have declared ALLY toward each other. |
areEnemies(teamAId, teamBId) |
boolean |
Returns true when either team has declared ENEMY toward the other. |
getTeamsInRelation(teamId, relation) |
Collection<UUID> |
Returns all team UUIDs toward which teamId has declared the given relation. Filters getRelations(teamId) by value; providers may override for efficiency. |
getRelationColor(relation) |
String |
#RRGGBB hex color for the relation. Default returns relation.getDefaultHexColor(); providers may override to supply server-configured colors. |
TeamRelation values with display name, legacy color code, and hex color:
| Constant |
Display name |
Legacy color |
Hex color |
ALLY |
"Ally" |
§a (green) |
#55FF55 |
TRUCE |
"Truce" |
§6 (gold) |
#FFAA00 |
NEUTRAL |
"Neutral" |
§7 (gray) |
#AAAAAA |
ENEMY |
"Enemy" |
§c (red) |
#FF5555 |
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);
| Method |
Returns |
Description |
sendNotification(senderPlugin, recipientUUID, type, message) |
boolean |
Sends a notification using built-in TeamNotificationType. |
sendNotification(senderPlugin, recipientUUID, notificationType, message) |
boolean |
Sends a notification using a custom string type (non-null, non-blank). |
isNotificationEnabled(playerUUID, type) |
boolean |
Whether this built-in notification type is enabled for the player. |
isNotificationEnabled(playerUUID, notificationType) |
boolean |
Whether this custom string notification type is enabled for the player. |
setNotificationEnabled(playerUUID, type, enabled) |
boolean |
Enables or disables a built-in notification type for the player. |
setNotificationEnabled(playerUUID, notificationType, enabled) |
boolean |
Enables or disables a custom string notification type for the player. |
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);
| Method |
Returns |
Description |
getName() |
String |
Matched case-insensitively against args[0] |
getDescription() |
String |
Optional description for help output |
getPermission() |
String |
Permission required, or null for no check |
execute(sender, args) |
boolean |
Called when the subcommand is dispatched; return false to show usage |
getUsage() |
String |
Usage hint sent when execute returns false |
tabComplete(sender, args) |
List<String> |
Tab-completion suggestions; default: empty list |
Commands & permissions
| Subcommand |
Permission |
Default |
Description |
/teamsapi / /teamsapi help |
teamsapi.use |
everyone |
Lists commands the sender can use |
/teamsapi version |
teamsapi.use |
everyone |
Prints plugin and API version |
/teamsapi status |
teamsapi.status |
everyone |
Active provider, team count, registered services |
/teamsapi info |
teamsapi.admin |
op |
Full internal diagnostic |
/teamsapi power status |
teamsapi.power |
op |
Sender's current and max power |
/teamsapi power buy <n> |
teamsapi.power.buy |
disabled |
Disabled by default; enable with power-shop.enabled: true in config.yml. Requires Vault. |
/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 a server restart. |
Events
All events live in com.skyblockexp.teamsapi.event. Providers are encouraged but not required to fire them.
| Event |
Cancellable |
Fired when |
TeamCreateEvent |
Yes |
Before a team is created |
TeamDeleteEvent |
Yes |
Before a team is deleted |
TeamJoinEvent |
Yes |
Before a player joins a team |
TeamLeaveEvent |
Yes |
Before a player leaves a team |
TeamRoleChangeEvent |
Yes |
Before a member's role changes |
TeamInviteEvent |
Yes |
Before an invitation is sent |
TeamInviteAcceptEvent |
No |
After a player accepts an invitation |
TeamInviteDeclineEvent |
No |
After a player declines an invitation |
TeamWarpSetEvent |
Yes |
Before a warp is created or updated |
TeamWarpDeleteEvent |
Yes |
Before a warp is deleted |
TeamClaimEvent |
Yes |
Before a chunk is claimed |
TeamUnclaimEvent |
Yes |
Before a chunk is unclaimed |
Roles
| Role |
Priority |
Description |
OWNER |
100 |
Full control; cannot be removed by others |
ADMIN |
50 |
Can manage members with a lower priority |
MEMBER |
10 |
Regular team member |
Links
MIT License - free to use in any project, open- or closed-source.
评论 0
登录后参与评分
还没有评论,来抢沙发吧