RarityCore API Documentation

For 1.20.1 version (Ver.13)

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 localized tooltip
String tip = RarityCoreAPI.getLocalizedTooltip(itemStack);

// 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();
    String 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) {
    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)