API 参考（开发者）

本页面向“二次开发/联动开发”。如果你只是服主或玩家，请优先阅读《配置》《命令与权限》。

依赖引入（Maven / Gradle）

NuStarParty 将 API 单独发布为 NuStarParty-party-api，建议以 compileOnly/provided 方式引入（服务端运行时由 NuStarParty 插件提供实现）。

Maven：

<repositories>
  <repository>
    <id>nustar-releases</id>
    <url>https://maven.nustar.top/repository/nustar-releases/</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>top.nustar.nustarparty</groupId>
    <artifactId>NuStarParty-party-api</artifactId>
    <version>1.0.4</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

Gradle Kotlin DSL：

repositories {
  maven("https://maven.nustar.top/repository/nustar-releases/")
}

dependencies {
  compileOnly("top.nustar.nustarparty:NuStarParty-party-api:1.0.4")
}

建议同时在你的 plugin.yml 中声明依赖关系（按需选 depend 或 softdepend）：

softdepend:
  - NuStarParty

常用接口（代码调用）

NuStarPartyAPI（静态入口）

推荐从静态入口开始使用（无需接入 NuStarParty 的容器/上下文）：

import java.util.Optional;
import org.bukkit.entity.Player;
import top.nustar.nustarparty.api.NuStarPartyAPI;
import top.nustar.nustarparty.api.entity.Party;

public class PartyCompat {
  public static Optional<Party> getParty(Player player) {
    return NuStarPartyAPI.getPlayerParty(player.getUniqueId());
  }
}

注意：

• NuStarPartyAPI.getPlayerParty/getPartyList 返回的是 Party.copy() 副本，用于读取信息；请通过 NuStarPartyAPI 或 PartyService 提供的方法执行“创建/解散/踢人”等写操作。
• 建议在 NuStarParty 插件启用后再调用（例如你的插件 onEnable，并在 plugin.yml 声明 depend/softdepend: NuStarParty）。

事件（Bukkit Event）

NuStarParty 提供了一组 Bukkit 事件，便于你拦截或监听组队流程：

• 创建队伍：CreatePartyEvent.Pre（可取消）/ CreatePartyEvent.After
• 入队申请：AddJoinApplicationEvent.Pre（可取消）/ AddJoinApplicationEvent.After
• 处理申请：AcceptJoinApplicationEvent.Pre（可取消）/ AcceptJoinApplicationEvent.After、RefuseJoinApplicationEvent.Pre（可取消）/ RefuseJoinApplicationEvent.After
• 退出队伍：QuitPartyEvent.Pre（可取消）/ QuitPartyEvent.After
• 解散队伍：DisbandPartyEvent.Pre（可取消）/ DisbandPartyEvent.After
• 转让队长：TransferLeaderEvent.Pre（可取消）/ TransferLeaderEvent.After
• 邀请处理：AcceptInviteApplicationEvent.Pre（可取消）/ AcceptInviteApplicationEvent.After、RefuseInviteApplicationEvent.Pre（可取消）/ RefuseInviteApplicationEvent.After
• 踢人：KickPartyEvent（不可取消）
• 地牢中途入队（DungeonPlus 联动）：JoinPartyDungeonEvent.Pre（可取消）/ JoinPartyDungeonEvent.After
• 菜单点击：top.nustar.nustarparty.api.event.inv.MenuClickEvent（用于监听玩家点击 NuStarParty GUI）

示例：拦截创建队伍（禁止在某世界创建）

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import top.nustar.nustarparty.api.event.CreatePartyEvent;

public class PartyListener implements Listener {
  @EventHandler
  public void on(CreatePartyEvent.Pre event) {
    if ("no-party-world".equalsIgnoreCase(event.getPlayer().getWorld().getName())) {
      event.setCancelled(true);
      event.getPlayer().sendMessage("§c该世界禁止创建队伍");
    }
  }
}

NuStarCoreBridge 联动（Packet / Placeholder）

如果你需要从龙核/萌芽/云拾等客户端 UI 触发队伍逻辑，安装 NuStarCoreBridge 后可以使用 NuStarParty 提供的 Packet。

Packet：NuStarParty（行为类）

返回值通过 PlaceholderService 下发到“触发玩家”，常见约定：

• 成功：1
• 失败：0
• 异常：执行失败

Handler	参数	返回占位符	说明
createParty	-	NuStarParty_CreateParty	创建队伍
quitParty	-	NuStarParty_QuitParty	退出队伍
disbandParty	-	NuStarParty_DisbandParty	解散队伍
addJoinPartyRequest	partyUid（UUID）	NuStarParty_AddJoinPartyRequest	申请加入队伍
acceptJoinRequest	requesterName（玩家名）	NuStarParty_AcceptJoinRequest	通过入队申请（队长）
refuseJoinRequest	requesterName（玩家名）	NuStarParty_RefuseJoinRequest	拒绝入队申请（队长）
kickMember	memberName、kickReason	NuStarParty_KickMember	踢人（队长）
isInSameParty	playerUid1、playerUid2（UUID）	NuStarParty_IsInSameParty	是否同队
transferLeader	playerName（新队长玩家名）	NuStarParty_TransferLeader	转让队长

以下 Handler 在当前版本仅发送提示消息（未返回占位符，属于 TODO/预留接口）：

• invitePlayer、mergeParty、changePickupMode、setPartyDestination、sendGatherRequest

Packet：NuStarPartyPlaceholder（数据下发类）

用于批量刷新 UI 需要的占位符变量（变量会下发到“触发玩家”）：

• refreshAllPlaceholder：刷新所有队伍列表变量
• refreshMyPartyPlaceholder：刷新“我的队伍”基础变量
• refreshMyPartyMemberPlaceholder：刷新“我的队伍”成员变量
• refreshJoinApplicationPlaceholder：刷新申请列表变量
• refreshInviteApplicationPlaceholder：刷新邀请列表变量
• refreshPlayerListPlaceholder：刷新玩家列表变量

常见变量命名示例：

• 队伍列表：NuStarParty_PartyListSize、NuStarParty_PartyName_<index>、NuStarParty_PartyUid_<index>…
• 我的队伍：NuStarParty_MyPartyLeaderName、NuStarParty_MyPartySize、NuStarParty_MyPartyMemberName_<index>…
• 玩家列表：NuStarParty_PlayerListSize、NuStarParty_PlayerListName_<index>…
• 邀请列表：NuStarParty_PartyInviteApplicationSize、NuStarParty_PartyInviteApplicantName_<index>、NuStarParty_PartyInviteReason_<index>…

用于 UI 红点/提示的变量：

• NuStarPartyPlaceholder_ReceiveJoinApplication：队长收到入队申请时会短暂置 1（申请处理完/超时后移除）

提示：变量详细命名规则以源码 PartyPlaceholderPacket 为准。

菜单占位符（GUI 渲染）

NuStarParty 的菜单 YAML 支持形如 {name} 的占位符（见《配置》页面）。

如果你想注册自定义占位符，可以使用 MenuPlaceholderRegistry（或 PartyMenuAPI.registerPlaceholder）：

import top.nustar.nustarparty.api.PartyMenuAPI;
import top.nustar.nustarparty.api.placeholder.MenuPlaceholderContext;

public class MyPlaceholders {
  public static void register() {
    PartyMenuAPI.registerPlaceholder("percentageHealth", (MenuPlaceholderContext ctx) -> {
      double health = ctx.getOnlinePlayer().getHealth();
      double max = ctx.getOnlinePlayer().getMaxHealth();
      return String.format("%.0f%%", health / max * 100);
    }, true);
  }
}

注意：

• 若 requireOnlinePlayer=true，玩家离线时该占位符不会被替换。
• 占位符回调应避免耗时操作（会影响菜单刷新性能）。