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.
At a glance
Section titled “At a glance”| 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 |
Quick start
Section titled “Quick start”In your mod’s common initializer:
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()); }});PlayerFootfallCallback
Section titled “PlayerFootfallCallback”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:
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()); }});Edge cases
Section titled “Edge cases”- 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.
MobFootfallCallback
Section titled “MobFootfallCallback”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:
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.
BlockChangedCallback
Section titled “BlockChangedCallback”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:
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#setBlockupdates the neighbors before the outer change’s listeners run.
See also
Section titled “See also”- Mob events: hurt, killed, target, and breeding events.
- Lifecycle events: server start, data-pack reload, and level tick events.
- Wear a path where players walk: a guide that builds this step by step.