A P I Parties

Mythic Dungeons provides a simple way to add compatibility for other party plugins. After following the instructions outlined in the introduction page, there are only two steps needed to make your party plugin compatible.

After that, server owners need to tell Mythic Dungeons to use your plugin as a party provider! This is done through the PartyPlugin option in the Mythic Dungeons config.

The option is General.PartyPlugin in plugins/MythicDungeons/config.yml, and its value must also be the name of an installed plugin, otherwise Mythic Dungeons disables party support entirely and logs ERROR :: Party plugin is set to '<name>', but no such plugin was found!. See Parties for the values Mythic Dungeons supports natively.

Because your plugin is not one of the natively-supported providers, Mythic Dungeons will never build a party on its own. A player who has not been passed to initDungeonParty is treated as playing solo. It also means the built-in party API methods (createParty, inviteToParty, disbandParty, and so on) are refused while your provider is selected; they only operate on the built-in system.

Step 1 - Implement the IDungeonParty Interface

Mythic Dungeons provides an interface that comes with all the necessary methods to make a party system compatible. All you have to do is implement the IDungeonParty interface into your existing party object and ensure it includes the necessary methods:

• void addPlayer(Player) - Allows Mythic Dungeons to add players to the party.
• void removePlayer(Player) - Allows Mythic Dungeons to remove players from the party.
• List<Player> getPlayers() - Allows Mythic Dungeons to retrieve a list of players currently in the party.
• @NotNull OfflinePlayer getLeader() - Allows Mythic Dungeons to retrieve the current owner of the party. This must never return null, even when the leader is offline. Mythic Dungeons calls it during the ready-check countdown and when resolving a party's checkpoint, and dereferences the result. If your leader may be offline, fall back to any remaining member.

The interface also provides these methods with working defaults. Override them if your party system can answer them more cheaply or more correctly:

• boolean hasPlayer(Player) - defaults to a scan of getPlayers(). That scan compares the UUID objects by identity rather than by value, so a stale Player reference (one kept across a relog, for example) can make it answer false. Override it if your party can answer membership directly.
• void partyMessage(String) - defaults to messaging every player from getPlayers().
• Location getPartySavePoint(String dungeon) - defaults to the leader's checkpoint for that dungeon.
• void setAwaitingDungeon(boolean) - flags every member as waiting to enter a dungeon.
• void initDungeonParty(Plugin) and void initDungeonParty(String...) - see Step 2 below. These are the only two you are expected to call yourself rather than override.

See the party class below for a full example.

Step 2 - Call the initDungeonParty Method

In order for Mythic Dungeons to track the party, it needs to be informed that it exists upon creation. This can be achieved by simply calling initDungeonParty(Plugin). The plugin is used to verify that the server owner has configured their Mythic Dungeons to use your party system. (You can also use initDungeonParty(String...) if you want to provide multiple possible names for your party system.)

Both overloads compare the configured General.PartyPlugin value against your plugin's name (or against each name you pass) without regard to case, and do nothing when none of them match. When one does match, every player currently returned by getPlayers() is pointed at this party object, which is why the call belongs at the end of your constructor, after the member list is populated.

Example Party Class

class ExampleParty implements IDungeonParty {

    private UUID leader;
    private List<UUID> playerUUIDs = new ArrayList<>();

    public ExampleParty(Player leader) {
        this.leader = leader.getUniqueId();

        // REQUIRED!! Init the party with your plugin instance here, or enter a list of names for the party system. 
        // It's recommended to do this after you've finished everything else in your constructor.
        initDungeonParty(plugin);
    }

    // Allows Mythic Dungeons to easily add players to your party object.
    @Override
    public void addPlayer(Player player) {
        playerUUIDs.add(player.getUniqueId());
    }

    // Allows Mythic Dungeons to easily remove players from your party object.
    @Override
    public void removePlayer(Player player) {
        playerUUIDs.remove(player.getUniqueId());
    }

    // Allows Mythic Dungeons to easily retrieve a list of players in the party.
    // NOTE: It's advised to store players using UUIDs and then convert them to Players in the getPlayers method.
    @Override
    public List<Player> getPlayers() {
        List<Player> players = new ArrayList<>();

        for (UUID uuid : playerUUIDs) {

            Player player = Bukkit.getPlayer(uuid);
            if (player == null) continue;

            players.add(player);

        }

        return players;
    }

    // Allows Mythic Dungeons to easily retrieve the leader or owner of the party object.
    // Must never return null. Bukkit declares getOfflinePlayer(UUID) as @NotNull, so this is
    // safe even when the leader has logged out.
    @Override
    public @NotNull OfflinePlayer getLeader() {
        return Bukkit.getOfflinePlayer(leader);
    }

}

And that's it! This system is still relatively experimental, but should allow easy integration with Mythic Dungeons using your own party system.

DISCLAIMER: The /recruit party-finder works with your provider only for players who already have a party registered through initDungeonParty. For those players Mythic Dungeons adds a joining player by calling your addPlayer(Player), so make sure that method really joins the player to the underlying party. A player with no party who runs /recruit is not currently handled for custom providers; create the party through your own plugin first.