Basic API Usage

Common patterns and examples for using the SuperiorSkyblock2 API

Accessing the API

The main entry point for the API is the SuperiorSkyblockAPI class. All methods are static, making it easy to access from anywhere:

import com.bgsoftware.superiorskyblock.api.SuperiorSkyblockAPI;
import com.bgsoftware.superiorskyblock.api.SuperiorSkyblock;

// Get the plugin instance
SuperiorSkyblock plugin = SuperiorSkyblockAPI.getSuperiorSkyblock();

// Check API version
int apiVersion = SuperiorSkyblockAPI.getAPIVersion();

Working with Players

The API provides a SuperiorPlayer wrapper that extends Bukkit’s Player with island-specific functionality:

Get Player

import com.bgsoftware.superiorskyblock.api.SuperiorSkyblockAPI;
import com.bgsoftware.superiorskyblock.api.wrappers.SuperiorPlayer;
import org.bukkit.entity.Player;
import java.util.UUID;

// From Bukkit Player
Player bukkitPlayer = ...; // Your Bukkit player
SuperiorPlayer superiorPlayer = SuperiorSkyblockAPI.getPlayer(bukkitPlayer);

// From UUID
UUID playerUUID = ...; // Player's UUID
SuperiorPlayer superiorPlayer = SuperiorSkyblockAPI.getPlayer(playerUUID);

// From name
String playerName = "Steve";
SuperiorPlayer superiorPlayer = SuperiorSkyblockAPI.getPlayer(playerName);

Working with Islands

1. Get Islands

   Retrieve islands by various methods

2. Modify Islands

   Create, delete, or update island properties

3. Query Islands

   Find islands by location or criteria

Getting Islands

import com.bgsoftware.superiorskyblock.api.island.Island;
import com.bgsoftware.superiorskyblock.api.SuperiorSkyblockAPI;
import org.bukkit.Location;
import java.util.UUID;

// Get island by name
Island island = SuperiorSkyblockAPI.getIsland("MyIsland");

// Get island by UUID
UUID islandUUID = ...; // Island's UUID
Island island = SuperiorSkyblockAPI.getIslandByUUID(islandUUID);

// Get island at location
Location location = new Location(world, x, y, z);
Island island = SuperiorSkyblockAPI.getIslandAt(location);

// Get spawn island
Island spawnIsland = SuperiorSkyblockAPI.getSpawnIsland();

Creating Islands

import com.bgsoftware.superiorskyblock.api.SuperiorSkyblockAPI;
import com.bgsoftware.superiorskyblock.api.wrappers.SuperiorPlayer;
import org.bukkit.block.Biome;
import java.math.BigDecimal;

SuperiorPlayer owner = SuperiorSkyblockAPI.getPlayer(player);
String schematicName = "default"; // Schematic to use
BigDecimal bonusWorth = BigDecimal.ZERO; // Starting bonus worth
BigDecimal bonusLevel = BigDecimal.ZERO; // Starting bonus level
Biome biome = Biome.PLAINS; // Starting biome
String islandName = "MyIsland"; // Island name
boolean offset = true; // Use offset for values

// Create the island
SuperiorSkyblockAPI.createIsland(
    owner,
    schematicName,
    bonusWorth,
    bonusLevel,
    biome,
    islandName,
    offset
);

Island creation is asynchronous. Use events to detect when the island is fully created.

Deleting Islands

import com.bgsoftware.superiorskyblock.api.SuperiorSkyblockAPI;
import com.bgsoftware.superiorskyblock.api.island.Island;

Island island = SuperiorSkyblockAPI.getIsland("MyIsland");

if (island != null) {
    SuperiorSkyblockAPI.deleteIsland(island);
}

Using Managers

The API provides specialized managers for different features. Access them through the main API:

import com.bgsoftware.superiorskyblock.api.handlers.*;

// Grid Manager - Island grid operations
GridManager gridManager = SuperiorSkyblockAPI.getGrid();

// Players Manager - Player operations
PlayersManager playersManager = SuperiorSkyblockAPI.getPlayers();

// Schematics Manager - Schematic operations
SchematicManager schematicManager = SuperiorSkyblockAPI.getSchematics();

// Block Values Manager - Worth calculations
BlockValuesManager blockValues = SuperiorSkyblockAPI.getBlockValues();

// Upgrades Manager - Island upgrades
UpgradesManager upgradesManager = SuperiorSkyblockAPI.getUpgrades();

// Missions Manager - Mission system
MissionsManager missionsManager = SuperiorSkyblockAPI.getMissions();

// Commands Manager - Register custom commands
CommandsManager commandsManager = SuperiorSkyblockAPI.getCommands();

// Settings Manager - Plugin configuration
SettingsManager settingsManager = SuperiorSkyblockAPI.getSettings();

Example: Island Info Command

Here’s a complete example that combines multiple API features:

import com.bgsoftware.superiorskyblock.api.SuperiorSkyblockAPI;
import com.bgsoftware.superiorskyblock.api.island.Island;
import com.bgsoftware.superiorskyblock.api.wrappers.SuperiorPlayer;
import org.bukkit.command.Command;
import org.bukkit.command.CommandExecutor;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;

public class IslandInfoCommand implements CommandExecutor {
    
    @Override
    public boolean onCommand(CommandSender sender, Command command, 
                           String label, String[] args) {
        if (!(sender instanceof Player)) {
            sender.sendMessage("Only players can use this command!");
            return true;
        }
        
        Player player = (Player) sender;
        SuperiorPlayer superiorPlayer = SuperiorSkyblockAPI.getPlayer(player);
        Island island = superiorPlayer.getIsland();
        
        if (island == null) {
            player.sendMessage("You don't have an island!");
            return true;
        }
        
        // Get island information
        String name = island.getName();
        SuperiorPlayer owner = island.getOwner();
        int members = island.getIslandMembers(true).size();
        BigDecimal level = island.getIslandLevel();
        BigDecimal worth = island.getWorth();
        
        // Send formatted information
        player.sendMessage("===== Island Info =====");
        player.sendMessage("Name: " + name);
        player.sendMessage("Owner: " + owner.getName());
        player.sendMessage("Members: " + members);
        player.sendMessage("Level: " + level.toString());
        player.sendMessage("Worth: $" + worth.toString());
        
        return true;
    }
}

Next Steps

Now that you understand the basics:

• Explore specific manager documentation for advanced features
• Check out the API events system for reacting to island changes
• Review the JavaDocs in the source code for detailed method documentation
• Join the Discord for support and examples