Skip to main content

API Overview

Mountale exposes a public Java API so other plugins can see what players are doing with their mounts, act on them, and decide where mounts can be summoned.

A few things you can build with it:

  • No mounts in arenas or dungeons — Forbid summoning while a player is in a match, a dungeon or someone else's claim.
  • Mounts as rewards — Unlock a mount when a player finishes a quest, buys it in a shop or clears a dungeon.
  • Dismount on teleport — Take players off their mount before moving them to another world.
  • Shared combat — Mark players in combat from your own damage sources, so they can't flee on a mount.
  • Stats and logs — Count summons, track which mounts are used, or log dismounts.

Getting Started​

Add Mountale's jar as a compileOnly dependency:

build.gradle.kts
dependencies {
compileOnly(files("libs/mountale-1.0.0.jar"))
}

Declare it as an optional dependency in your manifest.json, so your plugin loads after Mountale when both are installed:

{
"OptionalDependencies": {
"HaporeLab:Mountale": "*"
}
}

All public types live under com.mountale.api:

TypeDescription
MountaleAPIMain interface: queries, actions, restrictions and listeners
MountaleProviderStatic access to the API instance
MountInfoRead-only snapshot of a mount (id, name, rarity, speed, scroll item…)
SummonRestrictionA rule that can forbid summoning
MountaleListenerEvent callbacks
MountResultResult of unlocking or locking a mount
DismountReason, CastCancelReason, UnlockSourceEvent reasons

Obtaining the API​

import com.mountale.api.MountaleAPI;
import com.mountale.api.MountaleProvider;

MountaleAPI mountale = MountaleProvider.get();
if (mountale != null) {
// Mountale is installed and enabled
}

Mountale registers the API in its setup(), so it is ready from your plugin's start(). get() returns null when Mountale isn't installed.

Optional classes

If Mountale might be missing, keep every reference to com.mountale.api in a separate class that you only load after checking that Mountale is installed. Otherwise your plugin fails with NoClassDefFoundError on servers without Mountale.

Quick Examples​

Forbid summoning in arenas​

mountale.registerSummonRestriction((player, mount) ->
arenas.isInMatch(player)
? Optional.of("You can't summon mounts during a match.")
: Optional.empty());

Take a player off their mount before a teleport​

mountale.dismount(playerUuid); // false if they weren't riding a Mountale mount

Unlock a mount as a reward​

switch (mountale.unlock(playerUuid, "bengal_tiger")) {
case OK -> player.sendMessage(Message.raw("You unlocked the Bengal Tiger!"));
case ALREADY -> giveSomethingElse(player);
default -> getLogger().at(Level.WARNING).log("Could not unlock the mount");
}

Give the mount's scroll instead​

// On the player's world thread
mountale.getMount("bengal_tiger").ifPresent(mount ->
Player.giveItem(new ItemStack(mount.itemId(), 1), ref, store));

Listen to dismounts​

mountale.registerListener(new MountaleListener() {
@Override
public void onDismount(UUID player, MountInfo mount, DismountReason reason) {
if (reason == DismountReason.DAMAGE) {
stats.countKnockOff(player, mount.id());
}
}
});

Threading​

  • All methods can be called from any thread.
  • Actions that touch the player, like dismount and cancelCast, are queued on the player's world thread and return right away.
  • Restrictions and most events run on the player's world thread. Keep them fast and don't block.
  • An exception thrown by your restriction or listener is logged by Mountale and ignored, so it never breaks summoning or other plugins.

See API Reference for every method, and Restrictions & Events for rules and listeners.