WorldEdit API.md

   1 WorldEdit API\r
   2 =============\r
   3 The WorldEdit API is composed of multiple modules, each of which is independent and can be used without the other. Each module is contained within a single file.\r
   4 \r
   5 If needed, individual modules such as visualization.lua can be removed without affecting the rest of the program. The only file that cannot be removed is init.lua, which is necessary for the mod to run.\r
   6 \r
   7 For more information, see the [README](README.md).\r
   8 \r
   9 General\r
  10 -------\r
  11 \r
  12 ### value = worldedit.version\r
  13 \r
  14 Contains the current version of WorldEdit in a table of the form `{major=MAJOR_INTEGER, minor=MINOR_INTEGER}`, where `MAJOR_INTEGER` is the major version (the number before the period) as an integer, and `MINOR_INTEGER` is the minor version (the number after the period) as an integer. This is intended for version checking purposes.\r
  15 \r
  16 ### value = worldedit.version_string\r
  17 \r
  18 Contains the current version of WorldEdit in the form of a string `"MAJOR_INTEGER.MINOR_INTEGER"`, where `MAJOR_INTEGER` is the major version (the number before the period) as an integer, and `MINOR_INTEGER` is the minor version (the number after the period) as an integer. This is intended for display purposes.\r
  19 \r
  20 Manipulations\r
  21 -------------\r
  22 Contained in manipulations.lua, this module allows several node operations to be applied over a region.\r
  23 \r
  24 ### count = worldedit.set(pos1, pos2, node_name)\r
  25 \r
  26 Sets a region defined by positions `pos1` and `pos2` to `node_name`. To clear a region, use "air" as the value of `node_name`.\r
  27 If `node_name` is a list of nodes, each set node is randomly picked from it.\r
  28 \r
  29 Returns the number of nodes set.\r
  30 \r
  31 ### `count = worldedit.set_param2(pos1, pos2, param2)`\r
  32 \r
  33 Sets the param2 values of all nodes in a region defined by positions `pos1` and `pos2` to `param2`.\r
  34 \r
  35 Returns the number of nodes set.\r
  36 \r
  37 ### count = worldedit.replace(pos1, pos2, searchnode, replacenode)\r
  38 \r
  39 Replaces all instances of `searchnode` with `replacenode` in a region defined by positions `pos1` and `pos2`.\r
  40 \r
  41 Returns the number of nodes replaced.\r
  42 \r
  43 ### count = worldedit.replaceinverse(pos1, pos2, searchnode, replacenode)\r
  44 \r
  45 Replaces all nodes other than `searchnode` with `replacenode` in a region defined by positions `pos1` and `pos2`.\r
  46 \r
  47 Returns the number of nodes replaced.\r
  48 \r
  49 ### count = worldedit.copy(pos1, pos2, axis, amount)\r
  50 \r
  51 Copies the region defined by positions `pos1` and `pos2` along the `axis` axis ("x" or "y" or "z") by `amount` nodes.\r
  52 \r
  53 Returns the number of nodes copied.\r
  54 \r
  55 ### count = worldedit.copy2(pos1, pos2, off)\r
  56 \r
  57 Copies the region defined by positions `pos1` and `pos2` by the offset vector `off`.\r
  58 Note that the offset needs to be big enough that there is no overlap.\r
  59 \r
  60 Returns the number of nodes copied.\r
  61 \r
  62 ### count = worldedit.move(pos1, pos2, axis, amount)\r
  63 \r
  64 Moves the region defined by positions `pos1` and `pos2` along the `axis` axis ("x" or "y" or "z") by `amount` nodes.\r
  65 \r
  66 Returns the number of nodes moved.\r
  67 \r
  68 ### count = worldedit.stack(pos1, pos2, axis, count)\r
  69 \r
  70 Duplicates the region defined by positions `pos1` and `pos2` along the `axis` axis ("x" or "y" or "z") `count` times.\r
  71 \r
  72 Returns the number of nodes stacked.\r
  73 \r
  74 ### count = worldedit.stack2(pos1, pos2, direction, amount)\r
  75 \r
  76 Duplicates the region defined by positions `pos1` and `pos2` `amount` times with offset vector `direction`.\r
  77 Note that the offset vector needs to be big enough that there is no overlap.\r
  78 \r
  79 Returns the number of nodes stacked.\r
  80 \r
  81 ### count, newpos1, newpos2 = worldedit.stretch(pos1, pos2, stretchx, stretchy, stretchz)\r
  82 \r
  83 Stretches the region defined by positions `pos1` and `pos2` by an factor of positive integers `stretchx`, `stretchy`. and `stretchz` along the X, Y, and Z axes, respectively, with `pos1` as the origin.\r
  84 \r
  85 Returns the number of nodes stretched, the new scaled position 1, and the new scaled position 2.\r
  86 \r
  87 ### count, newpos1, newpos2 = worldedit.transpose(pos1, pos2, axis1, axis2)\r
  88 \r
  89 Transposes a region defined by the positions `pos1` and `pos2` between the `axis1` and `axis2` axes ("x" or "y" or "z").\r
  90 \r
  91 Returns the number of nodes transposed, the new transposed position 1, and the new transposed position 2.\r
  92 \r
  93 ### count = worldedit.flip(pos1, pos2, axis)\r
  94 \r
  95 Flips a region defined by the positions `pos1` and `pos2` along the `axis` axis ("x" or "y" or "z").\r
  96 \r
  97 Returns the number of nodes flipped.\r
  98 \r
  99 ### count, newpos2, newpos2 = worldedit.rotate(pos1, pos2, angle)\r
 100 \r
 101 Rotates a region defined by the positions `pos1` and `pos2` by `angle` degrees clockwise around the y axis (supporting 90 degree increments only).\r
 102 \r
 103 Returns the number of nodes rotated, the new position 1, and the new position 2.\r
 104 \r
 105 ### count = worldedit.orient(pos1, pos2, angle)\r
 106 \r
 107 Rotates all oriented nodes in a region defined by the positions `pos1` and `pos2` by `angle` degrees clockwise (90 degree increment) around the Y axis.\r
 108 \r
 109 Returns the number of nodes oriented.\r
 110 \r
 111 ### count = worldedit.fixlight(pos1, pos2)\r
 112 \r
 113 Fixes the lighting in a region defined by positions `pos1` and `pos2`.\r
 114 \r
 115 Returns the number of nodes updated.\r
 116 \r
 117 ### count = worldedit.clearobjects(pos1, pos2)\r
 118 \r
 119 Clears all objects in a region defined by the positions `pos1` and `pos2`.\r
 120 \r
 121 Returns the number of objects cleared.\r
 122 \r
 123 Primitives\r
 124 ----------\r
 125 Contained in primitives.lua, this module allows the creation of several geometric primitives.\r
 126 \r
 127 ### count = worldedit.cube(pos, width, height, length, node_name, hollow)\r
 128 \r
 129 Adds a cube with its ground level centered at `pos`, the dimensions `width` x `height` x `length`, composed of `node_name`.\r
 130 \r
 131 Returns the number of nodes added.\r
 132 \r
 133 ### count = worldedit.sphere(pos, radius, node_name, hollow)\r
 134 \r
 135 Adds a sphere centered at `pos` with radius `radius`, composed of `node_name`.\r
 136 \r
 137 Returns the number of nodes added.\r
 138 \r
 139 ### count = worldedit.dome(pos, radius, node_name, hollow)\r
 140 \r
 141 Adds a dome centered at `pos` with radius `radius`, composed of `node_name`.\r
 142 \r
 143 Returns the number of nodes added.\r
 144 \r
 145 ### count = worldedit.cylinder(pos, axis, length, radius1, radius2, node_name, hollow)\r
 146 \r
 147 Adds a cylinder-like at `pos` along the `axis` axis ("x" or "y" or "z") with length `length`, base radius `radius1` and top radius `radius2`, composed of `node_name`.\r
 148 \r
 149 Returns the number of nodes added.\r
 150 \r
 151 ### count = worldedit.pyramid(pos, axis, height, node_name, hollow)\r
 152 \r
 153 Adds a pyramid centered at `pos` along the `axis` axis ("x" or "y" or "z") with height `height`, composed of `node_name`.\r
 154 \r
 155 Returns the number of nodes added.\r
 156 \r
 157 ### count = worldedit.spiral(pos, length, height, spacer, node_name)\r
 158 \r
 159 Adds a spiral centered at `pos` with side length `length`, height `height`, space between walls `spacer`, composed of `node_name`.\r
 160 \r
 161 Returns the number of nodes added.\r
 162 \r
 163 Visualization\r
 164 -------------\r
 165 Contained in visualization.lua, this module allows nodes to be visualized in different ways.\r
 166 \r
 167 ### volume = worldedit.volume(pos1, pos2)\r
 168 \r
 169 Determines the volume of the region defined by positions `pos1` and `pos2`.\r
 170 \r
 171 Returns the volume.\r
 172 \r
 173 ### count = worldedit.hide(pos1, pos2)\r
 174 \r
 175 Hides all nodes in a region defined by positions `pos1` and `pos2` by non-destructively replacing them with invisible nodes.\r
 176 \r
 177 Returns the number of nodes hidden.\r
 178 \r
 179 ### count = worldedit.suppress(pos1, pos2, node_name)\r
 180 \r
 181 Suppresses all instances of `node_name` in a region defined by positions `pos1` and `pos2` by non-destructively replacing them with invisible nodes.\r
 182 \r
 183 Returns the number of nodes suppressed.\r
 184 \r
 185 ### count = worldedit.highlight(pos1, pos2, node_name)\r
 186 \r
 187 Highlights all instances of `node_name` in a region defined by positions `pos1` and `pos2` by non-destructively hiding all other nodes.\r
 188 \r
 189 Returns the number of nodes found.\r
 190 \r
 191 ### count = worldedit.restore(pos1, pos2)\r
 192 \r
 193 Restores all nodes hidden with WorldEdit functions in a region defined by positions `pos1` and `pos2`.\r
 194 \r
 195 Returns the number of nodes restored.\r
 196 \r
 197 Serialization\r
 198 -------------\r
 199 Contained in serialization.lua, this module allows regions of nodes to be serialized and deserialized to formats suitable for use outside Minetest.\r
 200 \r
 201 ### version, extra_fields, content = worldedit.read_header(value)\r
 202 \r
 203 Reads the header from serialized data `value`.\r
 204 \r
 205 Returns the version as a positive integer (nil for unknown versions),\r
 206 extra header fields (nil if not supported), and the content after the header.\r
 207 \r
 208 ### data, count = worldedit.serialize(pos1, pos2)\r
 209 \r
 210 Converts the region defined by positions `pos1` and `pos2` into a single string.\r
 211 \r
 212 Returns the serialized data and the number of nodes serialized, or nil.\r
 213 \r
 214 ### pos1, pos2, count = worldedit.allocate(origin_pos, value)\r
 215 \r
 216 Determines the volume the nodes represented by string `value` would occupy if deserialized at `origin_pos`.\r
 217 \r
 218 Returns the two corner positions and the number of nodes, or nil.\r
 219 \r
 220 ### count = worldedit.deserialize(origin_pos, value)\r
 221 \r
 222 Loads the nodes represented by string `value` at position `origin_pos`.\r
 223 \r
 224 Returns the number of nodes deserialized or nil.\r
 225 \r
 226 Code\r
 227 ----\r
 228 Contained in code.lua, this module allows arbitrary Lua code to be used with WorldEdit.\r
 229 \r
 230 ### error = worldedit.lua(code)\r
 231 \r
 232 Executes `code` as a Lua chunk in the global namespace.\r
 233 \r
 234 Returns an error if the code fails or nil otherwise.\r
 235 \r
 236 ### error = worldedit.luatransform(pos1, pos2, code)\r
 237 \r
 238 Executes `code` as a Lua chunk in the global namespace with the variable `pos` available, for each node in a region defined by positions `pos1` and `pos2`.\r
 239 \r
 240 Returns an error if the code fails or nil otherwise.\r