RarityCore API Documentation

For 1.20.1 version (Ver.14)

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 fg.deobf("maven.modrinth:raritycore:1201.14.0")
}

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 fg.deobf("org.yanbwe:raritycore:1201.14.0")
}

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 point RarityCoreAPI for other mods to use directly. Ver.14 adds per-level read/write capabilities for visual styling and connects the master switches directly to RarityStyleConfigManager. The old distributed API classes are still available but migration to the new API is recommended.

The Ver.13 API guide is archived at API 1.20.1 (Legacy).

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, not 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 RarityStyle)
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();

Master Switch Queries (Ver.14, direct to RarityStyleConfigManager)

RarityCoreAPI.isBorderEnabled();        // whether to render item borders
RarityCoreAPI.isTooltipEnabled();       // whether to insert tooltips
RarityCoreAPI.isTooltipColorEnabled();  // whether tooltips are colored
RarityCoreAPI.isBorderRenderingEnabled(); // same as isBorderEnabled()
RarityCoreAPI.isTooltipInsertEnabled();   // same as isTooltipEnabled()
RarityCoreAPI.isNameColorEnabled();       // whether item names are colored

No-Rarity Fallback Queries

RarityCoreAPI.isNoRaritySkip();           // skip rendering for unconfigured items
RarityCoreAPI.getNoRarityDefaultRarity(); // fallback rarity for unconfigured items (default 1)

Per-Level Visual Style Queries

// Tooltip content
String content = RarityCoreAPI.getTooltipContent(5);
// level segment translation key / fallback key
String key   = RarityCoreAPI.getLevelTranslationKey(5);
String fbKey = RarityCoreAPI.getLevelFallbackKey(5);
// Star config (StarSegmentConfig: colored / mode / repeatChar / custom)
RarityCoreAPI.StarSegmentConfig star = RarityCoreAPI.getStarConfig(5);

// Per-level border config
boolean useTex = RarityCoreAPI.isBorderUseTexture(5); // whether this level uses texture
int borderStyle = RarityCoreAPI.getBorderStyle(5);    // 1=solid, 0=hollow
String fallback = RarityCoreAPI.getBorderFallback();  // border fallback texture

Per-Level Switches (inherited state)

RarityCoreAPI.isLevelRendererEnabled(5); // whether this level renders border
RarityCoreAPI.isLevelTooltipEnabled(5);  // whether this level shows tooltip
RarityCoreAPI.isLevelNameColorEnabled(5); // whether this level colors name

Visual Style Writes (New in Ver.14)

All write methods persist immediately to RarityStyle.json.

// Master switches
RarityCoreAPI.setBorderEnabled(true);
RarityCoreAPI.setTooltipEnabled(true);
RarityCoreAPI.setTooltipColorEnabled(true);

// No-rarity fallback
RarityCoreAPI.setNoRaritySkip(false);
RarityCoreAPI.setNoRarityDefaultRarity(1);

// Per-level border
RarityCoreAPI.setBorderUseTexture(5, true);
RarityCoreAPI.setBorderStyle(5, 1);

// Per-level tooltip / star
RarityCoreAPI.setTooltipContent(5, "[@{level}] @{star}");
RarityCoreAPI.setStarMode(5, "repeat");
RarityCoreAPI.setStarRepeatChar(5, "★");

NBT Rarity Control

RarityCoreAPI.isNbtRarityControlEnabled();

Collection Queries

// All items resolved to any of the given levels
List<Item> items = RarityCoreAPI.getItemsByRarities(Set.of(5, 6));
// Count of items resolved to the given level
int n = RarityCoreAPI.getRarityCount(5);
// Snapshot of all resolved rarity levels (explicit + auto)
Map<ResourceLocation, Integer> all = RarityCoreAPI.getAllRarityEntries();

Style Batch Writes & Diagnostics

// During batch, setters skip per-write disk writes; save and emit once at end
RarityCoreAPI.beginStyleBatch();
RarityCoreAPI.setBorderStyle(5, 0);
RarityCoreAPI.setStarRepeatChar(5, "✦");
RarityCoreAPI.endStyleBatch();

// Write a whole level with a structured patch (null fields keep current values)
RarityStyleConfigManager.StylePatch patch = new RarityStyleConfigManager.StylePatch();
patch.rarity = 5;
patch.borderStyle = 1;
RarityCoreAPI.setStyle(patch);

// Validate and normalize a level (logs a warning and clamps when out of range)
int r = RarityCoreAPI.validateRarity(10); // 7

// Immutable snapshot of a level's effective visual style
RarityStyleConfigManager.StyleSnapshot snap = RarityCoreAPI.getStyleSnapshot(5);

API Version & Availability

int apiVer = RarityCoreAPI.API_VERSION;       // formal API version
String ver = RarityCoreAPI.getModVersion();    // mod version
int cfgVer = RarityCoreAPI.getConfigVersion(); // current config version
boolean ok = RarityCoreAPI.isAvailable();     // whether the mod is available

Network Sync

RarityCoreAPI.syncToClients();

Constants

RarityCoreAPI.MIN_RARITY       // 1 (lowest tier)
RarityCoreAPI.MAX_RARITY       // 7 (number of built-in preset tiers, not a rarity cap)

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

Batch Registration

// Batch register item rarities (one sync after all entries)
Map<Item, Integer> entries = new HashMap<>();
entries.put(Items.DIAMOND_SWORD, 5);
entries.put(Items.NETHERITE_INGOT, 5);
RarityCoreAPI.registerRarities(entries);

Rarity Item Queries

// All items resolved to the given level (scans item registry; covers config/auto/vanilla/compat sources)
List<Item> items = RarityCoreAPI.getItemsByRarity(5);
// Item IDs resolved to the given level
List<ResourceLocation> ids = RarityCoreAPI.getItemIdsByRarity(5);
// Distinct rarity levels currently present
Set<Integer> rarities = RarityCoreAPI.getConfiguredRarities();

Config Reload

// Trigger a full config reload (no command source, treated as programmatic)
RarityCoreAPI.reloadConfigs();

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"));
}

RarityConfigReloadEvent

Fires after a full config reload completes, split into a client-side reload and a server reload.

@SubscribeEvent
public void onClientReload(RarityConfigReloadEvent.Client event) {
    boolean startup = event.isStartup();       // whether this is the startup auto-reload
    CommandSourceStack src = event.getSource(); // command source, may be null
}

@SubscribeEvent
public void onServerReload(RarityConfigReloadEvent.Server event) {
    // full config reload finished
}

RarityStyleChangedEvent

Fires after a visual style config is written and persisted via the API, so listeners can refresh caches/rendering.

@SubscribeEvent
public void onStyleChanged(RarityStyleChangedEvent event) {
    int rarity = event.getRarity();                             // affected level (0 = global / no-rarity fallback)
    RarityStyleChangedEvent.ChangeTarget t = event.getTarget(); // BORDER_ENABLED / BORDER_STYLE etc.
}

RarityStyleReloadEvent

Fires after the RarityStyle config is reloaded from file changes (distinct from RarityStyleChangedEvent which fires on API writes).

@SubscribeEvent
public void onStyleReload(RarityStyleReloadEvent event) {
    int rarity = event.getRarity();    // affected level (negative = all levels)
    boolean ext = event.isExternal();  // whether triggered by external file change
}

RarityRegistryChangedEvent

Fires once after batch registration or a full reload, carrying all changes, avoiding per-entry RarityChangeEvent posts.

@SubscribeEvent
public void onRegistryChanged(RarityRegistryChangedEvent event) {
    for (var e : event.getChanges().entrySet()) {
        ResourceLocation id = e.getKey();
        Integer oldR = e.getValue().oldRarity; // null when removed
        Integer newR = e.getValue().newRarity; // null when added
    }
}

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)

// Rewrite per-level visual style via API
RarityCoreAPI.setBorderStyle(5, 0);       // level 5 uses hollow border
RarityCoreAPI.setStarRepeatChar(5, "✦");  // level 5 uses custom star char