Developer API

SnGens exposes a public developer API for other plugins: custom Bukkit events, a read-only query service, and a sell multiplier extension point. The API lives in the com.sn.sngens.api package inside the plugin jar. There is no separate artifact.

Getting the jar

1. Download the latest release jar.

2. Install it into your local Maven repository:

   mvn install:install-file -Dfile=SnGens-<version>.jar -DgroupId=com.sn \
     -DartifactId=SnGens -Dversion=<version> -Dpackaging=jar

3. Depend on it with provided scope. Never shade it.

<dependency>
  <groupId>com.sn</groupId>
  <artifactId>SnGens</artifactId>
  <version><!-- the version you installed --></version>
  <scope>provided</scope>
</dependency>

Gradle users can drop the jar in libs/ and use compileOnly files("libs/SnGens-<version>.jar") instead.

Quick start

Declare the dependency in your plugin.yml:

depend: [SnGens]        # or softdepend if the integration is optional

Resolve the API when you need it:

import com.sn.sngens.api.SnGensAPI;
import com.sn.sngens.api.SnGensProvider;

SnGensAPI api = SnGensProvider.get();
if (api != null) {
    int placed = api.getPlacedCount(player.getUniqueId());
}

SnGensProvider.isAvailable() is a boolean shortcut for the same check. The facade is registered with the Bukkit services manager at the very end of SnGens' startup, so with depend it is ready in your own onEnable.

Master switch

API events can be disabled by the server owner with api-events.enabled: false in config.yml. No event is then dispatched at all, and cancellable events behave as if nothing cancelled them, so gameplay is unaffected. The query service and the extension point stay available either way.

Events

All events live in com.sn.sngens.api.event, extend org.bukkit.event.Event and carry the usual static getHandlerList().

Cancellable events fire before the action. Cancelling aborts it cleanly, with no money taken and no items lost.

Notification events fire after the fact. They cannot be cancelled.

The last five originate off the main thread inside SnGens, but the plugin hops through its Folia aware scheduler before dispatching, so your listener always runs on the main thread and can touch the Bukkit API freely.

RefundIssuedEvent stays generator only. When an island kick, leave, ban or disband also removes the player's collectors and hoppers, those arrive as a separate StorageRefundIssuedEvent, so a generator listener never sees an empty id list.

Listen like any Bukkit event:

@EventHandler
public void onUpgrade(GeneratorUpgradeEvent event) {
    Player player = event.getPlayer();
    getLogger().info(player.getName()
            + " upgrades " + event.getGenerator().generatorId()
            + " into " + event.getToGeneratorId()
            + " for " + event.getCost());
}

@EventHandler
public void onHopperPlace(HopperPlaceEvent event) {
    if (event.getLocation().getWorld().getName().equals("pvp_arena")) {
        event.setCancelled(true);
        event.getPlayer().sendMessage("You cannot place hoppers here.");
    }
}

GeneratorSellEvent#getContext() returns a SellContext with the item count, the base value, the effective multiplier, the final amount and the source of the sale (PLAYER_INVENTORY, SELLWAND, COLLECTOR, HOPPER, OTHER).

@EventHandler
public void onSell(GeneratorSellEvent event) {
    SellContext c = event.getContext();
    if (c.source() == SellSource.SELLWAND && c.finalAmount() > 1_000_000) {
        event.setCancelled(true);
    }
}

GeneratorUpgradeEvent fires once per hop. A multi level upgrade through the API fires all of them before anything is charged. An event that you did not cancel is a proposal, not a commit. A later hop can still be cancelled, and the upgrade can still be refused after the events. No compensating event follows, so spend a quota against a state you can verify afterwards.

Wand swings are vetoed through their own event, not through the generator ones. A build wand places its whole line in one batch and an upgrade wand upgrades its whole square in one batch, so neither fires GeneratorPlaceEvent, GeneratorUpgradeEvent or GeneratorBulkUpgradeEvent. Cancel BuildWandUseEvent or UpgradeWandUseEvent to stop them.

@EventHandler
public void onBuildWand(BuildWandUseEvent event) {
    for (Location target : event.getTargets()) {
        if (myRegionPlugin.isProtected(target)) {
            event.setCancelled(true);
            event.getPlayer().sendMessage("You cannot build into that region.");
            return;
        }
    }
}

SellwandPreUseEvent fires the moment the wand is swung, before SnGens looks at what the clicked block holds, so it vetoes the swing whatever the target is: a chest, a collector, an infinite hopper or a display shop. SellwandUseEvent is its notification counterpart and only fires once a sale actually went through.

Event payloads are read-only. To influence the money a sale pays, use the extension point below instead of looking for setters.

Query service

Synchronous methods read in-memory state. Call them on the main thread.

api.getGeneratorAt(block.getLocation())
   .ifPresent(view -> player.sendMessage("Generator: " + view.displayName()));

for (HopperView hopper : api.getOwnerHoppers(player.getUniqueId())) {
    for (StoredItemView stored : hopper.contents()) {
        // stored.item() is a decoded ItemStack, ready for a menu icon
        menu.addIcon(stored.item(), stored.amount(), stored.totalValue());
    }
}

Asynchronous methods hit the database, so they also see generators in unloaded chunks.

api.getIslandGeneratorStats(player.getUniqueId()).thenAccept(stats ->
    Bukkit.getScheduler().runTask(this, () ->
        player.sendMessage("Island: " + stats.totalCount()
                + " generators worth " + stats.totalValue())));

Upgrades

The query service only reads. These four methods change the world, so they get their own rules. Call them on the main thread. On Folia, call them on the region thread that owns the location.

An upgrade is all or nothing. Either every level applies and the total is charged once, or nothing changes at all. One GeneratorUpgradeEvent fires per hop, and all of them fire before any money moves. Cancelling any hop refuses the whole request with CANCELLED and charges nothing.

Those per-hop listeners run arbitrary code. SnGens looks the generator up again after the events and honours the withdrawal result. A listener that removes or changes the generator, or that drains the actor's balance, yields BUSY, NOT_A_GENERATOR or NOT_ENOUGH_MONEY with nothing changed and nothing charged.

SnGens reads the block once more after the charge, because the charge is third party code too. If the generator changed in that window, the player gets the money back and the call refuses. The status is BUSY or NOT_A_GENERATOR, and charged stays 0. A climb whose total is 0 never calls the economy at all.

A dry run stops before the per-hop events. simulateUpgrade and simulateUpgradeTo fire nothing, so a simulation never returns CANCELLED. Treat a clean simulation as "would succeed right now", not as a reservation.

You identify a generator by its location. Any location inside the block matches, because decimals, yaw and pitch are ignored. So player.getLocation() of a standing player works as well as the GeneratorView#location() you get from the listings above. The same holds for getGeneratorAt and isGenerator.

api.getGeneratorAt(loc).ifPresent(gen -> {
    api.quoteUpgradeTo(gen.generatorId(), "diamond_generator")
       .ifPresent(quote -> player.sendMessage("Diamond costs " + quote.totalCost()
               + " over " + quote.levels() + " levels"));

    UpgradeResult result = api.upgradeGenerator(player, loc, 2);
    if (result.success()) {
        player.sendMessage("Now " + result.toGeneratorId() + ", paid " + result.charged());
    } else if (result.status() == UpgradeStatus.NOT_ENOUGH_MONEY) {
        player.sendMessage("You need " + result.totalCost());
    }
});

Views

Every returned object is an immutable snapshot. Location and ItemStack values are cloned, so mutating them never affects SnGens.

A HopperView or CollectorView is a snapshot taken when you asked for it. Both keep absorbing items afterwards, so query again on each menu refresh instead of caching.

A WandView reports one of five types: SELLWAND, BUILDWAND, UPGRADEWAND_FREE, UPGRADEWAND_RADIUS, ADMINWAND. Read type() first, then only the field that belongs to it. The others stay at zero. uses() is -1 on an unlimited wand, and the admin wand has no counter so it always reports -1.

ItemStack held = player.getInventory().getItemInMainHand();
api.getWand(held).ifPresent(wand -> {
    if (wand.type() == WandType.SELLWAND) {
        player.sendMessage("Sellwand x" + wand.sellMultiplier()
                + (wand.unlimited() ? " (unlimited)" : ", " + wand.uses() + " uses left"));
    }
});

A tier's configured upgrade-cost is the price of leaving it. So an UpgradeStepView prices a hop by its origin tier, never by the tier it reaches. cumulativeCost is the running total up to and including that hop.

An UpgradeQuote always covers at least one tier. A type that is already the last tier of the chain yields no quote at all. capped is true when you asked for more levels than the chain still had, and levels is then the shorter, real figure.

An UpgradeResult is refused or applied, never half applied. On any status other than SUCCESS, toGeneratorId equals fromGeneratorId, levels is 0 and charged is 0. totalCost still carries the quoted total when the chain resolved, so NOT_ENOUGH_MONEY tells you how much was needed. Both ids are null only for INVALID_REQUEST, NOT_LOADED and NOT_A_GENERATOR. On a dry run charged is always 0, and SUCCESS means the upgrade would succeed right now. It is not a reservation.

UpgradeStatus reports why a request succeeded or was refused:

failedRequirements holds the configured failure messages, raw and with their colour codes. It is empty unless the status is REQUIREMENTS_FAILED.

Extension points

Register through the facade, from your own onEnable:

// Additive: VIPs get +0.5x
api.registerSellMultiplier(this, ctx ->
        ctx.player().hasPermission("myrank.vip") ? 0.5 : 0.0);

// Multiplicative: +10% on top of whatever the player already has
api.registerSellMultiplier(this,
        (MultiplicativeGensSellMultiplier) ctx -> 0.10);

The context passed to a provider is a GensSellContext, with player() and sellwandMultiplier(). The second is only present for sellwand sales.

Providers run inside the payout path of every sale, so keep them fast. The server's player-multiplier-limit clamp still applies on top of whatever your provider contributes. Registrations last until SnGens reloads or disables.

Versioning

Call getApiVersion() for the API contract version. It is independent of the plugin version. Additions bump the minor component. Existing members are never removed or changed; deprecated members keep working.

The current contract version is 1.4.0. It added the upgrade path, the quotes, the dry runs and the four upgrade methods in SnGens 2.57.0.