Skip to content

Movement and block events

These events tell a mod when feet land on a block and when blocks change, without a mixin of its own. Use the footfall events for wear and trails under players, mounts, and mobs, and BlockChangedCallback for any change to a block, whatever caused it.

Type Summary Status Since Side Thread
BlockChangedCallback Fired after a block in a server level changes. Experimental 2.0.0 server server
BrushStrokeCallback Fired for each brush stroke on a block. Experimental 2.0.0 server server
MobFootfallCallback Fired when a mob comes to rest on a new supporting block, or lands after being airborne. Experimental 1.1.0 server server
PlayerFootfallCallback Fired when a player’s feet come to rest on a new supporting block, or land after being airborne. Experimental 1.0.0 server server
PlayerMountFootfallCallback Fired when a living mount ridden by a player comes to rest on a new supporting block, or lands after being airborne. Experimental 1.0.0 server server

In your mod’s common initializer:

Turn grass into a path where players walk
PlayerFootfallCallback.EVENT.register((player, level, pos, state) -> {
// One step in 50, so only routes players use often wear through.
if (state.is(Blocks.GRASS_BLOCK) && level.getRandom().nextInt(50) == 0) {
level.setBlockAndUpdate(pos, Blocks.DIRT_PATH.defaultBlockState());
}
});

Experimental · Since 1.0.0 · Side: server · Thread: server

PlayerFootfallCallback fires each time a player’s feet land on a block; use it for wear or trails under players. pos comes from Entity#getOnPos: the block that holds the player up, such as the grass block under a player standing in tall grass. The mount and mob footfall events report their pos the same way.

With PathWear, the saved data from the saved data quick start:

Count steps on grass and wear it to a path after 40
PlayerFootfallCallback.EVENT.register((player, level, pos, state) -> {
// Sneaking players tread lightly and leave no wear.
if (player.isShiftKeyDown() || !state.is(Blocks.GRASS_BLOCK)) return;
if (PathWear.get(level).step(pos) >= 40) {
level.setBlockAndUpdate(pos, Blocks.DIRT_PATH.defaultBlockState());
}
});
  • Stope keeps tracking where the feet are while the player is airborne, gliding, riding, or spectating, so the first step afterward compares against where the player really was.
  • A supporting block that changes while the feet stay grounded on it (snow layers building up underfoot) is not noticed until the feet move or land. The same holds for mounts and mobs.

Experimental · Since 1.1.0 · Side: server · Thread: server

MobFootfallCallback reports the footfalls of every loaded mob; use it for wear or trails under mobs.

With PathWear, as for PlayerFootfallCallback:

Wear paths under herd animals, but not under pets
MobFootfallCallback.EVENT.register((mob, level, pos, state) -> {
// Reject cheaply first: this runs for every loaded mob that lands on a new block.
if (!(mob instanceof Animal) || !state.is(Blocks.GRASS_BLOCK)) return;
if (MobOwnership.isKeptByPlayer(mob)) return;
if (PathWear.get(level).step(pos) >= 80) {
level.setBlockAndUpdate(pos, Blocks.DIRT_PATH.defaultBlockState());
}
});
  • Stope keeps tracking a mob’s position while a player rides it, so the first step after the player dismounts compares against where the mob really was.

Experimental · Since 2.0.0 · Side: server · Thread: server

Use BlockChangedCallback to keep a mod’s own state in step with blocks however they change. With PathWear, the saved data from the saved data quick start:

Forget a block's wear when it becomes another block
BlockChangedCallback.EVENT.register((level, pos, oldState, newState) -> {
// A property change (a door opening) keeps the wear; only a new block clears it.
if (oldState.getBlock() != newState.getBlock()) PathWear.get(level).clear(pos);
});
  • A property change of the same block fires (oldState.getBlock() == newState.getBlock()), for example a door opening or crops growing a stage.
  • A change vanilla makes in reaction to another (a lamp lit by a neighbor) fires before the change that caused it: Level#setBlock updates the neighbors before the outer change’s listeners run.