Manager API

「顿悟 Epiphany」提供了一组静态 Manager 类作为公共 API，供其他模组通过 Java 代码与系统交互。

TIP

所有 Manager 方法的玩家参数均为 ServerPlayer

INFO

KubeJS 脚本同样支持Manager API，详情请参见 KubeJS 兼容章节

`AptitudeManager`

管理玩家的阅历值和心得点。

查询方法

java

// 获取玩家当前阅历值
long getAptitude(ServerPlayer player)

// 获取玩家当前心得点
int getInsightPoints(ServerPlayer player)

// 获取玩家已消耗的心得点总数
int getTotalInsightPointsSpent(ServerPlayer player)

// 获取玩家下一个心得点的阅历阈值
long getRequiredForNextPoint(ServerPlayer player)

修改方法

java

// 设置阅历值（截断到当前上限）
// 触发 AptitudeChangedEvent
void setAptitude(ServerPlayer player, long value)

// 增加阅历值。超额部分自动转化为心得点
// 触发 AptitudeChangedEvent, AptitudeLevelUpEvent, InsightPointsChangedEvent
void addAptitude(ServerPlayer player, long amount)

// 按 aptitude_gain_multiplier（基础值 + 所有 modifier）增加阅历值
// 缩放结果向下取整；结果小于等于 0 时不增加
void addAptitudeWithMultiplier(ServerPlayer player, long amount)

// 设置心得点数（截断到 >= 0）
// 触发 InsightPointsChangedEvent
void setInsightPoints(ServerPlayer player, int value)

// 增加心得点（结果截断到 >= 0）
// 触发 InsightPointsChangedEvent
void addInsightPoints(ServerPlayer player, int amount)

// 将阅历补充到下一个心得点阈值
// 复用 addAptitude，因此会触发常规阅历与升级事件
// 返回实际增加的阅历值；已达到或超过阈值时返回 0
long fillAptitude(ServerPlayer player)

`EpiphanyDataUtils`

提供可供其他模组、UI 和命令实现复用的跨系统玩家数据操作。

事件行为

以下重置方法不会触发阅历、心得点或选择事件，与对应的 /epiphany reset 命令保持一致。

java

// 移除所有已应用的模块、心得和已激活顿悟奖励
void removeAllRewards(ServerPlayer player)

// 计算已选模块和已点亮心得应退还的心得点
// 仅查询，不修改玩家数据
int refundInsightCosts(ServerPlayer player, PlayerEpiphanyData data)

// 移除全部奖励和顿悟数据，再恢复初始状态为 SELECTABLE 的条目
// 等价于 /epiphany reset all
void resetAll(ServerPlayer player)

// 清除选择和奖励，但保留阅历并退还已选模块和已点亮心得的消耗
// 随后恢复初始状态为 SELECTABLE 的条目；等价于 /epiphany reset select
void resetSelections(ServerPlayer player)

`ModuleManager`

管理玩家的模块数据。

查询方法

java

// 模块是否已解锁（可以被选择）
boolean isUnlocked(ServerPlayer player, ResourceLocation moduleId)

// 模块是否已被选择
boolean isSelected(ServerPlayer player, ResourceLocation moduleId)

// 模块是否已完成
boolean isCompleted(ServerPlayer player, ResourceLocation moduleId)

// 玩家当前已选择的模块数量
int getSelectedModuleCount(ServerPlayer player)

// 配置中允许同时选择的模块数量上限
int getMaxSelectedModules()

修改方法

java

// 设置模块解锁状态
// 触发 ModuleUnlockEvent (Pre) 和 ModuleUnlockedEvent (Post)
void setUnlocked(ServerPlayer player, ResourceLocation moduleId, boolean unlocked)

// 选择模块（消耗心得点，检查条件和上限）
// 触发 ModuleSelectEvent (Pre) 和 ModuleSelectedEvent (Post)
// 应用 on_select_reward
void select(ServerPlayer player, ResourceLocation moduleId)

// 完成模块（检查所有心得是否已解锁，授予顿悟槽）
// 触发 ModuleCompleteEvent (Pre) 和 ModuleCompletedEvent (Post)
// 应用 on_complete_reward
void complete(ServerPlayer player, ResourceLocation moduleId)

// 强制选择（忽略消耗和条件）
// 触发 ModuleSelectedEvent (Post)
void forceSelect(ServerPlayer player, ResourceLocation moduleId)

// 强制完成（忽略心得检查，授予顿悟槽）
// 触发 ModuleCompletedEvent (Post)
void forceComplete(ServerPlayer player, ResourceLocation moduleId)

// 重置模块（退还心得点，移除奖励）
void resetModule(ServerPlayer player, ResourceLocation moduleId)

// 自动解锁满足条件的 locked 模块
// skipEventDriven：是否跳过轮询
// silent：是否触发 NotificationListener 中的通知消息
void checkAutoUnlock(ServerPlayer player, boolean skipEventDriven, boolean silent)

// 清理注册表中已不存在的 module
void cleanupOrphanedData(ServerPlayer player)

`InsightManager`

管理玩家的心得状态。

查询方法

java

// 心得是否已被选择
boolean isSelected(ServerPlayer player, ResourceLocation insightId)

// 心得所处的模块是否被选择
boolean isModuleSelected(ServerPlayer player, ResourceLocation insightId)

修改方法

java

// 选择心得（消耗心得点，检查前置条件）
// 触发 InsightSelectEvent (Pre) 和 InsightSelectedEvent (Post)
void select(ServerPlayer player, ResourceLocation insightId, ResourceLocation moduleId)

// 强制选择心得（忽略消耗和前置条件）
void forceSelect(ServerPlayer player, ResourceLocation insightId, ResourceLocation moduleId)

// 重置心得（退还心得点，移除奖励）
void resetInsight(ServerPlayer player, ResourceLocation insightId)

`EpiphanyManager`

管理玩家的顿悟状态。

查询方法

java

// 顿悟是否已解锁（可以被选择）
boolean isUnlocked(ServerPlayer player, ResourceLocation epiphanyId)

// 顿悟是否已被选择
boolean isSelected(ServerPlayer player, ResourceLocation epiphanyId)

// 玩家已解锁的顿悟槽数量
int getEpiphanySlots(ServerPlayer player)

// 当前已占用的顿悟槽数量
int getUsedEpiphanySlots(ServerPlayer player)

// 配置中允许选择的顿悟数量上限
int getMaxEpiphanySlots()

修改方法

java

// 设置顿悟解锁状态
void setUnlocked(ServerPlayer player, ResourceLocation epiphanyId, boolean unlocked)

// 选择顿悟（检查槽位和条件）
// 触发 EpiphanySelectEvent (Pre) 和 EpiphanySelectedEvent (Post)
void select(ServerPlayer player, ResourceLocation epiphanyId)

// 强制选择（忽略槽位和条件）
void forceSelect(ServerPlayer player, ResourceLocation epiphanyId)

// 重置顿悟
void resetEpiphany(ServerPlayer player, ResourceLocation epiphanyId)

// 清理注册表中已不存在的 Epiphany
void cleanupOrphanedData(ServerPlayer player)

// 自动解锁满足条件的 locked 顿悟
// skipEventDriven：是否跳过轮询
// silent：是否触发 NotificationListener 中的通知消息
void checkAutoUnlock(ServerPlayer player, boolean skipEventDriven, boolean silent)

`AptitudeSourceManager`

解析数据包定义的阅历来源并发放奖励。

java

// 解析一组行为与目标，但不修改玩家数据
// 返回匹配的奖励及相关解析信息
AptitudeSourceResolver.Resolution resolve(
	ServerPlayer sp, ResourceLocation behaviorId,
	ResourceLocation targetId, @Nullable Registry<?> registry)

// 发放阅历
// behaviorId: 行为 ID（如 mymod:foo）
// targetId: 目标 ID（如被击杀的实体类型）
// registry: targetId 所属的注册表，用于查找 tag。可为 null
boolean grant(
	ServerPlayer sp, ResourceLocation behaviorId,
	ResourceLocation targetId, @Nullable Registry<?> registry)

使用示例：

java

@SubscribeEvent
static void onCustomMobKill(LivingDeathEvent event) {
    if (!(event.getSource().getEntity() instanceof ServerPlayer sp)) return;
    ResourceLocation targetId = BuiltInRegistries.ENTITY_TYPE.getKey(event.getEntity().getType());
    AptitudeSourceManager.grant(
        sp,
        ResourceLocation.fromNamespaceAndPath("mymod", "custom_kill"),
        targetId,
        BuiltInRegistries.ENTITY_TYPE
    );
}

`AptitudeFormula`

阅历计算公式类。目前只实现了线性运算，计划加入更多公式支持。公式：

\text{required} = \text{Config.baseAptitudeCap} + (\text{totalSpent} + \text{insightPoints}) \times \text{Config.aptitudeCapGrowth}

java

// 计算获得下一个心得点所需的阅历值
// totalSpent: 已消耗心得点总数
// insightPoints: 当前可用心得点数
// 返回: 所需阅历值
long calcRequiredAptitude(long totalSpent, int insightPoints)

处理模式

所有 Manager 方法遵循统一的流程：

1. player.getData(AttachmentType) → 获取当前数据
2. 创建新的不可变数据记录（with* 方法）
3. player.setData(AttachmentType, newData) → 持久化 + 自动同步到客户端
4. NeoForge.EVENT_BUS.post(Event) → 触发事件

INFO

PlayerEpiphanyData 是不可变 record，所有修改通过 with*() 方法返回新实例。

方法总表

Manager	方法	描述	返回
`AptitudeManager`	`getAptitude`	当前阅历	`long`
`AptitudeManager`	`getInsightPoints`	可用心得点	`int`
`AptitudeManager`	`getTotalInsightPointsSpent`	累计已花费心得点	`int`
`AptitudeManager`	`getRequiredForNextPoint`	下一心得点的阅历阈值	`long`
`AptitudeManager`	`setAptitude`	设置阅历	`void`
`AptitudeManager`	`addAptitude`	增加阅历,溢出部分自动转心得点	`void`
`AptitudeManager`	`addAptitudeWithMultiplier`	按玩家阅历获取倍率增加阅历	`void`
`AptitudeManager`	`setInsightPoints`	直接覆盖可用心得点(不改 totalSpent)	`void`
`AptitudeManager`	`addInsightPoints`	增加或扣除心得点，结果不低于 0	`void`
`AptitudeManager`	`fillAptitude`	补充阅历至下一心得点阈值	`long`
`EpiphanyDataUtils`	`removeAllRewards`	移除全部已应用奖励	`void`
`EpiphanyDataUtils`	`refundInsightCosts`	计算选择消耗的心得点退款	`int`
`EpiphanyDataUtils`	`resetAll`	全量重置玩家顿悟数据	`void`
`EpiphanyDataUtils`	`resetSelections`	保留阅历并重置选择	`void`
`ModuleManager`	`isUnlocked`	模块是否已解锁	`boolean`
`ModuleManager`	`isSelected`	模块是否已选	`boolean`
`ModuleManager`	`isCompleted`	模块是否已完成	`boolean`
`ModuleManager`	`getSelectedModuleCount`	当前已选模块数量	`int`
`ModuleManager`	`getMaxSelectedModules`	同时选择模块的配置上限	`int`
`ModuleManager`	`setUnlocked`	设置解锁状态	`void`
`ModuleManager`	`select`	选择模块	`void`
`ModuleManager`	`forceSelect`	强制选择	`void`
`ModuleManager`	`complete`	完成模块	`void`
`ModuleManager`	`forceComplete`	强制完成	`void`
`ModuleManager`	`resetModule`	重置模块	`void`
`ModuleManager`	`checkAutoUnlock`	扫描自动解锁 LOCKED 且 condition 满足的模块	`void`
`ModuleManager`	`cleanupOrphanedData`	清理注册表中已不存在的 module	`void`
`InsightManager`	`isSelected`	心得是否已点亮	`boolean`
`InsightManager`	`isModuleSelected`	心得所属模块是否已选	`boolean`
`InsightManager`	`select`	选择心得	`void`
`InsightManager`	`forceSelect`	强制选择	`void`
`InsightManager`	`resetInsight`	重置心得	`void`
`EpiphanyManager`	`isUnlocked`	顿悟是否已解锁	`boolean`
`EpiphanyManager`	`isSelected`	顿悟是否已激活	`boolean`
`EpiphanyManager`	`getEpiphanySlots`	已解锁顿悟槽数量	`int`
`EpiphanyManager`	`getUsedEpiphanySlots`	已占用顿悟槽数量	`int`
`EpiphanyManager`	`getMaxEpiphanySlots`	可选择顿悟的配置上限	`int`
`EpiphanyManager`	`setUnlocked`	设置解锁状态	`void`
`EpiphanyManager`	`select`	激活顿悟	`void`
`EpiphanyManager`	`forceSelect`	强制激活	`void`
`EpiphanyManager`	`resetEpiphany`	重置顿悟	`void`
`EpiphanyManager`	`checkAutoUnlock`	扫描自动解锁 LOCKED 且 condition 满足的顿悟	`void`
`EpiphanyManager`	`cleanupOrphanedData`	清理注册表中已不存在的 epiphany	`void`
`AptitudeSourceManager`	`grant`	发放阅历	`boolean`
`AptitudeSourceManager`	`resolve`	纯查询某 behavior+target 的奖励	`Resolution`
`AptitudeFormula`	`calcRequiredAptitude`	计算获得下一心得点所需阅历	`long`

Manager API ​

AptitudeManager ​

查询方法 ​

修改方法 ​

EpiphanyDataUtils ​

ModuleManager ​

查询方法 ​

修改方法 ​

InsightManager ​

查询方法 ​

修改方法 ​

EpiphanyManager ​

查询方法 ​

修改方法 ​

AptitudeSourceManager ​

AptitudeFormula ​

处理模式 ​

方法总表 ​

Manager API

`AptitudeManager`

查询方法

修改方法

`EpiphanyDataUtils`

`ModuleManager`

查询方法

修改方法

`InsightManager`

查询方法

修改方法

`EpiphanyManager`

查询方法

修改方法

`AptitudeSourceManager`

`AptitudeFormula`

处理模式

方法总表