Skip to main content

Developer API

Requirements​

BetterStructures requires:

  • Java 17 or higher
  • Spigot/Paper server
  • WorldEdit plugin (7.3.0+)

Optional dependencies:

  • WorldGuard (7.0.7+) - For region protection features
  • EliteMobs - For elite mob spawning integration
  • MythicMobs - For mythic mob integration

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.0.4</version>
  <scope>provided</scope>
</dependency>

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

Gradle

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

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

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

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().

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, which provides:

  • getWorld() - The Bukkit World object
  • getSpawnLocations() - List of spawn point locations
  • getChestLocations() - List of chest locations
  • getBarrelLocations() - List of barrel locations
  • getExitLocations() - List of exit point locations
  • spawnChests() - Manually spawn chests at marked locations
  • spawnBarrels() - Manually spawn barrels at marked locations

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
  • getChestLocations() - Returns all chest spawn locations
  • getBarrelLocations() - Returns all barrel spawn locations
  • getExitLocations() - Returns all exit point locations
  • spawnChests() - Spawns chests at marked locations, returns List of Block
  • spawnBarrels() - Spawns barrels at marked locations, returns List of Block
  • spawnInaccessibleExitLocations() - Spawns upper elevator schematics
  • spawnAccessibleExitLocations() - Spawns lower elevator schematics
  • spawnOtherEntities() - Spawns custom entities from spawn pools

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 player can build at a location
  • Protect(...) - Create protected regions programmatically
  • Unprotect(CustomBossEntity) - Remove region protection