[Bug] 有可选的次要资源消耗的卡牌，在本回合被设为免费，过回合后，不会使它恢复原价

[iouter]

模块范围

Public API（公开 API）

严重程度

Minor（轻微）

发生了什么？

有可选的次要资源消耗的卡牌，在本回合被设为免费（SetToFreeThisTurn()），过回合后，不会使次要资源消耗恢复原价

复现步骤

打出一张被SetToFreeThisTurn()，有可选的次要资源消耗的卡牌

期望行为

过回合后，次要资源消耗应恢复原价

日志 / 堆栈

RitsuLib 版本

0.4.38

运行环境

No response

[ritsukage-local-analyzer]

Warning

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

摘要

SetToFreeThisTurn() 目前会把卡牌登记为“下一次打出免费”，但该登记没有随回合结束清理；如果卡牌当回合未被打出，次回合仍会让次要资源支付计划按免费处理。影响主要集中在带可选/额外次要资源消耗的卡牌：显示与实际结算都可能继续按 0 次要资源处理，严重度符合 minor，但属于可复现的状态生命周期问题。

建议在 free-play 绑定层补齐“本回合或打出前”生命周期，或在 CardModel.EndOfTurnCleanup 补充清除未消费的 SetToFreeThisTurn 次要资源免费标记，并加入回归测试覆盖可选支付场景。

重点结论

项目	结论
简单介绍	带可选次要资源消耗的卡牌被 SetToFreeThisTurn() 设为免费后，跨回合仍被 RitsuLib 次要资源系统视为免费。
可能原因	高置信：SetToFreeThisTurn() 的绑定使用 MarkCardFreeNextPlay，只按“下一次打出”消费，没有回合结束过期；RitsuLib 的回合清理只清 SecondaryResourceCostDuration.ThisTurn 成本层。
可能解决方案	将 SetToFreeThisTurn 标记改为随回合结束或打出前过期；在结束回合清理时同步刷新卡牌次要资源 UI，并增加未打出跨回合恢复原价的测试。
需要补充	若要精确复现 UI 表现，建议补充具体测试卡/资源定义、是否当回合未打出、以及截图或最小 mod 片段。

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

问题描述

期望行为

• SetToFreeThisTurn() 只应影响当前回合；回合结束后，可选次要资源消耗应恢复到原始费用。

实际行为

• 报告称：有可选次要资源消耗的卡牌本回合被 SetToFreeThisTurn() 设为免费后，过回合不会恢复次要资源原价。

复现步骤

1. 准备一张带可选次要资源消耗的卡牌。
2. 在当前回合对该卡调用 SetToFreeThisTurn()。
3. 结束回合后再次查看/尝试打出该卡。
4. 观察可选次要资源消耗是否仍按免费显示或结算。

环境与版本

• RitsuLib 版本：0.4.38
• 模块范围：Public API
• 运行环境：未提供

日志、附件与原文摘录

• 原文：有可选的次要资源消耗的卡牌，在本回合被设为免费（SetToFreeThisTurn()），过回合后，不会使次要资源消耗恢复原价
  • 要点：问题聚焦于 SetToFreeThisTurn() 与可选次要资源费用的生命周期不一致。
• 日志区为空，未提供堆栈或截图。

详细分析依据

• src/Cards/FreePlay/Patches/FreePlayBindingPatches.cs:20 将 CardModel.SetToFreeThisTurn 作为补丁目标，src/Cards/FreePlay/Patches/FreePlayBindingPatches.cs:23-src/Cards/FreePlay/Patches/FreePlayBindingPatches.cs:26 在 postfix 中调用 FreePlayBindingRegistry.MarkCardFreeNextPlay(__instance) 并刷新视觉。
• src/Cards/FreePlay/FreePlayBindingRegistry.cs:73-src/Cards/FreePlay/FreePlayBindingRegistry.cs:80 的 MarkCardFreeNextPlay 仅增加 NextPlayCharges；src/Cards/FreePlay/FreePlayBindingRegistry.cs:194-src/Cards/FreePlay/FreePlayBindingRegistry.cs:211 只有在解析一次 CardPlay 时才消费该 charge。未看到对应的回合结束清理入口。
• 次要资源的可打出检查、支付计划和 UI 均依赖 FreePlayBindingRegistry.IsCardFreeForUpcomingPlay(card)：见 src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:40-src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:42、src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:71-src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:74、src/Combat/SecondaryResources/SecondaryResourceUi.cs:220-src/Combat/SecondaryResources/SecondaryResourceUi.cs:225。因此未过期的 free marker 会同时影响 UI、可打出判断和支付提交。
• RitsuLib 已有回合清理补丁 CardModelEndOfTurnSecondaryResourcesPatch，但 src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:186-src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:189 只调用 ClearSecondaryCostsThisTurn()；该方法在 src/Combat/SecondaryResources/SecondaryResourceCosts.cs:339-src/Combat/SecondaryResources/SecondaryResourceCosts.cs:343 只清理次要资源成本/用途的 ThisTurn duration，不会清除 FreePlayBindingRegistry 的 NextPlayCharges。
• 游戏侧 SetToFreeThisTurn() 对能量/星星费用使用的是“回合结束或打出后”过期语义：0.104.0/src/Core/Models/CardModel.cs:970-0.104.0/src/Core/Models/CardModel.cs:974 调用 EnergyCost.SetThisTurnOrUntilPlayed(0) 和 SetStarCostThisTurn(0)；0.104.0/src/Core/Entities/Cards/CardEnergyCost.cs:111-0.104.0/src/Core/Entities/Cards/CardEnergyCost.cs:116 将能量 modifier 标记为 EndOfTurn | WhenPlayed；0.104.0/src/Core/Models/CardModel.cs:1258-0.104.0/src/Core/Models/CardModel.cs:1270 在 EndOfTurnCleanup() 中移除这些本回合临时费用。RitsuLib 当前将其映射成“下一次出牌免费”，与原生语义存在偏差。
• 可选费用在免费计划中确实会被降为 0：src/Combat/SecondaryResources/SecondaryResourceCosts.cs:843-src/Combat/SecondaryResources/SecondaryResourceCosts.cs:846 的预览分支在 isFree 时使用 displayCost = 0，src/Combat/SecondaryResources/SecondaryResourceCosts.cs:912-src/Combat/SecondaryResources/SecondaryResourceCosts.cs:983 的实际解析分支也会在 isFree 时令 AmountToSpend 为 0。由此可解释“过回合仍未恢复原价”的表现。

反馈规范性提醒

维度	状态
复现步骤	含糊：给出了核心动作，但未说明是否当回合不打出、使用哪张测试卡或资源定义。
期望/实际	已提供：期望回合后恢复原价，实际未恢复。
环境与版本	含糊：提供 RitsuLib 0.4.38，运行环境为 _No response_。
日志/附件	缺失：日志块为空，未附截图或最小 mod 片段。
标题与背景	已提供：标题与正文范围一致，指向 SetToFreeThisTurn() 与可选次要资源消耗。

详细验证建议

• 用一张固定可选次要资源消耗的测试卡，在 0.4.38 中调用 SetToFreeThisTurn() 后不打出，执行 EndOfTurnCleanup()，断言 FreePlayBindingRegistry.IsCardFreeForUpcomingPlay(card) 变为 false。
• 同一场景下重新解析 SecondaryResourcePaymentResolver.Plan(card, ...)，断言可选支付行的 Cost/Value 恢复为原始费用、AmountToSpend 不再因 free marker 固定为 0。
• 覆盖“当回合打出”路径：免费 ledger 应只对本次打出有效，且不会重复影响下一次打出。
• 覆盖 SetToFreeThisCombat() 路径，确认修复不会误清整场战斗免费的语义。
• 修复后确认 UI 刷新：回合结束清除标记后，手牌/桌面卡牌的次要资源成本显示应同步恢复。

风险与未决

• 修复点若只在次要资源补丁中清理，需避免破坏 SetToFreeThisCombat() 和自动出牌 CommitFree 的 ledger 行为。
• FreePlayBindingRegistry 当前命名为 NextPlayCharges，可能还被用于“下一次出牌免费”的语义；建议区分 ThisTurnOrNextPlay 与真正的 NextPlay，避免未来 API 误用。
• 仍需确认报告者的具体流程是否为“设为免费后未打出即过回合”；若是打出后仍残留，则还要检查 pending ledger/UI 刷新路径。

---

English translation

Summary

SetToFreeThisTurn() currently registers the card as “free on the next play,” but that registration is not cleared at end of turn; if the card is not played that turn, the next turn still treats its secondary-resource payment plan as free. The impact is concentrated on cards with optional or extra secondary-resource spends: display and actual payment can continue to use 0 secondary resources, so the severity fits minor but this is a reproducible state-lifetime bug.

The recommended fix is to make the free-play binding honor a “this turn or until played” lifetime, or clear the unconsumed SetToFreeThisTurn secondary-resource free marker during CardModel.EndOfTurnCleanup, with regression tests for optional payment cases.

Key Takeaways

Item	Conclusion
Brief description	A card with optional secondary-resource spend remains treated as free by RitsuLib’s secondary-resource system after SetToFreeThisTurn() crosses a turn boundary.
Likely cause	High confidence: the SetToFreeThisTurn() binding uses MarkCardFreeNextPlay, which is consumed only by the next play and does not expire at end of turn; RitsuLib’s turn cleanup only clears SecondaryResourceCostDuration.ThisTurn cost layers.
Possible fix	Change the SetToFreeThisTurn marker to expire at end of turn or before play; refresh secondary-resource card UI after end-turn cleanup; add a test that verifies an unplayed card restores its original optional cost next turn.
More info needed	To reproduce the exact UI behavior, it would help to provide the concrete test card/resource definition, whether the card is left unplayed during that turn, and a screenshot or minimal mod snippet.

Expand detailed analysis, evidence, and verification

Problem Description

Expected Behavior

• SetToFreeThisTurn() should affect only the current turn; after the turn ends, optional secondary-resource spend should return to its original cost.

Actual Behavior

• The report says that after a card with optional secondary-resource spend is made free by SetToFreeThisTurn(), ending the turn does not restore the secondary-resource cost.

Reproduction Steps

1. Prepare a card with optional secondary-resource spend.
2. Call SetToFreeThisTurn() on that card during the current turn.
3. End the turn, then inspect or attempt to play the card again.
4. Check whether the optional secondary-resource spend is still displayed or resolved as free.

Environment and Version

• RitsuLib version: 0.4.38
• Module scope: Public API
• Runtime environment: not provided

Logs, Attachments, and Original Excerpts

• Original: 有可选的次要资源消耗的卡牌，在本回合被设为免费（SetToFreeThisTurn()），过回合后，不会使次要资源消耗恢复原价
  • Key point: the issue is about a lifecycle mismatch between SetToFreeThisTurn() and optional secondary-resource costs.
• The log block is empty; no stack trace or screenshot was provided.

Detailed Analysis Basis

• src/Cards/FreePlay/Patches/FreePlayBindingPatches.cs:20 targets CardModel.SetToFreeThisTurn, and src/Cards/FreePlay/Patches/FreePlayBindingPatches.cs:23-src/Cards/FreePlay/Patches/FreePlayBindingPatches.cs:26 calls FreePlayBindingRegistry.MarkCardFreeNextPlay(__instance) in the postfix and refreshes visuals.
• MarkCardFreeNextPlay at src/Cards/FreePlay/FreePlayBindingRegistry.cs:73-src/Cards/FreePlay/FreePlayBindingRegistry.cs:80 only increments NextPlayCharges; src/Cards/FreePlay/FreePlayBindingRegistry.cs:194-src/Cards/FreePlay/FreePlayBindingRegistry.cs:211 consumes that charge only when a CardPlay is resolved. No corresponding end-of-turn cleanup entry point was found.
• Secondary-resource playability, payment planning, and UI all depend on FreePlayBindingRegistry.IsCardFreeForUpcomingPlay(card): see src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:40-src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:42, src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:71-src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:74, and src/Combat/SecondaryResources/SecondaryResourceUi.cs:220-src/Combat/SecondaryResources/SecondaryResourceUi.cs:225. Therefore an unexpired free marker affects UI, playability, and payment commit together.
• RitsuLib already has an end-turn card cleanup patch, but src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:186-src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:189 only calls ClearSecondaryCostsThisTurn(). That method, at src/Combat/SecondaryResources/SecondaryResourceCosts.cs:339-src/Combat/SecondaryResources/SecondaryResourceCosts.cs:343, clears secondary-resource costs/uses with ThisTurn duration only; it does not clear FreePlayBindingRegistry’s NextPlayCharges.
• On the game side, SetToFreeThisTurn() uses “end of turn or until played” semantics for energy and star costs: 0.104.0/src/Core/Models/CardModel.cs:970-0.104.0/src/Core/Models/CardModel.cs:974 calls EnergyCost.SetThisTurnOrUntilPlayed(0) and SetStarCostThisTurn(0); 0.104.0/src/Core/Entities/Cards/CardEnergyCost.cs:111-0.104.0/src/Core/Entities/Cards/CardEnergyCost.cs:116 marks the energy modifier as EndOfTurn | WhenPlayed; 0.104.0/src/Core/Models/CardModel.cs:1258-0.104.0/src/Core/Models/CardModel.cs:1270 removes these temporary costs in EndOfTurnCleanup(). RitsuLib’s current mapping to “free on next play” diverges from that native behavior.
• Optional costs are indeed reduced to 0 in a free plan: the preview branch at src/Combat/SecondaryResources/SecondaryResourceCosts.cs:843-src/Combat/SecondaryResources/SecondaryResourceCosts.cs:846 uses displayCost = 0 when isFree; the runtime resolution branch at src/Combat/SecondaryResources/SecondaryResourceCosts.cs:912-src/Combat/SecondaryResources/SecondaryResourceCosts.cs:983 also makes AmountToSpend 0 when isFree. This explains why the cost can appear not to return to its original value after the turn changes.

Feedback Quality Reminder

Dimension	Status
Reproduction steps	Ambiguous: the core action is provided, but it does not name the test card/resource definition or explicitly say whether the card is left unplayed that turn.
Expected/actual	Provided: expected cost restoration after the turn, actual non-restoration.
Environment and version	Ambiguous: RitsuLib 0.4.38 is provided, but runtime environment is _No response_.
Logs/attachments	Missing: the log block is empty and no screenshot or minimal mod snippet is attached.
Title and background	Provided: the title and body are consistent and point to SetToFreeThisTurn() with optional secondary-resource spend.

Detailed Verification Suggestions

• With a fixed test card that has optional secondary-resource spend, call SetToFreeThisTurn() in 0.4.38, do not play the card, run EndOfTurnCleanup(), and assert that FreePlayBindingRegistry.IsCardFreeForUpcomingPlay(card) becomes false.
• In the same scenario, resolve SecondaryResourcePaymentResolver.Plan(card, ...) again and assert that the optional payment line’s Cost/Value returns to the original cost and AmountToSpend is no longer forced to 0 by the free marker.
• Cover the “played in the same turn” path: the free ledger should apply only to that play and should not affect the next play again.
• Cover the SetToFreeThisCombat() path to ensure the fix does not accidentally clear combat-long free semantics.
• After the fix, verify UI refresh: once the marker is cleared at end of turn, secondary-resource cost display on hand/table cards should update back to the original cost.

Risks and Open Questions

• If the fix clears the marker only inside the secondary-resource patch, it must not break SetToFreeThisCombat() or auto-play CommitFree ledger behavior.
• FreePlayBindingRegistry currently names this state NextPlayCharges, which may also imply a true “next play is free” semantic; consider separating ThisTurnOrNextPlay from true NextPlay to prevent future API confusion.
• The reporter’s exact flow still needs confirmation: if the card was made free and left unplayed before ending the turn, the lifecycle bug above is the likely cause; if it was played and still left residue, pending ledger/UI refresh paths should also be checked.

---

工具侧记录

• BAKAOLC/STS2-RitsuLib#71 · 退出码 0 · 进程 341.49s
• gpt-5.5(high) · API 340524ms · 27 轮 · ↓68002 ↑8558 · 缓存读426496 写0 · $0.7672
• MCP available: management tools exposed to Claude.

[BAKAOLC]

最新的 devbuild 应该已解决，还有问题的话欢迎随时反馈

[iouter]

已修复