GroupService

GroupService is the main API interface exposed by GroupManager. It provides methods for querying group state, performing group operations, managing temporary groups, and controlling the HUD.

import com.groupmanager.api.GroupService;
import com.groupmanager.api.GroupManagerProvider;

GroupService api = GroupManagerProvider.get();

---

Data Types

GroupType

Enum representing the type of a group:

import com.groupmanager.api.GroupType;

public enum GroupType {
    TEMPORARY,  // Created programmatically for activities — dissolved automatically
    PERMANENT   // Created by players — persists across sessions
}

Use == for comparisons:

if (groupInfo.type() == GroupType.PERMANENT) {
    // Handle permanent group
}

GroupInfo

Immutable snapshot of a group's state:

interface GroupInfo {
    UUID groupId();           // Unique group identifier
    UUID leaderUuid();        // UUID of the group leader
    List<UUID> memberUuids(); // All member UUIDs (includes leader)
    List<UUID> onlineMemberUuids(); // UUIDs of currently online members
    int size();               // Total member count
    int onlineMemberCount();  // Currently online members
    GroupType type();         // PERMANENT or TEMPORARY
    Map<UUID, String> displayNames(); // UUID → display name mapping
}

GroupResult

Result of a group operation:

interface GroupResult {
    boolean success();   // Whether the operation succeeded
    String message();    // Human-readable result message
    UUID groupId();      // Group ID (if applicable)
}

---

Query Methods

isPlayerOnline(UUID playerUuid)

Checks whether a player is currently online (being tracked by the server's tick system).

boolean online = api.isPlayerOnline(playerUuid);

Parameter	Type	Description
playerUuid	UUID	The player's UUID

Returns: true if the player is online.

---

getPlayerGroup(UUID playerUuid)

Returns the group a player belongs to.

Optional<GroupInfo> group = api.getPlayerGroup(playerUuid);

Parameter	Type	Description
playerUuid	UUID	The player's UUID

Returns: Optional<GroupInfo> — empty if the player is not in a group.

---

getGroup(UUID groupId)

Returns a group by its ID.

Optional<GroupInfo> group = api.getGroup(groupId);

Parameter	Type	Description
groupId	UUID	The group's unique ID

Returns: Optional<GroupInfo> — empty if no group with that ID exists.

---

getAllGroups()

Returns all active groups on the server.

Collection<GroupInfo> groups = api.getAllGroups();

Returns: Collection<GroupInfo> — may be empty.

---

isGroupLeader(UUID playerUuid)

Checks whether a player is the leader of their group.

boolean leader = api.isGroupLeader(playerUuid);

---

areInSameGroup(UUID playerUuid1, UUID playerUuid2)

Checks whether two players belong to the same group.

boolean teammates = api.areInSameGroup(player1, player2);

---

getMaxGroupSize()

Returns the configured maximum group size.

int max = api.getMaxGroupSize(); // default: 16

---

canPlayerJoinExternalActivity(UUID playerUuid)

Checks whether a player is eligible to join an external activity (e.g., a game queue). Returns false if the player is busy or in a restricted state.

if (api.canPlayerJoinExternalActivity(playerUuid)) {
    // Safe to add to some queue or actvity
}

---

Operation Methods

All operation methods return a GroupResult indicating success or failure.

createGroup(Player leader)

Creates a new permanent group with the given player as leader.

GroupResult result = api.createGroup(player);

---

dissolveGroup(UUID groupId)

Dissolves a group entirely. All members are removed.

GroupResult result = api.dissolveGroup(groupId);

---

invitePlayer(UUID inviterUuid, UUID targetUuid)

Sends a group invitation from one player to another. If the inviter is not in a group, one is created automatically.

GroupResult result = api.invitePlayer(inviterUuid, targetUuid);

---

kickMember(UUID leaderUuid, UUID targetUuid)

Removes a member from the group. Only the leader can kick.

GroupResult result = api.kickMember(leaderUuid, targetUuid);

---

leaveGroup(UUID playerUuid)

Makes a player leave their current group.

GroupResult result = api.leaveGroup(playerUuid);

---

transferLeadership(UUID leaderUuid, UUID newLeaderUuid)

Transfers leadership from the current leader to another member.

GroupResult result = api.transferLeadership(currentLeader, newLeader);

---

Temporary Group Methods

These methods are designed for external plugins that need to create and manage temporary groups (e.g., for matchmaking).

createTemporaryGroup(Player leader, List<Player> members)

Creates a temporary group with the given leader and members.

GroupResult result = api.createTemporaryGroup(leader, Arrays.asList(member1, member2));
UUID tempGroupId = result.groupId();

---

dissolveTemporaryGroup(UUID groupId, Map<UUID, UUID> originalGroups)

Dissolves a temporary group and optionally restores members to their original permanent groups.

Map<UUID, UUID> originalGroups = new HashMap<>();
originalGroups.put(player1Uuid, originalGroup1Id);
originalGroups.put(player2Uuid, originalGroup2Id);

api.dissolveTemporaryGroup(tempGroupId, originalGroups);

---

Communication Methods

broadcastToGroup(UUID groupId, String message)

Sends a message to all members of a group.

api.broadcastToGroup(groupId, "Match starting in 10 seconds!");

broadcastToGroupExcept(UUID groupId, UUID exceptUuid, String message)

Sends a message to all group members except one.

api.broadcastToGroupExcept(groupId, senderUuid, "Player left the match.");

---

HUD Control

pauseHud(UUID playerUuid)

Temporarily hides the group HUD for a player. If AutoMultiHud is present, this is an automatic no-op (HUDs coexist in separate groups).

api.pauseHud(playerUuid); // e.g., during a match

resumeHud(UUID playerUuid)

Restores the group HUD for a player. Internally performs a full state cleanup (clears cached InternalMultiHud and AutoMultiHud state) before recreating the HUD from scratch. If AutoMultiHud is present, this is an automatic no-op.

api.resumeHud(playerUuid); // e.g., after a match

isAutoMultiHudPresent()

Returns true if AutoMultiHud is installed on the server. When true, pauseHud/resumeHud are no-ops internally. This method is informational — you don't need to check it before calling pause/resume.

boolean hasAutoMultiHud = api.isAutoMultiHudPresent();

info

You can call pauseHud/resumeHud unconditionally — GroupManager handles AutoMultiHud compatibility internally. See HUD Compatibility for details.

---

HUD Prefix / Suffix

External plugins can add a prefix and/or suffix to each player's name in the GroupManager HUD, without modifying the actual display name. This is useful for RPG plugins that want to show level, class, race, or any other tag next to the player's name.

The prefix/suffix data is stored in a thread-safe cache and rendered automatically by the HUD every 250ms.

setHudPrefix(UUID playerUuid, String prefix)

Sets a text prefix shown before the player's name in the group HUD.

api.setHudPrefix(playerUuid, "[Lv.5] ");
// HUD shows: "[Lv.5] Steve"

Parameter	Type	Description
playerUuid	UUID	The player's UUID
prefix	String	Text to prepend (pass null or "" to remove)

---

setHudSuffix(UUID playerUuid, String suffix)

Sets a text suffix shown after the player's name in the group HUD.

api.setHudSuffix(playerUuid, " [Warrior]");
// HUD shows: "Steve [Warrior]"

Parameter	Type	Description
playerUuid	UUID	The player's UUID
suffix	String	Text to append (pass null or "" to remove)

---

getHudPrefix(UUID playerUuid)

Returns the current HUD prefix for a player.

String prefix = api.getHudPrefix(playerUuid); // e.g. "[Lv.5] "

Returns: The prefix string, or "" if none is set.

---

getHudSuffix(UUID playerUuid)

Returns the current HUD suffix for a player.

String suffix = api.getHudSuffix(playerUuid); // e.g. " [Warrior]"

Returns: The suffix string, or "" if none is set.

---

clearHudPrefixSuffix(UUID playerUuid)

Removes both the prefix and suffix for a player.

api.clearHudPrefixSuffix(playerUuid);

---

Prefix/Suffix Example

// An RPG leveling plugin updates the HUD every time a player levels up
GroupService api = GroupManagerProvider.get();
if (api != null) {
    api.setHudPrefix(playerUuid, "[Lv." + level + "] ");
    api.setHudSuffix(playerUuid, " | " + className);
    // HUD shows: "[Lv.12] Steve | Warrior"
}

tip

Prefix and suffix are automatically cleaned up when a player disconnects. You don't need to call clearHudPrefixSuffix on disconnect.

info

The prefix/suffix only affects the group HUD display — the player's actual displayName is never modified.

---

Player Connection

reconnectPlayer(Player player)

Notifies GroupManager that a player has reconnected. Restores their group membership and HUD.

api.reconnectPlayer(player);

disconnectPlayer(Player player)

Notifies GroupManager that a player has disconnected.

api.disconnectPlayer(player);

---

Event Listeners

registerEventListener(GroupEventListener listener)

Registers a listener for group events. See Events for details.

unregisterEventListener(GroupEventListener listener)

Removes a previously registered event listener.

---

Persistence

savePersistedGroups()

Forces an immediate save of all persistent group data to disk.

api.savePersistedGroups();

registerPlayerToGroup(UUID playerUuid, UUID groupId)

Registers a player as belonging to a specific group (used during restoration).

restorePermanentGroupOnDisconnect(UUID playerUuid, UUID permanentGroupId)

Restores the internal mapping between a player and their permanent group after they disconnect while inside a temporary group.

When createTemporaryGroup() is called, the player's permanent group mapping is replaced by the temporary one. If the player then disconnects, the temporary mapping is cleaned up — leaving the player with no group mapping at all. Without this call, reconnectPlayer() would have nothing to restore when the player comes back.

This method re-establishes the permanent group mapping and marks the player as offline in that group, so that reconnectPlayer() works correctly on their next connection.

// A player disconnects while participating in your activity
private void onPlayerDisconnect(UUID playerUuid) {
    UUID permanentGroupId = originalPermanentGroups.get(playerUuid);
    if (permanentGroupId != null) {
        groupApi.restorePermanentGroupOnDisconnect(playerUuid, permanentGroupId);
    }
}

Parameter	Type	Description
playerUuid	UUID	The disconnected player's UUID
permanentGroupId	UUID	The player's original permanent group ID (saved before creating the temporary group)

---

restorePlayerFromCoalition(Player player, UUID permanentGroupId, List<UUID> coalitionGroupIds)

Restores an online player from a temporary group back to their permanent group. Use this when a player voluntarily leaves your activity while still connected (e.g., a /leave command).

The method removes the player from the temporary group, restores their permanent group mapping, and updates internal references. Unlike restorePermanentGroupOnDisconnect, the player stays online throughout the process.

// A player voluntarily leaves the activity
private void onPlayerLeave(Player player) {
    UUID permanentGroupId = originalPermanentGroups.get(player.getUuid());
    if (permanentGroupId != null) {
        groupApi.restorePlayerFromCoalition(
                player, permanentGroupId, temporaryGroupIds);
    }
}

Parameter	Type	Description
player	Player	The online player to restore
permanentGroupId	UUID	The player's original permanent group ID
coalitionGroupIds	List<UUID>	All temporary group IDs created for the current activity

---

rejoinCoalitionGroup(Player player, List<PlayerRef> teamMembers, Map<UUID, UUID> originalGroups, List<UUID> coalitionGroupIds)

Reintegrates a reconnected player into the temporary group of their team. When a player reconnects, reconnectPlayer() restores them to their permanent group — but if the activity is still running, they need to be back in the temporary group with their teammates.

This method finds the correct temporary group by checking which one the player's teammates belong to, then moves the player from the permanent group tracking into that temporary group.

Returns: true if the player was successfully reintegrated, false if no matching temporary group was found.

// A player reconnects while the activity is still running
private void onPlayerReconnect(Player player, List<PlayerRef> teamMembers) {
    // reconnectPlayer() already restored their permanent group.
    // Now move them back into the temporary group of their team.
    boolean rejoined = groupApi.rejoinCoalitionGroup(
            player, teamMembers,
            originalPermanentGroups, temporaryGroupIds);
}

Parameter	Type	Description
player	Player	The reconnected player
teamMembers	List<PlayerRef>	All members of the player's team (used to find the correct temporary group)
originalGroups	Map<UUID, UUID>	Mapping of playerUuid → original permanent group ID
coalitionGroupIds	List<UUID>	All temporary group IDs created for the current activity

info

See the Integration Guide for a complete example showing all of these methods working together in an activity lifecycle.