Skip to main content

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​

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)
    int size();               // Total member count
    int onlineMemberCount();  // Currently online members
    String 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​

getPlayerGroup(UUID playerUuid)​

Returns the group a player belongs to.

Optional<GroupInfo> group = api.getPlayerGroup(playerUuid);
ParameterTypeDescription
playerUuidUUIDThe 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);
ParameterTypeDescription
groupIdUUIDThe 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: 20

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 queue
}

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.

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

resumeHud(UUID playerUuid)​

Restores the group HUD for a player.

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

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)​

Marks a player's permanent group for restoration when they reconnect.

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

Restores a player from a coalition (temporary merge) back to their permanent group.

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

Attempts to rejoin a player to an existing coalition group.