Add vector helpers

4 files changed, 192 insertions, 15 deletions

diff --git a/builtin/builtin.lua b/builtin/builtin.lua
index d573cba90..34477e6aa 100644
--- a/builtin/builtin.lua
+++ b/builtin/builtin.lua
@@ -11,18 +11,20 @@ math.randomseed(os.time())
 os.setlocale("C", "numeric")
 
 -- Load other files
-dofile(minetest.get_modpath("__builtin").."/serialize.lua")
-dofile(minetest.get_modpath("__builtin").."/misc_helpers.lua")
-dofile(minetest.get_modpath("__builtin").."/item.lua")
-dofile(minetest.get_modpath("__builtin").."/misc_register.lua")
-dofile(minetest.get_modpath("__builtin").."/item_entity.lua")
-dofile(minetest.get_modpath("__builtin").."/deprecated.lua")
-dofile(minetest.get_modpath("__builtin").."/misc.lua")
-dofile(minetest.get_modpath("__builtin").."/privileges.lua")
-dofile(minetest.get_modpath("__builtin").."/auth.lua")
-dofile(minetest.get_modpath("__builtin").."/chatcommands.lua")
-dofile(minetest.get_modpath("__builtin").."/static_spawn.lua")
-dofile(minetest.get_modpath("__builtin").."/detached_inventory.lua")
-dofile(minetest.get_modpath("__builtin").."/falling.lua")
-dofile(minetest.get_modpath("__builtin").."/features.lua")
-dofile(minetest.get_modpath("__builtin").."/voxelarea.lua")
+local modpath = minetest.get_modpath("__builtin")
+dofile(modpath.."/serialize.lua")
+dofile(modpath.."/misc_helpers.lua")
+dofile(modpath.."/item.lua")
+dofile(modpath.."/misc_register.lua")
+dofile(modpath.."/item_entity.lua")
+dofile(modpath.."/deprecated.lua")
+dofile(modpath.."/misc.lua")
+dofile(modpath.."/privileges.lua")
+dofile(modpath.."/auth.lua")
+dofile(modpath.."/chatcommands.lua")
+dofile(modpath.."/static_spawn.lua")
+dofile(modpath.."/detached_inventory.lua")
+dofile(modpath.."/falling.lua")
+dofile(modpath.."/features.lua")
+dofile(modpath.."/voxelarea.lua")
+dofile(modpath.."/vector.lua")
diff --git a/builtin/misc.lua b/builtin/misc.lua
index f4e7dbca6..4be03c38a 100644
--- a/builtin/misc.lua
+++ b/builtin/misc.lua
@@ -106,3 +106,13 @@ function minetest.formspec_escape(str)
 	return str
 end
 
+function math.hypot(x, y)
+	local t
+	x = math.abs(x)
+	y = math.abs(y)
+	t = math.min(x, y)
+	x = math.max(x, y)
+	t = t / x
+	return x * math.sqrt(1 + t * t)
+end
+
diff --git a/builtin/vector.lua b/builtin/vector.lua
new file mode 100644
index 000000000..f534471c2
--- /dev/null
+++ b/builtin/vector.lua
@@ -0,0 +1,136 @@
+
+vector = {}
+
+function vector.new(a, b, c)
+	v = {x=0, y=0, z=0}
+	if type(a) == "table" then
+		v = {x=a.x, y=a.y, z=a.z}
+	elseif a and b and c then
+		v = {x=a, y=b, z=c}
+	end
+	setmetatable(v, {
+		__add = vector.add,
+		__sub = vector.subtract,
+		__mul = vector.multiply,
+		__div = vector.divide,
+		__umn = function(v) return vector.multiply(v, -1) end,
+		__len = vector.length,
+		__eq  = vector.equals,
+	})
+	return v
+end
+
+function vector.equals(a, b)
+	return a.x == b.x and
+	       a.y == b.y and
+	       a.z == b.z
+end
+
+function vector.length(v)
+	return math.hypot(v.x, math.hypot(v.y, v.z))
+end
+
+function vector.normalize(v)
+	return vector.divide(v, vector.length(v))
+end
+
+function vector.round(v)
+	return {
+		x = math.floor(v.x + 0.5),
+		y = math.floor(v.y + 0.5),
+		z = math.floor(v.z + 0.5)
+	}
+end
+
+function vector.distance(a, b)
+	local x = a.x - b.x
+	local y = a.y - b.y
+	local z = a.z - b.z
+	return math.hypot(x, math.hypot(y, z))
+end
+
+function vector.direction(pos1, pos2)
+	local x_raw = pos2.x - pos1.x
+	local y_raw = pos2.y - pos1.y
+	local z_raw = pos2.z - pos1.z
+	local x_abs = math.abs(x_raw)
+	local y_abs = math.abs(y_raw)
+	local z_abs = math.abs(z_raw)
+	if x_abs >= y_abs and
+	   x_abs >= z_abs then
+		y_raw = y_raw * (1 / x_abs)
+		z_raw = z_raw * (1 / x_abs)
+		x_raw = x_raw / x_abs
+	end
+	if y_abs >= x_abs and
+	   y_abs >= z_abs then
+		x_raw = x_raw * (1 / y_abs)
+		z_raw = z_raw * (1 / y_abs)
+		y_raw = y_raw / y_abs
+	end
+	if z_abs >= y_abs and
+	   z_abs >= x_abs then
+		x_raw = x_raw * (1 / z_abs)
+		y_raw = y_raw * (1 / z_abs)
+		z_raw = z_raw / z_abs
+	end
+	return {x=x_raw, y=y_raw, z=z_raw}
+end
+
+
+function vector.add(a, b)
+	if type(b) == "table" then
+		 return vector.new(
+			a.x + b.x,
+			a.y + b.y,
+			a.z + b.z)
+	else
+		return vector.new(
+			a.x + b,
+			a.y + b,
+			a.z + b)
+	end
+end
+
+function vector.subtract(a, b)
+	if type(b) == "table" then
+		return vector.new(
+			a.x - b.x,
+			a.y - b.y,
+			a.z - b.z)
+	else
+		return vector.new(
+			a.x - b,
+			a.y - b,
+			a.z - b)
+	end
+end
+
+function vector.multiply(a, b)
+	if type(b) == "table" then
+		return vector.new(
+			a.x * b.x,
+			a.y * b.y,
+			a.z * b.z)
+	else
+		return vector.new(
+			a.x * b,
+			a.y * b,
+			a.z * b)
+	end
+end
+
+function vector.divide(a, b)
+	if type(b) == "table" then
+		return vector.new(
+			a.x / b.x,
+			a.y / b.y,
+			a.z / b.z)
+	else
+		return vector.new(
+			a.x / b,
+			a.y / b,
+			a.z / b)
+	end
+end
+
diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index a9f2d0d46..5a2fdf102 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -988,12 +988,41 @@ Inventory location:
 - "nodemeta:<X>,<Y>,<Z>": Any node metadata
 - "detached:<name>": A detached inventory
 
+Vector helpers
+---------------
+vector.new([x[, y, z]]) -> vector
+ ^ x is a table or the x position.
+vector.direction(p1, p2) -> vector
+vector.distance(p1, p2) -> number
+vector.length(v) -> number
+vector.normalize(v) -> vector
+vector.round(v) -> vector
+vector.equal(v1, v2) -> bool
+vector.add(v, x) -> vector
+ ^ x can be annother vector or a number
+vector.subtract(v, x) -> vector
+vector.multiply(v, x) -> vector
+vector.divide(v, x) -> vector
+
+You can also use Lua operators on vectors.
+For example:
+	v1 = vector.new()
+	v1 = v1 + 5
+	v2 = vector.new(v1)
+	v1 = v1 * v2
+	if v1 == v2 then
+		error("Math broke")
+	end
+
 Helper functions
 -----------------
 dump2(obj, name="_", dumped={})
 ^ Return object serialized as a string, handles reference loops
 dump(obj, dumped={})
 ^ Return object serialized as a string
+math.hypot(x, y)
+^ Get the hypotenuse of a triangle with legs x and y.
+  Usefull for distance calculation.
 string:split(separator)
 ^ eg. string:split("a,b", ",") == {"a","b"}
 string:trim()