Skip to main content

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.restricted in 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.

Players already riding

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());
}
});
MethodWhen
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​

ValueMeaning
MOVEDThe player moved more than CastMoveTolerance
DAMAGEThe player took damage
COMBATThe player was in combat when the cast ended
NO_PERMISSIONThe player no longer had the mount's permission when the cast ended
RESTRICTEDA SummonRestriction forbade it when the cast ended
DISCONNECTThe player disconnected
APIAnother plugin called cancelCast
OTHERWorld change, shutdown or reload

DismountReason​

ValueMeaning
GAMEThe game took them off: the dismount key (F), /dismount, death or a world change
DAMAGEThey (or their mount) took damage
MENUThe Dismount button in the menu, or picking their current mount in the wheel
DISCONNECTThey disconnected
APIAnother plugin called dismount
TELEPORTThey or their mount were teleported: a portal, a teleporter or a command
SHUTDOWNThe server (or Mountale) shut down
OTHERAnything else

UnlockSource​

ValueMeaning
ITEMThe player used the mount's scroll
COMMANDAn admin ran /mountale unlock
APIAnother plugin called unlock