PatternBuilder

Pattern Builder - Automated Pattern Placement

A relatively simple mod that automates the placement of repeating block patterns (roads, walls, tunnels, etc) to reduce late-game construction tedium.

This is also survival-mode friendly, taking blocks out of the player's inventory and using their tools to mine/dig. 

Feature Status (roadmap)

DONE

• Define custom block patterns in JSON files to place in world
• Multi-pattern system with JSON configs (can hot-reload in-game)
• Adaptive roads vs tunnel carving (additive vs destructive)
• Pattern validation
• Survival mode support with inventory consumption
• 3D patterns
• Pattern preview - ghost images two steps in front of the user
• Directional block support: Use relative directions (|f|b|l|r) in patterns - adapts to travel direction
• Terrain following - roads adapt to elevation changes with stairs (walk, don't sprint on slopes)
• Tool durability use - carve mode consumes tools and harvests blocks in survival mode

PLANNED

• Fix adaptive roads as they have somewhat broken with the 1.22 update
• In-game editor

Commands

.pb              Show command help (default)
.pb help         Show command help
.pb toggle       Toggle pattern building on/off
.pb on/off       Enable/disable building mode
.pb list         Show available patterns
.pb slot X     Switch to pattern at slot X (1-50)
.pb info         Show current pattern details
.pb reload       Reload patterns from disk
.pb preview      Toggle pattern preview on/off

Creative Mode:

1. Type .pb on to enable building mode
2. Walk forward - patterns will be placed ahead of you
3. Switch patterns with .pb slot <number>
4. No materials consumed from inventory

Survival Mode:

1. Gather blocks needed for your pattern (check with .pb info)
2. For carve mode patterns: ensure you have appropriate tools (pickaxe for stone, shovel for soil/gravel)
3. Type .pb on to enable building mode
4. Walk forward - blocks consumed from inventory as you build
5. Use wildcard patterns (game:soil-*) for flexibility
6. Auto-disables when out of materials or tools (shows clear message)

Tips:

• Edit pattern JSON files in the config directory
• Reload patterns with .pb reload after editing
• Use .pb info to see current pattern details and material requirements
• Walking over existing patterns won't waste materials
• Enable preview with .pb preview to see what will be placed before it happens
• Terrain following: Walk (don't sprint) on slopes for best stair placement. Sprinting downhill may skip some stairs.
• Carve mode: Mod searches hotbar first, then full inventory for tools. If a tool breaks mid-tunnel, it automatically switches to a replacement if available.

Pattern Preview:

• Preview appears 2 blocks ahead of your movement
• Green tint: Placing in air (safe)
• Blue tint: Replacing existing blocks (intentional)
• Grey tint: Replacing with same block (no extra consumption)
• Works with both 2D and 3D patterns (shows current slice)
• Toggle on/off anytime with .pb preview

Pattern Files

Patterns are stored (for now) as JSON files at either of the following locations:

# MacOS:
~/Library/Application Support/VintagestoryData/ModConfig/patternbuilder/patterns/

# Windows:
%APPDATA%\VintagestoryData\ModConfig\patternbuilder\patterns\

File naming convention:

Pattern files must be named something like slotN_name.json where N is 1-50 (e.g., slot1_road.json, slot2_path.json).

There will already be a handful of example patterns that populate the directory on launch of the mod. You can change the pattern content of these but the mod will try to place that filename back each time a world is loaded.

Pattern syntax:

• Slices: Array of 2D patterns (one entry = 2D pattern, multiple entries = 3D pattern)
• Each slice uses comma-separated Y-layers (bottom to top)
• Each character maps to a block code
• _ = air/empty (carve mode will replace blocks with air, adaptive will leave untouched)
• P = player feet position (required in each slice for Y-offset)
• * = wildcard (matches any variant, e.g., game:soil-*)
• Mode = "adaptive" (moulds to terrain) or "carve" (cuts through terrain)
• TransitionUpLayer = Pattern for ascending slopes (optional, uses stairs facing forward |f)
• TransitionDownLayer = Pattern for descending slopes (optional, uses stairs facing backward |b)

3D pattern behaviour:

• Walk forward: cycles through slices (0,1,2...,N,0)
• Walk backward: reverses through slices (N,...,2,1,0,N)
• Turn left/right: maintains current slice (no slice change)
• Pattern switch: resets to slice 0

Directional behaviour:

I have a custom system for directional blocks that tries to use the appropriate cardinal direction block depending on what direction you are currently travelling.

• If a pattern has either "l" or "r" at the end of the block code it will attempt to place a "left" or "right" oriented block. This means stairs will slope down away from the player
• If a pattern has either "f" or "b" at the end of the block code it will attempt to place a "forward" or "backward" oriented block. This means the player can continue walking forward onto and up stairs
• If a pattern has "auto" it will try to snap to the appropriate direction based on its neighbours. This really only works for fences and wall blocks. 

Can you show me some examples of patterns?

This can get a little complicated, please let me know if things need to be more clear.

The patterns all use the game "block codes" so the wiki entry on this is incredibly valuable.

{
  "Name": "Default Road",
  "Description": "3-wide gravel road with dirt foundation",
  "Slices": [ "DDD,GGG,_P_,___" ],
  "Width": 3,
  "Height": 4,
  "Mode": "adaptive",
  "Blocks": {
    "D": "game:soil-medium-normal",
    "G": "game:gravel-granite",
    "P": "player"
  }
}

{
  "Name": "Lamp Post Road",
  "Description": "3-wide gravel road with lamp posts every 8 blocks",
  "Slices": [
    "DDD,GGG,_P_,___,___",
    "DDD,GGG,_P_,___,___",
    "DDD,GGG,_P_,___,___",
    "DDD,GGG,_P_,___,___",
    "DDD,GGG,_P_,___,___",
    "DDD,GGG,_P_,___,___",
    "DDD,GGG,_P_,___,___",
    "DDD,GGG,WPW,W_W,L_L"
  ],
  "Width": 3,
  "Height": 5,
  "Blocks": {
    "D": "game:soil-medium-normal",
    "G": "game:gravel-granite",
    "W": "game:woodenfence-oak-empty-free|auto",
    "L": "game:paperlantern-on",
    "P": "player"
  }
}

{
  "Name": "Flexible Road",
  "Description": "Works with ANY soil and gravel variants",
  "Slices": [ "SSSSS,GGGGG,__P__,_____" ],
  "Width": 5,
  "Height": 4,
  "Mode": "adaptive",
  "Blocks": {
    "S": "game:soil-*",
    "G": "game:gravel-*",
    "P": "player"
  }
}

{
  "Name": "Fenced Road",
  "Description": "Road with auto-connecting oak fences on sides",
  "Slices": [ "FGF,FGF,_P_,___" ],
  "Width": 3,
  "Height": 4,
  "Blocks": {
    "F": "game:woodenfence-oak|auto",
    "G": "game:gravel-granite",
    "P": "player"
  }
}

{
  "Name": "Stair Edged Road",
  "Description": "Road with stairs stepping down on each side",
  "Slices": [ "GGG,LGR,_P_,___" ],
  "Width": 3,
  "Height": 4,
  "Blocks": {
    "L": "cobblestonestairs-*|up|l",
    "R": "cobblestonestairs-*|up|r",
    "G": "game:gravel-granite",
    "P": "player"
  }
}

{
  "Name": "Adaptive Road with Stairs",
  "Description": "Road that adapts to terrain with stair transitions",
  "Slices": ["DDD,CCC,_P_,___"],
  "Width": 3,
  "Height": 4,
  "Mode": "adaptive",
  "Blocks": {
    "D": "game:soil-medium-normal",
    "C": "game:cobblestone-granite",
    "P": "player"
  },
  "TransitionUpLayer": {
    "Slices": ["DDD,SSS,_P_,___"],
    "Width": 3,
    "Height": 4,
    "Mode": "carve",
    "Blocks": {
      "D": "game:soil-medium-normal",
      "S": "game:cobblestonestairs-*|up|f",
      "P": "player"
    }
  },
  "TransitionDownLayer": {
    "Slices": ["DDD,SSS,_P_,___"],
    "Width": 3,
    "Height": 4,
    "Mode": "carve",
    "Blocks": {
      "D": "game:soil-medium-normal",
      "S": "game:cobblestonestairs-*|up|b",
      "P": "player"
    }
  }
}

Configuration

PatternBuilder uses a server-controlled configuration file for tool durability settings.

Location:

• MacOS: ~/Library/Application Support/VintagestoryData/ModConfig/patternbuilder/patternbuilder.json
• Windows: %APPDATA%\VintagestoryData\ModConfig\patternbuilder\patternbuilder.json

Default configuration:

{
  "requireToolsForCarving": true,
  "harvestCarvedBlocks": true,
  "durabilityPerBlock": 1
}

Settings:

• requireToolsForCarving (default: true) - Enable/disable tool durability consumption for carve mode patterns
• harvestCarvedBlocks (default: true) - Whether to harvest broken blocks into player inventory
• durabilityPerBlock (default: 1) - Tool durability cost per block broken

Notes:

• Config is server-authoritative (prevents client-side cheating in multiplayer)
• Changes require server restart to take effect
• Creative mode always bypasses tool requirements regardless of config

Known issues

Please see the ROADMAP.md file on GitHub for a list of known issues

The GitHub README.md also has more information if you are running into troubleshooting issues and need help. 

Misc

I know similar behaviour can be done with world-edit but I feel like this still adds to the community through the survial-friendly adaption. 

Thumbnail icon was made using the FOSS tool Goxel

The inspiration for this mod comes from the MC Bukkit Plugin "LazyRoad"