稀有度核心 API 文档

适用于 1.21.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(item);

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

// 清理无效条目
int removed = RarityCoreAPI.pruneInvalidEntries();

颜色

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

// 获取逐级纹理路径
String tex = RarityCoreAPI.getTexture(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
RarityCoreAPI.normalizeRarity(0);  // 1

Tag 稀有度

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

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

逐级开关 (RarityClientConfig)

RarityCoreAPI.isLevelRendererEnabled(5);
RarityCoreAPI.isLevelTooltipEnabled(5);
RarityCoreAPI.isLevelNameColorEnabled(5);

组件稀有度控制

// 检查是否开启了 DataComponent 稀有度控制
RarityCoreAPI.isComponentRarityControlEnabled();

// 从物品的 CUSTOM_DATA 中读取 raritycore 稀有度 (Level=0 时返回0)
int level = RarityCoreAPI.getComponentRarity(itemStack);

网络同步

// 全量同步
RarityCoreAPI.syncToClients();

// 带重试的全量同步
RarityCoreAPI.syncToClientsWithRetry();

// 增量同步
RarityCoreAPI.syncIncrementalChangesToClients();

// 待同步变更数
int pending = RarityCoreAPI.getPendingChangeCount();

常量

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

稀有度解析优先级

组件控制 (CUSTOM_DATA.raritycore.Level>0)  ← 最高
  ↓
Item Data 匹配规则
  ↓
Apotheosis 神化适配器
  ↓
Iron's Spells 法术适配器
  ↓
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.getRarityChatColor()	RarityCoreAPI.getColor()
RarityValidator.normalizeRarity()	RarityCoreAPI.normalizeRarity()
ClientConfigManager.isEnable*()	RarityCoreAPI.is*()
RarityClientConfig.getInstance().getColor()	RarityCoreAPI.getColor()

事件

RarityCore 提供以下 NeoForge 事件，其他模组可通过 NeoForge.EVENT_BUS 监听：

RarityChangeEvent

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

@SubscribeEvent
public void onRarityChange(RarityChangeEvent event) {
    Item item = event.getItem();
    Integer oldRarity = event.getOldRarity();
    Integer newRarity = event.getNewRarity();
    RarityChangeEvent.ChangeType type = event.getChangeType(); // REGISTER / UPDATE / REMOVE
}

RarityQueryEvent

查询物品稀有度时触发，可修改返回值。实现 ICancellableEvent。

@SubscribeEvent
public void onRarityQuery(RarityQueryEvent event) {
    ItemStack stack = event.getItemStack();
    int rarity = event.getOriginalRarity(); // 当前结果
    event.setOverriddenRarity(5);            // 覆盖为 5
    event.setCanceled(true);                 // 必须取消事件才生效
    String source = event.getSource();        // component/itemdata/apotheosis/ironspells/itemmap/tag/autorarity/vanilla/default
}

RarityTooltipEvent

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

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

使用示例

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

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

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

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

// 导出命令
// /raritycore export rarity 5  → 导出所有传说级物品到 JSON

// 编辑模式
// /raritycore edit toggle true    → 开启编辑模式
// /raritycore edit mode fullmatch → 切换到完全匹配模式
// 然后 shift+右键 任意物品即可编辑