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:
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:
| Type | Description |
|---|---|
MountaleAPI | Main interface: queries, actions, restrictions and listeners |
MountaleProvider | Static access to the API instance |
MountInfo | Read-only snapshot of a mount (id, name, rarity, speed, scroll item…) |
SummonRestriction | A rule that can forbid summoning |
MountaleListener | Event callbacks |
MountResult | Result of unlocking or locking a mount |
DismountReason, CastCancelReason, UnlockSource | Event 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.
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
dismountandcancelCast, 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.