Skip to main content

Developer API

zCollections fires three custom Bukkit events so other plugins can react to discovery, progress, and tier-ups. This page is for plugin developers. If you are running a server, you do not need any of this.

For developers only

You do not have to write code to use zCollections. Everything else in these docs works without touching Java. This page only matters if you are writing your own plugin that hooks into zCollections.

The events​

All three live in the package cc.arrowtan.zcollections.events.

EventWhen it firesCancellable
CollectionDiscoverEventThe first time a player discovers a resourceNo
CollectionProgressEventBefore a resource counter goes up by oneYes
CollectionTierUpEventWhen a player crosses a tier thresholdYes

CollectionDiscoverEvent​

Fired the first time a player triggers a resource they had never gathered before, before the discovery is saved. Not cancellable.

MethodReturns
getPlayer()The Player
getResource()The Resource that was discovered
getCategory()The collection id, like mining

CollectionProgressEvent​

Fired for every gather action, just before the counter increments. Cancel it to block the +1. A cancelled progress event also means no tier-up can happen that action.

MethodReturns
getPlayer()The Player
getResource()The Resource being gathered
getCategory()The collection id
getOldValue()The progress count before this action
getNewValue()The progress count if it is allowed (old + 1)
setCancelled(boolean)Cancel to block the increment

CollectionTierUpEvent​

Fired when a player passes a tier threshold. If one action crosses several thresholds at once, the event fires once per tier crossed. Cancel it to skip that tier's rewards and notification.

MethodReturns
getPlayer()The Player
getResource()The Resource
getCategory()The collection id
getTier()The tier number reached
setCancelled(boolean)Cancel to skip that tier's rewards and message

Reading the resource​

The Resource you get from any event exposes the ids and display name:

Resource r = event.getResource();
r.getKey();          // resource id, e.g. "diamond"
r.getCategoryKey();  // collection id, e.g. "mining"
r.getDisplayName();  // the colored display name
r.getMaxTier();      // highest tier number

Listening to an event​

import cc.arrowtan.zcollections.events.CollectionTierUpEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public final class MyListener implements Listener {

    @EventHandler
    public void onTierUp(CollectionTierUpEvent event) {
        event.getPlayer().sendMessage(
                event.getResource().getDisplayName() + " reached tier " + event.getTier());
    }
}

Register it like any other listener:

getServer().getPluginManager().registerEvents(new MyListener(), this);

Cancelling progress​

@EventHandler
public void onProgress(CollectionProgressEvent event) {
    if (shouldBlock(event.getPlayer())) {
        event.setCancelled(true); // no +1, no tier-up this action
    }
}

Building against zCollections​

The events ship inside the plugin jar. The source is closed, so you compile against the jar itself, not a public Maven repository.

In your own plugin.yml, declare zCollections so your plugin loads after it:

softdepend: [zCollections]

Use softdepend if your plugin still works without zCollections installed, or depend if it does not.

Gradle​

Drop zCollections-1.0.0-1.jar into a libs/ folder next to your build file:

dependencies {
    compileOnly files('libs/zCollections-1.0.0-1.jar')
}

Maven​

Install the jar into your local Maven repository once:

mvn install:install-file -Dfile=zCollections-1.0.0-1.jar \
    -DgroupId=cc.arrowtan -DartifactId=zCollections \
    -Dversion=1.0.0-1 -Dpackaging=jar

Then add it as a provided dependency:

<dependency>
    <groupId>cc.arrowtan</groupId>
    <artifactId>zCollections</artifactId>
    <version>1.0.0-1</version>
    <scope>provided</scope>
</dependency>

compileOnly and provided keep the jar out of your build, since the server already has it at runtime.