RarityCore API Documentation

For version 1.21.1 (Ver.13)

Maven Dependency

Recommended: Modrinth Maven (no authentication required)

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

dependencies {
    implementation "maven.modrinth:raritycore:<version>"
}

Alternative: GitHub Packages (requires token)

repositories {
    mavenCentral()
    maven {
        url = "https://maven.pkg.github.com/Yanbwe/RarityCore"
        credentials {
            username = "your-github-username"
            password = "your-github-personal-access-token"
        }
    }
}

dependencies {
    implementation "org.yanbwe:raritycore:1211.<version>"
}

Token requires read:packages scope. Store credentials in ~/.gradle/gradle.properties:

gpr.user=your-github-username
gpr.key=your-personal-access-token

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);
int r2 = RarityCoreAPI.getNormalizedRarity(item);  // also accepts Item

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

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

// Check if item has a configured rarity
boolean has1 = RarityCoreAPI.hasConfiguredRarity(item);
boolean has2 = RarityCoreAPI.hasConfiguredRarity(item, itemStack);  // includes component check

// 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.MIN_RARITY       // 1 (lowest tier)
RarityCoreAPI.MAX_RARITY       // 7 (number of built-in preset tiers, not a rarity cap)
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();
}

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