Custom Structure Addons

CustomStructure Addons allow developers to introduce custom functionality to interface their plugin with CustomStructures. An addon allows developers to add the following:

1. A custom Structure Property Section.
2. A custom Structure Configuration Sign.
3. A custom LootTable.
4. A custom Config Loot Item type.

Creating an Addon

To create an addon you need to use the CustomStructureAddon class to create an addon in the onEnable method of your plugin. An instance of your plugin is required by the constructor. The name and authors of a plugin are automatically obtained from the plugin. Register the addon using the method provided in the CustomStructuresAPI class.

@Override
public void onEnable() {
    CustomStructureAddon myAddon = new CustomStructureAddon(this);

    CustomStructuresAPI customStructuresAPI = new CustomStructuresAPI();
    customStructuresAPI.registerCustomAddon(myAddon);
}

Creating a Structure Property Section

In order to implement custom spawn functionality for structures you need to create a Structure Section. You can do that by implementing the StructureSection interface.

public class ExampleSection implements StructureSection {
    private boolean enabled;

    public ExampleSection() {
        this.enabled = true;
    }

    @Override
    public String getName() {
        return "ExampleSection";
    }

    @Override
    public void setupSection(@Nullable ConfigurationSection configurationSection) {
        if(configurationSection == null) return;

        if(configurationSection.contains("Enabled")) {
            enabled = configurationSection.getBoolean("Enabled");
        }
    }

    @Override
    public boolean checkStructureConditions(Structure structure, Block block, Chunk chunk) {
        Bukkit.getLogger().info("Check Condition for structure " + structure.getName());
        return enabled;
    }
}

The getName() method returns the name of the configuration section. This needs to be a YAML friendly name so users can use it in their structure config file. It is best practice to put your plugin name in front of the section name so users know where the section is from.

The setupSection() method is called when the plugin reads the Structure configuration files and needs to setup section data. The provided configuration section is already inside the YAML section. configurationSection is null if your section does not exist in the configuration file. (This method is not called if the StructureSection is added via the developer API.)

The checkStructureConditions is called when the structure is preparing to be spawned. The structure, spawn block, and spawn chunk are provided. All of the default conditions built into the plugin have already been checked by the time this method is called. The return value determines if the structure is able to spawn. (True if passes the tests and could spawn, false if it fails). (Returning false does not mean another structure can't spawn in the same chunk. The structure picker code will check the next structure in line if the current one fails).

Important Information

When creating a StructureSection it is important to have a constructor with no parameters. The constructor must also provide the default values for the section. A second constructor with parameters can be added for other developers to use.

Yaml Configuration

The example StructureSection above can be configured by adding the following section to the structure.yml file.

ExampleSection:
    Enabled: false

Registering a Structure Section

A StructureSection can be registered to an addon by using the addStructureSection method on the addon class.

@Override
public void onEnable() {
    CustomStructureAddon myAddon = new CustomStructureAddon(this);
    myAddon.addStructureSection(ExampleSection.class);

    CustomStructuresAPI customStructuresAPI = new CustomStructuresAPI();
    customStructuresAPI.registerCustomAddon(myAddon);
}

You can register as many StructureSections as you want.

Other Notes

Be sure to add CustomStructures to the depends or softdepends list in your plugin.yml file.

Addons that are in use are tracked by bstats.