Documentation/content/reference/buildertools/tool-operations.en.md

title, type, weight

title	type	weight
Tool Operations	docs	4

Tool operations handle the actual block editing mechanics when using builder tools.

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

Architecture

Tool Operations
├── Base
│   └── ToolOperation - Operation base class
├── Operations
│   ├── PaintOperation - Block painting
│   └── EditOperation - Edit tracking
├── Materials
│   └── Material - Block material wrapper
└── Utilities
    └── CopyCutSettings - Copy/cut configuration

ToolOperation

Base class for all tool operations:

public class ToolOperation {
    // Base operation that modifies blocks
    // Tracked for undo/redo
}

PaintOperation

Handles block painting with brush tools:

public class PaintOperation extends ToolOperation {
    // Applies blocks in brush shape
    // Supports patterns and masks
}

Usage

When a player uses a brush tool:

1. PaintOperation is created
2. Shape is calculated based on tool settings
3. Blocks are modified according to pattern
4. Operation is added to history

EditOperation

Tracks changes for undo/redo:

public class EditOperation {
    // Records block changes
    // Enables reversal
}

Material System

Material

Wrapper for block materials:

public class Material {
    // Block type reference
    // Additional properties (rotation, tint)
}

Block Patterns

Patterns define how blocks are selected:

Pattern	Description
[Stone]	Single block type
[50%Stone, 50%Dirt]	Weighted random
[Stone, Dirt, Grass]	Equal weights

Block Masks

Masks filter which blocks are affected:

Mask	Description
[Stone]	Only affect stone
[!Air]	Affect non-air blocks
[!^Fluid]	Exclude fluid tagged blocks

Copy/Cut Settings

CopyCutSettings

Configuration for copy and cut operations:

public class CopyCutSettings {
    // Include entities flag
    // Include biome data flag
    // Compression level
}

Tool Arguments

Builder tools support configurable arguments:

Argument Types

Type	Class	Description
Block	BlockArg	Block type selection
Bool	BoolArg	Boolean flag
Int	IntArg	Integer value
Float	FloatArg	Decimal value
Mask	MaskArg	Block mask
String	StringArg	Text value
BrushShape	BrushShapeArg	Sphere, Cube, etc.
BrushOrigin	BrushOriginArg	Center, Surface, etc.

Tool Argument Packets

Arguments sync via network packets:

// BuilderToolArgUpdate packet
// Syncs tool argument changes to server

Brush Configuration

Brush Shape

public enum BrushShape {
    Sphere,
    Cube,
    Cylinder,
    // ...
}

Brush Origin

public enum BrushOrigin {
    Center,      // Brush centered on click
    Surface,     // Brush on surface
    Offset       // Custom offset
}

Brush Axis

public enum BrushAxis {
    Y,           // Always vertical
    View,        // Follow view direction
    Surface      // Normal to surface
}

API Usage

Access Tool Settings

BuilderToolsPlugin tools = BuilderToolsPlugin.get();
BuilderToolsUserData userData = tools.getUserData(player);

Get Current Tool

BuilderTool currentTool = userData.getCurrentTool();
BuilderToolData toolData = currentTool.getData();

Tool State

BuilderToolState

Tracks current tool state:

// BuilderToolState packet
// Syncs tool state to client

Brush Data

// BuilderToolBrushData packet
// Contains brush size, shape, pattern