[Bug] Android: v0.4.24 causes black screen, v0.2.40 works

[asdoo4069]

Hi again. I previously reported Android compatibility issues in #38, which were eventually resolved and allowed RitsuLib to work correctly on Android.

Unfortunately, I seem to have encountered a new regression after updating to the latest version.

Environment

• Mobile Launcher: v0.3.29
• Slay the Spire 2: v0.103.3
• RitsuLib: v0.4.24

Regression

Using the exact same environment:

• RitsuLib v0.2.40 → works correctly
• RitsuLib v0.4.24 → game gets stuck on a black screen during startup

Relevant log errors

The log contains several exceptions during framework initialization:

KeyNotFoundException:
The given key 'ACT.OVERGROWTH' was not present in the dictionary.

followed by:

The type initializer for 'UnlockState' threw an exception.

and:

The type initializer for 'NPotionHolder' threw an exception.

with:

LocString.GetFormattedText()
NullReferenceException

Eventually framework initialization fails:

Critical patch(es) failed, rolling back all patches.
Framework initialization failed: critical framework patches failed.

Additional notes

The previous Android compatibility fix from #38 appears to still be working correctly. The log shows:

[MobileSteam] Native Steamworks calls are disabled on this mobile host.

so this does not appear to be related to the older Steamworks issue.

I was able to use RitsuLib on Android for several months after #38 was resolved, so this appears to be a regression introduced somewhere between v0.2.40 and v0.4.24.

I've attached the launcher log for reference.

If this issue is ultimately determined to be caused by the launcher rather than RitsuLib itself, I'd be happy to forward the report to the launcher developer and continue the investigation there.

Thanks again for all the Android compatibility work you've done so far.

launcher_20260618_233035.log

[ritsukage-local-analyzer]

Warning

此分析由 AI 自动生成，仅供开发者参考，最终判断请以人工确认为准。如有疑问建议结合本地环境进一步复现确认。

摘要

Android 平台在升级 RitsuLib 至 v0.4.24 后启动即黑屏，根本原因是 UnlockState 的静态构造函数在移动端 ModelDb.Init 完成前被触发，导致查找 ACT.OVERGROWTH 键时抛出 KeyNotFoundException，进而引发类型初始化连锁崩溃并终止框架初始化。该问题属于 v0.2.40 → v0.4.24 之间引入的 Android 兼容性退行，已有日志附件，建议优先读取日志定位具体失败的 patch。

重点结论

项目	内容
简单介绍	Android 上 v0.4.24 启动时黑屏，v0.2.40 正常；框架初始化在 UnlockState 静态构造失败后全部回滚
可能原因	v0.4.24 新增的某个 patch 或静态初始化路径在 Android 的 mod 加载阶段（ModelDb.Init 完成之前）触及了 UnlockState 的静态成员，而现有的 RitsuLibMobileModelDbInitPostfixPatch 延迟机制只涵盖了 CharacterUnlockFilterPatch / SharedAncientUnlockFilterPatch 等少数 patch，未能覆盖 v0.4.x 新增路径
可能解决方案	① 读取附件日志，找到第一条 [Critical] / [Optional] ... Failed 行，确认是哪个 patch ID 触发了 TypeInitializationException；② 将触发时序问题的新代码路径纳入移动端延迟机制（参考现有的 if (!SuppressNativeSteamIntegration) 守卫逻辑）
需要补充	附件日志（launcher_20260618_233035.log）已提供，维护者需下载并定位第一个失败的 patch；其他已安装 mod 列表未知（可能影响 patch 顺序，但不是主因）

展开详细分析、证据与验证

问题描述

期望行为

使用 Android 移动启动器 v0.3.29、STS2 v0.103.3、RitsuLib v0.4.24，游戏正常启动，与 v0.2.40 行为一致。

实际行为

游戏卡在黑屏，框架初始化失败并回滚全部 Harmony patch。

复现步骤

1. Android 移动启动器 v0.3.29，STS2 v0.103.3
2. 安装 RitsuLib v0.4.24（此前 v0.2.40 可正常工作）
3. 启动游戏 → 黑屏

---

环境与版本

• 平台：Android（移动启动器）
• Mobile Launcher：v0.3.29
• Slay the Spire 2：v0.103.3
• RitsuLib：v0.4.24（退行版本），v0.2.40（正常版本）

---

日志、附件与原文摘录

报告者附上了 launcher_20260618_233035.log，以下为关键错误序列（原文引用）：

KeyNotFoundException: The given key 'ACT.OVERGROWTH' was not present in the dictionary.
The type initializer for 'UnlockState' threw an exception.
The type initializer for 'NPotionHolder' threw an exception.
LocString.GetFormattedText() NullReferenceException
Critical patch(es) failed, rolling back all patches.
Framework initialization failed: critical framework patches failed.

同时日志确认 #38 的 Steamworks 修复仍在生效：

[MobileSteam] Native Steamworks calls are disabled on this mobile host.

---

详细分析依据

ACT.OVERGROWTH 不是缺失内容：在仓库中 v0.103.2 / v0.103.3 / v0.104.0 的 localization/zhs/acts.json 均含 "OVERGROWTH.title": "密林"，确认该 Act 在游戏数据中存在。错误根因是时序问题，而非内容缺失。

Android 初始化时序差异：在 Android 上，STS2Mobile 替换了 ModelDb.Init，其执行时机晚于 PC 的 mod 加载阶段。UnlockState 的静态构造函数在初始化时会查询 Act 字典（ACT.OVERGROWTH 等键），但此时 ModelDb.Init 尚未运行，字典为空，故抛出 KeyNotFoundException。

现有移动端延迟机制（RitsuLibMobileModelDbInitPostfixPatch，Platform/Patches/RitsuLibMobileModelDbInitPostfixPatch.cs）：
该 patch 在 ModelDb.Init 完成后才应用 NDailyRunLoadScreenBeginRunMissingCharacterPatch、CharacterUnlockFilterPatch、SharedAncientUnlockFilterPatch。PatcherSetup.cs 第 160 行的守卫 if (RitsuLibMobileSteamRuntime.SuppressNativeSteamIntegration) 同样跳过了部分 unlock patch 的即时注册。

v0.4.24 新增内容超出现有守卫范围：对比 RegisterUnlockPatches() 注册列表，v0.4.24 相较 v0.2.40 新增了大量未受移动端守卫保护的 patch（如 ModCharacterRootEpochBackfillPatch、ModRequiredEpochUnlockStatePatch、StartRunLobbyLocalHostUnlockStatePatch、多个时间线扩展相关 patch 等），以及 Core 区的网络、诊断、副手等全新系统。这些 patch 若在方法反射或 Harmony 编译阶段触及 UnlockState 的静态成员，即可在 ModelDb.Init 前提前触发其类型初始化。

连锁崩溃机制：C# 中若某类型的静态构造函数抛出异常，该类型此后每次被访问都会再次抛出 TypeInitializationException。UnlockState 失败 → NPotionHolder（依赖 UnlockState）失败 → LocString.GetFormattedText() 取到 null → 作为 critical patch 失败触发全回滚 → 框架拒绝激活 → 黑屏。

v0.2.40 正常的原因：该版本尚未引入触发 UnlockState 静态初始化的代码路径，移动端延迟机制足以保护当时存在的 patch 集合。

---

详细验证建议

• 下载附件 launcher_20260618_233035.log，搜索第一条含 [Critical] 或 Failed ✗ 的 RitsuLib patch 日志行，确认触发链的起始 patch ID
• 在日志中查找 TypeInitializationException 和 UnlockState 出现的具体栈帧，判断是哪个 patch 的 method resolution 触发了 UnlockState 的静态构造
• 确认触发点是否属于 v0.4.x 新增代码路径（对比 v0.2.40 的 RegisterUnlockPatches / RegisterLifecyclePatches 差异）
• 验证将该代码路径纳入 RitsuLibMobileModelDbInitPostfixPatch 延迟逻辑后，Android 能正常启动

---

风险与未决

• 未知 mod 列表：报告者未说明是否安装了其他 mod；其他 mod 的 patch 顺序理论上可能影响 UnlockState 初始化时机，但根据日志中 RitsuLib 框架自报的失败信息，主因应在 RitsuLib 本体
• 移动启动器版本：v0.3.29 与之前版本相比若改变了 ModelDb.Init 的调用时机，也可能缩短了安全窗口；需确认启动器侧是否有相关变更
• 修复范围：延迟机制可能需要比现有 patch 列表更通用的保护方式，以防未来再次出现类似问题

---

English translation

Summary

After upgrading RitsuLib to v0.4.24, Android users experience an immediate black screen on startup. The root cause is that UnlockState's static constructor is triggered before the mobile launcher's ModelDb.Init completes, causing a KeyNotFoundException for the key 'ACT.OVERGROWTH'. This propagates as a type-initializer cascade failure and terminates framework initialization. The issue is an Android compatibility regression introduced somewhere between v0.2.40 and v0.4.24. A log file is attached; reading it to locate the first failing patch ID should be the immediate next step.

Key Takeaways

Field	Detail
Problem	On Android, v0.4.24 produces a black screen at startup; v0.2.40 worked correctly. All Harmony patches are rolled back after the UnlockState static constructor failure.
Likely cause	A new patch or static-initialization path added in v0.4.24 touches a static member of UnlockState during the Android mod-load phase, before ModelDb.Init has populated the act dictionary. The existing RitsuLibMobileModelDbInitPostfixPatch deferral only covers a small fixed set of unlock patches (CharacterUnlockFilterPatch / SharedAncientUnlockFilterPatch / etc.) and does not extend to the new code paths introduced in v0.4.x.
Recommended action	① Open the attached log, find the first [Critical] ... Failed or Failed ✗ patch line, and identify which patch ID initiated the TypeInitializationException chain. ② Bring the offending code path under the mobile deferral mechanism (follow the existing if (!SuppressNativeSteamIntegration) guard pattern in RitsuLibFramework.PatcherSetup.cs).
Missing info	The attached log (launcher_20260618_233035.log) needs to be downloaded by the maintainer to confirm the exact failing patch; other installed mods are unknown but are unlikely to be the primary cause.

Expand detailed analysis, evidence, and verification

Problem Description

Expected behavior

Game starts normally on Android (mobile launcher v0.3.29, STS2 v0.103.3, RitsuLib v0.4.24), matching v0.2.40 behavior.

Actual behavior

Game stalls on a black screen; framework initialization fails and rolls back all Harmony patches.

Reproduction steps

1. Android device, mobile launcher v0.3.29, STS2 v0.103.3.
2. Install RitsuLib v0.4.24 (v0.2.40 previously worked on the same setup).
3. Launch the game → black screen.

---

Environment and versions

• Platform: Android (mobile launcher)
• Mobile Launcher: v0.3.29
• Slay the Spire 2: v0.103.3
• RitsuLib: v0.4.24 (regressed), v0.2.40 (known-good)

---

Logs, attachments, and excerpts

The reporter attached launcher_20260618_233035.log. Key error sequence (quoted from issue body):

KeyNotFoundException: The given key 'ACT.OVERGROWTH' was not present in the dictionary.
The type initializer for 'UnlockState' threw an exception.
The type initializer for 'NPotionHolder' threw an exception.
LocString.GetFormattedText() NullReferenceException
Critical patch(es) failed, rolling back all patches.
Framework initialization failed: critical framework patches failed.

The log also confirms that the #38 Steamworks fix still applies:

[MobileSteam] Native Steamworks calls are disabled on this mobile host.

---

Detailed analysis

ACT.OVERGROWTH is not missing content. Repository sources for v0.103.2, v0.103.3, and v0.104.0 all contain "OVERGROWTH.title" in localization/zhs/acts.json (the "密林" / Overgrowth act). The key exists in the game's data; the error is purely a timing issue.

Android init-order difference. On Android, STS2Mobile replaces ModelDb.Init and executes it later than the mod-load pass. UnlockState's static constructor queries the act model dictionary (which includes ACT.OVERGROWTH) during its initialization. If that constructor runs before ModelDb.Init completes, the dictionary lookup fails with KeyNotFoundException.

Existing mobile deferral mechanism (RitsuLibMobileModelDbInitPostfixPatch, located at Platform/Patches/RitsuLibMobileModelDbInitPostfixPatch.cs): After ModelDb.Init fires, this patch applies NDailyRunLoadScreenBeginRunMissingCharacterPatch, CharacterUnlockFilterPatch, and SharedAncientUnlockFilterPatch. The guard if (RitsuLibMobileSteamRuntime.SuppressNativeSteamIntegration) in PatcherSetup.cs (line 160) also suppresses a few additional unlock patches from immediate registration. However, this set is fixed and small.

v0.4.24 new code outside the guard. Comparing RegisterUnlockPatches() and RegisterLifecyclePatches() in RitsuLibFramework.PatcherSetup.cs, v0.4.24 registers many new patches not protected by any mobile guard: ModCharacterRootEpochBackfillPatch, ModRequiredEpochUnlockStatePatch, StartRunLobbyLocalHostUnlockStatePatch, multiple timeline expansion patches, plus entirely new subsystems in the Core area (sidecar networking, state-divergence diagnostics, secondary resources, model identity, card piles, etc.). Any of these that cause Harmony's method resolution or JIT compilation to access a static member of UnlockState before ModelDb.Init will trigger the failure.

Type-initializer cascade. In C#, once a type's static constructor throws, every subsequent use of that type re-throws TypeInitializationException. UnlockState failure → NPotionHolder (which depends on UnlockState) failure → LocString.GetFormattedText() receives null → triggers a critical patch failure → full Harmony rollback → framework inactive → black screen.

Why v0.2.40 worked. That version had not yet introduced code paths that trigger UnlockState's static initialization during the Android mod-load phase; the existing deferral mechanism was sufficient to protect the narrower patch set.

---

Verification checklist

• Download the attached launcher_20260618_233035.log and search for the first line containing [Critical] or Failed ✗ emitted by RitsuLib's patcher, to confirm which patch ID started the TypeInitializationException chain.
• Within that log, locate the full stack trace of the TypeInitializationException to determine exactly which Harmony method-resolution step triggered UnlockState's static constructor.
• Confirm whether the triggering code is a v0.4.x addition by comparing the RegisterUnlockPatches / RegisterLifecyclePatches diff between v0.2.40 and v0.4.24.
• After extending the deferral guard to cover the offending path, verify that the Android launch succeeds on the same environment.

---

Risks and open questions

• Other installed mods unknown. The reporter did not list other mods; a third-party mod's patches could theoretically interfere, but the RitsuLib framework's own failure log lines strongly indicate the root cause is internal to RitsuLib.
• Mobile launcher v0.3.29 timing change. If v0.3.29 delayed ModelDb.Init further compared to older launcher versions, the safe window may have shrunk independently of RitsuLib changes. Worth cross-checking with the launcher developer if the RitsuLib fix does not fully resolve the issue.
• Fix scope. The deferral mechanism may benefit from a more general protection strategy (e.g., guarding all unlock patches rather than a hand-maintained list) to avoid similar regressions in future releases.

---

工具侧记录

• BAKAOLC/STS2-RitsuLib#57 · 退出码 0 · 进程 436.82s
• claude-sonnet-4-6 · API 434443ms · 33 轮 · ↓26 ↑19348 · 缓存读1698444 写155885 · $1.7351
• MCP available: management tools exposed to Claude.

[BAKAOLC]

Since I personally lack mobile devices, I cannot conveniently perform actual testing for most ports.
In the CN environment, there is a similar launcher for this, and it basically works properly, so perhaps it can be used as a reference.
https://github.com/ModinMobileSTS/Sts2MobileLauncher
Issues like missing methods are caused by the launcher's logic handling, so it might be necessary to make some references on the launcher side.

However, I can indeed correct the initialization timing of some patches. Let me fix this part, and then the rest may require assistance from the launcher

Original (CN)

因为我个人缺少移动端设备，所以大多数移植版我并不能方便的实际测试。 这块的话在 CN 环境有个类似的启动器，它的工作基本是正常的，也许可以作为参考 https://github.com/ModinMobileSTS/Sts2MobileLauncher 有些方法缺失之类的行为是启动器的逻辑处理导致的，所以可能得启动器方面进行一定的参考

不过有些 patch 的初始化时机我确实可以修正一下，等我修改掉这部分然后其他的可能就需要启动器方面协助了

[BAKAOLC]

I have adjusted the creation and timing of some patches, so this should resolve the issues related to initialization timing in the logs.
Since the game is likely to release a new version today, I have accumulated quite a bit of content but haven't released a version yet. This adjustment will also be released together after the new game version is released.
As for the issue of the harmony method not being found, this part requires assistance from the mobile launcher side to resolve.

Original (CN)

我调整了部分patch的创建和生效时机，因此这应该能解决日志中与初始化时机相关的问题

由于今天大概率游戏会发布新版本，因此我囤积了不少内容但是尚未发布版本，这个调整也将等到游戏新版本发布后再一并发布。

至于 harmony 方法找不到的问题，这部分需要移动端启动器方面辅助解决。

/r set wip

[BAKAOLC]

For the remaining MissingMethodException part, this seems to match an existing launcher-side limitation that is already mentioned in this launcher.

In StS2-Launcher_Mod_Manager, BaseLibCompatPatches already describes a very similar root cause:

https://github.com/iunius612/StS2-Launcher_Mod_Manager/blob/40e6399f6f56e109cc1865316f35be5d05de1488/src/STS2Mobile/Patches/BaseLibCompatPatches.cs#L21-L29

// CombatRoom.FromSerializable whose wrapper generation throws
// MissingMethodException on set_ShouldResumeParentEventAfterCombat — an
// init-only setter (modreq IsExternalInit) in the original method body
// that MonoMod's import path can't resolve on Mono Android. The setter
// exists in the loaded sts2.dll bytes ...

The CardPlay.set_Card(CardModel) error from this issue should be the same class of problem. CardPlay.Card is also an init property, so its setter has required custom modifiers in metadata. If MonoMod/Harmony imports the STS2 method reference without preserving those modifiers, the generated wrapper can reference a setter signature that does not match the real method metadata, resulting in MissingMethodException even though the setter exists.

The current launcher workaround skips one known BaseLib patch container:

https://github.com/iunius612/StS2-Launcher_Mod_Manager/blob/40e6399f6f56e109cc1865316f35be5d05de1488/src/STS2Mobile/Patches/BaseLibCompatPatches.cs#L117-L189

That only covers this specific BaseLib patch. For RitsuLib and other mods, the more general fix should be in the Harmony/MonoMod method-reference import path.

A possible launcher-side fix is to install an early shim before normal game/mod Harmony patches run. In this launcher, the insertion point should be around ModEntry.Apply, after the TMPDIR setup and before BaseLibCompatPatches.Apply(...) / other game patches:

https://github.com/iunius612/StS2-Launcher_Mod_Manager/blob/40e6399f6f56e109cc1865316f35be5d05de1488/src/STS2Mobile/ModEntry.cs#L81-L99

Conceptually:

 PatchHelper.Log("Initializing STS2Mobile...");

 _harmony = new Harmony("com.sts2mobile");

+HarmonyMethodReferenceImporterShim.Initialize();

 // Game-assembly-independent — must run in both standalone-launcher and game modes
 RenderDiagnosticPatches.Apply(_harmony);

 ...
 BaseLibCompatPatches.Apply(_harmony);

The shim can patch MonoMod's reflection importer. A working reference implementation is here:

https://github.com/ModinMobileSTS/sts2-android-compat/blob/da76c457f3f58947836c1fbba224ee816746a5f1/STS2AndroidPortCompat/HarmonyMethodReferenceImporterShim.cs

The key parts are:

1. Patch MMReflectionImporter.ImportReference(MethodBase, IGenericParameterProvider):

var importerType = ResolveType("MonoMod.Utils", "MonoMod.Utils.MMReflectionImporter");
var genericProviderType = ResolveType("Mono.Cecil", "Mono.Cecil.IGenericParameterProvider");

var target = importerType.GetMethod(
    "ImportReference",
    BindingFlags.Public | BindingFlags.Instance,
    null,
    new[] { typeof(MethodBase), genericProviderType },
    null);

var postfix = typeof(HarmonyMethodReferenceImporterShim).GetMethod(
    nameof(ImportReferencePostfix),
    BindingFlags.NonPublic | BindingFlags.Static);

new Harmony(HarmonyId).Patch(target, postfix: new HarmonyMethod(postfix));

Reference:
https://github.com/ModinMobileSTS/sts2-android-compat/blob/da76c457f3f58947836c1fbba224ee816746a5f1/STS2AndroidPortCompat/HarmonyMethodReferenceImporterShim.cs#L41-L70

2. Only repair STS2 method references that actually contain custom modifiers:

private static bool ShouldImportWithModifiers(MethodBase method)
{
    if (method == null || !IsSts2Method(method))
        return false;

    if (method is MethodInfo methodInfo && HasCustomModifiers(methodInfo.ReturnParameter))
        return true;

    var parameters = method.GetParameters();
    for (var i = 0; i < parameters.Length; i++)
    {
        if (HasCustomModifiers(parameters[i]))
            return true;
    }

    return false;
}

Reference:
https://github.com/ModinMobileSTS/sts2-android-compat/blob/da76c457f3f58947836c1fbba224ee816746a5f1/STS2AndroidPortCompat/HarmonyMethodReferenceImporterShim.cs#L87-L102

3. Copy required/optional custom modifiers from reflection metadata back into the imported Cecil method reference:

private static void ApplyMethodReferenceModifiers(
    object importer,
    object methodReference,
    MethodBase method,
    object context)
{
    SetProperty(methodReference, "ReturnType", ImportReturnType(importer, method, methodReference));

    var importedParameters = GetProperty(methodReference, "Parameters") as System.Collections.IEnumerable;
    if (importedParameters == null)
        return;

    var originalParameters = method.GetParameters();
    var index = 0;
    foreach (var importedParameter in importedParameters)
    {
        if (index >= originalParameters.Length)
            break;

        var originalParameter = originalParameters[index++];
        SetProperty(
            importedParameter,
            "ParameterType",
            ImportTypeWithModifiers(
                importer,
                originalParameter.ParameterType,
                originalParameter.GetRequiredCustomModifiers(),
                originalParameter.GetOptionalCustomModifiers(),
                methodReference));
    }
}

Reference:
https://github.com/ModinMobileSTS/sts2-android-compat/blob/da76c457f3f58947836c1fbba224ee816746a5f1/STS2AndroidPortCompat/HarmonyMethodReferenceImporterShim.cs#L104-L132

4. Rebuild Cecil type references with RequiredModifierType / OptionalModifierType:

var requiredModifierType = ResolveType("Mono.Cecil", "Mono.Cecil.RequiredModifierType");
for (var i = 0; i < requiredModifiers.Length; i++)
{
    var modifier = CallImporter(
        importer,
        "ImportReference",
        new[] { typeof(Type), genericProviderType },
        requiredModifiers[i],
        context);

    typeReference = Activator.CreateInstance(requiredModifierType, modifier, typeReference);
}

var optionalModifierType = ResolveType("Mono.Cecil", "Mono.Cecil.OptionalModifierType");
for (var i = 0; i < optionalModifiers.Length; i++)
{
    var modifier = CallImporter(
        importer,
        "ImportReference",
        new[] { typeof(Type), genericProviderType },
        optionalModifiers[i],
        context);

    typeReference = Activator.CreateInstance(optionalModifierType, modifier, typeReference);
}

Reference:
https://github.com/ModinMobileSTS/sts2-android-compat/blob/da76c457f3f58947836c1fbba224ee816746a5f1/STS2AndroidPortCompat/HarmonyMethodReferenceImporterShim.cs#L147-L174

5. Initialize this before normal Harmony patches:

TryForceMonoLikeRuntimeDetection();
TryForceAndroidPlatformDetection();
TryLogMonoModDetection("after_platform_override");
TryLogResolvedMonoModBackend();
HarmonyMethodReferenceImporterShim.Initialize();

Reference:
https://github.com/ModinMobileSTS/sts2-android-compat/blob/da76c457f3f58947836c1fbba224ee816746a5f1/STS2AndroidPortCompat/HarmonyAndroidCompat.cs#L43-L47

This reference implementation may not be directly copy-pasteable because the launchers use different Harmony/MonoMod versions and bootstrap paths. But the required behavior should be the same: when importing STS2 MethodBase references for Harmony/MonoMod wrapper generation, required and optional custom modifiers must be preserved. Otherwise, any patch whose original method body contains init setter calls can fail with MissingMethodException.

For this launcher specifically, this would also be a more general replacement for the current one-off workaround around set_ShouldResumeParentEventAfterCombat, and should cover the RitsuLib CardPlay.set_Card case as well.

Original (CN)

对于剩下的 MissingMethodException 部分，这看起来和该启动器里已经记录过的一个启动器侧限制是同类问题。

在 StS2-Launcher_Mod_Manager 里，BaseLibCompatPatches 已经描述过一个非常接近的根因：

https://github.com/iunius612/StS2-Launcher_Mod_Manager/blob/40e6399f6f56e109cc1865316f35be5d05de1488/src/STS2Mobile/Patches/BaseLibCompatPatches.cs#L21-L29

// CombatRoom.FromSerializable whose wrapper generation throws
// MissingMethodException on set_ShouldResumeParentEventAfterCombat — an
// init-only setter (modreq IsExternalInit) in the original method body
// that MonoMod's import path can't resolve on Mono Android. The setter
// exists in the loaded sts2.dll bytes ...

这个 issue 里出现的 CardPlay.set_Card(CardModel) 应该也是同类问题。CardPlay.Card 同样是 init 属性，因此它的 setter 在 metadata 中带有 required custom modifiers。如果 MonoMod/Harmony 在导入 STS2 方法引用时没有保留这些 modifiers，生成出来的 wrapper 可能会引用一个和真实方法 metadata 不匹配的 setter 签名，于是即使 setter 实际存在，也会出现 MissingMethodException。

当前启动器里的 workaround 是跳过一个已知的 BaseLib patch 容器：

https://github.com/iunius612/StS2-Launcher_Mod_Manager/blob/40e6399f6f56e109cc1865316f35be5d05de1488/src/STS2Mobile/Patches/BaseLibCompatPatches.cs#L117-L189

这只能覆盖这个特定的 BaseLib patch。对于 RitsuLib 或其他 mod，更通用的修复应该放在 Harmony/MonoMod 的方法引用导入路径上。

一个可能的启动器侧修复方式，是在普通游戏/mod Harmony patch 执行前安装一个早期 shim。对于这个启动器，插入点大概在 ModEntry.Apply 中，TMPDIR 设置完成之后、BaseLibCompatPatches.Apply(...) 和其他游戏 patch 之前：

https://github.com/iunius612/StS2-Launcher_Mod_Manager/blob/40e6399f6f56e109cc1865316f35be5d05de1488/src/STS2Mobile/ModEntry.cs#L81-L99

概念上类似：

 PatchHelper.Log("Initializing STS2Mobile...");

 _harmony = new Harmony("com.sts2mobile");

+HarmonyMethodReferenceImporterShim.Initialize();

 // Game-assembly-independent — must run in both standalone-launcher and game modes
 RenderDiagnosticPatches.Apply(_harmony);

 ...
 BaseLibCompatPatches.Apply(_harmony);

这个 shim 可以 patch MonoMod 的 reflection importer。这里有一个可工作的参考实现：

https://github.com/ModinMobileSTS/sts2-android-compat/blob/da76c457f3f58947836c1fbba224ee816746a5f1/STS2AndroidPortCompat/HarmonyMethodReferenceImporterShim.cs

关键部分是：

1. Patch MMReflectionImporter.ImportReference(MethodBase, IGenericParameterProvider)：

var importerType = ResolveType("MonoMod.Utils", "MonoMod.Utils.MMReflectionImporter");
var genericProviderType = ResolveType("Mono.Cecil", "Mono.Cecil.IGenericParameterProvider");

var target = importerType.GetMethod(
    "ImportReference",
    BindingFlags.Public | BindingFlags.Instance,
    null,
    new[] { typeof(MethodBase), genericProviderType },
    null);

var postfix = typeof(HarmonyMethodReferenceImporterShim).GetMethod(
    nameof(ImportReferencePostfix),
    BindingFlags.NonPublic | BindingFlags.Static);

new Harmony(HarmonyId).Patch(target, postfix: new HarmonyMethod(postfix));

参考：
https://github.com/ModinMobileSTS/sts2-android-compat/blob/da76c457f3f58947836c1fbba224ee816746a5f1/STS2AndroidPortCompat/HarmonyMethodReferenceImporterShim.cs#L41-L70

2. 只修复真正带有 custom modifiers 的 STS2 方法引用：

private static bool ShouldImportWithModifiers(MethodBase method)
{
    if (method == null || !IsSts2Method(method))
        return false;

    if (method is MethodInfo methodInfo && HasCustomModifiers(methodInfo.ReturnParameter))
        return true;

    var parameters = method.GetParameters();
    for (var i = 0; i < parameters.Length; i++)
    {
        if (HasCustomModifiers(parameters[i]))
            return true;
    }

    return false;
}

参考：
https://github.com/ModinMobileSTS/sts2-android-compat/blob/da76c457f3f58947836c1fbba224ee816746a5f1/STS2AndroidPortCompat/HarmonyMethodReferenceImporterShim.cs#L87-L102

3. 把 reflection metadata 里的 required/optional custom modifiers 复制回导入后的 Cecil method reference：

private static void ApplyMethodReferenceModifiers(
    object importer,
    object methodReference,
    MethodBase method,
    object context)
{
    SetProperty(methodReference, "ReturnType", ImportReturnType(importer, method, methodReference));

    var importedParameters = GetProperty(methodReference, "Parameters") as System.Collections.IEnumerable;
    if (importedParameters == null)
        return;

    var originalParameters = method.GetParameters();
    var index = 0;
    foreach (var importedParameter in importedParameters)
    {
        if (index >= originalParameters.Length)
            break;

        var originalParameter = originalParameters[index++];
        SetProperty(
            importedParameter,
            "ParameterType",
            ImportTypeWithModifiers(
                importer,
                originalParameter.ParameterType,
                originalParameter.GetRequiredCustomModifiers(),
                originalParameter.GetOptionalCustomModifiers(),
                methodReference));
    }
}

参考：
https://github.com/ModinMobileSTS/sts2-android-compat/blob/da76c457f3f58947836c1fbba224ee816746a5f1/STS2AndroidPortCompat/HarmonyMethodReferenceImporterShim.cs#L104-L132

4. 用 RequiredModifierType / OptionalModifierType 重新包装 Cecil type reference：

var requiredModifierType = ResolveType("Mono.Cecil", "Mono.Cecil.RequiredModifierType");
for (var i = 0; i < requiredModifiers.Length; i++)
{
    var modifier = CallImporter(
        importer,
        "ImportReference",
        new[] { typeof(Type), genericProviderType },
        requiredModifiers[i],
        context);

    typeReference = Activator.CreateInstance(requiredModifierType, modifier, typeReference);
}

var optionalModifierType = ResolveType("Mono.Cecil", "Mono.Cecil.OptionalModifierType");
for (var i = 0; i < optionalModifiers.Length; i++)
{
    var modifier = CallImporter(
        importer,
        "ImportReference",
        new[] { typeof(Type), genericProviderType },
        optionalModifiers[i],
        context);

    typeReference = Activator.CreateInstance(optionalModifierType, modifier, typeReference);
}

参考：
https://github.com/ModinMobileSTS/sts2-android-compat/blob/da76c457f3f58947836c1fbba224ee816746a5f1/STS2AndroidPortCompat/HarmonyMethodReferenceImporterShim.cs#L147-L174

5. 在普通 Harmony patches 前初始化：

TryForceMonoLikeRuntimeDetection();
TryForceAndroidPlatformDetection();
TryLogMonoModDetection("after_platform_override");
TryLogResolvedMonoModBackend();
HarmonyMethodReferenceImporterShim.Initialize();

参考：
https://github.com/ModinMobileSTS/sts2-android-compat/blob/da76c457f3f58947836c1fbba224ee816746a5f1/STS2AndroidPortCompat/HarmonyAndroidCompat.cs#L43-L47

这个参考实现不一定能直接复制，因为两个启动器使用的 Harmony/MonoMod 版本和 bootstrap 路径不同。但需要实现的行为应该是一样的：Harmony/MonoMod 在为 wrapper 生成导入 STS2 的 MethodBase 引用时，需要保留 required 和 optional custom modifiers。否则任何原方法体里包含 init setter 调用的 patch 都可能因为生成错误的 method reference 而出现 MissingMethodException。

对于这个启动器来说，这也会比当前只针对 set_ShouldResumeParentEventAfterCombat 的一次性 workaround 更通用，并且应该能覆盖 RitsuLib 这次的 CardPlay.set_Card 问题。