Quality

Items can have randomized quality tiers when obtained as rewards. Quality affects numerical attributes via multipliers, and players can exchange duplicate boss rewards for different items via the reroll system.

How Quality Works

When an item is given as a quest reward, the framework rolls for quality per player. Each player has their own independent random stream, so one player's luck doesn't affect another.

graph TD
    A[Item given as reward] --> B{Item has quality.enabled?}
    B -->|NO| F[No quality applied]
    B -->|YES| C{Quality already on item?}
    C -->|YES| F
    C -->|NO| D[Roll quality per player]
    D --> E{First quality that succeeds?}
    E -->|None| G[Fallback to first tier]
    E -->|Success| H[Apply quality bonuses]
    H --> I{bonus >= 35%?}
    I -->|YES| J[Damage tier +1]
    I -->|NO| K[Store on item]

Key behavior:

• Exclusive — Only one quality can be applied to an item. Once a quality is set, it cannot be changed.
• Per-player random — Each player has an independent Random instance seeded from their UID.
• Sequential roll — Qualities are checked in order. The first one whose chance succeeds is applied.
• Fallback — If no quality succeeds and multiple qualities exist, the first (lowest) quality is applied.

Quality Tiers

The visual tier (I–V) is calculated from the actual bonus percentage rolled within the quality's minBonusPercent–maxBonusPercent range:

Example: For a quality with minBonusPercent: 30 and maxBonusPercent: 50:

• Rolled 32% → Tier I
• Rolled 38% → Tier II
• Rolled 44% → Tier III
• Rolled 46% → Tier IV
• Rolled 48% → Tier V

How Bonuses Are Calculated

Quality bonuses affect all numerical attributes on the item, with special rules:

Buff vs Debuff Detection

The framework automatically detects whether an attribute is beneficial or harmful:

• Normal attributes (positive = good): attackpower, warmth, protection, maxhealth, etc.
• Inverted attributes (negative = good): hungerrate, temporaldrainmult, falldamagemult

Buffs — Value is increased (more beneficial):

attackpower: 2.5 → +25% bonus → 3.125
hungerrate: -0.1 → +25% bonus → -0.125 (more negative = better)

Debuffs — Value is reduced (less harmful):

maxhealth: -3.0 → +25% bonus → -2.25 (less penalty)
hungerrate: 0.3 → +25% bonus → 0.225 (less penalty)

Per-Attribute vs Global Bonus

• perAttribute: false — One bonus percentage is rolled and applied to all attributes equally.
• perAttribute: true — Each attribute gets its own random bonus percentage. The displayed tier is based on the average of all individual bonuses.

Bonus Mode

The bonusMode field controls which attributes receive bonuses:

Quality-Exempt Attributes

These attributes are never modified by quality bonuses:

• damagetier — Only gets +1 at 35%+ bonus, otherwise unchanged
• secondchancecharges — Charge count is fixed
• chargehours — Charge duration is fixed

Damage Tier Special Rule

If an item has damagetier and the rolled bonus is ≥ 35%, the damage tier is increased by +1. This is a significant upgrade for weapons.

Quality Config (qualityconfig.json)

Global quality definitions are stored in config/qualityconfig.json:

{
  "qualities": [
    {
      "id": "common",
      "name": "Common",
      "color": "#FFFFFF",
      "chance": 0.40,
      "minBonusPercent": 0,
      "maxBonusPercent": 0,
      "perAttribute": false,
      "bonusMode": "all",
      "exclusive": true,
      "applicableItems": ["*"]
    },
    {
      "id": "uncommon",
      "name": "Uncommon",
      "color": "#22c55e",
      "chance": 0.30,
      "minBonusPercent": 5,
      "maxBonusPercent": 15,
      "perAttribute": true,
      "bonusMode": "all",
      "exclusive": true,
      "applicableItems": ["*"]
    },
    {
      "id": "rare",
      "name": "Rare",
      "color": "#60A5FA",
      "chance": 0.18,
      "minBonusPercent": 15,
      "maxBonusPercent": 30,
      "perAttribute": true,
      "bonusMode": "all",
      "exclusive": true,
      "applicableItems": ["*"]
    },
    {
      "id": "epic",
      "name": "Epic",
      "color": "#A78BFA",
      "chance": 0.09,
      "minBonusPercent": 30,
      "maxBonusPercent": 50,
      "perAttribute": true,
      "bonusMode": "all",
      "exclusive": true,
      "applicableItems": ["*"]
    },
    {
      "id": "legendary",
      "name": "Legendary",
      "color": "#F59E0B",
      "chance": 0.03,
      "minBonusPercent": 50,
      "maxBonusPercent": 75,
      "perAttribute": true,
      "bonusMode": "all",
      "exclusive": true,
      "applicableItems": ["*"]
    }
  ]
}

Quality Config Fields

Item-Specific Qualities

You can create qualities that only apply to specific items:

{
  "id": "prestigious",
  "name": "Prestigious",
  "color": "#FFD700",
  "chance": 0.05,
  "minBonusPercent": 20,
  "maxBonusPercent": 40,
  "applicableItems": ["yourmod:legendary-sword", "yourmod:legendary-shield"]
}

Item Replacement (actionItemOverride)

When a quality with actionItemOverride is rolled, the item is replaced entirely with a different action item. This is useful for creating "upgraded" variants:

{
  "id": "mythic",
  "name": "Mythic",
  "color": "#FF4500",
  "chance": 0.01,
  "minBonusPercent": 40,
  "maxBonusPercent": 60,
  "actionItemOverride": "yourmod:shadow-blade-mythic",
  "applicableItems": ["yourmod:shadow-blade"]
}

What happens: Player gets yourmod:shadow-blade → quality rolls mythic → item is replaced with yourmod:shadow-blade-mythic (which has stronger base stats).

Per-Item Quality Settings

Each action item can opt into quality and restrict which tiers it can roll:

{
  "id": "yourmod:shadow-earring",
  "itemCode": "game:yourmod-earring",
  "name": "Shadow Earring",
  "attributes": { "attackpower": 2.5, "critchance": 0.05 },
  "quality": {
    "enabled": true,
    "minTier": 1,
    "maxTier": 5
  }
}

• quality.enabled — Whether this item can receive quality tiers.
• quality.minTier — Lowest tier this item can roll (1—5).
• quality.maxTier — Highest tier this item can roll (1—5).

Where Quality Is Applied

Quality is automatically rolled when items are given in these contexts:

Admin Commands

Examples:

/avq setquality PlayerName epic
/avq setquality legendary
/avq rerollquality

Reroll System

Players can exchange duplicate boss rewards for a chance at different items from the same group.

How It Works

graph TD
    A[Player has 2+ items
from same group] --> B[Right-click NPC
with reroll capability]
    B --> C[Open reroll dialog]
    C --> D[Click reroll button]
    D --> E[Items removed
from inventory]
    E --> F[Animation plays]
    F --> G[Random item selected
from reward pool]
    G --> H[Player claims item]
    H --> I{applyQuality?}
    I -->|YES| J[Quality rolled on new item]
    I -->|NO| K[Item given as-is]

Reroll Config (rerollconfig.json)

{
  "questToGroupMapping": {
    "yourmod:bosshunt-dragon": "dragon",
    "yourmod:bosshunt-lich": "lich"
  },
  "rerollGroups": [
    {
      "id": "dragon",
      "name": "Dragon",
      "itemsRequired": 2,
      "applyQuality": true,
      "rewardItems": ["yourmod:dragon-sword", "yourmod:dragon-shield", "yourmod:dragon-ring"],
      "npcEntityCodes": ["yourmod:treasurer-npc"]
    },
    {
      "id": "lich",
      "name": "Lich",
      "itemsRequired": 2,
      "applyQuality": true,
      "rewardItems": ["yourmod:lich-staff", "yourmod:lich-amulet", "yourmod:lich-robe"]
    }
  ]
}

Reroll Fields

Reroll Behavior Details

• Item tracking — Items from quests are tagged with their reroll group via item attributes. The framework scans all player inventories to count items per group.
• Item removal — When rerolling, itemsRequired items are removed from the player's inventory (across all slots).
• Pending reward — The reward is stored server-side until the player claims it after the animation completes.
• NPC restriction — If npcEntityCodes is set, only those NPC entity types can offer this reroll.
• Can't reroll without enough items — The UI shows progress: 1 / 2, 2 / 2 (ready).

Tips

• Balance quality chances — Make sure the sum of chance values doesn't exceed 1.0 for items with multiple applicable qualities. If it does, the first ones "consume" the probability.
• Use perAttribute: true for high-tier qualities — It creates more varied and interesting items.
• Use actionItemOverride for transformative upgrades — A "Mythic" quality could replace a basic sword with a visually different, stronger variant.
• Test with /avq rerollquality — Quickly test how different qualities look on your items during development.
• Inverted attributes need careful tuning — hungerrate and temporaldrainmult are inverted: positive = bad, negative = good. Quality bonuses correctly handle this.
• Damage tier +1 is significant — At 35%+ bonus, a weapon's damagetier increases by 1. This is a major power spike.
• Reroll groups should have 3+ items — With only 2 items, the player has a 50% chance of getting the same item back. 3+ items makes rerolling meaningful.

Complete Example

A quality config with custom qualities for a specific mod:

{
  "qualities": [
    {
      "id": "standard",
      "name": "Standard",
      "color": "#AAAAAA",
      "chance": 0.45,
      "minBonusPercent": 0,
      "maxBonusPercent": 10,
      "perAttribute": false,
      "applicableItems": ["*"]
    },
    {
      "id": "refined",
      "name": "Refined",
      "color": "#4488FF",
      "chance": 0.30,
      "minBonusPercent": 10,
      "maxBonusPercent": 25,
      "perAttribute": true,
      "applicableItems": ["*"]
    },
    {
      "id": "perfect",
      "name": "Perfect",
      "color": "#FFAA00",
      "chance": 0.15,
      "minBonusPercent": 25,
      "maxBonusPercent": 45,
      "perAttribute": true,
      "applicableItems": ["*"]
    },
    {
      "id": "transcendent",
      "name": "Transcendent",
      "color": "#FF00FF",
      "chance": 0.05,
      "minBonusPercent": 40,
      "maxBonusPercent": 70,
      "perAttribute": true,
      "actionItemOverride": "yourmod:transcendent-variant",
      "applicableItems": ["yourmod:epic-sword", "yourmod:epic-shield"]
    }
  ]
}

What this does:

• 45% chance for Standard (0–10% bonus)
• 30% chance for Refined (10–25% bonus, per-attribute)
• 15% chance for Perfect (25–45% bonus, per-attribute)
• 5% chance for Transcendent (40–70% bonus, replaces item with transcendent variant)
• Transcendent only applies to epic-sword and epic-shield

Combined with a reroll config:

{
  "questToGroupMapping": {
    "yourmod:boss-quest-1": "boss-group-1"
  },
  "rerollGroups": [
    {
      "id": "boss-group-1",
      "name": "Boss Rewards",
      "itemsRequired": 2,
      "applyQuality": true,
      "rewardItems": [
        "yourmod:epic-sword",
        "yourmod:epic-shield",
        "yourmod:epic-ring"
      ]
    }
  ]
}

Full flow:

• Player completes boss quest → gets epic-sword with quality roll.
• Player gets another epic-sword (duplicate).
• Player visits treasurer NPC → rerolls 2 swords → gets epic-ring with new quality roll.