Documentation/content/reference/buildertools/scripted-brushes.en.md

title, type, weight

title	type	weight
Scripted Brushes	docs	1

Scripted brushes allow creating complex, programmable brush operations through JSON asset definitions.

Package: com.hypixel.hytale.builtin.buildertools.scriptedbrushes

Architecture

Scripted Brushes
├── Assets
│   └── ScriptedBrushAsset - Brush definitions
├── Operations
│   ├── BrushOperation - Base operation class
│   ├── SequenceBrushOperation - Sequential operations
│   └── GlobalBrushOperation - Global modifiers
├── Categories
│   ├── Shape Operations - Set, fill, shape
│   ├── Mask Operations - Mask, history mask
│   ├── Flow Control - Loops, jumps, conditions
│   ├── Material Operations - Pattern, replace
│   └── Transform Operations - Offset, dimensions
├── Config
│   ├── BrushConfig - Runtime configuration
│   └── BrushConfigEditStore - Edit state
└── Commands
    └── BrushConfigCommand - /brushconfig

ScriptedBrushAsset

Brush definitions loaded from JSON:

Asset Location: BuilderTools/Brushes/

# BuilderTools/Brushes/terrain_sphere.json
{
  "Id": "terrain_sphere",
  "Operations": [
    {
      "Type": "Shape",
      "Shape": "Sphere"
    },
    {
      "Type": "Dimensions",
      "Width": 5,
      "Height": 5,
      "Depth": 5
    },
    {
      "Type": "Material",
      "Pattern": "[Rock_Stone]"
    },
    {
      "Type": "Set"
    }
  ]
}

Asset Access

// Get brush asset
ScriptedBrushAsset brush = ScriptedBrushAsset.get("terrain_sphere");

// Get operations
List<BrushOperation> operations = brush.getOperations();

// Load into executor
brush.loadIntoExecutor(executor);

Operation Types

Shape Operations

Operation	Description
Set	Apply blocks at positions
Shape	Define brush shape (Sphere, Cube, Cylinder)
Delete	Remove blocks
Smooth	Smooth terrain
Erode	Erode terrain
Lift	Raise terrain
Melt	Melt terrain

{
  "Type": "Shape",
  "Shape": "Sphere"  // Sphere, Cube, Cylinder
}

Dimension Operations

{
  "Type": "Dimensions",
  "Width": 10,
  "Height": 5,
  "Depth": 10
}

{
  "Type": "RandomizeDimensions",
  "MinWidth": 3,
  "MaxWidth": 7,
  "MinHeight": 3,
  "MaxHeight": 7
}

Material Operations

{
  "Type": "Material",
  "Pattern": "[50%Rock_Stone, 50%Rock_Shale]"
}

{
  "Type": "BlockPattern",
  "Pattern": "[Rock_Stone]"
}

{
  "Type": "Replace",
  "From": "[Grass]",
  "To": "[Dirt]"
}

Mask Operations

{
  "Type": "Mask",
  "Mask": "[!Air]"
}

{
  "Type": "AppendMask",
  "Mask": "[!Water]"
}

{
  "Type": "HistoryMask"
  // Only affect previously modified blocks
}

{
  "Type": "UseBrushMask"
  // Use mask from tool arguments
}

Offset Operations

{
  "Type": "Offset",
  "X": 0,
  "Y": 5,
  "Z": 0
}

{
  "Type": "RandomOffset",
  "MinX": -2,
  "MaxX": 2,
  "MinY": 0,
  "MaxY": 5,
  "MinZ": -2,
  "MaxZ": 2
}

Flow Control

Loops

{
  "Type": "Loop",
  "Count": 5,
  "StartIndex": 2,
  "EndIndex": 6
}

{
  "Type": "LoopRandom",
  "MinCount": 3,
  "MaxCount": 8
}

{
  "Type": "CircleOffsetAndLoop",
  "Radius": 5,
  "Count": 8
}

Conditionals

{
  "Type": "JumpIfBlockType",
  "BlockType": "Air",
  "Index": 10,
  "ElseIndex": 5
}

{
  "Type": "JumpIfClickType",
  "ClickType": "Primary",
  "Index": 3
}

{
  "Type": "JumpIfCompare",
  "Variable": "height",
  "Operator": ">",
  "Value": 5,
  "Index": 8
}

{
  "Type": "JumpToIndex",
  "Index": 0
}

{
  "Type": "Exit"
  // Stop brush execution
}

Special Operations

{
  "Type": "Echo",
  "Message": "Brush applied!"
}

{
  "Type": "RunCommand",
  "Command": "/fill [Stone]"
}

{
  "Type": "PastePrefab",
  "PrefabId": "tree_oak"
}

{
  "Type": "HeightmapLayer",
  "Layer": 0
}

Save/Load Operations

{
  "Type": "LoadOperationsFromAsset",
  "AssetId": "common_setup"
}

{
  "Type": "SaveBrushConfig",
  "Key": "my_config"
}

{
  "Type": "LoadBrushConfig",
  "Key": "my_config"
}

Global Operations

Operations that affect the entire brush:

{
  "Type": "Debug",
  "Enabled": true
}

{
  "Type": "DisableHoldInteraction"
  // Only trigger on click, not hold
}

{
  "Type": "IgnoreExistingBrushData"
}

Brush Config Command

Manage brush configurations via command:

Command	Description
/brushconfig	Base brush config command
/brushconfig load <id>	Load brush config
/brushconfig list	List available brushes
/brushconfig clear	Clear current config
/brushconfig exit	Exit brush mode
/brushconfig debugstep	Step through operations

API Usage

Load Brush

ScriptedBrushAsset brush = ScriptedBrushAsset.get("terrain_sphere");

Execute Brush

BrushConfigCommandExecutor executor = new BrushConfigCommandExecutor();
brush.loadIntoExecutor(executor);
// Execute operations sequentially

Access Operations

List<BrushOperation> operations = brush.getOperations();
for (BrushOperation op : operations) {
    if (op instanceof SequenceBrushOperation) {
        // Sequential operation
    } else if (op instanceof GlobalBrushOperation) {
        // Global modifier
    }
}