Integration Guide

This guide walks through integrating GroupManager into your own Hytale plugin, using a PvP minigame plugin as an example use case.

1. Add the Dependency

Add GroupManager as a compile-only dependency:

build.gradle.kts

dependencies {
    compileOnly(files("libs/groupmanager.jar"))
}

In your manifest.json, declare GroupManager as an optional dependency:

{
  "Dependencies": {
    "HaporeLab:GroupManager": "*"
  }
}

2. Access the API

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

public class MyPlugin extends JavaPlugin {

    private GroupService groupApi;

    @Override
    public void start() {
        groupApi = GroupManagerProvider.get();
        if (groupApi == null) {
            getLogger().at(Level.WARNING).log("GroupManager not found, group features disabled");
            return;
        }
        // GroupManager is available
    }
}

3. Common Integration Patterns

Queuing Groups Together

When your plugin has a queue system, check if players are grouped and queue them together:

public void queuePlayer(UUID playerUuid) {
    if (groupApi == null) {
        // Solo queue
        addToQueue(playerUuid);
        return;
    }

    Optional<GroupService.GroupInfo> group = groupApi.getPlayerGroup(playerUuid);
    if (group.isPresent()) {
        // Queue the entire group
        GroupService.GroupInfo info = group.get();
        if (!info.leaderUuid().equals(playerUuid)) {
            sendMessage(playerUuid, "Only the group leader can queue!");
            return;
        }
        for (UUID member : info.memberUuids()) {
            addToQueue(member);
        }
    } else {
        addToQueue(playerUuid);
    }
}

Preventing Friendly Fire

public boolean shouldApplyDamage(UUID attacker, UUID victim) {
    if (groupApi != null && groupApi.areInSameGroup(attacker, victim)) {
        return false; // Teammates can't hurt each other
    }
    return true;
}

Creating Match Teams

Use temporary groups to manage teams during a match:

public void startMatch(Player leader, List<Player> teamMembers) {
    // Save original groups
    Map<UUID, UUID> originalGroups = new HashMap<>();
    for (Player p : teamMembers) {
        groupApi.getPlayerGroup(p.getUuid()).ifPresent(g ->
            originalGroups.put(p.getUuid(), g.groupId())
        );
    }

    // Create temp group
    GroupService.GroupResult result = groupApi.createTemporaryGroup(leader, teamMembers);
    UUID matchGroupId = result.groupId();

    // Pause HUD during match
    for (Player p : teamMembers) {
        groupApi.pauseHud(p.getUuid());
    }

    // ... match logic ...

    // After match ends:
    groupApi.dissolveTemporaryGroup(matchGroupId, originalGroups);
    for (Player p : teamMembers) {
        groupApi.resumeHud(p.getUuid());
    }
}

Broadcasting to a Team

groupApi.broadcastToGroup(groupId, "Match starting in 10 seconds!");
groupApi.broadcastToGroupExcept(groupId, mvpUuid, playerName + " got a double kill!");

4. Listening for Events

Register an event listener to react to group changes:

@Override
public void start() {
    groupApi = GroupManagerProvider.get();
    if (groupApi == null) return;

    groupApi.registerEventListener(new GroupEventListener() {
        @Override
        public void onGroupDissolved(UUID groupId) {
            // Remove group from any active queues
            removeGroupFromQueue(groupId);
        }

        @Override
        public void onMemberLeft(UUID groupId, UUID playerUuid) {
            // Check if group still meets minimum size for queue
            groupApi.getGroup(groupId).ifPresent(info -> {
                if (info.size() < getMinTeamSize()) {
                    removeGroupFromQueue(groupId);
                    groupApi.broadcastToGroup(groupId,
                        "Removed from queue: not enough members.");
                }
            });
        }
    });
}

5. Handling Player Connections

When players reconnect to your server, notify GroupManager:

// In your player join handler
groupApi.reconnectPlayer(player);

// In your player quit handler
groupApi.disconnectPlayer(player);

GroupManager will restore the player's group membership and HUD automatically.

6. Permissions Check

If your plugin needs to verify GroupManager permissions:

import com.groupmanager.permissions.GroupManagerPermissions;

// Check if a player can invite others
String permission = GroupManagerPermissions.GROUP_INVITE;
// Use your permission system to check: hasPermission(player, permission)

Best Practices

1. Always null-check the API — GroupManager may not be installed on every server.
2. Cache the API reference — call GroupManagerProvider.get() once in start().
3. Unregister listeners — clean up in shutdown() to prevent memory leaks.
4. Use temporary groups for matches — don't modify permanent groups for game logic.
5. Pause/resume HUD — hide the group HUD during activities that have their own UI.
6. Save original groups — when creating temporary groups, save the original group IDs so you can restore them later.