RitsuLib

外观

时间线与解锁 ​

本文是时间线注册与解锁语义的参考文档。

RitsuLib 将时间线注册和解锁规则拆成两个系统，配合使用。本文说明：

  • Story / Epoch 的注册方式
  • 模板类型的职责
  • 解锁规则的判定机制
  • 原版进度逻辑对 Mod 角色的局限性与 RitsuLib 的兼容桥接

两个注册器 ​

注册器职责
ModTimelineRegistry注册 StoryModel 和 EpochModel
ModUnlockRegistry定义内容或纪元的解锁条件

在链式构建器里，对应：

  • .Story<TStory>()、.Epoch<TEpoch>()
  • .RequireEpoch<TModel, TEpoch>()、.UnlockEpochAfter...()

核心区别：

  • 时间线注册回答"这个东西是否存在"
  • 解锁注册回答"它什么时候可用"

Story 注册 ​

故事类型仍用 ModStoryTemplate，只实现 StoryKey。栏内 Epoch 顺序不要在故事类里写死；按注册顺序把每个 Epoch 绑到该故事：

csharp
public class MyStory : ModStoryTemplate
{
    protected override string StoryKey => "my-story";
}

// 流式: .StoryEpoch<MyStory, MyCharacterEpoch>() … .Story<MyStory>()

ModStoryTemplate 的职责：

  • 通过 StoryKey 自动生成规范化的故事标识
  • 通过 ModStoryEpochBindings（RegisterStoryEpoch 写入）组装 Epochs

Epoch 注册 ​

可以直接写原生 EpochModel 子类，也可以使用 RitsuLib 提供的模板类型：

模板说明
CharacterUnlockEpochTemplate<TCharacter>解锁角色本身的纪元
CardUnlockEpochTemplate解锁额外卡牌的纪元
RelicUnlockEpochTemplate解锁额外遗物的纪元
PotionUnlockEpochTemplate解锁额外药水的纪元

Expansion Epochs ​

所有解锁纪元模板都支持：

csharp
protected virtual IEnumerable<Type> ExpansionEpochTypes => [];

当前纪元完成时会自动把这些纪元作为时间线扩展加入，用于组织解锁链：

  1. 先解锁角色
  2. 再展开卡牌解锁
  3. 再展开遗物解锁

为内容设置 Epoch 门槛 ​

当模型已注册，但应在某个纪元解锁后才出现时，使用 RequireEpoch<TModel, TEpoch>()。

常见用途：

  • 后期卡牌在进度达成前不进入牌池
  • 遗物只在特定故事分支后开放
  • 共享 Ancient / 事件需要时间线进度门槛

局后 Epoch 规则 ​

ModUnlockRegistry 提供的常用便捷 API：

方法说明
UnlockEpochAfterRunAs<TCharacter, TEpoch>()使用指定角色完成一局后解锁
UnlockEpochAfterWinAs<TCharacter, TEpoch>()使用指定角色胜利后解锁
UnlockEpochAfterAscensionWin<TCharacter, TEpoch>(level)指定进阶等级胜利后解锁
UnlockEpochAfterRunCount<TEpoch>(requiredRuns, requireVictory)累计跑局次数后解锁

累计进度型规则 ​

方法说明
UnlockEpochAfterEliteVictories<TCharacter, TEpoch>(count)精英击杀数
UnlockEpochAfterBossVictories<TCharacter, TEpoch>(count)Boss 击杀数
UnlockEpochAfterAscensionOneWin<TCharacter, TEpoch>()进阶 1 胜利
RevealAscensionAfterEpoch<TCharacter, TEpoch>()纪元后显示进阶
UnlockCharacterAfterRunAs<TCharacter, TEpoch>()使用角色后解锁角色

兼容补丁 ​

原版的若干进度检查是按原版角色设计的，不会自然支持 Mod 角色。RitsuLib 通过以下桥接补丁，让注册的解锁规则在这些检查点上生效：

  • 精英击杀计数的纪元判定桥接
  • Boss 击杀计数的纪元判定桥接
  • 进阶 1 的纪元判定桥接
  • 局后角色解锁纪元桥接
  • 进阶显示解锁判定桥接

构建器示例 ​

csharp
RitsuLibFramework.CreateContentPack("MyMod")
    .Character<MyCharacter>()
    .Card<MyCardPool, MyLateCard>()
    .Relic<MyRelicPool, MyLateRelic>()
    .Epoch<MyCharacterEpoch>()
    .Epoch<MyLateContentEpoch>()
    .Story<MyStory>()
    .RequireEpoch<MyLateCard, MyLateContentEpoch>()
    .RequireEpoch<MyLateRelic, MyLateContentEpoch>()
    .UnlockEpochAfterWinAs<MyCharacter, MyCharacterEpoch>()
    .UnlockEpochAfterAscensionWin<MyCharacter, MyLateContentEpoch>(10)
    .Apply();

常见错误 ​

  • 注册了纪元，却忘了注册包含这些纪元的故事
  • 在时间线冻结之后才注册故事/纪元
  • 给内容设置了 RequireEpoch，却没有任何规则能真正解锁该纪元
  • 对同一个纪元叠很多重叠解锁规则，却没有明确设计理由
  • 误以为原版累计进度逻辑会自动兼容 Mod 角色，而没有注册 RitsuLib 解锁规则