编写扩展

Cultivation 0.5.0 新增。

事件让你重塑 Cultivation 的所作所为。注册表让你添加它视如己出的内容。而本页的三个钩子走得更远：它们让另一个模组接管 Cultivation 的一整个层次，同时让其余一切照常在其之上运行。

三者皆从你插件的 setup() 中安装，相对于 Cultivation 自身的加载顺序不限。在玩家打坐、打开菜单或触及某道境界门槛之前，无人读取它们，而那已远在每个插件加载完毕之后。

ProgressionProvider

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

把境界／阶段／灵气的阶梯交到你的模组手里。自安装的那一刻起，Cultivation 中每一条指令、每一个界面页、每一行状态栏与每一道玩法门槛，都改从你这里读取数字，而不再读玩家的 CultivationComponent：/cultivation 显示你的等级名，状态栏显示你的经验条，打坐仪式跑的是你的升级。

模组中其余一切照常运作。宗门、大道、功法、灵兽、阵法、洞府、斗法、炼丹、炼器与天赋树，一律架在当前所安装的那条阶梯之上。

你需要实现的方法

plugin.siren.API.ProgressionProvider 共有 22 个方法。其中十七个是抽象方法，必须由你来写；其余五个带有默认实现。除另有注明者外，每个方法拿到的都是被询问玩家的 ComponentAccessor<EntityStore> accessor 与 Ref<EntityStore> ref（下表缩写为 accessor, ref）。

一个最小的 provider

一个完整的 provider，只维系一个属于它自己的数字。LadderComponent 是你自己持久化的组件；这个接口刻意是无状态的，所以你的组件始终是唯一的事实来源。

public final class MyLadder implements ProgressionProvider {

    private static final int MAX_LEVEL = 30;

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

    // --- 等级 ---

    @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;
    }

    // --- 进度 ---

    @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);   // 让状态栏的进度条保持实时
    }

    // --- 展示 ---

    @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)));
    }

    // --- 门槛 ---

    @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)];
    }

    // --- 仪式：每逢第十级为里程碑，其余皆寻常 ---

    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();     // 花掉已存进度，并加一级
        }
    }

    @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);     // 仪式失败只损失已存进度，绝不掉级
        }
    }
}

只需在你插件的 setup() 中安装一次：

CultivationAPI.setProgressionProvider(new MyLadder());

上例刻意略去了那五个带默认实现的方法：getHealthBonus 与 getDamageMultiplier 本就随 getLevel 缩放；supportsProfiles() 在你处理好存档切换之前应保持 false；而那两个 ...ForLevel 标签，只有当你想让离线玩家也以你的名号上榜时才有意义。

境界门槛

模组中数十道门槛是针对 CultivationRealm 写的 —— 一门功法的解锁境界、一个种族的解锁境界、一种灵兽的最低境界、炼器阶数、洞府品质、大道解锁。Cultivation 不去重写它们，而是询问你的 provider：这名玩家算作哪个境界：

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

随你把自己的等级映射到那七个境界上，此后每一道既有门槛都会白白地读懂你的进阶体系。把你的等级区间按比例均分，通常就是对的；返回一个常量也行，但那样一来，模组中每一项受境界限制的功能，不是永远敞开，就是永远关死。

两种升级

Cultivation 通过其计时打坐仪式驱动升级，并提供两种风味。随你把自己的进阶体系映射上去：

同一时刻只能有一种就绪；isReadyForBreakthrough 会被先行检验。两者都不返回 true，不过意味着打坐在这一 tick 做它寻常该做的事。仪式时长也由你自己经由 getBreakthroughDurationSeconds 与 getAdvancementDurationSeconds 供给，因此内置的那套时长对你的阶梯并不适用。

你所存储的东西

这个接口刻意是无状态的 —— 每个方法都会拿到被询问玩家的 accessor 与 ref，因此你自己持久化的组件始终是唯一的事实来源。玩家的 CultivationComponent 依然存在且被完全放置不动，正是这一点让服务器得以卸载你的扩展，并原封不动地取回它原本的境界。

同一时刻只能安装一个 provider。最后注册者胜出，并会记录一条同时点名双方的警告 —— 因为两个模组各自都认为自己拥有进阶体系，这是一种配置错误，而不是该悄悄挑一个赢家的事。传入 null 即可把进阶体系交还给内置系统。

每当你自己的代码在升级之外改动了玩家的等级，或在进度条正显示于屏幕时改动了他的已存进度，请调用 CultivationAPI.refreshProgression(accessor, ref)。Cultivation 自己无从察觉别人组件内部发生的改变，所以凡是跳过这一步的，都会让状态栏、排行与每一道境界门槛仍显示玩家先前的境况。

provider 治下的存档

v0.7.0 该接口新增了一个 default 方法：

default boolean supportsProfiles(){
    return false;
}

而这个默认值会在你的 provider 安装期间直接回绝存档切换 —— 玩家会被告知此处的进阶体系由另一个模组掌管。这是刻意为之：一次切换会在你脚下换掉玩家的 CultivationComponent、种族、大道、天赋树与功法，而一个未曾为此做好准备的 provider，届时描述的将是错误的那名修士 —— 做到一半，比直接回绝更糟。

要解除这道回绝，请完成以下两件事，随后返回 true：

• 处理 ProfileEvents.PreProfileSwitchEvent —— 为即将离开的那份存档保存你自己的状态。
• 处理 ProfileEvents.ProfileSwitchEvent —— 为抵达的那份存档载入你的状态。

存档监听器是整个接口中唯一被允许直接经由 Store 写入组件的地方 —— 它们运行在世界线程上，且在任何 tick 系统之外，正是为了让 provider 能做这份记账。完整的 ProfileEvents 表见事件。这道回绝有一个例外：操作员的试炼存档沙盒即便在 provider 治下也照样被允许 —— 它不会改变你的扩展对该玩家的看法，指令本身也会如此说明。

CultivationTheme

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

在丝毫不触碰行为的前提下，重写模组面向玩家的全套用词，如此一来，一个讲魂师与学院而非修士与宗门的设定，读起来便是它自己的一款游戏，而不是一层换皮。Cultivation 展示给玩家的每一个字符串 —— 聊天、指令、状态栏、菜单、物品名、提示框 —— 都会先经由你的 translate 路由，而你返回什么就原样采用什么。

CultivationTheme 有两个方法：

@Nonnull String getId();                          // 带命名空间（"SoulRings:soul_land"）；仅用于日志与 /cultivation admin
@Nullable Message translate(@Nonnull String key);   // 完整的键，始终带有 `server.` 前缀

对任何你不打算改写的键，从 translate 返回 null，即采用 Cultivation 自己的用词，因此一套主题想覆盖多少便覆盖多少。

为何是钩子而非语言文件

因为引擎不允许你那样做。所有资源包的语言文件会被合并进单一目录，而这次合并是先写者胜 —— 来自较晚资源包的重复键会被丢弃，并记录为 'x' has multiple definitions。Cultivation 自己的资源包先于任何依赖它的扩展加载，因此扩展若在自己的 server.lang 中提供 server.cultivation.playerMsg.breakthrough，会被悄然忽略；而即便侥幸赢下这场竞争，也不过是赢在那一次启动而已。

所以主题把自己的字符串放在它自己的键之下 —— 那与任何东西都不冲突 —— 再把 Cultivation 的键映射过去。

translate 是在正构建该消息的那个线程上调用的，且每渲染一行往往要调用数次，因此它必须快速、线程安全且无副作用 —— 在一个不可变 map 中查表，正是它本该有的形状。Cultivation 所填入的任何 .param(...) 占位符，都会施加到你所返回的内容上，因此替换文本必须保留同样的占位符名；漏掉一个，那一处便会渲染为空。同一时刻只能安装一套主题；最后注册者胜出，并会记录一条同时点名双方的警告。

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)

向 Cultivation 的管理菜单添加一组可调数值，它会作为一个独立的分节按钮，与 Cultivation 自己的 80 个（v0.11.2 比 0.11.1 多十个，v0.11.1 比 0.11.0 多八个）并列出现在 /cultivation admin 的配置页上 —— 同样的行、同样的编辑方式、同样的一次保存。这些设置同时也出现在寻常 Cultivation 设置菜单底部的一块模组设置区域中，仅管理员可见。完整示例、五种行工厂与提示框规则，见注册表。

一份配置文件对应一个分节，这是 Cultivation 自己所采用、也是读起来最顺的形状。

一行共有五种类型（AdminConfigField.Kind）：NUMBER（小数输入框，默认）、INT、BOOLEAN（真正的复选框）、CHOICE（基于 AdminConfigChoice 的下拉框）与 TEXT。0.6.1 之前只有数字，所以总开关只得伪装成一个 0／1 字段；如今已不必如此。任何列表形状的东西，请留在配置文件里。

两个宿主页面都以 cultivation.admin 为门槛，且该门槛在保存时是在服务端重新核验的，而非信任菜单的说法，因此一个分节尽可安全地暴露真正的平衡数值。

以同一分节键重复注册会替换先前那一个，因此在你的插件重载时这是安全的。

在任何阶梯下读取玩家

三个门面方法会在当前生效的任一体系下报告修士的境况，因此你的代码无需知道是否安装了 provider：

CultivationAPI.getRealm(accessor, ref) 返回的是有效境界，即在安装了 provider 时其所给出的等价境界 —— 模组中每一道门槛检验的正是它。在 provider 之下，CultivationAPI.getStage(accessor, ref) 始终为 null，因为替换阶梯并没有子阶段 —— 它只有自己的 getSubRankLabel。凡涉及数值，请优先使用 getGlobalLevel。

排行与 /cultivation top 按那个压平后的等级排序，因此一套替换进阶体系能正确地与自身相互排名。对内置阶梯而言，其顺序恰是「先境界后阶段」一贯产出的结果。