Initial commit

.gitattributes

+# Auto detect text files and perform LF normalization
+* text=auto

LICENSE

+MIT License
+
+Copyright (c) 2018 entuland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

+# Rhotator Screwdriver (rhotator)
+
+A different twist at Minetest screwdriving.
+
+Developed and tested on Minetest 0.4.16 - try in other versions at your own risk :)
+
+If you like my contributions you may consider reading http://entuland.com/en/support-entuland
+
+# Why yet another screwdriver?
+
+The default screwdriver included in minetest_game, as well as any other screwdriver mod I have found, operate differently depending on the node's direction and rotation. This means that any given click on a node may produce different results which you cannot predict at a glance.
+
+The Rhotator Screwdriver uses a different approach: the direction and orientation of the node make absolutely no difference.
+
+These are the factors that affect the results of a click:
+
+- the face you point at
+- where on that face you point
+- what button you click
+
+You will always be able to predict exactly the effect of the Rhotator Screwdriver.
+
+Four consecutive clicks of the same button on the same position will always bring the node back to its original direction / orientation.
+
+### Why is it called "Rhotator" and not "Rotator"?
+
+In mathematics, the greek letter *Rho* is used to indicate some stuff associated to certain types of matrices. Since I'm using matrices to compute the various rotations in the game I thought about including it in the mod's name to reduce the chance of naming conflicts.
+
+# Appearance
+
+Here you can see the Rhotator Screwdriver along with the Testing Cube.
+
+*The testing cube is just an addition to help practicing with this screwdriver.*
+
+The Rhotator Screwdriver will rotate ANY node where `paramtype2 == "facedir"`
+
+More node types will be supported in the future.
+
+![Preview](/screenshots/preview.png)
+
+# Usage
+
+Pretty simple:
+
+- a right click will rotate the face you're pointing in clockwise direction
+  - the arrow in the Testing Cube shows how the face will rotate when right-clicked
+  - `RT` in the tool stands for `rotate`
+
+- a left click will rotate the node as if you "pushed" the closest edge you're pointing at
+  - the colored edges in the Testing Cube indicate the color of the face you'll see when left-clicking near that edge
+  - `PS` in the tool stands for `push`
+
+The left-click interaction area is not limited to the edges you can see in the Testing Cube. In reality you can click anywhere in a triangle like this (highlighted here just for convenience, you won't see anything like this in the game):
+
+![Interaction triangle](/screenshots/interaction-triangle.png)
+
+# Non-full nodes
+
+Nodes that don't occupy a full cube (such as slabs and stairs) can still be rotated properly, it's enough that you pay attention to the direction of the part you're pointing at - the "stomp" parts of the stairs will behave as the "top" face, the "rise" parts will behave as the "front" face. With the Rhotator Screwdriver there never really is a "top" or a "front" or whatever: the only thing that matters is the face you're pointing at.
+
+# Crafting
+
+Rhotator Screwdriver: a stick and a copper ingot;
+
+![Screwdriver crafting](/screenshots/screwdriver-crafting.png)
+
+Rhotator Testing Cube: a Rhotator Screwdriver and any wool block
+
+![Testing cube crafting](/screenshots/testcube-crafting.png)
+
+# Usage feedback
+
+At the beginning of [init.lua](/init.lua) there is a line reading `local enable_chat_notifications = false` - set it to `true` if you want the tool to send you chat messages about the operations it performs and in particular about nodes that aren't currently supported (if you enable the chat notifications you'll receive messages like these:
+
+- Pushed closest edge (left click)
+- Rotated pointed face (right click)
+- Cannot rotate node with paramtype2 == glasslikeliquidlevel

init.lua

+rhotator = {}
+
+rhotator.mod_path = minetest.get_modpath(minetest.get_current_modname())
+
+local matrix = dofile(rhotator.mod_path .. "/lib/matrix.lua")
+
+local enable_chat_notifications = true
+
+-- constants
+
+local POS = {}
+local NEG = {}
+POS.Y = 0
+POS.Z = 1
+NEG.Z = 2
+POS.X = 3
+NEG.X = 4
+NEG.Y = 5
+
+PRIMARY_BTN = 1
+SECONDARY_BTN = 2
+
+-- helper tables
+
+local rot_matrices = {}
+local dir_matrices = {}
+
+-- init
+
+local function init_transforms()
+	local rot = {}
+	local dir = {}
+
+	-- no rotation
+	rot[0] = matrix{{  1,  0,  0},
+	                {  0,  1,  0},
+	                {  0,  0,  1}}
+	-- 90 degrees clockwise
+	rot[1] = matrix{{  0,  0,  1},
+	                {  0,  1,  0},
+	                { -1,  0,  0}}
+	-- 180 degrees
+	rot[2] = matrix{{ -1,  0,  0},
+	                {  0,  1,  0},
+	                {  0,  0, -1}}
+	-- 270 degrees clockwise
+	rot[3] = matrix{{  0,  0, -1},
+	                {  0,  1,  0},
+	                {  1,  0,  0}}
+
+	rot_matrices = rot
+
+	-- directions
+	-- Y+
+	dir[0] = matrix{{  1,  0,  0},
+	                {  0,  1,  0},
+	                {  0,  0,  1}}
+	-- Z+
+	dir[1] = matrix{{  1,  0,  0},
+	                {  0,  0, -1},
+	                {  0,  1,  0}}
+	-- Z-
+	dir[2] = matrix{{  1,  0,  0},
+	                {  0,  0,  1},
+	                {  0, -1,  0}}
+	-- X+
+	dir[3] = matrix{{  0,  1,  0},
+	                { -1,  0,  0},
+	                {  0,  0,  1}}
+	-- X-
+	dir[4] = matrix{{  0, -1,  0},
+	                {  1,  0,  0},
+	                {  0,  0,  1}}
+	-- Y-
+	dir[5] = matrix{{ -1,  0,  0},
+	                {  0, -1,  0},
+	                {  0,  0,  1}}
+
+	dir_matrices = dir
+
+	rhotator._facedir_transform = {}
+	rhotator._matrix_to_facedir = {}
+
+	for facedir = 0, 23 do
+		local direction = math.floor(facedir / 4)
+		local rotation = facedir % 4
+		local transform = dir[direction] * rot[rotation]
+		rhotator._facedir_transform[facedir] = transform
+		rhotator._matrix_to_facedir[transform:tostring():gsub("%-0", "0")] = facedir
+	end
+
+end
+
+init_transforms()
+
+-- helper functions
+
+local function cross_product(a, b)
+	return vector.new(
+		a.y * b.z - a.z * b.y,
+		a.z * b.x - a.x * b.z,
+		a.x * b.y - a.y * b.x
+	)
+end
+
+local function extract_main_axis(dir)
+	local axes = { "x", "y", "z" }
+	local axis = 1
+	local max = 0
+	for i = 1, 3 do
+		local abs = math.abs(dir[axes[i]])
+		if abs > max then
+			axis = i
+			max = abs
+		end
+	end
+	return axes[axis]
+end
+
+local function sign(num)
+	return (num < 0) and -1 or 1
+end
+
+local function extract_unit_vectors(player, pointed_thing)
+	assert(pointed_thing.type == "node")
+	local abs_face_pos = minetest.pointed_thing_to_face_pos(player, pointed_thing)
+	local pos = pointed_thing.under
+	local f = vector.subtract(abs_face_pos, pos)
+	local facedir = 0
+	local primary = 0
+
+	local m1, m2
+
+	local unit_direction = vector.new()
+	local unit_rotation = vector.new()
+	local rotation = vector.new()
+
+	if math.abs(f.y) == 0.5 then
+		unit_direction.y = sign(f.y)
+		rotation.x = f.x
+		rotation.z = f.z
+	elseif math.abs(f.z) == 0.5 then
+		unit_direction.z = sign(f.z)
+		rotation.x = f.x
+		rotation.y = f.y
+	else
+		unit_direction.x = sign(f.x)
+		rotation.y = f.y
+		rotation.z = f.z
+	end
+
+	local main_axis = extract_main_axis(rotation)
+
+	unit_rotation[main_axis] = sign(rotation[main_axis])
+
+	return {
+		back = unit_direction,
+		wrap = unit_rotation,
+		thumb = cross_product(unit_direction, unit_rotation),
+	}
+end
+
+local function get_facedir_transform(facedir)
+	return rhotator._facedir_transform[facedir] or rhotator._facedir_transform[0]
+end
+
+local function matrix_to_facedir(mtx)
+	local key = mtx:tostring():gsub("%-0", "0")
+	if not rhotator._matrix_to_facedir[key] then
+		error("Unsupported matrix:\n" .. key)
+	end
+	return rhotator._matrix_to_facedir[key]
+end
+
+local function notify(playername, message)
+	if enable_chat_notifications then
+		minetest.chat_send_player(playername, "[rhotator] " .. message)
+	end
+end
+
+local function vector_to_dir_index(vec)
+	local main_axis = extract_main_axis(vec)
+	if main_axis == "x" then return (vec.x > 0) and POS.X or NEG.X end
+	if main_axis == "z" then return (vec.z > 0) and POS.Z or NEG.Z end
+	return (vec.y > 0) and POS.Y or NEG.Y
+end
+
+-- rhotator main
+
+local function interact(itemstack, player, pointed_thing, click)
+	if pointed_thing.type ~= "node" then
+		return
+	end
+
+	local node = minetest.get_node_or_nil(pointed_thing.under)
+	local def = minetest.registered_nodes[node.name]
+
+	if not node or not def then
+		notify(player:get_player_name(), "Unsupported node type: " .. node.name)
+		return
+	end
+
+	if def.paramtype2 ~= "facedir" then
+		notify(player:get_player_name(), "Cannot rotate node with paramtype2 == " .. def.paramtype2)
+		return
+	end
+
+	local unit = extract_unit_vectors(player, pointed_thing)
+
+	local transform = false
+
+	if click == PRIMARY_BTN then
+		transform = dir_matrices[vector_to_dir_index(unit.thumb)]
+		notify(player:get_player_name(), "Pushed closest edge (left click)")
+	else
+		transform = dir_matrices[vector_to_dir_index(unit.back)]
+		notify(player:get_player_name(), "Rotated pointed face (right click)")
+	end
+
+	local start = get_facedir_transform(node.param2)
+	local stop = transform * rot_matrices[1] * transform:invert() * start
+
+	minetest.set_node(pointed_thing.under,{
+		name = node.name,
+		param1 = node.param1,
+		param2 = matrix_to_facedir(stop),
+	})
+
+end
+
+minetest.register_tool("rhotator:screwdriver", {
+	description = "Rhotator Screwdriver (left-click pushes edge, right-click rotates face)",
+	inventory_image = "rhotator.png",
+	on_use = function(itemstack, player, pointed_thing)
+		interact(itemstack, player, pointed_thing, PRIMARY_BTN)
+		return itemstack
+	end,
+	on_place = function(itemstack, player, pointed_thing)
+		interact(itemstack, player, pointed_thing, SECONDARY_BTN)
+		return itemstack
+	end,
+})
+
+minetest.register_craft({
+	output = "rhotator:screwdriver",
+	recipe = {
+		{"default:copper_ingot"},
+		{"group:stick"}
+	}
+})
+
+minetest.register_node("rhotator:cube", {
+	drawtype = "mesh",
+	mesh = "rhotocube.obj",
+	tiles = { "rhotocube.png" },
+	paramtype2 = "facedir",
+	description = "Rhotator Testing Cube",
+	walkable = true,
+	groups = { snappy = 2, choppy = 2, oddly_breakable_by_hand = 3 },
+})
+
+minetest.register_craft({
+	output = "rhotator:cube",
+	recipe = {
+		{"group:wool"},
+		{"rhotator:screwdriver"},
+	}
+})

mod.conf

+name = rhotator

models/rhotocube.obj

+v -0.500000 -0.500000 0.500000
+v -0.500000 -0.500000 -0.500000
+v 0.500000 -0.500000 -0.500000
+v 0.500000 -0.500000 0.500000
+v -0.500000 0.500000 0.500000
+v -0.499999 0.500000 -0.500000
+v 0.500000 0.500000 -0.500000
+v 0.500000 0.500000 0.500000
+vt 0.666667 -0.000000
+vt 0.666667 0.500000
+vt 0.333333 0.500000
+vt 0.333333 -0.000000
+vt 0.666667 1.000000
+vt 0.333333 1.000000
+vt 0.333333 0.500000
+vt 0.666667 0.500000
+vt 0.333333 0.500000
+vt 0.333333 1.000000
+vt -0.000000 1.000000
+vt 0.000000 0.500000
+vt 1.000000 0.000000
+vt 1.000000 0.500000
+vt 0.666667 0.500000
+vt 0.666667 -0.000000
+vt 0.333333 -0.000000
+vt 0.000000 0.500000
+vt -0.000000 -0.000000
+vt 0.666667 0.500000
+vt 1.000000 0.500000
+vt 1.000000 1.000000
+vn 0.0000 -1.0000 0.0000
+vn 0.0000 1.0000 0.0000
+vn -1.0000 0.0000 -0.0000
+vn 0.0000 -0.0000 -1.0000
+vn 1.0000 -0.0000 0.0000
+vn -0.0000 0.0000 1.0000
+s off
+f 1/1/1 2/2/1 3/3/1 4/4/1
+f 5/5/2 8/6/2 7/7/2 6/8/2
+f 1/9/3 5/10/3 6/11/3 2/12/3
+f 2/13/4 6/14/4 7/15/4 3/16/4
+f 3/17/5 7/7/5 8/18/5 4/19/5
+f 5/5/6 1/20/6 4/21/6 8/22/6