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