Creating Custom Structures

Lithostitched provides powerful tools for creating custom structures using Minecraft’s jigsaw system, enhanced with additional features like pool aliases, custom processors, and flexible configuration.

Structure System Overview

Lithostitched structures use three main components:

Structure Template Pools: Collections of structure pieces that can be placed
Structure Processors: Modify blocks during placement (randomization, swapping, etc.)
Structure Configuration: Controls size, height, and placement rules

Creating a Basic Jigsaw Structure

Create structure NBT files

Build your structure pieces in-game using structure blocks and save them to:

data/your_namespace/structure/your_structure/piece_1.nbt
data/your_namespace/structure/your_structure/piece_2.nbt

Define template pools

Create a template pool at:

data/your_namespace/worldgen/template_pool/your_structure/start.json

{
  "name": "your_namespace:your_structure/start",
  "fallback": "minecraft:empty",
  "elements": [
    {
      "weight": 1,
      "element": {
        "location": "your_namespace:your_structure/piece_1",
        "processors": "minecraft:empty",
        "projection": "rigid",
        "element_type": "minecraft:single_pool_element"
      }
    }
  ]
}

Create structure configuration

Define the structure at:

data/your_namespace/worldgen/structure/your_structure.json

{
  "type": "lithostitched:alternate_jigsaw",
  "start_pool": "your_namespace:your_structure/start",
  "size": 7,
  "start_height": {
    "absolute": 0
  },
  "max_distance_from_center": 80,
  "use_expansion_hack": false,
  "biomes": "#minecraft:is_overworld",
  "step": "surface_structures",
  "spawn_overrides": {},
  "terrain_adaptation": "beard_thin"
}

Add to structure set

Include your structure in a structure set:

data/your_namespace/worldgen/structure_set/your_structure.json

{
  "structures": [
    {
      "structure": "your_namespace:your_structure",
      "weight": 1
    }
  ],
  "placement": {
    "type": "minecraft:random_spread",
    "spacing": 32,
    "separation": 8,
    "salt": 123456789
  }
}

Template Pool Configuration

Pool Elements

Each pool element defines a structure piece that can be placed:

{
  "weight": 5,
  "element": {
    "location": "your_namespace:village/house_1",
    "processors": "your_namespace:village_weathering",
    "projection": "rigid",
    "element_type": "minecraft:single_pool_element"
  }
}

weight: Relative spawn chance (higher = more common)
location: Path to structure NBT file
processors: Processor list to apply (or minecraft:empty)
projection: rigid (exact) or terrain_matching (follows ground)
element_type: Usually minecraft:single_pool_element

Multiple Pieces in One Pool

{
  "name": "your_namespace:village/houses",
  "fallback": "minecraft:empty",
  "elements": [
    {
      "weight": 10,
      "element": {
        "location": "your_namespace:village/small_house",
        "processors": "your_namespace:village_processors",
        "projection": "rigid",
        "element_type": "minecraft:single_pool_element"
      }
    },
    {
      "weight": 5,
      "element": {
        "location": "your_namespace:village/large_house",
        "processors": "your_namespace:village_processors",
        "projection": "rigid",
        "element_type": "minecraft:single_pool_element"
      }
    },
    {
      "weight": 3,
      "element": {
        "location": "your_namespace:village/mansion",
        "processors": "your_namespace:village_processors",
        "projection": "rigid",
        "element_type": "minecraft:single_pool_element"
      }
    }
  ]
}

Small houses are twice as common as large houses, and over 3x more common than mansions.

Structure Processors

Processors modify blocks during structure placement. Lithostitched provides several custom processor types.

Block Swap Processor

Replace specific blocks with alternatives:

{
  "processors": [
    {
      "processor_type": "lithostitched:block_swap",
      "blocks": {
        "minecraft:oak_planks": "minecraft:spruce_planks",
        "minecraft:oak_log": "minecraft:spruce_log",
        "minecraft:oak_stairs": "minecraft:spruce_stairs",
        "minecraft:oak_slab": "minecraft:spruce_slab",
        "minecraft:oak_fence": "minecraft:spruce_fence"
      }
    }
  ]
}

This converts all oak variants to spruce, perfect for biome-specific variations.

Random Processor Application

Apply different processor lists randomly for variety:

{
  "processors": [
    {
      "processor_type": "lithostitched:apply_random",
      "mode": "per_piece",
      "processor_lists": "#your_namespace:building_palettes"
    }
  ]
}

Modes:

per_piece: Each structure piece gets a random processor
per_structure: Entire structure uses same random processor

Creating Processor Lists

Define processor lists at:

data/your_namespace/worldgen/processor_list/my_processors.json

Weathering Processor

{
  "processors": [
    {
      "processor_type": "minecraft:rule",
      "rules": [
        {
          "input_predicate": {
            "block": "minecraft:stone_bricks",
            "predicate_type": "minecraft:random_block_match",
            "probability": 0.3
          },
          "location_predicate": {
            "predicate_type": "minecraft:always_true"
          },
          "output_state": {
            "Name": "minecraft:cracked_stone_bricks"
          }
        },
        {
          "input_predicate": {
            "block": "minecraft:stone_bricks",
            "predicate_type": "minecraft:random_block_match",
            "probability": 0.2
          },
          "location_predicate": {
            "predicate_type": "minecraft:always_true"
          },
          "output_state": {
            "Name": "minecraft:mossy_stone_bricks"
          }
        }
      ]
    }
  ]
}

Multi-Palette System

Create a tag for random palette selection:

data/your_namespace/tags/worldgen/processor_list/house_palettes.json

{
  "values": [
    "your_namespace:palette/oak_and_stone",
    "your_namespace:palette/spruce_and_cobble",
    "your_namespace:palette/birch_and_brick"
  ]
}

Each referenced processor list swaps blocks to a different material set.

Alternate Jigsaw Configuration

Lithostitched’s alternate_jigsaw structure type extends vanilla jigsaw structures with additional features.

Basic Configuration

{
  "type": "lithostitched:alternate_jigsaw",
  "start_pool": "your_namespace:dungeon/entrance",
  "start_jigsaw_name": "your_namespace:dungeon_connector",
  "size": {
    "type": "minecraft:uniform",
    "min_inclusive": 5,
    "max_inclusive": 7
  },
  "start_height": {
    "type": "minecraft:uniform",
    "min_inclusive": -20,
    "max_inclusive": 40
  },
  "max_distance_from_center": {
    "horizontal": 80,
    "vertical": 64
  },
  "use_expansion_hack": false,
  "biomes": "#your_namespace:has_dungeon",
  "step": "underground_structures",
  "spawn_overrides": {},
  "terrain_adaptation": "bury"
}

Size Configuration

The size field controls jigsaw depth: Fixed size:

"size": 7

Random size range:

"size": {
  "type": "minecraft:uniform",
  "min_inclusive": 4,
  "max_inclusive": 8
}

Height Providers

Control where structures spawn vertically: Fixed height:

"start_height": {
  "absolute": 64
}

Height range:

"start_height": {
  "type": "minecraft:uniform",
  "min_inclusive": {
    "above_bottom": 0
  },
  "max_inclusive": {
    "absolute": 64
  }
}

Heightmap-based:

"start_height": {
  "type": "minecraft:constant",
  "value": {
    "type": "minecraft:heightmap",
    "heightmap": "WORLD_SURFACE_WG"
  }
}

Terrain Adaptation

Controls how structures interact with terrain:

none: No adaptation
bury: Buries underground portions
beard_thin: Small beard of terrain below structure
beard_box: Box-shaped terrain beard
encapsulate: Completely encapsulates in terrain

Pool Aliases

Pool aliases allow dynamic pool substitution:

{
  "type": "lithostitched:alternate_jigsaw",
  "start_pool": "your_namespace:temple/entrance",
  "size": 6,
  "pool_aliases": [
    {
      "alias": "your_namespace:temple/treasure",
      "target": "your_namespace:temple/treasure_common",
      "type": "minecraft:direct"
    }
  ]
}

This substitutes the treasure pool with treasure_common during generation.

Adding to Existing Structures

Use modifiers to add your pieces to vanilla structures:

{
  "type": "lithostitched:add_template_pool_elements",
  "template_pools": [
    "minecraft:village/plains/houses"
  ],
  "elements": [
    {
      "element": {
        "location": "your_namespace:village/custom_blacksmith",
        "processors": "minecraft:empty",
        "projection": "rigid",
        "element_type": "minecraft:single_pool_element"
      },
      "weight": 8
    },
    {
      "element": {
        "location": "your_namespace:village/custom_library",
        "processors": "your_namespace:village_books",
        "projection": "rigid",
        "element_type": "minecraft:single_pool_element"
      },
      "weight": 5
    }
  ]
}

Advanced Techniques

Multi-Level Structures

Create structures with multiple floors:

Create pools for each floor level
Use jigsaw blocks to connect levels
Set appropriate projection types

{
  "name": "your_namespace:tower/base",
  "fallback": "minecraft:empty",
  "elements": [
    {
      "weight": 1,
      "element": {
        "location": "your_namespace:tower/floor_base",
        "processors": "minecraft:empty",
        "projection": "rigid",
        "element_type": "minecraft:single_pool_element"
      }
    }
  ]
}

Conditional Piece Placement

Use processor conditions to place pieces based on environment:

{
  "processor_type": "lithostitched:condition",
  "condition": {
    "type": "lithostitched:biome",
    "biomes": "#minecraft:is_ocean"
  },
  "if_true": [
    {
      "processor_type": "lithostitched:block_swap",
      "blocks": {
        "minecraft:air": "minecraft:water"
      }
    }
  ]
}

Random Loot Integration

Add loot chests to your structures using block entities in your NBT files, then reference loot tables:

{
  "processor_type": "minecraft:rule",
  "rules": [
    {
      "input_predicate": {
        "block": "minecraft:chest",
        "predicate_type": "minecraft:always_true"
      },
      "location_predicate": {
        "predicate_type": "minecraft:always_true"
      },
      "output_state": {
        "Name": "minecraft:chest"
      },
      "output_nbt": "{LootTable:\"your_namespace:chests/dungeon\"}"
    }
  ]
}

Testing Your Structure

Use locate command

/locate structure your_namespace:your_structure

Force placement

/place structure your_namespace:your_structure ~ ~ ~

Check template pools

/place template your_namespace:your_structure/start ~ ~ ~

Verify processors

Test different processors by changing the processor list in your pool and force-placing.

Best Practices

Design modular pieces

Create reusable pieces that work in multiple contexts
Use consistent jigsaw connector names
Keep piece sizes reasonable (16x16 or smaller when possible)
Design pieces with multiple connection points

Balance weights carefully

Common pieces: 10-20
Uncommon pieces: 5-10
Rare pieces: 1-3
Ensure variety without over-randomization

Use processor lists effectively

Keep processors lightweight
Use tags for material palettes
Test performance with complex processors
Avoid excessive randomization

Structure placement considerations

Choose appropriate terrain adaptation
Set reasonable max_distance values
Use correct biome tags
Balance spacing and separation

Common Issues

Structure not generating

Verify biome tag includes target biomes
Check structure set spacing/separation
Ensure start pool exists and is valid
Verify structure step is appropriate

Pieces not connecting

Match jigsaw connector names exactly
Check projection types match
Verify size allows enough depth
Ensure fallback pool exists

Processors not applying

Check processor list path is correct
Verify processor syntax
Test with simple block swap first
Check for conflicting processors

Performance problems

Reduce max_distance_from_center
Simplify processor rules
Limit structure size
Optimize pool element count

Next Steps

Bandlands Terrain

Create banded terrain patterns for unique biomes

Common Patterns

Explore common worldgen patterns and techniques

Processor Reference

Complete documentation of all processor types

Structure Examples

Browse example structures for inspiration

Get Started

Core Concepts

Examples & Guides

Creating Custom Structures

Structure System Overview

Creating a Basic Jigsaw Structure

Template Pool Configuration

Pool Elements

Multiple Pieces in One Pool

Structure Processors

Block Swap Processor

Random Processor Application

Creating Processor Lists

Weathering Processor

Multi-Palette System

Alternate Jigsaw Configuration

Basic Configuration

Size Configuration

Height Providers

Terrain Adaptation

Pool Aliases

Adding to Existing Structures

Advanced Techniques

Multi-Level Structures

Conditional Piece Placement

Random Loot Integration

Testing Your Structure

Best Practices

Common Issues

Structure not generating

Pieces not connecting

Processors not applying

Performance problems

Next Steps

Bandlands Terrain

Common Patterns

Processor Reference

Structure Examples

Build docs developers (and LLMs) love

Get Started

Core Concepts

Examples & Guides

​Structure System Overview

​Creating a Basic Jigsaw Structure

​Template Pool Configuration

​Pool Elements

​Multiple Pieces in One Pool

​Structure Processors

​Block Swap Processor

​Random Processor Application

​Creating Processor Lists

​Weathering Processor

​Multi-Palette System

​Alternate Jigsaw Configuration

​Basic Configuration

​Size Configuration

​Height Providers

​Terrain Adaptation

​Pool Aliases

​Adding to Existing Structures

​Advanced Techniques

​Multi-Level Structures

​Conditional Piece Placement

​Random Loot Integration

​Testing Your Structure

​Best Practices

​Common Issues

Structure not generating

Pieces not connecting

Processors not applying

Performance problems

​Next Steps

Bandlands Terrain

Common Patterns

Processor Reference

Structure Examples

Build docs developers (and LLMs) love

Structure System Overview

Creating a Basic Jigsaw Structure

Template Pool Configuration

Pool Elements

Multiple Pieces in One Pool

Structure Processors

Block Swap Processor

Random Processor Application

Creating Processor Lists

Weathering Processor

Multi-Palette System

Alternate Jigsaw Configuration

Basic Configuration

Size Configuration

Height Providers

Terrain Adaptation

Pool Aliases

Adding to Existing Structures

Advanced Techniques

Multi-Level Structures

Conditional Piece Placement

Random Loot Integration

Testing Your Structure

Best Practices

Common Issues

Next Steps