fix(Unlocks): support chained mod character prerequisites

Author: BAKAOLC

Scaffolding/Characters/ModCharacterTemplate.cs

@@ -450,20 +450,19 @@ protected virtual IEnumerable<StartingDeckEntry> StartingDeckEntries
 
         /// <summary>
         ///     Optional prerequisite character type for vanilla <see cref="CharacterModel.GetUnlockText" /> (the
-        ///     <c>{Prerequisite}</c> placeholder). When set to <see cref="MegaCrit.Sts2.Core.Models.Characters.Ironclad" />,
-        ///     root <see cref="Timeline.Scaffolding.CharacterUnlockEpochTemplate{TCharacter}" /> slots are obtained with
-        ///     Neow's initial expansion so they match the Silent unlock path. Other unlock rules should still be aligned
-        ///     with <see cref="Unlocks.ModUnlockRegistry" />.
+        ///     <c>{Prerequisite}</c> placeholder). Root
+        ///     <see cref="Timeline.Scaffolding.CharacterUnlockEpochTemplate{TCharacter}" /> slots whose character declares
+        ///     this property are obtained with Neow's initial expansion for
+        ///     <see cref="MegaCrit.Sts2.Core.Models.Characters.Ironclad" /> prerequisites, or after a completed run as any
+        ///     other prerequisite character.
         ///     用于原版 <see cref="CharacterModel.GetUnlockText" /> 的可选前置角色类型（
-        ///     <c>{Prerequisite}</c> 占位符）。当设置为
-        ///     <see cref="MegaCrit.Sts2.Core.Models.Characters.Ironclad" /> 时，根
-        ///     <see cref="Timeline.Scaffolding.CharacterUnlockEpochTemplate{TCharacter}" /> 槽位会随 Neow 初始扩展获得，
-        ///     以匹配 Silent 解锁路径。其他解锁规则仍应与 <see cref="Unlocks.ModUnlockRegistry" /> 对齐。
+        ///     <c>{Prerequisite}</c> 占位符）。角色声明此属性时，其根
+        ///     <see cref="Timeline.Scaffolding.CharacterUnlockEpochTemplate{TCharacter}" /> 槽位会在前置为
+        ///     <see cref="MegaCrit.Sts2.Core.Models.Characters.Ironclad" /> 时随 Neow 初始扩展获得；其他前置角色则在完成该角色 run
+        ///     后获得。
         /// </summary>
         protected virtual Type? UnlocksAfterRunAsType => null;
 
-        Type? IModCharacterUnlockPrerequisite.UnlocksAfterRunAsType => UnlocksAfterRunAsType;
-
         /// <summary>
         ///     Placeholder vanilla character id used when merging partial <see cref="CharacterAssetProfile" /> data
         ///     (see <see cref="CharacterAssetProfiles.Resolve" />).
@@ -610,6 +609,8 @@ protected virtual IEnumerable<StartingDeckEntry> StartingDeckEntries
             return SetupCustomMerchantAnimationStateMachine(merchantRoot, character);
         }
 
+        Type? IModCharacterUnlockPrerequisite.UnlocksAfterRunAsType => UnlocksAfterRunAsType;
+
         /// <inheritdoc />
         public virtual bool HideFromVanillaCharacterSelect => false;
 

Timeline/ModTimelineNeowCoExpansion.cs

@@ -62,6 +62,37 @@ internal static bool IsNeowPrimaryTimelineExpansionSlots(IReadOnlyList<EpochSlot
                    && ids.Contains(EpochModel.GetId<Silent1Epoch>());
         }
 
+        internal static IReadOnlyList<string> GetModCharacterRootEpochIdsUnlockedAfterRunAs(
+            ModelId prerequisiteCharacterId)
+        {
+            var result = new List<string>();
+            var ironcladId = ModelDb.GetId<Ironclad>();
+
+            foreach (var id in EpochModel.AllEpochIds)
+            {
+                EpochModel model;
+                try
+                {
+                    model = EpochModel.Get(id);
+                }
+                catch
+                {
+                    continue;
+                }
+
+                if (!TryGetCharacterRootUnlockPrerequisite(model, out var registeredPrerequisiteId))
+                    continue;
+                if (registeredPrerequisiteId == ironcladId)
+                    continue;
+                if (registeredPrerequisiteId != prerequisiteCharacterId)
+                    continue;
+
+                result.Add(model.Id);
+            }
+
+            return result;
+        }
+
         internal static void MergeModEpochTemplateSlotsInto(List<EpochSlotData> slotsToAdd, ProgressState? progress)
         {
             PromoteNeowCharacterRootUnlocks(progress);
@@ -233,6 +264,14 @@ private static bool ShouldShowUnobtainedModSlot(string id, ProgressState? progre
 
         private static bool ShouldObtainWithNeow(EpochModel model)
         {
+            return TryGetCharacterRootUnlockPrerequisite(model, out var prerequisiteId) &&
+                   prerequisiteId == ModelDb.GetId<Ironclad>();
+        }
+
+        private static bool TryGetCharacterRootUnlockPrerequisite(EpochModel model, out ModelId prerequisiteId)
+        {
+            prerequisiteId = null!;
+
             if (model is not ModEpochTemplate)
                 return false;
             if (!IsModTimelineRootSlot(model.Id))
@@ -250,16 +289,20 @@ private static bool ShouldObtainWithNeow(EpochModel model)
                 return false;
             }
 
-            if (character == null)
-                return false;
-            if (character is IModCharacterEpochTimelineRequirement { RequiresEpochAndTimeline: false })
-                return false;
+            switch (character)
+            {
+                case null:
+                case IModCharacterEpochTimelineRequirement { RequiresEpochAndTimeline: false }:
+                    return false;
+            }
+
             if (character is not IModCharacterUnlockPrerequisite { UnlocksAfterRunAsType: { } prerequisiteType })
                 return false;
 
             try
             {
-                return ModelDb.GetId(prerequisiteType) == ModelDb.GetId<Ironclad>();
+                prerequisiteId = ModelDb.GetId(prerequisiteType);
+                return true;
             }
             catch
             {

Unlocks/ModUnlockRegistry.cs

@@ -33,7 +33,7 @@ public sealed class ModUnlockRegistry
         private static readonly Dictionary<ModelId, CountedEpochUnlockRule> BossEpochRulesByCharacterId = [];
         private static readonly Dictionary<ModelId, string> AscensionOneEpochsByCharacterId = [];
         private static readonly Dictionary<ModelId, string> AscensionRevealEpochsByCharacterId = [];
-        private static readonly Dictionary<ModelId, string> PostRunCharacterUnlockEpochsByCharacterId = [];
+        private static readonly Dictionary<ModelId, List<string>> PostRunCharacterUnlockEpochsByCharacterId = [];
 
         private static readonly HashSet<string> ModIdsIgnoringEpochRequirements =
             new(StringComparer.OrdinalIgnoreCase);
@@ -478,7 +478,14 @@ public void RegisterPostRunCharacterUnlockEpoch(ModelId characterId, string epoc
 
             lock (SyncRoot)
             {
-                PostRunCharacterUnlockEpochsByCharacterId[characterId] = epochId;
+                if (!PostRunCharacterUnlockEpochsByCharacterId.TryGetValue(characterId, out var epochIds))
+                {
+                    epochIds = [];
+                    PostRunCharacterUnlockEpochsByCharacterId[characterId] = epochIds;
+                }
+
+                if (!epochIds.Contains(epochId, StringComparer.Ordinal))
+                    epochIds.Add(epochId);
             }
         }
 
@@ -626,7 +633,25 @@ internal static bool TryGetPostRunCharacterUnlockEpoch(ModelId characterId, out
         {
             lock (SyncRoot)
             {
-                return PostRunCharacterUnlockEpochsByCharacterId.TryGetValue(characterId, out epochId!);
+                if (PostRunCharacterUnlockEpochsByCharacterId.TryGetValue(characterId, out var epochIds) &&
+                    epochIds.Count > 0)
+                {
+                    epochId = epochIds[0];
+                    return true;
+                }
+            }
+
+            epochId = string.Empty;
+            return false;
+        }
+
+        internal static string[] GetPostRunCharacterUnlockEpochs(ModelId characterId)
+        {
+            lock (SyncRoot)
+            {
+                return PostRunCharacterUnlockEpochsByCharacterId.TryGetValue(characterId, out var epochIds)
+                    ? [.. epochIds]
+                    : [];
             }
         }
 

Unlocks/Patches/AscensionOneEpochCompatibilityPatch.cs

@@ -12,6 +12,7 @@
 using STS2RitsuLib.Content;
 using STS2RitsuLib.Patching.Models;
 using STS2RitsuLib.Scaffolding.Characters;
+using STS2RitsuLib.Timeline;
 using SerializableRun = MegaCrit.Sts2.Core.Saves.SerializableRun;
 
 namespace STS2RitsuLib.Unlocks.Patches
@@ -96,8 +97,8 @@ public static bool Prefix(SerializablePlayer serializablePlayer, SerializableRun
     }
 
     /// <summary>
-    ///     Replaces vanilla post-run character-unlock epoch checks for mod characters with registry-driven grants.
-    ///     将 mod 角色的原版跑局后角色解锁纪元检查替换为由注册表驱动的授予。
+    ///     Extends vanilla post-run character-unlock epoch checks with registered and template-derived mod grants.
+    ///     用已注册和模板推导出的 mod 授予扩展原版跑局后角色解锁纪元检查。
     /// </summary>
     public class PostRunCharacterUnlockEpochCompatibilityPatch : IPatchMethod
     {
@@ -106,7 +107,7 @@ public class PostRunCharacterUnlockEpochCompatibilityPatch : IPatchMethod
 
         /// <inheritdoc />
         public static string Description =>
-            "Handle post-run character unlock epochs for mod characters via registered RitsuLib unlock rules";
+            "Handle registered or template-derived post-run character unlock epochs without blocking vanilla chains";
 
         /// <inheritdoc />
         public static bool IsCritical => false;
@@ -123,8 +124,8 @@ public static ModPatchTarget[] GetTargets()
         }
 
         /// <summary>
-        ///     Obtains the registered post-run character-unlock epoch when appropriate; skips vanilla when handled.
-        ///     在适当时获得已注册的跑局后角色解锁纪元；已处理时跳过原版逻辑。
+        ///     Obtains registered or template-derived post-run character-unlock epochs when appropriate.
+        ///     在适当时获得已注册或模板推导出的跑局后角色解锁纪元。
         /// </summary>
         public static bool Prefix(SerializablePlayer serializablePlayer, SerializableRun serializableRun)
         {
@@ -133,41 +134,48 @@ public static bool Prefix(SerializablePlayer serializablePlayer, SerializableRun
 
             ArgumentNullException.ThrowIfNull(serializablePlayer.CharacterId);
             var character = ModelDb.GetById<CharacterModel>(serializablePlayer.CharacterId);
-            if (!ModContentRegistry.TryGetOwnerModId(character.GetType(), out _))
-                return true;
+            var isModCharacter = ModContentRegistry.TryGetOwnerModId(character.GetType(), out _);
 
             if (!Sts2RunGameModeCompat.IsStandardSerializableRunForEpochUnlocks(serializableRun))
                 return true;
 
-            if (!ModUnlockRegistry.TryGetPostRunCharacterUnlockEpoch(character.Id, out var epochId))
+            var epochIds = new HashSet<string>(StringComparer.Ordinal);
+            foreach (var epochId in ModUnlockRegistry.GetPostRunCharacterUnlockEpochs(character.Id))
+                epochIds.Add(epochId);
+            foreach (var epochId in ModTimelineNeowCoExpansion.GetModCharacterRootEpochIdsUnlockedAfterRunAs(
+                         character.Id))
+                epochIds.Add(epochId);
+
+            if (epochIds.Count == 0)
             {
+                if (!isModCharacter)
+                    return true;
+
                 if (character is IModCharacterEpochTimelineRequirement { RequiresEpochAndTimeline: false })
                     return false;
 
                 ModUnlockMissingRuleWarnings.WarnOnce(
                     $"postrun_char_unlock_epoch:{character.Id}",
-                    $"[Unlocks] Mod character '{character.Id}' has no registered post-run character-unlock epoch (UnlockCharacterAfterRunAs / RegisterPostRunCharacterUnlockEpoch). " +
+                    $"[Unlocks] Mod character '{character.Id}' has no registered post-run character-unlock epoch (UnlocksAfterRunAsType / UnlockCharacterAfterRunAs / RegisterPostRunCharacterUnlockEpoch). " +
                     "Leaving vanilla post-run check in place (no-op for this character).");
                 return true;
             }
 
-            if (SaveManager.Instance.Progress.IsEpochObtained(epochId))
-                return false;
-
-            if (!EpochRuntimeCompatibility.CanUseEpochId(
-                    epochId,
-                    $"post-run character unlock epoch rule for mod character '{character.Id}'"))
-                return false;
-
-            SaveManager.Instance.ObtainEpoch(epochId);
-            NGame.Instance?.AddChildSafely(NGainEpochVfx.Create(EpochModel.Get(epochId)));
-            if (!serializablePlayer.DiscoveredEpochs.Contains(epochId, StringComparer.Ordinal))
-                serializablePlayer.DiscoveredEpochs.Add(epochId);
+            foreach (var epochId in epochIds.Where(epochId => !SaveManager.Instance.Progress.IsEpochObtained(epochId))
+                         .Where(epochId => EpochRuntimeCompatibility.CanUseEpochId(
+                             epochId,
+                             $"post-run character unlock epoch rule after run as '{character.Id}'")))
+            {
+                SaveManager.Instance.ObtainEpoch(epochId);
+                NGame.Instance?.AddChildSafely(NGainEpochVfx.Create(EpochModel.Get(epochId)));
+                if (!serializablePlayer.DiscoveredEpochs.Contains(epochId, StringComparer.Ordinal))
+                    serializablePlayer.DiscoveredEpochs.Add(epochId);
 
-            RitsuLibFramework.Logger.Info(
-                $"[Unlocks] Obtained post-run character unlock epoch '{epochId}' for mod character '{character.Id}'.");
+                RitsuLibFramework.Logger.Info(
+                    $"[Unlocks] Obtained post-run character unlock epoch '{epochId}' after run as '{character.Id}'.");
+            }
 
-            return false;
+            return !isModCharacter;
         }
     }