[Bug] ModSecondaryResourceRegistry.AlwaysShowInCombatUiForCharacter()無效

[C-W-Z]

模块范围

Public API（公开 API）

严重程度

Broken feature（功能不可用）

发生了什么？

ModSecondaryResourceRegistry中的AlwaysShowInCombatUiForCharacter()和RegisterCombatUiAlwaysVisibleWhen()都沒有效果

我看了原始碼AlwaysShowInCombatUiForCharacter()是調用RegisterCombatUiAlwaysVisibleWhen()於是我直接設定registry.RegisterCombatUiAlwaysVisibleWhen(ManaDefinition.LocalId, _ => false);測試，結果也還是會在遊玩任何角色時顯示(即使此次級資源數量是0)

复现步骤

我按照此次級資源教學撰寫了以下程式碼。

public static class ExEnergyManager
{
    public static SecondaryResourceDefinition ManaDefinition { get; private set; } = null!;
    public static string ManaId { get; private set; } = string.Empty;
    public static void Register()
    {
        var registry = RitsuLibFramework.GetSecondaryResourceRegistry(Entry.ModId);

        ManaDefinition = registry.Register("mana", new SecondaryResourceDefinition(
            defaultAmount: 0,
            baseMaxAmount: 100,
            turnStartPolicy: SecondaryResourceTurnStartPolicy.None,
            persistencePolicy: SecondaryResourcePersistencePolicy.Run,
            smallIconPath: "res://...png",
            largeIconPath: "res://...png"
        ));
        ManaId = ManaDefinition.Id;

        // 就算直接寫false也還是會在所有角色顯示
        registry.RegisterCombatUiAlwaysVisibleWhen(ManaDefinition.LocalId, _ => false);

        registry.RegisterCombatUi(
            "mana_combat_ui",
            parent =>
            {
                var row = NSecondaryResourceCounter.Create(ManaDefinition, SecondaryResourceCounterStyle.Default);
                var energyCounter = parent.GetNode<Control>("%EnergyCounterContainer");
                row.Position = energyCounter.Position + new Vector2(-80, -120);
                return row;
            },
            ctx => ctx.Node.Bind(ctx.Player)
        );
    }
}

期望行为

會錯誤地在任何角色戰鬥時顯示次級資源圖標和Counter在能量圖標的左上方。

日志 / 堆栈

RitsuLib 版本

0.4.20

运行环境

Windows 11, STS2 0.107.0

[ritsukage-local-analyzer]

Warning

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

摘要

RegisterCombatUiAlwaysVisibleWhen / AlwaysShowInCombatUiForCharacter 的谓词逻辑本身是正确的，问题在于 RegisterCombatUi 注册的更新回调始终被调用，框架不会根据可见性谓词自动隐藏节点；而教程示例回调 ctx => ctx.Node.Bind(ctx.Player) 会触发 NSecondaryResourceCounter.Refresh() 无条件将节点 Visible 置为 true，可见性谓词的结果从未被消费。严重程度较高，属于框架层面的设计缺口，建议在 RegisterCombatUi 内包裹更新回调以自动检查可见性。

重点结论

项目	内容
简单介绍	次级资源战斗 UI 注册时，可见性谓词（RegisterCombatUiAlwaysVisibleWhen）只影响上下文中的 VisibleDefinitions 字段，不会阻止更新回调被调用，导致资源图标始终显示。
可能原因	① RegisterCombatUpdater 每次 combat update 均无条件调用 update(ctx)，即使该资源不在 VisibleDefinitions 中；② NSecondaryResourceCounter.Refresh() 在 player != null 时无条件执行 Visible = true（见 SecondaryResourceCounterNodes.cs:284），从不查询可见性谓词。
可能解决方案	① （推荐）在 ModSecondaryResourceRegistry.RegisterCombatUi（SecondaryResourceUi.cs ~L255）中包裹 update 调用：若 localId 对应的定义不在 VisibleDefinitions 中，则先 HideNode(node) 再跳过回调；② 作为补充，可在 NSecondaryResourceCounter.Refresh() 中调用 _definition.IsVisibleInCombatUi(player) 替代无条件 Visible = true。

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

问题描述

期望行为

调用 AlwaysShowInCombatUiForCharacter<T>() 后，仅当玩家角色类型匹配时战斗 UI 才显示；未调用任何"始终显示"谓词、且数量为 0 时不显示。

实际行为

不论谓词结果如何，次级资源战斗 UI 在进入任意角色的战斗时始终可见，哪怕数量为 0、且已注册 _ => false 的测试谓词。

复现步骤

1. 按教程注册次级资源，defaultAmount: 0
2. 调用 registry.RegisterCombatUiAlwaysVisibleWhen(ManaDefinition.LocalId, _ => false) 作为测试
3. 调用 registry.RegisterCombatUi(...) 传入回调 ctx => ctx.Node.Bind(ctx.Player)
4. 进入任意角色的战斗 → 资源图标仍然显示

环境与版本

报告者未填写 RitsuLib 版本与运行环境。

详细分析依据

谓词存储（正确）

ModSecondaryResourceRegistry.RegisterCombatUiAlwaysVisibleWhen（ModSecondaryResourceRegistry.cs:171）将谓词以 resourceId（GetResourceId(_modId, localId) 的结果）为键存入静态字典 CombatUiVisibilityPredicates，顺序排列后备查。

可见性判断（正确）

SecondaryResourceVisibility.IsVisibleInCombatUi（SecondaryResourceVisibility.cs:56）：

if (ModSecondaryResourceRegistry.GetCombatUiVisibilityPredicates(definition.Id)
    .Any(predicate => predicate(context)))
    return true;
return context.Amount > definition.DefaultAmount;

以 _ => false 测试时：Any(...) 为 false；Amount(0) > DefaultAmount(0) 也为 false，故该定义不会出现在 GetCombatUiDefinitions(player) 返回的 VisibleDefinitions 列表中。

更新回调（缺口所在）

SecondaryResourceUiRuntime.RegisterCombatUpdater（SecondaryResourceUi.cs:157）注册的 updater lambda：

CombatUpdaters.GetOrCreate(parent).Add(player =>
{
    var definitions = ModSecondaryResourceRegistry.GetDefinitionsSnapshot();
    update(new(
        parent, node, player,
        definitions,
        SecondaryResourceVisibility.GetCombatUiDefinitions(player)));   // ← VisibleDefinitions
});

update 始终被调用，VisibleDefinitions 只是被传递到上下文中，框架不检查当前节点对应的定义是否在其中。

NSecondaryResourceCounter.Refresh（次级缺口）

SecondaryResourceCounterNodes.cs:276：

public void Refresh(Player? player)
{
    if (_definition == null || player == null) { Visible = false; return; }
    Visible = true;   // ← 无条件设为 true，从不查询可见性谓词
    SetAmount(...);
}

教程回调 ctx => ctx.Node.Bind(ctx.Player) 最终调用此方法，节点始终可见。

NSecondaryResourceCounterRow（对比，行为正确）

NSecondaryResourceCounterRow.Refresh(player, visibleDefinitions) 仅显示 visibleDefinitions 中包含的定义对应计数器，能正确响应可见性，但教程示例未使用此类型。

修复建议（代码层面）

在 ModSecondaryResourceRegistry.RegisterCombatUi（SecondaryResourceUi.cs:244）的 setup lambda 中，将 RegisterCombatUpdater 调用改为包裹可见性检查：

(parent, node) =>
{
    var resourceId = GetResourceId(_modId, localId);
    SecondaryResourceUiRuntime.RegisterCombatUpdater(parent, node, ctx =>
    {
        if (ctx.Player == null ||
            !ctx.VisibleDefinitions.Any(d => d.Id == resourceId))
        {
            if (node is CanvasItem ci) ci.Visible = false;
            return;
        }
        update(ctx);
    });
    SecondaryResourceUiRuntime.HideCombatUi(parent);
}

这样现有教程示例 ctx => ctx.Node.Bind(ctx.Player) 无需修改即可正常工作。

反馈规范性提醒

字段	状态
复现步骤	已提供（含代码）
期望 / 实际	实际已描述；期望为"No response"，但可从语境推断
环境与版本	缺失：RitsuLib 版本及运行环境均未填写
日志 / 附件	空 shell 块，可接受（逻辑 bug，无崩溃）

建议后续提供 RitsuLib 版本号，以便确认修复版本覆盖范围。

详细验证建议

• 在 SecondaryResourceVisibility.IsVisibleInCombatUi 设断点/日志，确认 _ => false 谓词时返回 false
• 跟踪 NCombatUi.Activate postfix → UpdateCombatUi → updater(player) → update(ctx) 调用链，确认回调确实在 VisibleDefinitions 为空时仍被调用
• 在 NSecondaryResourceCounter.Refresh 加日志确认 Visible = true 的执行路径
• 应用推荐修复后，测试 _ => false 谓词能否阻止显示；测试 ctx => characterType.IsInstanceOfType(ctx.Player.Character) 谓词能否按角色类型正确过滤

风险与未决

• 若有 mod 已依赖"回调始终被调用"的现有行为，框架层修复可能造成不兼容；需在 changelog 中标注
• 报告者未提供 RitsuLib 版本，无法确认 bug 首次出现版本

---

English translation

Summary

The predicate logic inside RegisterCombatUiAlwaysVisibleWhen / AlwaysShowInCombatUiForCharacter is implemented correctly, but the update callback registered through RegisterCombatUi is always invoked — the framework never auto-hides the node based on the predicate result. The tutorial example callback ctx => ctx.Node.Bind(ctx.Player) reaches NSecondaryResourceCounter.Refresh(), which unconditionally sets Visible = true when a player is present, so the visibility predicates are never acted upon. This is a high-severity framework design gap; the recommended fix is to wrap the update callback inside RegisterCombatUi to perform an automatic visibility check.

Key Takeaways

Item	Detail
Description	When a secondary resource combat UI is registered, visibility predicates (RegisterCombatUiAlwaysVisibleWhen) only affect the VisibleDefinitions field passed to the update context — they do not prevent the callback from being called, so the resource icon is always displayed.
Probable causes	① RegisterCombatUpdater unconditionally calls update(ctx) on every combat update, even if the resource is absent from VisibleDefinitions; ② NSecondaryResourceCounter.Refresh() unconditionally executes Visible = true when player != null (SecondaryResourceCounterNodes.cs:284), never consulting any visibility predicate.
Suggested fixes	① (Recommended) Wrap the update call inside ModSecondaryResourceRegistry.RegisterCombatUi (SecondaryResourceUi.cs ~L255): if the definition for localId is absent from VisibleDefinitions, call HideNode(node) and return without invoking the callback. ② As a supplementary fix, NSecondaryResourceCounter.Refresh() could call _definition.IsVisibleInCombatUi(player) instead of unconditionally setting Visible = true.

Expand detailed analysis, evidence, and verification

Problem Description

Expected Behavior

After calling AlwaysShowInCombatUiForCharacter<T>(), the combat UI should appear only when the player's character type matches. Without any "always-show" predicate and with amount = 0, the UI should be hidden.

Actual Behavior

Regardless of predicate results, the secondary resource combat UI is visible in every character's combat, even when the amount is 0 and a _ => false test predicate is registered.

Reproduction Steps

1. Register a secondary resource following the tutorial, with defaultAmount: 0
2. Call registry.RegisterCombatUiAlwaysVisibleWhen(ManaDefinition.LocalId, _ => false) as a test
3. Call registry.RegisterCombatUi(...) with callback ctx => ctx.Node.Bind(ctx.Player)
4. Enter combat with any character → the resource icon is still visible

Environment & Version

Reporter did not fill in RitsuLib version or runtime environment fields.

Detailed Analysis

Predicate storage — correct

ModSecondaryResourceRegistry.RegisterCombatUiAlwaysVisibleWhen (ModSecondaryResourceRegistry.cs:171) stores predicates in the static dictionary CombatUiVisibilityPredicates, keyed by resourceId (GetResourceId(_modId, localId)), sorted by order.

Visibility evaluation — correct

SecondaryResourceVisibility.IsVisibleInCombatUi (SecondaryResourceVisibility.cs:56):

if (ModSecondaryResourceRegistry.GetCombatUiVisibilityPredicates(definition.Id)
    .Any(predicate => predicate(context)))
    return true;
return context.Amount > definition.DefaultAmount;

With the _ => false test predicate: Any(...) is false; Amount(0) > DefaultAmount(0) is also false. The definition correctly does not appear in the list returned by GetCombatUiDefinitions(player).

Update callback — the gap

SecondaryResourceUiRuntime.RegisterCombatUpdater (SecondaryResourceUi.cs:157) registers an updater lambda that always calls update:

CombatUpdaters.GetOrCreate(parent).Add(player =>
{
    var definitions = ModSecondaryResourceRegistry.GetDefinitionsSnapshot();
    update(new(
        parent, node, player,
        definitions,
        SecondaryResourceVisibility.GetCombatUiDefinitions(player)));  // ← VisibleDefinitions
});

VisibleDefinitions is passed as context data only; the framework does not check whether the node's corresponding definition is present before calling update.

NSecondaryResourceCounter.Refresh — secondary gap

SecondaryResourceCounterNodes.cs:276:

public void Refresh(Player? player)
{
    if (_definition == null || player == null) { Visible = false; return; }
    Visible = true;   // ← unconditionally true; visibility predicates never consulted
    SetAmount(...);
}

The tutorial callback ctx => ctx.Node.Bind(ctx.Player) ends here, making the node always visible.

NSecondaryResourceCounterRow — correct behavior for comparison

NSecondaryResourceCounterRow.Refresh(player, visibleDefinitions) shows only counters whose definitions appear in visibleDefinitions, and correctly responds to visibility. The tutorial example does not use this type.

Recommended code-level fix

In ModSecondaryResourceRegistry.RegisterCombatUi (SecondaryResourceUi.cs:244), wrap the RegisterCombatUpdater call with a visibility guard:

(parent, node) =>
{
    var resourceId = GetResourceId(_modId, localId);
    SecondaryResourceUiRuntime.RegisterCombatUpdater(parent, node, ctx =>
    {
        if (ctx.Player == null ||
            !ctx.VisibleDefinitions.Any(d => d.Id == resourceId))
        {
            if (node is CanvasItem ci) ci.Visible = false;
            return;
        }
        update(ctx);
    });
    SecondaryResourceUiRuntime.HideCombatUi(parent);
}

With this fix, the existing tutorial example ctx => ctx.Node.Bind(ctx.Player) works correctly without any changes.

Reporter Hygiene

Field	Status
Reproduction steps	Provided (with code)
Expected / actual	Actual is described; expected is "No response" but inferable from context
Environment & version	Missing: RitsuLib version and runtime environment not filled in
Logs / attachments	Empty shell block — acceptable for a logic bug with no crash

Suggesting the reporter supply a RitsuLib version number to help scope the fix.

Verification Checklist

• Add a breakpoint/log in SecondaryResourceVisibility.IsVisibleInCombatUi to confirm it returns false for the _ => false predicate
• Trace NCombatUi.Activate postfix → UpdateCombatUi → updater(player) → update(ctx) to confirm the callback fires even when VisibleDefinitions is empty
• Add a log in NSecondaryResourceCounter.Refresh to confirm Visible = true is reached
• After applying the fix, test that _ => false successfully prevents display; test that a character-type predicate correctly filters by character

Risks & Open Questions

• If any mod already relies on the existing behavior of "callback always called," the framework-level fix may be a breaking change; should be noted in the changelog
• Reporter did not provide a RitsuLib version, so the first-affected version cannot be confirmed

---

工具侧记录

• BAKAOLC/STS2-RitsuLib#56 · 退出码 0 · 进程 293.37s
• claude-sonnet-4-6 · API 291603ms · 13 轮 · ↓14 ↑17189 · 缓存读393087 写67335 · $0.7798
• MCP available: management tools exposed to Claude.

[BAKAOLC]

/r set wip

[BAKAOLC]

已修正相关设计并推送至 DEV 分支
由于这个目前不会直接影响游戏进行，所以暂时不会发布新版本，会在有足够内容时统一发布修复版本。
但你可以使用 dev-build 分支的文件进行测试以确认该问题是否修复
issue 会在发布版本的同时自动关闭，所以你如果确认问题解决可以只需要通知确认

/r set confirmed

[C-W-Z]

問題似乎沒有解決，但我不確定究竟是bug還是教學不夠詳細導致我不太理解您的設計。

我猜想您的設計應該是讓所有角色預設不顯示次級資源的圖標，但只要獲得次級資源就會顯示。
而目前的狀況是所有角色預設都會顯示，因此AlwaysShowInCombatUiForCharacter的設定沒有用處。
因為就算不設定AlwaysShowInCombatUiForCharacter也還是會顯示圖標。

或者是關於RegisterCombatUi中的update我認為可能需要更詳細的教學？
因為按照現有教學，參數update傳入的是無條件綁定Player，或許原因出在這裡：ctx => ctx.Node.Bind(ctx.Player)，但我不知道要如何在綁定的同時設定只會在有次級資源時顯示。

以下是我的嘗試，我改成在RegisterCombatUi中的update邏輯設定只有特定角色預設顯示以及其他角色獲得次級資源後才會顯示的邏輯。

registry.RegisterCombatUi(
    "mana_combat_ui",
    parent =>
    {
        var row = NSecondaryResourceCounter.Create(ManaDefinition, SecondaryResourceCounterStyle.Default);
        var energyCounter = parent.GetNode<Control>("%EnergyCounterContainer");
        row.Position = energyCounter.Position + new Vector2(-80, -120);
        return row;
    },
    ctx =>
    {
        // 這裡設定只有MyCharacter預設顯示，其他角色要獲得次級資源後才會顯示
        if (ctx.Player == null)
            return;
        if (ctx.Player.Character is MyCharacter || SecondaryResourceCmd.Get(ctx.Player, ManaId) > 0)
            ctx.Node.Bind(ctx.Player);
    }
);

但結果是MyCharacter會預設顯示，而其他角色即使獲得了次級資源也無法顯示圖標。
看起來這個update參數只有在註冊時調用了一次，後續獲得資源時沒有被調用。
我已經不太確定這究竟是bug還是我沒有正確理解您的設計。
究竟應該要如何設定"讓所有角色預設不顯示次級資源，但只要獲得次級資源就會顯示。"？

[BAKAOLC]

我测试是没有问题，我怀疑你可能因为配置了 csporj 这些导致重新文件覆盖了或者别的什么原因。
具体的我后面让 reme 他们优化一下教程看看
目前你可以先放一下这个，我有其他的 bug 会在后面一起修复
这块还是很实验性的，所以很需要大量测试覆盖各种场景