RarityCore API Documentation (Legacy)

For 1.20.1 version (Ver.13, archived)

This is the Ver.13 API guide, archived and no longer updated. The Ver.14 API guide is at API 1.20.1.

Since Ver.13, RarityCore provides a unified formal API entry point RarityCoreAPI for other mods to use directly. The old distributed API classes are still available but migration to the new API is recommended.

Formal API: RarityCoreAPI

Package: org.yanbwe.raritycore.api.RarityCoreAPI

Rarity Registration & Query

// Register item rarity (1+, sync to clients)
RarityCoreAPI.registerRarity(item, 5);

// Register item rarity (optional sync)
RarityCoreAPI.registerRarity(item, 5, true);

// Remove item rarity
RarityCoreAPI.unregisterRarity(item);

// Get ItemStack rarity
int rarity = RarityCoreAPI.getRarity(itemStack);

// Get Item rarity
int rarity = RarityCoreAPI.getRarity(item);

// Get normalized rarity (<1→1, >7→7, recommended)
int r = RarityCoreAPI.getNormalizedRarity(itemStack);

// Get normalized rarity (Item overload)
int r = RarityCoreAPI.getNormalizedRarity(item);

// Get localized tooltip
String tip = RarityCoreAPI.getLocalizedTooltip(itemStack);

// Get localized tooltip (Item overload)
String tip = RarityCoreAPI.getLocalizedTooltip(item);

// Check if item has configured rarity
boolean has = RarityCoreAPI.hasConfiguredRarity(item, itemStack);

// Get all registered rarity mappings (read-only)
Map<ResourceLocation, Integer> map = RarityCoreAPI.getRegistryMap();

Colors

// Get per-level RGB color from RarityClientConfig
int rgb = RarityCoreAPI.getRarityColor(5);

// Get default RGB color (no alpha)
int rgb = RarityCoreAPI.getRarityRgbColor(3);

// Get per-level texture path
String tex = RarityCoreAPI.getRarityTexture(5);

// Parse "#RRGGBB" string to RGB int
int rgb = RarityCoreAPI.parseColor("#FFAA00");

// Format RGB int to "#RRGGBB"
String hex = RarityCoreAPI.formatColor(0xFFAA00);

Validation

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

Tag Rarity

// Get highest tag rule rarity for item (0=no match)
int r = RarityCoreAPI.getTagRarity(item);

// Number of loaded tag rules
int count = RarityCoreAPI.getTagRuleCount();

Config Switches

// Client master switches
RarityCoreAPI.isBorderRenderingEnabled();
RarityCoreAPI.isTooltipInsertEnabled();
RarityCoreAPI.isNameColorEnabled();

// Per-level switches (RarityClientConfig)
RarityCoreAPI.isLevelRendererEnabled(5);
RarityCoreAPI.isLevelTooltipEnabled(5);
RarityCoreAPI.isLevelNameColorEnabled(5);

// NBT rarity control
RarityCoreAPI.isNbtRarityControlEnabled();

Network Sync

RarityCoreAPI.syncToClients();

Constants

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

Rarity Resolution Priority

NBT control (raritycore:data.Level>0)  ← Highest
  ↓
NBT match rules
  ↓
Apotheosis / Iron's Spellbooks
  ↓
ITEM_RARITY_MAP (FinalRarity.json)
  ↓
TagRarity (TagRarity.json)
  ↓
AUTO_RARITY_MAP
  ↓
Vanilla getRarity()

Events

RarityChangeEvent

Fires when item rarity is registered/updated/removed.

@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

Fires when rarity is queried, allows modifying the result.

@SubscribeEvent
public void onRarityQuery(RarityQueryEvent event) {
    event.setRarity(5); // modify result
}

RarityTooltipEvent

Fires during tooltip building, allows adding custom text.

@SubscribeEvent
public void onRarityTooltip(RarityTooltipEvent event) {
    ItemStack stack = event.getItemStack();
    event.getTooltipList().add(Component.literal("Custom info"));
}

Example

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)); // 5
int rgb = RarityCoreAPI.getRarityColor(5); // 0xFFCC00 (bright gold)