Minetest mod library: poschangelib
==================================
version 0.1

See LICENSE for license information

This lib adds utilities to watch player movements and trigger things when they are
spotted moving.

It does nothing by itself but aim to ease event based upon players or item
moving.

All positions are rounded to node position (integer coordinates).

Summary
  - General warning
  - Watch players' movements
  - Watch players walking on particular nodes
  - Add _on_walk on nodes
  - Configuration/Performances tweaking


General warning
---------------

This mod may be resources consuming. The mods relying upon this lib should use
small functions not to decrease the server performances too much.

The more functions are provided, the more the server can lag (but probably a little
less than running every of them without the lib).



Watch player's movements
------------------------

Use poschangelib.add_player_pos_listener(name, my_callback)

Name is the identifier the listener, to use in remove_player_pos_listener. You should
follow the naming convention like for node names. See http://dev.minetest.net/Intro

The my_callback is a function that takes 3 arguments: the player, last known position
and new position.

On first call (once a player joins) the last known position will be nil. If your
listener does something in that case, it will be called shortly after the player
reconnects. It may so be triggered twice from the same position, before leaving and
after joining.

Be aware that the new position may not always be a neigrbor of the old one.
When on teleporting, programatic moves with setpos or moving fast it may be far away.

Quick code sample:

local function my_callback(player, old_pos, new_pos)
	if old_pos == nil then
		minetest.chat_send_player(player:get_player_name(), 'Welcome to the world!')
	else
		minetest.chat_send_player(player:get_player_name(),
			"You are now at x:" .. new_pos.x .. ", y:" .. new_pos.y ..
			"z:" .. new_pos.z)
	end
end
poschangelib.add_player_pos_listener("sample:pos_listener", my_callback)



Watch player walking on particular nodes
----------------------------------------

Use poschangelib.add_player_walk_listener(name, my_callback, nodenames)

The name is used in the same way as for player position listeners. It aims at reducing
the number of time the stepped node is fetched to share it accross all listeners.

The callback is a function that takes 4 arguments: the player, the position, the node
stepped on and that node description.
See http://dev.minetest.net/minetest.register_node for node description.

You can register the listener for a list of node name or groups, in the same way you
do it to register an ABM. See http://dev.minetest.net/register_abm

For example:
local function flop(player, pos, node, desc)
	minetest.chat_send_player(player:get_player_name(), 'Flop flop')
end
poschangelib.add_player_walk_listener('sample:flop', flop, {'default:dirt_with_grass'})

local function toptop(player, pos, node, desc)
	minetest.chat_send_player(player:get_player_name(), 'Top top top')
end
poschangelib.add_player_walk_listener('sample:top', toptop, {'group:choppy'})



Add _on_walk_over to nodes
-------------------------

This behaviour is ported from the walkover mod only for compatibility.
https://forum.minetest.net/viewtopic.php?f=9&t=15991

A new node property can be added in node definitions:
	_on_walk_over = <function>

This function takes the position, the node and the player as argument.

For compatibility with walkover, you can use on_walk_over (without the underscore
prefix) but it is discouraged as stated in the forum post. This support may be dropped
at any time when most mods have updated the name.

A performance tweak disable on walk checks if there is no player walk listener.
To be sure the check is done if you are only using _on_walk_over, you may register a
dummy listener on a unknown node name.



Configuration/Performances tweaking
-----------------------------------

The lib checks for position at a given interval. Default is every 0.3 seconds.

This can be changed by setting poschangelib.check_interval in minetest.conf
or in advanced settings.

Setting a lower value will make the lib more accurate but will be more demanding
on resources (down to 0.05 which is a every server tick).

If the server is lagging, try increasing the interval. If the server can afford
more precise checks you can decrease the value.