RarityCore API Documentation

For version 1.21.1 (Ver.13)

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

Formal API: RarityCoreAPI

Package path: org.yanbwe.raritycore.api.RarityCoreAPI

Rarity Registration & Queries

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

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

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

// Get ItemStack rarity (full priority chain)
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(item);

// Get read-only registry map
Map<ResourceLocation, Integer> map = RarityCoreAPI.getRegistryMap();

// Prune invalid entries
int removed = RarityCoreAPI.pruneInvalidEntries();

Colors

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

// Get per-rarity texture path
String tex = RarityCoreAPI.getTexture(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
RarityCoreAPI.normalizeRarity(0);  // 1

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

Per-level Switches (RarityClientConfig)

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

Component Rarity Control

// Whether DataComponent rarity control is enabled
RarityCoreAPI.isComponentRarityControlEnabled();

// Read raritycore rarity from item's CUSTOM_DATA (returns 0 if Level=0)
int level = RarityCoreAPI.getComponentRarity(itemStack);

Network Sync

// Full sync
RarityCoreAPI.syncToClients();

// Full sync with retry
RarityCoreAPI.syncToClientsWithRetry();

// Incremental sync
RarityCoreAPI.syncIncrementalChangesToClients();

// Pending change count
int pending = RarityCoreAPI.getPendingChangeCount();

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
RarityCoreAPI.MIN_RARITY       // 1
RarityCoreAPI.MAX_RARITY       // 7
RarityCoreAPI.DEFAULT_RGB_COLOR // 0xCCCCCC

Rarity Priority Chain

Component Control (CUSTOM_DATA.raritycore.Level>0)  ← Highest
  ↓
Item Data Matching
  ↓
Apotheosis Adapter
  ↓
Iron's Spells Adapter
  ↓
ITEM_RARITY_MAP (FinalRarity.json + datapacks)
  ↓
TagRarity (TagRarity.json)
  ↓
AUTO_RARITY_MAP (auto-calculated)
  ↓
Vanilla getRarity()

Legacy API Classes (Still Available)

Old Class	New Replacement
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()

Events

RarityCore provides the following NeoForge events, listenable via NeoForge.EVENT_BUS:

RarityChangeEvent

Fired when item rarity is registered/updated/removed.

@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

Fired during rarity lookup, allows overriding the result. Implements ICancellableEvent.

@SubscribeEvent
public void onRarityQuery(RarityQueryEvent event) {
    ItemStack stack = event.getItemStack();
    int rarity = event.getOriginalRarity(); // current result
    event.setOverriddenRarity(5);            // override
    event.setCanceled(true);                 // must cancel for override to take effect
    String source = event.getSource();        // component/itemdata/apotheosis/ironspells/itemmap/tag/autorarity/vanilla/default
}

RarityTooltipEvent

Fired during tooltip construction, allows appending custom text.

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

Usage Examples

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

// Register
RarityCoreAPI.registerRarity(Items.DIAMOND_SWORD, 5);

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

// Color
int rgb = RarityCoreAPI.getColor(5); // 0xFFCC00 (bright gold)

// Export command
// /raritycore export rarity 5  → export all legendary items to JSON

// Edit mode
// /raritycore edit toggle true    → enable edit mode
// /raritycore edit mode fullmatch → switch to full match mode
// Then shift+right-click any item to edit