Page 1 of 1

[Mod] Position listeners library (poschangelib)

PostPosted: Tue Jul 25, 2017 19:06
by karamel
Version 0.3: ...
Licence: LGPL v2
Dependencies: none
Source code:
Documentation: See README


Register functions to be called when the players are moving or walking on certain nodes. It does nothing by itself but is used as a dependency of other mods.

This feature is already implemented in multiple mods. So why not using only one code for them all? It is still a workaround which has it's flaws, but it's probably better than nothing.

The aim of this mod is to get only one mod to maintain and cover a wide range of uses. It must be light enough to bring the least lag as possible. At least to be better than stacking a lot of redundant checks across all the mods.

It's similar to the Walkover mod and in fact is compatible, but aims to be wider.

It comes with advanced features like interpolation and double check for half-nodes but all of them can be ignored in a way or an other. The lib passes some metadata to the listeners to know how they were called (that is you can ignore all the calls from interpolation if you don't want to compute useless things when only the last position is relevant).


  • Players' movement listener (0.1)
  • Interpolation of fast movements (0.3)
  • Walking on nodes (0.1) and in nodes (0.4)
  • Stomping (replacing a node by an other), footprints and automatic revert after a given time (0.4)
  • Compatible with non-filled nodes like slabs and snow (0.2)
  • Support for _on_walk_over (and on_walk_over) from Walkover (0.1)
  • Configurable checking interval (0.1)
  • Detect teleportation with a configurable range (0.3(

Missing features

  • Support for other things than players

About non-filled nodes

There was an issue with 0.1 in the walk detection on snow and generally non-filled blocks. When walking on a thin snow layer (the snow node), the node below the snow was considered being walked on and not the snow itself. You had to stand on the node above the snow to make it work.

I've looked at the code of the trail mod to check how it was handled and it was hardcoded. I haven't found an elegant way to handle collision checking while staying fast, so those special cases must be handled on the listener side with some new metadata that are passed to the listeners (and may be ignored most of the time).

About interpolation and teleportation

This lib checks the players' position at a given interval, but cannot do much more. So when the player is moving fast we can only know where he/she was at last check and now, but not by which way he/she went between these two points.

The interpolation takes the shortest path between the two spots, randomly if there are multiple candidates. This is absolutely not accurate for more than 3 nodes away. There is indeed no way to quickly check if a node is passable so the path may be computed across trees and stone the same way it can for air or stairs. Because this interpolation is meant for only short paths, I may leave it like this. You may want to check the metadata if some position are critical (for example lava).

Teleportation suffer from the same issue. There is no way to know if the player teleported from point A to B or walked there. The lib just assumes that if the distance is too long, it's more likely to be a teleportation.

About stomping

Stomping dedicates itself to replacing a node by an other. It isn't a simple walk listener because there could be multiple listeners for the same kind of node and if one replaced the node, the other could still replace it (or do something that will conflict with the new node).

Because of this, stomping let you define a priority on registration. If a stomp triggers, the others with less priority (higher value) won't be triggered. A duration can be registered for stomped nodes to revert to their original node (or an other) after a given time.

Footprints are a specific case of the stomping feature. It registers the footprinted node and the stomping behaviour in one registration call. A footprint texture is embedded but you can specify the one you want to use upon registration.

Mods using this lib:

Re: [Mod] Position listeners library (poschangelib)

PostPosted: Mon Jul 31, 2017 22:15
by karamel
Version 0.2 is out.

It handles the case of snow and slabs that were buggy.

Re: [Mod] Position listeners library (poschangelib)

PostPosted: Tue Aug 01, 2017 09:46
by azekill_DIABLO
awesome for weather and aura mods. same for achievments!

Re: [Mod] Position listeners library (poschangelib)

PostPosted: Thu Aug 03, 2017 22:08
by karamel
Version 0.3 is out. It lacks a lot of real use feedback and testing but version 1.0 is not far away (support for non player movements will probably be a post 1.0 feature)

Interpolation gave me some reminders about how complex pathfinding is until I thought I probably won't have to get something that precise.

Re: [Mod] Position listeners library (poschangelib)

PostPosted: Fri Aug 25, 2017 21:36
by karamel
Version 0.4, with 2 new features.

You can now listen to the players walking inside nodes (like grass or flowers).

And the stomping feature was added to handle the specific case of replacing a node by an other one with more options. It comes with a tool to register footprints. The replacement can be definitive or temporary, so you won't have all your nodes footprinted after a while.

Re: [Mod] Position listeners library (poschangelib)

PostPosted: Wed Aug 30, 2017 16:06
by karamel
Version 0.5

A lot of bugfixes and some ease of use for footprints. Only that.