Version 1.5.0

README.md

@@ -1,7 +1,7 @@
 # Schematic Editor [`schemedit`]
 
 ## Version
-1.4.1
+1.5.0
 
 ## Description
 This is a mod which allows you to edit and export schematics (`.mts` files).
@@ -27,10 +27,13 @@ It also adds these server commands:
 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`).
-The “server” privilege is required for most features.
+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

@@ -5,6 +5,9 @@ local schemedit = {}
 
 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
@@ -560,6 +563,11 @@ 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("Add")).."]"
@@ -920,8 +928,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
@@ -936,9 +942,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
@@ -988,9 +995,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
 
@@ -1126,7 +1135,7 @@ 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,
@@ -1294,11 +1303,16 @@ 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),
+	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] [<x> <y> <z>]"),
+	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
@@ -1318,10 +1332,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
 
@@ -1333,6 +1362,31 @@ 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", {
@@ -1369,3 +1423,7 @@ minetest.register_chatcommand("mts2lua", {
 	end,
 })
 end
+
+if MAKE_README then
+	dofile(minetest.get_modpath("schemedit")..DIR_DELIM.."make_readme.lua")
+end

locale/schemedit.de.tr

@@ -67,14 +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!
+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

@@ -67,14 +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!=
+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