Developer API

SnCredits exposes a public developer API for other plugins. On the Velocity proxy you get cancellable events, a query service and price modifiers. On Paper backends you get cancellable menu events, notifications, price modifiers and the cached balances. Both live in the com.sn.credits.api package inside the plugin jar. There is no separate artifact.

Two surfaces

Every balance, shop, discount and coinflip lives on the proxy. That is where the full API lives too.

Getting the jar

1. Sign in and download the latest SnCredits jar from SnDevelopment.

2. Install it into your local Maven repository:

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

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

Quick start (Velocity)

Declare the dependency in your velocity-plugin.json:

"dependencies": [{ "id": "sncredits", "optional": true }]

Resolve the API when you need it:

SnCreditsAPI api = SnCreditsProvider.get();
if (api != null) {
    double balance = api.getBalance(player.getUniqueId());
}

SnCreditsProvider.get() returns null while SnCredits is still booting, after it shut down, or when its license is refused. SnCreditsProvider.isAvailable() answers the same question.

Master switch

The server owner can turn the events off with api-events.enabled: false in the proxy config.yml. The proxy pushes the switch to every bridge, so it turns off the Paper events too. Every action then proceeds as if no plugin had cancelled it. The query service and the price modifiers stay active either way.

Events

Every event fires on the proxy before anything changes. SnCredits waits for all listeners, then continues. Denying the result aborts the action.

Payloads:

Listen like any Velocity event. Each event implements ResultedEvent<GenericResult>, and setCancelled(true) is a shorthand for setResult(GenericResult.denied()):

@Subscribe
public void onPurchase(ShopPurchaseEvent event) {
    if (event.getPrice() > 50_000 && !event.getPlayer().hasPermission("myplugin.bigspender")) {
        event.setCancelled(true);
        event.getPlayer().sendMessage(Component.text("You cannot buy items that expensive."));
    }
}

Event payloads are read-only. Cancelling is the only change a listener can make. Purchases in admin bypass mode charge nothing and fire no event.

Query service (Velocity)

Synchronous methods read in-memory snapshots. They are safe from any thread.

Asynchronous methods return CompletableFuture and complete on a SnCredits database thread.

Views are immutable records:

Treat unknown transaction type names gracefully. A future version may add new ones.

Price modifiers

A price modifier changes what a shop item costs for one player. Register it from a proxy plugin, from a Paper plugin, or from both:

// Velocity: 20% off for MVPs on every server
api.registerPriceModifier(this, ctx ->
        ctx.getPlayer().hasPermission("rank.mvp") ? ctx.percentOff(20) : ctx.getPrice());

// Paper: another 10% off on this backend during an event
bridge.registerPriceModifier(this, ctx -> eventRunning ? ctx.percentOff(10) : ctx.getPrice());

The price is built in this order:

1. The configured price.
2. The biggest active shop discount.
3. Every proxy modifier, in registration order. The confirm menu receives this price.
4. Every bridge modifier on the player's backend, in registration order.

The proxy charges the final price. The menus mark it as a discount when it is below the configured price.

Rules:

• Return ctx.getPrice() to leave the price unchanged.
• Results are floored to whole credits and never go below 0.
• A modifier that throws or returns a non-finite value is skipped and logged once.
• Modifiers must be fast and must never block. Proxy modifiers can run on a database thread; bridge modifiers run on the main thread.
• A Paper plugin's modifiers are removed when that plugin disables.

Bridge modifiers need an up-to-date proxy. Against an older proxy they stay off, so a menu never shows a price the proxy would not charge.

Bridge API (Paper)

Declare the dependency in your plugin.yml. The bridge registers under the name SnCredits-Bridge:

softdepend: [SnCredits-Bridge]

Resolve it through the Bukkit ServicesManager, or the provider:

SnCreditsBridgeAPI bridge = SnCreditsBridgeProvider.get();
if (bridge != null && bridge.isBalanceKnown(player.getUniqueId())) {
    double balance = bridge.getBalance(player.getUniqueId());
}

Bridge events

Bridge events are normal Bukkit events, fired on the main thread. Listen with @EventHandler.

The cancellable ones fire before the bridge sends the action to the proxy. A cancelled action never reaches the proxy and ends silently.

@EventHandler
public void onConfirm(ShopPurchaseConfirmEvent event) {
    if (event.getCategoryId().equals("vip") && !event.getPlayer().hasPermission("rank.vip")) {
        event.setCancelled(true);
        event.getPlayer().sendMessage("Only VIPs can buy from this category.");
    }
}

The proxy can still refuse an action the bridge sent, for example when the player lacks the credits.

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

Versioning

Call getApiVersion() for the API contract version. The proxy API and the bridge API carry separate versions, both independent of the plugin version. Additions bump the minor component. Existing members are never removed or changed; deprecated members keep working.