[Feature] 向垃圾堆事件注册

[iouter]

模块范围

Public API（公开 API）

动机 / 使用场景

向垃圾堆事件注册卡牌和遗物。
baselib有一个，ritsulib最好也有一个？

方案设想

就像注册先古升级什么的一样吧

替代方案

No response

其他补充

No response

[ritsukage-local-analyzer]

Warning

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

摘要

这是一个合理的 Public API 功能请求：让 mod 作者把自定义卡牌/遗物加入原版 TrashHeap（垃圾堆）事件的候选池。当前 RitsuLib 已有“向古代事件注入初始选项”的相似注册面，但未看到针对垃圾堆卡牌/遗物池的公开封装；建议作为小型 API 增量评估实现。

重点结论

项目	结论
简单介绍	用户希望像 baselib 一样，把自定义卡牌和遗物注册进垃圾堆事件奖励池。
可能原因	较高置信：RitsuLib 目前覆盖了 Ancient Option 注册，但没有等价的 TrashHeap 卡牌/遗物池扩展 API；baselib 中存在可参考的 marker-interface + Harmony patch 实现。
可能解决方案	增加 RegisterTrashHeapCard / RegisterTrashHeapRelic 或内容包 builder 方法，并在 TrashHeap.Cards / TrashHeap.Relics getter 后追加注册内容；同时补文档与最小验证用例。
需要补充	需要维护者确认偏好的 API 形态：marker interface、显式 registry，还是两者兼容；以及是否要与 baselib 命名/行为保持一致。

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

问题描述

期望行为

• mod 作者可以通过 RitsuLib Public API，把卡牌加入垃圾堆事件的 Grab 奖励池，把遗物加入 DiveIn 奖励池。
• 使用体验最好与现有内容注册流程一致，例如可通过 RitsuLibFramework / ModContentRegistry / ModContentPackBuilder 完成注册。

实际行为

• issue 描述表明当前缺少这样的 RitsuLib API。
• 本地检查中未发现 RitsuLib 主仓库已有 TrashHeap 相关注册或 patch；仅看到现有 RegisterAncientOption<TAncient> 体系用于向 ancient 初始选项注入内容。

复现步骤

• 这是功能请求，不是运行时 bug；可用最小场景理解为：
  1. 创建一个自定义卡牌或遗物。
  2. 尝试通过 RitsuLib 公共内容注册 API 将其加入垃圾堆事件候选池。
  3. 目前没有对应的明确入口。

日志、附件与原文摘录

• 原文：

  向垃圾堆事件注册卡牌和遗物。
  baselib有一个，ritsulib最好也有一个？

  要点：请求补齐 baselib 已有的垃圾堆候选池扩展能力。

• 原文：

  就像注册先古升级什么的一样吧

  要点：期望 API 风格接近现有 ancient/升级类注册入口，而不是要求特定实现细节。

详细分析依据

• 官方源码中 TrashHeap 是事件模型，内部有两个固定候选池：Relics 返回 5 个原版遗物，Cards 返回 10 张原版卡；DiveIn() 从 Relics 随机给遗物，Grab() 从 Cards 随机给卡牌（official-source/src/Core/Models/Events/TrashHeap.cs:19, official-source/src/Core/Models/Events/TrashHeap.cs:28, official-source/src/Core/Models/Events/TrashHeap.cs:62, official-source/src/Core/Models/Events/TrashHeap.cs:70）。
• baselib 的参考实现很小：空 marker interfaces ITrashHeapCard / ITrashHeapRelic，再用 Harmony postfix 扩展 TrashHeap.Cards / TrashHeap.Relics getter，将 ModelDb.AllCards / ModelDb.AllRelics 中实现 marker 的模型追加进去（sts-2-baselib/Abstracts/ITrashHeapCard.cs:3, sts-2-baselib/Abstracts/ITrashHeapRelic.cs:3, sts-2-baselib/Patches/Content/TrashHeapPatch.cs:8, sts-2-baselib/Patches/Content/TrashHeapPatch.cs:30）。
• RitsuLib 已有相近模式：ModContentRegistry.RegisterAncientOption<TAncient> 将规则交给 ModAncientOptionRegistry，并通过 AncientEventInitialOptionsRegistryPatch 在原版生成后追加选项（src/Content/ModContentRegistry.AncientOptions.cs:12, src/Scaffolding/Ancients/Options/ModAncientOptionRegistry.cs:21, src/Scaffolding/Content/Patches/AncientEventInitialOptionsRegistryPatch.cs:43）。这说明“声明式注册 + patch 注入”的设计在项目中已有先例。
• 实现上需要决定 API 形态：
  • 显式 registry：更符合 RitsuLib 现有 RegisterAncientOption 风格，也便于维护 owner mod id、去重、清测试状态、热重载。
  • marker interface：最接近 baselib，迁移成本低，但对注册时机、去重、跨 mod 可见性与热重载控制较弱。
  • 兼容方案：公开 registry，同时可选支持 marker interface 作为 baselib 迁移桥。
• 需要注意 TrashHeap.Cards / Relics 当前是静态私有属性，baselib 选择 patch getter 是可行参考；RitsuLib 若采用 registry，应避免长期缓存导致测试/热重载后新增内容不生效，或提供 ClearForTests 类似入口。

反馈规范性提醒

维度	状态
复现步骤	含糊：功能请求可不要求运行复现，但未给出目标调用示例。
期望/实际	已提供：期望“注册卡牌和遗物”，实际隐含“RitsuLib 没有”。
环境与版本	缺失：未说明目标游戏/RitsuLib/baselib 版本；本项不阻塞初步评估，但会影响兼容性判断。
日志/附件	已提供：此类 API 请求通常不需要日志。
标题与背景	已提供：标题和动机能定位到垃圾堆事件与 Public API。

详细验证建议

• 确认当前 Public API 中确实没有可间接扩展 TrashHeap.Cards / TrashHeap.Relics 的入口。
• 添加一张测试卡和一个测试遗物，通过新 API 注册后进入垃圾堆事件，分别验证 Grab 与 DiveIn 的随机池包含新增内容。
• 验证重复注册、跨 mod 注册顺序、内容注册冻结后调用、测试清理/热重载场景的行为。
• 补充文档示例，展示内容包 builder 与直接 RitsuLibFramework 调用两种常见用法（如果两者都支持）。

风险与未决

• 如果直接复制 baselib 的 marker-interface 方案，可能不符合 RitsuLib 当前偏向 registry/builder 的 API 风格。
• 垃圾堆奖励池扩展会改变事件奖励概率；需要决定是否按注册项简单追加，还是支持权重/条件过滤。
• 需要确认是否要对 baselib 的 ITrashHeapCard / ITrashHeapRelic 做迁移兼容，避免用户同时依赖两库时行为重复或不一致。

---

English translation

Summary

This is a reasonable Public API feature request: let mod authors add custom cards and relics to the vanilla TrashHeap event candidate pools. RitsuLib already has a similar registration surface for injecting initial options into ancient events, but no public wrapper for Trash Heap card/relic pools was found; this should be evaluated as a small API addition.

Key Takeaways

Item	Takeaway
Brief introduction	The user wants to register custom cards and relics into the Trash Heap event reward pools, similar to baselib.
Likely cause	High confidence: RitsuLib currently covers Ancient Option registration, but does not have an equivalent extension API for TrashHeap card/relic pools; baselib provides a marker-interface + Harmony patch reference implementation.
Possible solution	Add RegisterTrashHeapCard / RegisterTrashHeapRelic or content-pack builder methods, then append registered content after the TrashHeap.Cards / TrashHeap.Relics getters; also add docs and a minimal verification case.
Needs follow-up	Maintainers should confirm the preferred API shape: marker interface, explicit registry, or compatibility with both; and whether naming/behavior should stay aligned with baselib.

Expand detailed analysis, evidence, and verification

Problem Description

Expected Behavior

• Mod authors can use RitsuLib Public API to add cards to the Trash Heap Grab reward pool and relics to the DiveIn reward pool.
• Ideally, the usage should match existing content registration flows, such as through RitsuLibFramework, ModContentRegistry, or ModContentPackBuilder.

Actual Behavior

• The issue indicates that this RitsuLib API is currently missing.
• Local inspection did not find existing TrashHeap registration or patches in the main RitsuLib repository; only the existing RegisterAncientOption<TAncient> system for injecting content into ancient initial options was found.

Reproduction Steps

• This is a feature request rather than a runtime bug; the minimal scenario is:
  1. Create a custom card or relic.
  2. Try to register it into the Trash Heap event candidate pool through RitsuLib public content APIs.
  3. There is currently no clear corresponding entry point.

Logs, Attachments, and Original Excerpts

• Original:

  向垃圾堆事件注册卡牌和遗物。
  baselib有一个，ritsulib最好也有一个？

  Key point: the request is to add the Trash Heap candidate-pool extension capability that baselib already has.

• Original:

  就像注册先古升级什么的一样吧

  Key point: the desired API style should be close to existing ancient/upgrade registration entry points, without mandating a specific implementation.

Detailed Analysis Basis

• In the official source, TrashHeap is an event model with two fixed candidate pools: Relics returns 5 vanilla relics, and Cards returns 10 vanilla cards; DiveIn() randomly grants a relic from Relics, while Grab() randomly grants a card from Cards (official-source/src/Core/Models/Events/TrashHeap.cs:19, official-source/src/Core/Models/Events/TrashHeap.cs:28, official-source/src/Core/Models/Events/TrashHeap.cs:62, official-source/src/Core/Models/Events/TrashHeap.cs:70).
• baselib’s reference implementation is very small: empty marker interfaces ITrashHeapCard / ITrashHeapRelic, plus Harmony postfix patches on the TrashHeap.Cards / TrashHeap.Relics getters that append models from ModelDb.AllCards / ModelDb.AllRelics implementing those markers (sts-2-baselib/Abstracts/ITrashHeapCard.cs:3, sts-2-baselib/Abstracts/ITrashHeapRelic.cs:3, sts-2-baselib/Patches/Content/TrashHeapPatch.cs:8, sts-2-baselib/Patches/Content/TrashHeapPatch.cs:30).
• RitsuLib already has a comparable pattern: ModContentRegistry.RegisterAncientOption<TAncient> forwards rules to ModAncientOptionRegistry, and AncientEventInitialOptionsRegistryPatch appends options after vanilla generation (src/Content/ModContentRegistry.AncientOptions.cs:12, src/Scaffolding/Ancients/Options/ModAncientOptionRegistry.cs:21, src/Scaffolding/Content/Patches/AncientEventInitialOptionsRegistryPatch.cs:43). This shows that “declarative registration + patch-time injection” is already an established design in the project.
• The implementation needs an API-shape decision:
  • Explicit registry: better aligned with RitsuLib’s current RegisterAncientOption style, and easier to maintain owner mod id, deduplication, test cleanup, and hot-reload behavior.
  • Marker interface: closest to baselib and low-friction for migration, but weaker for registration timing, deduplication, cross-mod visibility, and hot-reload control.
  • Compatibility option: expose a registry while optionally supporting marker interfaces as a baselib migration bridge.
• One implementation detail: TrashHeap.Cards / Relics are currently private static properties, and baselib’s getter patch is a feasible reference. If RitsuLib uses a registry, it should avoid long-lived caches that make test/hot-reload additions invisible, or provide a ClearForTests-style reset hook.

Issue Hygiene Reminder

Dimension	Status
Reproduction steps	Ambiguous: acceptable for a feature request, but no target call-site example was provided.
Expected/actual	Provided: expected “register cards and relics”; actual is implicitly “RitsuLib does not support it.”
Environment/version	Missing: target game/RitsuLib/baselib versions are not listed; this does not block initial triage but affects compatibility decisions.
Logs/attachments	Provided: logs are usually not needed for this kind of API request.
Title/background	Provided: the title and motivation point to the Trash Heap event and Public API.

Detailed Verification Suggestions

• Confirm there is currently no Public API path that indirectly extends TrashHeap.Cards / TrashHeap.Relics.
• Add one test card and one test relic, register them through the new API, enter the Trash Heap event, and verify that Grab and DiveIn candidate pools include the new content.
• Verify behavior for duplicate registration, cross-mod registration order, calls after content registration freezes, and test cleanup/hot-reload scenarios.
• Add documentation examples for both content-pack builder usage and direct RitsuLibFramework calls, if both are supported.

Risks and Open Questions

• Copying baselib’s marker-interface approach directly may not match RitsuLib’s current registry/builder-oriented API style.
• Extending Trash Heap reward pools changes event reward probabilities; maintainers need to decide whether registered items are simply appended or whether weights/condition filters should be supported.
• Confirm whether RitsuLib should be migration-compatible with baselib’s ITrashHeapCard / ITrashHeapRelic, to avoid duplicate or inconsistent behavior when users depend on both libraries.

---

工具侧记录

• BAKAOLC/STS2-RitsuLib#92 · 退出码 0 · 进程 169.61s
• gpt-5.5(high) · API 167776ms · 27 轮 · ↓61345 ↑6815 · 缓存读291328 写0 · $0.6228
• MCP available: management tools exposed to Claude.