Events

Override any of these methods on your Plugin. Every one has a default that does nothing.

Cancellable events return bool: return false to stop the action. Events that pass a &mut String let you rewrite the text.

Priority

When several plugins handle the same event, they run by priority:

#![allow(unused)]
fn main() {
fn priority(&self) -> Priority {
    Priority::High
}
}
PriorityUse it for
Lowest, LowRuns first. Good for setting things up that others may override.
NormalThe default.
High, HighestRuns later, so it gets the final say. Protection plugins usually go here.
MonitorRuns last, only for events nobody cancelled. Its bool is ignored. Use it for logging and stats, never to change anything.

The first plugin that returns false cancels the event, and plugins after it don't see it. Plugins with the same priority run in load order.

Players

MethodWhenCancel / edit
on_pre_login(server, name, xuid) -> Option<String>Someone is logging in, before they joinReturn a message to refuse them
on_join(server, player)Player finished joining
on_leave(server, player)Player left, kicks and disconnects included
on_chat(server, player, message: &mut String) -> boolBefore a chat message is shownEdit message, or false to block it
on_command_preprocess(server, player, line: &mut String) -> boolA typed command (without /), before it runsRewrite line, or false to drop it
on_player_damage(server, player, cause: &str, amount: f32) -> boolAbout to take damage. cause is like "fall", "lava" or "Zombie"false cancels the damage
on_player_death(server, player, message: &mut String)Player diedEdit the death message, empty hides it
on_player_respawn(server, player)Player respawned
on_player_interact(server, player, pos, item: &str) -> boolRight-clicking a block holding itemfalse means nothing happens
on_item_use(server, player, item: &Stack) -> boolRight-click with an item in hand, in the air or on a blockfalse cancels the normal use
on_gamemode_change(server, player, mode: &str) -> boolGame mode about to change to "survival", "creative"...false keeps the old mode
on_item_drop(server, player, item: &str, count: i8)Player threw items out of their inventory
on_item_pickup(server, player, item: &str, count: i8) -> boolAbout to pick up items off the groundfalse leaves them there
on_move(server, player, to) -> boolMoved (to is the eye position)false puts them back
on_sneak(server, player, sneaking: bool)Started or stopped sneaking
on_sprint(server, player, sprinting: bool)Started or stopped sprinting
on_held_change(server, player, slot: u32, item: Option<&str>)Switched hotbar slot or what's in hand
on_consume(server, player, item: &str) -> boolFinished eating or drinkingfalse: nothing is eaten
on_container_open(server, player, pos, block: &str) -> boolOpening a chest, furnace or other block screenfalse keeps it shut
on_teleport(server, player, to)Teleported (commands, pearls, plugins), feet position
on_dimension_change(server, player, to: u8)Went to another dimension: 0 overworld, 1 Nether, 2 End
on_xp_change(server, player, points: &mut i32)Getting XP (negative takes it away)Change points, 0 cancels
on_sign_change(server, player, pos, front: &mut String, back: &mut String) -> boolWrote a signEdit the text, or false keeps the old text
on_bed_enter(server, player, pos) -> boolRight-clicked a bed (sets spawn)false stops it
on_craft(server, player, item: &str, count: i32) -> boolCrafting something at a table or in the inventoryfalse refuses the craft
on_projectile_hit(server, shooter, target: Target) -> boolTheir arrow or trident hit Target::Mob(id) or Target::Player(id)false: no damage

Blocks

MethodWhenCancel
on_block_break(server, player, pos, block: i32) -> boolPlayer breaking a blockfalse cancels
on_block_place(server, player, pos, block: i32) -> boolPlayer placing a blockfalse cancels

pos is (x, y, z) as i32. block is the block's runtime id.

Mobs and the world

MethodWhenCancel
on_entity_damage(server, player, mob: i64, kind: &str, damage: f32) -> boolPlayer hitting a mob, e.g. kind = "minecraft:cow"false cancels the hit
on_entity_death(server, kind, pos, killer: Option<i64>)Mob died. killer is the player id if a player did it
on_entity_spawn(server, kind, pos) -> boolMob about to spawn (natural, /summon, breeding)false stops it
on_explosion(server, pos, power: f32) -> boolCreeper, TNT or respawn anchor about to explodefalse stops it
on_mob_target(server, mob: i64, kind: &str, player) -> boolA hostile mob wants to go after a playerfalse leaves them alone
on_block_burn(server, pos, block: &str, spread: bool) -> boolFire spreading to a block (spread) or burning one awayfalse stops it
on_explosion_blocks(server, at, blocks: &mut Vec<pos>)An explosion is about to break these blocksRemove positions to keep them, clear for no block damage
on_entity_tame(server, player, mob, kind) -> boolTrying to tame a wolf, cat or horsefalse stops it
on_entity_breed(server, kind, parents) -> boolTwo mobs are about to breedfalse: no baby
on_portal_create(server, player, kind: &str) -> boolLighting a "nether" or "end" portalfalse keeps it unlit
on_block_grow(server, pos, from: &str, to: &str) -> boolA block changes by itself: crops, saplings, grass spreading, leaves decaying, ice meltingfalse keeps it as it is
on_weather_change(server, weather: &str) -> boolWeather changing to "clear", "rain" or "thunder"false keeps it

| on_mob_damage(server, mob, kind: &str, damage, from) -> bool | A mob is hurt by anything but a player: another mob, fire, a fall, an explosion | false cancels the damage | | on_inventory_action(server, player, action: &str, container: &str) -> bool | A player moves items in any screen. action is "take", "place", "swap", "drop", "destroy", "craft" or "other" | false undoes the move | | on_chunk_load(server, player, chunk: (i32, i32)) | A chunk is sent to a player as it comes into view | |

Mob positions are (f32, f32, f32).

Server

MethodWhen
on_server_start(server)Worlds loaded, about to accept players. A good place to start scheduled tasks.
on_server_stop(server)Server stopping, before the final save

Example: a no-grief zone

#![allow(unused)]
fn main() {
fn on_block_break(&self, server: &Server, player: &PlayerInfo, pos: (i32, i32, i32), _block: i32) -> bool {
    let (x, _, z) = pos;
    let in_spawn = x.abs() < 50 && z.abs() < 50;
    if in_spawn {
        server.tell(player.id, "§cYou can't build at spawn.");
    }
    !in_spawn
}
}