唱片元数据 API

基本信息

属性 值
接口 com.gtnewhorizon.gtnhlib.api.MusicRecordMetadataProvider
源码 src/main/java/com/gtnewhorizon/gtnhlib/api/MusicRecordMetadataProvider.java
实现前提 继承 net.minecraft.item.ItemRecord
注册方 无注册表，由 mod 自行在 ItemRecord 子类上实现

功能

为自定义唱片物品提供 NBT 感知的音乐元数据查询，供实现自定义唱片机的 mod 使用。原版 ItemRecord 只有一个 recordName 字段，无法表达"同一物品靠 NBT 区分曲目"。

源码注释（MusicRecordMetadataProvider.java:6-9）：

Implement on classes extending ItemRecord to provide metadata and NBT-aware versions of the standard music metadata for use by other mods that implement custom jukeboxes.

两个方法都是 default：

方法 默认行为 说明
getMusicRecordResource(ItemStack) 校验 stack.getItem() == this 后返回 self.getRecordResource(self.recordName) 返回该 ItemStack 播放的音效 ResourceLocation，无则 null
getMusicRecordVariants() Collections.singleton(new ItemStack((ItemRecord) this, 1, 0)) 该物品所有可播放变体的 ItemStack 列表

默认实现下行为与原版一致；只有需要 NBT 区分曲目、或一个物品含多首曲子时才需覆写。

数值

数值名 值
接口方法数 2
抽象方法数 0（全部有 default 实现）
默认变体数 1（meta = 0）
GTNHLib 内置实现 0（纯供下游 mod 实现的接口）

getMusicRecordResource 的默认实现有两层短路（MusicRecordMetadataProvider.java:18-25）：stack == null 或 stack.getItem() != this 时直接返回 null，因此调用方无需自行判空或比对物品。

交互

自定义唱片机读取物品时：

  1. 调 getMusicRecordResource(stack) 拿到音效资源
  2. 调 getMusicRecordVariants() 枚举该物品的全部可播放变体，用于 GUI 列表

返回 null 表示该 ItemStack 不含可播放音乐，调用方应跳过。

相关条目