Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Create a custom brush that runs a script

Create a prebuilt or custom scriptable brush that draws in more ways than the default tile palette tools.
Read time 3 minutesLast updated 14 days ago
Scriptable brushes are brushes that can draw in more ways than the default toolbar, for example draw a line of tiles or random tiles. Scriptable brushes are part of the 2D Tilemap Extras package.
You can do the following:
  • Use a prebuilt scriptable brush.
  • Create a custom scriptable brush using the 
    GridBrushBase
    API.

Use a prebuilt scriptable brush

To use a prebuilt scriptable brush, follow these steps:
  1. Make sure the 2D Tilemap Extras package is installed in your project. For more information, refer to set up your project for 2D games.
  2. Select a tile from the tile palette as normal.
  3. In the Brush section, select a brush type other than Default Brush.
For more information about each scriptable brush, refer to Scriptable brushes in the 2D Tilemap Extras package documentation.

Create a custom scriptable brush

  1. To create a new C# script, from the main menu select Assets > Create > MonoBehaviour script.
  2. Open the script and replace the code with a class that inherits from 
    UnityEngine.Tilemaps.GridBrushBase
    . For example:
    using UnityEngine;using UnityEngine.Tilemaps;public class MyCustomBrush : GridBrushBase{}
  3. Implement the methods of 
    GridBrushBase
     to define the behavior of the brush. For example, implement the following:
    • Paint
      to add items to the grid.
    • Erase
      to remove items from the grid.
    • FloodFill
      to fill areas on the grid.
    • Rotate
      to rotate items.
    • Flip
      to flip items.
    • ChangeZPosition
      and 
      ResetZPosition
      to control the 3D height of items in an Isometric Z as Y tilemap.
  4. To create instances of your brush as assets in your project, add the 
    CreateAssetMenu
    attribute before the class declaration.
    using UnityEngine;using UnityEngine.Tilemaps;[CreateAssetMenu]public class MyCustomBrush : GridBrushBase{    // ...}
  5. Create an instance of the brush. For example in the previous example, from the main menu, select Assets > My Custom Brush.
The custom brush automatically appears in the Brush Inspector dropdown in the Tile Palette window. For more information, refer to Tile Palette window reference.

Create a custom editor for a scriptable brush

You can also make a custom editor for a custom scriptable brush. This works the same way as custom editors for scriptable objects. The following are the main methods you would want to override when creating a custom editor:
  • Override 
    OnPaintInspectorGUI
    to have an Inspector window appear on the Palette when the Brush is selected to provide additional behaviour when painting.
  • Override 
    OnPaintSceneGUI
    to add additional behaviours when painting on the 
    SceneView
    .
  • Override 
    validTargets
    to have a custom list of targets which the Brush can interact with. This list of targets is shown as a dropdown list in the Palette window.
  • Add a 
    CustomGridBrush
    attribute to your Scriptable Brush class to change its name, make it the default brush in the project, and other options.
  • Add a 
    BrushTools
    attribute to your class with a list of compatible 
    TilemapEditorTools
    types. This ensures that your Scriptable Brush only activates with these specific tools from the Tile Palette toolbar.

Examples

Refer to the following for examples of a custom scriptable brush:
  • GridBrushBase
     in the API documentation for a simple example that paints GameObjects instead of tiles.
  • Select a prebuilt scriptable brush in the Tile Palette window, then double-click the Script field to open the script and check how the brush is implemented.

Additional resources