Version 1.4.2

README.md

@@ -1,7 +1,7 @@
 # Schematic Editor [`schemedit`]
 
 ## Version
-1.4.1
+1.4.2
 
 ## 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
@@ -1126,7 +1129,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,
@@ -1369,3 +1372,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,7 +67,7 @@ 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.

locale/template.txt

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

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
+})