Documentation/content/world/worldgen/generation-patterns.en.md

---
title: Generation Patterns
type: docs
weight: 11
---

Generation patterns provide reusable algorithms for creating terrain features, structures, and decorations.

**Packages:**
- `com.hypixel.hytale.builtin.hytalegenerator.patterns`
- `com.hypixel.hytale.builtin.hytalegenerator.fields`

## Pattern System

Patterns encapsulate generation logic:

```java
public interface GenerationPattern {
    // Apply pattern to container
    void apply(GenerationContainer container, PatternContext context);
}

public class PatternContext {
    private Vector3i origin;
    private int size;
    private Random random;
    private Map<String, Object> parameters;
}
```

## Built-in Patterns

### SpherePattern

Creates spherical formations:

```yaml
Type: SpherePattern
Radius: 5
Block: stone
Hollow: false
```

```java
public class SpherePattern implements GenerationPattern {
    private float radius;
    private BlockType block;
    private boolean hollow;

    public void apply(GenerationContainer container, PatternContext ctx) {
        int r = (int) radius;
        for (int dx = -r; dx <= r; dx++) {
            for (int dy = -r; dy <= r; dy++) {
                for (int dz = -r; dz <= r; dz++) {
                    float dist = (float) Math.sqrt(dx*dx + dy*dy + dz*dz);
                    if (dist <= radius && (!hollow || dist > radius - 1)) {
                        container.setBlock(
                            ctx.origin.x + dx,
                            ctx.origin.y + dy,
                            ctx.origin.z + dz,
                            block
                        );
                    }
                }
            }
        }
    }
}
```

### CylinderPattern

Creates cylindrical formations:

```yaml
Type: CylinderPattern
Radius: 4
Height: 10
Block: stone
Hollow: true
```

### ArchPattern

Creates arch formations:

```yaml
Type: ArchPattern
Width: 8
Height: 6
Thickness: 2
Block: stone
```

### SpirePattern

Creates spire/stalagmite shapes:

```yaml
Type: SpirePattern
BaseRadius: 3
Height: 15
TaperRate: 0.2
Block: stone
```

## Field Generation

Fields generate values across 2D or 3D space:

### NoiseField

```java
public class NoiseField implements Field2D {
    private SimplexNoise noise;
    private float scale;
    private int octaves;

    public float getValue(int x, int z) {
        return noise.noise2D(x * scale, z * scale);
    }
}
```

### GradientField

```java
public class GradientField implements Field2D {
    private Vector2f direction;
    private float scale;

    public float getValue(int x, int z) {
        return (x * direction.x + z * direction.y) * scale;
    }
}
```

### VoronoiField

```java
public class VoronoiField implements Field2D {
    private List<Vector2i> points;

    public float getValue(int x, int z) {
        float minDist = Float.MAX_VALUE;
        for (Vector2i point : points) {
            float dist = (float) Math.sqrt(
                (x - point.x) * (x - point.x) +
                (z - point.y) * (z - point.y)
            );
            minDist = Math.min(minDist, dist);
        }
        return minDist;
    }
}
```

## Composite Patterns

### RepeatPattern

Repeats a pattern in a grid:

```yaml
Type: RepeatPattern
Pattern: pillar_pattern
SpacingX: 10
SpacingZ: 10
Count: 16
```

### ScatterPattern

Places patterns at random positions:

```yaml
Type: ScatterPattern
Pattern: boulder_pattern
Density: 0.05
MinSpacing: 5
```

### ConditionalPattern

Applies pattern based on conditions:

```yaml
Type: ConditionalPattern
Pattern: snow_cap
Condition:
  Type: HeightAbove
  Height: 100
```

## Terrain Patterns

### RiverPattern

Carves river channels:

```java
public class RiverPattern implements GenerationPattern {
    private List<Vector2f> path;
    private float width;
    private float depth;

    public void apply(GenerationContainer container, PatternContext ctx) {
        for (Vector2f point : path) {
            carveRiverSection(container, point, width, depth);
        }
    }
}
```

### CliffPattern

Creates cliff formations:

```yaml
Type: CliffPattern
Height: 20
Steepness: 0.9
NoiseScale: 0.1
```

### TerracePattern

Creates terraced terrain:

```yaml
Type: TerracePattern
TerraceHeight: 5
TerraceCount: 4
Smoothing: 0.3
```

## Decoration Patterns

### ClusterPattern

Creates clusters of blocks:

```yaml
Type: ClusterPattern
Block: flower_red
Size: 3-7
Density: 0.8
```

### VeinPattern

Creates ore veins:

```yaml
Type: VeinPattern
Block: iron_ore
Length: 10-20
Branching: 0.3
```

### LayerPattern

Creates horizontal layers:

```yaml
Type: LayerPattern
Layers:
  - Block: grass_block
    Thickness: 1
  - Block: dirt
    Thickness: 3
  - Block: stone
    Thickness: -1  # Fill remaining
```

## Configuration

```yaml
# patterns/config.yaml
Patterns:
  boulder:
    Type: SpherePattern
    Radius: 2-4
    Block: stone
  tree_trunk:
    Type: CylinderPattern
    Radius: 1
    Height: 5-10
    Block: oak_log
  crystal_cluster:
    Type: ClusterPattern
    Block: crystal
    Size: 3-8
```

## Custom Pattern

```java
public class MyPattern implements GenerationPattern {
    @Override
    public void apply(GenerationContainer container, PatternContext ctx) {
        // Custom generation logic
        int size = ctx.parameters.getInt("size", 5);

        for (int i = 0; i < size; i++) {
            int x = ctx.origin.x + ctx.random.nextInt(size);
            int z = ctx.origin.z + ctx.random.nextInt(size);
            int y = container.getHeight(x, z);

            container.setBlock(x, y + 1, z, BlockTypes.STONE);
        }
    }
}

// Register
patternRegistry.register("my_pattern", new MyPattern());
```

## Best Practices

{{< callout type="info" >}}
**Pattern Guidelines:**
- Use patterns for reusable generation logic
- Combine patterns with fields for variety
- Test patterns at different scales
- Consider performance with complex patterns
- Document pattern parameters clearly
{{< /callout >}}