build_files/.htaccess

@@ -254,3 +254,24 @@ RedirectMatch "^/manual/{lang}/{version}/modeling/geometry_nodes/utilities/rotat
 
 RedirectMatch "^/manual/{lang}/{version}/modeling/modifiers/modify/normal_edit.html" "^/manual/{lang}/{version}/modeling/modifiers/normals/normal_edit.html"
 RedirectMatch "^/manual/{lang}/{version}/modeling/modifiers/modify/weighted_normal.html" "^/manual/{lang}/{version}/modeling/modifiers/normals/weighted_normal.html"
+
+RedirectMatch "^/manual/{lang}/{version}/sculpt_paint/brush/brush.html" "^/manual/{lang}/{version}/sculpt_paint/brush/introduction.html"
+RedirectMatch "^/manual/{lang}/{version}/sculpt_paint/sculpting/tools/rotate.html" "^/manual/{lang}/{version}/sculpt_paint/sculpting/brushes/twist.html"
+RedirectMatch "^/manual/{lang}/{version}/sculpt_paint/sculpting/tools/simplify.html" "^/manual/{lang}/{version}/sculpt_paint/sculpting/brushes/density.html"
+# Mesh sculpting tools converted to asset
+RedirectMatch "^/manual/{lang}/{version}/sculpt_paint/sculpting/tools/\
+                   (blob|boundary|clay|clay_strips|clay_thumb|cloth|crease|draw|draw_facesets|draw_sharp|\
+                   elastic_deform|fill|flatten|grab|inflate|layer|mask|multiplane_scrape|\
+                   multires_displacement_eraser|multires_displacement_smear|nudge|paint|pinch|pose|\
+                   scrape|slide_relax|smear|smooth|snake_hook|thumb).html" \
+                "^/manual/{lang}/{version}/sculpt_paint/sculpting/brushes/$1.html"
+# Curve sculpting tools converted to asset
+RedirectMatch "^/manual/{lang}/{version}/sculpt_paint/curves_sculpting/tools/\
+                   (index|add_curves|comb_curves|delete_curves|density_curves|grow_shrink_curves|\
+                   pinch_curves|puff_curves|selection_paint|slide_curves|smooth_curves|snake_hook_curves).html" \
+                "^/manual/{lang}/{version}/sculpt_paint/curves_sculpting/brushes/$1.html"
+# Grease pencil draw tools
+RedirectMatch "^/manual/{lang}/{version}/grease_pencil/modes/draw/tools/(draw|erase|fill|tint).html" \
+                "^/manual/{lang}/{version}/sculpt_paint/curves_sculpting/brushes/$1.html"
+# Texture paint tools converted to asset
+RedirectMatch "^/manual/{lang}/{version}/sculpt_paint/texture_paint/tools.html" "^/manual/{lang}/{version}/sculpt_paint/texture_paint/brushes.html"

manual/editors/3dview/introduction.rst

@@ -110,3 +110,11 @@ The Sidebar region contains properties of the active object and tool,
 as well as of the viewport itself.
 
 See :doc:`Sidebar </editors/3dview/sidebar>` for more information.
+
+Asset Shelf Region
+==================
+
+Depending on the current mode, the asset shelf may be available, providing quick access to assets
+for this specific mode (for example pose assets in *Pose Mode*, brush assets in *Sculpt Mode*).
+
+See :ref:`ui-region-asset_shelf` for more information.

manual/editors/image/introduction.rst

@@ -123,6 +123,15 @@ Display Channels
       Single color channel visualized as a grayscale image.
 
 
+Asset Shelf Region
+==================
+
+Depending on the current mode, the asset shelf may be available, providing quick access to assets
+for this specific mode (for example brush assets in *Paint* mode).
+
+See :ref:`ui-region-asset_shelf` for more information.
+
+
 Main View
 =========
 

manual/editors/outliner/interface.rst

@@ -20,6 +20,9 @@ It helps to narrow the list of objects so that you can find things quickly and e
    Shows all the collections and objects in the current view layer.
 :Video Sequencer:
    Lists data, images and videos, that are used by the :doc:`Video Sequencer </video_editing/index>`.
+
+.. _outliner-blender-file-mode:
+
 :Blender File:
    Lists all data in the current blend-file.
 :Data API:

manual/editors/properties_editor.rst

@@ -19,6 +19,7 @@ Tabs
 The Properties editor has several categories, which can be chosen via tabs (the icons column to its left).
 Each tab regroups properties and settings of a data type, and is documented in its own manual sections, linked below.
 
+.. _properties-tool-tab:
 
 Active Tool and Workspace Settings
 ----------------------------------

manual/files/asset_libraries/introduction.rst

@@ -75,9 +75,11 @@ Primitive assets are data-blocks that are either **linked or appended** to the c
 Examples are objects, materials, and worlds. These can be dragged from the Asset Browser into
 the scene (objects and worlds), or onto existing objects (materials).
 
-Preset assets are data-blocks that are loaded and then **applied** to something.
+Preset assets are data-blocks that are loaded and then **applied** to something or **activated**.
-An example is a pose asset. When applying the pose, the data-block is loaded
+An example is a pose asset. When applying the pose, the data-block is loaded from its blend-file,
-from its blend-file, and then the pose is applied to the active armature.
+and then the pose is applied to the active armature. Brush assets are an example of an asset type
+that is activated. They get loaded into the current file and activated for painting or sculpting,
+but don't get saved in the file.
 
 In the future, the asset type definition will be expanded;
 see :ref:`asset-libraries-future-development` for more info.
@@ -98,6 +100,8 @@ When the current blend-file is part of an asset library, you can also see its as
 The assets that are in the current file are marked with an icon; only those are editable.
 
 
+.. _asset-life-cycle:
+
 Life Cycle of an Asset
 ======================
 
@@ -120,10 +124,9 @@ When using *Mark as Asset*, an automatic preview is generated.
 If you want, you can also change or replace this with an image of your own choosing;
 use the folder button next to the preview image in the Asset Details region of the Asset Browser.
 
-For preset assets, there will be a dedicated button for the different asset types.
+For preset assets, there will be a dedicated button for the different asset types. For example for
-Currently poses are the only preset assets; use the **Create Pose Asset** button in the Action editor.
+poses there is a **Create Pose Asset** button in the Action editor. Brush assets are created by
-This will copy the pose of the selected bones into a new Action, mark it as asset,
+using **Duplicate Asset** from existing brush assets.
-and put it into the currently active asset catalog if there is an Asset Browser open.
 
 After creating the asset, make sure the current blend-file is saved in your asset library.
 Blender does not copy the asset into the asset library for you.
@@ -204,22 +207,49 @@ Included in this library are:
 
 - :doc:`Hair node groups </modeling/geometry_nodes/hair/index>`
 - :doc:`/modeling/geometry_nodes/normals/smooth_by_angle`
+- Brushes:
 
+  - :doc:`Mesh Sculpt</sculpt_paint/sculpting/brushes/index>`
+  - :doc:`Curve Sculpt</sculpt_paint/curves_sculpting/brushes/index>`
+  - :doc:`Texture Paint</sculpt_paint/texture_paint/brushes>`
+  - :doc:`Vertex Paint</sculpt_paint/vertex_paint/brushes>`
+  - :doc:`Weight Paint</sculpt_paint/weight_paint/brushes>`
+
+.. _asset-system-files:
+
+Asset System Files (`.asset.blend` Extention)
+=============================================
+
+Some types of assets can be edited without having to open a blend-file inside of an asset library.
+Blender saves these assets to libraries in special files using the `.asset.blend` extension. They
+are entirely managed by Blender's asset system, and only contain a single asset and its
+dependencies.
+
+It is still possible to save a normal file with the `.asset.blend` extension. This will then not
+be treated as an asset system file, Blender knows the difference.
+
+Asset system files have one more special characteristic: You can open, but not save them. The
+:ref:`Save As <bpy.ops.wm.save_as_mainfile>` operator can still be used to create a new file from
+them, which will then be just a normal blend-file. Thus contained assets cannot be edited without
+opening the file itself. Blender shows some clear warnings to communicate that asset system files
+cannot be changed and saved the normal way.
+
+The reason these files are special is that the asset system might need to regenerate them. Any
+additional changes done by the user might be lost then. To prevent this data-loss, these files are
+protected from user modifications.
+
+Currently, only brush assets support this feature.
 
 .. _asset-libraries-design-limitations:
 
 Design Limitations
 ==================
 
-Blender is **not allowed to write to other blend-files** than the one you have currently open.
+Blender is **not allowed to write to other blend-files** than the one you have currently open, or
-This means that to edit an asset, you have to open its blend-file.
+the special `.asset.blend` files explained above. This means that to edit an asset, you have to
-Fortunately this is only a single click away, both in the Source List region of the Asset Browser
+open its blend-file. Fortunately this is only a single click away, both in the Source List region of the Asset Browser
 and in the asset context menu.
 
-This also means that **Blender does not copy assets into the asset library** for you.
-You are responsible for placing the blend-file with the asset in an asset library directory,
-and marking the asset as such. See :ref:`asset-pushing` for more on this topic.
-
 
 .. _asset-libraries-future-development:
 
@@ -261,6 +291,10 @@ or as an add-on; the rule above applies to Blender itself, not to its add-ons.
 Asset Pushing
 -------------
 
+.. note::
+   The introduction of Brush assets in Blender 4.3 includes support for an asset pushing concept as
+   described here. This might be brought to more asset types in future.
+
 Asset **pushing** is a way of getting assets into the asset library, where you are working on a file
 and want to copy the asset from that file into the library. This is a concept that appears deceptively simple.
 In certain cases it is actually simple, but often enough it gets quite complex. For example,

manual/files/data_blocks.rst

@@ -98,10 +98,10 @@ Pack
      - |none|
      - Skeleton used to deform meshes.
        Used as data of armature objects, and by the Armature Modifier.
-   * - :doc:`Brush </sculpt_paint/brush/brush>`
+   * - :doc:`Brush </sculpt_paint/brush/index>`
      - |tick|
      - |none|
-     - Used by paint tools.
+     - Used as brush assets in sculpt and paint modes.
    * - :doc:`Camera </render/cameras>`
      - |tick|
      - |none|

manual/grease_pencil/materials/introduction.rst

@@ -58,7 +58,7 @@ to interactively preview how the material looks in the scene.
 Grease Pencil materials are data-blocks that can be :doc:`assigned </render/materials/assignment>`
 to one or more objects, and different materials can be assigned to different strokes.
 
-In Grease Pencil the :doc:`brush </grease_pencil/modes/draw/tools/index>`
+In Grease Pencil the :doc:`brush </grease_pencil/modes/draw/brushes/index>`
 settings together with the material used will define the look and feel of the final strokes.
 
 Materials slots in the :ref:`List view <ui-list-view>` also have some extra controls

manual/grease_pencil/modes/draw/brushes/draw.rst

@@ -1,15 +1,14 @@
-.. _tool-grease-pencil-draw-draw:
 
-*********
+**********
-Draw Tool
+Draw Brush
-*********
+**********
 
 .. reference::
 
    :Mode:      Draw Mode
-   :Tool:      :menuselection:`Toolbar --> Draw`
+   :Brush:     :menuselection:`Asset Shelf --> Draw`
 
-The Draw tool allows you to draw free-hand strokes.
+The Draw brush allows you to draw free-hand strokes.
 
 
 Brush Settings
@@ -284,6 +283,6 @@ Switching to the Erase Tool
 ---------------------------
 
 :kbd:`Ctrl-LMB` changes temporally to the active Erase tool.
-See :doc:`Erase Tool </grease_pencil/modes/draw/tools/erase>` for more information.
+See :doc:`Erase Tool </grease_pencil/modes/draw/brushes/erase>` for more information.
 
 You can also use :kbd:`B` to delete all the points in the selected drawing area.

manual/grease_pencil/modes/draw/brushes/erase.rst

@@ -1,15 +1,14 @@
-.. _tool-grease-pencil-draw-erase:
 
-**********
+***********
-Erase Tool
+Erase Brush
-**********
+***********
 
 .. reference::
 
    :Mode:      Draw Mode
-   :Tool:      :menuselection:`Toolbar --> Erase`
+   :Brush:     :menuselection:`Asset Shelf --> Erase`
 
-The Erase tool erase already drawn strokes.
+The Erase brush erases already drawn strokes.
 
 
 Brush Settings

manual/grease_pencil/modes/draw/brushes/fill.rst

@@ -1,15 +1,14 @@
-.. _tool-grease-pencil-draw-fill:
 
-*********
+**********
-Fill Tool
+Fill Brush
-*********
+**********
 
 .. reference::
 
    :Mode:      Draw Mode
-   :Tool:      :menuselection:`Toolbar --> Fill`
+   :Brush:      :menuselection:`Asset Shelf --> Fill`
 
-The Fill tool is used to automatically fill closed strokes areas.
+The Fill brush is used to automatically fill closed strokes areas.
 
 
 Brush Settings
@@ -248,4 +247,4 @@ Switch to Draw Tool
 
 Use :kbd:`Ctrl-LMB` to change temporary to the active draw tool.
 For example to manually cover small areas difficult to reach for the Fill tool.
-See :doc:`Draw Tool </grease_pencil/modes/draw/tools/draw>` for more information.
+See :doc:`Draw Tool </grease_pencil/modes/draw/brushes/draw>` for more information.

manual/grease_pencil/modes/draw/brushes/index.rst

@@ -0,0 +1,13 @@
+
+#########
+  Brushes
+#########
+
+.. toctree::
+   :maxdepth: 2
+
+   overview.rst
+   draw.rst
+   fill.rst
+   erase.rst
+   tint.rst

manual/grease_pencil/modes/draw/brushes/overview.rst

@@ -0,0 +1,19 @@
+
+********
+Overview
+********
+
+There are a number of brushes for draw mode bundled in the *Essentials* asset library. This is an
+overview of all of them.
+
+:doc:`Draw <draw>`
+   Draw free-hand strokes.
+
+:doc:`Fill <fill>`
+   Automatic fill closed strokes areas.
+
+:doc:`Erase <erase>`
+   Erase strokes.
+
+:doc:`Tint <tint>`
+   Colorize stroke points.

manual/grease_pencil/modes/draw/brushes/tint.rst

@@ -1,15 +1,14 @@
-.. _tool-grease-pencil-draw-tint:
 
-*********
+**********
-Tint Tool
+Tint Brush
-*********
+**********
 
 .. reference::
 
    :Mode:      Draw Mode
-   :Tool:      :menuselection:`Toolbar --> Tint`
+   :Brush:     :menuselection:`Brush --> Tint`
 
-The Tint tool allows you to paint onto strokes point mixing the material base color with a selected color.
+The Tint brush allows you to paint onto strokes point mixing the material base color with a selected color.
 
 
 Brush Settings

manual/grease_pencil/modes/draw/index.rst

@@ -7,6 +7,7 @@
    :maxdepth: 2
 
    introduction.rst
+   brushes/index.rst
    tools.rst
    tools/index.rst
    tool_settings/index.rst

manual/grease_pencil/modes/draw/tools.rst

@@ -10,17 +10,8 @@ Drawing Tools
 Cursor
    Change the location of the 3D Cursor.
 
-:ref:`Draw <tool-grease-pencil-draw-draw>`
+:doc:`Brush </grease_pencil/modes/draw/tools/brush>`
-   Draw free-hand strokes.
+   Tool to use for any of the drawing brushes, see :doc:`/grease_pencil/modes/draw/brushes/overview`.
-
-:ref:`Fill <tool-grease-pencil-draw-fill>`
-   Automatic fill closed strokes areas.
-
-:ref:`Erase <tool-grease-pencil-draw-erase>`
-   Erase strokes.
-
-:ref:`Tint <tool-grease-pencil-draw-tint>`
-   Colorize stroke points.
 
 :ref:`Cutter <tool-grease-pencil-draw-cutter>`
    Cut strokes in between others.

manual/grease_pencil/modes/draw/tools/arc.rst

@@ -17,7 +17,7 @@ Tool Settings
 
 You can configure the brush main settings exposed on the Tool Settings for convenience.
 For the draw brushes configuration and settings see:
-:doc:`Draw Brush </grease_pencil/modes/draw/tools/draw>`.
+:doc:`Draw Brush </grease_pencil/modes/draw/brushes/draw>`.
 
 Subdivisions
    The number of stroke points between each stroke edge.

manual/grease_pencil/modes/draw/tools/box.rst

@@ -17,7 +17,7 @@ Tool Settings
 
 You can configure the brush main settings exposed on the Tool Settings for convenience.
 For the draw brushes configuration and settings see:
-:doc:`Draw Brush </grease_pencil/modes/draw/tools/draw>`.
+:doc:`Draw Brush </grease_pencil/modes/draw/brushes/draw>`.
 
 Subdivisions
    The number of stroke points between each stroke edge.

manual/grease_pencil/modes/draw/tools/brush.rst

@@ -0,0 +1,24 @@
+
+*****
+Brush
+*****
+
+.. reference::
+
+   :Mode:      Draw Mode
+   :Tool:      :menuselection:`Toolbar --> Brush`
+
+
+Tool to use for any of the Grease Pencil *Draw* mode brushes. Activating a brush from an asset
+shelf or brush selector will also activate this tool for convenience.
+
+See :doc:`brushes </grease_pencil/modes/draw/brushes/index>` (or the
+:doc:`overview </grease_pencil/modes/draw/brushes/overview>`) for a detailed list of all brushes
+and their options.
+
+Tool Settings
+=============
+
+Default Eraser Brush
+   Select a brush to use as eraser for quickly alternating with the main brush using
+   :kbd:`Ctrl-LMB`.

manual/grease_pencil/modes/draw/tools/circle.rst

@@ -17,7 +17,7 @@ Tool Settings
 
 You can configure the brush main settings exposed on the Tool Settings for convenience.
 For the draw brushes configuration and settings see:
-:doc:`Draw Brush </grease_pencil/modes/draw/tools/draw>`.
+:doc:`Draw Brush </grease_pencil/modes/draw/brushes/draw>`.
 
 Subdivisions
    The number of stroke points between each stroke edge.

manual/grease_pencil/modes/draw/tools/curve.rst

@@ -17,7 +17,7 @@ Tool Settings
 
 You can configure the brush main settings exposed on the Tool Settings for convenience.
 For the draw brushes configuration and settings see:
-:doc:`Draw Brush </grease_pencil/modes/draw/tools/draw>`.
+:doc:`Draw Brush </grease_pencil/modes/draw/brushes/draw>`.
 
 Subdivisions
    The number of stroke points between each stroke edge.

manual/grease_pencil/modes/draw/tools/index.rst

@@ -7,10 +7,7 @@
 .. toctree::
    :maxdepth: 2
 
-   draw.rst
+   brush.rst
-   fill.rst
-   erase.rst
-   tint.rst
    cutter.rst
    eyedropper.rst
    line.rst

manual/grease_pencil/modes/draw/tools/line.rst

@@ -17,7 +17,7 @@ Tool Settings
 
 You can configure the brush main settings exposed on the Tool Settings for convenience.
 For the draw brushes configuration and settings see:
-:doc:`Draw Brush </grease_pencil/modes/draw/tools/draw>`.
+:doc:`Draw Brush </grease_pencil/modes/draw/brushes/draw>`.
 
 Subdivisions
    The number of stroke points between each stroke edge.

manual/grease_pencil/modes/draw/tools/polyline.rst

@@ -17,7 +17,7 @@ Tool Settings
 
 You can configure the brush main settings exposed on the Tool Settings for convenience.
 For the draw brushes configuration and settings see:
-:doc:`Draw Brush </grease_pencil/modes/draw/tools/draw>`.
+:doc:`Draw Brush </grease_pencil/modes/draw/brushes/draw>`.
 
 Subdivisions
    The number of stroke points between each stroke edge.

manual/grease_pencil/modes/edit/grease_pencil_menu.rst

@@ -217,7 +217,7 @@ Boundary Strokes
    :Menu:      :menuselection:`Grease Pencil --> Clean Up --> Boundary Strokes`
 
 Removes boundary strokes used by the *Fill* tool.
-See :doc:`Fill tool </grease_pencil/modes/draw/tools/fill>` for more information.
+See :doc:`Fill tool </grease_pencil/modes/draw/brushes/fill>` for more information.
 
 Mode
    Active Frame Only

manual/grease_pencil/modes/sculpting/brushes.rst

@@ -0,0 +1,46 @@
+
+*****************
+Sculpting Brushes
+*****************
+
+Brushes for Grease Pencil *Sculpt* mode bundled in the *Essentials* library.
+See :doc:`Brush </grease_pencil/modes/sculpting/tool_settings/brush>` for more information.
+
+.. figure:: /images/grease-pencil_modes_sculpting_tools_brushes.png
+   :align: right
+
+Smooth Stroke
+   Eliminates irregularities in the area of the drawing
+   within the brush's influence by smoothing the positions of the points.
+
+Thickness Stroke
+   Increase or decrease the points thickness in the area of the drawing
+   within the brush's influence.
+
+Strength Stroke
+   Increase or decrease the points transparency (alpha) in the area of the drawing
+   within the brush's influence.
+
+Randomize Stroke
+   Add noise to the strokes in the area of the drawing
+   within the brush's influence by moving points location in a random way.
+
+Grab Stroke
+   Used to drag a group of points around. Unlike the other brushes,
+   Grab does not modify different points as the brush is dragged across the model.
+   Instead, Grab selects a group of points on mouse-down, and pulls them to follow the mouse.
+   The effect is similar to moving a group of points in Edit Mode with Proportional Editing enabled.
+
+Pull Stroke
+   Moves points in the direction of the brush stroke.
+
+Twist Stroke
+   Twist the points in counter-clockwise (CCW) or Clockwise (CW) rotation.
+
+Pinch Stroke
+   Pulls points towards the center of the brush.
+   The inverse setting is Inflate, in which points are pushed away from the center of the brush.
+
+Clone Stroke
+   Adds copies of the strokes in the clipboard in the center of the brush.
+   You have to copy the selected strokes you want into the clipboard with :kbd:`Ctrl-C` before using the tool.

manual/grease_pencil/modes/sculpting/index.rst

@@ -7,5 +7,6 @@
    :maxdepth: 2
 
    introduction.rst
+   brushes.rst
    tools.rst
    tool_settings/brush.rst

manual/grease_pencil/modes/sculpting/tools.rst

@@ -4,48 +4,8 @@
 Sculpting Tools
 ***************
 
-For Grease Pencil sculpt modes each brush type is exposed as a tool,
+Brush
-the brush can be changed in the Tool Settings.
+   Tool to use for any of the sculpting :doc:`brushes <brushes>`.
-See :doc:`Brush </grease_pencil/modes/sculpting/tool_settings/brush>` for more information.
-
-.. figure:: /images/grease-pencil_modes_sculpting_tools_brushes.png
-   :align: right
-
-Smooth
-   Eliminates irregularities in the area of the drawing
-   within the brush's influence by smoothing the positions of the points.
-
-Thickness
-   Increase or decrease the points thickness in the area of the drawing
-   within the brush's influence.
-
-Strength
-   Increase or decrease the points transparency (alpha) in the area of the drawing
-   within the brush's influence.
-
-Randomize
-   Add noise to the strokes in the area of the drawing
-   within the brush's influence by moving points location in a random way.
-
-Grab
-   Used to drag a group of points around. Unlike the other brushes,
-   Grab does not modify different points as the brush is dragged across the model.
-   Instead, Grab selects a group of points on mouse-down, and pulls them to follow the mouse.
-   The effect is similar to moving a group of points in Edit Mode with Proportional Editing enabled.
-
-Push
-   Moves points in the direction of the brush stroke.
-
-Twist
-   Twist the points in counter-clockwise (CCW) or Clockwise (CW) rotation.
-
-Pinch/Inflate
-   Pulls points towards the center of the brush.
-   The inverse setting is Inflate, in which points are pushed away from the center of the brush.
-
-Clone
-   Adds copies of the strokes in the clipboard in the center of the brush.
-   You have to copy the selected strokes you want into the clipboard with :kbd:`Ctrl-C` before using the tool.
 
 :ref:`Annotate <tool-annotate-freehand>`
    Draw free-hand annotation.

manual/grease_pencil/modes/vertex_paint/brushes.rst

@@ -0,0 +1,23 @@
+
+********************
+Vertex Paint Brushes
+********************
+
+Brushes for Grease Pencil *Vertex Paint* mode bundled in the *Essentials* library.
+
+Paint Point Color
+   Paints a specified color over the object.
+
+Blur Point Color
+   Smooths out the colors of adjacent vertices. In this mode the Color
+   Value is ignored. The strength defines how much the colors are blurred.
+
+Average Point Color
+   Smooths color by painting the average resulting color from all colors under the brush.
+
+Smear Point Color
+   Smudges colors by grabbing the colors under the brush and "dragging" them.
+   This can be imagined as a finger painting tool.
+
+Replace Point Color
+   Change the color only to the stroke points that already have a color applied.

manual/grease_pencil/modes/vertex_paint/index.rst

@@ -7,6 +7,7 @@
    :maxdepth: 2
 
    introduction.rst
+   brushes.rst
    tools.rst
    tool_settings/brush.rst
    editing.rst

manual/grease_pencil/modes/vertex_paint/tools.rst

@@ -6,22 +6,8 @@ Vertex Paint Tools
 .. figure:: /images/grease-pencil_modes_vertex-paint_tools_brushes.png
    :align: right
 
-Draw
+Brush
-   Paints a specified color over the object.
+   Tool to use for any of the vertex paint :doc:`brushes <brushes>`.
-
-Blur
-   Smooths out the colors of adjacent vertices. In this mode the Color
-   Value is ignored. The strength defines how much the colors are blurred.
-
-Average
-   Smooths color by painting the average resulting color from all colors under the brush.
-
-Smear
-   Smudges colors by grabbing the colors under the brush and "dragging" them.
-   This can be imagined as a finger painting tool.
-
-Replace
-   Change the color only to the stroke points that already have a color applied.
 
 :ref:`Annotate <tool-annotate-freehand>`
    Draw free-hand annotation.

manual/grease_pencil/modes/weight_paint/brushes.rst

@@ -0,0 +1,20 @@
+
+********************
+Weight Paint Brushes
+********************
+
+Brushes for Grease Pencil *Weight Paint* mode bundled in the *Essentials* library.
+
+Paint Point Weight
+   Paints a specified weight over the strokes.
+
+Blur Point Weight
+   Smooths out the weighting of adjacent points. In this mode the Weight
+   Value is ignored. The strength defines how much the smoothing is applied.
+
+Average Point Weight
+   Smooths weights by painting the average resulting weight from all weights under the brush.
+
+Smear Point Weight
+   Smudges weights by grabbing the weights under the brush and "dragging" them.
+   This can be imagined as a finger painting tool.

manual/grease_pencil/modes/weight_paint/index.rst

@@ -7,6 +7,7 @@
    :maxdepth: 2
 
    introduction.rst
+   brushes.rst
    tools.rst
    tool_settings/index.rst
    weights_menu.rst

manual/grease_pencil/modes/weight_paint/tools.rst

@@ -11,19 +11,8 @@ See :doc:`Brush </grease_pencil/modes/weight_paint/tool_settings/brush>` for mor
 .. figure:: /images/grease-pencil_modes_weight-paint_tools_brushes.png
    :align: right
 
-Draw
+Brush
-   Paints a specified weight over the strokes.
+   Tool to use for any of the weight paint :doc:`brushes <brushes>`.
-
-Blur
-   Smooths out the weighting of adjacent points. In this mode the Weight
-   Value is ignored. The strength defines how much the smoothing is applied.
-
-Average
-   Smooths weights by painting the average resulting weight from all weights under the brush.
-
-Smear
-   Smudges weights by grabbing the weights under the brush and "dragging" them.
-   This can be imagined as a finger painting tool.
 
 :ref:`Annotate <tool-annotate-freehand>`
    Draw free-hand annotation.

manual/interface/window_system/regions.rst

@@ -83,6 +83,8 @@ The :ref:`Toolbar <ui-region-toolbar>` (on the left side of the editor area)
 contains a set of interactive tools. :kbd:`T` toggles the visibility of the Toolbar.
 
 
+.. _ui-region-tool-settings:
+
 Tool Settings
 =============
 

manual/sculpt_paint/brush/brush.rst

@@ -1,51 +0,0 @@
-.. _bpy.types.Brush:
-.. _bpy.ops.brush:
-.. _bpy.types.UnifiedPaintSettings:
-
-*******
-Brushes
-*******
-
-.. reference::
-
-   :Mode:      Sculpt Mode
-   :Panel:     :menuselection:`Sidebar --> Tools --> Brushes`
-
-For painting/sculpting modes each brush type is exposed as a tool in the toolbar.
-The brush on the other hand is a saved preset of all the brush settings, including a name and thumbnail.
-
-All these settings can be found and changed here in the tool setting (brush, texture, stroke, falloff & cursor).
-
-.. figure:: /images/sculpt-paint_brush_brush_data-block-menu.png
-   :align: right
-
-   Brush panel in the tool settings.
-
-Brushes
-   Clicking on the brush thumbnail will open the :ref:`ui-data-block` to select a brush.
-
-   Add Brush (Duplicate icon)
-      When you add a brush, the new brush is a duplicate of the current one.
-   Fake User (Shield icon)
-      Enabling this button will ensure that the brush will not be deleted,
-      even if it is not used by any tool.
-   Unlink Data-Block (Cross icon)
-      Unassign the brush from the active tool.
-      Hold :kbd:`Shift` to remove the brush from all users,
-      so it will be deleted upon reloading the file or purging orphan data.
-
-   Brush Specials (Arrow button)
-      Enabled Modes
-         Enable the brush to be used in different (even multiple) modes.
-         For example, the exact same brushes are used in both Weight Paint
-         and Vertex Paint mode.
-      Tool Selection
-         Transfer the brush preset to be used by a different brush type.
-      Reset Brush
-         Reset all brush settings to the default values of the current brush type.
-
-.. _bpy.types.Brush.use_custom_icon:
-.. _bpy.types.Brush.icon_filepath:
-
-   Custom Icon
-      Define a custom brush thumbnail from an image file.

manual/sculpt_paint/brush/brush_management.rst

@@ -0,0 +1,106 @@
+**************
+Manage Brushes
+**************
+
+Brush assets are stored in :doc:`asset libraries </files/asset_libraries/introduction>` to make them accessible from
+any Blender session. There are two ways of managing brush assets:
+
+- Using :ref:`asset operators <brush-management-utility-operators>`: Create and update brush assets
+  using utility operators from any Blender file. Storage is managed by Blender. Convenient for
+  simple "on the fly" management of personal brush
+  asset libraries.
+- Using :ref:`manual storage <brush-management-manual>`: Create and update brush assets by opening
+  blend files within asset libraries, and managing brush asset data-blocks in there. Useful for
+  careful curation of asset libraries, especially to prepare them for sharing with others.
+
+.. _brush-management-utility-operators:
+
+Asset Operators
+===============
+
+Brushes can be managed through a few operators that let Blender handle the act of saving and
+updating the brushes in asset libraries for you. Assets managed this way will be saved in special
+:ref:`asset system files <asset-system-files>` using a `.asset.blend` file extension.
+
+.. note::
+   Note that only brush assets created via :ref:`Duplicate Asset <bpy.ops.brush.asset_save_as>`
+   can be edited further using these asset operators. For others, these operations will be grayed
+   out, and :ref:`manual management <brush-management-manual>` is necessary.
+
+   Brushes from the *Essentials* asset library cannot be edited.
+
+.. reference::
+
+   :Mode:      All Paint Modes
+   :Panel:     :menuselection:`Sidebar --> Tool --> Brush Asset`
+               :menuselection:`Properties --> Tool --> Brush Asset`
+   :Menu:      :menuselection:`Asset Shelf --> Context Menu`
+
+.. figure:: /images/sculpt-paint_brush_brush-management_asset-operators.png
+   :align: right
+   :width: 300
+
+   Brush Asset panel in the Sidebar showing asset operators.
+
+.. _bpy.ops.brush.asset_save_as:
+
+Duplicate Asset... (Duplicate icon)
+   Creates a copy of the currently active brush as asset, and activates it. A popup is spawned to input some settings
+   to use:
+
+   Name
+      A custom name to use for the new brush.
+   Library
+      Choose an Asset Library to store the new brush asset in. The available asset libraries are configured
+      :ref:`in the Preferences <bpy.types.UserAssetLibrary>`.
+   Catalog
+      Choose an :doc:`Asset Catalog </files/asset_libraries/catalogs>` to assign the brush asset to. Entering a
+      non-existent name/path will create a new catalog accordingly.
+
+Delete Asset
+   Permanently remove this brush asset from the Asset Library it is stored in. This cannot be undone, so a popup will
+   ask for confirmation.
+Edit Metadata...
+   Spawns a popup to change some of the available :ref:`asset metadata <editing-asset-metadata>` fields:
+
+   Catalog
+      Choose an :doc:`Asset Catalog </files/asset_libraries/catalogs>` to assign the brush asset to. Entering a
+      non-existent name/path will create a new catalog accordingly.
+   Author
+      See :ref:`Asset Author <bpy.types.AssetMetaData.description>`.
+   Description
+      See :ref:`Asset Description <bpy.types.AssetMetaData.description>`.
+Edit Preview Image...
+   Opens a window with the File Browser to select an image for the asset preview.
+Update Asset
+   Saves any changes made to the active brush to the asset library.
+Revert to Asset
+   Discards any unsaved changes made to the brush asset.
+
+
+.. _brush-management-manual:
+
+Manual Storage
+==============
+
+.. seealso::
+   :ref:`asset-life-cycle`
+      Complete description of the manual asset create, edit, share and use workflow.
+
+It is also possible to manually manage brushes in blend-files like any other asset data-block. By
+marking brushes as assets and saving the file in an asset library, they become available from any
+Blender session. This gives full control over how assets are stored, and is particularly useful for
+curating asset libraries that can be shared with others.
+
+.. figure:: /images/sculpt-paint_brush_brush-management_mark-as-asset.png
+   :align: right
+   :width: 350
+
+   The *Mark as Asset* operator used on a brush in the Outliner.
+
+Brushes can be imported as normal data-blocks from other files (including from `.asset.blend` files
+from an asset library) through :ref:`appending <bpy.ops.wm.append>`. In the
+:ref:`Blender File <outliner-blender-file-mode>` mode of the Outliner, the brush will be listed
+under *Brushes*. Right-click the brush and select *Mark as Asset*. By saving the file inside of
+an asset library directory, the asset becomes available from all Blender sessions. If necessary,
+configure an asset library directory in the Preferences.

manual/sculpt_paint/brush/brush_settings.rst

@@ -161,7 +161,7 @@ Deformation Target
 
    :Geometry: Deform the geometry directly.
    :Cloth Simulation:
-      Deform the mesh while a :doc:`cloth simulation </sculpt_paint/sculpting/tools/cloth>`
+      Deform the mesh while a :doc:`cloth simulation </sculpt_paint/sculpting/brushes/cloth>`
       is applied to it at the same time.
 
 
@@ -170,6 +170,25 @@ Deformation Target
 Advanced
 ========
 
+.. _sculpt-tool-settings-brush-type:
+
+Brush Type
+   Defines the basic behavior and the available settings. Through the settings of
+   a brush type, brushes can be created that produce vastly different effects.
+
+   The *Essentials* asset library contains brushes for each of the brush types. Their preview image
+   and description should give a good idea of the effect the brush produces, with the particular
+   combination of brush type and settings. Because of this, they are usually the more useful starting
+   point for custom brushes than the mere brush type is, which is why the brush type is part of the
+   *Advanced* brush settings.
+
+   types.
+
+   - :doc:`Sculpt </sculpt_paint/sculpting/brushes/brush_types>`
+   - :doc:`Vertex Paint </sculpt_paint/vertex_paint/brushes>`
+   - :doc:`Weight Paint </sculpt_paint/weight_paint/brushes>`
+   - :doc:`Texture Paint </sculpt_paint/texture_paint/brushes>`
+
 Accumulate
    Causes stroke dabs to accumulate on top of each other.
 

manual/sculpt_paint/brush/index.rst

@@ -1,12 +1,13 @@
 
 #########
-  Brush
+  Brushes
 #########
 
 .. toctree::
    :maxdepth: 2
 
    introduction.rst
+   brush_management.rst
 
 
 Brush Settings
@@ -15,7 +16,6 @@ Brush Settings
 .. toctree::
    :maxdepth: 1
 
-   brush.rst
    brush_settings.rst
    texture.rst
    stroke.rst

manual/sculpt_paint/brush/introduction.rst

@@ -1,22 +1,48 @@
+.. _bpy.types.Brush:
+.. _bpy.ops.brush:
+.. _bpy.types.UnifiedPaintSettings:
 
 ************
 Introduction
 ************
 
-.. figure:: /images/sculpt-paint_brush_introduction_brush-circle.png
+Brushes are the main way of interacting with any painting and sculpting mode. By click & dragging in the 3D Viewport
-   :align: center
+(or the Image Editor when using :doc:`Texture Paint </sculpt_paint/texture_paint/index>`), the active brush creates a
+:doc:`stroke </sculpt_paint/brush/stroke>` with a certain effect, depending on the used brush settings. Brushes are
+used as brush assets and stored in asset libraries, which makes it easy to reuse and share them. Typically they have a
+preview image and a name that indicate the effect they create.
 
-   Brush cursor.
-
-The brush is the main way of interacting with any painting and sculpting mode.
-While click & dragging in the 3D Viewport it will create a :doc:`stroke </sculpt_paint/brush/stroke>`
-and apply an effect depending on various brush settings.
 
 .. tip::
 
    It is highly recommended to use a :ref:`Graphics Tablet <hardware-tablet>`
    for a better brush feel and additional features.
 
+.. _brush-introduction-accessing-brushes:
+
+Accessing Brushes
+=================
+
+In modes that use painting or sculpting functionality, the :ref:`Asset Shelf <ui-region-asset_shelf>` of the 3D
+Viewport and Image Editor displays brush assets that can be used in that mode. Clicking a brush asset will activate the
+Brush Tool if necessary, with the clicked brush set.
+
+.. figure:: /images/sculpt-paint_brush_introduction_brush-asset-shelf.png
+   :align: center
+
+   The Asset Shelf of the 3D Viewport, providing access to brush assets.
+
+This asset shelf is also available as popup in the :ref:`Tool Settings <ui-region-tool-settings>`, the
+:ref:`Sidebar<ui-region-sidebar>`, :doc:`Properties </editors/properties_editor>` and using a shortcut.
+
+.. reference::
+
+   :Mode:      All Paint Modes
+   :Header:    :menuselection:`Tool Settings`
+   :Panel:     :menuselection:`Sidebar --> Tool --> Brush Asset`,
+               :menuselection:`Properties --> Tool --> Brush Asset`
+   :Shortcut:  :kbd:`Shift-Spacebar`
+
 
 Brush Control
 =============
@@ -33,3 +59,37 @@ Move the mouse right or left to increase/reduce the value
 Finally confirm (:kbd:`LMB`, :kbd:`Return`) or cancel (:kbd:`RMB`, :kbd:`Esc`).
 
 You can also invert the brush direction/effect by holding :kbd:`Ctrl`.
+
+
+Custom Brush Shortcuts
+======================
+
+To give a brush a shortcut, simply right click it in the asset shelf or brush selector popup, and
+select *Assign Shortcut*. To modify or remove an existing shortcut, select *Change Shortcut* or
+*Remove Shortcut* accordingly.
+
+
+Brush Assets
+============
+
+Brushes are used as assets, and stored in :doc:`asset libraries </files/asset_libraries/introduction>`. This makes the
+brushes shared across project files. All available brush assets can be displayed in the
+:doc:`Asset Browser </editors/asset_browser>`, which also provides ways to organize them.
+
+Blender comes bundled with a number of brushes in the `Essentials` asset library. These can be customized into all
+kinds of custom brushes by duplicating them (see :doc:`Brush Editing<brush_management>`).
+
+While it's possible to have brush data-blocks that are local to the file and not marked as assets, such brushes cannot
+be activated for actual painting or sculpting. Use the `Mark as Asset` operator to make them brush assets that can be
+activated.
+
+Brush Tool
+==========
+
+.. figure:: /images/sculpt-paint_brush_introduction_brush-tool.png
+   :align: right
+
+   The *Brush* tool.
+
+Painting or sculpting with brushes requires the brush tool to be active. Activating a brush from an
+asset shelf or brush selector also activates the brush tool for convenience.

manual/sculpt_paint/brush/texture.rst

@@ -146,5 +146,5 @@ Vector Displacement :guilabel:`Sculpt Mode`
 
    .. note::
 
-      This is only supported for the :doc:`Draw </sculpt_paint/sculpting/tools/draw>` brush
+      This is only supported for the :doc:`Draw </sculpt_paint/sculpting/brushes/draw>` brush
       with :ref:`Area Plane <bpy.types.BrushTextureSlot.map_mode>` mapping enabled.

manual/sculpt_paint/curves_sculpting/brushes/index.rst

@@ -1,8 +1,10 @@
 
 #########
-  Tools
+  Brushes
 #########
 
+Brushes for Curves *Sculpt Mode* bundled in the *Essentials* library.
+
 .. toctree::
    :maxdepth: 1
 
@@ -16,4 +18,4 @@
    pinch_curves.rst
    puff_curves.rst
    smooth_curves.rst
-   slide_curves.rst
+   slide_curves.rst

manual/sculpt_paint/curves_sculpting/index.rst

@@ -9,5 +9,5 @@
    :maxdepth: 2
 
    introduction.rst
-   tools/index.rst
+   brushes/index.rst
    tools_settings.rst

manual/sculpt_paint/curves_sculpting/introduction.rst

@@ -7,7 +7,7 @@ Introduction
 It is commonly used for hair grooming, but can be used with all kinds of curves.
 
 The curves' surface object plays an important role in many curves sculpting brushes.
-Most brushes such as :doc:`Add Curves </sculpt_paint/curves_sculpting/tools/add_curves>`
+Most brushes such as :doc:`Add Curves </sculpt_paint/curves_sculpting/brushes/add_curves>`
 require the surface to be set already.
 
 .. note::

manual/sculpt_paint/sculpting/brushes/blob.rst

@@ -6,9 +6,9 @@ Blob
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Blob`
+   :Brush:     :menuselection:`Asset Shelf --> Blob`
 
-Similar to :doc:`Draw </sculpt_paint/sculpting/tools/clay>`,
+Similar to :doc:`Draw </sculpt_paint/sculpting/brushes/clay>`,
 but vertices are pushed outwards like an inverted pinching effect.
 This will lead to a more consistent spherical curvature and thickening of strokes.
 

manual/sculpt_paint/sculpting/brushes/boundary.rst

@@ -6,9 +6,9 @@ Boundary
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Boundary`
+   :Brush:     :menuselection:`Asset Shelf --> Boundary`
 
-Similar to the :doc:`Pose </sculpt_paint/sculpting/tools/pose>` brush
+Similar to the :doc:`Pose </sculpt_paint/sculpting/brushes/pose>` brush
 but deforms the open boundaries of a mesh.
 The tool detects the mesh boundary closest to the active vertex and
 propagates the deformation using the brush :doc:`Falloff </sculpt_paint/brush/falloff>` into the mesh.
@@ -61,16 +61,16 @@ Deformation
       Moves/extends the mesh boundary in the local X direction.
       Useful for extending the boundaries along the surface.
    :Inflate:
-      Works similar to the :doc:`Inflate </sculpt_paint/sculpting/tools/inflate>` tool but,
+      Works similar to the :doc:`Inflate </sculpt_paint/sculpting/brushes/inflate>` tool but,
       the vertices that are inflated are constrained to the mesh boundary.
    :Grab:
-      Works similar to the :doc:`Grab </sculpt_paint/sculpting/tools/grab>` tool but,
+      Works similar to the :doc:`Grab </sculpt_paint/sculpting/brushes/grab>` tool but,
       the vertices that are grabbed are constrained to the mesh boundary.
    :Twist:
       Rotates the active boundary around the local Z axis.
       Useful for creating folds like on a skirt.
    :Smooth:
-      Works similar to the :doc:`Grab </sculpt_paint/sculpting/tools/smooth>` tool but,
+      Works similar to the :doc:`Grab </sculpt_paint/sculpting/brushes/smooth>` tool but,
       the vertices that are smoothed are constrained to the mesh boundary.
 
 .. _bpy.types.Brush.boundary_falloff_type:

manual/sculpt_paint/sculpting/brushes/brush_types.rst

@@ -0,0 +1,226 @@
+
+
+***********
+Brush Types
+***********
+
+See :ref:`Brush Type <sculpt-tool-settings-brush-type>`.
+
+Available brush types are listed here, together with links to the *Essentials* library brushes
+using them.
+
+Add/Subtract Brushes
+====================
+
+.. figure:: /images/sculpt-paint_sculpting_brushes_overview-add-substract.png
+   :align: right
+   :width: 250
+
+These brush types generally push vertices outwards and inwards.
+
+Draw
+   Brushes: :doc:`draw`
+
+   The standard brush for pushing vertices inwards and outwards from the surface direction.
+
+Draw Sharp
+   Brushes: :doc:`draw_sharp`
+
+   Same as *Draw* but with a much sharper :doc:`Falloff </sculpt_paint/brush/falloff>`.
+   Useful for creating creases and sharp angles.
+
+Clay
+   Brushes: :doc:`clay`
+
+   Similar to the *Draw* brush but with a flattening effect and subtle smoothing.
+   Useful for polishing and building volumes.
+
+Clay Strips
+   Brushes: :doc:`clay_strips`
+
+   The same as the *Clay* brush, but more aggressive with a square falloff.
+   A common standard for building rough volumes.
+
+Layer
+   Brushes: :doc:`layer`
+
+   Draw with a fixed height. Useful for adding flat layers to a surface.
+
+Inflate
+   Brushes: :doc:`inflate`
+
+   Moves the mesh in multiple direction. Useful for inflating or shrinking surfaces and volumes.
+
+Blob
+   Brushes: :doc:`blob`
+
+   Magnifies the mesh as you draw. Useful for an additional inflation effect on the stroke.
+
+Crease
+   Brushes: :doc:`crease`
+
+   Same as *Blob* but with a pinching effect. Useful for creating and polishing sharp creases.
+
+
+Contrast Brushes
+================
+
+.. figure:: /images/sculpt-paint_sculpting_brushes_overview-contrast.png
+   :align: right
+   :width: 250
+
+Recognizable by their red icon and cursor.
+These brushes generally flatten or heighten the contrast of the surface.
+
+Smooth
+   Brushes: :doc:`smooth`
+
+   Smooths out irregularities in the surface and shrinks volumes by averaging the vertices positions.
+   An essential brush that is frequently used.
+
+Flatten
+   Brushes: :doc:`flatten`
+
+   Pushes vertices to an average height to create a flat plateau.
+
+Fill
+   Brushes: :doc:`fill`
+
+   Pushes surfaces outwards. Useful for filling in holes and crevices.
+
+Scrape
+   Brushes: :doc:`scrape`
+
+   Pushes surfaces inwards. This is the most common brush for flattening meshes.
+
+Multi-plane Scrape
+   Brushes: :doc:`multiplane_scrape`
+
+   Scrapes the mesh with two angled planes at the same time, producing a sharp edge between them.
+
+
+Transform Brushes
+=================
+
+.. figure:: /images/sculpt-paint_sculpting_brushes_overview-transform.png
+   :align: right
+   :width: 250
+
+Recognizable by their yellow icon and cursor.
+These brushes generally move, pinch and magnify the mesh.
+
+Pinch
+   Brushes: :doc:`pinch`
+
+   Pulls vertices towards the center of the brush. Useful for polishing angles and creases.
+
+Grab
+   Brushes: :doc:`grab`
+
+   Moves vertices along with the mouse. An essential brush for building shapes and adjusting proportions.
+
+Elastic Deform
+   Brushes: :doc:`elastic_deform`
+
+   Used to simulate realistic deformations such as grabbing or twisting of :term:`Elastic` objects.
+
+Snake Hook
+   Brushes: :doc:`snake_hook`
+
+   Pulls vertices along with the stroke to create long, snake-like forms.
+
+Thumb
+   Brushes: :doc:`thumb`
+
+   Same as *Grab* but moves vertices along the surface direction. Useful for preserving specific surfaces.
+
+Pose
+   Brushes: :doc:`pose`
+
+   Simulating an armature-like deformations. Useful for quick posing and transformations.
+
+Nudge
+   Brushes: :doc:`nudge`
+
+   Similar as *Thumb* but dynamically picks up vertices like the *Snake Hook*.
+   Useful for nudging something along the mesh surface.
+
+Rotate
+   Brushes: :doc:`twist`
+
+   Rotates vertices within the brush in the direction mouse.
+
+Slide Relax
+   Brushes: :doc:`slide_relax`
+
+   Slides the topology of the mesh in the direction of the stroke
+   while preserving the geometrical shape of the mesh.
+   Also useful for redistributing topology where it is needed.
+
+Boundary
+   Brushes: :doc:`boundary`
+
+   Transform mesh boundaries specifically with various deformations.
+
+
+Utility Brushes
+===============
+
+.. figure:: /images/sculpt-paint_sculpting_brushes_overview-utilities.png
+   :align: right
+   :width: 250
+
+No clear color assignment.
+These brushes are general purpose brushes or specific.
+
+Cloth
+   Brushes: :doc:`cloth`
+
+   Simulates cloth to create folds and draping, which can be sculpted further.
+
+Simplify
+   Brushes: :doc:`density`
+
+   Cleans up geometry by collapsing short edges.
+
+Mask
+   Brushes: :doc:`mask`
+
+   Paints a selection on parts of the mesh to be unaffected by other brushes.
+
+Draw Face Sets
+   Brushes: :doc:`draw_facesets`
+
+   Paint new or extend existing face sets.
+
+Multires Displacement Eraser
+   Brushes: :doc:`multires_displacement_eraser`
+
+   Remove displacement information on a Multiresolution modifier.
+
+Multires Displacement Smear
+   Brushes: :doc:`multires_displacement_smear`
+
+   Smear displacement information on a Multiresolution modifier.
+
+
+Painting Brushes
+================
+
+.. figure:: /images/sculpt-paint_sculpting_brushes_overview-paint.png
+   :align: right
+   :width: 250
+
+Recognizable by their green icon.
+These brushes are used for painting color attributes within sculpt mode.
+
+Paint
+   Brushes: :doc:`paint`
+
+   Paint on the vertices of your mesh via color attributes.
+
+Smear
+   Brushes: :doc:`smear`
+
+   Smears the vertex colors via color attributes.
+

manual/sculpt_paint/sculpting/brushes/clay.rst

@@ -6,12 +6,12 @@ Clay
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Clay`
+   :Brush:     :menuselection:`Asset Shelf --> Clay`
 
-Similar to the :doc:`Draw </sculpt_paint/sculpting/tools/draw>` brush,
+Similar to the :doc:`Draw </sculpt_paint/sculpting/brushes/draw>` brush,
 but includes settings to adjust the :ref:`sculpt plane <bpy.types.Brush.sculpt_plane>`
 on which the brush acts. That's because it behaves like a combination of the
-:doc:`Flatten </sculpt_paint/sculpting/tools/flatten>` and *Draw* brushes.
+:doc:`Flatten </sculpt_paint/sculpting/brushes/flatten>` and *Draw* brushes.
 
 This brush is useful for building and removing volumes and shapes like real clay,
 because it flattens details as you add/subtract from the surfaces.

manual/sculpt_paint/sculpting/brushes/clay_strips.rst

@@ -6,10 +6,10 @@ Clay Strips
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Clay Strips`
+   :Brush:     :menuselection:`Asset Shelf --> Clay Strips`
    :Shortcut:  :kbd:`C`
 
-Similar to the :doc:`Clay </sculpt_paint/sculpting/tools/clay>` brush,
+Similar to the :doc:`Clay </sculpt_paint/sculpting/brushes/clay>` brush,
 but it uses a square tip shape instead of a round one.
 
 Just like the *Clay* brush, it's useful for building and removing volumes

manual/sculpt_paint/sculpting/brushes/clay_thumb.rst

@@ -6,9 +6,9 @@ Clay Thumb
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Clay Thumb`
+   :Brush:     :menuselection:`Asset Shelf --> Clay Thumb`
 
-Similar to the :doc:`/sculpt_paint/sculpting/tools/clay` brush.
+Similar to the :doc:`/sculpt_paint/sculpting/brushes/clay` brush.
 It imitates the effect of deforming clay with the finger, accumulating material during the stroke.
 The sculpt plane tilts during the stroke in the front part of the brush to achieve this effect.
 

manual/sculpt_paint/sculpting/brushes/cloth.rst

@@ -7,7 +7,7 @@ Cloth
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Cloth`
+   :Brush:     :menuselection:`Asset Shelf --> Cloth`
 
 This brush simulates cloth physics on the mesh under the brush cursor.
 There are various deformation types and settings to customize the brush.

manual/sculpt_paint/sculpting/brushes/crease.rst

@@ -6,7 +6,7 @@ Crease
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Crease`
+   :Brush:     :menuselection:`Asset Shelf --> Crease`
    :Shortcut:  :kbd:`Shift-C`
 
 Create sharp indents or ridges by pushing or pulling the mesh, while pinching the vertices together.
@@ -24,9 +24,9 @@ General
 Pinch
    Adds a consistent pinching effect to your stroke.
    If set to 0 it the brush will behave like the
-   :doc:`Draw </sculpt_paint/sculpting/tools/draw>` brush.
+   :doc:`Draw </sculpt_paint/sculpting/brushes/draw>` brush.
    If set to 1 and the brush strength set to 0, the brush
-   will behave like a :doc:`Pinch </sculpt_paint/sculpting/tools/pinch>` brush.
+   will behave like a :doc:`Pinch </sculpt_paint/sculpting/brushes/pinch>` brush.
 
 .. note::
 

manual/sculpt_paint/sculpting/brushes/density.rst

@@ -1,20 +1,20 @@
 
-********
+*******
-Simplify
+Density
-********
+*******
 
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Simplify`
+   :Brush:     :menuselection:`Asset Shelf --> Density`
 
-The Simplify brush is specifically meant for use with
+The Density brush is specifically meant for use with
 :doc:`/sculpt_paint/sculpting/tool_settings/dyntopo`
 to remove/add detail in the mesh.
 
 Even when the :ref:`Refine Method <bpy.types.Sculpt.detail_refine_method>`
 is set to *Subdivide Edges*, this brush is always able to collapse edges.
-This ensures that while focusing on adding detail to your sculpt, the *Simplify* brush
+This ensures that while focusing on adding detail to your sculpt, the *Density* brush
 can always be used to simplify and polish surfaces.
 
 This brush has no effect if Dyntopo is disabled.

manual/sculpt_paint/sculpting/brushes/draw.rst

@@ -5,7 +5,7 @@ Draw
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Draw`
+   :Brush:     :menuselection:`Asset Shelf --> Draw`
    :Shortcut:  :kbd:`V`
 
 Moves vertices inward or outward, based the average vertex normals within the brush radius.

manual/sculpt_paint/sculpting/brushes/draw_facesets.rst

@@ -6,7 +6,7 @@ Draw Face Sets
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Draw Face Sets`
+   :Brush:     :menuselection:`Asset Shelf --> Draw Face Sets`
 
 Draw new or extend existing :ref:`Face Sets <sculpting-editing-facesets>` with each stroke.
 

manual/sculpt_paint/sculpting/brushes/draw_sharp.rst

@@ -6,21 +6,21 @@ Draw Sharp
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Draw Sharp`
+   :Brush:     :menuselection:`Asset Shelf --> Draw Sharp`
 
-Similar to the :doc:`Draw </sculpt_paint/sculpting/tools/draw>` brush,
+Similar to the :doc:`Draw </sculpt_paint/sculpting/brushes/draw>` brush,
 but it always deforms the mesh from the original coordinates
 and uses the *Sharper* Falloff by default.
 
 Draw Sharp is useful on high density meshes for creating cloth wrinkles, stylized hair or hard surface edges.
 To further sharpen or polish sharp edges in the case that the mesh density is not enough,
-it's recommended to use the :doc:`Pinch </sculpt_paint/sculpting/tools/pinch>`,
+it's recommended to use the :doc:`Pinch </sculpt_paint/sculpting/brushes/pinch>`,
-:doc:`Crease </sculpt_paint/sculpting/tools/crease>` or
+:doc:`Crease </sculpt_paint/sculpting/brushes/crease>` or
-:doc:`Multiplane Scrape </sculpt_paint/sculpting/tools/multiplane_scrape>` brushes.
+:doc:`Multiplane Scrape </sculpt_paint/sculpting/brushes/multiplane_scrape>` brushes.
 
 A limitation is that the brush does not remesh the sculpted surfaces
 with :ref:`Dyntopo <bpy.ops.sculpt.dynamic_topology_toggle>` enabled.
-Because of that, a better brush to use with Dyntopo can be :doc:`Crease </sculpt_paint/sculpting/tools/crease>`.
+Because of that, a better brush to use with Dyntopo can be :doc:`Crease </sculpt_paint/sculpting/brushes/crease>`.
 
 
 Brush Settings

manual/sculpt_paint/sculpting/brushes/elastic_deform.rst

@@ -6,7 +6,7 @@ Elastic Deform
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Elastic Deform`
+   :Brush:     :menuselection:`Asset Shelf --> Elastic Deform`
 
 Used to simulate realistic deformations such as grabbing or twisting of :term:`Elastic` objects.
 For example, this tool works great for modeling the shape of organic objects such as humans or animals.

manual/sculpt_paint/sculpting/brushes/fill.rst

@@ -6,9 +6,9 @@ Fill
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Fill`
+   :Brush:     :menuselection:`Asset Shelf --> Fill`
 
-Similar to the :doc:`Flatten </sculpt_paint/sculpting/tools/flatten>` brush,
+Similar to the :doc:`Flatten </sculpt_paint/sculpting/brushes/flatten>` brush,
 but only pushes surfaces upwards to the medium height.
 
 Although :kbd:`Ctrl` can be held to invert the effect to a Scrape brush,

manual/sculpt_paint/sculpting/brushes/flatten.rst

@@ -1,12 +1,12 @@
 
-*******
+****************
-Flatten
+Flatten/Contrast
-*******
+****************
 
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Flatten`
+   :Brush:     :menuselection:`Asset Shelf --> Flatten/Contrast`
 
 Flatten or contrast surfaces by pulling and pushing them towards
 (or away from) a defined medium height.

manual/sculpt_paint/sculpting/brushes/grab.rst

@@ -6,7 +6,7 @@ Grab
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Grab`
+   :Brush:     :menuselection:`Asset Shelf --> Grab`
    :Shortcut:  :kbd:`G`
 
 Drag geometry across the screen, following the cursor.

manual/sculpt_paint/sculpting/brushes/index.rst

@@ -0,0 +1,43 @@
+
+#########
+  Brushes
+#########
+
+Brushes for *Sculpt Mode* bundled in the *Essentials* library.
+
+.. toctree::
+   :maxdepth: 1
+
+   brush_types.rst
+   draw.rst
+   draw_sharp.rst
+   clay.rst
+   clay_strips.rst
+   clay_thumb.rst
+   layer.rst
+   inflate.rst
+   blob.rst
+   crease.rst
+   smooth.rst
+   flatten.rst
+   fill.rst
+   scrape.rst
+   multiplane_scrape.rst
+   pinch.rst
+   grab.rst
+   elastic_deform.rst
+   snake_hook.rst
+   thumb.rst
+   pose.rst
+   nudge.rst
+   twist.rst
+   slide_relax.rst
+   boundary.rst
+   cloth.rst
+   density.rst
+   mask.rst
+   draw_facesets.rst
+   multires_displacement_eraser.rst
+   multires_displacement_smear.rst
+   paint.rst
+   smear.rst

manual/sculpt_paint/sculpting/brushes/inflate.rst

@@ -1,15 +1,15 @@
 
-*******
+***************
-Inflate
+Inflate/Deflate
-*******
+***************
 
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Inflate`
+   :Brush:     :menuselection:`Asset Shelf --> Inflate/Deflate`
    :Shortcut:  :kbd:`I`
 
-Similar to :doc:`Draw </sculpt_paint/sculpting/tools/clay>`,
+Similar to :doc:`Draw </sculpt_paint/sculpting/brushes/clay>`,
 except that vertices are moved in the direction of their own normals.
 Especially useful when sculpting meshes with a lot of curvature.
 

manual/sculpt_paint/sculpting/brushes/layer.rst

@@ -6,9 +6,9 @@ Layer
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Layer`
+   :Brush:     :menuselection:`Asset Shelf --> Layer`
 
-This brush is similar to :doc:`Draw </sculpt_paint/sculpting/tools/clay>`,
+This brush is similar to :doc:`Draw </sculpt_paint/sculpting/brushes/clay>`,
 except that the height capped.
 This creates the appearance of a flat layer.
 

manual/sculpt_paint/sculpting/brushes/multiplane_scrape.rst

@@ -1,12 +1,12 @@
 
 *****************
-Multiplane Scrape
+Scrape Multiplane
 *****************
 
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Multiplane Scrape`
+   :Brush:     :menuselection:`Brush --> Scrape Multiplane`
 
 Scrapes the mesh with two angled planes at the same time, creating a sharp edge between them.
 This is useful for creating & polishing hard surface objects.

manual/sculpt_paint/sculpting/brushes/multires_displacement_eraser.rst

@@ -1,12 +1,12 @@
 
-****************************
+***************************
-Multires Displacement Eraser
+Erase Multires Displacement
-****************************
+***************************
 
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Multires Displacement Erase`
+   :Brush:     :menuselection:`Asset Shelf --> Erase Multires Displacement`
 
 This brush deletes displacement information of
 the :doc:`Multires Modifier </modeling/modifiers/generate/multiresolution>`,

manual/sculpt_paint/sculpting/brushes/multires_displacement_smear.rst

@@ -1,12 +1,12 @@
 
 ***************************
-Multires Displacement Smear
+Smear Multires Displacement
 ***************************
 
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Multires Displacement Smear`
+   :Brush:     :menuselection:`Asset Shelf --> Smear Multires Displacement`
 
 This tool deforms displacement information of
 the :doc:`Multires Modifier </modeling/modifiers/generate/multiresolution>`,

manual/sculpt_paint/sculpting/brushes/nudge.rst

@@ -6,11 +6,11 @@ Nudge
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Nudge`
+   :Brush:     :menuselection:`Asset Shelf --> Nudge`
 
 Moves vertices in the direction of the brush stroke.
 
-Similar to the :doc:`Snake Hook </sculpt_paint/sculpting/tools/snake_hook>` brush,
+Similar to the :doc:`Snake Hook </sculpt_paint/sculpting/brushes/snake_hook>` brush,
 but instead only moves the geometry along the surface (using the area plane).
 This is useful for grabbing geometry along curved surfaces,
 without making too impactful changes to the overall object shape.

manual/sculpt_paint/sculpting/brushes/paint.rst

@@ -6,7 +6,7 @@ Paint
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Paint`
+   :Brush:     :menuselection:`Asset Shelf --> Paint`
 
 Paints on the active color attribute.
 Hold :kbd:`Shift` to blur painted colors instead.

manual/sculpt_paint/sculpting/brushes/pinch.rst

@@ -1,12 +1,12 @@
 
-*****
+*************
-Pinch
+Pinch/Magnify
-*****
+*************
 
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Pinch`
+   :Brush:     :menuselection:`Asset Shelf --> Pinch/Magnify`
    :Shortcut:  :kbd:`P`
 
 Pulls geometry towards the center of the brush.

manual/sculpt_paint/sculpting/brushes/pose.rst

@@ -6,7 +6,7 @@ Pose
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Pose`
+   :Brush:     :menuselection:`Asset Shelf --> Pose`
 
 Deform a model simulating armature-like workflow.
 This can either be useful for posing a model without a rig,

manual/sculpt_paint/sculpting/brushes/scrape.rst

@@ -1,15 +1,15 @@
 
-******
+***********
-Scrape
+Scrape/Fill
-******
+***********
 
 .. reference::
 
    :Mode:      Sculpt Mode
-   :Tool:      :menuselection:`Toolbar --> Scrape`
+   :Brush:     :menuselection:`Asset Shelf --> Scrape/Fill`
    :Shortcut:  :kbd:`Shift-T`
 
-Similar to the :doc:`Flatten </sculpt_paint/sculpting/tools/flatten>` brush,
+Similar to the :doc:`Flatten </sculpt_paint/sculpting/brushes/flatten>` brush,
 but only pushes surfaces downward to the medium height.
 
 Although :kbd:`Ctrl` can be held to invert the effect to a Fill brush,