[Feature] 希望增加Single Custom Target对药水的兼容以及更丰富的canTarget Context

[Carry332]

模块范围

Public API（公开 API）

动机 / 使用场景

能直接在药水中使用Single Custom Target。
根据玩家或卡牌来决定CanTarget.

方案设想

目前在药水中使用Single Custom Target无法投掷，而是显示饮用，传入OnUse的参数也是Player Self
希望能够做Potion的customtarget兼容，使SingleTarget类型的CustomTarget能够投掷。
同时，希望RegisterSingleTargetType中传入的canTarget能够接受一个Context，包含TargetCreature，使用Target的Player，Target的source，如来自哪个卡牌或药水。

替代方案

No response

其他补充

No response

[ritsukage-local-analyzer]

Warning

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

摘要

玩家希望在药水中使用 Custom Single Target 时触发投掷选目标流程，并希望 RegisterSingleTargetType 的 canTarget 谓词能接收更多来源上下文（使用者 Player、来源卡牌或药水）。当前的根因是 NPotionHolder.UsePotion() 的目标类型判断硬编码为仅 AnyEnemy / TargetedNoCreature，Custom 类型被漏判而走"饮用"分支。该特性请求技术上可行，但涉及两个独立子任务，建议拆分实现。

重点结论

• 简介：药水 TargetType 设为自定义单体目标类型时，UI 显示"饮用"而非"投掷"，OnUse 收到的 target 为玩家自身，无法选择其他生物。
• 可能原因：NPotionHolder.UsePotion()（游戏源码 NPotionHolder.cs:285）仅对 AnyEnemy 和 TargetedNoCreature 触发 TargetNode()，自定义类型绕过检查后直接以 Owner.Creature 入队；TargetNode() 的手柄分支（:309）也仅枚举 AnyEnemy/AnyPlayer，若强行进入会抛 ArgumentOutOfRangeException。
• 可能解决方案：
  1. 在 RitsuLib 中对 NPotionHolder.UsePotion() 打补丁，在 flag 计算前加入 CustomTargetTypeResolver.IsCustomSingleTargetType(targetType) 检查，命中时转入自定义的 TargetNode 流程。
  2. 为 RegisterSingleTargetType 新增接受来源上下文的重载（Func<Creature, Player, PotionModel?, bool> 或通用 TargetSource 对象），内部 Registry/Resolver 以可选参数形式向下传递，保持现有重载向后兼容。

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

问题描述

期望行为

• 药水将 TargetType 设为通过 CustomTargetType.RegisterSingleTargetType 注册的自定义类型后，在战斗中点击时应弹出投掷选目标 UI（与 AnyEnemy 药水一致），并将玩家选中的生物正确传入 OnUse(ctx, target)。
• canTarget 谓词应可按来源（是哪个卡牌还是哪个药水触发）区分可选目标集。

实际行为

• 药水显示"饮用"选项，点击后 OnUse 收到的 target 是玩家自身（Owner.Creature），无法瞄准其他生物。
• 若强行进入 TargetNode() 的手柄分支，switch 表达式对未知 TargetType 抛 ArgumentOutOfRangeException。

复现步骤

1. 使用 CustomTargetType.RegisterSingleTargetType(modId, stem, predicate) 注册自定义单体目标类型。
2. 实现一个 PotionModel，将 TargetType 属性返回上一步注册的值。
3. 在战斗中点击该药水 → 出现"饮用"菜单而非投掷选目标。
4. 选择使用 → OnUse 中 target 为 Owner.Creature（而非所选生物）。

环境与版本

来自 Issue 描述，无明确版本信息；但问题可在当前代码仓直接定位到游戏源码。

详细分析依据

根因一（主）：NPotionHolder.UsePotion() 对自定义类型的漏判

游戏源码 0.104.0/src/Core/Nodes/Potions/NPotionHolder.cs，第 283–296 行：

bool flag = ((targetType == TargetType.AnyEnemy
           || targetType == TargetType.TargetedNoCreature) ? true : false);
if (flag || Potion.Model.CanThrowAtAlly())
    await TargetNode(Potion.Model.TargetType);
else
    Potion.Model.EnqueueManualUse(Potion.Model.Owner.Creature);

flag 仅检查两个硬编码值，Custom Single Target 类型全部落入 else，以 Owner.Creature 作为 target 直接入队。这与报告者描述的"显示饮用 / target 是 Player Self"完全吻合。

根因二（次）：TargetNode() 手柄分支的 switch 不支持自定义类型

同文件第 307–316 行：

List<Creature> source = (targetType switch
{
    TargetType.AnyEnemy   => combatState.GetOpponentsOf(creature),
    TargetType.AnyPlayer  => combatState.GetTeammatesOf(creature),
    _ => throw new ArgumentOutOfRangeException(...)
}).Where(c => c.IsAlive).ToList();

即使 UsePotion() 被修复、进入 TargetNode()，手柄模式下遇到自定义类型也会直接抛异常。

现有基础支持

RitsuLib 已有以下补丁可复用：

• ActionTargetExtensionsIsSingleTargetCustomTargetTypePatch：IsSingleTarget() 已感知自定义类型，PotionModel.OnUseWrapper() 的 VFX 位置计算（:229）会自动正确。
• NControllerCardPlaySingleTargetingCustomTargetTypePatch：演示了如何在手柄路径中用 CustomTargetTypeResolver.TryIsAllowedSingleTarget 过滤候选生物，药水侧可照此实现。
• NPotionHolder._Ready 补丁已存在（ModRightClickPotionPatch），证明对 NPotionHolder 打补丁可行。

子请求二：更丰富的 canTarget 上下文

现有签名：Func<Creature, Player, bool>。

报告者希望谓词知道触发来源（来自哪个卡牌或药水），典型用例：同一个目标类型，从药水用时只选敌方，从卡牌打出时可选友方。

实现路径：

• 定义 record TargetSourceContext(Player Player, PotionModel? Potion, CardModel? Card) 或类似类型。
• 新增 RegisterSingleTargetType(..., Func<Creature, TargetSourceContext, bool>) 重载，内部 Registry 升级存储签名；现有 Func<Creature, bool> / Func<Creature, Player, bool> 重载包装成新签名后仍走同一路径。
• CustomTargetTypeRegistry.TryIsAllowedSingleTarget 增加可选 context 参数，从各调用点（NTargetManagerAllowedToTargetCreaturePatch、新的药水补丁等）传入。

反馈规范性提醒

维度	状态	说明
复现步骤	含糊	描述了现象，未提供最小复现代码片段
期望 / 实际	已提供	清晰说明了期望投掷 / 实际饮用的差异
环境与版本	缺失	未说明游戏版本与 RitsuLib 版本
日志 / 附件	缺失	无崩溃日志或截图
标题与背景	已提供	标题明确，范围合理

缺少最小复现代码和版本信息，但因问题可直接在源码层定位，不阻碍分析。如需维护者评估优先级，建议补充游戏 + RitsuLib 版本。

详细验证建议

• 在 NPotionHolder.UsePotion() 的 flag 计算之前插入 || CustomTargetTypeResolver.IsCustomSingleTargetType(targetType)，在沙盒中确认药水弹出投掷 UI。
• 在新的药水 TargetNode 补丁中，用 CustomTargetTypeResolver.TryIsAllowedSingleTarget 过滤候选生物，确认鼠标模式可选目标、OnUse 收到正确 target。
• 手柄模式下同步测试：不进入原 TargetNode() 的 switch，而是复用类似 NControllerCardPlaySingleTargetingCustomTargetTypePatch 的实现。
• 验证 VFX 抛瓶动画位置正确（依赖 IsSingleTarget() 返回 true，已有补丁覆盖）。
• 若追加子请求二，先确认 TargetSourceContext 设计在所有调用点（卡牌打出路径、药水路径）均可无破坏性传入，再发布 API。

风险与未决

• 子请求一修复只需在 RitsuLib 侧打补丁，风险低；子请求二涉及公开 API 签名变更，建议在 Discussion 中先对齐接口设计再实现。
• TargetNode() 在鼠标模式下通过 instance.SelectionFinished() 获得 Node，返回类型断言需覆盖自定义目标可能命中的所有节点类型（NCreature 足够，无需额外处理）。
• 报告者未说明是否需要"投掷失败/取消"的回退处理，建议与卡牌自定义目标路径保持一致（取消即 CancelPlayCard 等价操作）。

---

English translation

Summary

The reporter wants potions with a Custom Single Target type to show the throw/targeting UI (instead of the "drink" menu), and also wants the canTarget predicate in RegisterSingleTargetType to receive richer source context (the using Player, and the originating card or potion). The root cause is that NPotionHolder.UsePotion() hard-codes only AnyEnemy / TargetedNoCreature in its targeting-gate check; custom types fall through to the "drink" branch. Both sub-requests are technically feasible and should be implemented as separate tasks.

Key Takeaways

• Problem: When a potion's TargetType is a custom single-target type registered via RegisterSingleTargetType, the UI shows "Drink" instead of "Throw", and OnUse receives Owner.Creature (the player's own character) as the target — no creature selection is possible.
• Likely cause: NPotionHolder.UsePotion() (game source NPotionHolder.cs:285) only triggers TargetNode() for AnyEnemy and TargetedNoCreature; custom types bypass the check and call EnqueueManualUse(Owner.Creature). Additionally, the controller branch inside TargetNode() (:309) enumerates only AnyEnemy/AnyPlayer in a switch expression that throws ArgumentOutOfRangeException for unknown types.
• Suggested fixes:
  1. Patch NPotionHolder.UsePotion() to also branch into TargetNode() when CustomTargetTypeResolver.IsCustomSingleTargetType(targetType) returns true, with a custom creature-filtering flow (mirroring NControllerCardPlaySingleTargetingCustomTargetTypePatch).
  2. Add new RegisterSingleTargetType overloads accepting a TargetSourceContext (or similar) that exposes the originating Player, PotionModel?, and CardModel?; wrap existing Func<Creature, bool> / Func<Creature, Player, bool> overloads for backward compatibility.

Expand detailed analysis, evidence, and verification

Problem Description

Expected Behavior

A potion whose TargetType is a custom single-target type should display a throw/targeting cursor on use (identical to AnyEnemy potions) and deliver the player-selected creature to OnUse(ctx, target) as the target argument.

The canTarget predicate registered with that type should optionally receive information about what triggered the selection (card vs. potion, and which specific instance) so a single type can behave differently in each context.

Actual Behavior

The potion shows a "Drink" popup. On confirmation, OnUse receives Owner.Creature (the player character) as the target. No creature targeting UI is shown.

Reproduction Steps

1. Register a custom single-target type: CustomTargetType.RegisterSingleTargetType(modId, stem, predicate).
2. Implement a PotionModel whose TargetType property returns the registered value.
3. During combat, click the potion → the "Drink / Discard" popup appears instead of a throwing cursor.
4. Click "Use" → OnUse receives Owner.Creature instead of any selected enemy.

Environment & Version

Not specified in the report. Game version and RitsuLib version were not provided; however the issue is traceable directly to game source and RitsuLib source code without version-specific ambiguity.

Detailed Analysis

Root cause 1 (primary): Hard-coded targeting gate in NPotionHolder.UsePotion()

Game source 0.104.0/src/Core/Nodes/Potions/NPotionHolder.cs, lines 283–296:

bool flag = ((targetType == TargetType.AnyEnemy
           || targetType == TargetType.TargetedNoCreature) ? true : false);
if (flag || Potion.Model.CanThrowAtAlly())
    await TargetNode(Potion.Model.TargetType);
else
    Potion.Model.EnqueueManualUse(Potion.Model.Owner.Creature);

Custom single-target types do not satisfy flag, so they fall into else and Owner.Creature is passed as target — perfectly matching the reporter's description ("shows Drink / target is Player Self").

Root cause 2 (secondary): TargetNode() controller branch throws on unknown type

Same file, lines 307–316:

List<Creature> source = (targetType switch
{
    TargetType.AnyEnemy  => combatState.GetOpponentsOf(creature),
    TargetType.AnyPlayer => combatState.GetTeammatesOf(creature),
    _ => throw new ArgumentOutOfRangeException(...)
}).Where(c => c.IsAlive).ToList();

Even if UsePotion() is fixed to enter TargetNode(), controller mode will immediately throw. A fully custom flow (not using this switch) is required.

Existing infrastructure that can be reused

• ActionTargetExtensionsIsSingleTargetCustomTargetTypePatch already makes IsSingleTarget() return true for registered custom types, so the VFX arc positioning in PotionModel.OnUseWrapper() (:229) will work correctly once targeting is triggered.
• NControllerCardPlaySingleTargetingCustomTargetTypePatch shows how to filter creature candidates with CustomTargetTypeResolver.TryIsAllowedSingleTarget in the controller path; the potion-side implementation can mirror this.
• ModRightClickPotionPatch already patches NPotionHolder._Ready, confirming that patching NPotionHolder is viable in RitsuLib.

Sub-request 2: Richer canTarget context

Current signatures: Func<Creature, bool> and Func<Creature, Player, bool>.

The reporter wants the predicate to know the trigger source (card or potion), enabling a single registered target type to filter candidates differently depending on what triggered it. Implementation path:

• Define a context record such as record TargetSourceContext(Player Player, PotionModel? Potion, CardModel? Card).
• Add a new RegisterSingleTargetType(..., Func<Creature, TargetSourceContext, bool>) overload; existing two-parameter overloads wrap into this signature for backward compatibility.
• Thread the context through CustomTargetTypeRegistry.TryIsAllowedSingleTarget as an optional parameter, populated from each call site (card-play patches, the new potion patch).

Feedback Quality Notes

Dimension	Status	Note
Reproduction steps	Vague	Behavior described; no minimal code snippet provided
Expected / Actual	Provided	Clearly stated: "throw" expected, "drink" actual
Environment / Version	Missing	No game or RitsuLib version listed
Logs / Attachments	Missing	No crash log or screenshot
Title & Scope	Provided	Title is clear and scope is reasonable

The missing version info and reproduction snippet do not block analysis since the issue is directly traceable in source. For priority assessment, the reporter should add game + RitsuLib version.

Detailed Verification Checklist

• Insert || CustomTargetTypeResolver.IsCustomSingleTargetType(targetType) into the flag computation in NPotionHolder.UsePotion() (via Harmony patch); confirm that the potion shows a throw cursor in a sandbox build.
• In the new potion TargetNode patch, use CustomTargetTypeResolver.TryIsAllowedSingleTarget to filter candidate creatures; confirm mouse-mode targeting works and OnUse receives the correct creature.
• Test controller mode: bypass the original TargetNode() switch entirely; reuse the pattern from NControllerCardPlaySingleTargetingCustomTargetTypePatch.
• Verify VFX throw arc lands on the selected target (depends on IsSingleTarget() returning true — already patched).
• For sub-request 2: confirm the TargetSourceContext design can be threaded into all call sites (card-play path and potion path) without breaking existing Func<Creature, Player, bool> callers before publishing the new API.

Risks & Open Questions

• Sub-request 1 is a RitsuLib-side patch with low risk. Sub-request 2 is a public API change and should be design-reviewed (e.g., in a GitHub Discussion) before implementation.
• The TargetNode() mouse-mode path resolves SelectionFinished() to an NCreature node; no additional node-type handling is needed for the custom-target potion case.
• The reporter did not specify cancellation/fail behavior; recommend matching the existing card custom-target cancel path for consistency.

---

工具侧记录

• BAKAOLC/STS2-RitsuLib#63 · 退出码 0 · 进程 208.47s
• claude-sonnet-4-6 · API 206468ms · 19 轮 · ↓14 ↑10113 · 缓存读536016 写79799 · $0.7913
• MCP available: management tools exposed to Claude.

[BAKAOLC]

/r set wip p1