LoadStage 与 ModLoadOrder
LoadStage 是模组加载阶段枚举；ModLoadOrder 是模组加载顺序声明（不可变 record），模组经 Mod.loadOrder() 返回，声明加载阶段与软依赖。宿主按阶段升序激活模组：CORE → PRE_INIT → INIT → POST_INIT，未声明阶段的模组默认落在 INIT。
方法速览
| 方法 | 用途 |
|---|---|
LoadStage.valueOf(String) / LoadStage.values() | 枚举生成方法 |
ModLoadOrder(LoadStage, List<String>, List<String>) | 规范构造器 |
of(LoadStage) | 仅声明阶段，无软依赖 |
init() | 默认阶段（INIT），无软依赖 |
stage() | 加载阶段 |
loadAfter() | 软依赖：排在目标之后 |
loadBefore() | 软反向依赖：排在目标之前 |
equals(Object) / hashCode() / toString() | record 生成的值语义 |
完整签名
public enum LoadStage {
CORE,
PRE_INIT,
INIT,
POST_INIT
}public record ModLoadOrder(
LoadStage stage,
List<String> loadAfter,
List<String> loadBefore
) {
public static ModLoadOrder of(LoadStage stage);
public static ModLoadOrder init();
LoadStage stage();
List<String> loadAfter();
List<String> loadBefore();
boolean equals(Object obj);
int hashCode();
String toString();
}常量语义
| 常量 | 含义 |
|---|---|
CORE | 底层框架、API、运行时库；必须被其它模组依赖才允许声明 |
PRE_INIT | 需要在普通初始化之前准备的模组 |
INIT | 普通模组（未声明阶段时的默认值） |
POST_INIT | 需要等大多数模组加载完后运行的模组 |
stage仅决定激活顺序（同一激活流程内先CORE后INIT），不改变生命周期方法——所有模组都在各自排序位置调用同一个onInit(ModContext)。- 渲染顺序联动：激活顺序决定
activeGameplayMods的插入顺序，因此游玩滤镜 / 背景 / 特效的叠加顺序也遵循阶段（CORE模组最先叠加，位于最底层）。 - 反滥用规则：声明
CORE但没有任何已注册模组依赖它（依赖来源含dependsOn与loadAfter，按全体注册模组计算，不区分是否启用）时，宿主自动降级为INIT并记录告警。 - 阶段修正：若
dependsOn/loadAfter指向更高阶段的候选，本模组会被提升到该阶段；若loadBefore指向更低阶段的候选，本模组会被降级到该阶段（迭代至稳定）。这类修正会记录告警。
ModLoadOrder(LoadStage stage, List loadAfter, List loadBefore)
签名：
public ModLoadOrder(LoadStage stage, List<String> loadAfter, List<String> loadBefore);行为：规范构造器。紧凑构造把 null 列表归一为空列表，并用 List.copyOf 复制成不可变列表（元素不可为 null，否则 NullPointerException）。stage 为 null 时由宿主视为 LoadStage.INIT（record 本身保留 null）。
示例：
ModLoadOrder order = new ModLoadOrder(LoadStage.POST_INIT, List.of("core_lib"), List.of());of(LoadStage stage)
签名：
public static ModLoadOrder of(LoadStage stage);行为：兼容性工厂：仅声明阶段，无软依赖。
示例：
return ModLoadOrder.of(LoadStage.PRE_INIT);init()
签名：
public static ModLoadOrder init();行为：兼容性工厂：默认阶段 INIT，无软依赖。等价于 of(LoadStage.INIT)。
示例：
return ModLoadOrder.init();stage()
签名：
LoadStage stage();行为：返回声明的加载阶段；可能为 null（宿主按 INIT 处理）。
示例：
LoadStage stage = mod.loadOrder().stage();loadAfter()
签名：
List<String> loadAfter();行为：返回软依赖列表：若目标模组参与本次加载，本模组排在它之后；目标不存在（未注册 / 未启用）时该约束自动失效，不影响加载。与 ModInfo.dependsOn()（硬依赖，缺失即失败）不同。
示例：
List<String> after = mod.loadOrder().loadAfter();loadBefore()
签名：
List<String> loadBefore();行为：返回软反向依赖列表：若目标模组参与本次加载，本模组排在它之前；目标不存在时自动失效。软边成环时宿主丢弃该边并记录说明，不阻断加载。
示例：
List<String> before = mod.loadOrder().loadBefore();equals(Object obj)
签名：
boolean equals(Object obj);行为：record 生成：阶段与两个列表逐一比较。
示例：
boolean same = orderA.equals(orderB);hashCode()
签名：
int hashCode();行为：record 生成，与 equals 一致。
示例：
int h = order.hashCode();toString()
签名：
String toString();行为：record 生成，形如 ModLoadOrder[stage=..., loadAfter=..., loadBefore=...]。
示例：
ctx.getLogger().info(String.valueOf(order));线程：源码未声明额外线程约束。
稳定性：2.0 起冻结：2.x 内只增不破（禁止删签名 / 改签名 / 改语义）；破坏性变更只在 major 版本发生且须提供迁移指南与至少一个大版本的弃用期。3.x 内继续只增不破。