Teams API

插件

· 作者 Shadow48402

TeamsAPI 是一个被动的、服务器端的 Minecraft 服务器桥接插件,灵感来源于 Vault。

0 本站下载 0 关注 更新于 5 个月前

最新 2.5.0-bungee · 26.1.2 · BungeeCord / Waterfall

一键开服(送7天)

CI codecov Jitpack

团队插件与其他一切之间的通用桥梁。

TeamsAPI 是一个被动的、服务端桥接插件,适用于 Paper、Spigot、Purpur 和 Folia 服务器,灵感源自 Vault。它提供了一个单一且稳定的接口来处理团队操作,因此任何需要团队数据的插件都可以与任何兼容的团队插件配合工作,而无需这两个插件互相知晓对方。

在我们的重构版 Factions fork 中实现:

工作原理

Teams API connect your plugin with team plugins

  • 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 用于战力商店)

安装(服务器管理员)

  1. 从此列表的 Files 选项卡或 GitHub Releases 下载 teams-api-plugin-VERSION.jar。
  2. 将其放入服务器的 plugins/ 目录中。
  3. 安装一个兼容的团队插件。官方扩展包括 BetterTeams、 Towny Advanced 和 KingdomsX,已打包在 TeamsAPI 内部。在游戏中运行 /teamsapi install betterteams(或 towny / kingdomsx), 或者让 TeamsAPI 自动将它们配置到 plugins/TeamsAPI/extensions/。
  4. 重启服务器。

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 许可证 - 可在任何项目(开源或闭源)中自由使用。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源