Cultivation 接口

Cultivation 为其他 Hytale 模组提供了一套公开的集成面：plugin.siren.API.CultivationAPI，外加同一包下的五十三个 *Events 类。它是本模组有意保持稳定的形态 —— 请优先使用它，而非直接伸手去碰 CultivationManager、Cultivation 或那些 ECS 组件，因为后者随时可能在版本之间变动。

你可以用它做四件事：

• 读取玩家的修炼状态 —— 境界、阶段、全局等级、存蓄灵气、种族、打坐状态、天赋点、已解锁节点，以及从宗门到寿元的每一个子系统的状态。见接口参考。
• 注册与内置内容行为完全一致的新内容 —— 一个种族、一门功法、一项灵气吸收物品修正、一个称号、一面宗门旗帜、一套配色、一个菜单页、一篇典籍条目、一项更新或兼容性检查。register* 方法共三十个。见注册表。
• 监听（并重新调参，或否决）遍及模组各子系统的 391 个事件。见事件。
• 替换模组的一整个层次 —— 进阶阶梯本身、它的全套用词，或两者兼有 —— 而其余每个子系统仍照常在其之上运行。此为 0.5.0 新增；见编写扩展。

本页所记载的是 Cultivation 0.11.2 时的接口。凡是在 0.5.0 之后才出现的方法或事件，描述它的那一页都会注明版本。

将 Cultivation 引入你的项目

Cultivation 0.11.2 面向 Hytale Update 7 构建，针对 Server API 0.7.2 编译，其清单声明 ServerVersion: >=0.7.2 <0.8.0 —— v0.11.1 0.11.0 针对 0.7.0-pre.5.1 构建，声明的是 >=0.7.0-pre.0 <0.8.0；0.11.1 把这个下限提到了 0.7.2，0.11.2 沿用不变。它以 Java 25 为目标，因此针对它编译的扩展也需如此。Cultivation 不在公共 Maven 仓库中：请先把发行的 jar 安装进你的本地仓库，再以 provided 作用域依赖它，且绝不要把它打包（shade）进你自己的 jar。服务器加载的是真正的 Cultivation jar，若类路径上有两份 plugin.siren.Cultivation，两份会各自得到一个静态插件实例 —— 于是每一次注册调用都会落进无人读取的那一份，悄无声息。

mvn install:install-file -Dfile=Cultivation-0.11.2.jar -DgroupId=plugin.siren -DartifactId=Cultivation -Dversion=0.11.2 -Dpackaging=jar

Maven pom.xml：

<properties>
    <maven.compiler.source>25</maven.compiler.source>
    <maven.compiler.target>25</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<repositories>
    <repository>
        <id>hytale-release</id>
        <url>https://maven.hytale.com/release</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.hypixel.hytale</groupId>
        <artifactId>Server</artifactId>
        <version>0.7.2</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>plugin.siren</groupId>
        <artifactId>Cultivation</artifactId>
        <version>0.11.2</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

然后在你的 Hytale manifest.json 中声明它。Cultivation 自己的清单将自身发布为 group Siren、name Cultivation，因此依赖 id 是 Siren:Cultivation。请声明第一个包含你所调用之物的版本作下限：针对本 jar 构建的扩展用 >=0.11.2，因为这些页面上凡标有 v0.11.2 的东西（PreDeathPenaltyEvent、DeathPenaltyAppliedEvent、SectVeinAscendedEvent 与 CultivationAPI.isDuelLethal）在它之前并不存在，凡标有 v0.11.1 的东西（其中就有 DaoDomainEvents 与 SectArrayEvents）在 0.11.1 之前同样不存在。随 0.11.0 发布的官方扩展仍声明 >=0.11.0。你自己的 ServerVersion 请取与 Cultivation 相同的形态：

"ServerVersion": ">=0.7.2 <0.8.0",
"Dependencies": {
  "Siren:Cultivation": ">=0.11.2"
}

清单中的版本范围接受完整的 semver 区间，而不只是一个下限 —— ">=0.11.2 <0.12.0" 会让引擎在你的一行代码运行之前，就拒绝让你的扩展对着该区间之外的任何 Cultivation 加载。若你更愿意仅在 Cultivation 恰好已安装时才集成，请改把同样的条目放进 "OptionalDependencies"，并让每一处对 plugin.siren 类的引用都置于守卫之后，使这些类在缺少它时永不加载。关于在两个 jar 都已发布之后、用来修正某个搭配的公开兼容性名单，见模组兼容。

入口点

一切都是静态的。CultivationAPI 有一个私有构造函数，永不被实例化 —— 你直接在类上调用它：

import plugin.siren.API.CultivationAPI;
import plugin.siren.ECS.Realms.CultivationRealm;

CultivationRealm realm = CultivationAPI.getRealm(accessor, ref);
float qi = CultivationAPI.getQi(accessor, ref);

这些读取方法一律接受一个 ComponentAccessor<EntityStore> 与一个 Ref<EntityStore> —— 正是每个 Hytale ECS 系统手头已有的那一对。凡是读取组件的方法，在玩家尚未拥有该组件时都返回 null（或 0，或 Human），因此一个刚进服的新玩家绝不会引发异常。

监听器与注册表的调用，在你自己插件的 setup() 中，相对于 Cultivation 自身的 setup() 无论何种加载顺序都是安全的。注册表是普通的静态 map，监听器列表则是 CopyOnWriteArrayList；在玩家真正与模组交互之前，二者都不会被读取，而那已远在每个插件加载完毕之后。

你的第一个监听器

其模式是：以 CultivationEvents.onPreX(...) 在事情发生之前更改或否决它，以 CultivationEvents.onX(...) 在其落定之后收到告知。二者都接受一个该事件类型的 java.util.function.Consumer，因此一个 lambda 就够了：

import com.hypixel.hytale.server.core.universe.PlayerRef;
import plugin.siren.API.CultivationEvents;
import plugin.siren.ECS.Realms.CultivationRealm;

public final class MyCultivationHooks {

    public static void register(){
        // 让踏入金丹期的那一跃，所耗存蓄灵气翻倍。
        CultivationEvents.onPreBreakthrough(event -> {
            if(event.toRealm() == CultivationRealm.GOLDEN_CORE_FORMATION){
                event.setQiCost(event.qiCost() * 2.0F);
            }
        });

        // 直接回绝最后一个境界。
        CultivationEvents.onPreBreakthrough(event -> {
            if(event.toRealm() == CultivationRealm.VOID_REFINEMENT){
                event.setCancelled(true);
            }
        });

        // 事情真正发生之后再作反应 —— 此时组件已显示新的境界。
        CultivationEvents.onBreakthrough(event -> {
            if(event.player() != null){
                recordAscension(event.player(), event.newRealm());
            }
        });
    }

    private static void recordAscension(PlayerRef player, CultivationRealm realm){
        // 你自己的记账逻辑
    }
}

在你插件的 setup() 中调用 MyCultivationHooks.register()。这里刻意没有反注册 —— 监听器的生命周期就是服务器的生命周期，正合插件「加载一次、常驻不去」的方式。

公开仓库里的完整示例 examples/ExampleAddon，针对真实的 0.11.1 jar 与 0.7.2 服务器编译通过。它的 CultivationHooks.java 里有 0.11.1 的各个钩子：registerDaoDomains() 在战事窗口期间缩短高阶位道域的持续时间，并记录它的展开、崩塌与交锋；registerSectArrays() 把一次宗门大阵升起的贡献点代价减半，并记录它的升起与结束；registerVetoes() 则是前置事件否决的所在，其中包括拒绝 /cultivation meditate abort。

各页导览

这些钩子所依托的各系统，其面向玩家的文档位于本站主体：境界与阶段、聚灵采气、大道、功法、宗门、宗门攻伐、阵法、洞府、斗法与灵兽。事件允许你重新调整的每一个数值，在配置页都有一份面向服主的对应项，其中大多数也在指令页有所映照。