API Addons

New in Cultivation 0.5.0.

Events let you reshape what Cultivation does. Registries let you add content it treats as its own. The three hooks on this page go further: they let another mod take over a whole layer of Cultivation and keep everything else running on top.

All three are installed from your plugin's setup(), in any load order relative to Cultivation's own. Nothing reads them until a player meditates, opens a menu, or trips a realm gate, which is long after every plugin has loaded.

ProgressionProvider

CultivationAPI.setProgressionProvider(@Nullable ProgressionProvider provider)
CultivationAPI.getProgressionProvider()

Hands your mod the realm/stage/Qi ladder. From the moment one is installed, every command, UI page, HUD line and gameplay gate in Cultivation reads its numbers from you instead of from the player's CultivationComponent: /cultivation shows your rank names, the HUD shows your XP bar, the meditation ritual runs your rank-ups.

Everything else in the mod keeps working. Sects, the Dao, techniques, spirit beasts, formations, cave abodes, duels, alchemy, refinement and the skill tree all sit on top of whatever ladder is installed.

The methods you implement

plugin.siren.API.ProgressionProvider has 22 methods. Seventeen are abstract and you must write them; the other five have defaults. Every one is handed the ComponentAccessor<EntityStore> accessor and Ref<EntityStore> ref of the player being asked about (shown as accessor, ref), except where noted.

A minimal provider

A complete provider that keeps one number of its own. LadderComponent is your own persisted component; the interface is deliberately stateless, so your component stays the single source of truth.

public final class MyLadder implements ProgressionProvider {

    private static final int MAX_LEVEL = 30;

    @Nonnull @Override
    public String getId(){
        return "MyMod:ladder";
    }

    // --- Level ---

    @Override
    public int getLevel(@Nonnull ComponentAccessor<EntityStore> accessor, @Nonnull Ref<EntityStore> ref){
        LadderComponent ladder = accessor.getComponent(ref, LadderComponent.getComponentType());
        return ladder == null ? 1 : ladder.getLevel();
    }

    @Override
    public int getMaxLevel(){
        return MAX_LEVEL;
    }

    @Override
    public boolean isMaxLevel(@Nonnull ComponentAccessor<EntityStore> accessor, @Nonnull Ref<EntityStore> ref){
        return getLevel(accessor, ref) >= MAX_LEVEL;
    }

    // --- Progress ---

    @Override
    public float getProgress(@Nonnull ComponentAccessor<EntityStore> accessor, @Nonnull Ref<EntityStore> ref){
        LadderComponent ladder = accessor.getComponent(ref, LadderComponent.getComponentType());
        return ladder == null ? 0f : ladder.getXp();
    }

    @Override
    public float getProgressRequiredForNext(@Nonnull ComponentAccessor<EntityStore> accessor, @Nonnull Ref<EntityStore> ref){
        return isMaxLevel(accessor, ref) ? Float.MAX_VALUE : 100f * getLevel(accessor, ref);
    }

    @Override
    public void addProgress(@Nonnull ComponentAccessor<EntityStore> accessor, @Nonnull Ref<EntityStore> ref,
                            float amount, @Nullable PlayerRef playerRef){
        LadderComponent ladder = accessor.getComponent(ref, LadderComponent.getComponentType());
        if(ladder == null || isMaxLevel(accessor, ref)){
            return;
        }
        ladder.addXp(amount);
        CultivationAPI.refreshProgression(accessor, ref);   // keep the HUD bar live
    }

    // --- Display ---

    @Nonnull @Override
    public Message getRankLabel(@Nonnull ComponentAccessor<EntityStore> accessor, @Nonnull Ref<EntityStore> ref){
        return Message.translation("server.mymod.rank." + (getLevel(accessor, ref) / 10));
    }

    @Nullable @Override
    public Message getSubRankLabel(@Nonnull ComponentAccessor<EntityStore> accessor, @Nonnull Ref<EntityStore> ref){
        return Message.translation("server.mymod.label.level").param("level", String.valueOf(getLevel(accessor, ref)));
    }

    // --- Gating ---

    @Nonnull @Override
    public CultivationRealm getEquivalentRealm(@Nonnull ComponentAccessor<EntityStore> accessor, @Nonnull Ref<EntityStore> ref){
        CultivationRealm[] realms = CultivationRealm.values();
        return realms[Math.min(getLevel(accessor, ref) / 5, realms.length - 1)];
    }

    // --- Rituals: every tenth level is the milestone, the rest are routine ---

    private boolean banked(ComponentAccessor<EntityStore> accessor, Ref<EntityStore> ref){
        return !isMaxLevel(accessor, ref) && getProgress(accessor, ref) >= getProgressRequiredForNext(accessor, ref);
    }

    @Override
    public boolean isReadyForBreakthrough(@Nonnull ComponentAccessor<EntityStore> accessor, @Nonnull Ref<EntityStore> ref){
        return banked(accessor, ref) && getLevel(accessor, ref) % 10 == 9;
    }

    @Override
    public boolean isReadyForAdvancement(@Nonnull ComponentAccessor<EntityStore> accessor, @Nonnull Ref<EntityStore> ref){
        return banked(accessor, ref) && getLevel(accessor, ref) % 10 != 9;
    }

    @Override
    public float getBreakthroughDurationSeconds(@Nonnull ComponentAccessor<EntityStore> accessor, @Nonnull Ref<EntityStore> ref){
        return 60f;
    }

    @Override
    public float getAdvancementDurationSeconds(@Nonnull ComponentAccessor<EntityStore> accessor, @Nonnull Ref<EntityStore> ref){
        return 30f;
    }

    @Override
    public void completeBreakthrough(@Nonnull ComponentAccessor<EntityStore> accessor, @Nonnull Ref<EntityStore> ref,
                                     @Nullable PlayerRef playerRef){
        levelUp(accessor, ref);
    }

    @Override
    public void completeAdvancement(@Nonnull ComponentAccessor<EntityStore> accessor, @Nonnull Ref<EntityStore> ref,
                                    @Nullable PlayerRef playerRef){
        levelUp(accessor, ref);
    }

    private void levelUp(ComponentAccessor<EntityStore> accessor, Ref<EntityStore> ref){
        LadderComponent ladder = accessor.getComponent(ref, LadderComponent.getComponentType());
        if(ladder != null){
            ladder.levelUp();     // spends the banked progress and adds a level
        }
    }

    @Override
    public void demote(@Nonnull ComponentAccessor<EntityStore> accessor, @Nonnull Ref<EntityStore> ref,
                       @Nullable PlayerRef playerRef, boolean wasBreakthrough){
        LadderComponent ladder = accessor.getComponent(ref, LadderComponent.getComponentType());
        if(ladder != null){
            ladder.setXp(0f);     // a failed ritual costs the banked progress, never a level
        }
    }
}

Install it once from your plugin's setup():

CultivationAPI.setProgressionProvider(new MyLadder());

The five defaulted methods are left out above on purpose: getHealthBonus and getDamageMultiplier already scale with getLevel, supportsProfiles() stays false until you handle profile switches, and the two ...ForLevel labels only matter once you want offline players ranked under your names.

Realm gates

Dozens of gates across the mod are written against CultivationRealm -- a technique's unlock realm, a race's, a spirit beast species' minimum realm, refinement tiers, abode quality, the Dao unlock. Rather than rewrite them, Cultivation asks your provider which realm the player counts as:

@Nonnull CultivationRealm getEquivalentRealm(ComponentAccessor<EntityStore> accessor, Ref<EntityStore> ref);

Map your own levels onto the seven realms however you like, and every existing gate understands your progression for free. A straight proportional split of your level range is usually right; returning a constant works too, but then every realm-gated feature in the mod is either permanently open or permanently shut.

Two kinds of rank-up

Cultivation drives rank-ups through its timed meditation ritual and offers two flavours. Map your progression onto them however suits:

Only one may be ready at a time; isReadyForBreakthrough is tested first. Returning true from neither simply means meditation does its ordinary thing that tick. You also supply the ritual durations yourself through getBreakthroughDurationSeconds and getAdvancementDurationSeconds, so the built-in timings do not apply to your ladder.

What you store

The interface is deliberately stateless -- every method is handed the accessor and ref of the player being asked about, so your own persisted component stays the single source of truth. The player's CultivationComponent still exists and is left completely alone, which is what lets a server uninstall your addon and get its original realms back untouched.

Only one provider can be installed at a time. The last to register wins, and a warning naming both is logged, since two mods each believing they own progression is a misconfiguration rather than something to silently pick a winner for. Pass null to hand progression back to the built-in system.

Whenever your own code changes a player's level outside a rank-up, or their banked progress while a bar is on screen, call CultivationAPI.refreshProgression(accessor, ref). Cultivation cannot detect a change inside somebody else's component on its own, so anything that skips it leaves the HUD, the rankings and every realm gate showing the player's previous standing.

Profiles under a provider

v0.7.0 The interface gained one default method:

default boolean supportsProfiles(){
    return false;
}

And that default refuses profile switching outright while your provider is installed - the player is told another mod governs progression here. That is deliberate: a switch swaps the player's CultivationComponent, race, dao, skill tree and techniques underneath you, and a provider that has not planned for it would be left describing the wrong cultivator - half-performed is worse than refused.

To lift the refusal, do both of these and then return true:

• Handle ProfileEvents.PreProfileSwitchEvent - save your own state for the profile being left.
• Handle ProfileEvents.ProfileSwitchEvent - load your state for the arriving one.

Profile listeners are the one place in the API allowed to write components directly through the Store - they run on the world thread outside any ticking system, precisely so a provider can do this bookkeeping. See Events for the full ProfileEvents table. The one exception to the refusal is the operator's test sandbox, which is allowed even under a provider - it cannot change your addon's view of the player, and the command says so.

CultivationTheme

CultivationAPI.setTheme(@Nullable CultivationTheme theme)
CultivationAPI.getTheme()

Re-words the mod's entire player-facing vocabulary without touching its behavior, so a setting with soul masters and academies rather than cultivators and sects reads as its own game instead of a re-skin. Every string Cultivation shows a player -- chat, commands, HUD, menus, item names, tooltips -- is routed through your translate first, and whatever you return is used verbatim.

CultivationTheme has two methods:

@Nonnull String getId();                          // namespaced ("SoulRings:soul_land"); logging and /cultivation admin only
@Nullable Message translate(@Nonnull String key);   // the full key, always with its `server.` prefix

Return null from translate for any key you do not re-word and Cultivation's own wording is used, so a theme may cover as much or as little as it likes.

Why a hook and not a language file

Because the engine will not let you do it with one. Language files from every asset pack are merged into a single catalog, and that merge is first-writer-wins -- a duplicate key from a later pack is discarded and logged as 'x' has multiple definitions. Cultivation's own pack loads before any addon that depends on it, so an addon shipping server.cultivation.playerMsg.breakthrough in its own server.lang would be silently ignored, and even winning that race would only mean winning it on that particular boot.

So a theme keeps its strings under its own keys -- which collide with nothing -- and maps Cultivation's keys onto them.

translate is called on whatever thread is building the message, often several times per rendered line, so it must be fast, thread-safe and free of side effects -- a lookup in an immutable map is the intended shape. Any .param(...) placeholders Cultivation fills in are applied to whatever you return, so a replacement must keep the same placeholder names; drop one and it renders empty. Only one theme can be installed at a time; the last to register wins and a warning naming both is logged.

AdminConfigSection

CultivationAPI.registerAdminConfigSection(@Nonnull AdminConfigSection section)
CultivationAPI.unregisterAdminConfigSection(@Nonnull String sectionKey)
CultivationAPI.getAdminConfigSections()
CultivationAPI.getAdminConfigSection(@Nonnull String sectionKey)
CultivationAPI.newAdminConfigSection(String key, String labelKey, String hintKey, int sortOrder, Runnable save, List<AdminConfigField> fields)

Adds a group of tunable rows to Cultivation's admin menu, where it appears as its own section button on the Config tab of /cultivation admin beside Cultivation's own 53 -- with the same rows, the same editing, and the same single Save. The same settings also appear in a Mod Settings block at the bottom of the ordinary Cultivation settings menu, visible to admins only. The worked example, the five row factories and the tooltip rule are under Registries.

One section per config file is the shape Cultivation uses for itself and the one that reads best.

A row has one of five kinds (AdminConfigField.Kind): NUMBER (a decimal field, the default), INT, BOOLEAN (a real checkbox), CHOICE (a dropdown over AdminConfigChoices) and TEXT. Before 0.6.1 only numbers existed, so a master switch had to masquerade as a 0/1 field; that is no longer necessary. Keep anything list-shaped in the config file.

Both host pages are gated on cultivation.admin, and the gate is re-checked server-side on save rather than trusted from the menu, so a section may safely expose real balance numbers.

Registering the same section key twice replaces the first, so this is safe across a reload of your plugin.

Reading a player under any ladder

Three facade methods report a cultivator's standing under whichever system happens to be live, so your code does not need to know whether a provider is installed:

CultivationAPI.getRealm(accessor, ref) returns the effective realm, which is the provider's equivalent realm while one is installed -- this is what every gate in the mod tests against. CultivationAPI.getStage(accessor, ref) is always null under a provider, since a replacement ladder has no sub-stages -- it has only its own getSubRankLabel. Prefer getGlobalLevel for anything numeric.

The rankings and /cultivation top sort on that flattened level, so a replacement progression ranks correctly against itself. For the built-in ladder the ordering is exactly what realm-then-stage always produced.