[Feature] 希望能有統一註冊主畫面右上角圖標的功能

[C-W-Z]

模块范围

Public API（公开 API）

动机 / 使用场景

我看了目前的MainMenuModSettingsButtonPatch，如果每個Mod都有自己自己寫一個Patch放右上角圖標的話很容易導致重疊
希望能夠有統一的註冊方式，由RitsuLib來管理圖標位置避免重疊

方案设想

可能按照模組載入順序排序圖標或者怎麼樣，看你覺得怎樣比較好

替代方案

No response

其他补充

No response

[ritsukage-local-analyzer]

Warning

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

摘要

MainMenuModSettingsButtonPatch 将 RitsuLib 设置按钮硬编码在 %PatchNotesButton 正下方固定偏移处；若其他 Mod 各自用相同方式向该区域追加图标，节点会叠放在同一坐标导致视觉重叠。RitsuLib 在战斗内顶部栏已有完整的统一注册体系（ModTopBarButtonRegistry + ModTopBarLayout），但主菜单目前缺少对等的公开 API，属于合理的功能缺口。建议参照顶部栏注册体系，新建主菜单快捷图标统一注册入口，由 RitsuLib 集中管理布局以消除重叠。

重点结论

维度	内容
简单介绍	多个 Mod 若各自向主菜单右上角注入快捷按钮，位置会相互叠放，无法共存。
可能原因	MainMenuModSettingsButtonPatch.SyncPlacement 将按钮硬编码在 %PatchNotesButton 底部固定偏移（GapBelowPatchNotes = 8f），无任何与外部 Mod 协调的机制；RitsuLib 不存在主菜单版的 ModTopBarButtonRegistry。
可能解决方案	① 新建 MainMenuShortcutRegistry 公开 API（仿 ModTopBarButtonRegistry.For(modId).RegisterOwned）；② 在 MainMenuModSettingsButtonPatch 内实现统一布局逻辑（按注册顺序纵向或横向排列按钮，每项间距固定），将 RitsuLib 自身的设置按钮迁移到此注册表，使第三方 Mod 也能免重叠地参与。

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

问题描述

期望行为

多个 Mod 均可向主菜单右上角（%PatchNotesButton 附近）添加自己的图标快捷入口，且 RitsuLib 统一管理各图标的排列，不产生重叠。

实际行为

当前仅 RitsuLib 自身通过 MainMenuModSettingsButtonPatch 占据该位置（硬编码在 %PatchNotesButton.OffsetBottom + 8f 处）。若其他 Mod 使用同样的 Harmony postfix 方式向相同位置插入节点，两个 Control 会出现在完全相同的坐标，互相叠压。

复现步骤

1. 另一个 Mod 编写自己的 NMainMenu._Ready postfix，将一个 64×64 按钮贴在 %PatchNotesButton 下方。
2. 同时加载该 Mod 和 RitsuLib，进入主菜单。
3. 两个按钮节点位置完全相同，视觉上叠放为一个图标。

环境与版本

无特定版本要求；问题属架构层面，与游戏/lib 版本无关。

详细分析依据

现有代码证据（MainMenuModSettingsButtonPatch.cs）：

• SyncPlacement（第 119–145 行）直接复制 %PatchNotesButton 的 anchor/grow 属性，并将 OffsetTop 固定设为 patchNotesButton.OffsetBottom + GapBelowPatchNotes（即 8f）。
• 整个节点以固定名称 RitsuLibMainMenuModSettings 挂在 NMainMenu 下，没有任何全局注册表去记录"该槽已被占用"。
• 对比已有的顶部栏系统：ModTopBarButtonRegistry（TopBar/ModTopBarButtonRegistry.cs）提供了带去重和排序的统一注册入口，ModTopBarLayout.Place（TopBar/ModTopBarLayout.cs）通过 HBoxContainer 子索引操纵自动完成无冲突排列；主菜单侧完全没有对等设施。

方案可行性：

• 主菜单按钮区域不是 HBoxContainer，而是 anchor-based 的自由布局，因此需要手动按注册顺序计算 OffsetTop（每个按钮高度 64f + 间距 8f，依此叠加），逻辑比顶部栏稍复杂但不难实现。
• MainMenuModSettingsButtonPatch 现有的 EnsureEntry / SyncPlacement 逻辑可以平滑迁移为注册表驱动，RitsuLib 的设置按钮在框架初始化时作为第 0 号条目注册，优先级最高（或最低，按需决定）。

详细验证建议

• 在沙箱中新建一个测试 Mod，用同样的 anchor 偏移向主菜单添加一个按钮，确认当前确实重叠。
• 评估主菜单右上角区域（%PatchNotesButton 以下）在不同分辨率下的可用垂直空间，确定最多可容纳几个 64px 图标（估算值：1080p 下约 3–4 个）。
• 设计注册 API 时参考 ModTopBarButtonRegistry.For(modId).RegisterOwned(localStem, spec) 的调用形式，保持一致的公共 API 风格。
• 确认注册时机：主菜单按钮在 NMainMenu._Ready 时挂载，注册可在此之前任意时机（无需与 ModelDb 一起冻结，与顶部栏按钮相同）。

风险与未决

• 主菜单区域按钮数量上限需确定（超过上限时是否换行/缩小/截断）。
• 注册顺序（即各 Mod 按钮的排列顺序）是否需要提供优先级控制，或仅按模组加载顺序排列——报告者在方案设想中明确提及此点，交由维护者决策。
• 现有 VisibilitySynchronizer (_Process 轮询) 若扩展为多按钮，应考虑合并为单个同步节点，避免每个注册按钮各开一个 _Process。

---

English translation

Summary

MainMenuModSettingsButtonPatch hard-codes the RitsuLib settings button at a fixed offset directly below %PatchNotesButton; if other mods each inject their own icons into this area using the same approach, the nodes will stack at identical coordinates and overlap visually. RitsuLib already has a complete unified registration system for the in-game top bar (ModTopBarButtonRegistry + ModTopBarLayout), but no equivalent public API exists for the main menu — a legitimate gap. The recommended action is to build a unified main-menu shortcut icon registry (modeled on the top-bar pattern) so RitsuLib can centrally manage icon placement and prevent overlap.

Key Takeaways

Dimension	Detail
Summary	Multiple mods adding shortcut buttons to the main menu's top-right corner will overlap, since each calculates its own position independently.
Likely Cause	MainMenuModSettingsButtonPatch.SyncPlacement hard-codes the button at %PatchNotesButton.OffsetBottom + 8f (constant GapBelowPatchNotes), with no mechanism to coordinate with external mods. There is no main-menu equivalent of ModTopBarButtonRegistry.
Suggested Fix	① Create a public MainMenuShortcutRegistry API (mirroring ModTopBarButtonRegistry.For(modId).RegisterOwned). ② Implement a unified layout step inside the MainMenuModSettingsButtonPatch plumbing that stacks registered buttons vertically in registration order with fixed spacing, and migrate RitsuLib's own settings button into this registry as entry 0.

Expand detailed analysis, evidence, and verification

Problem Description

Expected Behavior

Multiple mods can each register a shortcut icon near %PatchNotesButton on the main menu, and RitsuLib manages the layout so they appear side-by-side (or stacked) without visual overlap.

Actual Behavior

Only RitsuLib's own button occupies that slot today, hard-coded at %PatchNotesButton.OffsetBottom + 8f. If a second mod patches NMainMenu._Ready to insert a button at the same anchor offsets, the two Control nodes share identical coordinates and overlap into a single visible icon.

Reproduction Steps

1. Write a second mod that adds a 64×64 button below %PatchNotesButton via a Harmony postfix on NMainMenu._Ready.
2. Load both mods alongside RitsuLib and enter the main menu.
3. Both button nodes land at the same position and render as one icon.

Environment & Version

No specific version requirement; the issue is architectural and affects all current releases.

Detailed Analysis

Code evidence (MainMenuModSettingsButtonPatch.cs):

• SyncPlacement (lines 119–145) copies the anchor/grow properties of %PatchNotesButton verbatim and sets OffsetTop = patchNotesButton.OffsetBottom + GapBelowPatchNotes (8f), with no global registry tracking that the slot is occupied.
• The container node is created under the fixed name RitsuLibMainMenuModSettings on NMainMenu — scoped only to RitsuLib's own use.
• Contrast with the in-game top-bar system: ModTopBarButtonRegistry (TopBar/ModTopBarButtonRegistry.cs) provides a deduplicated, ordered registration surface, and ModTopBarLayout.Place (TopBar/ModTopBarLayout.cs) achieves conflict-free placement by manipulating HBoxContainer child indices. The main menu has no equivalent infrastructure.

Feasibility:

• The main-menu button area uses anchor-based free layout (not HBoxContainer), so the layout step needs to compute OffsetTop manually per registered entry (slot index × (64f + spacing)). This is slightly more explicit than the top-bar approach but straightforward.
• The existing EnsureEntry / SyncPlacement logic is easy to refactor into a registry-driven loop. RitsuLib's own settings button registers itself as slot 0 during framework initialization; third-party mods register subsequently.

Detailed Verification Checklist

• Create a sandbox test mod that places a button at the same anchor offset; confirm the overlap is reproducible today.
• Measure the available vertical space below %PatchNotesButton at common resolutions to determine the maximum number of 64 px icons that fit (rough estimate: 3–4 at 1080p).
• Design the registration API to mirror ModTopBarButtonRegistry.For(modId).RegisterOwned(localStem, spec) for API consistency.
• Confirm the registration window: main-menu buttons are mounted at NMainMenu._Ready, so registration can happen at any earlier point (same as top-bar buttons; no ModelDb freeze required).

Risks & Open Questions

• A maximum-entry cap or overflow strategy (wrapping, scaling, truncation) needs a design decision.
• Whether button ordering should honor an explicit priority field or simply follow mod-load order — the reporter explicitly raises this in their proposal; left to maintainer discretion.
• The current RitsuLibMainMenuModSettingsVisibilitySync node runs _Process per button. Extending this to multiple registrants should consolidate into a single sync node to avoid one _Process per registered entry.

---

工具侧记录

• BAKAOLC/STS2-RitsuLib#59 · 退出码 0 · 进程 115.50s
• claude-sonnet-4-6 · API 113527ms · 11 轮 · ↓9 ↑5433 · 缓存读182712 写42963 · $0.3941
• MCP available: management tools exposed to Claude.

[BAKAOLC]

理论上其实不应该在主界面摆太多按钮，这个 api 在实际设计上并不算合适的功能点
尤其是可能的用户图标样式和需要显示的内容五花八门，如果提供可能会因此完全限制为同样的按钮样式等或者难以布局等情况
而且理论来说会增加相关按钮的 mod 并不多，尤其是有专门的设置界面的情况下
未来可能根据评估需求会增加，但是目前来说并不算优先级很高的一个功能需求，我会更优先于开发其他功能

/r set confirm p3 feature