API

Overview

ProCosmetics provides a developer API that allows other plugins to integrate with and extend its features.

Adding ProCosmetics to your project

The API artefact is published to the FilleDev repository.

Maven Setup

Repository

<repositories>
    <repository>
        <id>filledev-releases</id>
        <url>https://repo.filledev.se/releases</url>
    </repository>
</repositories>

Dependency

<dependencies>
    <dependency>
        <groupId>se.filledev</groupId>
        <artifactId>procosmetics-api</artifactId>
        <version>2.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle Setup (Kotlin DSL)

Repository

repositories {
    maven {
        url = uri("https://repo.filledev.se/releases")
    }
}

Dependency

dependencies {
    compileOnly("se.filledev:procosmetics-api:2.0.0")
}

Gradle Setup (Groovy DSL)

repositories {
    maven {
        url 'https://repo.filledev.se/releases'
    }
}

Dependency

dependencies {
    compileOnly 'se.filledev:procosmetics-api:2.0.0'
}

Obtaining an instance of the API

When the plugin is enabled, an instance of ProCosmetics can be obtained statically from the ProCosmeticsProvider class. Note: this method will throw an IllegalStateException if the API is accessed before the plugin has been fully enabled.

ProCosmetics api = ProCosmeticsProvider.get();

Creating custom cosmetics

To create a custom cosmetic, start by creating a new class representing your cosmetic and implement the appropriate CosmeticBehavior. For example, if you want to create an arrow effect, implement the ArrowEffectBehavior. After implementing the interface, define your custom behaviour by overriding the available methods. Below is an example of an arrow effect:

public class LoveArrows implements ArrowEffectBehavior {

    private static final int HIT_AMOUNT = 4;
    private static final double HIT_SPREAD = 0.5d;

    @Override
    public void onEquip(CosmeticContext<ArrowEffectType> context) {
    }

    @Override
    public void onUpdate(CosmeticContext<ArrowEffectType> context, Location location) {
        location.getWorld().spawnParticle(Particle.HEART, location, 1);
    }

    @Override
    public void onArrowHit(CosmeticContext<ArrowEffectType> context, Location location) {
        location.getWorld().spawnParticle(Particle.HEART,
                location,
                HIT_AMOUNT,
                HIT_SPREAD,
                HIT_SPREAD,
                HIT_SPREAD
        );
    }

    @Override
    public void onUnequip(CosmeticContext<ArrowEffectType> context) {
    }
}

Registering a cosmetic

Cosmetics are registered through their corresponding CosmeticRegistry based on the CosmeticCategory. First, access the built-in registries:

ProCosmetics api = ProCosmeticsProvider.get();
CosmeticRegistry<ArrowEffectType, ArrowEffectBehavior, ArrowEffectType.Builder> arrowEffectRegistry = api.getCategoryRegistries().arrowEffects().getCosmeticRegistry();

Creating a builder

Each cosmetic is defined using a builder. You should provide a unique key in lowercase format. If the name contains spaces, replace them with underscores (_).

ArrowEffectType.Builder builder = arrowEffectRegistry.builder("love_arrows");

Providing cosmetic data

You can define cosmetic data in two ways:

Option 1: Configuration (recommended)

1. Open the relevant configuration file for the cosmetic category in /plugins/ProCosmetics/.
2. Copy and paste an existing cosmetic entry.
3. Rename the key to your new desired cosmetic key (the configuration key must exactly match the builder key (case-sensitive)).
4. Use readFromConfig() to automatically load the values.

Option 2: Code-based data

Alternatively, you can configure all values manually using the builder (e.g. cost, rarity, permissions, etc.).

Registering the cosmetic

You must provide a factory before calling build(). In this example, the factory creates a new instance of LoveArrows using LoveArrows::new. After that, you can register it with:

arrowEffectRegistry.register(arrowEffectRegistry.builder("love_arrows").readFromConfig().factory(LoveArrows::new).build());

The custom cosmetic should now be registered properly and visible in the ProCosmetics cosmetics menu.

Creating custom cosmetic categories

WIP