Init

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

@@ -0,0 +1,205 @@
+---
+title: Tool Operations
+type: docs
+weight: 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:
+
+```java
+public class ToolOperation {
+    // Base operation that modifies blocks
+    // Tracked for undo/redo
+}
+```
+
+## PaintOperation
+
+Handles block painting with brush tools:
+
+```java
+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:
+
+```java
+public class EditOperation {
+    // Records block changes
+    // Enables reversal
+}
+```
+
+## Material System
+
+### Material
+
+Wrapper for block materials:
+
+```java
+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:
+
+```java
+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:
+
+```java
+// BuilderToolArgUpdate packet
+// Syncs tool argument changes to server
+```
+
+## Brush Configuration
+
+### Brush Shape
+
+```java
+public enum BrushShape {
+    Sphere,
+    Cube,
+    Cylinder,
+    // ...
+}
+```
+
+### Brush Origin
+
+```java
+public enum BrushOrigin {
+    Center,      // Brush centered on click
+    Surface,     // Brush on surface
+    Offset       // Custom offset
+}
+```
+
+### Brush Axis
+
+```java
+public enum BrushAxis {
+    Y,           // Always vertical
+    View,        // Follow view direction
+    Surface      // Normal to surface
+}
+```
+
+## API Usage
+
+### Access Tool Settings
+
+```java
+BuilderToolsPlugin tools = BuilderToolsPlugin.get();
+BuilderToolsUserData userData = tools.getUserData(player);
+```
+
+### Get Current Tool
+
+```java
+BuilderTool currentTool = userData.getCurrentTool();
+BuilderToolData toolData = currentTool.getData();
+```
+
+## Tool State
+
+### BuilderToolState
+
+Tracks current tool state:
+
+```java
+// BuilderToolState packet
+// Syncs tool state to client
+```
+
+### Brush Data
+
+```java
+// BuilderToolBrushData packet
+// Contains brush size, shape, pattern
+```