[Feature] 希望次要资源不足时不再只能是无法被打出

[moli-Mori]

模块范围

Public API（公开 API）

动机 / 使用场景

希望次要资源不足时，例如打出七星需要七个辉星，但是我只有六个，此时有可选项：七星不能被打出/可以打出七星，但是执行一个方法，作为透支费用的惩罚

方案设想

也许在通过SecondaryResource那些注册的时候就选择这个资源不足时，卡牌是无法被打出还是可以承受相应代价被打出

替代方案

No response

其他补充

当然，这个应该可以通过patch修改打出逻辑做到吧，而且方法也很多，只是想偷个小懒（）

[ritsukage-local-analyzer]

Warning

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

摘要

这个 issue 请求为次要资源费用增加“资源不足仍允许打出，并执行惩罚/透支逻辑”的公开 API。目前次要资源的必需费用会在资源不足时直接阻止 CanPlay；现有可选支付只能表达“够就支付并触发，不够也能打但不触发”。建议按向后兼容的 API 增强处理：默认继续阻止出牌，新增显式不足策略与提交阶段回调。

重点结论

项目	结论
简单介绍	用户希望同一种次要资源费用能在“不足时禁止出牌”和“不足时允许出牌但执行惩罚”之间选择。
可能原因	高置信：当前 RequiredCost/SecondaryCosts() 被设计为硬费用，CanPlay 与支付校验都会要求当前资源量不少于费用；SpendIfAvailable 是可选支付，不覆盖“短缺惩罚”的必需费用语义。
可能解决方案	新增不足支付策略，默认 BlockPlay；可考虑“资源定义默认策略 + 单个 card use 覆盖”的 API，并在 SpendResources/ledger 提交阶段触发带 shortfall 的惩罚回调。

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

问题描述

期望行为

• 对某些次要资源费用，当前值低于费用时卡牌仍可打出。
• 出牌成功后，框架能按短缺额或上下文执行一个方法，作为透支/惩罚成本。
• 报告者倾向于在注册 SecondaryResource 相关 API 时声明“不足时禁止”或“不足时允许并付出代价”。

实际行为

• 现有硬费用语义是资源不足即不可打出。
• 现有可选支付语义是“资源足够则支付并激活，不足则不支付但仍可打出”，不能直接表达“必需费用不足但仍激活惩罚逻辑”。

复现步骤

按报告者示例可归纳为：

1. 注册一个次要资源，例如“辉星”。
2. 给某张卡设置 7 点该资源费用。
3. 当前只有 6 点资源时尝试出牌。
4. 当前框架会把它视为不可支付；期望新增一种可配置路径，让它可出牌并执行短缺惩罚。

日志、附件与原文摘录

希望次要资源不足时，例如打出七星需要七个辉星，但是我只有六个，此时有可选项：七星不能被打出/可以打出七星，但是执行一个方法，作为透支费用的惩罚

要点：需求不是普通可选 kicker，而是“短缺时仍可通过并执行代价”的出牌策略。

详细分析依据

• SecondaryResourcePlayUseKind.RequiredCost 当前定义为必需支付，无法支付时卡牌不能打出；OptionalSpend 则是可支付才消耗并激活，否则仍可打出：src/Combat/SecondaryResources/SecondaryResourcePlayUses.cs:10。
• 支付行的 IsAffordable 要求 AmountAvailable >= Cost，CanPlay 对阻塞行要求 IsAffordable && CanSpend：src/Combat/SecondaryResources/SecondaryResourceCosts.cs:322。
• 整个 SecondaryResourcePaymentPlan.IsAffordable 要求每一行 CanPlay：src/Combat/SecondaryResources/SecondaryResourceCosts.cs:409。
• CardModel.CanPlay patch 在计划不可支付时设置 UnplayableReason.BlockedByCardLogic 并返回 false：src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:33。
• 支付提交阶段也会拒绝不可打出的支付行，并调用 SpendResolvedCardPayment 消耗资源：src/Combat/SecondaryResources/SecondaryResourceCosts.cs:517。
• SecondaryResourceCmd.Spend 与内部 SpendCore 都有当前值小于消耗量时返回 false 的保护：src/Combat/SecondaryResources/SecondaryResourceCmd.cs:114、src/Combat/SecondaryResources/SecondaryResourceCmd.cs:155。因此仅把资源 MinAmount 设为负数，不能自动支持透支支付。
• 文档也明确当前行为：无法支付全部有效次级费用时，CanPlay 自动失败；可选支付永远不会阻止 CanPlay，不足时只是不会激活 ledger 行：docs/pages/guide/secondary-resources.md:203。

可行设计方向：

• 保持现有默认行为不变，避免破坏已有 mod 对硬费用的预期。
• 新增类似 SecondaryResourceInsufficientPaymentPolicy 的策略：例如 BlockPlay（默认）、AllowPlayWithShortfallCallback，必要时再区分是否消耗现有资源、是否允许写入负值。
• 策略位置建议不要只放在资源定义上：同一种资源可能在一张卡上是硬费用，在另一张卡上是可透支费用。较稳妥的 API 是“资源定义提供默认策略，SecondaryResourcePlayUse/card use 可覆盖”。
• 惩罚方法应尽量在提交阶段执行，而不是 CanPlay 查询阶段执行；CanPlay 可能被 UI 高频调用，不能有副作用。提交阶段可通过 ledger 记录 Shortfall、AmountAvailable、Cost、UseId，再触发 hook/callback。
• UI 需要同步表达“资源不足但策略允许出牌”，否则费用颜色仍可能让玩家误判为不可打出。

详细验证建议

• 保持默认 SecondaryCosts().Set(resource, 7) 在当前资源为 6 时仍不可打出，确认兼容旧行为。
• 新增允许短缺策略后，用 6/7 的场景确认 CanPlay 返回 true，且惩罚回调不会在 UI 预览/多次 CanPlay 查询时触发。
• 出牌提交后确认惩罚回调只执行一次，并能拿到 shortfall = 1、卡牌、玩家、资源、use id 等上下文。
• 验证可选支付 SpendIfAvailable 的旧语义不变：不足时不激活、不阻止出牌、不触发短缺惩罚。
• 验证 free play、auto-play、X 次要资源费用、多个次要资源费用并存时的 ledger 与 UI 状态。

风险与未决

• 需要决定策略粒度：只按资源注册配置会简单，但可能限制同一资源在不同卡上的不同语义；按 use/card 覆盖更灵活。
• 惩罚回调若允许修改资源、抽牌、造成伤害等副作用，必须限定在提交阶段并保证多人/回放状态一致。
• 若支持真正负债式透支，需要同时调整 SpendCore 的不足保护与资源下限策略；若只是“短缺惩罚”，则可避免改动底层资源扣减规则。
• 费用 UI、手牌描边/发光规则可能需要新增一种“资源不足但可打出”的表现，避免与普通不可支付红色状态混淆。

---

English translation

Summary

This issue requests a public API that lets secondary-resource costs remain playable when the resource is short, then run a penalty or overdraft action. Today, required secondary-resource costs directly block CanPlay when unaffordable; optional spends only cover “pay and activate if enough, otherwise still play but do nothing.” The recommended handling is a backward-compatible API enhancement: keep blocking as the default, and add an explicit insufficient-payment policy plus a commit-stage callback.

Key Takeaways

Item	Conclusion
Brief introduction	The user wants the same kind of secondary-resource cost to choose between “block play when short” and “allow play when short, but execute a penalty.”
Likely cause	High confidence: current RequiredCost/SecondaryCosts() semantics are hard costs, so both CanPlay and payment validation require the current resource amount to be at least the cost; SpendIfAvailable is optional payment and does not cover “required cost with shortfall penalty.”
Possible solution	Add an insufficient-payment policy with default BlockPlay; consider a “resource definition default + individual card use override” API, and trigger a shortfall-aware penalty callback during SpendResources/ledger commit.

Expand detailed analysis, evidence, and verification

Problem description

Expected behavior

• For selected secondary-resource costs, a card can still be played when the current amount is lower than the cost.
• After the successful play, the framework can run a method based on the shortfall or play context as the overdraft/penalty cost.
• The reporter suggests declaring whether shortage blocks play or allows play with a penalty when registering the SecondaryResource-related API.

Actual behavior

• Current hard-cost semantics make the card unplayable when the resource is insufficient.
• Current optional-payment semantics are “pay and activate if enough; otherwise do not pay but still play,” which does not directly express “required cost is short, but still activate penalty logic.”

Reproduction steps

The reporter’s example can be reduced to:

1. Register a secondary resource, such as “Starlight.”
2. Give a card a 7-point cost in that resource.
3. Try to play the card while the current amount is 6.
4. The current framework treats it as unaffordable; the requested API would allow a configurable path where the card is playable and a shortfall penalty runs.

Logs, attachments, and source excerpts

希望次要资源不足时，例如打出七星需要七个辉星，但是我只有六个，此时有可选项：七星不能被打出/可以打出七星，但是执行一个方法，作为透支费用的惩罚

Key point: this is not a normal optional kicker; it is a play policy where shortage can still pass and execute a cost/penalty.

Detailed analysis basis

• SecondaryResourcePlayUseKind.RequiredCost is currently defined as required payment that prevents play when unaffordable; OptionalSpend only spends and activates if payable, otherwise the card still plays: src/Combat/SecondaryResources/SecondaryResourcePlayUses.cs:10.
• A payment line’s IsAffordable requires AmountAvailable >= Cost, and CanPlay requires IsAffordable && CanSpend for blocking lines: src/Combat/SecondaryResources/SecondaryResourceCosts.cs:322.
• The whole SecondaryResourcePaymentPlan.IsAffordable requires every line to CanPlay: src/Combat/SecondaryResources/SecondaryResourceCosts.cs:409.
• The CardModel.CanPlay patch sets UnplayableReason.BlockedByCardLogic and returns false when the plan is unaffordable: src/Combat/SecondaryResources/Patches/SecondaryResourceCardPatches.cs:33.
• The payment commit stage also rejects unplayable lines and calls SpendResolvedCardPayment to spend resources: src/Combat/SecondaryResources/SecondaryResourceCosts.cs:517.
• SecondaryResourceCmd.Spend and internal SpendCore both return false when the current value is below the spend amount: src/Combat/SecondaryResources/SecondaryResourceCmd.cs:114, src/Combat/SecondaryResources/SecondaryResourceCmd.cs:155. Therefore, setting a negative MinAmount alone would not automatically support overdraft spending.
• The documentation states the current behavior: if the player cannot pay all material secondary costs, CanPlay fails automatically; optional spends never block CanPlay and simply leave the ledger line inactive when short: docs/pages/guide/secondary-resources.md:203.

Possible design direction:

• Preserve the existing default behavior to avoid breaking mods that rely on hard secondary-resource costs.
• Add a policy such as SecondaryResourceInsufficientPaymentPolicy: for example, BlockPlay by default and AllowPlayWithShortfallCallback; if needed, further distinguish whether to spend available resources or allow a negative balance.
• The policy should probably not live only on the resource definition: the same resource may be a hard cost on one card and an overdraftable cost on another. A safer API is “resource definition provides the default, SecondaryResourcePlayUse/card use can override it.”
• The penalty method should run during commit, not during CanPlay; CanPlay can be called frequently by UI and must not have side effects. Commit can record Shortfall, AmountAvailable, Cost, and UseId in the ledger before triggering a hook/callback.
• UI should also represent “insufficient but playable by policy,” otherwise cost coloring may still look indistinguishable from a normal unplayable shortage.

Detailed verification suggestions

• Keep the default SecondaryCosts().Set(resource, 7) behavior unchanged: with 6 current resource, the card remains unplayable.
• After adding an allow-shortfall policy, verify that the 6/7 case makes CanPlay return true and that the penalty callback does not fire during UI preview or repeated CanPlay queries.
• After play commit, verify the penalty callback runs exactly once and receives context such as shortfall = 1, card, player, resource, and use id.
• Verify old SpendIfAvailable semantics remain unchanged: when short, it does not activate, does not block play, and does not trigger shortfall penalty.
• Verify ledger and UI state for free play, auto-play, X secondary-resource costs, and multiple secondary-resource costs on the same card.

Risks and open questions

• Policy granularity must be decided: resource-level registration is simpler but may prevent different cards from using the same resource with different meanings; per-use/card override is more flexible.
• If penalty callbacks can modify resources, draw cards, deal damage, or perform other side effects, they must be limited to the commit stage and remain deterministic for multiplayer/replay state.
• If true negative-balance overdraft is supported, SpendCore’s insufficient-resource guard and resource lower-bound rules must also change; if the feature is only “shortfall penalty,” lower-level spend rules may remain unchanged.
• Cost UI and hand outline/glow rules may need a new “insufficient but playable” presentation to avoid confusion with ordinary unaffordable red states.

---

工具侧记录

• BAKAOLC/STS2-RitsuLib#69 · 退出码 0 · 进程 273.71s
• gpt-5.5(high) · API 272670ms · 15 轮 · ↓59285 ↑7136 · 缓存读202240 写0 · $0.5759
• MCP available: management tools exposed to Claude.

[BAKAOLC]

/r set p2 wip

[BAKAOLC]

/r set review
大概的设计和功能已经放置于 Dev 分支