Rename //find to //highlight and worldedit.find to worldedit.highlight, add //allocate and worldedit.allocate as well as related documentation. Improve documentation by fixing a few mistakes and adding return signatures.

Chat Commands.md

@@ -182,13 +182,13 @@ Suppress all <node> in the current WorldEdit region non-destructively.
     //suppress default:glass
     //suppress mesecons:mesecon
 
-### //find <node>
+### //highlight <node>
 
-Find <node> in the current WorldEdit region by hiding everything else non-destructively.
+Highlight <node> in the current WorldEdit region by hiding everything else non-destructively.
 
-    //find dirt
+    //highlight dirt
-    //find default:glass
+    //highlight default:glass
-    //find mesecons:mesecon
+    //highlight mesecons:mesecon
 
 ### //restore
 
@@ -203,6 +203,13 @@ Save the current WorldEdit region to "(world folder)/schems/<file>.we".
     //save some random filename
     //save huge_base
 
+### //allocate <file>
+
+Set the region defined by nodes from "(world folder)/schems/<file>.we" as the current WorldEdit region.
+
+    //allocate some random filename
+    //allocate huge_base
+
 ### //load <file>
 
 Load nodes from "(world folder)/schems/<file>.we" with position 1 of the current WorldEdit region as the origin.

WorldEdit API.md

@@ -8,63 +8,55 @@ Manipulations
 -------------
 Contained in manipulations.lua, this module allows several node operations to be applied over a region.
 
-### worldedit.volume(pos1, pos2)
+### count = worldedit.set(pos1, pos2, nodename)
-
-Determines the volume of the region defined by positions `pos1` and `pos2`.
-
-Returns the volume.
-
-### worldedit.set(pos1, pos2, nodename)
 
 Sets a region defined by positions `pos1` and `pos2` to `nodename`. To clear to region, use "air" as the value of `nodename`.
 
 Returns the number of nodes set.
 
-### worldedit.replace(pos1, pos2, searchnode, replacenode)
+### count = worldedit.replace(pos1, pos2, searchnode, replacenode)
 
 Replaces all instances of `searchnode` with `replacenode` in a region defined by positions `pos1` and `pos2`.
 
 Returns the number of nodes replaced.
 
-Returns the number of nodes added.
+### count = worldedit.copy(pos1, pos2, axis, amount)
-
-### worldedit.copy(pos1, pos2, axis, amount)
 
 Copies the region defined by positions `pos1` and `pos2` along the `axis` axis ("x" or "y" or "z") by `amount` nodes.
 
 Returns the number of nodes copied.
 
-### worldedit.move(pos1, pos2, axis, amount)
+### count = worldedit.move(pos1, pos2, axis, amount)
 
 Moves the region defined by positions `pos1` and `pos2` along the `axis` axis ("x" or "y" or "z") by `amount` nodes.
 
 Returns the number of nodes moved.
 
-### worldedit.stack(pos1, pos2, axis, count)
+### count = worldedit.stack(pos1, pos2, axis, count)
 
 Duplicates the region defined by positions `pos1` and `pos2` along the `axis` axis ("x" or "y" or "z") `count` times.
 
 Returns the number of nodes stacked.
 
-### worldedit.transpose(pos1, pos2, axis1, axis2)
+### count = worldedit.transpose(pos1, pos2, axis1, axis2)
 
 Transposes a region defined by the positions `pos1` and `pos2` between the `axis1` and `axis2` axes ("x" or "y" or "z").
 
 Returns the number of nodes transposed.
 
-### worldedit.flip(pos1, pos2, axis)
+### count = worldedit.flip(pos1, pos2, axis)
 
 Flips a region defined by the positions `pos1` and `pos2` along the `axis` axis ("x" or "y" or "z").
 
 Returns the number of nodes flipped.
 
-### worldedit.rotate(pos1, pos2, angle)
+### count = worldedit.rotate(pos1, pos2, angle)
 
 Rotates a region defined by the positions `pos1` and `pos2` by `angle` degrees clockwise around the y axis (supporting 90 degree increments only).
 
 Returns the number of nodes rotated.
 
-### worldedit.dig(pos1, pos2)
+### count = worldedit.dig(pos1, pos2)
 
 Digs a region defined by positions `pos1` and `pos2`.
 
@@ -74,37 +66,37 @@ Primitives
 ----------
 Contained in primitives.lua, this module allows the creation of several geometric primitives.
 
-### worldedit.hollow_sphere = function(pos, radius, nodename)
+### count = worldedit.hollow_sphere(pos, radius, nodename)
 
 Adds a hollow sphere at `pos` with radius `radius`, composed of `nodename`.
 
 Returns the number of nodes added.
 
-### worldedit.sphere = function(pos, radius, nodename)
+### count = worldedit.sphere(pos, radius, nodename)
 
 Adds a sphere at `pos` with radius `radius`, composed of `nodename`.
 
 Returns the number of nodes added.
 
-### worldedit.hollow_cylinder(pos, axis, length, radius, nodename)
+### count = worldedit.hollow_cylinder(pos, axis, length, radius, nodename)
 
 Adds a hollow cylinder at `pos` along the `axis` axis ("x" or "y" or "z") with length `length` and radius `radius`, composed of `nodename`.
 
 Returns the number of nodes added.
 
-### worldedit.cylinder(pos, axis, length, radius, nodename)
+### count = worldedit.cylinder(pos, axis, length, radius, nodename)
 
 Adds a cylinder at `pos` along the `axis` axis ("x" or "y" or "z") with length `length` and radius `radius`, composed of `nodename`.
 
 Returns the number of nodes added.
 
-### worldedit.pyramid(pos, height, nodename)
+### count = worldedit.pyramid(pos, height, nodename)
 
 Adds a pyramid at `pos` with height `height`.
 
 Returns the number of nodes added.
 
-### worldedit.spiral(pos, width, height, spacer, nodename)
+### count = worldedit.spiral(pos, width, height, spacer, nodename)
 
 Adds a spiral at `pos` with width `width`, height `height`, space between walls `spacer`, composed of `nodename`.
 
@@ -112,25 +104,31 @@ Visualization
 -------------
 Contained in visualization.lua, this module allows nodes to be visualized in different ways.
 
-### worldedit.hide(pos1, pos2)
+### volume = worldedit.volume(pos1, pos2)
+
+Determines the volume of the region defined by positions `pos1` and `pos2`.
+
+Returns the volume.
+
+### count = worldedit.hide(pos1, pos2)
 
 Hides all nodes in a region defined by positions `pos1` and `pos2` by non-destructively replacing them with invisible nodes.
 
 Returns the number of nodes hidden.
 
-### worldedit.suppress(pos1, pos2, nodename)
+### count = worldedit.suppress(pos1, pos2, nodename)
 
 Suppresses all instances of `nodename` in a region defined by positions `pos1` and `pos2` by non-destructively replacing them with invisible nodes.
 
 Returns the number of nodes suppressed.
 
-### worldedit.find(pos1, pos2, nodename)
+### count = worldedit.highlight(pos1, pos2, nodename)
 
-Finds all instances of `nodename` in a region defined by positions `pos1` and `pos2` by non-destructively hiding all other nodes.
+Highlights all instances of `nodename` in a region defined by positions `pos1` and `pos2` by non-destructively hiding all other nodes.
 
 Returns the number of nodes found.
 
-### worldedit.restore(pos1, pos2)
+### count = worldedit.restore(pos1, pos2)
 
 Restores all nodes hidden with WorldEdit functions in a region defined by positions `pos1` and `pos2`.
 
@@ -140,19 +138,25 @@ Serialization
 -------------
 Contained in serialization.lua, this module allows regions of nodes to be serialized and deserialized to formats suitable for use outside MineTest.
 
-### worldedit.serialize(pos1, pos2)
+### data, count = worldedit.serialize(pos1, pos2)
 
 Converts the region defined by positions `pos1` and `pos2` into a single string.
 
 Returns the serialized data and the number of nodes serialized.
 
-### worldedit.deserialize(originpos, value)
+### pos1, pos2, count = worldedit.allocate(originpos, value)
+
+Determines the volume the nodes represented by string `value` would occupy if deserialized at `originpos`.
+
+Returns the two corner positions and the number of nodes.
+
+### count = worldedit.deserialize(originpos, value)
 
 Loads the nodes represented by string `value` at position `originpos`.
 
 Returns the number of nodes deserialized.
 
-### worldedit.deserialize_old(originpos, value)
+### count = worldedit.deserialize_old(originpos, value)
 
 Loads the nodes represented by string `value` at position `originpos`, using the older table-based WorldEdit format.
 
@@ -160,13 +164,13 @@ This function is deprecated, and should not be used unless there is a need to su
 
 Returns the number of nodes deserialized.
 
-### worldedit.metasave(pos1, pos2, file)
+### count = worldedit.metasave(pos1, pos2, file)
 
 Saves the nodes and meta defined by positions `pos1` and `pos2` into a file.
 
 Returns the number of nodes saved.
 
-### worldedit.metaload(pos1, file)
+### count = worldedit.metaload(pos1, file)
 
 Loads the nodes and meta from `file` to position `pos1`.
 

worldedit/serialization.lua

@@ -45,16 +45,49 @@ worldedit.serialize = function(pos1, pos2)
 	return result, count
 end
 
+--determines the volume the nodes represented by string `value` would occupy if deserialized at `originpos`, returning the two corner positions and the number of nodes
+worldedit.allocate = function(originpos, value)
+	local huge = math.huge
+	local pos1 = {x=huge, y=huge, z=huge}
+	local pos2 = {x=-huge, y=-huge, z=-huge}
+	local originx, originy, originz = originpos.x, originpos.y, originpos.z
+	local count = 0
+	for x, y, z, name, param1, param2 in value:gmatch("([+-]?%d+)%s+([+-]?%d+)%s+([+-]?%d+)%s+([^%s]+)%s+(%d+)%s+(%d+)[^\r\n]*[\r\n]*") do --match node entries
+		x, y, z = originx + tonumber(x), originy + tonumber(y), originz + tonumber(z)
+		if x < pos1.x then
+			pos1.x = x
+		end
+		if y < pos1.y then
+			pos1.y = y
+		end
+		if z < pos1.z then
+			pos1.z = z
+		end
+		if x > pos2.x then
+			pos2.x = x
+		end
+		if y > pos2.y then
+			pos2.y = y
+		end
+		if z > pos2.z then
+			pos2.z = z
+		end
+		count = count + 1
+	end
+	return pos1, pos2, count
+end
+
 --loads the nodes represented by string `value` at position `originpos`, returning the number of nodes deserialized
 worldedit.deserialize = function(originpos, value)
 	local pos = {x=0, y=0, z=0}
 	local node = {name="", param1=0, param2=0}
+	local originx, originy, originz = originpos.x, originpos.y, originpos.z
 	local count = 0
 	local env = minetest.env
 	for x, y, z, name, param1, param2 in value:gmatch("([+-]?%d+)%s+([+-]?%d+)%s+([+-]?%d+)%s+([^%s]+)%s+(%d+)%s+(%d+)[^\r\n]*[\r\n]*") do --match node entries
-		pos.x = originpos.x + tonumber(x)
+		pos.x = originx + tonumber(x)
-		pos.y = originpos.y + tonumber(y)
+		pos.y = originy + tonumber(y)
-		pos.z = originpos.z + tonumber(z)
+		pos.z = originz + tonumber(z)
 		node.name = name
 		node.param1 = param1
 		node.param2 = param2

worldedit/visualization.lua

@@ -94,8 +94,8 @@ worldedit.suppress = function(pos1, pos2, nodename)
 	return count
 end
 
---finds all instances of `nodename` in a region defined by positions `pos1` and `pos2` by non-destructively hiding all other nodes, returning the number of nodes found
+--highlights all instances of `nodename` in a region defined by positions `pos1` and `pos2` by non-destructively hiding all other nodes, returning the number of nodes found
-worldedit.find = function(pos1, pos2, nodename)
+worldedit.highlight = function(pos1, pos2, nodename)
 	local pos1, pos2 = worldedit.sort_pos(pos1, pos2)
 	local env = minetest.env
 

worldedit_commands/init.lua

@@ -567,9 +567,9 @@ minetest.register_chatcommand("/hide", {
 	end,
 })
 
-minetest.register_chatcommand("/find", {
+minetest.register_chatcommand("/highlight", {
 	params = "<node>",
-	description = "Find <node> in the current WorldEdit region by hiding everything else non-destructively",
+	description = "Highlight <node> in the current WorldEdit region by hiding everything else non-destructively",
 	privs = {worldedit=true},
 	func = function(name, param)
 		local pos1, pos2 = worldedit.pos1[name], worldedit.pos2[name]
@@ -583,8 +583,8 @@ minetest.register_chatcommand("/find", {
 			return
 		end
 
-		local count = worldedit.find(pos1, pos2, param)
+		local count = worldedit.highlight(pos1, pos2, param)
-		minetest.chat_send_player(name, count .. " nodes found")
+		minetest.chat_send_player(name, count .. " nodes highlighted")
 	end,
 })
 
@@ -638,6 +638,42 @@ minetest.register_chatcommand("/save", {
 	end,
 })
 
+minetest.register_chatcommand("/allocate", {
+	params = "<file>",
+	description = "Set the region defined by nodes from \"(world folder)/schems/<file>.we\" as the current WorldEdit region",
+	privs = {worldedit=true},
+	func = function(name, param)
+		local pos1 = worldedit.pos1[name]
+		if pos1 == nil then
+			minetest.chat_send_player(name, "No WorldEdit region selected")
+			return
+		end
+
+		if param == "" then
+			minetest.chat_send_player(name, "Invalid usage: " .. param)
+			return
+		end
+
+		local filename = minetest.get_worldpath() .. "/schems/" .. param .. ".we"
+		local file, err = io.open(filename, "rb")
+		if err ~= nil then
+			minetest.chat_send_player(name, "Could not open file \"" .. filename .. "\"")
+			return
+		end
+		local value = file:read("*a")
+		file:close()
+
+		local nodepos1, nodepos2, count = worldedit.allocate(pos1, value)
+
+		worldedit.pos1[name] = nodepos1
+		worldedit.mark_pos1(name)
+		worldedit.pos2[name] = nodepos2
+		worldedit.mark_pos2(name)
+
+		minetest.chat_send_player(name, count .. " nodes allocated")
+	end,
+})
+
 minetest.register_chatcommand("/load", {
 	params = "<file>",
 	description = "Load nodes from \"(world folder)/schems/<file>.we\" with position 1 of the current WorldEdit region as the origin",