InsurgenceBoosters

WIP

Setup

Installing The Plugin
Creating Your First Booster
Addon Roundup

Messages

Prefix
Json
Player Variable
Send Message As Action Bar
Send Message As Toast
Send Message As A Title
Send Message As A Boss Bar
Center A Message In Chat

Developer API

Creating an Addon
Creating a Custom Booster (Java)
Creating an Effect Booster (Java)

Placeholders

PlaceholderAPI

Setup

Get yourself started with the plugin!

Setup

Installing The Plugin

After downloading the plugin from BuiltByBit, place it in the plugins folder on your server. That's it!

InsurgenceBoosters | Boosters

Setup

Creating Your First Booster

The command below can be used to generate a booster. It will produce an automatically generated booster file that you can customize to your preference!

/iboosters create <type> <namespace>

Type: Can be anything that describes the kind of booster it will be. Take experience and money as examples.
Namespace: Anything that uniquely distinguishes it from other boosters. Take MY_BOOSTER and VANILLA as examples.

Following the execution of that command, a new file should be visible in the /plugins/IBoosters/boosters folder.

Setup

Addon Roundup

What are addons?

Addons are used to extend the capabilities of the main plugin. We offer free addons which provide support for other plugins and also add additional features to the main plugin. You can view the entire list of addons on BuiltByBit. There are two types of addons, those that add support to plugins and those that add features to the main plugin. Plugin support addons will mostly be a .Lua file. They can also be .jar files depending on the complexity.

Below is a list of plugins we currently support. We are open to suggestions.

Loading an addon

For an addon to be loaded, the .jar or .Lua file must be placed in the plugins\IBoosters\addons folder followed by the execution of the plugin's reload command or a server restart. You can verify if an addon has been loaded by running the command /iboosters addons.

Implementing an addon

Feature addons will work once loaded; no extra steps required. Plugin support addons are identified by a Type and a Namespace. You should be able to open the .Lua files with any given text editor and retrieve the type and namespace which is usually located at the top. See below example.

name = "Sellwand-Addon"
version = "1.0.0"
author = "Hxtch"
description = {"This addon will add", "Support for Sellwand boosting"}

local TYPE = "Sell"			   <<---------------------
local NAMESPACE = "SELLWAND"   <<---------------------

utils.subscribeToEvent("me.zachary.sellwand.api.events.SellwandSellEvent", function(event)
    local multi = boosterUtils.getMulti(event:getPlayer(), TYPE, NAMESPACE)

    if multi > 0 then
        event:setSellPrice(boosterUtils.calculateAmount(event:getSellPrice(), multi))
    end
end)

You will then be required to use the type and namespace in a booster's YAML file and that's it! See below example.

Type: Sell           <<---------------------
Namespace: SELLWAND  <<---------------------
Type_Display_Name: "Money"
Type_Menu_Item:
  Icon: GOLD_INGOT
  Display_Name: "&c&lMoney Booster"
  Priority: 0
  Model_Data: 0
  Lore:
    - ""
    - "&7&oThis boosts the amount"
    - "&7&o of money you earn"
    - ""
    - "&7Amount: &f{amount}"
    - ""
    - "&fClick &7to view your boosters"
Global_Item:
  Icon: GOLD_INGOT
  Model_Data: 0
  Display_Name: "&f&lGlobal &c&lMoney Booster"
  Glow_When_Active: false
  Inactive_Lore:
    - ""
    - "&7&oThis boosts the amount"
    - "&7&o of money you earn"
    - ""
    - "&7Time: &f{time}"
    - "&7Multiplier: &fx{multiplier}"
    - ""
    - "&fClick &7to activate"
  Activated_Lore:
    - ""
    - "&7&oThis boosts the amount"
    - "&7&o of money you earn"
    - ""
    - "&7Time: &f{time}"
    - "&7Multiplier: &fx{multiplier}"
    - "&7Remaining time: &f{remaining}"
Personal_Item:
  Icon: GOLD_INGOT
  Model_Data: 0
  Display_Name: "&f&lPersonal &c&lMoney Booster"
  Glow_When_Active: false
  Inactive_Lore:
    - ""
    - "&7&oThis boosts the amount"
    - "&7&o of money you earn"
    - ""
    - "&7Time: &f{time}"
    - "&7Multiplier: &fx{multiplier}"
    - ""
    - "&fClick &7to activate"
  Activated_Lore:
    - ""
    - "&7&oThis boosts the amount"
    - "&7&o of money you earn"
    - ""
    - "&7Time: &f{time}"
    - "&7Multiplier: &fx{multiplier}"
    - "&7Remaining time: &f{remaining}"
Menu:
  Title: "Money Boosters"
  Size: 45
  Booster_Slots: [ 10, 11, 12, 13, 14, 15, 16, 19, 20, 21, 22, 23, 24, 25 ]
  Inactive_Booster_Button:
    Icon: PAPER
    Display_Name: "&d&lActive Boosters"
    Slot: 40
    Model_Data: 0
    Lore:
      - ""
      - "&d│ &7None"
      - ""
      - "&7➥ Activate a booster"
  Deactivate_Booster_Button:
    Icon: BARRIER
    Display_Name: "&c&lDeactivate"
    Slot: 41
    Model_Data: 0
    Lore:
      - ""
      - "&7➥ Deactivate the booster"
  Previous_Page_Button:
    Slot: 9
    Icon_Script: |-
      if canGo then
        return "LIME_DYE"
      else
        return "GRAY_DYE"
      end
    Model_Data: 0
  Next_Page_Button:
    Slot: 17
    Icon_Script: |-
      if canGo then
        return "LIME_DYE"
      else
        return "GRAY_DYE"
      end
    Model_Data: 0
  Misc_Items:
    - Display_Name: "&7"
      Slots: [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 41, 42, 43, 44 ]
      Icon: BLACK_STAINED_GLASS_PANE
      Lore: []
      Glow: false
      Hide_Attributes: true
      Model_Data: 0
    - Display_Name: "&7"
      Slots: [ 18, 26 ]
      Icon: GRAY_STAINED_GLASS_PANE
      Lore: []
      Glow: false
      Hide_Attributes: true
      Model_Data: 0

Messages

The list of actions that can be taken on messages. Hex colors are supported in all messages.

Messages

Prefix

Insert the Prefix from settings.yml into any message just add {prefix} to the message

Messages

Json

Minecraft allows you to create more advanced messages using Json you can use a json text generator like this one here

To use json in a message all you have to do is put [JSON] at the start of the message

Example:

"[JSON]["",{"text":"Example ","color":"dark_red"},{"text":"message ","color":"#E124E1"},{"text":"with ","color":"dark_gray"},{"text":"hover ","color":"gold","hoverEvent":{"action":"show_text","contents":"Hover text!"}},{"text":"text","color":"red"}]"

Messages

Player Variable

You can also show the players name by inserting {player} into the message

Messages

Send Message As Action Bar

You can choose to send a chat message as an actionbar instead by adding <actionbar> to the start of the message

Messages

Send Message As Toast

You can choose to send a chat message as a toast by adding <toast> to the start of the message

Messages

Send Message As A Title

You can choose to send a chat message as a title by adding <title> to the start of the message

Messages

Send Message As A Boss Bar

You can choose to send a chat message as a bossbar by adding <bossbar> to the start of the message, it will show a boss bar for 10 seconds.

Messages

Center A Message In Chat

To center a message in chat add <center> to the start of the message.

Developer API

Use our robust API to put your unique ideas into practice.

Developer API

Creating an Addon

Assuming you have already created your empty project, you will be required to create a new directory

called libs by right-clicking your main folder and clicking New -> Directory.

Cope and paste your IBoosters JAR file into that new folder.

Adding InsurgenceBoosters as a dependency

Add the below dependencies to your pom.xml file; replace {JAR-NAME} with the name of your IBoosters JAR file. A reference to the Spigot API is also included.

    <dependencies>
        <dependency>
            <groupId>org.insurgencedev</groupId>
            <artifactId>IBoosters</artifactId>
            <version>LATEST</version>
            <scope>system</scope>
            <systemPath>${project.basedir}/src/main/libs/{JAR-NAME}</systemPath>
        </dependency>
        <dependency>
            <groupId>org.spigotmc</groupId>
            <artifactId>spigot-api</artifactId>
            <version>1.20.2-R0.1-SNAPSHOT</version>
        </dependency>
    </dependencies>

Setting up the main class

After creating your main class, it should extend InsurgenceBoostersAddon and override the necessary methods. The class should also be annotated with @IboostersAddon.

package com.insurgencedev.exampleaddon;

import org.insurgencedev.insurgenceboosters.api.addon.IBoostersAddon;
import org.insurgencedev.insurgenceboosters.api.addon.InsurgenceBoostersAddon;

@IBoostersAddon(name = "ExampleAddon", version = "1.0.0", author = "Insurgence Dev Team", description = "Example Addon")
public class ExampleAddon extends InsurgenceBoostersAddon {

    @Override
    public void onAddonStart() {
    }

    @Override
    public void onAddonReloadablesStart() {
    }

    @Override
    public void onAddonReload() {
    }

    @Override
    public void onAddonStop() {
    }

}

Creating a custom config

Make a fresh class. It should extend the AddonConfig class and override the onLoad() function. To load and generate your configuration file based on the file in your internal resource folder, make sure the loadAddonConfig() method is used in the constructor.

package org.insurgencedev.exampleaddon;

import org.insurgencedev.insurgencesets.api.addon.AddonConfig;

public class CustomConfig extends AddonConfig {

    public static String MYSTRING = null;


    public CustomConfig() {
        loadAddonConfig("config.yml", "config.yml");
    }

    @Override
    protected void onLoad() {
        MYSTRING = getString("Test");
    }
}

Developer API

Creating a Custom Booster (Java)

Below is an example of an Experience booster. When a player receives exp, the amount received will be multiplied based on the boosters that are active. We locate active personal and global boosters of the required Type and Namespace. If located, we apply the associated multipliers.

package com.insurgencedev.exampleaddon.listeners;

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerExpChangeEvent;
import org.insurgencedev.insurgenceboosters.api.IBoosterAPI;
import org.insurgencedev.insurgenceboosters.models.booster.GlobalBoosterManager;
import org.insurgencedev.insurgenceboosters.settings.IBoostersPlayerCache;

public final class ExperienceChangeListener implements Listener {

    @EventHandler
    private void onChange(PlayerExpChangeEvent event) {
        final String TYPE = "Experience";
        final String NAMESPACE = "CUSTOM";
        double totalMulti = 1;

        IBoostersPlayerCache.BoosterFindResult pResult = IBoosterAPI.getCache(event.getPlayer()).findActiveBooster(TYPE, NAMESPACE);
        if (pResult instanceof IBoostersPlayerCache.BoosterFindResult.Success boosterResult) {
            totalMulti += boosterResult.getBooster().getMultiplier();
        }

        GlobalBoosterManager.BoosterFindResult gResult = IBoosterAPI.getGlobalBoosterManager().findBooster(TYPE, NAMESPACE);
        if (gResult instanceof GlobalBoosterManager.BoosterFindResult.Success boosterResult) {
            totalMulti += boosterResult.getBooster().getMultiplier();
        }

        event.setAmount((int) (event.getAmount() * totalMulti));
    }
}

Register your listener

For your listener class to take effect, it must be registered.

package com.insurgencedev.exampleaddon;

import com.insurgencedev.exampleaddon.listeners.ExperienceChangeListener;
import org.insurgencedev.insurgenceboosters.api.addon.IBoostersAddon;
import org.insurgencedev.insurgenceboosters.api.addon.InsurgenceBoostersAddon;

@IBoostersAddon(name = "ExampleAddon", version = "1.0.0", author = "Insurgence Dev Team", description = "Example Addon")
public class ExampleAddon extends InsurgenceBoostersAddon {

    @Override
    public void onAddonReloadablesStart() {
        registerEvent(new ExperienceChangeListener());
    }

}

Developer API

Creating an Effect Booster (Java)

Below is an example of how you can create a booster that applies effects to the player

Main Class

package com.insurgencedev.potioneffectsaddon;

import com.insurgencedev.potioneffectsaddon.listeners.BoosterListener;
import org.insurgencedev.insurgenceboosters.api.addon.IBoostersAddon;
import org.insurgencedev.insurgenceboosters.api.addon.InsurgenceBoostersAddon;

@IBoostersAddon(name = "PotionEffects", version = "1.0.0", author = "Insurgence Dev Team", description = "Apply Potion Effects")
public class PotionEffectsAddon extends InsurgenceBoostersAddon {

    @Override
    public void onAddonStart() {
        new MyConfig();
    }

    @Override
    public void onAddonReloadablesStart() {
        registerEvent(new BoosterListener());
    }

}

Listener Class

package com.insurgencedev.potioneffectsaddon.listeners;

import com.insurgencedev.potioneffectsaddon.MyConfig;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerItemConsumeEvent;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.event.player.PlayerRespawnEvent;
import org.bukkit.potion.PotionEffectType;
import org.insurgencedev.insurgenceboosters.api.IBoosterAPI;
import org.insurgencedev.insurgenceboosters.events.IBoosterEndEvent;
import org.insurgencedev.insurgenceboosters.events.IBoosterStartEvent;
import org.insurgencedev.insurgenceboosters.libs.fo.Common;
import org.insurgencedev.insurgenceboosters.libs.fo.remain.CompMaterial;
import org.insurgencedev.insurgenceboosters.models.booster.GlobalBoosterManager;
import org.insurgencedev.insurgenceboosters.settings.IBoostersPlayerCache;

import java.util.ArrayList;
import java.util.List;
import java.util.UUID;

public final class BoosterListener implements Listener {

    private final List<UUID> activeList = new ArrayList<>();
    private final String NAMESPACE = "CUSTOM_EFFECT";

    @EventHandler
    private void onStart(IBoosterStartEvent event) {
        if (event.getBoosterData().getType().equals(MyConfig.boosterType) &&
                event.getBoosterData().getNamespace().equals(NAMESPACE)) {

            Player player = event.getPlayer();

            if (MyConfig.disabledWorlds.contains(player.getWorld().getName())) {
                event.getBoosterData().setActive(false);
                return;
            }

            if (alreadyHasEffect(player)) {
                event.getBoosterData().setActive(false);
                return;
            }

            activeList.add(player.getUniqueId());
            applyEffect(player);
        }
    }

    @EventHandler
    private void onEnd(IBoosterEndEvent event) {
        if (event.getBoosterData().getType().equals(MyConfig.boosterType) &&
                event.getBoosterData().getNamespace().equals(NAMESPACE)) {

            Player player = event.getPlayer();

            activeList.remove(player.getUniqueId());
            removeEffect(player);
        }
    }

    @EventHandler
    private void onConsume(PlayerItemConsumeEvent event) {
        if (CompMaterial.fromItem(event.getItem()).equals(CompMaterial.MILK_BUCKET)) {
            Player player = event.getPlayer();

            IBoostersPlayerCache.BoosterFindResult pResult = IBoosterAPI.getCache(player).findActiveBooster(MyConfig.boosterType, NAMESPACE);
            if (pResult instanceof IBoostersPlayerCache.BoosterFindResult.Success) {
                Common.runLater(2, () -> applyEffect(player));
                return;
            }

            GlobalBoosterManager.BoosterFindResult gResult = IBoosterAPI.getGlobalBoosterManager().findBooster(MyConfig.boosterType, NAMESPACE);
            if (gResult instanceof GlobalBoosterManager.BoosterFindResult.Success) {
                Common.runLater(2, () -> applyEffect(player));
            }
        }
    }

    @EventHandler(priority = EventPriority.MONITOR)
    private void onRespawn(PlayerRespawnEvent event) {
        Player player = event.getPlayer();

        IBoostersPlayerCache.BoosterFindResult pResult = IBoosterAPI.getCache(player).findActiveBooster(MyConfig.boosterType, NAMESPACE);
        if (pResult instanceof IBoostersPlayerCache.BoosterFindResult.Success) {
            Common.runLater(2, () -> applyEffect(player));
            return;
        }

        GlobalBoosterManager.BoosterFindResult gResult = IBoosterAPI.getGlobalBoosterManager().findBooster(MyConfig.boosterType, NAMESPACE);
        if (gResult instanceof GlobalBoosterManager.BoosterFindResult.Success) {
            Common.runLater(2, () -> applyEffect(player));
        }
    }

    @EventHandler(priority = EventPriority.MONITOR)
    private void onJoin(PlayerJoinEvent event) {
        GlobalBoosterManager.BoosterFindResult gResult = IBoosterAPI.getGlobalBoosterManager().findBooster(MyConfig.boosterType, NAMESPACE);
        if (gResult instanceof GlobalBoosterManager.BoosterFindResult.Success) {
            Player player = event.getPlayer();

            if (!activeList.contains(player.getUniqueId())) {
                activeList.add(player.getUniqueId());
                Common.runLater(2, () -> applyEffect(player));
            }
        }
    }
  
  @EventHandler(priority = EventPriority.MONITOR)
    private void onLeave(PlayerQuitEvent event) {
        Player player = event.getPlayer();

        IBoostersPlayerCache.BoosterFindResult pResult = IBoosterAPI.getCache(player).findActiveBooster(MyConfig.boosterType, NAMESPACE);
        if (pResult instanceof IBoostersPlayerCache.BoosterFindResult.Success) {
            removeEffect(player);
            return;
        }

        GlobalBoosterManager.BoosterFindResult gResult = IBoosterAPI.getGlobalBoosterManager().findBooster(MyConfig.boosterType, NAMESPACE);
        if (gResult instanceof GlobalBoosterManager.BoosterFindResult.Success) {
            removeEffect(player);
        }
    }

    @EventHandler(priority = EventPriority.MONITOR)
    private void onKick(PlayerKickEvent event) {
        Player player = event.getPlayer();

        IBoostersPlayerCache.BoosterFindResult pResult = IBoosterAPI.getCache(player).findActiveBooster(MyConfig.boosterType, NAMESPACE);
        if (pResult instanceof IBoostersPlayerCache.BoosterFindResult.Success) {
            removeEffect(player);
            return;
        }

        GlobalBoosterManager.BoosterFindResult gResult = IBoosterAPI.getGlobalBoosterManager().findBooster(MyConfig.boosterType, NAMESPACE);
        if (gResult instanceof GlobalBoosterManager.BoosterFindResult.Success) {
            removeEffect(player);
        }
    }

    private boolean alreadyHasEffect(Player player) {
        PotionEffectType type = PotionEffectType.getByName(MyConfig.effectNamespace);
        return type != null && player.hasPotionEffect(type);
    }

    private void applyEffect(Player player) {
        PotionEffectType type = PotionEffectType.getByName(MyConfig.effectNamespace);
        if (type != null) {
            player.addPotionEffect(type.createEffect(Integer.MAX_VALUE, MyConfig.effectAmplifier - 1));
        }
    }

    private void removeEffect(Player player) {
        PotionEffectType type = PotionEffectType.getByName(MyConfig.effectNamespace);
        if (type != null) {
            player.removePotionEffect(type);
        }
    }
}

Custom Config Class

package com.insurgencedev.potioneffectsaddon;

import lombok.Getter;
import org.insurgencedev.insurgenceboosters.api.addon.AddonConfig;

import java.util.List;

@Getter
public class MyConfig extends AddonConfig {

    public static String boosterType;
    public static String effectNamespace;
    public static int effectAmplifier;
    public static List<String> disabledWorlds;

    public MyConfig() {
        loadAddonConfig("config.yml", "config.yml");
    }

    @Override
    protected void onLoad() {
        boosterType = getString("Type");
        effectNamespace = getString("Effect");
        effectAmplifier = getInteger("Amplifier");
        disabledWorlds = getStringList("Disabled_Worlds");
    }
}

Internal Config file

Type: Strength
Effect: INCREASE_DAMAGE
Amplifier: 2
Disabled_Worlds:
  - example

Placeholders

PlaceholderAPI

Below is a list of placeholders that can be used to retrieve data about the boosters.

{scope} - Booster scope (Personal or Global)
{type} - Name of the booster (Money, Token)
{namespace} - Unique identifier for the booster (CUSTOM, VANILLA)

Get how much time is left on an active booster

%iboosters_{scope}_{type}_{namespace}_time_left%

Get the multiplier of an active booster

%iboosters_{scope}_{type}_{namespace}_multiplier%

Get the owner of an active global booster

%iboosters_global_{type}_{namespace}_owner%

Returns whether or not a booster is active

%iboosters_{scope}_{type}_{namespace}_is_active%

Returns a permanent booster

%iboosters_{scope}_{type}_{namespace}_permanent%