BetterStructures

BetterStructures is a generator-agnostic topology scanner that finds optimal placement locations for custom structures based on geometry and block characteristics. The plugin pastes schematics into your world with terrain adaptation methods that preserve the natural look of your world.

The plugin uses advanced scanning to measure terrain compatibility and adapts structures to fit seamlessly into existing worlds. It supports pedestals, special blocks, and intelligent pasting that makes structures look natural in any environment.

Getting Started

Requirements

Required:

WorldEdit or FastAsyncWorldEdit (one must be installed)
Minecraft 1.14+ (Paper recommended)

Optional:

EliteMobs (for boss encounters in structures)
WorldGuard (for region protection)
Custom world generators (Terralith, Iris, Terra, TerraformGenerator)

Installation

Install WorldEdit or FastAsyncWorldEdit on your server
Download BetterStructures and place it in your plugins folder
Download structure packs:
- Free packs: magmaguy.itch.io (103+ structures available)
- Premium packs: patreon.com/magmaguy
Extract downloaded structure files to ~/plugins/BetterStructures/imports
Start your server or run /betterstructures reload

The plugin automatically processes imported structures and makes them available for generation.

Quick Start

After installation, structures spawn automatically in your world based on their configured settings. To test structure placement or manage the plugin, use the commands listed below.

Commands

All commands use the base /betterstructures or alias /bs.

Command	Description	Permission
`/betterstructures`	Main command	None
`/betterstructures reload`	Reload all configurations	betterstructures.*
`/betterstructures place <name> <type>`	Test structure placement at your location	betterstructures.*
`/betterstructures lootify`	Add custom items to loot tables	betterstructures.*
`/betterstructures setup`	Run setup process	betterstructures.setup
`/betterstructures initialize`	Initialize the plugin	betterstructures.initialize
`/betterstructures generatemodules`	Generate modular dungeons (normal speed)	betterstructures.generatemodules
`/betterstructures generatemodules slowly`	Generate modular dungeons slowly (low server impact)	betterstructures.generatemodules.slowly
`/betterstructures generatemodules instantly`	Generate modular dungeons instantly (high server impact)	betterstructures.generatemodules.instantly
`/betterstructures teleport`	Teleport to structure locations	betterstructures.*
`/betterstructures version`	Display plugin version	None
`/betterstructures silent`	Toggle silent mode	betterstructures.*

Permissions

All permissions default to op (server operators only).

Permission	Description	Default
`betterstructures.setup`	Access to setup command	op
`betterstructures.initialize`	Access to initialize command	op
`betterstructures.generatemodules`	Access to standard module generation	op
`betterstructures.generatemodules.slowly`	Access to slow module generation	op
`betterstructures.generatemodules.instantly`	Access to instant module generation	op

Structure Types

BetterStructures supports six structure types, each with different placement rules and spawn locations.

SURFACE

Spawns structures on the ground surface, adapting to terrain elevation. The plugin scans for flat or compatible areas and places structures with automatic terrain blending.

Default spacing: 31 blocks between structures

SKY

Places structures floating in the air at high altitudes.

Altitude range:

Overworld: 80-120 blocks
End: 80-120 blocks

Default spacing: 95 blocks between structures

UNDERGROUND_SHALLOW

Generates structures in shallow underground areas near the surface.

Y-level range (Overworld): 0 to 60

Default spacing: 22 blocks between structures

UNDERGROUND_DEEP

Creates structures in deep underground locations, including deep caves and caverns.

Y-level range (Overworld): -64 to 0

Default spacing: 22 blocks between structures

LIQUID_SURFACE

Spawns structures on water or lava surfaces, perfect for ocean monuments or floating bases.

Default spacing: 65 blocks between structures

DUNGEON

Generates modular procedural dungeons using Wave Function Collapse algorithm. These structures connect multiple modules to create complex underground systems.

Default spacing: 80 blocks between structures

Configuration

Main Config (config.yml)

The main configuration file contains global settings that apply to all structures.

Y-Level Ranges

Control the height limits for structure generation in different dimensions.

# Overworld/Custom Worlds
lowestYNormalCustom: -60
highestYNormalCustom: 320

# Nether
lowestYNether: 4
highestYNether: 120

# End
lowestYEnd: 0
highestYEnd: 320

Air Building Altitudes

Set the altitude ranges for sky-based structures.

# Overworld/Custom Worlds
normalCustomAirBuildingMinAltitude: 80
normalCustomAirBuildingMaxAltitude: 120

# End
endAirBuildMinAltitude: 80
endAirBuildMaxAltitude: 120

Structure Spacing

Define minimum distances between structures of each type.

distanceSurface: 31        # Surface structures
distanceShallow: 22        # Shallow underground
distanceDeep: 22           # Deep underground
distanceSky: 95            # Sky structures
distanceLiquid: 65         # Liquid surface
distanceDungeon: 80        # Dungeons

Spacing Randomization

Add random offset to structure placement to prevent grid patterns.

maxOffsetSurface: 5        # ±5 blocks for surface
maxOffsetShallow: 5        # ±5 blocks for shallow
maxOffsetDeep: 5           # ±5 blocks for deep
maxOffsetSky: 5            # ±5 blocks for sky
maxOffsetLiquid: 5         # ±5 blocks for liquid
maxOffsetDungeon: 18       # ±18 blocks for dungeons

Admin Notifications

warnAdminsAboutNewBuildings: true  # Notify admins when structures spawn

Schematic Configuration

Each schematic has its own configuration file in ~/plugins/BetterStructures/schematics/.

Available settings:

isEnabled: Enable or disable this schematic (default: true)
weight: Selection probability when multiple schematics are available (default: 1.0)
generatorConfigFilename: Links to the generator configuration that controls where this structure spawns
pedestalMaterial: Block type used for pedestals under the structure
treasureFile: Custom loot table configuration for chests in this structure

Generator Configuration

Generator configs control where and when structures spawn. Files are located in ~/plugins/BetterStructures/generators/.

Available settings:

structureType: One of the six types (SURFACE, SKY, UNDERGROUND_SHALLOW, UNDERGROUND_DEEP, LIQUID_SURFACE, DUNGEON)
lowestYLevel: Minimum spawn height (default: -59)
highestYLevel: Maximum spawn height (default: 320)
validWorlds: List of world names where this structure can spawn (empty = all worlds)
validWorldEnvironments: Filter by environment type (NORMAL, NETHER, THE_END)
validBiomes: List of biomes where structure can spawn (supports namespace format like minecraft:plains)
treasureFilename: Loot table reference for chests in this structure

Treasure Configuration

Treasure configs define loot tables for structure chests. Files are located in ~/plugins/BetterStructures/treasures/.

Available settings:

mean: Average number of items per chest (default: 4.0)
standardDeviation: Variation in item quantities (default: 3.0)
rawLoot: Item pools organized by rarity level
chestEntries: Specific items with amount ranges and spawn chances

Enchantment configuration:

Each material can have enchantment rules:

minLevel: Minimum enchantment level
maxLevel: Maximum enchantment level
chance: Probability of applying enchantment (0.0 to 1.0)

Special Blocks

BetterStructures uses special blocks in schematics to control pasting behavior and add functionality.

Barrier Blocks

Barrier blocks tell the plugin to skip pasting at that location, preserving the original world generation.

Use cases:

Create natural-looking edges that blend with terrain
Preserve existing caves or features
Round structure corners to match landscape

Bedrock Blocks

Bedrock blocks guarantee solid flooring beneath the structure.

Behavior:

If a solid block exists at that location, leave it unchanged
If the block is air or liquid, replace it with the pedestal material

Use cases:

Create defined pathways without overriding natural terrain
Ensure structures have stable foundations
Add features like minecart rails or bridges that require solid blocks

Spawn Signs

Spawn signs create mob spawns at specific locations in your structures. Signs are removed when the structure is pasted.

Vanilla Mobs

[spawn]
ZOMBIE

Format:

Line 1: [spawn]
Line 2: Entity type (use Spigot API names like ZOMBIE, SKELETON, CREEPER)

EliteMobs Integration

[elitemobs]
boss_filename.yml

Format:

Line 1: [elitemobs]
Line 2+: Boss configuration filename

Creates boss encounters with WorldGuard protection. The protected region remains until players defeat the boss.

MythicMobs Integration

[mythicmobs]
mob_identifier
5

Format:

Line 1: [mythicmobs]
Line 2: MythicMobs mob ID
Line 3: Mob level (optional)

Plugin Integration

EliteMobs

BetterStructures integrates with EliteMobs to create boss arenas and combat encounters.

Features:

Spawn EliteMobs bosses in structures using spawn signs
Automatic region protection during boss fights
Protection removal when boss is defeated

Configuration:

protectEliteMobsRegions: true  # Enable EliteMobs region protection

WorldGuard

WorldGuard integration provides region protection and placement control.

Features:

Custom flags for structure placement
Region protection capabilities
Compatibility with WorldGuard-protected areas

WorldEdit / FastAsyncWorldEdit

WorldEdit or FastAsyncWorldEdit is required for schematic pasting operations.

Requirements:

Install one (not both) of these plugins
Version compatibility is critical - use versions matching your server
FastAsyncWorldEdit is recommended for large structures on busy servers

World Generators

BetterStructures works with custom world generators:

Supported generators:

Terralith
Iris
Terra
TerraformGenerator

These integrations enable structure generation in custom biomes and terrain types.

Performance Tuning

Adjust these settings in config.yml to optimize performance for your server.

Chunk Pasting Speed

modularChunkPastingSpeed: 10

Controls how fast modular structures paste. Higher values paste faster but use more server resources.

Recommended values:

Small servers (1-10 players): 10-15
Medium servers (10-50 players): 5-10
Large servers (50+ players): 3-5

Tick Usage Percentage

percentageOfTickUsedForPasting: 0.2

Limits the percentage of each server tick used for pasting operations. Default is 0.2 (20% of tick time).

Recommended values:

High-performance servers: 0.3-0.4 (30-40%)
Standard servers: 0.2 (20%)
Busy servers with TPS issues: 0.1-0.15 (10-15%)

Module Generation Speed

When using /betterstructures generatemodules, you have three speed options:

Normal: /betterstructures generatemodules Balanced generation speed with moderate server impact.

Slowly: /betterstructures generatemodules slowly Minimal server impact, best for busy servers or during peak hours.

Instantly: /betterstructures generatemodules instantly Maximum speed, high server impact. Use only during low-traffic periods.

Developer API

BetterStructures provides two events for plugin developers to interact with structure generation.

BuildPlaceEvent

Fires when a structure is about to be placed in the world.

Package: com.magmaguy.betterstructures.api.BuildPlaceEvent

Event type: Cancellable

Use cases:

Validate structure placement
Implement custom permission checks
Prevent placement in specific areas
Log structure generation

Important: Do not modify the build object itself. The event exposes the FitAnything object, but modifying the entire build can cause poor terrain fitting. Only make minor adjustments if necessary.

ChestFillEvent

Fires when chests in structures are being populated with loot.

Package: com.magmaguy.betterstructures.api.ChestFillEvent

Event type: Cancellable

Use cases:

Add custom items to structure loot
Modify or remove generated loot
Implement custom loot logic
Track chest contents

Usage: Modify loot by using addItem() and removeItem() methods on the snapshot inventory. Do not directly manipulate the chest container.

Maven Dependency

BetterStructures does not currently have a Maven repository. To use the API, manually import the plugin jar into your project.

<dependency>
    <groupId>com.magmaguy</groupId>
    <artifactId>BetterStructures</artifactId>
    <version>2.0.3</version>
    <scope>provided</scope>
</dependency>

Add the plugin jar to your project's build path and mark it as a provided dependency in your plugin.yml.

Additional Resources

Official GitHub Wiki: github.com/MagmaGuy/BetterStructures/wiki

Structure Downloads:

Free packs: magmaguy.itch.io
Premium packs: patreon.com/magmaguy

Plugin Page: spigotmc.org/resources/betterstructures.103241

Support: Visit the official GitHub repository or SpigotMC resource page for support and bug reports.

Getting Started​

Requirements​

Installation​

Quick Start​

Commands​

Permissions​

Structure Types​

SURFACE​

SKY​

UNDERGROUND_SHALLOW​

UNDERGROUND_DEEP​

LIQUID_SURFACE​

DUNGEON​

Configuration​

Main Config (config.yml)​

Y-Level Ranges​

Air Building Altitudes​

Structure Spacing​

Spacing Randomization​

Admin Notifications​

Schematic Configuration​

Generator Configuration​

Treasure Configuration​

Special Blocks​

Barrier Blocks​

Bedrock Blocks​

Spawn Signs​

Vanilla Mobs​

EliteMobs Integration​

MythicMobs Integration​

Plugin Integration​

EliteMobs​

WorldGuard​

WorldEdit / FastAsyncWorldEdit​

World Generators​

Performance Tuning​

Chunk Pasting Speed​

Tick Usage Percentage​

Module Generation Speed​

Developer API​

BuildPlaceEvent​

ChestFillEvent​

Maven Dependency​

Additional Resources​

Getting Started

Requirements

Installation

Quick Start

Commands

Permissions

Structure Types

SURFACE

SKY

UNDERGROUND_SHALLOW

UNDERGROUND_DEEP

LIQUID_SURFACE

DUNGEON

Configuration

Main Config (config.yml)

Y-Level Ranges

Air Building Altitudes

Structure Spacing

Spacing Randomization

Admin Notifications

Schematic Configuration

Generator Configuration

Treasure Configuration

Special Blocks

Barrier Blocks

Bedrock Blocks

Spawn Signs

Vanilla Mobs

EliteMobs Integration

MythicMobs Integration

Plugin Integration

EliteMobs

WorldGuard

WorldEdit / FastAsyncWorldEdit

World Generators

Performance Tuning

Chunk Pasting Speed

Tick Usage Percentage

Module Generation Speed

Developer API

BuildPlaceEvent

ChestFillEvent

Maven Dependency

Additional Resources