稀有度核心 API 文档

适用于 1.20.1 版本 (Ver.13)

自 Ver.13 起,RarityCore 提供统一的正式 API 入口 RarityCoreAPI,供其他模组直接调用。旧的分散式 API 类仍可使用,但推荐迁移到新 API。

正式 API: RarityCoreAPI

包路径: org.yanbwe.raritycore.api.RarityCoreAPI

稀有度注册与查询

// 注册物品稀有度 (1+,同步到客户端)
RarityCoreAPI.registerRarity(item, 5);

// 注册物品稀有度 (可选是否同步)
RarityCoreAPI.registerRarity(item, 5, true);

// 删除物品稀有度
RarityCoreAPI.unregisterRarity(item);

// 获取 ItemStack 的稀有度
int rarity = RarityCoreAPI.getRarity(itemStack);

// 获取 Item 的稀有度
int rarity = RarityCoreAPI.getRarity(item);

// 获取标准化稀有度 (<1→1, >7→7,推荐使用)
int r = RarityCoreAPI.getNormalizedRarity(itemStack);

// 获取本地化工具提示
String tip = RarityCoreAPI.getLocalizedTooltip(itemStack);

// 检查物品是否有已配置的稀有度
boolean has = RarityCoreAPI.hasConfiguredRarity(item, itemStack);

// 获取所有已注册的稀有度映射 (只读)
Map<ResourceLocation, Integer> map = RarityCoreAPI.getRegistryMap();

颜色

// 获取 RarityClientConfig 中定义的逐级 RGB 颜色
int rgb = RarityCoreAPI.getRarityColor(5);

// 获取默认 RGB 颜色 (不含 alpha)
int rgb = RarityCoreAPI.getRarityRgbColor(3);

// 获取逐级纹理路径
String tex = RarityCoreAPI.getRarityTexture(5);

// 解析 "#RRGGBB" 字符串为 RGB int
int rgb = RarityCoreAPI.parseColor("#FFAA00");

// RGB int 格式化为 "#RRGGBB"
String hex = RarityCoreAPI.formatColor(0xFFAA00);

验证

RarityCoreAPI.isValidRarity(5);   // true
RarityCoreAPI.normalizeRarity(10); // 7

Tag 稀有度

// 获取物品匹配的 Tag 规则最高稀有度 (0=无匹配)
int r = RarityCoreAPI.getTagRarity(item);

// 已加载的 Tag 规则数量
int count = RarityCoreAPI.getTagRuleCount();

配置开关

// 客户端主开关
RarityCoreAPI.isBorderRenderingEnabled();
RarityCoreAPI.isTooltipInsertEnabled();
RarityCoreAPI.isNameColorEnabled();

// 逐级开关 (RarityClientConfig)
RarityCoreAPI.isLevelRendererEnabled(5);
RarityCoreAPI.isLevelTooltipEnabled(5);
RarityCoreAPI.isLevelNameColorEnabled(5);

// NBT 稀有度控制
RarityCoreAPI.isNbtRarityControlEnabled();

网络同步

RarityCoreAPI.syncToClients();

常量

RarityCoreAPI.RARITY_COMMON    // 1
RarityCoreAPI.RARITY_UNCOMMON  // 2
RarityCoreAPI.RARITY_RARE      // 3
RarityCoreAPI.RARITY_EPIC      // 4
RarityCoreAPI.RARITY_LEGENDARY // 5
RarityCoreAPI.RARITY_MYTHICAL  // 6
RarityCoreAPI.RARITY_UNIQUE    // 7
RarityCoreAPI.MIN_RARITY       // 1
RarityCoreAPI.MAX_RARITY       // 7
RarityCoreAPI.DEFAULT_RGB_COLOR // 0xCCCCCC

稀有度解析优先级

NBT 控制 (raritycore:data.Level>0)  ← 最高
  ↓
NBT 匹配规则
  ↓
Apotheosis / Iron's Spellbooks
  ↓
ITEM_RARITY_MAP (FinalRarity.json)
  ↓
TagRarity (TagRarity.json)
  ↓
AUTO_RARITY_MAP
  ↓
原版 getRarity()

旧版 API 类 (仍可用)

以下类在 Ver.13 中仍可用,但推荐迁移到 RarityCoreAPI:

旧类	新替代
RarityRegistry.register()	RarityCoreAPI.registerRarity()
RarityRegistry.getRarity()	RarityCoreAPI.getRarity()
RarityColorUtil.getRarityRgbColor()	RarityCoreAPI.getRarityRgbColor()
RarityValidator.normalizeRarity()	RarityCoreAPI.normalizeRarity()
ClientConfigManager.isEnable*()	RarityCoreAPI.is*Enabled()

事件

RarityCore 提供以下 Forge 事件,其他模组可通过 MinecraftForge.EVENT_BUS 监听:

RarityChangeEvent

物品稀有度被注册/更新/删除时触发。

@SubscribeEvent
public void onRarityChange(RarityChangeEvent event) {
    Item item = event.getItem();
    int oldRarity = event.getOldRarity();
    int newRarity = event.getNewRarity();
    String type = event.getChangeType(); // "register"/"update"/"remove"
}

RarityQueryEvent

查询物品稀有度时触发,可修改返回值。

@SubscribeEvent
public void onRarityQuery(RarityQueryEvent event) {
    ItemStack stack = event.getItemStack();
    int rarity = event.getRarity();   // 当前结果
    event.setRarity(5);               // 修改结果
    String source = event.getSource(); // "registry"/"nbt"/"tag"等
}

RarityTooltipEvent

工具提示构建时触发,可追加自定义文本。

@SubscribeEvent
public void onRarityTooltip(RarityTooltipEvent event) {
    event.getTooltipList().add(Component.literal("自定义信息"));
    int rarity = event.getRarity();
    boolean special = event.isSpecialRarity(); // >7?
}

使用示例

import org.yanbwe.raritycore.api.RarityCoreAPI;
import net.minecraft.world.item.Items;

// 注册
RarityCoreAPI.registerRarity(Items.DIAMOND_SWORD, 5);

// 查询
int r = RarityCoreAPI.getNormalizedRarity(new ItemStack(Items.DIAMOND_SWORD));
// r = 5

// 颜色
int rgb = RarityCoreAPI.getRarityColor(5); // 0xFFCC00 (亮金色)