Developer API

CustomStructures provides a robust API allowing developers to support CustomStructures features. Server developers can also use the API to modify the functionality of the plugin to better suite their needs.

Checkout the JavaDoc here.

Major API Features:

• Custom Structure Addon
• Bottom Fill Implementation
• Custom Structure Signs
• Custom Loot Tables or Loot Items

Adding as a Dependency

You can use Maven or Gradle to add CustomStructures as a dependency to access its API.

Maven

First add my repository:

<repositories>
    <repository>
        <id>Ryandw11 Repo</id>
        <url>https://repo.ryandw11.com/repository/maven-releases/</url>
    </repository>
</repositories>

Then add the dependency:

<dependency>
  <groupId>com.ryandw11</groupId>
  <artifactId>CustomStructures</artifactId>
  <version>1.9.0</version>
  <scope>provided</scope>
</dependency>

Gradle

First add my repository:

repositories {
    maven { url 'https://repo.ryandw11.com/repository/maven-releases/' }
}

Then add the dependency:

dependencies {
    implementation 'com.ryandw11:CustomStructures:1.9.0'
}

Generic API Features

The base way to access CustomStructures' many API features is through the CustomStructuresAPI class. You can obtain many of the important handlers and register a Custom Addon.

CustomStructuresAPI customStructuresAPI = new CustomStructuresAPI();
StructureHandler structureHandler = customStructuresAPI.getStructureHandler();

If you want to access more features than the API class offers, you can also access all plugin handlers from the main CustomStructures class.

CustomStructures customStructures = CustomStructures.getInstance();
StructureHandler structureHandler = customStructures.getStructureHandler();

CustomStructures allows plugins to extend CustomStructures' functionality by registering itself as an addon.
See the main wiki page here.

Accessing Structures

A common way to use the API is to access a structure. All structures can be accessed through the StructureHandler. The StructureHandler class contains methods the following methods:

• getStructure(String)
• getStructures()
• getStructureNames()

You can use these methods to obtain a list of or a specific Structure. The Structure class is read-only and contains the properties of the structure. It is important not to save a persistent instance of a structure class since the object can be invalidated after a plugin reload. The properties of a Structure are stored in the same way they are presented in the structure configuration file.

Obtaining a Property

    public boolean canSpawnInBiome(String structureName, Biome biome) {
        CustomStructuresAPI customStructuresAPI = new CustomStructuresAPI();
        Structure structure = customStructuresAPI.getStructureHandler().getStructure(structureName);

        StructureLocation structureLocation = structure.getStructureLocation();
        return structureLocation.hasBiome(biome);
    }

Spawning a Structure

You can spawn a structure using the #spawn() method.

CustomStructuresAPI customStructuresAPI = new CustomStructuresAPI();
Structure structure = customStructuresAPI.getStructureHandler().getStructure("MyStructure");
structure.spawn(loc);

Creating Structures

The StructureBuilder class is used to create a Structure programmatically.

Persistent Structure Storage

When enabled by the server owner, CustomStructures keeps track of all structures that are spawned in a SQLite database. This database is used by the /cstruct nearby command. Plugins can access this database through the StructureDatabaseHandler. The structure database handler can be accessed through the StructureHandler.

The way the StructureDatabaseHandler is that you send a request to it, and it will process it asynchronously, returning the data in a CompletableFuture. The following requests are available:

• getStructure(Location)
• findNearby(NearbyStructureRequest)
• getStructureLocations(Structure)

Example:

public class Example {
    public void printStructuresWithXBlocks(Player player, int limit, int distance) {
        CustomStructuresAPI csAPI = new CustomStructuresAPI();
        StructureDatabaseHandler structDbHandler = csAPI.getStructureHandler().getStructureDatabaseHandler().orElseThrow();

        NearbyStructuresRequest request = new NearbyStructuresRequest(player.getLocation(), limit);
        structDbHandler.findNearby(request).thenAccept( response -> {
            response.getResponse().stream()
                    .filter(container -> container.getDistance() < distance)
                    .map(container -> container.getLocation())
                    .forEach(location -> player.sendMessage(String.format("%sFound Structure: (%d, %d, %d)",
                            ChatColor.GREEN,
                            location.getBlockX(),
                            location.getBlockY(),
                            location.getBlockZ())
                    ));
        });
    }
}