Merge pull request Ghoulboy78#49 from Ghoulboy78/brush-overhaul

Brush overhaul

CONTRIBUTING.md

@@ -17,8 +17,9 @@ This applies to everyone, including admins. The PR needs at least 2 reviews befo
 
 #### Block manipulating commands
 
-If you're gonna add a new function that manipulates blocks in the world, you should first familiarize yourself with the
-existing code, so you know what to do right off the bat, but here is the tl;dr, in case it was too confusing:
+If you're gonna add a new function that manipulates blocks in the world with a player - utilisable function, you should 
+first familiarize yourself with the existing code, so you know what to do right off the bat, but here is the tl;dr, in 
+case it was too confusing:
 
 1. Define the function below all the other defined functions (i.e, underneath the comment which says `//Command functions`).
    This helps with legibility of your code later on.
@@ -87,7 +88,63 @@ existing code, so you know what to do right off the bat, but here is the tl;dr,
    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 
    handle undoing, `set_block` does that on its own.
-
+
+#### Brushes
+
+If you are adding a new brush function, there is a simple syntax to follow to ensure it is compatible with the existing 
+brush function utility. You must add your new function in the following fashion:
+
+Add your function as an entry to the `global_brush_shapes` map variable, with the key being the string name of your function,
+and the value being a lambda function with `(pos, args, flags)` as the arguments. This is where you can manipulate the 
+world in whatever way you see fit, and must call the `add_to_history()` function (cos not all brush functions set blocks).
+You can take whichever arguments you need from the args `args` variable as long as you specify them in the input command.
+You must also add a command which takes the correct inputs and passes them to the `shape()` function in the proper manner.
+You must also add a translation key for the action to the lang file.
+
+If this was too bulky and confusing too understand, here is a full example of  the `cube` function, which simply places
+cubes:
+
+1. First, we add an entry to the `global_brush_shapes` map variable which consists of the string `'cube'` mapped to the 
+   block setting function:
+      ```
+   global_brush_shapes={
+         ... //brush entries
+         'cube'->_(pos, args, flags)->(//this can be like a template for new brushes as it's the simplest
+            [block, size, replacement] = args;
+            scan(pos,[size,size,size]/2, set_block(_, block, replacement, flags, {}));
+            add_to_history('action_cube',player())
+         ),
+         ... //more entries
+   }
+      ```
+   Here, we can see the lambda (`_(pos, args, flags)->`) which is called when you right click with the brush or use the
+   `/shape` command.
+
+
+2. We can see that we got three arguments: `[block, size, replacement] = args;`. We can know that we are going to get
+   these arguments when we define the command:
+   ```
+   base_commands_map = [
+      ... //commands
+      ['cube <block> <size> replace <replacement> f <flags>', _(block, size, replacement, flags)->shape('cube',[block, size, replacement], flags)'']
+      ... //more commands
+   ]
+   ```
+   It is important to use that syntax of calling the `shape()` function to work properly.
+
+
+3. We can also see that we ran the `add_to_history` function with `'action_cube'`, not `'cube'`. This is because we need
+   to then add an entry to the translations map (`global_default_lang`). This is so the action name can be translated to
+   other languages when running the `/undo history` command. Add your translation key to
+   the map, mapped to the en_us translation:
+   ```
+   global_default_lang = {
+      ... //other entries
+      'action_cube' -> 'cube',
+      ... //more entries
+   }
+   ```
+
 #### Messages
 
 If you want to print a message as an output to the player, the easiest way is using the `_print(player, message_id, ...extra_args)`

docs/Documentation.md

@@ -14,34 +14,39 @@ The main contributors to this project are:
  - altrisi	 (GitHub: altrisi, Discord: altrisi#9772)
 
 ## How to use
-
 If you are running an outdated version of fabric-carpet, WorldEdit for scarpet won't work. Currently, the oldest compatible
 version is: carpet 1.4.22
 
 ### Area selection
 
-This is done by left-clicking with the wand (default wooden sword)
+This is done by left-clicking with the wand (default is wooden sword)
 
 It will pop up a grid, and it will follow your mouse (hovering 5 blocks in midair if need be) until you left click again.
 Left clicking again will reselect the whole box.
 
 ### Commands:
- - `/world-edit fill <block> [replacement]` -> Fills selection with `<block>`. If `[replacement]` is given, it only fills replacing that block or block tag.
- - `/world-edit undo [moves]` -> Undoes last move performed by player or as many as specified by `[moves]`. This can be redone with `/world-edit redo`.
+ - `/world-edit fill <block> [replacement]` -> Fills selection with `<block>`. If `[replacement]` is given, it only fills
+    replacing that block or block tag.
+ - `/world-edit undo [moves]` -> Undoes last move performed by player or as many as specified by `[moves]`. This can be
+    redone with `/world-edit redo`.
  - `/world-edit undo all` -> Undoes entire undo history. Careful!
  - `/world-edit undo history` -> Displays entire undo history.
- - `/world-edit redo [moves]` -> Redoes `[moves]` ammount undone by the player, or one if not specified. Also shows up in undo history.
- - `/world-edit redo all` -> Redoes all undone moves.
- - `/world-edit wand <wand>` -> Sets wand to held item, or if your hand is empty, gives you the wand. With optional `[wand]` argument, it sets wand to specified item
- - `/world-edit rotate <pos> <degrees> <axis>` -> Rotates selection `degrees` degrees about point `pos`. Axis must be `x`, `y` or `z`.
- - `/world-edit stack [stackcount] [direction]` -> Stacks selection in the direction the player is looking if not otherwise specfied. By defaults, it stacks one time.
+ - `/world-edit redo [moves]` -> Redoes `[moves]` amount of moves previously undone by the player, or one if not specified.
+    Also shows up in undo history so you can re- undo them.
+ - `/world-edit redo all` -> Redoes all undone moves. (These can be re- undone by regular /undo command)
+ - `/world-edit wand <wand>` -> Sets wand to held item, or if your hand is empty, gives you the wand. With optional `[wand]`
+    argument, it sets wand to specified item
+ - `/world-edit rotate <pos> <degrees> <axis>` -> Rotates selection `degrees` degrees about point `pos`. Axis must be `x`,
+    `y` or `z`. NB: This will look funky if you do not use multiples of 45 or 90.
+ - `/world-edit stack [stackcount] [direction]` -> Stacks selection in the direction the player is looking if not otherwise
+    specfied. By defaults, it stacks one time.
  - `/world-edit expand <pos> <magnitude>` -> Expands selection by whatever magnitude specified by player, from pos `pos`
  - `/world-edit move <pos>` -> Moves selection to `pos`
  - `/world-edit copy` -> Copies selection to clipboard. 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 copy <pos>` -> Copies selection to clipboard, with positions relative to `pos`. This is significant when 
     pasting blocks, in terms of how it is pasted.
- - `/world-edit paste` -> Pastes selection relative to player position. Be careful incase you didnt' choose a wise spot
+ - `/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 
@@ -57,35 +62,62 @@ Left clicking again will reselect the whole box.
     structure blocks. `entities` will make it save entities, and `force` will override an existing structure with the same
     name.
  - `/world-edit structure save <name> clipboard force?` -> Saves current clipboard to a `.nbt` file compatible with vanilla 
-    structure blocks.`force` will override an existing structure with the same name. Gives an error if no clipboard is present.
-    Will also copy entities.
+    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 isntance, will fill the horizontal plane.
- - `/world-edit walls <block> [sides] [replacement]` -> Creates walls on the sides specified around the selection, defalts 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>` -> 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 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.
 
 #### Brushes
 
-`brushes` let you attach some actions or commands to specific items to use them at a distance. When registering an action with `/world-edit brush <action> <arguments>`, the held item type will be converted into a brush and righ clicking with it will perform the registered action at the highlited block. To view the currently registered brushes use `/world-edit brush list`. To remove a brush from said list or get more info on the registered action for that brush, hold the corresponding item type and use `/world-edit brush clear` or `/world-edit brush info`, respectively.
+`brushes` let you attach some actions or commands to specific items to use them at a distance. When registering an action
+with `/world-edit brush <action> <arguments>`, the held item type will be converted into a brush and right clicking with
+it will perform the registered action at the highlighted block. To view the currently registered brushes use `/world-edit brush list`.
+To remove a brush from said list or get more info on the registered action for that brush, hold the corresponding item type
+and use `/world-edit brush clear` or `/world-edit brush info`, respectively.
 
 The available actions for brushes are:
-- `cube <block> <size> [replacement]` -> creates a cube out of `block` and with side length `size`, replacing only blocks that match `replacement` (block or tag), if given.
-- `cuboid <block> <x> <y> <z> [replacement]` -> creates a cuboid out of `block` and with side lengths `x`, `y` and `z`, replacing only blocks that match `replacement` (block or tag), if given.
-- `sphere <block> <radius> [replacement]` -> creates a sphere out of `block` and with `radius`, replacing only blocks that match `replacement` (block or tag), if given.
-- `ellipsoid <block> <x_radius> <y_radius> <z_radius> [replacement]` -> creates an ellipsoid with different raddi on each axis, replacing only blocks that match `replacement` (block or tag), if given.
-- `cylinder <block> <radius> <height> [axis] [replacement]` -> creates a cylinder out of `block` and with `radius` and `height` along `axis` (if given; else, defaults to `y` for a vertical cylinder), replacing only blocks that match `replacement` (block or tag), if given.
-- `cone <block> <radius> <height> [signed_axis] [replacement]` -> creates a cone out of `block` and with `radius` and `height` along `signed_axis` (if given; else, defaults to `+y` for a vertical cone pointing up), replacing only blocks that match `replacement` (block or tag), if given.
-- `prism_polygon <block> <radius> <height> <vertices> [axis] [rotation] [replacement]` -> generates a polygon inscribed in a circle of `radius` with `vertices` ammount of sides. Said polygon is the base for a prism of height `height` along `axis`. Optionally, it can be rotated from it's base orientation.
-- `prism_star <block> <outer_radius> <inner_radius> <height> <vertices> [axis] [rotation] [replacement]` -> generates a star whouse points touch a circle of radius `outer_radius` with `vertices` ammount of points. Said star is the base for a prism of height `height` along `axis`. Optionally, it can be rotated from it's base orientation.
-- `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 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.
+- `cube <block> <size> [replacement]` -> creates a cube out of `block` and with side length `size`, replacing only blocks
+    that match `replacement` (block or tag), if given.
+- `cuboid <block> <x> <y> <z> [replacement]` -> creates a cuboid out of `block` and with side lengths `x`, `y` and `z`, 
+    replacing only blocks that match `replacement` (block or tag), if given.
+- `sphere <block> <radius> [replacement]` -> creates a sphere out of `block` and with `radius`, replacing only blocks that
+    match `replacement` (block or tag), if given.
+- `ellipsoid <block> <x_radius> <y_radius> <z_radius> [replacement]` -> creates an ellipsoid with different radii on each
+    axis, replacing only blocks that match `replacement` (block or tag), if given.
+- `cylinder <block> <radius> <height> [axis] [replacement]` -> creates a cylinder out of `block` and with `radius` and 
+    `height` along `axis` (if given; else, defaults to `y` for a vertical cylinder), replacing only blocks that match 
+    `replacement` (block or tag), if given.
+- `cone <block> <radius> <height> [signed_axis] [replacement]` -> creates a cone out of `block` and with `radius` and 
+    `height` along `signed_axis` (if given; else, defaults to `+y` for a vertical cone pointing up), replacing only blocks
+    that match `replacement` (block or tag), if given.
+- `prism_polygon <block> <radius> <height> <vertices> [axis] [rotation] [replacement]` -> generates a prism with the base
+    of a regular polygon inscribed in a circle of `radius` with `vertices` amount of sides and height `height` along `axis`.
+    Optionally, it can be rotated from its base orientation.
+- `prism_star <block> <outer_radius> <inner_radius> <height> <vertices> [axis] [rotation] [replacement]` -> generates a 
+    star whose points touch a circle of radius `outer_radius` with `vertices` amount of points. Said star is the base 
+    for a prism of height `height` along `axis`. Optionally, it can be rotated from its base orientation.
+- `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.
 - `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.
+- `feature <feature>` -> places a feature (decoration) in the targeted location. Can fail, if natural feature would fail.
+    DOES NOT SUPPORT `undo` functionality.
 
 All brush functions can be appended with flags, same as fill commands, adding `f -<flags>` at the end of the regular commands.
 
@@ -98,13 +130,13 @@ an effect in each case.
 Available flags:
 
  - `-u` -> Places blocks without block updates
- - `-w` -> Waterlogs blocks placed in water or in other waterlogged blocks, air included
+ - `-w` -> Water-logs blocks placed in water or in other waterlogged blocks, air included
  - `-d` -> Removes water and waterlogged state from placed blocks. Applies before `-w`
  - `-p` -> Only replaces air blocks when setting an area
  - `-e` -> Copies/moves entities from old location to new location. Technically, a new entity is generated with same data
     and position within the structure as the old one, so all that changes is UUID. Undoing will not remove these entities
  - `-b` -> Copies old biomes to new location.
  - `-a` -> Pasting a structure will not paste the air blocks within the structure.
- - `-s` -> Preserves block states when seting blocks
+ - `-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