Quickstart Guide

This guide will walk you through creating your first worldgen modifier with Lithostitched. You’ll learn how to add custom features to biomes using data-driven JSON configuration.

What You’ll Build

By the end of this guide, you’ll have:

A working datapack that uses Lithostitched modifiers
A custom biome feature addition that adds flowers to plains biomes
Understanding of the modifier system and JSON structure

Prerequisites

Lithostitched installed (see Installation)
Basic understanding of Minecraft datapacks
A text editor (VS Code, IntelliJ IDEA, etc.)

Project Setup

Create the datapack structure

Create a new datapack in your world’s datapacks folder:

datapacks/
└── my_worldgen_pack/
    ├── pack.mcmeta
    └── data/
        └── my_worldgen_pack/
            └── lithostitched/
                └── worldgen_modifier/

Create pack.mcmeta

Add the datapack metadata file:

pack.mcmeta

{
  "pack": {
    "pack_format": 41,
    "description": "My first Lithostitched worldgen modifications"
  }
}

Creating Your First Modifier

Let’s create a modifier that adds poppy flowers to plains biomes.

Step 1: Define the Modifier

Create data/my_worldgen_pack/lithostitched/worldgen_modifier/add_poppies.json:

add_poppies.json

{
  "type": "lithostitched:add_features",
  "priority": 1000,
  "biomes": "minecraft:plains",
  "features": "minecraft:flower_plain",
  "step": "vegetal_decoration"
}

The priority field determines the order in which modifiers are applied. Lower numbers = higher priority. Default is 1000.

Let’s break down the fields:

type - The modifier type. See Lithostitched.java:103-118 for all available types
priority - Execution order (optional, defaults to 1000)
biomes - Target biomes (can be a tag like #minecraft:is_overworld or single biome)
features - Features to add (can be a list or single feature)
step - Generation step (see Generation Steps)

Step 2: Test the Modifier

Load the datapack

Launch Minecraft and create a new world, or reload an existing world:

/reload

Verify in logs

Check the game logs for Lithostitched modifier loading:

[lithostitched] Loading worldgen modifiers...
[lithostitched] Loaded modifier: my_worldgen_pack:add_poppies

Generate terrain

Travel to a plains biome and observe the increased flower density.

Understanding Modifier Types

Lithostitched provides many modifier types. Here are the most commonly used:

Biome Modifiers

Add Features

Add placed features to biomes during specific generation steps:

{
  "type": "lithostitched:add_features",
  "biomes": ["minecraft:forest", "minecraft:birch_forest"],
  "features": "#my_mod:custom_trees",
  "step": "vegetal_decoration"
}

Remove Features

Remove existing features from biomes:

{
  "type": "lithostitched:remove_features",
  "biomes": "#minecraft:is_ocean",
  "features": "minecraft:seagrass_simple",
  "step": "vegetal_decoration"
}

Replace Biome Effects

Customize biome colors, particles, sounds, and music:

{
  "type": "lithostitched:replace_effects",
  "biomes": "minecraft:plains",
  "effects": {
    "grass_color": 8439583,
    "foliage_color": 6726447,
    "sky_color": 7907327,
    "fog_color": 12638463
  }
}

Structure Modifiers

Add Surface Rules

Add custom terrain generation rules:

{
  "type": "lithostitched:add_surface_rule",
  "levels": ["minecraft:overworld"],
  "surface_rule": {
    "type": "minecraft:condition",
    "if_true": {
      "type": "lithostitched:biome",
      "biomes": "minecraft:desert"
    },
    "then_run": {
      "type": "minecraft:block",
      "result_state": {
        "Name": "minecraft:red_sand"
      }
    }
  }
}

Add Template Pool Elements

Add structure pieces to jigsaw pools:

{
  "type": "lithostitched:add_template_pool_elements",
  "target": "minecraft:village/plains/houses",
  "elements": [
    {
      "element": {
        "location": "my_mod:village/plains/custom_house",
        "processors": "minecraft:empty",
        "projection": "rigid",
        "element_type": "minecraft:single_pool_element"
      },
      "weight": 1
    }
  ]
}

Advanced Example: Bandlands Terrain

Create custom banded terrain similar to badlands:

Step 1: Define the Bandlands

Create data/my_worldgen_pack/lithostitched/bandlands/custom_bands.json:

custom_bands.json

{
  "base": {
    "Name": "minecraft:terracotta"
  },
  "bands": [
    {
      "type": "lithostitched:base",
      "state": {
        "Name": "minecraft:red_terracotta"
      },
      "height": 3,
      "offset": 0
    },
    {
      "type": "lithostitched:base",
      "state": {
        "Name": "minecraft:orange_terracotta"
      },
      "height": 2,
      "offset": 3
    },
    {
      "type": "lithostitched:repeating",
      "states": [
        {
          "element": {
            "Name": "minecraft:yellow_terracotta"
          },
          "weight": 1
        },
        {
          "element": {
            "Name": "minecraft:white_terracotta"
          },
          "weight": 1
        }
      ],
      "height": 4,
      "offset": 5,
      "count": 10
    }
  ]
}

Step 2: Apply with Surface Rule

Create a modifier that uses the bandlands:

use_bandlands.json

{
  "type": "lithostitched:add_surface_rule",
  "levels": ["minecraft:overworld"],
  "surface_rule": {
    "type": "minecraft:condition",
    "if_true": {
      "type": "lithostitched:biome",
      "biomes": "minecraft:desert"
    },
    "then_run": {
      "type": "lithostitched:bandlands",
      "options": "my_worldgen_pack:custom_bands"
    }
  }
}

This creates colorful banded terrain in desert biomes, with:

3 blocks of red terracotta at the base
2 blocks of orange terracotta above
Repeating pattern of yellow and white terracotta (4 blocks high, repeating 10 times)

Generation Steps

When using feature modifiers, specify the correct generation step:

Step	Description	Examples
`raw_generation`	Terrain features	Lakes, springs
`lakes`	Lake generation	-
`local_modifications`	Local terrain edits	Amethyst geodes, icebergs
`underground_structures`	Underground features	Dungeons, monster rooms
`surface_structures`	Surface structures	Villages, temples
`strongholds`	Stronghold generation	-
`underground_ores`	Ore generation	All ores
`underground_decoration`	Underground decorations	Pointed dripstone, roots
`fluid_springs`	Spring features	Water/lava springs
`vegetal_decoration`	Plant features	Trees, flowers, grass
`top_layer_modification`	Final layer changes	Freeze top layer

Debugging Tips

Worldgen modifiers only affect newly generated chunks. Use /tp @s ~ ~ ~ to teleport to unexplored areas.

Enable Debug Logging

Create config/lithostitched.json in your instance folder:

lithostitched.json

{
  "logDebugMessages": true
}

This enables detailed logging from Lithostitched.java:234-238.

Common Issues

Modifier not loading:

Check JSON syntax with a validator
Verify file is in correct location: data/<namespace>/lithostitched/worldgen_modifier/
Check logs for parsing errors

Changes not visible:

Ensure you’re in a newly generated chunk
Verify biome selector matches target biomes
Check modifier priority doesn’t conflict with other mods

Invalid feature references:

Use /locate to verify features exist
Check feature namespaces are correct
Ensure referenced tags are defined

Next Steps

Now that you’ve created your first modifier, explore more advanced features:

Modifier Reference

Complete list of all modifier types and their options

Surface Rules

Learn about custom terrain generation with surface rules

Structure System

Advanced structure customization and processors

Common Patterns

Real-world examples and use cases

Get Started

Core Concepts

Examples & Guides

What You’ll Build

Prerequisites

Project Setup

Creating Your First Modifier

Step 1: Define the Modifier

Step 2: Test the Modifier

Understanding Modifier Types

Biome Modifiers

Add Features

Remove Features

Replace Biome Effects

Structure Modifiers

Add Surface Rules

Add Template Pool Elements

Advanced Example: Bandlands Terrain

Step 1: Define the Bandlands

Step 2: Apply with Surface Rule

Generation Steps

Debugging Tips

Enable Debug Logging

Common Issues

Next Steps

Modifier Reference

Surface Rules

Structure System

Common Patterns

Build docs developers (and LLMs) love

Get Started

Core Concepts

Examples & Guides

​What You’ll Build

​Prerequisites

​Project Setup

​Creating Your First Modifier

​Step 1: Define the Modifier

​Step 2: Test the Modifier

​Understanding Modifier Types

​Biome Modifiers

​Add Features

​Remove Features

​Replace Biome Effects

​Structure Modifiers

​Add Surface Rules

​Add Template Pool Elements

​Advanced Example: Bandlands Terrain

​Step 1: Define the Bandlands

​Step 2: Apply with Surface Rule

​Generation Steps

​Debugging Tips

​Enable Debug Logging

​Common Issues

​Next Steps

Modifier Reference

Surface Rules

Structure System

Common Patterns

Build docs developers (and LLMs) love

What You’ll Build

Prerequisites

Project Setup

Creating Your First Modifier

Step 1: Define the Modifier

Step 2: Test the Modifier

Understanding Modifier Types

Biome Modifiers

Add Features

Remove Features

Replace Biome Effects

Structure Modifiers

Add Surface Rules

Add Template Pool Elements

Advanced Example: Bandlands Terrain

Step 1: Define the Bandlands

Step 2: Apply with Surface Rule

Generation Steps

Debugging Tips

Enable Debug Logging

Common Issues

Next Steps