Skip to main content

API: Getting Started

Quick start guide for using the SigmaOrders API.

Prerequisites​

  • SigmaOrders plugin installed and running
  • Your plugin depends on SigmaOrders
  • Basic Java knowledge

Setup​

1. Add Dependency​

Maven (pom.xml):

<dependency>
    <groupId>com.sigma</groupId>
    <artifactId>sigma-orders</artifactId>
    <version>1.0.2</version>
    <scope>provided</scope>
</dependency>

Gradle (build.gradle):

dependencies {
    compileOnly 'com.sigma:sigma-orders:1.0.2'
}

2. Get API Instance​

import com.sigma.orders.api.SigmaOrdersAPI;
import org.bukkit.Bukkit;
import org.bukkit.plugin.ServicesManager;

public class YourPlugin extends JavaPlugin {
    
    private SigmaOrdersAPI ordersAPI;
    
    @Override
    public void onEnable() {
        ServicesManager servicesManager = Bukkit.getServicesManager();
        ordersAPI = servicesManager.load(SigmaOrdersAPI.class);
        
        if (ordersAPI == null) {
            getLogger().warning("SigmaOrders not found! API not available.");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }
        
        getLogger().info("SigmaOrders API loaded! Version: " + ordersAPI.getVersion());
    }
}

3. Check API Availability​

if (ordersAPI == null || !ordersAPI.isEnabled()) {
    // API not available
    return;
}

Basic Usage​

Create an Order​

import com.sigma.orders.models.OrderItem;
import org.bukkit.Material;

// Create order item
OrderItem item = new OrderItem(Material.DIAMOND, 64, 100.0);

// Create order
CompletableFuture<Order> future = ordersAPI.createOrder(
    player.getUniqueId(),
    player.getName(),
    Collections.singletonList(item)
);

future.thenAccept(order -> {
    if (order != null) {
        player.sendMessage("Order #" + order.getId() + " created!");
    }
});

Get an Order​

CompletableFuture<Order> future = ordersAPI.getOrder(1);

future.thenAccept(order -> {
    if (order != null) {
        getLogger().info("Order by: " + order.getPlayerName());
    }
});

Deliver Items​

CompletableFuture<Boolean> future = ordersAPI.deliverItems(
    1,                    // order ID
    1,                    // item ID
    64,                   // amount
    player.getUniqueId(), // deliverer UUID
    player.getName()      // deliverer name
);

future.thenAccept(success -> {
    if (success) {
        player.sendMessage("Delivery successful!");
    }
});

Async Operations​

All API methods are async and return CompletableFuture:

// Handle success
future.thenAccept(result -> {
    // Handle result
});

// Handle errors
future.exceptionally(throwable -> {
    getLogger().severe("Error: " + throwable.getMessage());
    return null;
});

// Chain operations
future.thenCompose(order -> {
    // Use order for next operation
    return ordersAPI.deliverItems(...);
});

Error Handling​

CompletableFuture<Order> future = ordersAPI.getOrder(orderId);

future.thenAccept(order -> {
    if (order == null) {
        // Order not found
        player.sendMessage("Order not found!");
        return;
    }
    
    // Use order
    processOrder(order);
});

future.exceptionally(throwable -> {
    // Handle exception
    getLogger().severe("Failed to get order: " + throwable.getMessage());
    return null;
});

Best Practices​

  1. Always Check for Null: API methods may return null
  2. Handle Async Properly: Use CompletableFuture correctly
  3. Check API Availability: Verify API is loaded before use
  4. Error Handling: Always handle potential errors
  5. Validate Input: Validate parameters before API calls

Next Steps​