QualityAPI

Not every sword is made equal. Quality API gives items, mobs and players a quality, from Crude to Masterwork, and that quality changes how they perform.

One shared quality for every mod: a forging mod, a loot mod and a skills mod all read and write the same tier. Everything is data driven, and every section below shows the datapack that sets it up.

Tier	Level	Stars
Crude	-1	½
Standard	0	1
Fine	1	1½
Superior	2	2
Exquisite	3	2½
Masterwork	4	3

Standard is the baseline and does nothing, so standard items behave exactly like plain ones. Rename, rebalance, add or replace tiers in a datapack. Tooltips show the tier's name, its stars, or both (each player picks with the qualityTooltipStyle client config), plus who crafted it. Every quality item also gets a small star in its tier's colour in the corner of its slot, so you can sort a chest at a glance without hovering anything. Don't want it? Turn off showQualityMarker, or list a tier in hiddenTooltipTiers to keep that tier's items looking plain.

Only the tier is stored on the item. Every bonus is computed live, so items already in the world follow your datapack: per-item overrides apply on /reload, and changed tier files once players rejoin.

Quality API also fixes one of the major issues with adding quality to itemstacks, inventory bloat. Each item with a different quality counts as a different itemstack. Now these qualities can stack together into one stack and a simple UI lets you easily break them back out.

---

Equipment

Weapons, armor and tools get real stats from their tier:

• Durability: masterwork lasts 1.6x as long, crude 0.75x.
• Attributes: more attack damage on blades, more armor on plate, or any attribute you like (speed, reach, luck, health).
• Mining speed on tools.
• Bonus enchantment levels: exquisite acts as Unbreaking I, masterwork as Unbreaking II, on top of real enchantments.
• Broken, not destroyed: at zero durability a quality item breaks and stays in your inventory until repaired. Breaking may cost a tier (75% by default), so a masterwork sword that breaks is usually exquisite once you've repaired it.
• Crafting carries it over: masterwork ingots make a masterwork pickaxe. Highest, lowest or average of the ingredients, and the grid shows the result before you craft.

Picture a village smith whose masterwork blades are worth the trip, a crude axe looted off a bandit that barely holds an edge, or ore you refine up the tiers before forging a tool you'll keep for the whole run.

Datapack: a new tier

data/mypack/quality_api/quality/legendary.json. Override a shipped tier by using its path, e.g. data/quality_api/quality_api/quality/masterwork.json.

{
  "level": 5,
  "color": "#FF55FF",
  "particle_color": "#FF55FF",
  "weight": 1,
  "items": "#c:tools",
  "effects": {
    "durability_multiplier": 2.0,
    "mining_speed_multiplier": 1.75,
    "enchantment_levels": { "minecraft:unbreaking": 3 },
    "break_downgrade_chance": 0.5,
    "attributes": [
      { "type": "minecraft:generic.attack_damage", "operation": "add_value", "amount": 3.0, "slot": "mainhand" }
    ]
  }
}

level orders tiers and sets the stars. particle_color makes mobs and players of this tier sparkle in that colour now and then. weight is how often random rolls pick it (0 = never rolled, only given). items optionally limits what it applies to. Name it in a resource pack: "quality.mypack.legendary": "Legendary".

Datapack: per item and per tag

data/quality_api/data_maps/item/item_qualities.json patches a tier for specific items or tags. Name only what changes; the tier file fills in the rest, and item entries beat tags.

{
  "values": {
    "#minecraft:pickaxes": {
      "quality_api:masterwork": { "mining_speed_multiplier": 3.0, "enchantment_levels": { "minecraft:fortune": 1 } }
    },
    "minecraft:netherite_sword": {
      "quality_api:masterwork": {
        "attributes": [ { "type": "minecraft:generic.attack_damage", "operation": "add_value", "amount": 6.0 } ]
      }
    }
  }
}

Equipment effect	Neutral value
durability_multiplier	1.0
mining_speed_multiplier	1.0
enchantment_levels	{}
attributes (type, operation, amount, optional slot)	[]
break_downgrade_chance	the config value
break_destroy_chance (break like vanilla)	0.0

Set a field to its neutral value to remove it for that item.

---

Food

A tier can change everything about eating:

• Nutrition and saturation
• Effect duration: a golden apple's regeneration lasts longer
• Extra effects, each with its own chance

Food has its own names too: Poor, Common, Fine, Choice, Prime, Gourmet. Picture a farmer's prized harvest that keeps you full twice as long, or a Gourmet stew that gives a burst of strength before a boss fight. The shipped tiers leave food alone until you turn it on. AppleSkin shows the real values.

Datapack: food bonuses

Same file as equipment, data/quality_api/data_maps/item/item_qualities.json:

{
  "values": {
    "#c:foods": {
      "quality_api:masterwork": {
        "nutrition_multiplier": 1.5,
        "saturation_multiplier": 1.5,
        "eat_effect_duration_multiplier": 2.0,
        "eat_effects": [ { "effect": "minecraft:regeneration", "duration": 100, "probability": 0.5 } ]
      },
      "quality_api:crude": { "nutrition_multiplier": 0.75 }
    }
  }
}

eat_effects take effect, duration in ticks, and optional amplifier and probability.

---

Mobs, villagers and players

Any living thing can have a quality, and it reads differently depending on what it is:

Level	Items	Food	Animals	Monsters	Townsfolk	Players
-1	Crude	Poor	Sickly	Feeble	Lowly	Frail
0	Standard	Common	Common	Common	Common	Common
1	Fine	Fine	Healthy	Seasoned	Capable	Able
2	Superior	Choice	Hardy	Fierce	Skilled	Stalwart
3	Exquisite	Prime	Pedigree	Elite	Renowned	Heroic
4	Masterwork	Gourmet	Champion	Dread	Illustrious	Legendary

Each tier can give attribute bonuses per mob type: a Dread zombie half again as big that hits like a truck, a Champion cow that's bigger and tougher, a Legendary player with extra hearts. Quality survives death and conversions (a zombie that drowns stays Dread), babies inherit it from their parents, and drops can inherit it too, so Champion cows drop masterwork beef.

Picture breeding your way up to a ranch of Pedigree livestock, a dungeon guarded by Elite skeletons, or a player rank that grows with your skill level.

Spot it in the world, no other mods needed: look at a mob or player and its tier shows on a nametag above its head (or, if you prefer, only when you sneak and right-click it with an empty hand), and the best tiers give off an occasional sparkle in their colour. Both can be changed or turned off in the client config. Packs can go further and tint a mob's whole body by its tier (see below).

Quality API stores and applies entity quality. Deciding what a mob gets when it spawns is up to your pack, another mod, or /quality entity.

Datapack: mob and player bonuses

data/quality_api/data_maps/entity_type/entity_qualities.json, keyed by entity type or tag. Item effects never reach mobs, so a mob with no entry gets nothing.

{
  "values": {
    "minecraft:zombie": {
      "quality_api:masterwork": {
        "attributes": [
          { "type": "minecraft:generic.max_health", "operation": "add_value", "amount": 30.0 },
          { "type": "minecraft:generic.attack_damage", "operation": "add_value", "amount": 6.0 },
          { "type": "minecraft:generic.scale", "operation": "add_value", "amount": 0.5 }
        ]
      }
    },
    "minecraft:player": {
      "quality_api:superior": {
        "attributes": [ { "type": "minecraft:generic.max_health", "operation": "add_value", "amount": 10.0 } ]
      }
    }
  }
}

Datapack: tint mobs and players by quality

Add tint to any tier in the same file and that mob's body is drawn in that colour. Crude livestock looks sickly green; masterwork players gleam gold:

{
  "values": {
    "#quality_api:animals": {
      "quality_api:crude": { "tint": "#9CCC65" }
    },
    "minecraft:player": {
      "quality_api:masterwork": { "tint": "#FFD54F" }
    }
  }
}

The tint multiplies the skin, so softer colours read best. "#FFFFFF" removes a tint set by a tag. Armour, held items and overlays such as sheep wool keep their own colours. Nothing is tinted by default.

Datapack: your own name sets

Modded mobs pick up the shipped names by joining #quality_api:animals, #quality_api:monsters or #quality_api:townsfolk. For a new set, point items at it in data/quality_api/data_maps/item/name_set.json (or mobs in entity_type/name_set.json):

{
  "values": {
    "#c:gems": { "name_set": "gem" }
  }
}

then name the tiers in a resource pack's lang file:

{
  "quality.quality_api.fine.gem": "Clear",
  "quality.quality_api.masterwork.gem": "Flawless"
}

---

Quality stacks

The catch with quality items: 10 fine carrots, 12 superior and 30 plain no longer stack, and your inventory fills with near-duplicates. A quality stack puts them back in one slot. It holds a normal stack's worth of one item, every tier counted separately, and looks just like the item inside. Tidier storage, never more storage.

• Make one: right-click carrots onto carrots of another quality.
• Fill it: right-click more carrots onto it, or carry it and right-click a slot to scoop them up. Right-click one quality stack onto another to combine them; the tiers already there go in first.
• Auto-pickup: carry one and matching items you walk over go straight in.
• Empty it: right-click with an empty hand to take a tier out. With one tier left it turns back into a normal stack.

Hover it to see every tier with its count. Scroll to select, right-click to remove. With nothing selected the best tier comes out first.

Works in chests, barrels and backpacks and respects their slot rules. Only stackable items that differ by nothing but quality can share one. Server config qualityStacks turns them off; existing ones can still be emptied.

---

Loot, recipes and other ways in

Roll quality onto loot (global loot modifier)

data/mypack/loot_modifiers/dungeon_quality.json rolls a weighted tier onto damageable loot without one:

{
  "type": "quality_api:roll_quality",
  "chance": 0.35,
  "conditions": [
    { "condition": "neoforge:loot_table_id", "loot_table_id": "minecraft:chests/simple_dungeon" }
  ]
}

Switch it on in data/neoforge/loot_modifiers/global_loot_modifiers.json:

{ "replace": false, "entries": [ "mypack:dungeon_quality" ] }

Drops that match the mob

In a mob's loot table, the function quality_api:copy_entity_quality gives a drop the mob's tier (level_offset shifts it, fractions are rolled), and the condition quality_api:entity_min_quality gates on the mob's level. This cow drops beef of its own quality when fine or better, and extra leather when masterwork:

{
  "type": "minecraft:entity",
  "pools": [
    {
      "rolls": 1,
      "entries": [ {
        "type": "minecraft:item",
        "name": "minecraft:beef",
        "functions": [
          { "function": "minecraft:set_count", "count": { "min": 1, "max": 3 } },
          { "function": "quality_api:copy_entity_quality", "level_offset": 0,
            "conditions": [ { "condition": "quality_api:entity_min_quality", "min_level": 1 } ] }
        ]
      } ]
    },
    {
      "rolls": 1,
      "conditions": [ { "condition": "quality_api:entity_min_quality", "min_level": 4 } ],
      "entries": [ { "type": "minecraft:item", "name": "minecraft:leather",
                     "functions": [ { "function": "minecraft:set_count", "count": 5 } ] } ]
    }
  ]
}

Recipes that need quality

quality_api:min_quality accepts an ingredient of at least a given level. For an exact tier use NeoForge's neoforge:components with "quality_api:quality": "quality_api:superior".

{
  "type": "minecraft:crafting_shaped",
  "pattern": [ "I", "I", "S" ],
  "key": {
    "I": { "type": "quality_api:min_quality", "items": "minecraft:iron_ingot", "min_level": 2 },
    "S": { "item": "minecraft:stick" }
  },
  "result": { "id": "minecraft:iron_sword" }
}

Everything else

• Roll on craft (config): things crafted from plain ingredients roll a weighted tier (tools, weapons and armour only, unless you turn off craftInheritanceDamageableOnly), so the mod works with nothing else installed.
• Blacklist: items in #quality_api:blacklist never get a quality.
• Commands (permission 2): /quality set <tier>, /quality remove, /quality entity <targets> set <tier>, /quality entity <targets> remove.
• Give command: /give @s iron_sword[quality_api:quality="quality_api:masterwork"].

---

Config

Config	File	What it does
craftInheritance	common	highest, lowest, average (default), or none
craftInheritanceDamageableOnly	common	only results with durability inherit (default on)
downgradeChance	common	chance a crafted quality drops one tier (default 0)
rollOnCraft	common	results crafted from plain ingredients roll a weighted tier (default off)
recordCrafter	common	show "Crafted by" (default on)
brokenInsteadOfDestroyed	common	the broken state (default on)
breakDowngradeChance	common	chance breaking drops a tier (default 0.75)
highestTierCanDowngrade	common	whether the top tier can drop when broken (default on)
breedInheritance	common	how bred animals inherit from their parents: average (default), highest, lowest, or none
keepPlayerQualityOnDeath	common	players keep their quality on respawn (default on)
qualityStacks	server	quality stacks and their auto-pickup (default on)
qualityTooltipStyle	client	BOTH (default), SYMBOLS or TEXT
entityQualityDisplay	client	NAMETAG (default) shows a mob's tier when you look at it, INSPECT when you sneak and right-click it with an empty hand, OFF never
showEntityQualityParticles	client	sparkles for tiers with a particle_color (default on)
showQualityTooltip	client	quality lines in tooltips and the tier on mobs and players (default on)
showQualityMarker	client	a small star in the tier's colour in the corner of each item's slot (default on)
hiddenTooltipTiers	client	tiers left out of tooltips, slot markers and mob labels, e.g. ["quality_api:standard"]

---

For mod developers

Forging, tailoring and cooking mods keep reinventing quality, and none of them can see each other's. Build on Quality API instead and get tooltips, durability, attributes, the broken state, quality stacks and every other quality mod's compatibility for free.

• Qualities: read, apply, remove, roll, forLevel, shift, meanLevel, names, food values and isBroken, for items and entities.
• QualityCraftEvent: decide a crafted result's tier. A skill mod nudges it up for a good crafter, a minigame drops it for a bad run.
• QualityLootEvent: decide a drop's tier from the killer and the mob.
• QualityBreedEvent: decide a bred baby's tier. Set breedInheritance to none and run your own genetics.
• QualityFoodEatenEvent, QualityBreakDowngradeEvent, QualityItemBrokenEvent.

Custom stations skip the crafting table: run your minigame, call forLevel with the level the score earns, then apply. The API has no side effects before a world loads, so an optional ModList.isLoaded bridge works.

Requires NeoForge for Minecraft 1.21.1 and SilverLib.