Skip to main content

API Overview

SigmaTools provides a public API for developers to integrate with the plugin. This API allows you to interact with tools, check permissions, manage economy, and listen to events.

Getting Started​

Accessing the API​

The API is provided via Bukkit's ServicesManager:

import com.sigmatools.api.SigmaToolsAPI;
import org.bukkit.Bukkit;

// Get the API
SigmaToolsAPI api = Bukkit.getServicesManager().load(SigmaToolsAPI.class);

if (api == null) {
    // SigmaTools is not loaded
    getLogger().warning("SigmaToolsAPI not available");
    return;
}

// API is ready to use
String version = api.getVersion();

Dependency Setup​

Add SigmaTools as a dependency in your pom.xml:

<dependency>
    <groupId>com.sigmatools</groupId>
    <artifactId>SigmaTools</artifactId>
    <version>1.0.3</version>
    <scope>provided</scope>
</dependency>

Note: The API is not published to Maven Central. You'll need to either:

  1. Install SigmaTools locally to your Maven repository
  2. Include the SigmaTools JAR in your build path
  3. Use the API at runtime only (recommended)

Runtime API Access​

For runtime-only access (recommended):

@Override
public void onEnable() {
    // Try to get API immediately
    SigmaToolsAPI api = Bukkit.getServicesManager().load(SigmaToolsAPI.class);
    
    if (api == null) {
        // Try again next tick (load order timing)
        Bukkit.getScheduler().runTask(this, () -> {
            api = Bukkit.getServicesManager().load(SigmaToolsAPI.class);
            if (api != null) {
                initializeAPI(api);
            } else {
                getLogger().warning("SigmaToolsAPI not available");
            }
        });
    } else {
        initializeAPI(api);
    }
}

private void initializeAPI(SigmaToolsAPI api) {
    // API is ready
    getLogger().info("Found SigmaToolsAPI v" + api.getVersion());
}

API Methods​

Tool Identification​

isSigmaTool(ItemStack item)​

Check if an item is a SigmaTool.

boolean isTool = api.isSigmaTool(itemStack);

getToolType(ItemStack item)​

Get the tool type of a SigmaTool item.

Optional<String> toolType = api.getToolType(itemStack);
if (toolType.isPresent()) {
    String type = toolType.get(); // "pickaxe", "axe", "bucket", or "hoe"
}

getToolId(ItemStack item)​

Get the tool ID (currently same as tool type).

Optional<String> toolId = api.getToolId(itemStack);

Usage and Protection​

canUseHere(Player player, Location location)​

Check if a player can use tools at a location.

boolean canUse = api.canUseHere(player, location);

Economy​

getActiveCurrency()​

Get the active economy currency.

String currency = api.getActiveCurrency(); // "vault" or "coins"

getBalance(Player player)​

Get player's economy balance.

EconomyResult result = api.getBalance(player);
if (result.success()) {
    double balance = result.balanceAfter();
    String currency = result.currency();
}

deduct(Player player, double amount)​

Deduct currency from a player.

EconomyResult result = api.deduct(player, 10.0);
if (result.success()) {
    // Deduction successful
    double newBalance = result.balanceAfter();
} else {
    // Insufficient funds
    String message = result.message();
}

reward(Player player, double amount)​

Give currency to a player.

EconomyResult result = api.reward(player, 5.0);
if (result.success()) {
    // Reward given
    double newBalance = result.balanceAfter();
}

Introspection​

getAvailableToolTypes()​

Get all available tool types.

Set<String> toolTypes = api.getAvailableToolTypes();
// Returns: ["pickaxe", "axe", "bucket", "hoe"]

getToolConfig(String toolType)​

Get tool configuration.

Map<String, Object> config = api.getToolConfig("pickaxe");
Object enabled = config.get("enabled");
Object maxCharges = config.get("cooldown.max-charges");

getVersion()​

Get SigmaTools version.

String version = api.getVersion(); // "1.0.3"

Events​

SigmaTools fires several events that you can listen to:

SigmaToolUseEvent​

Fired when a tool is used.

@EventHandler
public void onToolUse(SigmaToolUseEvent event) {
    Player player = event.getPlayer();
    String toolType = event.getToolType();
    Set<Block> affectedBlocks = event.getAffectedBlocks();
    
    // Modify planned cost/reward
    event.setPlannedCost(5.0);
    event.setPlannedReward(10.0);
    
    // Cancel the event
    // event.setCancelled(true);
}

SigmaToolEconomyDeductEvent​

Fired when economy is deducted.

@EventHandler
public void onEconomyDeduct(SigmaToolEconomyDeductEvent event) {
    Player player = event.getPlayer();
    String toolType = event.getToolType();
    String currency = event.getCurrency();
    double amount = event.getAmount();
    
    // Modify amount
    event.setAmount(amount * 0.5); // 50% discount
    
    // Cancel the event
    // event.setCancelled(true);
}

SigmaToolEconomyRewardEvent​

Fired when economy reward is given.

@EventHandler
public void onEconomyReward(SigmaToolEconomyRewardEvent event) {
    Player player = event.getPlayer();
    String toolType = event.getToolType();
    String currency = event.getCurrency();
    double amount = event.getAmount();
    
    // Modify amount
    event.setAmount(amount * 2.0); // Double reward
    
    // Cancel the event
    // event.setCancelled(true);
}

Complete Example​

package com.example.plugin;

import com.sigmatools.api.SigmaToolsAPI;
import com.sigmatools.api.events.SigmaToolUseEvent;
import org.bukkit.Bukkit;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.plugin.java.JavaPlugin;

public class MyPlugin extends JavaPlugin implements Listener {
    
    private SigmaToolsAPI api;
    
    @Override
    public void onEnable() {
        // Get API
        this.api = Bukkit.getServicesManager().load(SigmaToolsAPI.class);
        
        if (api == null) {
            // Try again next tick
            Bukkit.getScheduler().runTask(this, () -> {
                this.api = Bukkit.getServicesManager().load(SigmaToolsAPI.class);
                if (api != null) {
                    getLogger().info("Found SigmaToolsAPI v" + api.getVersion());
                    Bukkit.getPluginManager().registerEvents(this, this);
                }
            });
        } else {
            getLogger().info("Found SigmaToolsAPI v" + api.getVersion());
            Bukkit.getPluginManager().registerEvents(this, this);
        }
    }
    
    @EventHandler
    public void onToolUse(SigmaToolUseEvent event) {
        Player player = event.getPlayer();
        String toolType = event.getToolType();
        
        // Log tool usage
        getLogger().info(player.getName() + " used " + toolType);
        
        // Check if player has special permission
        if (player.hasPermission("myp plugin.double-reward")) {
            event.setPlannedReward(event.getPlannedReward() * 2.0);
        }
    }
}

API Reference​

See the API Reference for complete method documentation.

Examples​

See API Examples for more code samples.

Next Steps​