Developer API

Requirements

BetterStructures requires:

• Java 21 or higher
• Spigot/Paper server
• WorldEdit plugin (hard dependency)

Optional dependencies:

• WorldGuard - For region protection features (requires EliteMobs to also be installed for full integration)
• EliteMobs - For elite mob spawning integration
• MythicMobs - For mythic mob integration
• Terralith, Iris, Terra, TerraformGenerator - For custom biome compatibility

Public Repository

Maven

<repositories>
    <repository>
        <id>magmaguy-repo-releases</id>
        <name>MagmaGuy's Repository</name>
        <url>https://repo.magmaguy.com/releases</url>
    </repository>
</repositories>

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

Note: Visit https://repo.magmaguy.com/releases/com/magmaguy/BetterStructures to see available versions. Latest stable: 2.3.0

Gradle

repositories {
  maven {
    name = "magmaguyRepoReleases"
    url = uri("https://repo.magmaguy.com/releases")
  }
}

dependencies {
    implementation 'com.magmaguy:BetterStructures:2.3.0'
}

Note: Visit https://repo.magmaguy.com/releases/com/magmaguy/BetterStructures to see available versions. Latest stable: 2.3.0

Events

Note: Events are in com.magmaguy.betterstructures.api

Package Imports

import com.magmaguy.betterstructures.api.BuildPlaceEvent;
import com.magmaguy.betterstructures.api.ChestFillEvent;
import com.magmaguy.betterstructures.api.WorldGenerationFinishEvent;
import com.magmaguy.betterstructures.buildingfitter.FitAnything;
import com.magmaguy.betterstructures.modules.ModularWorld;
import com.magmaguy.betterstructures.thirdparty.WorldGuard;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

BuildPlaceEvent

Called when a build is about to be placed. Exposes data about which build is going to be placed and where, among other things, through the FitAnything object.

Don't attempt to modify the build getting placed! You can modify minor things, but changing the whole build will probably result in a build with a poor fit.

This is cancellable.

ChestFillEvent

Called when a chest is filled. Uses the container snapshot inventory to safely store the data to be applied.

You can modify the loot using the Inventory methods addItem() or removeItem() on the container's snapshot inventory obtained via getContainer().getSnapshotInventory().

You can also call getTreasureConfigFilename() to identify which loot table configuration was used to fill this chest.

This is cancellable.

WorldGenerationFinishEvent

Called when world generation finishes. Provides access to the ModularWorld object containing all data about the generated world including spawn points, chest locations, and exit points.

This event is NOT cancellable.

You can access world data through the getModularWorld() method. See the ModularWorld section below for all available methods.

Example Event Listener

public class MyBetterStructuresListener implements Listener {

    @EventHandler
    public void onBuildPlace(BuildPlaceEvent event) {
        FitAnything build = event.getFitAnything();
        Location location = build.getLocation();
        // Custom logic here
        // event.setCancelled(true); // To prevent placement
    }

    @EventHandler
    public void onChestFill(ChestFillEvent event) {
        Container container = event.getContainer();
        Inventory inv = container.getSnapshotInventory();
        // Modify inventory here
        inv.addItem(new ItemStack(Material.DIAMOND, 1));
    }

    @EventHandler
    public void onWorldGenFinish(WorldGenerationFinishEvent event) {
        ModularWorld world = event.getModularWorld();
        // Access generated world data
        List<Location> spawns = world.getSpawnLocations();
    }
}

Key classes

FitAnything

The FitAnything class is the class that gets instantiated when a build gets pasted in and handles every aspect of the paste, including filling chests and spawning mobs.

Available getter methods:

• getSchematicContainer() - Returns the schematic container
• getSchematicClipboard() - Returns the WorldEdit Clipboard object
• getSchematicOffset() - Returns the Vector offset for placement
• getLocation() - Returns the placement Location

These methods are useful when creating custom region protections or analyzing build placements.

ModularWorld

The ModularWorld class represents a generated modular world and is provided through the WorldGenerationFinishEvent. It contains all location data and methods for spawning entities and containers in the generated world.

Key methods:

• getWorld() - Returns the Bukkit World instance
• getWorldFolder() - Returns the world's File folder
• getSpawnLocations() - Returns all marked spawn locations (List<Location>)
• getChestLocations() - Returns all chest spawn locations (List<Location>)
• getBarrelLocations() - Returns all barrel spawn locations (List<Location>)
• getExitLocations() - Returns all exit point locations (List<ExitLocation>)
• spawnChests() - Spawns chests at marked locations, returns List<Block>
• spawnBarrels() - Spawns barrels at marked locations, returns List<Block>
• spawnInaccessibleExitLocations() - Spawns upper elevator schematics, returns List<Location>
• spawnAccessibleExitLocations() - Spawns lower elevator schematics, returns List<Location>
• spawnOtherEntities() - Spawns custom entities from spawn pools
• spawnInstancedEntities(MatchInstance) - Spawns instanced boss entities, returns List<InstancedBossEntity>

WorldGuard

The WorldGuard class handles the WorldGuard region protections. The utility method public static ProtectedRegion generateProtectedRegion(FitAnything fitAnything, String regionName) is made available for developers to easily hook in a custom region protection scheme on top of BetterStructures.

Other useful methods:

• checkArea(Location, Player) - Check if a location is in a BetterStructures-protected region (returns true if protected, sends a warning message to the player)
• Protect(...) - Create protected regions programmatically
• Unprotect(CustomBossEntity) - Remove region protection when a boss is killed