Adding Drain, corresponding brush and new flag

CONTRIBUTING.md

@@ -80,10 +80,11 @@ case it was too confusing:
    e     copy/move entities as well
    b     copy/move biomes as well (handled by set_block)
    a     don't paste air
-   h	 create hollow shapes
+   h	   create hollow shapes
    d     "dry" out the pasted structure (remove water and waterlogged)
    s     keep block states of replaced block, if new block matches
    g     when replacing air or water, some greenery gets repalced too
+   l     when registering a brush with this flag, the brush will trace for liquids as well as blocks
    ```
    Biomes are handled by the `set_block` function, but you need to input the previous biome as a map in the `extra` 
    argument: `{'biome' -> biome}`, where the variable `biome` is the biome at the position you copied from. No need to 
@@ -190,32 +191,68 @@ add your commands into the `base_command_map` instead with the following format:
 -  `[command_for_carpet, interpretation_for_carpet, false] (will hide it from help menu)`
 -  `[command_for_carpet, interpretation_for_carpet, [optional_arguments_since, description, description_tooltip, description_action]]`
 
-Explained in words: In the list, you add the command for carpet ("syntax") (eg `'fill <block>'`) as the first element.
-The second element is the "interpretation" for Carpet (what will that do, basically the other side of a regular commands
-map), and then the third item is either `false` (to prevent it from appearing in help menu, for example, `help` can be 
-hidden since `help [page]` is basically the same) or another list with the info for the help menu, which you can find below.
-
-- `command_for_carpet`: As mentioned, it is the command "syntax" that will be passed to Carpet, the equivalent to the 
-  first side of a regular commands map
-- `interpretation_for_carpet`: As mentioned, it is how Carpet will process that command, the equivalent to the other side
-  of a regular commands map
-- `optional_arguments_since`: The position of the first argument to make visibly optional (`<arg>` to `[arg]`). Can be 
-  used to merge multiple commands in help menu (e.g. `help` and `help <page>` into `help [page]`). If the command shouldn't
-  have any optional arguments, use `-1`
+In words: the first two arguments are the usual key and value arguments in the `__config():'commands'` map when defining custom commands 
+with scarpet the regular way. For example, they can be `'fill <block>'` and `'fill_with_blocks'`, where the latter is a user-defined 
+function. The third element in the list is what defines the representation of the command in the help menu. Use `false` to hide the command
+from the help menu (not every variation of a command needs it's individual entry), or see below for more info.
+
+- `command_for_carpet`: it's the command "syntax" that will be passed to Carpet, the equivalent to the 
+  key in regular commands map
+- `interpretation_for_carpet`: it's how Carpet will process that command, the equivalent to value argument of a regular commands map
+- `optional_arguments_since`: the index of the first optional argument in the command out of all arguments given. optional arguemtns will
+  be printed as `[arg]`, and mandaroty ones as `<arg>` For isntance, setting it to `0` will make all arguments optional, while setting it to
+  `2` means the first two arguments are mandatory. Set it to `-1` if all arguments are mandatory. This can be used to merge multiple commands
+  into one help entry (for isntance, `help [page]` represents both the `help` and `help <page>` commands).
 - `description`: The description of the command in the help menu. Must be a translation string (see [Messages](#messages))
   or a lambda (if you need arguments in the translation, `_()->_translate('string', ...args)`). (it can technically be 
   `null`, but the idea is to add a description)
 - `description_tooltip`: An optional tooltip to show when the user is hovering the description. Can be `null`. If present,
   it must be a translation string or a lambda (if you need arguments in the translation)
 - `description_action` An optional action to run when the player clicks the description. Can be `null`. If present, it must
   start with either `!` (to specify it will _run_ the action) or `?` (to specify it will _suggest_ the action). The command
-  is automatically prefixed with `/worldedit ` (and a space)
+  is automatically prefixed with `/world-edit ` (and a space)
 
 The command suggestion will be derived from `command_for_carpet`: everything before the first `<`.
 
 You should try to fit each entry in a single line (when viewed in the help menu) for proper pagination (until something 
 is done).
 
+#### Items with new functionality
+
+Some items have built-in functionality, like the wand, but the user has the ability to add more items with actions associated
+with them (like brushes and angel block, for instance). If you want to add a new item functionality (say, building wand, for 
+example), then you need to take care of a few things, to avoid one item having multiple actions associated with it:
+  * When registering an item for a new action, call `new_action_item(item, action)`. This will check if the item is already 
+  registered for another action and call `_error()` if it is. Remember, that `exit`s, so there no need for an extra `return()` 
+  call or anything, that function does the check for you.
+  * When unregistering an item (not replacing it with a new one, like the wand does, actually deleting it), call 
+  `remove_action_item(item, action)`, which will check that the requested item indeed has that action registered to it. It also 
+  `exit`s if it fails. For isntance, `brush` uses it like this:
+  ```C++
+      if(
+        action=='clear',
+        remove_action_item(held_item, 'brush'); // delete old item from global_items_with_actions
+        delete(global_brushes, held_item); // deregister item as brush
+        ...
+  ```
+  * For these two functions to work properly, you any new action you add needs a few things: 
+      1. add your action's name to the `global_lang_keys` so it can be translated
+      2. add your action's code name to `global_item_action_translation_key` so it can be requested from `global_lang_keys` (for example,
+      the angel block's code name is `'angel'`, with a translation key `'action_item_angel'`, which gives the text `'angel block item'`)
+      3. if your new action has a default tool or item (like the wand does), add it to `global_items_with_actions` along with its action
+  * If registering a new item to your action just replaces the previous one, rather than adding a brand new one (think wand vs brush: one 
+  replaces the old wand with a new one, while the other adds a new brush, leaving the old ones untouched), take good care to manually 
+  delete the old item from `global_items_with_actions` just before adding the new one. Angel block for example does it like this:
+  ```C++
+  _set_angel_block_item() -> (
+    new_action_item(item = player()~'holds':0, 'angel'); // add new item
+    delete(global_items_with_actions, global_angel_block); // delete old one
+    global_angel_block = item; // register new item as angel block
+    ...
+  ```
+  This is extremely important so that old deregistered items can be reused for new actions by the player.
+
+
 #### Other functions
 
 If you're doing something that changes the player's stored data, please ensure that:

docs/Documentation.md

@@ -49,11 +49,6 @@ Left clicking again will reselect the whole box.
  - `/world-edit paste` -> Pastes selection relative to player position. Be careful in case you didn't choose a wise spot
     when making the selection.
  - `/world-edit paste <pos>` -> Pastes selection relative to `pos`
- - `/world-edit flood <block>` -> Performs a flood fill (fill connex volume) within the selection and starting at the 
-    player's position. Can both "fill"
- what used to be air or replace some other block.
- - `/world-edit flood <block> <axis>` -> Flood fill will happen only perpendicular to an axis. Setting axis to `y`, for 
-    instance, will fill the horizontal plane.
  - `/world-edit structure list` -> Lists all available structures. Currently, they are all in the same file as the lang 
     files, this may change soon. You can add other structure files, and they will load properly 
  - `/world-edit structure load <structure name> <pos?>` -> Loads a structure relative to `pos`, or relative to player 
@@ -65,20 +60,21 @@ Left clicking again will reselect the whole box.
     structure blocks.`force` will override an existing structure with the same name. Gives an error if no clipboard is 
     present. Will also copy entities.
  - `/world-edit structure delete <name>` -> Deletes a structure file called `name`.
- - `/world-edit copy [pos]` -> Copies selection to clipboard setting the origin of the structure at `[pos]`, if given, or
-    the curren player position, if not. By default, will not override the existing clipboard (can be changed by adding
-    keyword `force`), and will also take the positions relative to position of player.
- - `/world-edit paste [pos]` -> Pastes selection relative to player position or to `[pos]`, if given. Be careful incase 
-    you didnt' choose a wise spot making the selection.
- - `/world-edit flood <block>` -> Performs a flood fill (fill connex volume) within the selection and starting at the 
-    player's position. Can both "fill" used to be air or replace some other block.
- - `/world-edit flood <block> [axis]` -> Flood fill will happen only perpendicular to iven axis. Setting axis to `y`, for
-    instance, will fill the horizontal plane.
- - `/world-edit walls <block> [sides] [replacement]` -> Creates walls on the sides specified around the selection, defaults
-    to ony vertical walls (`xz`).
+ - `/world-edit copy [pos]` -> Copies selection to clipboard setting the origin of the structure at `[pos]`, if given, or the curren player position, if not. By default, 
+   will not override the existing clipboard (can be changed by adding keyword `force`), and will also take the positions relative to position of player.
+ - `/world-edit paste [pos]` -> Pastes selection relative to player position or to `[pos]`, if given. Be careful incase you didnt' choose a wise spot making the selection.
+ - `/world-edit flood <block> [axis] [radius]` -> Performs a flood fill (fill connex volume) starting at the player's position. Flood will be limited by the current selection, 
+    unless `[radius]` is given, in which case it will happen within a sphere. `[axis]` has to be `x`, `y` or `z` to performa flat flood fill within the plane perpendicular to 
+    the given axis, or `none` to perform a 3D flood fill (default behaviour). Use this with `<block>` set to air to delete stuff.
+ - `/world-edit drain [radius]` -> Drains the liquid the player is standing on. By default, it does so on a given radius, but you can set that with the optional parameter. If 
+  you don't specify a radius and are standing in a seleciton, it will drain within the selection only. It supports the `-g` flag, try it!
+ - `/world-edit walls <block> [sides] [replacement]` -> Creates walls on the sides specified around the selection, defalts to ony vertical walls (`xz`).
  - `/world-edit outline <block> [replacement]` -> Outlines the selection with `<block>`.
  - `/world-edit shape ...` -> Generates a shape centered arround the palyer. See brushes for all options and parameters.
- - `/world-edit up <distance>` -> Teleports you up `<distance>` ammount of blocks. Places a block under you if there was nothing there, so you don't fall and can start building right away.
+ - `/world-edit angel [new|clear]` -> Angel block: click in mid air to place a (stone) block you can the build off. Without arguments, it gives the player the item registered 
+  as angel block. With `new`, it will register the currently held item as angel block item. With `clear` clears the current angel block item; you will have to register a new one
+  to use it.
+- `/world-edit up <distance>` -> Teleports you up `<distance>` ammount of blocks. Places a block under you if there was nothing there, so you don't fall and can start building right away.
 
 #### Brushes
 
@@ -112,9 +108,8 @@ The available actions for brushes are:
 - `line <block> [length] [replacement]` -> creates a line out of `block` between the player and the clicked block, replacing
     only blocks that match `replacement` (block or tag), if given. If `length` is given, the length of the line is fixed,
     and it only uses the clicked block to get the direction of the line.
-- `flood <block> <radius> [axis]` -> creates a flood fill starting in the target block and modifying all the connected blocks
-    to become `block`, always staying within `radius` blocks of the starting point. The flood happens in the plane 
-    perpendicular to `axis`, if given.
+- `flood <block> <radius> [axis]` -> creates a flood fill starting in the target block and modifying all the connex blocks to become `block`, always staying within `radius` blocks of the starting point. The flood happens in the plane perpendicular to `axis`, if given.
+- `drain <radius>` -> Drains the liquids connected to the liquid block you click, up to `<radius>` blocks away.
 - `paste` -> pastes the current clipboard, using the targeted block as origin.
 - `feature <fearure>` -> places a feature (decoration) in the targeted location. Can fail, if natural feature would fail. DOES NOT SUPPORT `undo` functionality.
 - `spray <block> [size] [count] [replacement]` -> creates a spray paint effect: projects `[count]` (100 by default) random rays around the volume the player is looking at in a cone with `[size]` (12 degrees, by default) angle aperture and places `<block>` in a random patter.
@@ -141,3 +136,4 @@ Available flags:
  - `-s` -> Preserves block states when setting blocks
  - `-g` -> When replacing air or water, greenery corresponding to each medium will be replaced too
  - `-h` -> When creating a shape, makes it hollow
+ - `-l` -> When used to register a brush, the brush will targer liquids as well as blocks, instead of going right through them to the block behind.