Version 1.5.1

README.md

@@ -1,11 +1,14 @@
 # Schematic Editor [`schemedit`]
 
 ## Version
-1.2.0
+1.5.1
 
 ## Description
 This is a mod which allows you to edit and export schematics (`.mts` files).
 
+This mod works in Minetest 5.0.0 or later, but recommended is version 5.1.0
+or later.
+
 It supports node probabilities, forced node placement and slice probabilities.
 
 It adds 3 items:
@@ -14,12 +17,23 @@ It adds 3 items:
 * Schematic Void: Marks a position in a schematic which should not replace anything when placed as a schematic
 * Schematic Node Probability Tool: Set per-node probabilities and forced node placement
 
-It also adds the server command `placeschem` to place a schematic.
+Note: The import feature requires Minetest 5.1.0 or later.
+
+It also adds these server commands:
+
+* `placeschem` to place a schematic
+* `mts2lua` to convert .mts files to .lua files (Lua code)
+
+There's also a setting `schemedit_export_lua` to enable automatic export to .lua files.
 
 ## Usage help
-Usage help can be found when you use the optional Help modpack (mods `doc` and `doc_items`).
+This mod assumes you already have a basic understanding about how schematics in Minetest work.
+If not, refer to the Minetest Lua API documentation to understand more about schematics.
 
-You should also refer to the Minetest Lua API documentation to understand more about schematics.
+To learn how to use all the items in this mod, read `USAGE.md`.
+
+You can also find the same help texts in-game if you if you use the optional Help modpack
+(mods `doc` and `doc_items`).
 
 ## License of everything
 MIT License

USAGE.md

@@ -0,0 +1,44 @@
+## Usage help
+In this section you'll learn how to use the items of this mod.
+Note: If you have the `doc` and `doc_items` mods installed, you can also access the same help texts in-game (possibly translated).
+
+### Schematic Creator
+The schematic creator is used to save a region of the world into a schematic file (.mts).
+
+#### Usage
+To get started, place the block facing directly in front of any bottom left corner of the structure you want to save. This block can only be accessed by the placer or by anyone with the “`schematic_override`” privilege.
+To save a region, use the block, enter the size and a schematic name and hit “Export schematic”. The file will always be saved in the world directory. Note you can use this name in the /placeschem command to place the schematic again.
+
+Importing a schematic will load a schematic from the world directory, place it in front of the schematic creator and sets probability and force-place data accordingly.
+The other features of the schematic creator are optional and are used to allow to add randomness and fine-tuning.
+
+Y slices are used to remove entire slices based on chance. For each slice of the schematic region along the Y axis, you can specify that it occurs only with a certain chance. In the Y slice tab, you have to specify the Y slice height (0 = bottom) and a probability from 0 to 255 (255 is for 100%). By default, all Y slices occur always.
+
+With a schematic node probability tool, you can set a probability for each node and enable them to overwrite all nodes when placed as schematic. This tool must be used prior to the file export.
+
+
+### Schematic Node Probability Tool
+This is an advanced tool which only makes sense when used together with a schematic creator. It is used to finetune the way how nodes from a schematic are placed.
+It allows you to set two things:
+1) Set probability: Chance for any particular node to be actually placed (default: always placed)
+2) Enable force placement: These nodes replace node other than air and ignore when placed in a schematic (default: off)
+
+#### Usage
+
+BASIC USAGE:
+Punch to configure the tool. Select a probability (0-255; 255 is for 100%) and enable or disable force placement. Now place the tool on any node to apply these values to the node. This information is preserved in the node until it is destroyed or changed by the tool again. This tool has no effect on schematic voids.
+Now you can use a schematic creator to save a region as usual, the nodes will now be saved with the special node settings applied.
+
+NODE HUD:
+To help you remember the node values, the nodes with special values are labelled in the HUD. The first line shows probability and force placement (with “[F]”). The second line is the current distance to the node. Nodes with default settings and schematic voids are not labelled.
+To disable the node HUD, unselect the tool or hit “place” while not pointing anything.
+
+UPDATING THE NODE HUD:
+The node HUD is not updated automatically and may be outdated. The node HUD only updates the HUD for nodes close to you whenever you place the tool or press the punch and sneak keys simultaneously. If you sneak-punch a schematic creator, then the node HUD is updated for all nodes within the schematic creator's region, even if this region is very big.
+
+
+### Schematic Void
+This is an utility block used in the creation of schematic files. It should be used together with a schematic creator. When saving a schematic, all nodes with a schematic void will be left unchanged when the schematic is placed again. Technically, this is equivalent to a block with the node probability set to 0.
+
+#### Usage
+Just place the schematic void like any other block and use the schematic creator to save a portion of the world.

init.lua

@@ -1,12 +1,18 @@
-local S = minetest.get_translator("schemedit")
+local S
+if minetest.get_translator then
+	S = minetest.get_translator("schemedit")
+else
+	S = function(s) return s end
+end
 local F = minetest.formspec_escape
 
 local schemedit = {}
 
--- Directory delimeter fallback (normally comes from builtin)
-if not DIR_DELIM then
-	DIR_DELIM = "/"
-end
+local DIR_DELIM = "/"
+
+-- Set to true to enable `make_schemedit_readme` command
+local MAKE_README = false
+
 local export_path_full = table.concat({minetest.get_worldpath(), "schems"}, DIR_DELIM)
 
 -- truncated export path so the server directory structure is not exposed publicly
@@ -28,6 +34,38 @@ local function renumber(t)
 	return res
 end
 
+local NEEDED_PRIV = "server"
+local function check_priv(player_name, quit)
+	local privs = minetest.get_player_privs(player_name)
+	if privs[NEEDED_PRIV] then
+		return true
+	else
+		if not quit then
+			minetest.chat_send_player(player_name, minetest.colorize("red",
+					S("Insufficient privileges! You need the “@1” privilege to use this.", NEEDED_PRIV)))
+		end
+		return false
+	end
+end
+
+-- Lua export
+local export_schematic_to_lua
+if can_import then
+	export_schematic_to_lua = function(schematic, filepath, options)
+		if not options then options = {} end
+		local str = minetest.serialize_schematic(schematic, "lua", options)
+		local file = io.open(filepath, "w")
+		if file and str then
+			file:write(str)
+			file:flush()
+			file:close()
+			return true
+		else
+			return false
+		end
+	end
+end
+
 ---
 --- Formspec API
 ---
@@ -112,7 +150,8 @@ function schemedit.show_formspec(pos, player, tab, show, ...)
 
 			-- Update player attribute
 			if forms[tab].cache_name ~= false then
-				player:set_attribute("schemedit:tab", tab)
+				local pmeta = player:get_meta()
+				pmeta:set_string("schemedit:tab", tab)
 			end
 		else
 			minetest.close_formspec(pname, "schemedit:"..tab)
@@ -254,30 +293,34 @@ schemedit.add_form("main", {
 
 		local xs, ys, zs = meta.x_size or 1, meta.y_size or 1, meta.z_size or 1
 		local size = {x=xs, y=ys, z=zs}
+		local schem_name = meta.schem_name or ""
 
 		local form = [[
 			size[7,8]
 			label[0.5,-0.1;]]..F(S("Position: @1", strpos))..[[]
 			label[3,-0.1;]]..F(S("Owner: @1", name))..[[]
-			label[0.5,0.4;]]..F(S("Schematic name: @1", meta.schem_name))..[[]
+			label[0.5,0.4;]]..F(S("Schematic name: @1", F(schem_name)))..[[]
 			label[0.5,0.9;]]..F(S("Size: @1", minetest.pos_to_string(size)))..[[]
 
-			field[0.8,2;5,1;name;]]..F(S("Schematic name:"))..[[;]]..F(meta.schem_name or "")..[[]
+			field[0.8,2;5,1;name;]]..F(S("Schematic name:"))..[[;]]..F(schem_name or "")..[[]
 			button[5.3,1.69;1.2,1;save_name;]]..F(S("OK"))..[[]
 			tooltip[save_name;]]..F(S("Save schematic name"))..[[]
 			field_close_on_enter[name;false]
 
 			button[0.5,3.5;6,1;export;]]..F(S("Export schematic")).."]"..
 			import_btn..[[
-			textarea[0.8,4.5;6.2,5;;]]..F(S("Export/import path:\n@1",
+			textarea[0.8,4.5;6.2,1;;]]..F(S("Export/import path:\n@1",
 			export_path_trunc .. DIR_DELIM .. F(S("<name>"))..".mts"))..[[;]
+			button[0.5,5.5;3,1;air2void;]]..F(S("Air to voids"))..[[]
+			button[3.5,5.5;3,1;void2air;]]..F(S("Voids to air"))..[[]
+			tooltip[air2void;]]..F(S("Turn all air nodes into schematic void nodes"))..[[]
+			tooltip[void2air;]]..F(S("Turn all schematic void nodes into air nodes"))..[[]
 			field[0.8,7;2,1;x;]]..F(S("X size:"))..[[;]]..xs..[[]
 			field[2.8,7;2,1;y;]]..F(S("Y size:"))..[[;]]..ys..[[]
 			field[4.8,7;2,1;z;]]..F(S("Z size:"))..[[;]]..zs..[[]
 			field_close_on_enter[x;false]
 			field_close_on_enter[y;false]
 			field_close_on_enter[z;false]
-
 			button[0.5,7.5;3,1;save;]]..F(S("Save size"))..[[]
 		]]..
 		border_button
@@ -288,6 +331,15 @@ schemedit.add_form("main", {
 		return form
 	end,
 	handle = function(self, pos, name, fields)
+		if fields.doc then
+			doc.show_entry(name, "nodes", "schemedit:creator", true)
+			return
+		end
+
+		if not check_priv(name, fields.quit) then
+			return
+		end
+
 		local realmeta = minetest.get_meta(pos)
 		local meta = realmeta:to_table().fields
 		local hashpos = minetest.hash_node_position(pos)
@@ -317,8 +369,18 @@ schemedit.add_form("main", {
 			meta.schem_name = fields.name
 		end
 
-		if fields.doc then
-			doc.show_entry(name, "nodes", "schemedit:creator", true)
+		-- Node conversion
+		if (fields.air2void) then
+			local pos1, pos2 = schemedit.size(pos)
+			pos1, pos2 = schemedit.sort_pos(pos1, pos2)
+			local nodes = minetest.find_nodes_in_area(pos1, pos2, {"air"})
+			minetest.bulk_set_node(nodes, {name="schemedit:void"})
+			return
+		elseif (fields.void2air) then
+			local pos1, pos2 = schemedit.size(pos)
+			pos1, pos2 = schemedit.sort_pos(pos1, pos2)
+			local nodes = minetest.find_nodes_in_area(pos1, pos2, {"schemedit:void"})
+			minetest.bulk_set_node(nodes, {name="air"})
 			return
 		end
 
@@ -358,7 +420,7 @@ schemedit.add_form("main", {
 			local slice_list = {}
 			for _, i in pairs(slist) do
 				slice_list[#slice_list + 1] = {
-					ypos = pos.y + i.ypos,
+					ypos = i.ypos,
 					prob = schemedit.lua_prob_to_schematic_prob(i.prob),
 				}
 			end
@@ -369,6 +431,16 @@ schemedit.add_form("main", {
 			if res then
 				minetest.chat_send_player(name, minetest.colorize("#00ff00",
 						S("Exported schematic to @1", filepath)))
+				-- Additional export to Lua file if MTS export was successful
+				local schematic = minetest.read_schematic(filepath, {})
+				if schematic and minetest.settings:get_bool("schemedit_export_lua") then
+					local filepath_lua = path..meta.schem_name..".lua"
+					res = export_schematic_to_lua(schematic, filepath_lua)
+					if res then
+						minetest.chat_send_player(name, minetest.colorize("#00ff00",
+								S("Exported schematic to @1", filepath_lua)))
+					end
+				end
 			else
 				minetest.chat_send_player(name, minetest.colorize("red",
 						S("Failed to export schematic to @1", filepath)))
@@ -377,12 +449,6 @@ schemedit.add_form("main", {
 
 		-- Import schematic
 		if fields.import and meta.schem_name and meta.schem_name ~= "" then
-			if not minetest.get_player_privs(name).debug then
-				minetest.chat_send_player(name, minetest.colorize("red",
-						S("Insufficient privileges! You need the “debug” privilege to do this.")))
-				return
-			end
-
 			if not can_import then
 				return
 			end
@@ -398,14 +464,19 @@ schemedit.add_form("main", {
 				meta.x_size = schematic.size.x
 				meta.y_size = schematic.size.y
 				meta.z_size = schematic.size.z
-				meta.slices = minetest.serialize(schematic.yslice_prob)
+				meta.slices = minetest.serialize(renumber(schematic.yslice_prob))
+				local special_x_size = meta.x_size
+				local special_y_size = meta.y_size
+				local special_z_size = meta.z_size
 
 				if node.param2 == 1 then
 					pos1 = vector.add(pos, {x=1,y=0,z=-meta.z_size+1})
+					meta.x_size, meta.z_size = meta.z_size, meta.x_size
 				elseif node.param2 == 2 then
 					pos1 = vector.add(pos, {x=-meta.x_size+1,y=0,z=-meta.z_size})
 				elseif node.param2 == 3 then
 					pos1 = vector.add(pos, {x=-meta.x_size,y=0,z=0})
+					meta.x_size, meta.z_size = meta.z_size, meta.x_size
 				else
 					pos1 = vector.add(pos, {x=0,y=0,z=1})
 				end
@@ -423,9 +494,9 @@ schemedit.add_form("main", {
 				-- Add special schematic data to nodes
 				if success then
 					local d = 1
-					for z=0, meta.z_size-1 do
-					for y=0, meta.y_size-1 do
-					for x=0, meta.x_size-1 do
+					for z=0, special_z_size-1 do
+					for y=0, special_y_size-1 do
+					for x=0, special_x_size-1 do
 						local data = schematic_for_meta.data[d]
 						local pp = {x=pos1.x+x, y=pos1.y+y, z=pos1.z+z}
 						if data.prob == 0 then
@@ -497,19 +568,29 @@ schemedit.add_form("slice", {
 			table[0,0;6.8,6;slices;]]..slices..[[;]]..selected..[[]
 		]]
 
+		-- Close edit panel if no slices
+		if self.panel_edit and slices == "" then
+			self.panel_edit = nil
+		end
+
 		if self.panel_add or self.panel_edit then
 			local ypos_default, prob_default = "", ""
-			local done_button = "button[5,7.18;2,1;done_add;"..F(S("Done")).."]"
+			local done_button = "button[5,7.18;2,1;done_add;"..F(S("Add")).."]"
 			if self.panel_edit then
-				done_button = "button[5,7.18;2,1;done_edit;"..F(S("Done")).."]"
+				done_button = "button[5,7.18;2,1;done_edit;"..F(S("Apply")).."]"
 				if slice_list[self.selected] then
 					ypos_default = slice_list[self.selected].ypos
 					prob_default = slice_list[self.selected].prob
 				end
 			end
 
+			local field_ypos = ""
+			if self.panel_add then
+				field_ypos = "field[0.3,7.5;2.5,1;ypos;"..F(S("Y position (max. @1):", (meta.y_size - 1)))..";"..ypos_default.."]"
+			end
+
 			form = form..[[
-				field[0.3,7.5;2.5,1;ypos;]]..F(S("Y position (max. @1):", (meta.y_size - 1)))..[[;]]..ypos_default..[[]
+				]]..field_ypos..[[
 				field[2.8,7.5;2.5,1;prob;]]..F(S("Probability (0-255):"))..[[;]]..prob_default..[[]
 				field_close_on_enter[ypos;false]
 				field_close_on_enter[prob;false]
@@ -517,19 +598,22 @@ schemedit.add_form("slice", {
 		end
 
 		if not self.panel_edit then
-			form = form.."button[0,6;2.4,1;add;"..F(S("+ Add slice")).."]"
+			if self.panel_add then
+				form = form.."button[0,6;2.4,1;add;"..F(S("Cancel")).."]"
+			else
+				form = form.."button[0,6;2.4,1;add;"..F(S("Add slice")).."]"
+			end
 		end
 
 		if slices ~= "" and self.selected and not self.panel_add then
 			if not self.panel_edit then
 				form = form..[[
-					button[2.4,6;2.4,1;remove;]]..F(S("- Remove slice"))..[[]
-					button[4.8,6;2.4,1;edit;]]..F(S("+/- Edit slice"))..[[]
+					button[2.4,6;2.4,1;remove;]]..F(S("Remove slice"))..[[]
+					button[4.8,6;2.4,1;edit;]]..F(S("Edit slice"))..[[]
 				]]
 			else
 				form = form..[[
-					button[2.4,6;2.4,1;remove;]]..F(S("- Remove slice"))..[[]
-					button[4.8,6;2.4,1;edit;]]..F(S("+/- Edit slice"))..[[]
+					button[4.8,6;2.4,1;edit;]]..F(S("Back"))..[[]
 				]]
 			end
 		end
@@ -537,6 +621,10 @@ schemedit.add_form("slice", {
 		return form
 	end,
 	handle = function(self, pos, name, fields)
+		if not check_priv(name, fields.quit) then
+			return
+		end
+
 		local meta = minetest.get_meta(pos)
 		local player = minetest.get_player_by_name(name)
 
@@ -556,8 +644,10 @@ schemedit.add_form("slice", {
 		end
 
 		local ypos, prob = tonumber(fields.ypos), tonumber(fields.prob)
-		if (fields.done_add or fields.done_edit) and fields.ypos and fields.prob and
-		fields.ypos ~= "" and fields.prob ~= "" and ypos and prob and
+		if fields.done_edit then
+			ypos = 0
+		end
+		if (fields.done_add or fields.done_edit) and ypos and prob and
 				 ypos <= (meta:get_int("y_size") - 1) and prob >= 0 and prob <= 255 then
 			local slice_list = minetest.deserialize(meta:get_string("slices"))
 			local index = #slice_list + 1
@@ -565,7 +655,21 @@ schemedit.add_form("slice", {
 				index = self.selected
 			end
 
-			slice_list[index] = {ypos = ypos, prob = prob}
+			local dupe = false
+			if fields.done_add then
+				for k,v in pairs(slice_list) do
+					if v.ypos == ypos then
+						v.prob = prob
+						dupe = true
+					end
+				end
+			end
+			if fields.done_edit and slice_list[index] then
+				ypos = slice_list[index].ypos
+			end
+			if not dupe then
+				slice_list[index] = {ypos = ypos, prob = prob}
+			end
 
 			meta:set_string("slices", minetest.serialize(slice_list))
 
@@ -580,7 +684,7 @@ schemedit.add_form("slice", {
 			meta:set_string("slices", minetest.serialize(renumber(slice_list)))
 
 			-- Update formspec
-			self.selected = 1
+			self.selected = math.max(1, self.selected-1)
 			self.panel_edit = nil
 			schemedit.show_formspec(pos, player, "slice")
 		end
@@ -632,6 +736,10 @@ schemedit.add_form("probtool", {
 		return form
 	end,
 	handle = function(self, pos, name, fields)
+		if not check_priv(name, fields.quit) then
+			return
+		end
+
 		if fields.submit then
 			local prob = tonumber(fields.prob)
 			if prob then
@@ -825,8 +933,6 @@ end
 
 -- Show probability and force_place status of a particular position for player in HUD.
 -- Probability is shown as a number followed by “[F]” if the node is force-placed.
--- The distance to the node is also displayed below that. This can't be avoided and is
--- and artifact of the waypoint HUD element.
 function schemedit.display_node_prob(player, pos, prob, force_place)
 	local wpstring
 	if prob and force_place == true then
@@ -841,9 +947,10 @@ function schemedit.display_node_prob(player, pos, prob, force_place)
 			hud_elem_type = "waypoint",
 			name = wpstring,
 			precision = 0,
-			text = "m", -- For the distance artifact
+			text = "m", -- For the distance artifact [legacy]
 			number = text_color_number,
 			world_pos = pos,
+			z_index = -300,
 		})
 	end
 end
@@ -893,9 +1000,11 @@ end
 function schemedit.clear_displayed_node_probs(player)
 	local playername = player:get_player_name()
 	for nodehash, hud_id in pairs(displayed_waypoints[playername]) do
-		player:hud_remove(hud_id)
-		displayed_waypoints[playername][nodehash] = nil
-		displayed_waypoints[playername].display_active = false
+		if nodehash ~= "display_active" then
+			player:hud_remove(hud_id)
+			displayed_waypoints[playername][nodehash] = nil
+			displayed_waypoints[playername].display_active = false
+		end
 	end
 end
 
@@ -999,7 +1108,8 @@ S("With a schematic node probability tool, you can set a probability for each no
 		if meta:get_string("owner") == name or
 				minetest.check_player_privs(player, "schematic_override") == true then
 			-- Get player attribute
-			local tab = player:get_attribute("schemedit:tab")
+			local pmeta = player:get_meta()
+			local tab = pmeta:get_string("schemedit:tab")
 			if not forms[tab] or not tab then
 				tab = "main"
 			end
@@ -1030,12 +1140,17 @@ S("NODE HUD:").."\n"..
 S("To help you remember the node values, the nodes with special values are labelled in the HUD. The first line shows probability and force placement (with “[F]”). The second line is the current distance to the node. Nodes with default settings and schematic voids are not labelled.").."\n"..
 S("To disable the node HUD, unselect the tool or hit “place” while not pointing anything.").."\n\n"..
 S("UPDATING THE NODE HUD:").."\n"..
-S("The node HUD is not updated automatically and may be outdated. The node HUD only updates the HUD for nodes close to you whenever you place the tool or press the punch and sneak keys simutanously. If you sneak-punch a schematic creator, then the node HUD is updated for all nodes within the schematic creator's region, even if this region is very big."),
+S("The node HUD is not updated automatically and may be outdated. The node HUD only updates the HUD for nodes close to you whenever you place the tool or press the punch and sneak keys simultaneously. If you sneak-punch a schematic creator, then the node HUD is updated for all nodes within the schematic creator's region, even if this region is very big."),
 	wield_image = "schemedit_probtool.png",
 	inventory_image = "schemedit_probtool.png",
 	liquids_pointable = true,
 	groups = { disable_repair = 1 },
 	on_use = function(itemstack, user, pointed_thing)
+		local uname = user:get_player_name()
+		if uname and not check_priv(uname) then
+			return
+		end
+
 		local ctrl = user:get_player_control()
 		-- Simple use
 		if not ctrl.sneak then
@@ -1065,10 +1180,20 @@ S("The node HUD is not updated automatically and may be outdated. The node HUD o
 		end
 	end,
 	on_secondary_use = function(itemstack, user, pointed_thing)
+		local uname = user:get_player_name()
+		if uname and not check_priv(uname) then
+			return
+		end
+
 		schemedit.clear_displayed_node_probs(user)
 	end,
 	-- Set note probability and force_place and enable node probability display
 	on_place = function(itemstack, placer, pointed_thing)
+		local pname = placer:get_player_name()
+		if pname and not check_priv(pname) then
+			return
+		end
+
 		-- Use pointed node's on_rightclick function first, if present
 		local node = minetest.get_node(pointed_thing.under)
 		if placer and not placer:get_player_control().sneak then
@@ -1108,11 +1233,19 @@ S("The node HUD is not updated automatically and may be outdated. The node HUD o
 	end,
 })
 
+local use_texture_alpha_void
+if minetest.features.use_texture_alpha_string_modes then
+	use_texture_alpha_void = "clip"
+else
+	use_texture_alpha_void = true
+end
+
 minetest.register_node("schemedit:void", {
 	description = S("Schematic Void"),
 	_doc_items_longdesc = S("This is an utility block used in the creation of schematic files. It should be used together with a schematic creator. When saving a schematic, all nodes with a schematic void will be left unchanged when the schematic is placed again. Technically, this is equivalent to a block with the node probability set to 0."),
 	_doc_items_usagehelp = S("Just place the schematic void like any other block and use the schematic creator to save a portion of the world."),
 	tiles = { "schemedit_void.png" },
+	use_texture_alpha = use_texture_alpha_void,
 	drawtype = "nodebox",
 	is_ground_content = false,
 	paramtype = "light",
@@ -1160,13 +1293,31 @@ minetest.register_lbm({
 	end,
 })
 
+local function add_suffix(schem)
+	-- Automatically add file name suffix if omitted
+	local schem_full, schem_lua
+	if string.sub(schem, string.len(schem)-3, string.len(schem)) == ".mts" then
+		schem_full = schem
+		schem_lua = string.sub(schem, 1, -5) .. ".lua"
+	else
+		schem_full = schem .. ".mts"
+		schem_lua = schem .. ".lua"
+	end
+	return schem_full, schem_lua
+end
+
 -- [chatcommand] Place schematic
 minetest.register_chatcommand("placeschem", {
-	description = S("Place schematic at the position specified or the current player position (loaded from @1)", export_path_trunc),
-	privs = {debug = true},
-	params = S("<schematic name>[.mts] [<x> <y> <z>]"),
+	description = S("Place schematic at the position specified or the current player position (loaded from @1). “-c” will clear the area first", export_path_trunc),
+	privs = {server = true},
+	params = S("<schematic name>[.mts] [-c] [<x> <y> <z>]"),
 	func = function(name, param)
-		local schem, p = string.match(param, "^([^ ]+) *(.*)$")
+		local schem, clear, p = string.match(param, "^([^ ]+) +(%-c) *(.*)$")
+		if not schem then
+			schem, p = string.match(param, "^([^ ]+) *(.*)$")
+		end
+		clear = clear == "-c"
+
 		local pos = minetest.string_to_pos(p)
 
 		if not schem then
@@ -1177,14 +1328,7 @@ minetest.register_chatcommand("placeschem", {
 			pos = minetest.get_player_by_name(name):get_pos()
 		end
 
-		-- Automatically add file name suffix if omitted
-		local schem_full
-		if string.sub(schem, string.len(schem)-3, string.len(schem)) == ".mts" then
-			schem_full = schem
-		else
-			schem_full = schem .. ".mts"
-		end
-
+		local schem_full, schem_lua = add_suffix(schem)
 		local success = false
 		local schem_path = export_path_full .. DIR_DELIM .. schem_full
 		if minetest.read_schematic then
@@ -1193,10 +1337,25 @@ minetest.register_chatcommand("placeschem", {
 			-- files when we reload. minetest.read_schematic circumvents that.
 			local schematic = minetest.read_schematic(schem_path, {})
 			if schematic then
+				if clear then
+					-- Clear same size for X and Z because
+					-- because schematic is randomly rotated
+					local max_xz = math.max(schematic.size.x, schematic.size.z)
+					local posses = {}
+					for z=pos.z, pos.z+max_xz-1 do
+					for y=pos.y, pos.y+schematic.size.y-1 do
+					for x=pos.x, pos.x+max_xz-1 do
+						table.insert(posses, {x=x,y=y,z=z})
+					end
+					end
+					end
+					minetest.bulk_set_node(posses, {name="air"})
+				end
 				success = minetest.place_schematic(pos, schematic, "random", nil, false)
 			end
 		else
-			-- Legacy support for Minetest versions that do not have minetest.read_schematic
+			-- Legacy support for Minetest versions that do not have minetest.read_schematic.
+			-- Note: "-c" is ignored here.
 			success = minetest.place_schematic(schem_path, schematic, "random", nil, false)
 		end
 
@@ -1208,3 +1367,68 @@ minetest.register_chatcommand("placeschem", {
 	end,
 })
 
+minetest.register_chatcommand("listschems", {
+	description = S("List schematic files in world path"),
+	privs = {server = true},
+	params = "",
+	func = function(name, param)
+		local files = minetest.get_dir_list(minetest.get_worldpath()..DIR_DELIM.."schems", false)
+		if not files then
+			return false
+		end
+		local out_files = {}
+		-- Only show files with “.mts” suffix
+		for f=#files, 1, -1 do
+			if string.sub(string.lower(files[f]), -4, -1) == ".mts" then
+				table.insert(out_files, files[f])
+			end
+		end
+		table.sort(out_files)
+		local str = table.concat(out_files, ", ")
+		if str == "" then
+			return true, S("No schematic files.")
+		end
+		return true, str
+	end,
+})
+
+if can_import then
+-- [chatcommand] Convert MTS schematic file to .lua file
+minetest.register_chatcommand("mts2lua", {
+	description = S("Convert .mts schematic file to .lua file (loaded from @1)", export_path_trunc),
+	privs = {server = true},
+	params = S("<schematic name>[.mts] [comments]"),
+	func = function(name, param)
+		local schem, comments_str = string.match(param, "^([^ ]+) *(.*)$")
+
+		if not schem then
+			return false, S("No schematic file specified.")
+		end
+
+		local comments = comments_str == "comments"
+
+		-- Automatically add file name suffix if omitted
+		local schem_full, schem_lua = add_suffix(schem)
+		local schem_path = export_path_full .. DIR_DELIM .. schem_full
+		local schematic = minetest.read_schematic(schem_path, {})
+
+		if schematic then
+			local str = minetest.serialize_schematic(schematic, "lua", {lua_use_comments=comments})
+			local lua_path = export_path_full .. DIR_DELIM .. schem_lua
+			local file = io.open(lua_path, "w")
+			if file and str then
+				file:write(str)
+				file:flush()
+				file:close()
+				return true, S("Exported schematic to @1", lua_path)
+			else
+				return false, S("Failed!")
+			end
+		end
+	end,
+})
+end
+
+if MAKE_README then
+	dofile(minetest.get_modpath("schemedit")..DIR_DELIM.."make_readme.lua")
+end

locale/schemedit.de.tr

@@ -1,48 +1,57 @@
 # textdomain: schemedit
 <world path>=<Weltpfad>
-<name>=<Name>
+Insufficient privileges! You need the “@1” privilege to use this.=Unzureichende Privilegien! Sie benötigen das „@1“-Privileg, um dies benutzen zu können.
 Probability: @1=Wahrscheinlichkeit: @1
 Not Set=Nicht gesetzt
 Force placement=Platzierung erzwingen
+Import schematic=Schematic importieren
+Main=Grundeinstellungen
 Hide border=Rand verbergen
 Show border=Rand anzeigen
 Position: @1=Position: @1
 Owner: @1=Eigentümer: @1
-Size: @1=Größe: @1
 Schematic name: @1=Schematic-Name: @1
+Size: @1=Größe: @1
 Schematic name:=Schematic-Name:
 OK=OK
 Save schematic name=Schematic-Name speichern
 Export schematic=Schematic exportieren
-Import schematic=Schematic importieren
-Imported schematic from @1=Schematic von @1 importiert
-Failed to import schematic from @1=Schematic konnte nicht von @1 importiert werden
-The schematic will be exported as a .mts file and stored in@n@1=Das Schematic wird als .mts-Datei gespeichert in:@n@1
 Export/import path:@n@1=Export-/Importpfad:@n@1
+<name>=<Name>
+Air to voids=Luft zu Lücken
+Voids to air=Lücken zu Luft
+Turn all air nodes into schematic void nodes=Alle Luft-Nodes zu Schematic-Lücken umwandeln
+Turn all schematic void nodes into air nodes=Alle Schematic-Lücken zu Luft-Nodes umwandeln
+X size:=X-Größe:
+Y size:=Y-Größe:
+Z size:=Z-Größe:
 Save size=Größe speichern
 Help=Hilfe
 Exported schematic to @1=Schematic nach @1 exportiert
 Failed to export schematic to @1=Schematic konnte nicht nach @1 exportiert werden
+Imported schematic from @1=Schematic von @1 importiert
+Failed to import schematic from @1=Schematic konnte nicht von @1 importiert werden
 Y Slices=Y-Scheiben
 Y @= @1; Probability @= @2=Y @= @1; Wahrscheinlichkeit @= @2
-Done=Fertig
+Add=Hinzufügen
+Apply=Anwenden
 Y position (max. @1):=Y-Position (max. @1):
 Probability (0-255):=Wahrscheinlichkeit (0-255):
-+ Add slice=+ Neue Scheibe
-+/- Edit slice=+/- Scheibe bearbeiten
-- Remove slice=- Scheibe entfernen
+Cancel=Abbrechen
+Add slice=Neue Scheibe
+Remove slice=Scheibe entfernen
+Edit slice=Scheibe anpassen
+Back=Zurück
 Schematic Node Probability Tool=Schematic-Node-Wahrscheinlichkeitswerkzeug
 Probability (0-255)=Wahrscheinlichkeit
-Cancel=Abbrechen
-Apply=Anwenden
 Probability that the node will be placed=Wahrscheinlichkeit, dass der Node platizert wird
 If enabled, the node will replace nodes other than air and ignore=Wenn aktiviert, wird der Node alle Nodes außer Luft und Ignorieren ersetzen
 Allows you to access schemedit nodes not owned by you=Damit können Sie auf Schemedit-Nodes, die ihnen nicht gehören, zugreifen
+Importing a schematic will load a schematic from the world directory, place it in front of the schematic creator and sets probability and force-place data accordingly.=Das Importieren eines Schematics wird eine Schematicdatei aus dem Weltverzeichnis laden, sie vor dem Schematic-Macher platzieren und die Wahrscheinlichkeits- und Zwangsplatzierungsdaten entsprechend setzen.
 Schematic Creator=Schematic-Macher
 The schematic creator is used to save a region of the world into a schematic file (.mts).=Der Schematic-Macher wird benutzt, um eine Region der Welt in eine Schematic-Datei (.mts) zu speichern.
 To get started, place the block facing directly in front of any bottom left corner of the structure you want to save. This block can only be accessed by the placer or by anyone with the “schematic_override” privilege.=Um anzufangen, platzieren Sie den Block direkt vor einer beliebigen unteren linken Ecke des Gebäudes, das Sie speichern möchten. Dieser Block kann nur vom Platzierer oder von Spielern mit dem „schematic_override“-Privileg benutzt werden.
 To save a region, use the block, enter the size and a schematic name and hit “Export schematic”. The file will always be saved in the world directory. Note you can use this name in the /placeschem command to place the schematic again.=Um eine Region zu speichern, benutzen Sie den Block, geben Sie die Größe und einen Schematic-Namen ein und klicken Sie auf „Schematic exportieren“. Die Datei wird immer im Weltverzeichnis gespeichert. Beachten Sie, dass Sie diesen Namen im „/placeschem“-Befehl benutzen können, um das Schematic erneut zu platzieren.
-Importing a schematic will load a schematic from the world directory, place it in front of the schematic creator and sets probability and force-place data accordingly.=Das Importieren eines Schematics wird eine Schematicdatei aus dem Weltverzeichnis laden, sie vor dem Schematic-Macher platzieren und die Wahrscheinlichkeits- und Zwangsplatzierungsdaten entsprechend setzen.
 The other features of the schematic creator are optional and are used to allow to add randomness and fine-tuning.=Die anderen Funktionen des Schematic-Machers sind optional und werden für Zufälligkeit und Feinjustierungen benutzt.
 Y slices are used to remove entire slices based on chance. For each slice of the schematic region along the Y axis, you can specify that it occurs only with a certain chance. In the Y slice tab, you have to specify the Y slice height (0 @= bottom) and a probability from 0 to 255 (255 is for 100%). By default, all Y slices occur always.=Y-Scheiben werden benutzt, um ganze Scheiben mit einer gewissen Wahrscheinlichkeit auszulassen. Für jede Scheibe der Schematic-Region entlang der Y-Achse können Sie festlegen, dass sie nur mit einer gewissen Wahrscheinlichkeit auftritt. In der Registerkarte „Y-Scheiben“ müssen Sie die Höhe der Y-Scheibe festlegen (0 @= Boden) sowie eine Wahrscheinlichkeit zwischen 0 und 255 (255 steht für 100%). Standardmäßig treten alle Y-Scheiben immer auf.
 With a schematic node probability tool, you can set a probability for each node and enable them to overwrite all nodes when placed as schematic. This tool must be used prior to the file export.=Mit einem Schematic-Node-Wahrscheinlichkeitswerkzeug können Sie die Wahrscheinlichkeit für jeden Node setzen und sie dazu aktivieren, alle Nodes zu ersetzen, wenn sie als Schematic platziert werden. Dieses Werkzeug muss vor dem Dateiexport benutzt werden.
@@ -58,16 +67,16 @@ NODE HUD:=NODE-HUD:
 To help you remember the node values, the nodes with special values are labelled in the HUD. The first line shows probability and force placement (with “[F]”). The second line is the current distance to the node. Nodes with default settings and schematic voids are not labelled.=Um Ihnen dabei zu helfen, sich die Node-Werte zu merken, werden die Nodes mit besonderen Werten in der Benutzeroberfläche gekennzeichnet. Die erste Zeile zeigt die Wahrscheinlichkeit und die Zwangsplatzierung (mit „[F]“) an. Die zweite Zeile zeigt die momentane Entfernung zum Node an. Nodes mit den Standardeinstellungen und Schematic-Lücken werden nicht gekennzeichnet.
 To disable the node HUD, unselect the tool or hit “place” while not pointing anything.=Um die Node-HUD zu deaktivieren, wählen Sie das Werkzeug ab oder drücken Sie die Platzierentaste, während Sie auf nichts zeigen.
 UPDATING THE NODE HUD:=NODE-HUD AKTUALISIEREN:
-The node HUD is not updated automatically and may be outdated. The node HUD only updates the HUD for nodes close to you whenever you place the tool or press the punch and sneak keys simutanously. If you sneak-punch a schematic creator, then the node HUD is updated for all nodes within the schematic creator's region, even if this region is very big.=Die Node-HUD wird nicht automatisch aktualisiert und kann veraltet sein. Die Node-HUD wird nur die HUD für Nodes in Ihrer Nähe aktualisieren oder wenn Sie das Werkzeug benutzen oder gleichzeitig die Schlag- und Schleichtaste drücken. Wenn Sie auf einen Schematic-Macher schleichschlagen, wird die Node-HUD für alle Nodes innerhalb der Region des Schematic-Machers aktualisiert, selbst, wenn diese Region sehr groß ist.
+The node HUD is not updated automatically and may be outdated. The node HUD only updates the HUD for nodes close to you whenever you place the tool or press the punch and sneak keys simultaneously. If you sneak-punch a schematic creator, then the node HUD is updated for all nodes within the schematic creator's region, even if this region is very big.=Die Node-HUD wird nicht automatisch aktualisiert und kann veraltet sein. Die Node-HUD wird nur die HUD für Nodes in Ihrer Nähe aktualisieren oder wenn Sie das Werkzeug benutzen oder gleichzeitig die Schlag- und Schleichtaste drücken. Wenn Sie auf einen Schematic-Macher schleichschlagen, wird die Node-HUD für alle Nodes innerhalb der Region des Schematic-Machers aktualisiert, selbst, wenn diese Region sehr groß ist.
 Schematic Void=Schematic-Lücke
 This is an utility block used in the creation of schematic files. It should be used together with a schematic creator. When saving a schematic, all nodes with a schematic void will be left unchanged when the schematic is placed again. Technically, this is equivalent to a block with the node probability set to 0.=Dies ist ein Hilfsblock, der bei der Erstellung von Schematic-Dateien benutzt wird. Er sollte zusammen mit einem Schematic-Macher benutzt werden. Wenn ein Schematic gespeichert wird, werden alle Nodes mit einer Schematic-Lücke unverändert gelassen, wenn das Schematic erneut platziert wird. Technisch gesehen ist dieses Verhalten identisch mit einem Block, der eine Node-Wahrscheinlichkeit von 0 hat.
 Just place the schematic void like any other block and use the schematic creator to save a portion of the world.=Platzieren Sie einfach die Schematic-Lücke wie jeden anderen Block und benutzen Sie den Schematic-Macher, um einen Teil der Welt zu speichern.
-Place schematic at the position specified or the current player position (loaded from @1)=Schematic an der angegebenen Position oder der aktuellen Spielerposition speichern (geladen von @1)
-<schematic name>[.mts] [<x> <y> <z>]=<Schematic-Name>[.mts] [<x> <y> <z>]
+Place schematic at the position specified or the current player position (loaded from @1). “-c” will clear the area first=Schematic an der angegebenen Position oder der aktuellen Spielerposition platzieren (geladen von @1). Mit „-c“ wird das Gebiet zuerst geleert
+<schematic name>[.mts] [-c] [<x> <y> <z>]=<Schematic-Name>[.mts] [-c] [<x> <y> <z>]
 No schematic file specified.=Keinen Schematic-Namen angegeben.
 Schematic file could not be loaded!=Schematic-Datei konnte nicht geladen werden!
-Main=Grundeinstellungen
-X size:=X-Größe:
-Y size:=Y-Größe:
-Z size:=Z-Größe:
-Insufficient privileges! You need the “debug” privilege to do this.=Unzureichende Privilegien! Sie benötigen das „debug“-Privileg, um dies tun zu können.
+List schematic files in world path=Schematic-Dateien im Weltpfad auflisten
+No schematic files.=Keine Schematic-Dateien.
+Convert .mts schematic file to .lua file (loaded from @1)=„.mts“-Schematicdatei zu „.lua“-Datei konvertieren (geladen von @1)
+<schematic name>[.mts] [comments]=<Schematic-Name>[.mts] [comments]
+Failed!=Fehlgeschlagen!

locale/template.txt

@@ -1,41 +1,53 @@
 # textdomain: schemedit
 <world path>=
-<name>=
-Not Set=
+Insufficient privileges! You need the “@1” privilege to use this.=
 Probability: @1=
+Not Set=
 Force placement=
+Import schematic=
+Main=
 Hide border=
 Show border=
 Position: @1=
 Owner: @1=
-Size: @1=
 Schematic name: @1=
+Size: @1=
 Schematic name:=
 OK=
 Save schematic name=
 Export schematic=
-Import schematic=
-Imported schematic from @1=
-Failed to import schematic from @1=
 Export/import path:@n@1=
+<name>=
+Air to voids=
+Voids to air=
+Turn all air nodes into schematic void nodes=
+Turn all schematic void nodes into air nodes=
+X size:=
+Y size:=
+Z size:=
 Save size=
 Help=
 Exported schematic to @1=
 Failed to export schematic to @1=
+Imported schematic from @1=
+Failed to import schematic from @1=
 Y Slices=
 Y @= @1; Probability @= @2=
-Done=
+Add=
+Apply=
 Y position (max. @1):=
 Probability (0-255):=
-+ Add slice=
-+/- Edit slice=
+Cancel=
+Add slice=
+Remove slice=
+Edit slice=
+Back=
 Schematic Node Probability Tool=
 Probability (0-255)=
-Cancel=
-Apply=
 Probability that the node will be placed=
 If enabled, the node will replace nodes other than air and ignore=
 Allows you to access schemedit nodes not owned by you=
+Importing a schematic will load a schematic from the world directory, place it in front of the schematic creator and sets probability and force-place data accordingly.=
 Schematic Creator=
 The schematic creator is used to save a region of the world into a schematic file (.mts).=
 To get started, place the block facing directly in front of any bottom left corner of the structure you want to save. This block can only be accessed by the placer or by anyone with the “schematic_override” privilege.=
@@ -43,7 +55,6 @@ To save a region, use the block, enter the size and a schematic name and hit “
 The other features of the schematic creator are optional and are used to allow to add randomness and fine-tuning.=
 Y slices are used to remove entire slices based on chance. For each slice of the schematic region along the Y axis, you can specify that it occurs only with a certain chance. In the Y slice tab, you have to specify the Y slice height (0 @= bottom) and a probability from 0 to 255 (255 is for 100%). By default, all Y slices occur always.=
 With a schematic node probability tool, you can set a probability for each node and enable them to overwrite all nodes when placed as schematic. This tool must be used prior to the file export.=
-Importing a schematic will load a schematic from the world directory, place it in front of the schematic creator and sets probability and force-place data accordingly.=
 (owned by @1)=
 This is an advanced tool which only makes sense when used together with a schematic creator. It is used to finetune the way how nodes from a schematic are placed.=
 It allows you to set two things:=
@@ -56,16 +67,16 @@ NODE HUD:=
 To help you remember the node values, the nodes with special values are labelled in the HUD. The first line shows probability and force placement (with “[F]”). The second line is the current distance to the node. Nodes with default settings and schematic voids are not labelled.=
 To disable the node HUD, unselect the tool or hit “place” while not pointing anything.=
 UPDATING THE NODE HUD:=
-The node HUD is not updated automatically and may be outdated. The node HUD only updates the HUD for nodes close to you whenever you place the tool or press the punch and sneak keys simutanously. If you sneak-punch a schematic creator, then the node HUD is updated for all nodes within the schematic creator's region, even if this region is very big.=
+The node HUD is not updated automatically and may be outdated. The node HUD only updates the HUD for nodes close to you whenever you place the tool or press the punch and sneak keys simultaneously. If you sneak-punch a schematic creator, then the node HUD is updated for all nodes within the schematic creator's region, even if this region is very big.=
 Schematic Void=
 This is an utility block used in the creation of schematic files. It should be used together with a schematic creator. When saving a schematic, all nodes with a schematic void will be left unchanged when the schematic is placed again. Technically, this is equivalent to a block with the node probability set to 0.=
 Just place the schematic void like any other block and use the schematic creator to save a portion of the world.=
-Place schematic at the position specified or the current player position (loaded from @1)=
-<schematic name>[.mts] [<x> <y> <z>]=
+Place schematic at the position specified or the current player position (loaded from @1). “-c” will clear the area first=
+<schematic name>[.mts] [-c] [<x> <y> <z>]=
 No schematic file specified.=
 Schematic file could not be loaded!=
-Main=
-X size:=
-Y size:=
-Z size:=
-Insufficient privileges! You need the “debug” privilege to do this.=
+List schematic files in world path=
+No schematic files.=
+Convert .mts schematic file to .lua file (loaded from @1)=
+<schematic name>[.mts] [comments]=
+Failed!=

make_readme.lua

@@ -0,0 +1,69 @@
+-- This file adds a command for generating the schemedit usage help readme
+-- file, in Markdown format. The text is extracted from the metadata of
+-- the items. This is only used for development purposes, after the
+-- help text of any of the items was changed.
+
+-- How to use: Temporarily set MAKE_README to true in init.lua, then
+-- start the game as admin and run “/make_schemedit_readme”. Copy the
+-- generated file back to the mod directory (USAGE.md).
+
+-- Everything here is intentionally NOT translated because it is for text
+-- files only.
+
+
+-- Extract text from item definition
+local get_text = function(item, field)
+	local text = minetest.registered_items[item][field]
+
+	-- Remove translation escapes
+	text = string.gsub(text, "\x1BE", "")
+	text = string.gsub(text, "\x1B%(T@schemedit%)", "")
+
+	-- Fix Markdown syntax error
+	text = string.gsub(text, "schematic_override", "`schematic_override`")
+	return text
+end
+
+
+-- Schemedit items to generate the readme from
+local items = { "creator", "probtool", "void" }
+
+minetest.register_chatcommand("make_schemedit_readme", {
+	description = "Generate the schemedit usage help readme file",
+	privs = {server=true},
+	func = function(name, param)
+
+		local readme = "## Usage help".."\n"
+		readme = readme .. "In this section you'll learn how to use the items of this mod.".."\n"
+		readme = readme .. "Note: If you have the `doc` and `doc_items` mods installed, you can also access the same help texts in-game (possibly translated).".."\n\n"
+
+		local entries = {}
+		for i=1, #items do
+			local item = items[i]
+			local desc = get_text("schemedit:"..item, "description")
+			local longdesc = get_text("schemedit:"..item, "_doc_items_longdesc")
+			local usagehelp = get_text("schemedit:"..item, "_doc_items_usagehelp")
+
+			readme = readme .. "### "..desc.."\n"
+			readme = readme .. longdesc .."\n\n"
+			readme = readme .. "#### Usage\n"
+			readme = readme .. usagehelp
+			if i < #items then
+				readme = readme .. "\n\n\n"
+			end
+		end
+
+		local path = minetest.get_worldpath().."/schemedit_readme.md"
+		local file = io.open(path, "w")
+		if not file then
+			return false, "Failed to open file!"
+		end
+		local ok = file:write(readme)
+		file:close()
+		if ok then
+			return true, "File written to: "..path
+		else 
+			return false, "Failed to write file!"
+		end
+	end
+})

mod.conf

@@ -1,3 +1,4 @@
 name = schemedit
 optional_depends = doc
 description = Advanced tool for modders and advanced users to create and edit schematics.
+min_minetest_version = 5.0

settingtypes.txt

@@ -0,0 +1,3 @@
+# If enabled, exporting a schematic will also create a .lua file
+# in addition to the .mts file.
+schemedit_export_lua (.lua file schematic export) bool false