Restrictions & Events
Summon Restrictions
A SummonRestriction lets your plugin forbid summoning: inside an arena, a dungeon, a claim, during a cutscene, or any other rule you need.
@FunctionalInterface
public interface SummonRestriction {
Optional<String> check(UUID player, MountInfo mount);
}
- Allowed — Return
Optional.empty(). - Forbidden — Return a message. Mountale shows it to the player in red and doesn't summon.
- Forbidden, generic text — Return
Optional.of(""). Mountale shows its own "You can't summon mounts here." (mount.restrictedin the language files).
Mountale checks every restriction twice: when the player picks the mount (menu, wheel or API) and again when the cast ends. A player who walks into an arena mid-cast doesn't get the mount. The first restriction that forbids it wins.
SummonRestriction noArenas = (player, mount) -> arenas.isBusy(player)
? Optional.of("You can't summon mounts during a match.")
: Optional.empty();
mountale.registerSummonRestriction(noArenas);
// ...
mountale.unregisterSummonRestriction(noArenas);
Restrictions run on the player's world thread: keep them fast and don't block.
Restrictions only affect summoning. To take players off their mount when they enter a restricted place, call mountale.dismount(player) as well.
Listeners
Implement MountaleListener and override only the methods you need. They all have an empty default.
mountale.registerListener(new MountaleListener() {
@Override
public void onMountSummoned(UUID player, MountInfo mount) {
stats.countSummon(player, mount.id());
}
});
| Method | When |
|---|---|
onCastStart(UUID player, MountInfo mount, double seconds) | The player started summoning (the cast began) |
onCastCancel(UUID player, MountInfo mount, CastCancelReason reason) | The summon was interrupted before the mount appeared |
onMountSummoned(UUID player, MountInfo mount) | The mount appeared and the player is riding it |
onDismount(UUID player, MountInfo mount, DismountReason reason) | The player got off and the mount vanished |
onCombatEnter(UUID player) | The player entered combat: they can't summon while it lasts |
onCombatLeave(UUID player) | The player left combat |
onMountUnlocked(UUID player, MountInfo mount, UnlockSource source) | The player was given a mount's permission |
onMountLocked(UUID player, MountInfo mount) | The player lost their own permission for a mount |
Cast, summon and dismount events run on the player's world thread. Combat and unlock events may come from any thread.
onDismount only fires for players who were actually mounted, after onMountSummoned. With a cast time of 0, there is no onCastStart: the mount appears right away.
CastCancelReason
| Value | Meaning |
|---|---|
MOVED | The player moved more than CastMoveTolerance |
DAMAGE | The player took damage |
COMBAT | The player was in combat when the cast ended |
NO_PERMISSION | The player no longer had the mount's permission when the cast ended |
RESTRICTED | A SummonRestriction forbade it when the cast ended |
DISCONNECT | The player disconnected |
API | Another plugin called cancelCast |
OTHER | World change, shutdown or reload |
DismountReason
| Value | Meaning |
|---|---|
GAME | The game took them off: the dismount key (F), /dismount, death or a world change |
DAMAGE | They (or their mount) took damage |
MENU | The Dismount button in the menu, or picking their current mount in the wheel |
DISCONNECT | They disconnected |
API | Another plugin called dismount |
TELEPORT | They or their mount were teleported: a portal, a teleporter or a command |
SHUTDOWN | The server (or Mountale) shut down |
OTHER | Anything else |
UnlockSource
| Value | Meaning |
|---|---|
ITEM | The player used the mount's scroll |
COMMAND | An admin ran /mountale unlock |
API | Another plugin called unlock |