CollectibleDefinition
模组收集品定义（对外契约）。不可变值对象，用 of(String) 起手，再按需 with* 派生新实例，最后经 ModRegistries 的 collectibles() 注册；宿主在注册时转换为内核收集品模型。
id 在哪：本记录不自带 id，身份由注册表键（RegistryKey）承载；进入内核后使用的收集品 id 取注册键的 path，所以与内置收集品的 id 空间天然兼容，解锁时也用它调 ModContext.unlockCollect(id)。
方法速览
| 方法 | 用途 |
|---|---|
of(name) | 最小构造（其余字段取默认值） |
name() / source() / brief() / detail() | 读显示名、来源、短简介、详情 |
unlockedByDefault() / rewardLogs() | 读默认可见性与日志奖励 |
withSource(v) / withBrief(v) / withDetail(v) | 派生带新文案的实例 |
withUnlockedByDefault(v) / withRewardLogs(v) | 派生新可见性 / 奖励 |
equals(o) / hashCode() / toString() | 记录默认实现（按全部组件比较） |
完整签名
public record CollectibleDefinition(String name, String source, String brief,
String detail, boolean unlockedByDefault, int rewardLogs) {
public static CollectibleDefinition of(String name);
public String name();
public String source();
public String brief();
public String detail();
public boolean unlockedByDefault();
public int rewardLogs();
public CollectibleDefinition withSource(String v);
public CollectibleDefinition withBrief(String v);
public CollectibleDefinition withDetail(String v);
public CollectibleDefinition withUnlockedByDefault(boolean v);
public CollectibleDefinition withRewardLogs(int v);
public boolean equals(Object o);
public int hashCode();
public String toString();
}of(name)
签名：
public static CollectibleDefinition of(String name);行为：最小构造，等价于 new CollectibleDefinition(name, "", "", "", false, 0)。name 会经紧凑构造归一与校验（见下）。
示例：
CollectibleDefinition base = CollectibleDefinition.of("首次通关");name()
签名：
public String name();行为：返回显示名（必填）。紧凑构造会先 trim；null 归一为空串后同样被拒绝，因此已构造成功的实例 name() 永远非空。
示例：
String title = def.name();source()
签名：
String source();行为：返回来源标注。null 在构造期归一为空串；该字段不做 trim。
示例：
String from = def.source();brief()
签名：
String brief();行为：返回侧面板短简介。null 归一为空串。
示例：
String summary = def.brief();detail()
签名：
String detail();行为：返回悬浮面板详情，支持 \n 换行。null 归一为空串。
示例：
String body = def.detail();unlockedByDefault()
签名：
boolean unlockedByDefault();行为：为 true 时玩家进入收集品场景即可见；为 false 时需模组在运行期调用 ModContext.unlockCollect(id) 解锁（id = 注册键的 path）。
示例：
boolean visible = def.unlockedByDefault();rewardLogs()
签名：
int rewardLogs();行为：返回阅读后给予的日志货币数量。紧凑构造拒绝负值（IllegalArgumentException），因此该值恒 >= 0。
示例：
int logs = def.rewardLogs();withSource(v) / withBrief(v) / withDetail(v)
签名：
public CollectibleDefinition withSource(String v);
public CollectibleDefinition withBrief(String v);
public CollectibleDefinition withDetail(String v);行为：各派生一个新实例，只替换对应字段，其余字段保持不变；原实例不受影响。v 为 null 时该字段归一为空串；派生同样走紧凑构造校验。
示例：
CollectibleDefinition def = CollectibleDefinition.of("星尘徽章")
.withSource("Stardust Mod")
.withBrief("收集 100 个星尘音符")
.withDetail("在任意谱面中累计触发 100 次星尘音符。");withUnlockedByDefault(v)
签名：
public CollectibleDefinition withUnlockedByDefault(boolean v);行为：派生一个新实例并替换默认可见性，其余字段保持不变。
示例：
CollectibleDefinition shown = def.withUnlockedByDefault(true);withRewardLogs(v)
签名：
public CollectibleDefinition withRewardLogs(int v);行为：派生一个新实例并替换日志奖励；v < 0 抛 IllegalArgumentException（校验发生在派生时，原实例保持可用）。
示例：
CollectibleDefinition rewarded = def.withRewardLogs(20);equals(o) / hashCode() / toString()
签名：
public boolean equals(Object o);
public int hashCode();
public String toString();行为：记录（record）的默认实现：equals / hashCode 基于全部六个组件（值相等即相等），toString 输出 CollectibleDefinition[name=..., source=..., ...]。注册表的重复判定与身份无关（按注册键的 location 判重），因此不要用记录相等性推断「是否已注册」。
示例：
CollectibleDefinition a = CollectibleDefinition.of("A").withRewardLogs(5);
CollectibleDefinition b = CollectibleDefinition.of("A").withRewardLogs(5);
boolean same = a.equals(b); // true：同一组组件值线程：源码未声明额外线程约束（不可变值对象，可跨线程共享）。
生命周期阶段：在 onPreInit 内构造并注册；解锁时机由模组在运行期经 ModContext.unlockCollect(id) 决定。
稳定性：2.0 起冻结：2.x 内只增不破（禁止删签名 / 改签名 / 改语义）。