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 Manipulations\r
  10 -------------\r
  11 Contained in manipulations.lua, this module allows several node operations to be applied over a region.\r
  12 \r
  13 ### count = worldedit.set(pos1, pos2, nodename)\r
  14 \r
  15 Sets a region defined by positions `pos1` and `pos2` to `nodename`. To clear to region, use "air" as the value of `nodename`.\r
  16 \r
  17 Returns the number of nodes set.\r
  18 \r
  19 ### count = worldedit.replace(pos1, pos2, searchnode, replacenode)\r
  20 \r
  21 Replaces all instances of `searchnode` with `replacenode` in a region defined by positions `pos1` and `pos2`.\r
  22 \r
  23 Returns the number of nodes replaced.\r
  24 \r
  25 ### count = worldedit.replaceinverse(pos1, pos2, searchnode, replacenode)\r
  26 \r
  27 Replaces all nodes other than `searchnode` with `replacenode` in a region defined by positions `pos1` and `pos2`.\r
  28 \r
  29 Returns the number of nodes replaced.\r
  30 \r
  31 ### count = worldedit.copy(pos1, pos2, axis, amount)\r
  32 \r
  33 Copies the region defined by positions `pos1` and `pos2` along the `axis` axis ("x" or "y" or "z") by `amount` nodes.\r
  34 \r
  35 Returns the number of nodes copied.\r
  36 \r
  37 ### count = worldedit.move(pos1, pos2, axis, amount)\r
  38 \r
  39 Moves the region defined by positions `pos1` and `pos2` along the `axis` axis ("x" or "y" or "z") by `amount` nodes.\r
  40 \r
  41 Returns the number of nodes moved.\r
  42 \r
  43 ### count = worldedit.stack(pos1, pos2, axis, count)\r
  44 \r
  45 Duplicates the region defined by positions `pos1` and `pos2` along the `axis` axis ("x" or "y" or "z") `count` times.\r
  46 \r
  47 Returns the number of nodes stacked.\r
  48 \r
  49 ### count, newpos1, newpos2 = worldedit.scale(pos1, pos2, factor)\r
  50 \r
  51 Scales the region defined by positions `pos1` and `pos2` by an factor of positive integer `factor` with `pos1` as the origin.\r
  52 \r
  53 Returns the number of nodes scaled, the new scaled position 1, and the new scaled position 2.\r
  54 \r
  55 ### count, newpos1, newpos2 = worldedit.transpose(pos1, pos2, axis1, axis2)\r
  56 \r
  57 Transposes a region defined by the positions `pos1` and `pos2` between the `axis1` and `axis2` axes ("x" or "y" or "z").\r
  58 \r
  59 Returns the number of nodes transposed, the new transposed position 1, and the new transposed position 2.\r
  60 \r
  61 ### count = worldedit.flip(pos1, pos2, axis)\r
  62 \r
  63 Flips a region defined by the positions `pos1` and `pos2` along the `axis` axis ("x" or "y" or "z").\r
  64 \r
  65 Returns the number of nodes flipped.\r
  66 \r
  67 ### count, newpos2, newpos2 = worldedit.rotate(pos1, pos2, angle)\r
  68 \r
  69 Rotates a region defined by the positions `pos1` and `pos2` by `angle` degrees clockwise around the y axis (supporting 90 degree increments only).\r
  70 \r
  71 Returns the number of nodes rotated, the new position 1, and the new position 2.\r
  72 \r
  73 ### count = worldedit.orient(pos1, pos2, angle)\r
  74 \r
  75 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
  76 \r
  77 Returns the number of nodes oriented.\r
  78 \r
  79 ### count = worldedit.fixlight(pos1, pos2)\r
  80 \r
  81 Fixes the lighting in a region defined by positions `pos1` and `pos2`.\r
  82 \r
  83 Returns the number of nodes updated.\r
  84 \r
  85 ### count = worldedit.clearobjects(pos1, pos2)\r
  86 \r
  87 Clears all objects in a region defined by the positions `pos1` and `pos2`.\r
  88 \r
  89 Returns the number of objects cleared.\r
  90 \r
  91 Primitives\r
  92 ----------\r
  93 Contained in primitives.lua, this module allows the creation of several geometric primitives.\r
  94 \r
  95 ### count = worldedit.hollow_sphere(pos, radius, nodename)\r
  96 \r
  97 Adds a hollow sphere centered at `pos` with radius `radius`, composed of `nodename`.\r
  98 \r
  99 Returns the number of nodes added.\r
 100 \r
 101 ### count = worldedit.sphere(pos, radius, nodename)\r
 102 \r
 103 Adds a sphere centered at `pos` with radius `radius`, composed of `nodename`.\r
 104 \r
 105 Returns the number of nodes added.\r
 106 \r
 107 ### count = worldedit.hollow_dome(pos, radius, nodename)\r
 108 \r
 109 Adds a hollow dome centered at `pos` with radius `radius`, composed of `nodename`.\r
 110 \r
 111 Returns the number of nodes added.\r
 112 \r
 113 ### count = worldedit.dome(pos, radius, nodename)\r
 114 \r
 115 Adds a dome centered at `pos` with radius `radius`, composed of `nodename`.\r
 116 \r
 117 Returns the number of nodes added.\r
 118 \r
 119 ### count = worldedit.hollow_cylinder(pos, axis, length, radius, nodename)\r
 120 \r
 121 Adds a hollow cylinder at `pos` along the `axis` axis ("x" or "y" or "z") with length `length` and radius `radius`, composed of `nodename`.\r
 122 \r
 123 Returns the number of nodes added.\r
 124 \r
 125 ### count = worldedit.cylinder(pos, axis, length, radius, nodename)\r
 126 \r
 127 Adds a cylinder at `pos` along the `axis` axis ("x" or "y" or "z") with length `length` and radius `radius`, composed of `nodename`.\r
 128 \r
 129 Returns the number of nodes added.\r
 130 \r
 131 ### count = worldedit.pyramid(pos, axis, height, nodename)\r
 132 \r
 133 Adds a pyramid centered at `pos` along the `axis` axis ("x" or "y" or "z") with height `height`.\r
 134 \r
 135 Returns the number of nodes added.\r
 136 \r
 137 ### count = worldedit.spiral(pos, width, height, spacer, nodename)\r
 138 \r
 139 Adds a spiral centered at `pos` with width `width`, height `height`, space between walls `spacer`, composed of `nodename`.\r
 140 \r
 141 Returns the number of nodes added.\r
 142 \r
 143 Visualization\r
 144 -------------\r
 145 Contained in visualization.lua, this module allows nodes to be visualized in different ways.\r
 146 \r
 147 ### volume = worldedit.volume(pos1, pos2)\r
 148 \r
 149 Determines the volume of the region defined by positions `pos1` and `pos2`.\r
 150 \r
 151 Returns the volume.\r
 152 \r
 153 ### count = worldedit.hide(pos1, pos2)\r
 154 \r
 155 Hides all nodes in a region defined by positions `pos1` and `pos2` by non-destructively replacing them with invisible nodes.\r
 156 \r
 157 Returns the number of nodes hidden.\r
 158 \r
 159 ### count = worldedit.suppress(pos1, pos2, nodename)\r
 160 \r
 161 Suppresses all instances of `nodename` in a region defined by positions `pos1` and `pos2` by non-destructively replacing them with invisible nodes.\r
 162 \r
 163 Returns the number of nodes suppressed.\r
 164 \r
 165 ### count = worldedit.highlight(pos1, pos2, nodename)\r
 166 \r
 167 Highlights all instances of `nodename` in a region defined by positions `pos1` and `pos2` by non-destructively hiding all other nodes.\r
 168 \r
 169 Returns the number of nodes found.\r
 170 \r
 171 ### count = worldedit.restore(pos1, pos2)\r
 172 \r
 173 Restores all nodes hidden with WorldEdit functions in a region defined by positions `pos1` and `pos2`.\r
 174 \r
 175 Returns the number of nodes restored.\r
 176 \r
 177 Serialization\r
 178 -------------\r
 179 Contained in serialization.lua, this module allows regions of nodes to be serialized and deserialized to formats suitable for use outside MineTest.\r
 180 \r
 181 ### version = worldedit.valueversion(value)\r
 182 \r
 183 Determines the version of serialized data `value`.\r
 184 \r
 185 Returns the version as a positive integer or 0 for unknown versions.\r
 186 \r
 187 ### data, count = worldedit.serialize(pos1, pos2)\r
 188 \r
 189 Converts the region defined by positions `pos1` and `pos2` into a single string.\r
 190 \r
 191 Returns the serialized data and the number of nodes serialized.\r
 192 \r
 193 ### pos1, pos2, count = worldedit.allocate(originpos, value)\r
 194 \r
 195 Determines the volume the nodes represented by string `value` would occupy if deserialized at `originpos`.\r
 196 \r
 197 Returns the two corner positions and the number of nodes.\r
 198 \r
 199 ### count = worldedit.deserialize(originpos, value)\r
 200 \r
 201 Loads the nodes represented by string `value` at position `originpos`.\r
 202 \r
 203 Returns the number of nodes deserialized.\r
 204 \r
 205 Code\r
 206 ----\r
 207 Contained in code.lua, this module allows arbitrary Lua code to be used with WorldEdit.\r
 208 \r
 209 ### error = worldedit.lua(code)\r
 210 \r
 211 Executes `code` as a Lua chunk in the global namespace.\r
 212 \r
 213 Returns an error if the code fails or nil otherwise.\r
 214 \r
 215 ### error = worldedit.luatransform(pos1, pos2, code)\r
 216 \r
 217 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
 218 \r
 219 Returns an error if the code fails or nil otherwise.