Upgrades

Using upgrades, you can give your players custom perks that are upgradable. In this documentation, you will understand how to edit them to your own style!

The Upgrades Module

Upgrades are part of the upgrades module of the plugin. Therefore, they are configured in the config file of the module, located in plugins/SuperiorSkyblock2/modules/upgrades/config.yml, and not in the main config.yml of the plugin.

If you have an old upgrades.yml file from older versions of the plugin, it will be migrated automatically into the module's config file.

Besides the upgrades themselves, the config file of the module contains the following global settings:

Field	Default	Description
enabled	true	Whether the module should be enabled. When disabled, all module commands and features will also be disabled.
crop-growth	true	Whether crop-growth should be enabled. When disabled, the plugin will not alter crop growth.
mob-drops	true	Whether mob drops should be enabled. When disabled, the plugin will not alter mob drops.
island-effects	true	Whether island-effects should be enabled. When disabled, the plugin will not give any effects to any players.
spawner-rates	true	Whether spawner-rates should be enabled. When disabled, the plugin will not alter spawner rates.
block-limits	true	Whether block-limits should be enabled. When disabled, the plugin will not limit placement of blocks.
entity-limits	true	Whether entity-limits should be enabled. When disabled, the plugin will not limit spawning of entities.

Creating your first upgrade

Creating a new upgrade is an easy task to do! All the upgrades follow the same rules, but in this tutorial we will create a generator upgrade.

We will start with the basic layout for the upgrade:

upgrades:
  island-generators:        # The name of the upgrade.
    '1':                    # The first level of the upgrade.
      <to-do>
    '2':                    # The second level of the upgrade.
      <to-do>

All the upgrades work with the same layout: a global section for the upgrade, and sub-sections for every level of the upgrade. You can make as many levels as you want!

Now, we can start working on our first level. We will give it a price-type, price, commands to be executed upon rankup and a required permission to use the upgrade. In this case, I don't want a permission - so I don't add that section.

'1':
  price-type: 'money'      # The type of price handler. More information below.
  price: 100000.0          # The price to rank up to the second level.
  commands:
    - 'island admin setupgrade %player% island-generators 2'     # We must change the level of the upgrade manually using a command.
    - 'island admin msgall %player% &e&lUpgrade | &7%player% upgraded your generators to level 2!'   # Message that will be sent to the island members.
  permission:  <your-permission>   # You can add it if you want a required permission to rankup.

As you might have noticed, I run /is admin setupgrade - this is required so the plugin will actually change the upgrade's level for the island. Not doing so will make the upgrade to not rankup, as you'll see in the last level.

After we set up the basic layout of the level, we want to give it some values. The values will be synced with the island. You can change crop growth, spawner rates, mob drops, limits, generators and more with the upgrades! For this tutorial, I will change the generator rates using the "generator-rates" section:

'1':
 price-type: 'money'
 price: 100000.0
 commands:
   - 'island admin setupgrade %player% island-generators 2'
   - 'island admin msgall %player% &e&lUpgrade | &7%player% upgraded your generators to level 2!'
 generator-rates:
   normal:      # The world environment. Can use normal, nether or the_end.
     STONE: 85
     COAL_ORE: 10
     IRON_ORE: 5 

That's it! We completed our first level! Because this is the first level of the upgrade, it will be applied to all the islands by default. It means that all of the islands on my server will have the generator rates that I configured. Now, I will add more levels by following the same layout:

upgrades:
 island-generators:
   '1':
     price-type: 'money'
     price: 100000.0
     commands:
       - 'island admin setupgrade %player% island-generators 2'
       - 'island admin msgall %player% &e&lUpgrade | &7%player% upgraded your generators to level 2!'
     generator-rates:
       normal:
         STONE: 85
         COAL_ORE: 10
         IRON_ORE: 5 
   '2':
     price-type: 'money'
     price: 150000.0
     commands:
       - 'island admin setupgrade %player% island-generators 3'
       - 'island admin msgall %player% &e&lUpgrade | &7%player% upgraded your generators to level 3!'
     generator-rates:
       normal:
         STONE: 70
         COAL_ORE: 15
         IRON_ORE: 10
         DIAMOND_ORE: 5
   '3':
     price-type: 'money'
     price: 300000.0
     commands:
       - 'island admin setupgrade %player% island-generators 4'
       - 'island admin msgall %player% &e&lUpgrade | &7%player% upgraded your generators to level 4!'
     generator-rates:
       normal:
         STONE: 50
         COAL_ORE: 25
         IRON_ORE: 15
         DIAMOND_ORE: 10

After I configured all of my levels, I must also add the last upgrade - level #4. Unlike the other upgrades, this upgrade will not have the setupgrade command, but will still have values assigned to it:

'4':
  price-type: 'money'
  price: 0.0       # I set the price to 0, so my players will always get the warning message.
  commands:
    - 'island admin msg %player% &c&lError | &7You have reached the maximum upgrade for island generators.'
  generator-rates:
    normal:
      EMERALD_ORE: 50
      DIAMOND_ORE: 50

Finally, I have a working generator upgrade that will have it's values synced with all the islands. You can change the values anytime you want, and your islands will be synced automatically with it. Removing existing levels is not an option - you can just make the upgrade to do nothing, but removing it completely will cause errors from the plugin.

Level Fields

Every level of an upgrade can have the following fields:

Field	Type	Description
price-type	String	The type of the price handler. Optional; when omitted, defaults to money. The value is case-insensitive. If an invalid price-type is used, the level will be skipped.
price	Double	The cost to upgrade to the next level.
commands	List	Commands that will be executed by the console when the level is purchased. You can use %player% for the player's name.
permission	String	Optional permission that is required to rankup to the configured level.
required-checks	List	Optional conditions that must be met to purchase the level. More information below.

Required Checks

Using the required-checks field, you can add custom conditions that players must meet before they can purchase a level. Each entry in the list is in the format <condition>;<error-message>: the condition is evaluated by the JavaScript engine (placeholders are supported), and if it's not met, the error message will be sent to the player.

For example, requiring the island to be at least level 10 in order to purchase the level:

'2':
  price-type: 'money'
  price: 150000.0
  required-checks:
    - '%superior_island_level% >= 10;&cYour island must be level 10 or higher to purchase this upgrade!'
  commands:
    - ...

Island Values

You can use the following sections to alter island values:

Field	Type	Description
crop-growth	Double	The crop growth multiplier for this upgrade.
spawner-rates	Double	The spawner rates multiplier for this upgrade.
mob-drops	Double	The mob drops multiplier for this upgrade.
team-limit	Integer	The team limit for this upgrade.
warps-limit	Integer	The warps limit for this upgrade.
coop-limit	Integer	The coops limit for this upgrade.
border-size	Integer	The border size for this upgrade. Must not exceed the max-island-size from the main config, otherwise the level will be skipped.
bank-limit	String	The maximum amount of money that can be deposited into the island bank for this upgrade. Supports large numbers.
block-limits	Section	The block limits for this upgrade. All the blocks are in the format TYPE: LIMIT. Block types also support data values, in the format TYPE:DATA.
entity-limits	Section	The entity limits for this upgrade. All the entities are in the format TYPE: LIMIT.
generator-rates	Section	The generator rates for this upgrade. The rates are configured per world environment (normal, nether or the_end), with all the rates in the format TYPE: CHANCE. Rates that are placed directly under the section (legacy format) will apply to the default world of the plugin.
island-effects	Section	The island effects for this upgrade. All the effects are in the format EFFECT: LEVEL, where the level is the in-game effect level (SPEED: 1 gives Speed I). Invalid effect names are ignored.
role-limits	Section	The role limits for this upgrade. All the roles are in the format ROLE-ID: LIMIT, where the role id is the numeric id (weight) of the role from the main config, not its name.

Price Types

The plugin has two pre-defined price types - money based prices and placeholders based prices. Simply add the price-type section to your upgrade with the price-type you want. Currently there are two different ones: money and placeholders:

money

When using this price-type, money will be taken from the players' bank (Essentials or any other economy plugin).

You must add the following fields to your upgrade to get this working:

Required Field	Type	Description
price	Double	The cost to upgrade to next level.

placeholders

When using this price-type, money will be taken by executing custom commands, and the balance will be parsed by a placeholder.

You must add the following fields to your upgrade to get this working:

Required Field	Type	Description
price	Double	The cost to upgrade to next level.
placeholder	String	The placeholder that represents the balance of the player.
withdraw-commands	List	A list of commands to be executed for withdrawing money. You can use %player% for player's name and %amount% for the amount to withdraw.

You can register custom price types using the API.

Example

In the example below, you can find two upgrades (each has only one level) with different price types.

The first upgrade, money-example-upgrade, has a money price-type configured to it. The second one, placeholders-example-upgrade, has a placeholders price-type. For this example, assume the placeholder %custom_economy_balace% returns an integer with the balance of the player and the command /customeco take <player-name> <price> takes the given balance from the given player.

upgrades:
  money-example-upgrade:
    '1':
      price: 1000000.0
      price-type: 'money'
      commands:
        - ...
  placeholders-example-upgrade:
    '1':
      price: 1000000.0
      price-type: 'placeholders'
      placeholder: '%custom_economy_balance%'
      withdraw-commands:
      - 'customeco take %player% 1000000'
      commands:
        - ...