Durability & Quality

The durability and quality systems control item wear mechanics and rarity classification. Durability determines how long items last before breaking, while quality is a full asset system that controls tooltip appearance, slot textures, text colors, and drop visual effects.

Durability System

Core Properties

Field	Type	Default	Description
MaxDurability	float	—	Maximum durability points
DurabilityLossOnHit	float	—	Durability lost per use

Weapon Durability

Weapons lose durability when hitting targets. The DurabilityLossOnHit value is subtracted from current durability on each successful hit.

Weapon_Sword_Mithril.json (durability section)

{
  "MaxDurability": 220,
  "DurabilityLossOnHit": 0.21
}

Calculation: Hits until broken = MaxDurability / DurabilityLossOnHit

• Mithril Sword: 220 / 0.21 = ~1048 hits

Tool Durability

Tools use a more complex durability system with per-block-type loss rates.

Tool_Pickaxe_Mithril.json (durability section)

{
  "MaxDurability": 400.0,
  "Tool": {
    "DurabilityLossBlockTypes": [
      {
        "BlockSets": ["Stone", "Rock", "Ores", "Soil"],
        "DurabilityLossOnHit": 0.25
      }
    ]
  }
}

Tool-specific properties:

Field	Type	Description
DurabilityLossBlockTypes	array	Per-block-set durability loss
BlockSets	array	Block categories that trigger this loss rate
DurabilityLossOnHit	float	Loss when mining these blocks

Armor Durability

Armor pieces have durability that decreases when taking damage.

Armor_Mithril_Chest.json (durability)

{
  "MaxDurability": 180
}

Durability by Tier

Weapon Durability Progression

Material	MaxDurability	DurabilityLossOnHit	Approximate Hits
Scrap	50	0.21	~238
Crude	80	0.21	~381
Copper	100	0.21	~476
Iron	120	0.21	~571
Cobalt	150	0.21	~714
Adamantite	180	0.21	~857
Mithril	220	0.21	~1048

Tool Durability Progression

Material	MaxDurability
Crude	100
Copper	150
Iron	200
Steel	280
Mithril	400

Quality System

Quality isn’t a hardcoded enum — it’s a full asset system. Each quality tier is a JSON asset (ItemQuality) loaded into its own AssetStore, which means modders can define entirely new quality tiers beyond the defaults. Each quality asset defines its own tooltip textures, slot textures, text color, localization, and visual behavior.

Quality Asset Properties

Field	Type	Description
QualityValue	int	Ordering value (0 = lowest quality)
ItemTooltipTexture	string	Tooltip background texture path
ItemTooltipArrowTexture	string	Tooltip arrow texture path
SlotTexture	string	Inventory slot texture
BlockSlotTexture	string	Slot texture for block-type items
SpecialSlotTexture	string	Slot texture for consumables/usables
TextColor	Color	Item name color in inventory
LocalizationKey	string	Localized quality name
VisibleQualityLabel	boolean	Show quality label in tooltip
RenderSpecialSlot	boolean	Use special slot for consumables
HideFromSearch	boolean	Hide from creative library search
ItemEntityConfig	object	Drop visual config (glow, particles)

Items reference a quality by its asset ID string (e.g. "Quality": "Common"), which gets resolved to the full ItemQuality asset at load time.

Default Quality Tiers

Quality	Description	Text Color
Common	Basic items	White
Uncommon	Improved items	Green
Rare	Advanced items	Blue
Epic	High-tier items	Purple
Legendary	Top-tier items	Gold
Template	Base templates (not for items)	—

Quality in Item Definitions

Weapon_Sword_Copper.json

{
  "Parent": "Template_Weapon_Sword",
  "Quality": "Common",
  "ItemLevel": 10,
  "MaxDurability": 100
}

Weapon_Sword_Mithril.json

{
  "Parent": "Template_Weapon_Sword",
  "Quality": "Epic",
  "ItemLevel": 50,
  "MaxDurability": 220
}

Weapon_Longsword_Flame.json

{
  "Quality": "Legendary",
  "ItemLevel": 30,
  "DurabilityLossOnHit": 0.52
}

Quality by Material

Weapons

Material	Quality	Item Level
Crude	Common	8
Copper	Common	10
Scrap	Uncommon	15
Iron	Uncommon	20
Bronze	Uncommon	30
Steel	Uncommon	30
Cobalt	Rare	35
Adamantite	Rare	40
Mithril	Epic	50
Onyxium	Epic	30
Flame (Special)	Legendary	30

Armor

Material	Quality
Cloth (Linen, Cotton, Wool, Silk)	Common
Bronze	Uncommon
Iron	Uncommon
Steel	Uncommon
Cobalt	Rare
Adamantite	Rare
Cindercloth	Rare
Mithril	Epic
Onyxium	Epic

Item Level

The ItemLevel field indicates the relative power/tier of an item. Higher levels typically correlate with better stats and higher quality.

Item Level Range	Typical Quality
1-10	Common
11-25	Uncommon
26-39	Rare
40-50+	Epic/Legendary

Visual Effects by Quality

Dropped items display visual effects based on their quality tier.

Drop Effects

Drop_Uncommon.json

{
  "SwitchTo": "PostColor",
  "PostColorOpacity": 0.0,
  "AnimationDuration": 1.0,
  "EffectDirection": "BottomUp",
  "AnimationRange": { "Y": 1.0 },
  "UseBloomOnHighlight": true,
  "HighlightThickness": 0.5,
  "HighlightColor": "#e0ff7d",
  "LoopOption": "Loop"
}

Drop_Rare.json

{
  "SwitchTo": "PostColor",
  "PostColorOpacity": 0.0,
  "AnimationDuration": 1.0,
  "EffectDirection": "BottomUp",
  "AnimationRange": { "Y": 1.0 },
  "UseBloomOnHighlight": true,
  "HighlightThickness": 1.0,
  "HighlightColor": "#7db2ff",
  "LoopOption": "Loop"
}

Drop_Legendary.json

{
  "SwitchTo": "PostColor",
  "PostColorOpacity": 0.0,
  "AnimationDuration": 1.0,
  "EffectDirection": "BottomUp",
  "AnimationRange": { "Y": 1.0 },
  "UseBloomOnHighlight": true,
  "HighlightThickness": 5.0,
  "HighlightColor": "#ffdb91",
  "LoopOption": "Loop"
}

Effect Properties by Quality

Quality	Highlight Color	Thickness	Effect
Common	—	—	No glow
Uncommon	Green (#e0ff7d)	0.5	Subtle glow
Rare	Blue (#7db2ff)	1.0	Medium glow
Epic	Purple (#cb91ff)	2.0	Strong glow
Legendary	Gold (#ffdb91)	5.0	Bright glow

Creating Custom Items

Basic Durable Weapon

MyPlugin_Weapon_Sword_Custom.json

{
  "Parent": "Template_Weapon_Sword",
  "Quality": "Rare",
  "ItemLevel": 35,
  "MaxDurability": 160,
  "DurabilityLossOnHit": 0.21,
  "Model": "MyPlugin/Weapons/Sword_Custom.blockymodel",
  "Texture": "MyPlugin/Weapons/Sword_Custom_Texture.png"
}

High-Durability Tool

MyPlugin_Tool_Pickaxe_Custom.json

{
  "Parent": "Tool_Pickaxe_Crude",
  "Quality": "Epic",
  "ItemLevel": 45,
  "MaxDurability": 500.0,
  "Tool": {
    "DurabilityLossBlockTypes": [
      {
        "BlockSets": ["Stone", "Rock", "Ores"],
        "DurabilityLossOnHit": 0.15
      },
      {
        "BlockSets": ["Soil"],
        "DurabilityLossOnHit": 0.10
      }
    ]
  }
}

Legendary Item with Custom Effects

MyPlugin_Weapon_Special.json

{
  "Quality": "Legendary",
  "ItemLevel": 50,
  "MaxDurability": 300,
  "DurabilityLossOnHit": 0.35,
  "InteractionVars": {
    "Swing_Damage": {
      "Interactions": [
        {
          "DamageCalculator": {
            "BaseDamage": { "Fire": 45 },
            "RandomPercentageModifier": 0.15
          }
        }
      ]
    }
  },
  "Light": {
    "Radius": 1,
    "Color": "#621"
  }
}

Durability Patterns

Balancing Guidelines

1. Durability scales with tier - Higher-tier items last longer
2. Loss rate is consistent - Most weapons use 0.21 loss per hit
3. Special items may vary - Legendary items can have different loss rates
4. Tools use block-specific rates - Different blocks cause different wear

Standard Loss Rates

Item Type	Typical DurabilityLossOnHit
Swords	0.21
Maces	0.21
Daggers	0.21
Battleaxes	0.21
Bows	0.58
Pickaxes (Stone/Rock)	0.25
Pickaxes (Soil)	0.25
Axes (Wood)	0.25

Formula Reference

Hits Until Broken = MaxDurability / DurabilityLossOnHit

Example:
Iron Sword: 120 / 0.21 = 571 hits
Mithril Sword: 220 / 0.21 = 1048 hits

Best Practices

1. Match quality to power - Higher ItemLevel items should have higher Quality
2. Scale durability appropriately - More powerful items should last longer
3. Use consistent loss rates - Follow game patterns for weapon types
4. Consider tool specialization - Different loss rates for different block types
5. Test in-game - Verify durability feels right during gameplay
6. Balance crafting costs - Higher durability items should cost more to craft

Related

• Items Overview - Item definitions
• Weapons - Weapon configurations
• Tools - Tool configurations
• Armor - Armor configurations
• Recipes - Crafting recipes
• Model Effects - Visual effects for rarity