Merge branch 'dev' into selection-tools-refactor

API.md

@@ -0,0 +1,36 @@
+# API Reference
+This file exists to give people looking for it convenient access to the various types of documentation WorldEditAdditions (WEA) provides.
+
+
+## I'm a user of WorldEditAdditions
+If you're using WEA in-game, you probably want the chat command reference:
+
+ - [Interactive Chat Command Reference](https://worldeditadditions.mooncarrot.space/Reference/)
+ - [Source file for the above in the git repository](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md)
+
+Remember: *Documentation, not code, defines what a program does.*
+
+In other words, if the documentation ain't right, [open an issue](https://github.com/sbrl/Minetest-WorldEditAdditions/issues/new)!
+
+
+## I'm a mod developer and I want to hook into WorldEditAdditions
+That's awesome! WEA provides an extensive library of node and region manipulation functions. It also provides a significantly extensive library of utility functions - many of which Lua should provide built-in like Javascript.
+
+ - [Lua API Reference](https://worldeditadditions.mooncarrot.space/api/)
+
+The Lua API reference is built automatically from code comments using [moondoc](https://github.com/sbrl/moondoc). These code comments have been curated and written to ensure the docs are as detailed as possible. This is an ongoing process however, so if there are any issues with these docs, please get in touch.
+
+## I want to hack on WorldEditAdditions!
+Yay, we always love new people around here! Do see our Lua API docs and our contributing guide:
+
+ - [Lua API Reference](https://worldeditadditions.mooncarrot.space/api/)
+ - [Contributing Guide](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/dev/CONTRIBUTING.md)
+ - [Discord server](https://discord.gg/FzD73kuhsk)
+
+We also have a dedicated channel to development questions and chatter in our Discord server.
+
+## I want to do something else!
+Interesting! Do get in touch, as we'd love to hear about it:
+
+ - [GitHub discussion board](https://github.com/sbrl/Minetest-WorldEditAdditions/discussions)
+ - [Discord server](https://discord.gg/FzD73kuhsk)

CHANGELOG.md

@@ -11,7 +11,7 @@ Note to self: See the bottom of this file for the release template text.
 - Added [`//nodeapply`](https://worldeditadditions.mooncarrot.space/Reference/#nodeapply), a generalisation of [`//airapply`](https://worldeditadditions.mooncarrot.space/Reference/#airapply) that works with a defined list of nodes. Check out [the reference](https://worldeditadditions.mooncarrot.space/Reference/#nodeapply) - it has some cool tricks to it! (thanks for suggesting, @kliv91 from the Discord server!)
 - Added [`//ngroups`](https://worldeditadditions.mooncarrot.space/Reference/#ngroups), which lists the groups that a given node is a member of. Useful when paired with [`//nodeapply`](https://worldeditadditions.mooncarrot.space/Reference/#nodeapply)!
 - Added [`//rotate+`](https://worldeditadditions.mooncarrot.space/Reference/#rotate) to rotate regions through arbitrary series of potentially non-axis-aligned rotations. **Does not support slabs/stairs yet,** but this is on the todo list!
-- Added [`//speed`](https://worldeditadditions.mooncarrot.space/Reference/#rotate) to adjust your own movement speed
+- Added [`//speed`](https://worldeditadditions.mooncarrot.space/Reference/#speed) to adjust your own movement speed
 	- Also added an associated [movement speed adjustment tool](https://worldeditadditions.mooncarrot.space/Reference/#movement), which looks like this: ![A picture of the move speed adjustment tool. It looks like a monarch butterfly.](https://raw.githubusercontent.com/sbrl/Minetest-WorldEditAdditions/dev/worldeditadditions_farwand/textures/worldeditadditions_movement.png)
 - Added [`//set+`](https://worldeditadditions.mooncarrot.space/Reference/#set) for setting nodes and param2/light levels quickly.
 	- NOTE TO SELF: Setting light values doesn't appear to be working very well for some reason

CONTRIBUTING.md

@@ -2,13 +2,14 @@
 
 Hey there! So you like WorldEditAdditions enough to consider helping out? That's awesome! This guide should get you up and running in no time.
 
+**Lua API documentation:** <https://worldeditadditions.mooncarrot.space/api/>
 
 ## Code structure
 The WorldEditAdditions codebase is split into 3 main submods:
 
 Name							| Description
 --------------------------------|------------------------
-`worldeditadditions`			| The main mod. Core world manipulation implementations should go in here.
+`worldeditadditions`			| The main mod. Core world manipulation implementations (backed by the `*_core` mod ref core and utility functions) should go in here.
 `worldeditadditions_commands`	| Chat commands. These interact with the core manipulators in `worldeditadditions` mod.
 `worldeditadditions_farwand`	| Everything to do with the far wand tool, and now other tools like the cloud wand, multi-point wand, etc. It's different enough to everything else that it warrants it's own separate mod to avoid muddling things.
 `worldeditadditions_core`		| Core components such as the positioning system (`worldeditadditions_core.pos`), the command registration function, and utility functions go in here.

Chat-Command-Reference.md

@@ -23,6 +23,8 @@ Other useful links:
 -->
 
 ### `//metaball add <radius> | remove <index> | render <replace_node> [<threshold=1>] | list | clear | volume`
+> Added in v1.14
+
 Draws two or more [metaballs](https://en.wikipedia.org/wiki/Metaballs). Based on a subcommand system, since each metaball may have a different radius.
 
 Calling `//metaball render <replace_node>` actually makes changes to the world - all others manipulate an internal player-local list of metaballs to be drawn.
@@ -111,6 +113,8 @@ Creates a hollow ellipsoid at position 1 with the radius `(rx, ry, rz)`. Works t
 ```
 
 ### `//ellipsoid2 [<node_name:dirt> [h[ollow]]]`
+> Added in v1.13
+
 Creates an (optionally hollow) solid ellipsoid that fills the defined region.
 
 ```weacmd
@@ -145,6 +149,8 @@ Creates a hollow torus at position 1 with the radius major and minor radii. Work
 ```
 
 ### `//line [<replace_node> [<radius>]]`
+> Added in v1.10
+
 Draw a line from position 1 to position 2, optionally with a given thickness.
 
 The radius can be thought of as the thickness of the line, and is defined as the distance from a given node to an imaginary line from pos1 to pos2. Defaults to drawing with dirt and a radius of 1.
@@ -159,6 +165,8 @@ Floating-point values are fully supported for the radius.
 ```
 
 ### `//hollow [<wall_thickness>]`
+> Added in v1.11
+
 Replaces nodes inside the defined region with air, but leaving a given number of nodes near the outermost edges alone. In other words, it makes the defined region hollow, while leaving walls around the edges of a given thickness (defaulting to a wall thickness of 1).
 
 Note that all air-like nodes are also left alone.
@@ -230,6 +238,8 @@ Creates vertical walls of `<replace_node>` around the inside edges of the define
 
 
 ### `//spiral2 [<circle|square>] [<replace_node=dirt> [<interval=3> [<acceleration=0>] ] ]`
+> Added in v1.13
+
 Generates both square and circular spiral shapes with the given `<replace_node>` - defaulting to square spirals. The interval defines the gap between the spiral in nodes, and the acceleration defines by how much the interval should be increased (a value of 1 means 1 node per revolution).
 
 ```
@@ -243,6 +253,8 @@ Generates both square and circular spiral shapes with the given `<replace_node>`
 
 
 ### `//dome+ <radius> <replace_node> [<pointing_dir:x|y|z|-x|-y|-z|?|front|back|left|right|up|down> ...] [h[ollow]]`
+> Added in v1.14
+
 Creates a dome shape (i.e. a hemisphere; half a sphere) with a specified radius of the defined node, optionally specifying the direction it should be pointing in (defaults to the positive y direction).
 
 For example, `//dome+ 5 stone y` creates a dome shape pointing upwards, but `//dome+ 5 stone -y` creates a dome shape pointing downwards.
@@ -260,6 +272,8 @@ If `h` or `hollow` is specified at the end, then the resulting dome shape is mad
 
 
 ### `//spline <replace_node> <width_start> [<width_end=width_start> [<steps=3>]]`
+> Added in v1.14
+
 Draws a curved line, using all the currently defined points as control points. The starting and ending widths of the line can be controlled, and the width will be linearly interpolated.
 
 **Note:** `//spline` uses the **new** WorldEditAdditions positions! Use the [multipoint wand](#multi-point-wand) to define the control points for the resulting line.
@@ -285,6 +299,8 @@ For those interested, WorldEditAdditions uses the [chaikin curve algorithm](http
 
 
 ### `//rotate+ <axis> <degrees> [<axis> <degrees> ...] [origin|o [<pos_number>]]`
+> Added in v1.15
+
 Rotates the defined region using the specified list of rotation operations, optionally around the defined rotation origin. For example, the following:
 
 ```weacmd
@@ -339,6 +355,8 @@ Floods all connected nodes of the same type starting at _pos1_ with `<replace_no
 
 
 ### `//wbox <replace_node>`
+> Added in v1.13
+
 Sets the edges of the current selection to `<replace_node>`to create an outline of a rectangular prism. Useful for roughing in walls.
 
 In other words, creates a wireframe of a box defined by the current selection.
@@ -349,6 +367,8 @@ In other words, creates a wireframe of a box defined by the current selection.
 ```
 
 ### `//wcompass <replace_node> [<bead_node>]`
+> Added in v1.13
+
 Creates a compass around pos1 with a single node bead pointing north (+Z).
 
 ```weacmd
@@ -358,6 +378,8 @@ Creates a compass around pos1 with a single node bead pointing north (+Z).
 ```
 
 ### `//wcorner <replace_node>`
+> Added in v1.13
+
 Set the corners of the current selection to `<replace_node>`. Useful for outlining building sites and setting boundaries.
 
 ```weacmd
@@ -366,6 +388,8 @@ Set the corners of the current selection to `<replace_node>`. Useful for outlini
 ```
 
 ### `//scale <axis> <scale_factor> | <factor_x> [<factor_y> <factor_z> [<anchor_x> <anchor_y> <anchor_z>`
+> Added in v1.11
+
 Advanced version of [`//stretch` from WorldEdit](https://github.com/Uberi/Minetest-WorldEdit/blob/master/ChatCommands.md#stretch-stretchx-stretchy-stretchz) that can scale both up and down at the same time by transparently splitting it into 2 different operations. Scaling up is *always* done before scaling down.
 
 Although the syntax looks complicated, it's really quite simple. The key concept to understand is that of the scale factor. It refers to how much the defined region should be scaled up or down by, and can be specified in multiple different ways:
@@ -449,6 +473,8 @@ So in the above example, we scale in the positive x and z directions, and the ne
 
 
 ### `//copy+ <axis:x|y|z|-x|-y|-z|?|front|back|left|right|up|down> <count> [<axis> <count> [...]] [aa|airapply]`
+> Added in v1.13; param2 support added in v1.14
+
 Fully backwards-compatible with `//copy` from regular WorldEdit, but allows you to specify multiple axes at once in a single copy operation. Each successive axis in the list is specified in the form `<axis> <count>`, where:
 
  - `<axis>` is the name of the axis to move the defined region along
@@ -487,6 +513,8 @@ Finally, if the word `airapply` (or `aa` for short) is present at the end of the
 
 
 ### `//move+ <axis:x|y|z|-x|-y|-z|?|front|back|left|right|up|down> <count> [<axis> <count> [...]] [aa|airapply]`
+> Added in v1.13; param2 support added in v1.14
+
 Identical to [`//copy+`](#copy), but instead moves the defined region instead of copying it.
 
 Note that the integrated `airapply` (`aa` for short) also works as in [`//copy+`](#copy), but remember that if a given target node is not *not* air-like and the integrated `airapply` mode is enabled, the source node is still moved from the source, but destroyed because it is can't be set at the target.
@@ -505,6 +533,39 @@ Note that the integrated `airapply` (`aa` for short) also works as in [`//copy+`
 ```
 
 
+### `//set+ [param|param2|p2|light|l] <value>`
+Sets the node, param2, or light level to a fixed value in the defined region. Defaults to setting the node. If `param2`/`p2` is specified, the param2 value associated with nodes is set instead. If `light`/`l` is specified, the light level is set.
+
+For example, the follow will set the node for every block in the currently defined region:
+
+```weacmd
+//set+ stone
+//set+ glass
+```
+
+See also [`//replacemix`](#replacemix), which extends the simple set functionality implemented in this command with a powerful chance-based find-and-replace system.
+
+See also [`//nodeapply`](#nodeapply), which implements a wrapper around most WorldEditAdditions commands that filters changes made within the defined region to those affecting a defined set of nodes or nodes with the given group name.
+
+The following examples set param2 for all blocks in the defined region to a given value:
+
+```weacmd
+//set+ param2 34
+//set+ p2 2
+//set+ param2 0
+```
+
+...finally, the following examples set the light level for all blocks within the currently defined region:
+
+```weacmd
+//set+ light 3
+//set+ l 10
+//set+ light 15
+```
+
+At an indeterminate point in the future, `//set` may be aliased to this command.Your feedback is valuable on this topic as no decision has yet been reached, so please do start a conversation in our Discord server ([link here on the website homepage](https://worldeditadditions.mooncarrot.space/)) or on the [GitHub discussion board](https://github.com/sbrl/Minetest-WorldEditAdditions/discussions).
+
+
 ### `//replacemix <target_node> [<chance>] <replace_node_a> [<chance_a>] [<replace_node_b> [<chance_b>]] [<replace_node_N> [<chance_N>]] ...`
 Replaces a given node with a random mix of other nodes. Functions like `//mix`.
 
@@ -564,6 +625,8 @@ Here are all the above examples together:
 
 
 ### `//revolve <times> [<pivot_point_number=last_point>]`
+> Added in v1.14
+
 Makes a given number of copies of the currently defined region (bounded by pos1 and pos2) at a given number of equally spaced points rotated around a given pivot/origin point.
 
 For example, `//revolve 4` would make rotated copies of the currently defined region at intervals 0° (the source to copy), 90°, 180°, and 270° around the given pivot point.
@@ -587,6 +650,8 @@ For example, `//revolve 4` would make rotated copies of the currently defined re
 
 
 ### `//convolve <kernel> [<width>[,<height>]] [<sigma>]`
+> Added in v1.7
+
 Advanced version of `//smooth` from we_env, and one of the few WorldEditAdditions commands to have any aliases (`//smoothadv` and `//conv`).
 
 Extracts a heightmap from the defined region and then proceeds to [convolve](https://en.wikipedia.org/wiki/Kernel_(image_processing)) over it with the specified kernel. The kernel can be thought of as the filter that will be applied to the heightmap. Once done, the newly convolved heightmap is applied to the terrain.
@@ -636,6 +701,8 @@ Note also that columns without any air nodes in them at all are also skipped, so
 
 
 ### `//fillcaves [<node_name>]`
+> Added in v1.9
+
 Fills in all airlike nodes beneath non airlike nodes, which gives the effect of filling in caves. Defaults to filling in with stone, but this can be customised.
 
 Note that the *entire* cave you want filling must be selected, as `//fillcaves` only operates within the defined region (ref #50).
@@ -649,6 +716,8 @@ Note that the *entire* cave you want filling must be selected, as `//fillcaves`
 
 
 ### `//layers [<max_slope|min_slope..max_slope>] [<node_name_1> [<layer_count_1>]] [<node_name_2> [<layer_count_2>]] ...`
+> Added in v1.7
+
 Finds the first non-air node in each column and works downwards, replacing non-air nodes with a defined list of nodes in sequence. Like WorldEdit for Minecraft's `//naturalize` command, and also similar to [`we_env`'s `//populate`](https://github.com/sfan5/we_env). Speaking of, this command has `//naturalise` and `//naturalize` as aliases. Defaults to 1 layer of grass followed by 3 layers of dirt.
 
 Since WorldEditAdditions v1.13, a maximum and minimum slope is optionally accepted, and constrains the columns in the defined region that `//layers` will operate on. For example, specifying a value of `20` would mean that only columns with a slop less than or equal to 20° (degrees, not radians) will be operated on. A value of `45..60` would mean that only columns with a slope between 45° and 60° will be operated on.
@@ -667,6 +736,8 @@ The list of nodes has a form similar to that of a chance list you might find in
 
 
 ### `//erode [<snowballs|river> [<key_1> [<value_1>]] [<key_2> [<value_2>]] ...]`
+> Added in v1.9
+
 Runs an erosion algorithm over the defined region, optionally passing a number of key - value pairs representing parameters that are passed to the chosen algorithm. This command is **experimental**, as the author is currently on-the-fence about the effects it produces.
 
 Works best if you run `//fillcaves` first, or otherwise have no air nodes below the top non-air node in each column.
@@ -735,6 +806,8 @@ Usage examples:
 
 
 ### `//noise2d [<key_1> [<value_1>]] [<key_2> [<value_2>]] ...]`
+> Added in v1.13
+
 Applies 2D noise to the terrain in the defined region. Like `//erode`, this command accepts a number of different key-value parameters and provides a number of different underlying algorithms.
 
 In other words, this command changes the height of the terrain according to some noise function (e.g. Perlin noise):
@@ -826,6 +899,8 @@ Example invocations:
 
 
 ### `//sculptlist [preview]`
+> Added in v1.13
+
 Lists all the available sculpting brushes for use with `//sculpt`. If the `preview` keyword is specified as an argument, then the brushes are also rendered in ASCII as a preview. See [`//sculpt`](#sculpt).
 
 ```
@@ -835,6 +910,8 @@ Lists all the available sculpting brushes for use with `//sculpt`. If the `previ
 
 
 ### `//sculpt [<brush_name=default> [<brush_size=8> [<height=1>]]]`
+> Added in v1.13
+
 Applies a specified brush to the terrain at position 1 with a given height and a given size. Multiple brushes exist (see [`//sculptlist`](#sculptlist)) - and are represented as a 2D grid of values between 0 and 1, which are  then scaled to the specified height. The terrain around position 1 is first converted to a 2D heightmap (as in [`//convolve`](#convolve) before the brush "heightmap" is applied to it.
 
 Similar to [`//sphere`](https://github.com/Uberi/Minetest-WorldEdit/blob/master/ChatCommands.md#sphere-radius-node), [`//cubeapply 10 set`](https://github.com/Uberi/Minetest-WorldEdit/blob/master/ChatCommands.md#cubeapply-sizesizex-sizey-sizez-command-parameters), or [`//cylinder y 5 10 10 dirt`](https://github.com/Uberi/Minetest-WorldEdit/blob/master/ChatCommands.md#cylinder-xyz-length-radius1-radius2-node) (all from [WorldEdit](https://content.minetest.net/packages/sfan5/worldedit/)), but has a number of added advantages:
@@ -898,6 +975,8 @@ To contribute your new brush back, you can either [open a pull request](https://
 
 
 ### `//forest [<density>] <sapling_a> [<chance_a>] <sapling_b> [<chance_b>] [<sapling_N> [<chance_N>]] ...`
+> Added in v1.9
+
 Plants and grows saplings to generate a forest. A density value is optionally taken, which controls the overall density of the forest that is generated. The `bonemeal` mod is required - just like for the [`//bonemeal`](#bonemeal-strength-chance) command.
 
 The density defaults to 1, acts like a multiplier, and is not affected by the chances of all saplings listed (e.g. you can have a sapling with a chance of 1-in-50, and the overall density of the forest will be unaffected). For example, 2 results in a forest twice as dense as the default, and 0.5 a forest half as dense as the default density.
@@ -1013,6 +1092,8 @@ Returns the absolute canonical name of a node, given an alias or partial node na
 
 
 ### `//ngroups <node_name> [v[erbose]]`
+> Added in v1.15
+
 Lists the groups that a given node is a member of. For example:
 
 ```weacmd
@@ -1048,6 +1129,8 @@ Finally, the customary misc examples:
 ```
 
 ### `//ndef <node_name>`
+> Added in v1.15
+
 Short for *Node Definition*. Prints the definition table for the node with the given name. In other words. the output could look a little like this:
 
 ```
@@ -1192,6 +1275,8 @@ From the above examples you can also see the principle of inference. All directi
 Because UAS parses "natural" measurement syntax, there are many ways to express the same direction and distance. This caters to users with different ways of thinking and different play styles which will hopefully make the tools easier to use.
 
 ### `//unmark`
+> First overridden in v1.14
+
 Hides the in-game UI that indicates where the current positions and region are located.
 
 This hides both the WorldEditAdditions *and* the WorldEdit UI if displayed, but does **not** change or remove any points that are registered.
@@ -1203,6 +1288,8 @@ Should more than 2 points be defined, they are all hidden.
 ```
 
 ### `//mark`
+> WorldEditAdditions-native version first implemented in v1.14
+
 Shows the in-game UI that indicates where the current positions and region are located once more.
 
 Should more than 2 points be defined, they are all shown once more.
@@ -1215,28 +1302,34 @@ Often used after calling [`//unmark`](#unmark)
 
 
 ### `//pos1`
+> WorldEditAdditions-native version first implemented in v1.14
+
+**Aliases:** `//1`
+
 Sets pos1 to the location of the calling player.
 
 This is, as with all other WorldEditAdditions commands, seamlessly synchronised with WorldEdit, allowing you to use any combination of WorldEditAdditions and WorldEdit commands and tools without them desynchronising from one another.
 
-**Aliases:** `//1`
-
 ```weacmd
 //pos2
 ```
 
 ### `//pos2`
+> WorldEditAdditions-native version first implemented in v1.14
+
+**Aliases:** `//2`
+
 Sets pos1 to the location of the calling player.
 
 This is, as with all other WorldEditAdditions commands, seamlessly synchronised with WorldEdit, allowing you to use any combination of WorldEditAdditions and WorldEdit commands and tools without them desynchronising from one another.
 
-**Aliases:** `//2`
-
 ```weacmd
 //pos2
 ```
 
 ### `//pos <index>`
+> Added in v1.14
+
 Sets position with the given index `<index>` to the location of the calling player.
 
 Should the index be less than or equal to 2, then as with all other WorldEditAdditions commands, seamlessly synchronised with WorldEdit, allowing you to use any combination of WorldEditAdditions and WorldEdit commands and tools without them desynchronising from one another.
@@ -1253,6 +1346,8 @@ If no index is specified, an error is returned and nothing is done.
 ```
 
 ### `//reset`
+> WorldEditAdditions-native version first implemented in v1.14
+
 Clears all positions defined and the defined region.
 
 This also synchronises with WorldEdit, as all other WorldEditAdditions commands do.
@@ -1263,8 +1358,13 @@ This also synchronises with WorldEdit, as all other WorldEditAdditions commands
 
 
 ### `//scol [<axis1> ] <length>`
+> Added in v1.12
+
 > [!WARNING]
-> **REMOVED** in v1.15 in favour of [`//srel`](#srel)
+> This command has been deprecated in v1.15 in favour of [`//srel`](#srel).
+> 
+> Users of earlier versions of WorldEditAdditions should update if possible, or continue to use this command if not.
+
 Short for _select column_. Sets the pos2 at a set distance along 1 axis from pos1. If the axis isn't specified, defaults the direction you are facing. Implementation thanks to @VorTechnix.
 
 ```weacmd
@@ -1273,8 +1373,13 @@ Short for _select column_. Sets the pos2 at a set distance along 1 axis from pos
 ```
 
 ### `//srect [<axis1> [<axis2>]] <length>`
+> Added in v1.12; deprecated in favour of [`//srel`](#srel) in v1.15
+
 > [!WARNING]
-> **REMOVED** in v1.15 in favour of [`//srel`](#srel)
+> This command has been deprecated in v1.15 in favour of [`//srel`](#srel).
+> 
+> Users of earlier versions of WorldEditAdditions should update if possible, or continue to use this command if not.
+
 Short for _select rectangle_. Sets the pos2 at a set distance along 2 axes from pos1. If the axes aren't specified, defaults to positive y and the direction you are facing. Implementation thanks to @VorTechnix.
 
 ```weacmd
@@ -1285,8 +1390,13 @@ Short for _select rectangle_. Sets the pos2 at a set distance along 2 axes from
 
 
 ### `//scube [<axis1> [<axis2> [<axis3>]]] <length>`
+> Added in v1.12
+
 > [!WARNING]
-> **REMOVED** in v1.15 in favour of [`//srel`](#srel)
+> This command has been deprecated in v1.15 in favour of [`//srel`](#srel).
+> 
+> Users of earlier versions of WorldEditAdditions should update if possible, or continue to use this command if not.
+
 Short for _select cube_. Sets the pos2 at a set distance along 3 axes from pos1. If the axes aren't specified, defaults to positive y, the direction you are facing and the axis to the left of facing. Implementation thanks to @VorTechnix.
 
 ```weacmd
@@ -1298,6 +1408,8 @@ Short for _select cube_. Sets the pos2 at a set distance along 3 axes from pos1.
 
 
 ### `//scloud <0-6|stop|reset>`
+> Added in v1.12
+
 Short for _select point cloud_. Sets pos1 and pos2 to include the nodes you punch. Numbers 1-6 designate how many nodes you want to punch before the operation ends. 0 or stop terminate the operation so that any further nodes you punch won't be added to selection. Reset terminates operation if one is running and resets the selection area.
 
 ```weacmd
@@ -1325,6 +1437,8 @@ Short for _select relative_. Sets the pos2 at set distances along 3 axes relativ
 ```
 
 ### `//sgrow <unified axis syntax>`
+> Added in v1.15
+
 Short for _selection grow_. Grows the current selection along specified axes/directions.
 Aliases: `//extend`, `//outset`.
 
@@ -1336,6 +1450,8 @@ Aliases: `//extend`, `//outset`.
 ```
 
 ### `//sshrink <unified axis syntax>`
+> Added in v1.15
+
 Short for _selection shrink_. Shrinks the current selection along specified axes/directions.
 Aliases: `//contract`, `//inset`.
 
@@ -1347,6 +1463,8 @@ Aliases: `//contract`, `//inset`.
 ```
 
 ### `//sshift <unified axis syntax>`
+> Added in v1.13
+
 Short for _selection shift_. Shifts the WorldEdit region along 3 axes. The axis arguments accept `x, y, z` as well as `up, down, left, right, front, back`. Left, right, front and back are relative to player facing direction. Negative (`-`) can be applied to the axis, the length or both. Implementation thanks to @VorTechnix.
 
 ```weacmd
@@ -1357,6 +1475,8 @@ Short for _selection shift_. Shifts the WorldEdit region along 3 axes. The axis
 ```
 
 ### `//smake <operation:odd|even|equal> <mode:grow|shrink|average> [<target=xz> [<base>]]`
+> Added in v1.12
+
 Short for _selection make_. Modifies existing selection by moving pos2. Allows you to make the selection an odd or even length on one or more axes or set two or more axes equal to each other or the longest, shortest or average of them. Implementation thanks to @VorTechnix.
 
 Usage examples:
@@ -1406,8 +1526,13 @@ Name		| Description
 `<base>`: If `<operation>` == equal			| Overrides `<mode>` and sets all `<target>` axes equal to itself
 
 ### `//sfactor <mode:grow|shrink|average> <factor> [<target=xz>]`
+> Added in v1.13
+
 > [!WARNING]
-> **REMOVED** in v1.15 in favour of [`//sgrow`](#sgrow) and [`//sshrink`](#sshrink)
+> This command has been deprecated in v1.15 in favour of [`//srel`](#srel).
+> 
+> Users of earlier versions of WorldEditAdditions should update if possible, or continue to use this command if not.
+
 Short for _selection factor_; alias: `//sfac`. Built specifically for use with `//maze`, this command sets targeted axes equal to the nearest multiple of `<factor>` based on the `<mode>`.
 
 Usage examples:
@@ -1426,6 +1551,8 @@ Value	|	Description
 `average`/`avg` | Takes the average of all axes specified in `<target>` and then for each specified axis grows or shrinks it, depending on whether it is less than or greater than the average, to the nearest multiple of `<factor>`
 
 ### `//sstack`
+> Added in v1.12
+
 Displays the contents of your per-user selection stack. This stack can be pushed to and popped from rather like a stack of plates. See also `//spush` (for pushing to the selection stack) and `//spop` (for popping from the selection stack).
 
 ```weacmd
@@ -1433,6 +1560,8 @@ Displays the contents of your per-user selection stack. This stack can be pushed
 ```
 
 ### `//spush`
+> Added in v1.12
+
 Pushes the currently defined region onto your per-user selection stack. Does not otherwise alter the defined region.
 
 If the stack is full (currently the limit is set to 100 regions in the stack), then it will complain at you but otherwise will have no effect.
@@ -1444,6 +1573,8 @@ Note that pos2 does _not_ need to be defined in order to use this. if it isn't d
 ```
 
 ### `//spop`
+> Added in v1.12
+
 Pops a selection off your per-user selection stack and applies it to the currently defined region. If pos2 from the item popped from the stack is nil, then pos2 is explicitly unset. If the stack is empty, this has no effect.
 
 ```weacmd
@@ -1471,6 +1602,8 @@ Alias for [`//count`](#count).
 
 
 ### `//mface`
+> Added in v1.13
+
 Returns the horizontal (X/Z) axis or axes the player is looking along.
 Aliases: `//mfacing`.
 
@@ -1480,6 +1613,8 @@ Aliases: `//mfacing`.
 
 
 ### `//midpos`
+> Added in v1.13
+
 Returns the coordinates of the centre of the current selection.
 
 ```
@@ -1488,6 +1623,8 @@ Returns the coordinates of the centre of the current selection.
 
 
 ### `//msize`
+> Added in v1.13
+
 Returns the lengths of the current selection on the X, Y and Z axes.
 
 ```
@@ -1559,6 +1696,8 @@ In addition, this also allows for including a double forward slash in the argume
 
 
 ### `//many <times> <command>`
+> Added in v1.9
+
 Executes a single chat command many times in a row. Uses `minetest.after()` to yield to the main server thread to allow other things to happen at the same time, so technically you could have multiple `//many` calls going at once (but multithreading support is out of reach, so only a single one will be executing at the same time).
 
 Note that this isn't necessarily limited to executing WorldEdit / WorldEditAdditions commands. Combine with `//multi` (see above) execute multiple commands at once for even more power and flexibility!
@@ -1570,6 +1709,8 @@ Note that this isn't necessarily limited to executing WorldEdit / WorldEditAddit
 
 
 ### `//ellipsoidapply <command_name> <args>`
+> Added in v1.9
+
 Executes the given command, and then clips the result to the largest ellipsoid that will fit inside the defined region. The specified command must obviously take 2 positions - so for example `//set`, `//replacemix`, and `//maze3d` will work, but `//sphere`, `//torus`, and `//floodfill` won't.
 
 For advanced users, `//multi` is also supported - but make sure your modifications stay within the defined region - otherwise they will not be affected by the ellipsoidal clipping operation.
@@ -1584,6 +1725,8 @@ For advanced users, `//multi` is also supported - but make sure your modificatio
 
 
 ### `//airapply <command_name> <args>`
+> Added in v1.13
+
 Like [`//ellipsoidapply`](#ellipsoidapply), but instead only keeps changes that replace airlike nodes, and discards any other changes made.
 
 As with `//ellipsoidapply` for advanced users `//multi` is also supported - but make sure your modifications stay within the defined region - otherwise they be kept regardless, as `//airapply` only applies the masking to the nodes in the defined region.
@@ -1595,6 +1738,8 @@ As with `//ellipsoidapply` for advanced users `//multi` is also supported - but
 
 
 ### `//nodeapply <node_a> [<node_b>] [... <node_N>] -- <command_name> <args>`
+> Added in v1.15
+
 **Aliases:** `//napply`
 
 It's got `apply` in the name, so as you might imagine it works the same as [`//ellipsoidapply`](#ellipsoidapply), [`//airapply`](#airapply), [`//noiseapply2d`](#noiseapply2d), etc. Only changes made by the given command that replace nodes on the list given will be replaced. For example:
@@ -1637,6 +1782,8 @@ More misc examples to end this command description, as is customary:
 
 
 ### `//noiseapply2d <threshold> <scale> <command_name> <args>`
+> Added in v1.13
+
 Like [`//ellipsoidapply`](#ellipsoidapply), but instead only keeps changes where a noise function (defaults to `perlinmt`, see [`//noise2d`](#noise2d)) returns a value greater than a given threshold value.
 
 Also takes a scale value that controls the scale of the noise - -higher values result in smaller "blobs". If you're operating on small areas, then a value of at least 10 is advised as "blobs" are by default on the scale of ~50 nodes.
@@ -1651,6 +1798,8 @@ Any suggestions on  how to provide more customisability without making this comm
 ```
 
 ### `//for <value1> <value2> <value3>... do //<command> <arg> %% <arg>`
+> Added in v1.13
+
 For a given list of values, executes the specified command for each value, replacing `%%` with each value. Implementation thanks to @VorTechnix.
 
 To better illustrate what happens, consider the following command:
@@ -1699,6 +1848,8 @@ This command is intended for development and modding. You will not normally need
 
 
 ### `//speed [<value=1>]`
+> Added in v1.15
+
 Adjusts your player movement speed to the specified value. In other words:
 
 ```weacmd
@@ -1755,6 +1906,8 @@ Note this only affects **you**, and **not any other player**.
 See also [`//speed`](#speed).
 
 ### Far Wand
+> Added in v1.7
+
 The far wand (`worldeditadditions:farwand`) is a variant on the traditional WorldEdit wand (`worldedit:wand`). It looks like this: ![A picture of the far wand](https://raw.githubusercontent.com/sbrl/Minetest-WorldEditAdditions/main/worldeditadditions_farwand/textures/worldeditadditions_farwand.png)
 
 It functions very similarly to the regular WorldEdit wand, except that it has a _much_ longer range - which can be very useful for working on large-scale terrain for example. It also comes with an associated command to control it.
@@ -1786,6 +1939,8 @@ You can change the maximum range with the `maxdist` subcommand:
 Note that the number there isn't in blocks (because hard maths). It is however proportional to the distance the wand will raycast looks for nodes, so a higher value will result in it raycasting further.
 
 ### Cloud Wand
+> Added in v1.11
+
 The cloud wand (`worldeditadditions:cloudwand`) is a another variant the above _Far Wand_. It looks like this: ![A picture of the far wand](https://raw.githubusercontent.com/sbrl/Minetest-WorldEditAdditions/main/worldeditadditions_farwand/textures/worldeditadditions_cloudwand.png)
 
 Unlike the other 2 wands, this wand functions in an additive manner. Left-click on a node to expand the currently defined region (creating a new one if one isn't defined already) to include that node. Right click to clear the currently defined region.
@@ -1796,6 +1951,8 @@ Note that punching out the positions **does not unset them**. Use `//reset` to r
 
 
 ### MultiPoint Wand
+> Added in v1.14
+
 The third type of wand provided by WorldEditAdditions is completely different, in that it allows you to select up to **999 points** at once! It looks like this: ![A picture of the multi-point wand](https://raw.githubusercontent.com/sbrl/Minetest-WorldEditAdditions/main/worldeditadditions_farwand/textures/worldeditadditions_multiwand.png)
 
 It is important to note that (at present) the points selected by this wand **are not compatible with normal points**. This will change in the future, but requires a lot of work to implement.

README.md

@@ -16,7 +16,8 @@ _(Do you have a cool build that you used WorldEditAdditions to build? [Get in to
  - [Quick Command Reference](#quick-command-reference) (including links to detailed explanations)
  - [Using the Far Wand](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md#far-wand)
  - [Using the Cloud Wand](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md#cloud-wand)
- - [Detailed Chat Command Explanations](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md)
+ - [Interactive Chat Command Reference](https://worldeditadditions.mooncarrot.space/Reference/) ([git](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md))
+ - [Lua API Reference](https://worldeditadditions.mooncarrot.space/api/)
  - [Chat Command Cookbook](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Cookbook.md)
  - [Troubleshooting](#troubleshooting)
  - [Contributing](#contributing)
@@ -27,6 +28,9 @@ _(Do you have a cool build that you used WorldEditAdditions to build? [Get in to
 ## Quick Command Reference
 The detailed explanations have moved! Check them out [here](https://worldeditadditions.mooncarrot.space/Reference/) (or edit at [Chat-Command-Reference.md](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md)), or click the links below.
 
+- **Full chat command reference:** <https://worldeditadditions.mooncarrot.space/Reference/>
+- **Lua API documentation** (for mod developers and hackers)**:** <https://worldeditadditions.mooncarrot.space/api/>
+
 ### Geometry
  - [`//spline <replace_node> <width_start> [<width_end=width_start> [<steps=3>]]`](https://worldeditadditions.mooncarrot.space/Reference/#spline)
  - [`//dome+ <radius> <replace_node> [<pointing_dir:x|y|z|-x|-y|-z|?|front|back|left|right|up|down> ...] [h[ollow]]`](https://worldeditadditions.mooncarrot.space/Reference/#dome)
@@ -47,9 +51,11 @@ The detailed explanations have moved! Check them out [here](https://worldeditadd
  - [`//wcorner <replace_node>`](https://worldeditadditions.mooncarrot.space/Reference/#wcorner)
 
 ### Misc
+ - [`//rotate+ <axis> <degrees> [<axis> <degrees> ...] [origin|o [<pos_number>]]`](https://worldeditadditions.mooncarrot.space/Reference/#rotate) _(new in v1.15)_
  - [`//revolve <times> [<pivot_point_number=last_point>]`](https://worldeditadditions.mooncarrot.space/Reference/#revolve)
  - [`//copy+ <axis:x|y|z|-x|-y|-z|?|front|back|left|right|up|down> <count> [<axis> <count> [...]]`](https://worldeditadditions.mooncarrot.space/Reference/#copy)
  - [`//move+ <axis:x|y|z|-x|-y|-z|?|front|back|left|right|up|down> <count> [<axis> <count> [...]]`](https://worldeditadditions.mooncarrot.space/Reference/#move)
+ - [`//set+ [param|param2|p2|light|l] <value>`](https://worldeditadditions.mooncarrot.space/Reference/#set) _(new in v1.15)_
  - [`//replacemix <target_node> [<chance>] <replace_node_a> [<chance_a>] [<replace_node_b> [<chance_b>]] [<replace_node_N> [<chance_N>]] ....`](https://worldeditadditions.mooncarrot.space/Reference/#replacemix)
  - [`//floodfill [<replace_node> [<radius>]]`](https://worldeditadditions.mooncarrot.space/Reference/#floodfill)
  - [`//scale <axis> <scale_factor> | <factor_x> [<factor_y> <factor_z> [<anchor_x> <anchor_y> <anchor_z>]]`](https://worldeditadditions.mooncarrot.space/Reference/#scale) **experimental**
@@ -72,7 +78,8 @@ The detailed explanations have moved! Check them out [here](https://worldeditadd
 ### Statistics
  - [`//count`](https://worldeditadditions.mooncarrot.space/Reference/#count)
  - [`//basename <name>`](https://worldeditadditions.mooncarrot.space/Reference/#basename)
- - [`//ngroups <node_name> [v[erbose]]`](https://worldeditadditions.mooncarrot.space/Reference/#ngroups)
+ - [`//ngroups <node_name> [v[erbose]]`](https://worldeditadditions.mooncarrot.space/Reference/#ngroups) _(new in v1.15)_
+ - [`//ndef <node_name>`](https://worldeditadditions.mooncarrot.space/Reference/#ndef) _(new in v1.15)_
  - [`//uasparse <unified axis syntax>`](https://worldeditadditions.mooncarrot.space/Reference/#uasparse) _(new in v1.15)_
 
 ### Selection
@@ -116,6 +123,7 @@ The detailed explanations have moved! Check them out [here](https://worldeditadd
 ### Extras
  - [`//y`](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md#y)
  - [`//n`](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md#n)
+ - [`//speed [<value=1>]`](https://worldeditadditions.mooncarrot.space/Reference/#speed) _(new in v1.15)_
 
 ### Tools
  - [WorldEditAdditions Far Wand](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md#far-wand)
@@ -194,12 +202,20 @@ The new positioning system now rectifies this issue with the region marker walls
 
 If this is not showing for you, please update WorldEditAdditions and try again.
 
+### Where's the documentation?
+As linked above:
+
+ - [Interactive Chat Command Reference](https://worldeditadditions.mooncarrot.space/Reference/) ([git](https://github.com/sbrl/Minetest-WorldEditAdditions/blob/main/Chat-Command-Reference.md))
+ - [Lua API Reference](https://worldeditadditions.mooncarrot.space/api/) (built with [moondoc](https://github.com/sbrl/moondoc))
+
 
 ## Contributing
 Contributions are welcome! Please state in your pull request(s) that you release your contribution under the _Mozilla Public License 2.0_.
 
 Please also make sure that the logic for every new command has it's own file. For example, the logic for `//floodfill` goes in `worldeditadditions/floodfill.lua`, the logic for `//overlay` goes in `worldeditadditions/overlay.lua`, etc. More contributing help can be found in [the contributing guide](CONTRIBUTING.md).
 
+**Lua API Documentation:** <https://worldeditadditions.mooncarrot.space/api/>
+
 ### Inspiration
 Want to contribute, but finding it tough to find inspiration of what to implement? Here are some great places to look:
 
@@ -208,7 +224,7 @@ Want to contribute, but finding it tough to find inspiration of what to implemen
 	- WorldEdit for Minecraft
 	- VoxelSniper(-Reimagined) for Minecraft
 	- WorldPainter for Minecraft
-	- Axiom
+	- Axiom for Minecraft
 - **Do some building:** When you put WorldEditAdditions to use in building projects of your own, things will absolutely stand out to you what you want in the creative building process that WorldEditAdditions doesn't yet have.
 - **Watch others build stuff:** Doesn't even have to be Minetest! There are lots of talented Minecraft builders with videos and series on e.g. YouTube. From their creative building processes, many ideas can be derived.
 

worldeditadditions/lib/copy.lua

@@ -4,6 +4,7 @@ local Vector3 = wea_c.Vector3
 ---
 -- @module worldeditadditions
 
+-- TODO add `minetest.find_nodes_with_meta(pos1, pos2)` support ref https://github.com/minetest/minetest/blob/5.9.1/doc/lua_api.md?plain=1#L6112 for locked chests, inventories etc. Perhaps for copy add a flag to allow for disabling such support?
 
 --  ██████  ██████  ██████  ██    ██
 -- ██      ██    ██ ██   ██  ██  ██

worldeditadditions/lib/move.lua

@@ -5,6 +5,8 @@ local Vector3 = wea_c.Vector3
 ---
 -- @module worldeditadditions
 
+-- TODO add `minetest.find_nodes_with_meta(pos1, pos2)` support ref https://github.com/minetest/minetest/blob/5.9.1/doc/lua_api.md?plain=1#L6112 for locked chests, inventories etc. Perhaps for copy add a flag to allow for disabling such support?
+
 -- ███    ███  ██████  ██    ██ ███████
 -- ████  ████ ██    ██ ██    ██ ██
 -- ██ ████ ██ ██    ██ ██    ██ █████

worldeditadditions_core/core/pos.lua

@@ -218,9 +218,20 @@ local function set2(player_name, pos)
 	return set(player_name, 2, pos)
 end
 
+--- Sets multiple positions for the given player.
+-- @param	player_name		string				The name of the player to set the positions for.
+-- @param	pos_list		table<int, Vector3>	A table of Vector3 positions to set, where the key is the index and the value is the position.
+local function set_multi(player_name, pos_list)
+	for i,pos_new in pairs(pos_list) do
+		set(player_name, i, pos_new)
+	end
+end
 
 --- Sets the all the positions for the given player.
 -- You probably want push_pos, not this function.
+-- 
+-- WARNING: Will DELETE all points registered for the given player!
+-- 
 -- @param	player_name		string	The name of the player to set the positions for.
 -- @param	pos_list		Vector3	The table of positions to set.
 -- @returns	bool			Whether the operation was successful or not (players aren't allowed more than positions_count_limit number of positions at a time).
@@ -319,6 +330,7 @@ anchor = wea_c.EventEmitter.new({
 	set = set,
 	set1 = set1,
 	set2 = set2,
+	set_multi = set_multi,
 	set_all = set_all,
 	unmark = unmark,
 	mark = mark,

worldeditadditions_core/core/register_command.lua

@@ -5,7 +5,7 @@
 -- ██   ██ ███████  ██████  ██ ███████    ██    ███████ ██   ██
 
 --- WorldEditAdditions chat command registration
--- @namespace worldeditadditions_core
+-- @module worldeditadditions_core
 local wea_c = worldeditadditions_core
 local run_command = dofile(wea_c.modpath.."/core/run_command.lua")
 
@@ -13,7 +13,19 @@ local function log_error(cmdname, error_message)
 	minetest.log("error", "register_command("..cmdname..") error: "..error_message)
 end
 
---- TODO: Document this function
+
+--- Registers a new WorldEditAdditions chat command.
+-- @param	cmdname		string	The name of the command to register.
+-- @param	options		table	A table of options for the command:
+-- - `params` (string) A textual description of the parameters the command takes.
+-- - `description` (string) A description of the command.
+-- - `privs` (`{someprivilege=true, ....}`) The privileges required to use the command.
+-- - `require_pos` (number) The number of positions required for the command.
+-- - `parse` (function) A function that parses the raw param_text into proper input arguments to be passed to `nodes_needed` and `func`.
+-- - `nodes_needed` (function) A function that returns the number of nodes the command could potential change given the parsed input arguments.
+-- - `func` (function) The function to execute when the command is run.
+-- - `override=false` (boolean) Whether to override an existing command with the same name.
+-- @return	boolean	True if the command was registered successfully, false otherwise.
 local function register_command(cmdname, options)
 	
 	---

worldeditadditions_core/core/run_command.lua

@@ -8,15 +8,77 @@ local human_size = wea_c.format.human_size
 
 -- TODO: Reimplement worldedit.player_notify(player_name, msg_text)
 
-local function run_command_stage2(player_name, func, parse_result)
+--- Actually runs the command in question.
+-- Unfortunately needed to keep the codebase clena because Lua sucks.
+-- @internal
+-- @param	player_name	string		The name of the player executing the function. 
+-- @param	func		function	The function to execute.
+-- @param	parse_result	table	The output of the parsing function that was presumably called earlier. Will be unpacked and passed to `func` as arguments.
+-- @param	tbl_event	table		Internal event table used when calling `worldeditadditions_core.emit(event_name, tbl_event)`.
+-- @returns	nil
+local function run_command_stage2(player_name, func, parse_result, tbl_event)
+	wea_c:emit("pre-execute", tbl_event)
 	local success, result_message = func(player_name, wea_c.table.unpack(parse_result))
 	if result_message then
-		-- TODO: If we were unsuccessfull, then colour the message red
+		-- TODO: If we were unsuccessful, then colour the message red
 		worldedit.player_notify(player_name, result_message)
 	end
+	
+	tbl_event.success = success
+	tbl_event.result = result_message
+	wea_c:emit("post-execute", tbl_event)
 end
 
+--- Command execution pipeline: before `paramtext` parsing but after validation.
+-- 
+-- See `worldeditadditions_core.run_command`
+-- @event	pre-parse
+-- @format	{ player_name: string, cmddef: table, paramtext: string }
+
+--- Command execution pipeline: directly after `paramtext` parsing
+--
+-- See `worldeditadditions_core.run_command`
+-- @event	post-parse
+-- @format	{ player_name: string, cmddef: table, paramtext: string, paramargs: table }
+
+--- Command execution pipeline: after the `nodesneeded` function is called (if provided).
+--
+-- See `worldeditadditions_core.run_command`
+-- @event	post-nodesneeded
+-- @format	{ player_name: string, cmddef: table, paramtext: string, paramargs: table, potential_changes: number }
+
+--- Command execution pipeline: directly before the command is invoked.
+--
+-- See `worldeditadditions_core.run_command`
+-- @event	pre-execute
+-- @format	{ player_name: string, cmddef: table, paramtext: string, paramargs: table, potential_changes: number }
+
+--- Command execution pipeline: after the command is executed.
+--
+-- See `worldeditadditions_core.run_command`
+-- @event	post-execute
+-- @format	{ player_name: string, cmddef: table, paramtext: string, paramargs: table, potential_changes: number, success: boolean, result: any }
+
+
 --- Runs a command with the given name and options for the given player.
+-- Emits several events in the process, in the following order:
+-- 1. **`pre-parse`:** Before `paramtext` parsing but after validation.
+-- 2. **`post-parse`:** Directly after `paramtext` parsing
+-- 3. **`post-nodesneeded`:** If a `nodesneeded` function is provided, this executes after the nodesneeded function is called.
+-- 4. **`pre-execute`:** Directly before the command is invoked.
+-- 5. **`post-execute`:** After the command is executed.
+-- 
+-- Items #4 and #5 here are actually emitted by the private internal function `run_command_stage2`.
+-- 
+-- The event object passed has the following properties:
+-- - `cmddef` (table): The WEA-registered definition of the command
+-- - `cmdname` (string): The name of the command, sans-forward slashes
+-- - `paramtext` (string): The unparsed `paramtext` the user passed as argument(s) to the command.
+-- - `player_name` (string): The name of the player calling the command.
+-- - `paramargs` (table): The parsed arguments returned by the parsing function. Available in `post-parse` and later.
+-- - `potential_changes` (number): The number of potential nodes that could be changed as a result of running the command. `post-nodesneeded` and later: remember not all commands have an associated `nodesneeded` function.
+-- - `success` (boolean): Whether the command executed successfully or not. Available only in `post-execute`.
+-- - `result` (any): The `result` value returned by the command function. Value depends on the command executed. Available only in `post-execute`.
 -- @param	cmdname		string	The name of the command to run.
 -- @param	options		table	The table of options associated with the command. See worldeditadditions_core.register_command for more information.
 -- @param	player_name	string	The name of the player to execute the command for.
@@ -36,6 +98,15 @@ local function run_command(cmdname, options, player_name, paramtext)
 		return false
 	end
 	
+	local tbl_event = {
+		cmddef = options,
+		cmdname = cmdname,
+		paramtext = paramtext,
+		player_name = player_name
+	}
+	
+	wea_c:emit("pre-parse", tbl_event)
+	
 	local parse_result = { options.parse(paramtext) }
 	local success = table.remove(parse_result, 1)
 	if not success then
@@ -43,8 +114,16 @@ local function run_command(cmdname, options, player_name, paramtext)
 		return false
 	end
 	
+	tbl_event.paramargs = parse_result
+	wea_c:emit("post-parse", tbl_event)
+	
+	
 	if options.nodes_needed then
 		local potential_changes = options.nodes_needed(player_name, wea_c.table.unpack(parse_result))
+		
+		tbl_event.potential_changes = potential_changes
+		wea_c:emit("post-nodesneeded", tbl_event)
+		
 		if type(potential_changes) ~= "number" then
 			worldedit.player_notify(player_name, "Error: The command '"..cmdname.."' returned a "..type(potential_changes).." instead of a number when asked how many nodes might be changed. Abort. This is a bug.")
 			return
@@ -59,13 +138,13 @@ local function run_command(cmdname, options, player_name, paramtext)
 		elseif potential_changes > limit then
 			worldedit.player_notify(player_name, "/"..cmdname.." "..paramtext.." may affect up to "..human_size(potential_changes).." nodes. Type //y to continue, or //n to cancel (see the //saferegion command to control when this message appears).")
 			safe_region(player_name, cmdname, function()
-				run_command_stage2(player_name, options.func, parse_result)
+				run_command_stage2(player_name, options.func, parse_result, tbl_event)
 			end)
 		else
-			run_command_stage2(player_name, options.func, parse_result)	
+			run_command_stage2(player_name, options.func, parse_result, tbl_event)	
 		end
 	else
-		run_command_stage2(player_name, options.func, parse_result)
+		run_command_stage2(player_name, options.func, parse_result, tbl_event)
 	end
 	
 end

worldeditadditions_core/init.lua

@@ -1,4 +1,5 @@
---- WorldEditAdditions-Core
+--- WorldEditAdditions core engine
+-- This namespace contains the core command processing engine used by WorldEditAdditions and associated parsing, formatting, and utility functions. It does not contain any of the commands themselves - see the namespace/'mod' simply called 'worldeditadditions' for that.
 -- @namespace worldeditadditions_core
 -- @release 1.14.5
 -- @copyright 2021 Starbeamrainbowlabs and VorTechnix
@@ -8,7 +9,9 @@
 
 local modpath = minetest.get_modpath("worldeditadditions_core")
 
-worldeditadditions_core = {
+local EventEmitter = dofile(modpath .. "/utils/EventEmitter.lua")
+
+worldeditadditions_core = EventEmitter.new({
 	version = "1.15-dev",
 	modpath = modpath,
 	registered_commands = {},
@@ -17,9 +20,9 @@ worldeditadditions_core = {
 	safe_region_limits = {},
 	-- The default limit for new players on the number of potential nodes changed before safe_region kicks in.
 	safe_region_limit_default = 100000,
-}
+})
 local wea_c = worldeditadditions_core
-wea_c.EventEmitter = dofile(modpath.."/utils/EventEmitter.lua")
+wea_c.EventEmitter = EventEmitter
 
 
 wea_c.Set = dofile(wea_c.modpath.."/utils/set.lua")
@@ -27,6 +30,7 @@ wea_c.Set = dofile(wea_c.modpath.."/utils/set.lua")
 wea_c.Vector3 = dofile(wea_c.modpath.."/utils/vector3.lua")
 wea_c.Mesh, wea_c.Face = dofile(wea_c.modpath.."/utils/mesh.lua")
 wea_c.rotation = dofile(wea_c.modpath .. "/utils/rotation.lua")
+wea_c.orientation = dofile(wea_c.modpath .. "/utils/orientation.lua")
 wea_c.param2 = dofile(wea_c.modpath .. "/utils/param2.lua")
 
 wea_c.Queue = dofile(wea_c.modpath.."/utils/queue.lua")

worldeditadditions_core/utils/orientation.lua

@@ -0,0 +1,81 @@
+
+
+-- This file is based on code from the screwdriver2 mod and a forum post on the Minetest forums. By @12Me21 and @khonkhortisan
+-- Edited by @sbrl
+-- Ref https://github.com/12Me21/screwdriver2/blob/master/init.lua#L75-L79
+-- Ref https://forum.minetest.net/viewtopic.php?p=73195&sid=1d2d2e4e76ce2ef9c84646481a4b84bc#p73195
+
+local facedir_cycles = {
+	x = { { 12, 13, 14, 15 }, { 16, 19, 18, 17 }, { 0, 4, 22, 8 }, { 1, 5, 23, 9 }, { 2, 6, 20, 10 }, { 3, 7, 21, 11 } },
+	y = { { 0, 1, 2, 3 }, { 20, 23, 22, 21 }, { 4, 13, 10, 19 }, { 8, 17, 6, 15 }, { 12, 9, 18, 7 }, { 16, 5, 14, 11 } },
+	z = { { 4, 5, 6, 7 }, { 8, 11, 10, 9 }, { 0, 16, 20, 12 }, { 1, 17, 21, 13 }, { 2, 18, 22, 14 }, { 3, 19, 23, 15 } },
+}
+local wallmounted_cycles = {
+	x = { 0, 4, 1, 5 },
+	y = { 4, 2, 5, 3 },
+	z = { 0, 3, 1, 2 },
+}
+
+-- We have standardised on radians for other rotation operations, so it wouldn't make sense for the API-facing functions in this file to use a number of times or degrees, as this would be inconsistent
+function convert_normalise_rad(rad)
+	local deg = math.deg(rad)
+	local times = worldeditadditions_core.round(deg / 90)
+	return math.floor(times) -- ensure it's an integer and not e.g. a float 1.0
+end
+
+--- Functions to rotate a facedir/wallmounted value around an axis by a certain amount
+-- 
+-- Code lifted from @12Me21 and @khonkhortisan
+-- 
+-- Ref <https://github.com/12Me21/screwdriver2/blob/master/init.lua#L75-L79> and <https://forum.minetest.net/viewtopic.php?p=73195&sid=1d2d2e4e76ce2ef9c84646481a4b84bc#p73195>
+-- @namespace worldeditadditions_core.orientation
+
+--- Facedir: lower 5 bits used for direction, 0 - 23
+-- @param	param2	number	`param2` value to rotate.
+-- @param	axis	string	The name of the axis to rotate around. Valid values: `x`, `y`, `z`
+-- @param	amount	The number of radians to rotate around the given `axis`. Only right angles are supported (i.e. 90° increments). Any value that isn't a 90° increment will be **rounded**!
+-- @returns	number	A new param2 value that is rotated the given number of degrees around the given `axis`
+function facedir(param2, axis, amount_rad)
+	local amount = convert_normalise_rad(amount_rad)
+	print("DEBUG:core/orientation:facedir AMOUNT rad "..tostring(amount_rad).." norm "..tostring(amount))
+	local facedir = param2 % 32
+	for _, cycle in ipairs(facedir_cycles[axis]) do
+		-- Find the current facedir
+		-- Minetest adds table.indexof, but I refuse to use it because it returns -1 rather than nil
+		for i, fd in ipairs(cycle) do
+			if fd == facedir then
+				return param2 - facedir + cycle[1 + (i - 1 + amount) % 4] -- If only Lua didn't use 1 indexing...
+			end
+		end
+	end
+	return param2
+end
+
+--- Wallmounted: lower 3 bits used, 0 - 5
+-- @param	param2	number	`param2` value to rotate.
+-- @param	axis	string	The name of the axis to rotate around. Valid values: `x`, `y`, `z`
+-- @param	amount	The number of radians to rotate around the given `axis`. Only right angles are supported (i.e. 90° increments). Any value that isn't a 90° increment will be **rounded**!
+-- @returns	number	A new param2 value that is rotated the given number of degrees around the given `axis`
+function wallmounted(param2, axis, amount_rad)
+	local amount = convert_normalise_rad(amount_rad)
+	print("DEBUG:core/orientation:wallmounted AMOUNT rad " .. tostring(amount_rad) .. " norm " .. tostring(amount))
+
+	local wallmounted = param2 % 8
+	for i, wm in ipairs(wallmounted_cycles[axis]) do
+		if wm == wallmounted then
+			return param2 - wallmounted + wallmounted_cycles[axis][1 + (i - 1 + amount) % 4]
+		end
+	end
+	return param2
+end
+
+local orientation = {
+	facedir = facedir,
+	wallmounted = wallmounted,
+	-- From the original codebase (linked above):
+	--colorfacedir = facedir,
+	--colorwallmounted = wallmounted
+	-- ...we'll need to know this later
+}
+
+return orientation

worldeditadditions_core/utils/rotation.lua

@@ -40,7 +40,7 @@ local function rotlist_compile(rotlist)
 end
 
 
---- Applies a given list of rotatiosn rotlist to rotate pos1 and pos2 around a given origin, and returns a pos1/pos2 pair of a region that bounds the rotated area.
+--- Applies a given list of rotations rotlist to rotate pos1 and pos2 around a given origin, and returns a pos1/pos2 pair of a region that bounds the rotated area.
 -- The returned pos1/pos2 are guaranteed to be integer values that fully enclose the rotated region. This function is designed to be used to e.g. find the bounds of a region to pass to a VoxelManip to ensure we grab everything.
 -- @param	pos1	Vector3		Position 1 to rotate.
 -- @param	pos2	Vector3		Position 2 to rotate.

worldeditadditions_core/utils/table/deepcopy.lua

@@ -1,3 +1,5 @@
+---
+-- @module worldeditadditions_core.table
 
 
 -- 4. Supporting recursive structures.

worldeditadditions_core/utils/table/init.lua

@@ -4,9 +4,10 @@
 --    ██    ██   ██ ██   ██ ██      ██           ██
 --    ██    ██   ██ ██████  ███████ ███████ ███████
 
--- Functions that operate on tables.
+--- Functions that operate on tables.
 -- Lua doesn't exactly come with batteries included, so this is quite an
 -- extensive collection of functions :P
+-- @namespace worldeditadditions_core.table
 
 local wea_c = worldeditadditions_core
 
@@ -22,5 +23,6 @@ wea_c.table = {
 	shallowcopy	= dofile(wea_c.modpath.."/utils/table/shallowcopy.lua"),
 	tostring	= dofile(wea_c.modpath.."/utils/table/table_tostring.lua"),
 	unique		= dofile(wea_c.modpath.."/utils/table/table_unique.lua"),
+	find		= dofile(wea_c.modpath.."/utils/table/table_find.lua"),
 	unpack		= dofile(wea_c.modpath.."/utils/table/table_unpack.lua"),
 }

worldeditadditions_core/utils/table/makeset.lua

@@ -1,4 +1,9 @@
+---
+-- @module worldeditadditions_core.table
+
+
 --- Creates a table that stores data in keys.
+-- See also `worldeditadditions_core.Set`.
 -- @source	https://riptutorial.com/lua/example/13407/search-for-an-item-in-a-list
 -- @param	list	table	The table of values to convert to keys.
 -- @return	table	The table of (key => true) pairs.

worldeditadditions_core/utils/table/shallowcopy.lua

@@ -1,3 +1,6 @@
+---
+-- @module worldeditadditions_core.table
+
 
 --- Shallow clones a table.
 -- @source	http://lua-users.org/wiki/CopyTable

worldeditadditions_core/utils/table/table_apply.lua

@@ -1,11 +1,14 @@
---- SHALLOW ONLY - applies the values in source to overwrite the equivalent keys in target.
+---
--- Warning: This function mutates target!
+-- @module worldeditadditions_core.table
+
+--- SHALLOW ONLY - applies the values in source to overwrite the equivalent keys in `target`.
+-- Warning: This function mutates `target`!
 -- @param	source	table	The source to take values from
 -- @param	target	table	The target to write values to
-local function table_apply(source, target)
+local function apply(source, target)
 	for key, value in pairs(source) do
 		target[key] = value
 	end
 end
 
-return table_apply
+return apply

worldeditadditions_core/utils/table/table_contains.lua

@@ -1,13 +1,15 @@
+---
+-- @module worldeditadditions_core.table
 
 --- Looks to see whether a given table contains a given value.
 -- @param	tbl		table	The table to look in.
 -- @param	target	any		The target to look for.
 -- @returns	bool	Whether the table contains the given target or not.
-local function table_contains(tbl, target)
+local function contains(tbl, target)
 	for key, value in ipairs(tbl) do
 		if value == target then return true end
 	end
 	return false
 end
 
-return table_contains
+return contains

worldeditadditions_core/utils/table/table_filter.lua

@@ -1,3 +1,6 @@
+---
+-- @module worldeditadditions_core.table
+
 --- Filters the items in the given table using the given function.
 -- The function is executed for each item in the list. If it returns true, the
 -- item is kept. If it returns false, the item is discarded.
@@ -7,7 +10,7 @@
 -- @param	tbl		table		The table of values to filter.
 -- @param	func	function<any, number>:bool	The filter function to execute - should return a boolean value indicating whether the item provided as the first argument should be kept
 -- @returns	table	A new table containing the values that the given function returned true for.
-local function table_filter(tbl, func)
+local function filter(tbl, func)
 	local result = {}
 	for i,value in ipairs(tbl) do
 		if func(value, i) then
@@ -17,4 +20,4 @@ local function table_filter(tbl, func)
 	return result
 end
 
-return table_filter
+return filter

worldeditadditions_core/utils/table/table_find.lua

@@ -0,0 +1,23 @@
+---
+-- @module worldeditadditions_core.table
+
+--- Finds the first element in the given table that satisfies the given testing function.
+-- A port of Javascript's `array.find` to Lua.
+-- 
+-- Uses for .. in ipairs() under-the-hood.
+-- 
+-- @param	tbl		table		The table to search.
+-- @param	func	function	The testing function to call on each element. The function should return true/false as to whether the passed value passes the test function. The testing function will be provided with the following arguments:
+-- 1. `value` (any): The value being inspected.
+-- 2. `i` (number): The index in the table that the value can be found at
+-- 3. `tbl` (table): The original table.
+-- @return any|nil The first element in the table that satisfies the predicate, or nil if no such element is found.
+function find(tbl, func)
+	for i,value in ipairs(tbl) do
+		if func(value, i, tbl) then
+			return value
+		end
+	end
+end
+
+return find

worldeditadditions_core/utils/table/table_get_last.lua

@@ -2,16 +2,18 @@ local wea_c = worldeditadditions_core
 
 local table_unpack = dofile(wea_c.modpath.."/utils/table/table_unpack.lua")
 
+---
+-- @module worldeditadditions_core.table
 
 --- Returns only the last count items in a given numerical table-based list.
 -- @param	tbl		table		The table to fetch items from.
 -- @param	count	number		The number of items to fetch from the end of the table.
 -- @returns	table	A table containing the last count items from the given table.
-local function table_get_last(tbl, count)
+local function get_last(tbl, count)
 	return {table_unpack(
 		tbl,
 		math.max(0, (#tbl) - (count - 1))
 	)}
 end
 
-return table_get_last
+return get_last

worldeditadditions_core/utils/table/table_map.lua

@@ -1,9 +1,12 @@
+---
+-- @module worldeditadditions_core.table
+
 --- Executes the given function on every item in the given table.
 -- Ignores return values that are nil and doesn't insert them into the table.
 -- @param	tbl		table		The table to operate on.
 -- @param	func	function<any>:any|nil	The function to execute on every item in the table.
 -- @returns	table	A new table containing the return values of the function.
-local function table_map(tbl, func)
+local function map(tbl, func)
 	local result = {}
 	for i,value in ipairs(tbl) do
 		local newval = func(value, i)
@@ -12,4 +15,4 @@ local function table_map(tbl, func)
 	return result
 end
 
-return table_map
+return map

worldeditadditions_core/utils/table/table_reduce.lua

@@ -1,10 +1,11 @@
+---
+-- @module worldeditadditions_core.table
 
-
+--- Lua implementation of `array.reduce()` from Javascript.
---- Lua implementation of array.reduce() from Javascript.
 -- @param	tbl				The table to iterate over.
 -- @param	func			The function to call for every element in tbl. Will be passed the following arguments: accumulator, value, index, table. Of course, the provided function need not take this many arguments.
 -- @param	initial_value	The initial value of the accumulator.
-local function table_reduce(tbl, func, initial_value)
+local function reduce(tbl, func, initial_value)
 	local acc = initial_value
 	for key, value in pairs(tbl) do
 		acc = func(acc, value, key, tbl)
@@ -12,4 +13,4 @@ local function table_reduce(tbl, func, initial_value)
 	return acc
 end
 
-return table_reduce
+return reduce

worldeditadditions_core/utils/table/table_tostring.lua

@@ -1,10 +1,13 @@
+---
+-- @module worldeditadditions_core.table
+
 --- Returns the key value pairs in a table as a single string
 -- @param	tbl	table	input table
 -- @param	sep	string	key value seperator
 -- @param	new_line	string	key value pair delimiter
 -- @param	max_depth	number	max recursion depth (optional)
 -- @return	string	concatenated table pairs
-local function table_tostring(tbl, sep, new_line, max_depth)
+local function tostring(tbl, sep, new_line, max_depth)
 	if type(sep) ~= "string" then sep = ": " end
 	if type(new_line) ~= "string" then new_line = ", " end
 	if type(max_depth) == "number" then max_depth = {depth=0,max=max_depth}
@@ -25,4 +28,4 @@ end
 -- Test:
 -- /lua v1 = { x= 0.335, facing= { axis= "z", sign= -1 } }; print(worldeditadditions.table.tostring(v1))
 
-return table_tostring
+return tostring

worldeditadditions_core/utils/table/table_unique.lua

@@ -1,7 +1,12 @@
+---
+-- @module worldeditadditions_core.table
+
+
 --- Builds a new table with the elements of the given table appearing at most once.
+-- See also `worldeditadditions_core.Set`.
 -- @param	tbl		table	The table of values to make unique.
 -- @returns	table	A new table containing the values of the given table appearing at most once.
-local function table_unique(tbl)
+local function unique(tbl)
 	local newtbl = {}
 	for i,value in ipairs(tbl) do
 		local seen = false
@@ -18,4 +23,4 @@ local function table_unique(tbl)
 	return newtbl
 end
 
-return table_unique
+return unique

worldeditadditions_core/utils/table/table_unpack.lua

@@ -1,8 +1,19 @@
+---
+-- @module worldeditadditions_core.table
+
 --- Polyfill for unpack / table.unpack.
 -- Calls unpack when available, and looks for table.unpack if unpack() isn't
 -- found.
 -- This is needed because in Lua 5.1 it's the global unpack(), but in Lua 5.4
 -- it's moved to table.unpack().
+--
+-- Important: All unpack calls in WorldEditAdditions **MUST** use this function.
+-- @param	tbl			table	The table to unpack
+-- @param	[offset=0]	number	The offset at which to start unpacking.
+-- @param	[count=nil]	number	The number of items to unpack. Defaults to unpack all remaining items after `offset`.
+-- @returns any...		The selected items unpacked from the table.
+-- @example Lua version agnostic unpack
+-- print(worldeditadditions_core.table.unpack({1 = "apple", 2 = "orange"}))
 local function table_unpack(tbl, offset, count)
 	---@diagnostic disable-next-line: deprecated
 	if type(unpack) == "function" then