[Bug] 可选的次要资源消耗规则未正确应用（重放/免费/自动打出）

[iouter]

模块范围

Public API（公开 API）

严重程度

Broken feature（功能不可用）

发生了什么？

卡牌均带有可选的次要资源消耗。
A. 卡牌带有重放，成功扣费后，只有第一次打出能执行额外效果，后续重放的都不会再执行额外效果。
B. 卡牌被设为免费，即不会扣费，也不会执行额外效果。
C. 卡牌被自动打出，如果不是类似于瓦库的自动打出（即在AutoPlay之前先SpendResources()），既不会扣费，也不会执行额外效果。

复现步骤

A. 打出一张带有可选的次要资源消耗，并且带有重放的卡牌。
B. 打出一张带有可选的次要资源消耗，并且被设为免费（card.SetToFree）的卡牌。
C. 自动打出一张带有可选的次要资源消耗的卡牌。

期望行为

A. 打出重放卡牌后，成功扣费（或不需要扣费），就每次重放都触发额外效果。
B. 打出免费卡牌后，不扣费，并触发额外效果。
C. 一般的自动打出，免费触发额外效果。瓦库的自动打出，则根据是否扣费触发额外效果。

日志 / 堆栈

RitsuLib 版本

0.4.36

运行环境

No response

[ritsukage-local-analyzer]

Warning

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

摘要

可选次级资源支付的 ledger 目前只在部分出牌路径上被正确标记和绑定，导致重放、免费打出、普通自动打出时额外效果容易丢失。影响面在 Public API 的 CardPlay.SecondaryResources()/Activated() 消费者，按现有描述可视为功能不可用级别。建议优先修正“支付一次、每个实际 CardPlay 都有可用 ledger”的契约，并补回免费/自动打出的可选支付激活语义。

重点结论

项目	结论
简单介绍	带可选次级资源消耗的卡牌在重放、SetToFree 免费、自动打出路径下，额外效果没有按预期触发。
可能原因	高置信：SpendResources() 只排入一个 pending ledger，OnPlayWrapper() 多次重放时只有第一个 CardPlay 能取到；同时免费/自动打出路径把可选支付行标记为未激活。
可能解决方案	让一次资源支付生成的 ledger 可绑定到该次出牌产生的每个重放 CardPlay；调整 free/autoplay 的可选支付行，使“免费但应触发”的行 Activated=true 且 AmountSpent=0。
需要补充	运行环境未填写；若方便，补一个最小测试卡/示例 mod 片段可帮助锁定 API 期望，日志不是当前定位的主要阻塞。

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

问题描述

期望行为

• 重放卡：首次成功扣费或不需要扣费后，每一次重放都应触发可选次级资源额外效果。
• 免费卡：card.SetToFree 后不扣次级资源，但仍触发额外效果。
• 自动打出：一般自动打出按免费触发额外效果；像瓦库这类在 AutoPlay 前主动 SpendResources() 的路径，则按是否实际扣费决定。

实际行为

• 重放卡只有第一次打出能执行额外效果，后续重放不执行。
• 免费卡不扣费，也不执行额外效果。
• 一般自动打出既不扣费，也不执行额外效果。

复现步骤

1. 打出一张带有可选次级资源消耗且带重放的卡牌。
2. 打出一张带有可选次级资源消耗且被 card.SetToFree 设为免费的卡牌。
3. 自动打出一张带有可选次级资源消耗的卡牌。

环境与版本

• RitsuLib：0.4.36
• 模块范围：Public API（公开 API）
• 运行环境：未提供

日志、附件与原文摘录

• 日志代码块为空，当前问题更像语义/状态绑定缺陷，不依赖堆栈才能初步定位。
• 摘录：

  卡牌带有重放，成功扣费后，只有第一次打出能执行额外效果

  • 要点：符合“pending ledger 只被消费一次”的症状。
• 摘录：

  卡牌被设为免费，即不会扣费，也不会执行额外效果

  • 要点：符合 free plan/CommitFree 将可选行设为未激活的实现行为。

详细分析依据

• RitsuLib 注册了次级资源相关补丁：CardModelSpendResourcesSecondaryResourcesPatch、CardModelOnPlayWrapperSecondaryResourcesPatch、HookBeforeCardPlayedSecondaryResourcesPatch 位于 src/RitsuLibFramework.PatcherSetup.cs:370 到 src/RitsuLibFramework.PatcherSetup.cs:373。
• 普通手动出牌路径在游戏本体 PlayCardAction 中先调用 _card.SpendResources()，再构造 ResourceInfo 并调用 _card.OnPlayWrapper(..., isAutoPlay: false, ...)：0.104.0/src/Core/GameActions/PlayCardAction.cs:88 到 0.104.0/src/Core/GameActions/PlayCardAction.cs:99。
• RitsuLib 对 CardModel.SpendResources 的补丁会在前缀中创建次级资源支付 plan，并在异步原方法之后 Commit(plan, card)：src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:65 到 src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:94。Commit 最终只调用一次 SecondaryResourcePlayLedgerRuntime.SetPending(plan.Card, ledger)：src/Combat/SecondaryResources/SecondaryResourceCosts.cs:545 到 src/Combat/SecondaryResources/SecondaryResourceCosts.cs:547。
• SecondaryResourcePlayLedgerRuntime 的 pending 存储是按卡牌排队的 queue，TryBindPending 只会 Dequeue() 一个 ledger 并附加到当前 CardPlay：src/Combat/SecondaryResources/SecondaryResourcePlayLedger.cs:246 到 src/Combat/SecondaryResources/SecondaryResourcePlayLedger.cs:311。而游戏本体 OnPlayWrapper 会按 playCount 循环创建多个 CardPlay：0.104.0/src/Core/Models/CardModel.cs:1460 到 0.104.0/src/Core/Models/CardModel.cs:1494。因此重放时只有第一次循环能绑定到 ledger，后续 CardPlay.SecondaryResources() 会回落为空 ledger。
• SetToFree 已由 RitsuLib 的 free-play binding 记录为下一次/本战斗免费：src/Cards/FreePlay/Patches/FreePlayBindingPatches.cs:20 到 src/Cards/FreePlay/Patches/FreePlayBindingPatches.cs:47；CanPlay 和 SpendResources 补丁都会读取 FreePlayBindingRegistry.IsCardFreeForUpcomingPlay(__instance)：src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:41 到 src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:43、src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:72 到 src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:75。
• 可选固定费用在 ResolveLine 中只有 !isFree && available >= fixedCost 才会 activated=true；免费时可选行会被视为未激活：src/Combat/SecondaryResources/SecondaryResourceCosts.cs:656 到 src/Combat/SecondaryResources/SecondaryResourceCosts.cs:681。CommitFree 对可选支付也显式写成 IsFree=true, AmountToSpend=0, Value=0, Activated=false：src/Combat/SecondaryResources/SecondaryResourceCosts.cs:554 到 src/Combat/SecondaryResources/SecondaryResourceCosts.cs:569。
• 游戏本体普通 CardCmd.AutoPlay 不调用 SpendResources()，而是用 EnergySpent=0/StarsSpent=0 直接进入 OnPlayWrapper(..., isAutoPlay: true, ...)：0.104.0/src/Core/Commands/CardCmd.cs:33 到 0.104.0/src/Core/Commands/CardCmd.cs:112。RitsuLib 的自动打出前缀会 Plan(__instance, true) 并 CommitFree(plan)：src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:119 到 src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:129，这解释了一般自动打出按免费处理但可选额外效果仍未激活。
• 因此，三类症状可以由两个实现点共同解释：ledger 生命周期只覆盖一次 CardPlay，以及“免费”语义对可选次级资源采用了“不扣费且不激活”，而 issue 期望是“不扣费但激活”。

反馈规范性提醒

维度	状态
复现步骤	已提供：覆盖重放、免费、自动打出三条路径，但未给最小测试卡代码。
期望/实际	已提供：三条路径分别说明清楚。
环境与版本	含糊：RitsuLib 版本为 0.4.36，运行环境为空。
日志/附件	缺失：日志块为空；当前不阻塞初步定位，但修复验证时最好补最小示例或测试用例。
标题与背景	已提供：标题准确指向“可选次要资源消耗规则”和三个触发路径。

详细验证建议

• 增加一张测试卡：附加 SecondaryResourceUses().SpendIfAvailable(...)，在 OnPlay 中记录 cardPlay.SecondaryResources().Activated(useId)。
• 手动出牌且带重放：确认次级资源只扣一次，但每个 PlayIndex 的 CardPlay 都能读到激活 ledger。
• SetToFreeThisTurn/SetToFreeThisCombat 后手动打出：确认次级资源不减少，ledger 中对应可选 use 为 IsFree=true、AmountSpent=0、Activated=true。
• 普通 CardCmd.AutoPlay：确认按免费路径触发可选额外效果，不发生次级资源扣费。
• 预先调用 SpendResources() 再 AutoPlay 的特殊路径：确认不会被 OnPlayWrapper 的免费 ledger 覆盖，且按真实扣费结果触发。
• 补一组必需次级资源费用回归，避免把“可选免费触发”的改动误扩散到必需费用或不可支付判定。

风险与未决

• 若现有 mod 使用 SpentByUse(useId) > 0 判断可选效果，免费触发语义可能仍需迁移到 Activated(useId) 或增加文档说明。
• 重放修复必须避免重复扣次级资源；应复用同一次支付结果的 ledger，而不是在每次 replay 重新 Commit。
• 自动打出路径需要区分“真正已预先扣费”的自动出牌与“一般免费自动出牌”，否则可能出现重复 ledger 或免费 ledger 覆盖已扣费 ledger。

---

English translation

Summary

Optional secondary-resource payment ledgers are currently marked and attached correctly only on part of the card-play flow, so replay, free play, and ordinary autoplay can lose the extra effect. The impact is on Public API consumers of CardPlay.SecondaryResources() / Activated(), and the reported behavior matches a broken-feature classification. The next step should be to enforce the contract “pay once, but expose a usable ledger on every actual CardPlay” and restore the activation semantics for free/autoplay optional spends.

Key Takeaways

Item	Conclusion
Brief description	Cards with optional secondary-resource spends fail to trigger their extra effect when replayed, made free via SetToFree, or autoplayed.
Likely cause	High confidence: SpendResources() enqueues only one pending ledger, so only the first replay CardPlay can consume it; free/autoplay paths also mark optional spend lines as inactive.
Possible fix	Make one payment ledger attach to every replay CardPlay produced by that play; adjust free/autoplay optional lines so “free but should trigger” means Activated=true and AmountSpent=0.
Needs more info	Runtime environment is not provided; a minimal test card or sample mod snippet would help pin down the API contract, though logs are not the main blocker for initial triage.

Expand detailed analysis, evidence, and verification

Problem Description

Expected behavior

• Replay cards: after the first successful payment, or when no payment is required, every replay should trigger the optional secondary-resource extra effect.
• Free cards: after card.SetToFree, the card should not spend secondary resources but should still trigger the extra effect.
• Autoplay: ordinary autoplay should trigger the extra effect for free; special paths such as Waku-style autoplay that call SpendResources() before AutoPlay should trigger based on whether payment actually occurred.

Actual behavior

• Replay cards execute the extra effect only on the first play; later replays do not.
• Free cards do not spend resources and also do not execute the extra effect.
• Ordinary autoplay neither spends resources nor executes the extra effect.

Reproduction steps

1. Play a card that has an optional secondary-resource spend and replay.
2. Play a card that has an optional secondary-resource spend and was made free via card.SetToFree.
3. Autoplay a card that has an optional secondary-resource spend.

Environment and Versions

• RitsuLib: 0.4.36
• Module scope: Public API
• Runtime environment: not provided

Logs, Attachments, and Excerpts

• The log block is empty. This appears to be a semantic/state-binding issue, so a stack trace is not required for initial localization.
• Excerpt:

  With replay, after successful payment, only the first play executes the extra effect.

  • Point: this matches the symptom of a pending ledger being consumed only once.
• Excerpt:

  When the card is made free, it does not spend resources and does not execute the extra effect.

  • Point: this matches the implementation where the free plan / CommitFree marks optional lines as inactive.

Detailed Analysis Basis

• RitsuLib registers secondary-resource patches including CardModelSpendResourcesSecondaryResourcesPatch, CardModelOnPlayWrapperSecondaryResourcesPatch, and HookBeforeCardPlayedSecondaryResourcesPatch in src/RitsuLibFramework.PatcherSetup.cs:370 through src/RitsuLibFramework.PatcherSetup.cs:373.
• The normal manual play path in the game calls _card.SpendResources(), builds ResourceInfo, then calls _card.OnPlayWrapper(..., isAutoPlay: false, ...): 0.104.0/src/Core/GameActions/PlayCardAction.cs:88 through 0.104.0/src/Core/GameActions/PlayCardAction.cs:99.
• RitsuLib’s CardModel.SpendResources patch creates a secondary-resource payment plan in the prefix and calls Commit(plan, card) after the original async method: src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:65 through src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:94. Commit ultimately calls SecondaryResourcePlayLedgerRuntime.SetPending(plan.Card, ledger) only once: src/Combat/SecondaryResources/SecondaryResourceCosts.cs:545 through src/Combat/SecondaryResources/SecondaryResourceCosts.cs:547.
• SecondaryResourcePlayLedgerRuntime stores pending ledgers as a per-card queue. TryBindPending attaches only one ledger to the current CardPlay by calling Dequeue(): src/Combat/SecondaryResources/SecondaryResourcePlayLedger.cs:246 through src/Combat/SecondaryResources/SecondaryResourcePlayLedger.cs:311. The game’s OnPlayWrapper creates multiple CardPlay instances in a loop according to playCount: 0.104.0/src/Core/Models/CardModel.cs:1460 through 0.104.0/src/Core/Models/CardModel.cs:1494. Therefore, on replay only the first loop iteration can bind the ledger; later CardPlay.SecondaryResources() calls fall back to an empty ledger.
• SetToFree is already bound by RitsuLib’s free-play binding patches for next-play / this-combat markers: src/Cards/FreePlay/Patches/FreePlayBindingPatches.cs:20 through src/Cards/FreePlay/Patches/FreePlayBindingPatches.cs:47. Both the CanPlay and SpendResources secondary-resource patches read FreePlayBindingRegistry.IsCardFreeForUpcomingPlay(__instance): src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:41 through src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:43, and src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:72 through src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:75.
• For a fixed optional cost, ResolveLine sets activated=true only when !isFree && available >= fixedCost; free optional lines are therefore inactive: src/Combat/SecondaryResources/SecondaryResourceCosts.cs:656 through src/Combat/SecondaryResources/SecondaryResourceCosts.cs:681. CommitFree also explicitly writes optional spend lines as IsFree=true, AmountToSpend=0, Value=0, Activated=false: src/Combat/SecondaryResources/SecondaryResourceCosts.cs:554 through src/Combat/SecondaryResources/SecondaryResourceCosts.cs:569.
• The game’s ordinary CardCmd.AutoPlay does not call SpendResources(). It builds a zero-spent ResourceInfo and directly enters OnPlayWrapper(..., isAutoPlay: true, ...): 0.104.0/src/Core/Commands/CardCmd.cs:33 through 0.104.0/src/Core/Commands/CardCmd.cs:112. RitsuLib’s autoplay prefix calls Plan(__instance, true) and CommitFree(plan): src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:119 through src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:129, which explains why ordinary autoplay is treated as free but still leaves the optional extra effect inactive.
• Thus the three reported symptoms can be explained by two implementation points: the ledger lifecycle covers only one CardPlay, and the “free” semantics for optional secondary resources currently mean “do not spend and do not activate,” while the issue expects “do not spend but activate.”

Feedback Hygiene Reminder

Dimension	Status
Reproduction steps	Provided: covers replay, free play, and autoplay, but no minimal test card code is included.
Expected/actual	Provided: the three paths are described clearly.
Environment and version	Ambiguous: RitsuLib version is 0.4.36, but runtime environment is empty.
Logs/attachments	Missing: the log block is empty; this does not block initial localization, but a minimal example or test case would help validation.
Title and background	Provided: the title accurately points to optional secondary-resource rules and the three affected paths.

Detailed Verification Suggestions

• Add a test card that attaches SecondaryResourceUses().SpendIfAvailable(...) and records cardPlay.SecondaryResources().Activated(useId) in OnPlay.
• Manual play with replay: confirm the secondary resource is spent once, while every PlayIndex CardPlay can read an activated ledger.
• Manual play after SetToFreeThisTurn / SetToFreeThisCombat: confirm secondary resources do not decrease, and the optional use line is IsFree=true, AmountSpent=0, Activated=true.
• Ordinary CardCmd.AutoPlay: confirm it triggers the optional extra effect through the free path without spending secondary resources.
• Special autoplay after a prior SpendResources() call: confirm it is not overwritten by the OnPlayWrapper free ledger and triggers according to the real payment result.
• Add required-secondary-resource regressions so the optional-free activation change does not leak into required-cost or unplayable checks.

Risks and Open Questions

• If existing mods check SpentByUse(useId) > 0 to decide whether an optional effect triggered, the free-trigger contract may still need migration guidance toward Activated(useId) or additional documentation.
• The replay fix must avoid repeated secondary-resource spending; it should reuse the ledger from the single payment result rather than Commit again for each replay.
• Autoplay handling must distinguish “payment already happened before autoplay” from “ordinary free autoplay,” otherwise it may create duplicate ledgers or overwrite a paid ledger with a free ledger.

---

工具侧记录

• BAKAOLC/STS2-RitsuLib#67 · 退出码 0 · 进程 366.54s
• gpt-5.5(high) · API 365666ms · 25 轮 · ↓79614 ↑8741 · 缓存读469504 写0 · $0.8513
• MCP available: management tools exposed to Claude.

[BAKAOLC]

/r set wip

[BAKAOLC]

https://github.com/BAKAOLC/STS2-RitsuLib/actions/runs/28184662242

你能试试这个版本吗？帮我测试一下它是否修复了这个问题
另外 #66 的 UI 颜色也可以看看

[iouter]

https://github.com/BAKAOLC/STS2-RitsuLib/actions/runs/28184662242

你能试试这个版本吗？帮我测试一下它是否修复了这个问题 另外 #66 的 UI 颜色也可以看看

上面三个问题已全部修复。

UI颜色：通过钩子设置的低费显示为绿色已经生效（没有测试蓝色，但应该也行吧）。SetToFree设置的不会显示为0，也不会显示为绿色。升级的降费也不会显示为绿色（这可能真的需要绑定一个var）。

[BAKAOLC]

可能会大改部分逻辑来更准确实现颜色那块，这个先改为完成
/r set confirmed