[Feature] 让次要资源图标在获得次要资源时会闪光

[iouter]

模块范围

UI

动机 / 使用场景

就像原版的辉星一样，原版的辉星在获得辉星时，会闪光。所以希望能让次要资源图标在获得次要资源时也会闪光

方案设想

让次要资源图标在获得次要资源时会闪光，就像原版辉星一样

替代方案

No response

其他补充

No response

[ritsukage-local-analyzer]

Warning

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

摘要

这是一个明确的 UI 体验增强请求：希望 RitsuLib 的次级资源计数器在资源增加时，像原版辉星计数器一样产生闪光/获得特效。当前次级资源 UI 已能刷新数量与图标，但从本地代码看尚未实现“增加时播放视觉反馈”的逻辑；建议作为小型 feature 保留并在次级资源计数节点层实现。

重点结论

项目	结论
简单介绍	玩家获得次级资源时，顶部/战斗 UI 的次级资源图标目前缺少类似原版辉星的获得反馈。
可能原因	较高可信：现有次级资源计数器只刷新数值、颜色与图标提示，未在数值上升时触发 tween 或 VFX；原版辉星有独立的 NStarCounter.UpdateStarCount 增量动画逻辑。
可能解决方案	在 NSecondaryResourceCounter 的数值更新路径中检测 newAmount > oldAmount，复用或新增可配置的闪光/VFX；同时保留样式开关，避免强制所有模组使用同一效果。
需要补充	不阻塞初步实现；若要精确设计，可请提出者确认触发范围：仅 Gain，还是 Set/回合开始重置导致数值上升也要闪光。

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

问题描述

期望行为

• 当次级资源数量增加时，次级资源图标出现闪光或获得特效。
• 视觉反馈参考原版辉星：获得辉星时计数器会短暂高亮并播放获得 VFX。

实际行为

• Issue 描述的是功能缺口而非崩溃：次级资源图标没有提到获得资源时的闪光反馈。
• 本地代码也显示次级资源计数器目前主要负责显示、刷新、悬浮提示与可见性，没有看到资源增加时的专门动画触发。

日志、附件与原文摘录

• 原文：

  “就像原版的辉星一样，原版的辉星在获得辉星时，会闪光。”
  “希望能让次要资源图标在获得次要资源时也会闪光”
  要点：提出者期望的是与原版辉星一致的 UI 反馈，而不是资源数值逻辑变更。

详细分析依据

• RitsuLib 文档说明次级资源用于模组自定义能量、弹药、姿态计数等战斗支付状态，并通过 SecondaryResourceCmd.Gain/Set/Spend/Reset 修改运行时数值：docs/pages/guide/secondary-resources.md:44、docs/pages/guide/secondary-resources.md:113。
• SecondaryResourceCmd.Gain 会计算有效增加量后进入 SetCore：src/Combat/SecondaryResources/SecondaryResourceCmd.cs:39。SetCore 在数值变化后记录历史、刷新当前战斗 UI，并调用 AfterChanged hook：src/Combat/SecondaryResources/SecondaryResourceCmd.cs:264、src/Combat/SecondaryResources/SecondaryResourceCmd.cs:289、src/Combat/SecondaryResources/SecondaryResourceCmd.cs:290、src/Combat/SecondaryResources/SecondaryResourceCmd.cs:291。
• 当前显示层 NSecondaryResourceCounter.SetAmount 只更新 _amount/_maxAmount、数值文本、颜色和 icon hover-tip amount：src/Combat/SecondaryResources/SecondaryResourceCounterNodes.cs:302。NSecondaryResourceIcon 也主要负责加载并显示图标纹理：src/Combat/SecondaryResources/SecondaryResourceCounterNodes.cs:406、src/Combat/SecondaryResources/SecondaryResourceCounterNodes.cs:497。
• 原版辉星计数器存在明确的增加反馈路径：NStarCounter 保存 star_gain_vfx 场景路径：official-source/src/Core/Nodes/Combat/NStarCounter.cs:19；当 newCount > oldCount 时创建 tween 调整 shader 亮度并实例化获得 VFX：official-source/src/Core/Nodes/Combat/NStarCounter.cs:121、official-source/src/Core/Nodes/Combat/NStarCounter.cs:130、official-source/src/Core/Nodes/Combat/NStarCounter.cs:133、official-source/src/Core/Nodes/Combat/NStarCounter.cs:135。
• 因此最自然的实现点是显示节点层，而不是资源状态层：状态层已经统一刷新 UI；计数器能直接比较旧显示值与新值，并可按样式决定是否播放视觉反馈。若将效果绑定到 Gain 命令本身，可能漏掉 Set 或回合开始策略造成的正向变化；若所有正向变化都播放，则更贴近“看到数量增加就反馈”的 UI 语义。

详细验证建议

• 注册一个带图标的测试次级资源，并把它显示在战斗 UI 中。
• 调用 SecondaryResourceCmd.Gain(player, id, 1, source)，确认数量增加且图标短暂闪光/播放 VFX。
• 调用 Lose 或 Spend，确认减少时不播放“获得”闪光。
• 测试从 0 增加到正数时的首次可见场景，确认显示与动画不会互相打断或错位。
• 测试多次快速 Gain，确认 tween/VFX 不堆积到影响可读性或性能。
• 若实现样式开关，验证默认行为与模组自定义关闭/替换效果都可用。

风险与未决

• 触发语义需要维护者取舍：仅 Gain 播放更保守；所有正向数值变化播放更符合 UI 感知，但可能让回合开始重置/初始化也产生动画。
• 如果直接复用原版 star_gain_vfx，视觉风格可能偏向辉星；为通用次级资源提供可配置 VFX 或 shader/tween 参数更稳妥。
• 需要注意自动刷新路径：NSecondaryResourceCounter 支持每帧刷新，动画检测应避免因同一数值重复刷新而重复触发。

---

English translation

Summary

This is a clear UI quality-of-life feature request: RitsuLib secondary-resource counters should flash or play a gain effect when the resource increases, similar to the vanilla star counter. The current secondary-resource UI can refresh amounts and icons, but local inspection suggests it does not yet implement visual feedback for positive amount changes; this is worth keeping as a small feature and implementing in the secondary-resource counter node layer.

Key Takeaways

Item	Takeaway
Brief description	When the player gains a secondary resource, the top/combat UI secondary-resource icon currently lacks vanilla-star-like gain feedback.
Likely cause	High confidence: the existing secondary-resource counter updates text, color, icon, and hover-tip state, but does not trigger a tween or VFX on amount increase; vanilla stars have dedicated increment animation logic in NStarCounter.UpdateStarCount.
Possible solution	Detect newAmount > oldAmount in the NSecondaryResourceCounter amount update path, then reuse or add a configurable flash/VFX effect; keep a style toggle so mods are not forced into one visual treatment.
Needs more info	Not blocking initial implementation; for exact behavior, ask whether the effect should trigger only on Gain, or also when Set/turn-start reset increases the displayed value.

Expand detailed analysis, evidence, and verification

Problem Description

Expected Behavior

• When a secondary-resource amount increases, its icon should flash or play a gain effect.
• The requested feedback should resemble the vanilla star counter: gaining stars briefly highlights the counter and plays gain VFX.

Actual Behavior

• The issue describes a feature gap rather than a crash: the secondary-resource icon is not described as flashing when resources are gained.
• The local code also indicates that the secondary-resource counter currently focuses on display, refresh, hover tips, and visibility, with no obvious dedicated animation trigger for resource gains.

Logs, Attachments, and Source Excerpts

• Original text:

  “就像原版的辉星一样，原版的辉星在获得辉星时，会闪光。”
  “希望能让次要资源图标在获得次要资源时也会闪光”
  Key point: the request is for UI feedback matching vanilla stars, not a change to resource value logic.

Detailed Analysis Basis

• RitsuLib documentation describes secondary resources as mod-defined combat payment state such as custom energy, ammo, stance counters, etc., mutated through SecondaryResourceCmd.Gain/Set/Spend/Reset: docs/pages/guide/secondary-resources.md:44, docs/pages/guide/secondary-resources.md:113.
• SecondaryResourceCmd.Gain computes the effective gain and then enters SetCore: src/Combat/SecondaryResources/SecondaryResourceCmd.cs:39. After a value change, SetCore records history, refreshes the current combat UI, and invokes the AfterChanged hook: src/Combat/SecondaryResources/SecondaryResourceCmd.cs:264, src/Combat/SecondaryResources/SecondaryResourceCmd.cs:289, src/Combat/SecondaryResources/SecondaryResourceCmd.cs:290, src/Combat/SecondaryResources/SecondaryResourceCmd.cs:291.
• The current display layer NSecondaryResourceCounter.SetAmount updates _amount/_maxAmount, amount text, color, and icon hover-tip amount: src/Combat/SecondaryResources/SecondaryResourceCounterNodes.cs:302. NSecondaryResourceIcon mainly loads and displays the icon texture: src/Combat/SecondaryResources/SecondaryResourceCounterNodes.cs:406, src/Combat/SecondaryResources/SecondaryResourceCounterNodes.cs:497.
• The vanilla star counter has a clear positive-change feedback path: NStarCounter stores the star_gain_vfx scene path at official-source/src/Core/Nodes/Combat/NStarCounter.cs:19; when newCount > oldCount, it creates a tween to adjust shader brightness and instantiates the gain VFX: official-source/src/Core/Nodes/Combat/NStarCounter.cs:121, official-source/src/Core/Nodes/Combat/NStarCounter.cs:130, official-source/src/Core/Nodes/Combat/NStarCounter.cs:133, official-source/src/Core/Nodes/Combat/NStarCounter.cs:135.
• Therefore, the most natural implementation point is the display-node layer rather than the resource-state layer. The state layer already routes UI refreshes; the counter can directly compare the previous displayed value with the new value and decide, via style, whether to play feedback. Binding the effect only to Gain may miss positive changes caused by Set or turn-start policies; playing it for every positive displayed-value change better matches UI semantics.

Detailed Verification Suggestions

• Register a test secondary resource with an icon and display it in combat UI.
• Call SecondaryResourceCmd.Gain(player, id, 1, source) and confirm the amount increases while the icon briefly flashes or plays VFX.
• Call Lose or Spend and confirm decreases do not play the “gain” flash.
• Test the first visible transition from 0 to a positive amount, confirming display and animation do not interrupt or misplace each other.
• Test multiple rapid Gain calls, confirming tween/VFX stacking does not harm readability or performance.
• If a style toggle is implemented, verify the default behavior and mod-customized disable/replace behavior both work.

Risks and Open Questions

• Maintainers need to choose trigger semantics: only Gain is more conservative; all positive value changes better match what the user sees, but may animate turn-start reset or initialization.
• Directly reusing vanilla star_gain_vfx may make all resources look too star-themed; configurable VFX or shader/tween parameters would be safer for generic secondary resources.
• The auto-refresh path matters: NSecondaryResourceCounter can refresh every frame, so animation detection must avoid retriggering for the same unchanged value.

---

工具侧记录

• BAKAOLC/STS2-RitsuLib#75 · 退出码 0 · 进程 316.96s
• gpt-5.5(high) · API 315950ms · 31 轮 · ↓68160 ↑7211 · 缓存读684544 写0 · $0.8633
• MCP available: management tools exposed to Claude.

[BAKAOLC]

添加了预制的行为和响应接口，优化了默认内置ui的数值变更行为，此外的默认行为未改动，可以在注册ui时显式指定使用类辉星的样式