Upgrades - SuperiorSkyblock2

Overview

The upgrade system allows islands to progressively improve their capabilities by purchasing upgrades. Each upgrade has multiple levels, with each level providing enhanced benefits and requiring payment of a cost.

Upgrade Structure

Upgrades in SuperiorSkyblock2 follow a level-based progression system:

Upgrade Definition

Each upgrade has a unique name and maximum level

Level Progression

Islands advance through upgrade levels by paying costs

Cumulative Benefits

Higher levels provide better multipliers, limits, and effects

Menu Integration

Upgrades appear in configurable slots in the upgrades GUI

Upgrade Interface

Basic Properties

public interface Upgrade {
    // Upgrade identification
    String getName();
    
    // Level management
    UpgradeLevel getUpgradeLevel(int level);
    int getMaxUpgradeLevel();
    
    // GUI positioning
    List<Integer> getSlots();
    boolean isSlot(int slot);
    void setSlots(List<Integer> slots);
}

If a requested level doesn’t exist, getUpgradeLevel() returns an upgrade level with level 0 (no benefits).

Getting Upgrades

import com.bgsoftware.superiorskyblock.api.SuperiorSkyblockAPI;
import com.bgsoftware.superiorskyblock.api.upgrades.Upgrade;

// Get specific upgrade by name
Upgrade upgrade = SuperiorSkyblockAPI.getUpgrades().getUpgrade("upgrade-name");

// Get all upgrades
Collection<Upgrade> allUpgrades = SuperiorSkyblockAPI.getUpgrades().getUpgrades();

Upgrade Levels

Each upgrade level defines the costs and benefits for that tier:

Level Properties

public interface UpgradeLevel {
    // Level identification
    int getLevel();
    
    // Cost to reach this level
    UpgradeCost getCost();
    
    // Permission required
    String getPermission();
    
    // Check requirements
    String checkRequirements(SuperiorPlayer player);
    
    // Commands executed on upgrade
    List<String> getCommands();
}

Upgrade Categories

Production Multipliers

Upgrades can boost various production rates:

Crop Growth
Spawner Rates
Mob Drops

// Check if level has crop growth multiplier
if (level.hasCropGrowth()) {
    double multiplier = level.getCropGrowth();
    // multiplier of 2.0 = 2x faster growth
}

Accelerates the growth rate of crops on the island.

// Check if level has spawner multiplier
if (level.hasSpawnerRates()) {
    double multiplier = level.getSpawnerRates();
    // multiplier of 1.5 = 1.5x faster spawning
}

Increases mob spawner spawn rates.

// Check if level has mob drop multiplier
if (level.hasMobDrops()) {
    double multiplier = level.getMobDrops();
    // multiplier of 3.0 = 3x more drops
}

Multiplies items dropped by mobs.

Multipliers are typically values like 1.5 (150%), 2.0 (200%), etc. A value of 1.0 means no change.

Block & Entity Limits

Block Limits

Control how many of each block type can be placed:

// Get limit for specific block
int getBlockLimit(Key blockKey);
int getExactBlockLimit(Key blockKey);

// Get all block limits
Map<Key, Integer> getBlockLimits();

Example Usage:

UpgradeLevel level = upgrade.getUpgradeLevel(5);

// Check hopper limit
Key hopperKey = Key.of("HOPPER");
int hopperLimit = level.getBlockLimit(hopperKey);

if (hopperLimit > 0) {
    player.sendMessage("Maximum hoppers: " + hopperLimit);
}

Entity Limits

Limit spawning of specific entity types:

// Get entity limit by type
int getEntityLimit(EntityType entityType);
int getEntityLimit(Key entityKey);

// Get all entity limits
Map<Key, Integer> getEntityLimitsAsKeys();

Example:

// Check if island can spawn more cows
int cowLimit = level.getEntityLimit(EntityType.COW);
int currentCows = island.getEntitiesTracker().getEntityCount(EntityType.COW);

if (currentCows >= cowLimit) {
    event.setCancelled(true);
    player.sendMessage("Cow limit reached!");
}

Generator Rates

Upgrades can modify cobblestone generator rates:

// Get generation rate for block in dimension
int getGeneratorAmount(Key blockKey, Dimension dimension);

// Get all generator rates for dimension
Map<String, Integer> getGeneratorAmounts(Dimension dimension);

Example Configuration:

UpgradeLevel level = upgrade.getUpgradeLevel(3);

Key diamondOre = Key.of("DIAMOND_ORE");
int diamondRate = level.getGeneratorAmount(diamondOre, Dimension.NORMAL);

// Rate of 10 means 10% chance to generate diamond ore

Normal World

Overworld cobble generator rates

Nether

Nether cobble generator rates

End

End cobble generator rates

Island Effects

Upgrade levels can grant permanent potion effects:

// Get potion effect level
int getPotionEffect(PotionEffectType type);

// Get all potion effects
Map<PotionEffectType, Integer> getPotionEffects();

Usage Example:

UpgradeLevel level = upgrade.getUpgradeLevel(island.getUpgradeLevel(upgrade));

Map<PotionEffectType, Integer> effects = level.getPotionEffects();
for (Map.Entry<PotionEffectType, Integer> entry : effects.entrySet()) {
    player.addPotionEffect(
        new PotionEffect(entry.getKey(), Integer.MAX_VALUE, entry.getValue() - 1)
    );
}

Potion effects are automatically applied to players while they’re on their island.

Role Limits

Limit how many players can have specific roles:

// Get role limit
int getRoleLimit(PlayerRole role);

// Get all role limits
Map<PlayerRole, Integer> getRoleLimits();

Example:

PlayerRole adminRole = PlayerRole.of("Admin");
int adminLimit = level.getRoleLimit(adminRole);

List<SuperiorPlayer> currentAdmins = island.getIslandMembers(adminRole);

if (currentAdmins.size() >= adminLimit) {
    player.sendMessage("Cannot promote: Admin limit reached!");
    return;
}

Upgrade Costs

Each level has an associated cost that must be paid:

// Get upgrade cost
UpgradeCost cost = level.getCost();

// Cost can be:
// - Money (economy)
// - Items
// - Placeholders/custom requirements

Cost System

// The cost system is extensible
UpgradeCost cost = level.getCost();

// Cost implementations handle:
// - Checking if player can afford
// - Withdrawing the cost
// - Displaying cost information

Upgrade Commands

Execute commands when an upgrade level is purchased:

List<String> commands = level.getCommands();

// Commands support placeholders:
// {player} - player name
// {island} - island owner name
// etc.

Example:

commands:
  - "give {player} diamond 10"
  - "broadcast {player} upgraded their island!"

Permission Requirements

Restrict upgrades by permission:

String permission = level.getPermission();

if (!permission.isEmpty() && !player.hasPermission(permission)) {
    player.sendMessage("You don't have permission for this upgrade!");
    return;
}

Custom Requirements

Implement custom requirements for upgrades:

// Check all requirements
String errorMessage = level.checkRequirements(player);

if (!errorMessage.isEmpty()) {
    // Requirements not met
    player.sendMessage(errorMessage);
    return false;
}

// Requirements met, can upgrade
return true;

Requirements can check:

Island worth
Island level
Completed missions
Custom conditions via placeholders

Applying Upgrades to Islands

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

Island island = player.getIsland();
Upgrade upgrade = SuperiorSkyblockAPI.getUpgrades().getUpgrade("crop-growth");

// Get current level
int currentLevel = island.getUpgradeLevel(upgrade).getLevel();

// Get next level
UpgradeLevel nextLevel = upgrade.getUpgradeLevel(currentLevel + 1);

// Check if can upgrade
if (nextLevel.getLevel() > currentLevel) {
    // Check cost, requirements, etc.
    // Then upgrade:
    island.setUpgradeLevel(upgrade, nextLevel.getLevel());
}

Always validate costs, permissions, and requirements before applying upgrades.

Common Upgrade Types

Member Limit

Increases the maximum number of island members.

int teamLimit = level.getTeamLimit();

Island Size

Expands the island border radius.

int borderSize = level.getBorderSize();
island.setIslandSize(borderSize);

Warp Slots

Increases available warp slots.

int warpLimit = level.getWarpsLimit();

Bank Capacity

Increases island bank storage limit.

BigDecimal bankLimit = level.getBankLimit();
island.setBankLimit(bankLimit);

Generator

Improves cobblestone generator drops.

Map<String, Integer> rates = level.getGeneratorAmounts(Dimension.NORMAL);

GUI Integration

Slot Management

Upgrades can appear in multiple inventory slots:

// Get all slots for this upgrade
List<Integer> slots = upgrade.getSlots();

// Check if upgrade is in specific slot
if (upgrade.isSlot(22)) {
    // Handle click on slot 22
}

// Set upgrade slots (usually done via config)
upgrade.setSlots(Arrays.asList(20, 21, 22));

Best Practices

Cache Upgrade Objects

Don’t repeatedly fetch upgrades. Store references when possible.

Check hasXXX() Methods

Always check if a property exists before using it (e.g., hasCropGrowth()).

Validate Level Existence

Check if the level exists before accessing properties.

Use Keys Consistently

Always use Key objects for blocks/entities, not material names.

Example: Complete Upgrade Flow

public boolean upgradeIsland(SuperiorPlayer player, String upgradeName) {
    Island island = player.getIsland();
    if (island == null) return false;
    
    // Get upgrade
    Upgrade upgrade = SuperiorSkyblockAPI.getUpgrades().getUpgrade(upgradeName);
    if (upgrade == null) return false;
    
    // Get current and next level
    int currentLevel = island.getUpgradeLevel(upgrade).getLevel();
    UpgradeLevel nextLevel = upgrade.getUpgradeLevel(currentLevel + 1);
    
    // Check if max level reached
    if (nextLevel.getLevel() == 0 || nextLevel.getLevel() <= currentLevel) {
        player.sendMessage("Maximum upgrade level reached!");
        return false;
    }
    
    // Check permission
    String permission = nextLevel.getPermission();
    if (!permission.isEmpty() && !player.hasPermission(permission)) {
        player.sendMessage("No permission for this upgrade!");
        return false;
    }
    
    // Check requirements
    String requirements = nextLevel.checkRequirements(player);
    if (!requirements.isEmpty()) {
        player.sendMessage(requirements);
        return false;
    }
    
    // Check and withdraw cost
    UpgradeCost cost = nextLevel.getCost();
    // Implement cost checking/withdrawal based on your cost system
    
    // Apply upgrade
    island.setUpgradeLevel(upgrade, nextLevel.getLevel());
    
    // Execute commands
    for (String command : nextLevel.getCommands()) {
        command = command.replace("{player}", player.getName());
        Bukkit.dispatchCommand(Bukkit.getConsoleSender(), command);
    }
    
    player.sendMessage("Successfully upgraded " + upgradeName + " to level " + nextLevel.getLevel());
    return true;
}

Islands

Learn how islands use upgrades

Configuration

Configure upgrade levels and costs

Getting Started

Core Concepts

Configuration

Features

Integrations

Documentation Index

​Overview

​Upgrade Structure

​Upgrade Interface

​Basic Properties

​Getting Upgrades

​Upgrade Levels

​Level Properties

​Upgrade Categories

​Production Multipliers

​Block & Entity Limits

​Block Limits

​Entity Limits

​Generator Rates

Normal World

Nether

End

​Island Effects

​Role Limits

​Upgrade Costs

​Cost System

​Upgrade Commands

​Permission Requirements

​Custom Requirements

​Applying Upgrades to Islands

​Common Upgrade Types

​GUI Integration

​Slot Management

​Best Practices

Cache Upgrade Objects

Check hasXXX() Methods

Validate Level Existence

Use Keys Consistently

​Example: Complete Upgrade Flow

​See Also

Islands

Configuration

Build docs developers (and LLMs) love

Overview

Upgrade Structure

Upgrade Interface

Basic Properties

Getting Upgrades

Upgrade Levels

Level Properties

Upgrade Categories

Production Multipliers

Block & Entity Limits

Block Limits

Entity Limits

Generator Rates

Island Effects

Role Limits

Upgrade Costs

Cost System

Upgrade Commands

Permission Requirements

Custom Requirements

Applying Upgrades to Islands

Common Upgrade Types

GUI Integration

Slot Management

Best Practices

Example: Complete Upgrade Flow

See Also