QualityAPI

Quality API

Features

Six tiers out of the box

Every tier has a level, a colour, a roll weight, and a set of effects. Level 0 is "normal" and shows nothing, so plain items still look plain.

Swords and axes also gain attack damage per tier, and armor gains armor points. Rename the tiers, rebalance them, add a seventh, or replace the lot with a datapack.

Nothing is baked onto the item

The item only stores which tier it is. Everything else is computed live from your data, so:

• Change a number in a datapack, /reload, and every item already in the world updates.
• Quality survives smithing upgrades, anvil repairs, and grindstones.
• Attribute bonuses are added next to vanilla's and other mods', never written over them.
• Tooltips show the item name in the tier colour, the tier, who crafted it, and whether it's broken.

Broken, not destroyed

A quality item at zero durability becomes broken. It stays in your hand but can't attack, mine, or be used until you repair it at an anvil, grindstone, or with Mending.

• Breaking rolls a downgrade chance (75% by default). Fail it and your masterwork sword is now exquisite.
• Optionally protect the top tier so masterwork never drops.
• Optional shatter chance per tier for the vanilla behaviour, if you want crude tools to just die.
• Turn the whole feature off with one config switch.

Quality carries through crafting

Craft with ingredients that have quality and the result inherits it. Only results with durability inherit by default, so a masterwork plank makes plain sticks but a masterwork ingot makes a masterwork pickaxe.

• Highest, lowest, or average of the ingredients. Average rolls the remainder: a 3.25 mean is exquisite three times in four and masterwork once.
• The preview in the crafting grid shows what you'll get, and it's stable until you actually craft. No rearranging the grid to re-roll.
• Optional downgrade chance on craft for extra risk.
• Optional roll on craft gives plain recipes a weighted random tier, so the mod works with no other mods installed.
• A quality tool head, a quality ingot, a quality diamond: anything can carry quality into a recipe. Tool heads and materials never become damageable by having a tier.

Loot

Add the quality_api:roll_quality loot modifier to any loot table and every damageable item in it rolls a tier using the tier weights.

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

Datapack control

Tiers live in data/<namespace>/quality_api/quality/<name>.json:

{
  "level": 3,
  "color": "#17DD62",
  "weight": 2,
  "items": "#c:tools",
  "effects": {
    "durability_multiplier": 1.45,
    "mining_speed_multiplier": 1.35,
    "enchantment_levels": { "minecraft:unbreaking": 1 },
    "break_downgrade_chance": 0.5,
    "attributes": [ { "type": "minecraft:generic.attack_damage", "operation": "add_value", "amount": 1.5 } ]
  }
}

items is optional and limits what the tier can apply to. weight 0 means the tier is never rolled, only granted.

Per item and per tag overrides use a NeoForge data map at data/quality_api/data_maps/item/item_qualities.json. Each entry is a patch on top of the tier: name only the fields you want to change.

{
  "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 } ] }
    }
  }
}

Item entries beat tag entries. Remove something by setting its neutral value: an empty list, an empty map, or a multiplier of 1.0.

• #quality_api:blacklist (items): items that can never receive quality.
• quality_api:min_quality ingredient: recipes can demand "a stick of at least Superior". Exact tiers work with NeoForge's built in component ingredient.

Extremely customizable

For mod developers

Everything goes through one static class, Qualities:

• getId, get, level to read a stack's tier. Level is 0 when there is none.
• canApply, apply, remove to set it. apply respects the blacklist and the tier's item filter.
• roll for a weighted random tier, forLevel to turn an integer or fractional level into a tier, shift to move up or down, meanLevel to average a set of ingredients.

QualityCraftEvent fires for every crafting result with the player, recipe, ingredients, the ingredient mean level, and the proposed tier. Call setQuality to change the outcome. A skill mod can nudge the level up for a good crafter; a minigame mod can drop it for a bad run.

Custom stations like a forging anvil don't need the crafting table at all: run your minigame, call forLevel with the level your score earns, apply, and hand over the item. Post QualityCraftEvent yourself and other mods get the same hook they have on the vanilla table.

The API returns empty before a world loads and has no side effects, so the usual ModList.isLoaded bridge pattern works for optional integration.

Commands

For server admins and testing:

/quality set <tier>   — set the quality of the item in your main hand
/quality remove       — strip it

Why Quality API?

Item quality is a great mechanic and several mods have built one: forging mods, tailoring mods, food mods. Each stores it differently, each re-implements durability and attributes, and none of them can see the others. A masterwork ingot from one mod is just an ingot to the next. Quality API pulls that into one place: one component, one set of tiers, one way to apply effects, and an event any mod can hook. Use it standalone through datapacks and configs, or build your crafting station on top of it and get tooltips, durability, attributes, the broken state, and every other mod's compatibility for free.

Requires NeoForge for Minecraft 1.21.1.