External Booster Integration

Virtual Booster System

Virtual boosters are special, read-only boosters that are generated at runtime. They are NOT stored in the database by the booster module.

What are Virtual Boosters?

Virtual boosters are the bridge between the booster UI and other modules.

They are designed to show up in booster menus, placeholders, and list commands so players can see they have a boost from another system, such as Masks.

In other words:

• the virtual booster provider makes the buff visible inside the booster system

• the source module still applies the real gameplay effect in its own listeners / logic

Important Distinction

Registering a VirtualBoosterProvider by itself does not make the booster module apply that multiplier in getCombinedMultiplier(...).

However, that does not mean the buff is fake.

For Masks specifically, the mask buff is applied for real through the masks module's event listeners. The virtual booster simply makes that same buff appear in /boosters, placeholders, and booster menus.

For the virtual booster system to work, you MUST have the booster module enabled. If you do not have the module enabled, it simply won't work as the interface can't reference none instantiated classes or objects.

Implementing a Virtual Provider

To add virtual boosters, you must implement the VirtualBoosterProvider interface.

MaskVirtualBoosterProvider.java

public final class MaskVirtualBoosterProvider implements VirtualBoosterProvider {

    private final String SOURCE_ID = "masks";

    @Override
    public String getSourceId() {
        return SOURCE_ID;
    }

    @Override
    public List<ActiveBooster> getVirtualBoosters(UUID playerId) {
        // Return display entries that mirror your module's current buffs
        // Note: This method does NOT set the players boosters, so they won't gain any multipliers. 
        // this is purely for displaying in menus, placeholders and other sources.
        return maskManager.getCachedVirtualBoosters(playerId);
    }
}

Registering the Provider

Once you've implemented your provider, you must register it with the BoosterManager.

MasksModule.java

BoostersModule boostersModule = AbstractPhantomModule.getModuleByClass(context, BoostersModule.class);
if (boostersModule != null && boostersModule.getBoosterManager() != null) {
    boostersModule.getBoosterManager().registerVirtualProvider(new MaskVirtualBoosterProvider(maskManager));
}

Example: Masks

The Masks Module uses this system in two ways:

1. It registers a virtual provider so mask buffs show inside the booster UI.

2. It applies the actual buff values through its own event listeners. (i.e Currency Events, Damage Events, etc)

Rule of Thumb

If you build your own virtual-booster-backed module:

• use VirtualBoosterProvider to display the buff in the booster system

• use your own listeners / hooks to apply the buff to gameplay

If you only do the first part, it will be display-only. If you do both parts, like Masks does, the boost is fully functional.