稀有度核心 API 文档

适用于 1.20.1 版本 (Ver.14)

Maven 依赖

推荐：Modrinth Maven（无需身份验证）

repositories {
    mavenCentral()
    maven {
        name = "Modrinth"
        url = "https://api.modrinth.com/maven"
        content {
            includeGroup "maven.modrinth"
        }
    }
}

dependencies {
    implementation fg.deobf("maven.modrinth:raritycore:1201.14.0")
}

备选：GitHub Packages（需要 Token）

repositories {
    mavenCentral()
    maven {
        url = "https://maven.pkg.github.com/Yanbwe/RarityCore"
        credentials {
            username = "你的GitHub用户名"
            password = "你的GitHub Personal Access Token"
        }
    }
}

dependencies {
    implementation fg.deobf("org.yanbwe:raritycore:1201.14.0")
}

Token 需要 read:packages 权限，可在 ~/.gradle/gradle.properties 中配置：

gpr.user=你的GitHub用户名
gpr.key=你的Personal Access Token

自 Ver.13 起,RarityCore 提供统一的正式 API 入口 RarityCoreAPI,供其他模组直接调用。Ver.14 在视觉表现配置上新增了逐级读写能力,并将主开关直连到 RarityStyleConfigManager。旧的分散式 API 类仍可使用,但推荐迁移到新 API。

Ver.13 的 API 指南已归档于 API 1.20.1（旧版）。

正式 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);

// 获取本地化工具提示 (Item 重载)
String tip = RarityCoreAPI.getLocalizedTooltip(item);

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

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

颜色

// 获取逐级 RGB 颜色 (来自 RarityStyle)
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();

主开关查询 (Ver.14 直连 RarityStyleConfigManager)

RarityCoreAPI.isBorderEnabled();        // 是否渲染物品边框
RarityCoreAPI.isTooltipEnabled();       // 是否插入工具提示
RarityCoreAPI.isTooltipColorEnabled();  // 工具提示是否染色
RarityCoreAPI.isBorderRenderingEnabled(); // 同 isBorderEnabled()
RarityCoreAPI.isTooltipInsertEnabled();   // 同 isTooltipEnabled()
RarityCoreAPI.isNameColorEnabled();       // 是否变色物品名称

无稀有度回退查询

RarityCoreAPI.isNoRaritySkip();         // 无稀有度物品是否跳过渲染
RarityCoreAPI.getNoRarityDefaultRarity(); // 无稀有度物品兜底等级 (默认 1)

逐级视觉表现查询

// 工具提示内容
String content = RarityCoreAPI.getTooltipContent(5);
// level 段翻译键 / 回退键
String key    = RarityCoreAPI.getLevelTranslationKey(5);
String fbKey  = RarityCoreAPI.getLevelFallbackKey(5);
// 星星配置 (StarSegmentConfig: colored / mode / repeatChar / custom)
RarityCoreAPI.StarSegmentConfig star = RarityCoreAPI.getStarConfig(5);

// 边框逐级配置
boolean useTex = RarityCoreAPI.isBorderUseTexture(5); // 该等级是否使用纹理
int borderStyle = RarityCoreAPI.getBorderStyle(5);     // 1=实心, 0=空心
String fallback = RarityCoreAPI.getBorderFallback();   // 边框回退纹理

逐级开关 (继承现状)

RarityCoreAPI.isLevelRendererEnabled(5); // 该等级是否渲染边框
RarityCoreAPI.isLevelTooltipEnabled(5);  // 该等级是否显示工具提示
RarityCoreAPI.isLevelNameColorEnabled(5); // 该等级是否变色名称

视觉表现写入 (Ver.14 新增)

所有写入方法会即时保存至 RarityStyle.json。

// 主开关
RarityCoreAPI.setBorderEnabled(true);
RarityCoreAPI.setTooltipEnabled(true);
RarityCoreAPI.setTooltipColorEnabled(true);

// 无稀有度回退
RarityCoreAPI.setNoRaritySkip(false);
RarityCoreAPI.setNoRarityDefaultRarity(1);

// 逐级边框
RarityCoreAPI.setBorderUseTexture(5, true);
RarityCoreAPI.setBorderStyle(5, 1);

// 逐级工具提示 / 星星
RarityCoreAPI.setTooltipContent(5, "[@{level}] @{star}");
RarityCoreAPI.setStarMode(5, "repeat");
RarityCoreAPI.setStarRepeatChar(5, "★");

NBT 稀有度控制

RarityCoreAPI.isNbtRarityControlEnabled();

集合查询

// 返回匹配任一指定等级的全部物品
List<Item> items = RarityCoreAPI.getItemsByRarities(Set.of(5, 6));
// 返回该等级的物品数量
int n = RarityCoreAPI.getRarityCount(5);
// 返回全部已解析稀有度等级快照（显式配置与自动计算合并）
Map<ResourceLocation, Integer> all = RarityCoreAPI.getAllRarityEntries();

视觉表现批量写入与诊断

// 批量写入期间 setter 不逐条写盘，结束时统一保存并发布一次事件
RarityCoreAPI.beginStyleBatch();
RarityCoreAPI.setBorderStyle(5, 0);
RarityCoreAPI.setStarRepeatChar(5, "✦");
RarityCoreAPI.endStyleBatch();

// 以结构化补丁整体写入某等级（null 字段保留现有值）
RarityStyleConfigManager.StylePatch patch = new RarityStyleConfigManager.StylePatch();
patch.rarity = 5;
patch.borderStyle = 1;
RarityCoreAPI.setStyle(patch);

// 校验并标准化等级（越界时记录告警并返回边界值）
int r = RarityCoreAPI.validateRarity(10); // 7

// 返回某等级生效视觉表现的不可变快照
RarityStyleConfigManager.StyleSnapshot snap = RarityCoreAPI.getStyleSnapshot(5);

API 版本与可用性

int apiVer = RarityCoreAPI.API_VERSION;   // 正式 API 版本号
String ver = RarityCoreAPI.getModVersion(); // 模组版本号
int cfgVer = RarityCoreAPI.getConfigVersion(); // 当前配置版本号
boolean ok = RarityCoreAPI.isAvailable();     // 模组是否可用

网络同步

RarityCoreAPI.syncToClients();

常量

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()

批量注册

// 批量注册物品稀有度（注册结束后统一同步一次）
Map<Item, Integer> entries = new HashMap<>();
entries.put(Items.DIAMOND_SWORD, 5);
entries.put(Items.NETHERITE_INGOT, 5);
RarityCoreAPI.registerRarities(entries);

稀有度物品查询

// 返回被解析为指定等级的全部物品（遍历物品注册表，覆盖配置/自动/原版/联动来源）
List<Item> items = RarityCoreAPI.getItemsByRarity(5);
// 返回该等级的物品 ID 列表
List<ResourceLocation> ids = RarityCoreAPI.getItemIdsByRarity(5);
// 返回当前出现过的稀有度等级集合
Set<Integer> rarities = RarityCoreAPI.getConfiguredRarities();

配置重载

// 触发完整配置重载（命令源为空，视为程序化触发）
RarityCoreAPI.reloadConfigs();

旧版 API 类 (仍可用)

以下类仍可用,但推荐迁移到 RarityCoreAPI:

旧类	新替代
RarityRegistry.register()	RarityCoreAPI.registerRarity()
RarityRegistry.getRarity()	RarityCoreAPI.getRarity()
RarityColorUtil.getRarityRgbColor()	RarityCoreAPI.getRarityRgbColor()
RarityValidator.normalizeRarity()	RarityCoreAPI.normalizeRarity()

ClientConfigManager 的旧委托方法仍作为内部桥接保留,公共调用请使用 RarityCoreAPI。

事件

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

RarityChangeEvent

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

@SubscribeEvent
public void onRarityChange(RarityChangeEvent event) {
    Item item = event.getItem();
    int oldRarity = event.getOldRarity();
    int newRarity = event.getNewRarity();
    ChangeType 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) {
    ItemStack stack = event.getItemStack();
    event.getTooltipList().add(Component.literal("自定义信息"));
    int rarity = event.getRarity();
}

RarityConfigReloadEvent

配置整体重载完成后触发，分为客户端侧重载与服务端重载。

@SubscribeEvent
public void onClientReload(RarityConfigReloadEvent.Client event) {
    boolean startup = event.isStartup();       // 是否启动时的自动重载
    CommandSourceStack src = event.getSource(); // 命令源，可能为 null
}

@SubscribeEvent
public void onServerReload(RarityConfigReloadEvent.Server event) {
    // 全部配置重载完成
}

RarityStyleChangedEvent

通过 API 写入并持久化某项视觉表现配置后触发，便于监听方刷新缓存与渲染。

@SubscribeEvent
public void onStyleChanged(RarityStyleChangedEvent event) {
    int rarity = event.getRarity();                              // 受影响等级（0=全局/无稀有度回退）
    RarityStyleChangedEvent.ChangeTarget t = event.getTarget();  // BORDER_ENABLED / BORDER_STYLE 等
}

RarityStyleReloadEvent

RarityStyle 配置被文件改动并重新加载后触发（区别于 API 写入触发的 RarityStyleChangedEvent）。

@SubscribeEvent
public void onStyleReload(RarityStyleReloadEvent event) {
    int rarity = event.getRarity();   // 受影响等级（负数=全等级）
    boolean ext = event.isExternal(); // 是否由文件外部改动触发
}

RarityRegistryChangedEvent

批量注册或整体重载后一次性发布本次全部变更，避免逐条触发 RarityChangeEvent。

@SubscribeEvent
public void onRegistryChanged(RarityRegistryChangedEvent event) {
    for (var e : event.getChanges().entrySet()) {
        ResourceLocation id = e.getKey();
        Integer oldR = e.getValue().oldRarity; // 移除时为空
        Integer newR = e.getValue().newRarity; // 新增时为空
    }
}

使用示例

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 (亮金色)

// 通过 API 改写逐级视觉表现
RarityCoreAPI.setBorderStyle(5, 0);          // 5 级改用空心边框
RarityCoreAPI.setStarRepeatChar(5, "✦");     // 5 级改用自定义星标字符