Item Rarity

Status: Design Date: 2026-04-05

Fixed rarity per item template. Affects name display color, loot table weights, shop pricing, and player perception of value.

Rarity Tiers

Unique Items

Unique items are one-of-a-kind. Only one copy of a unique template can exist in the world at any time. They are the rarest and most coveted items in the game.

Rules

• One per world. The agent tracks which unique templates are currently in circulation. If a unique item already exists (held by a player, on the ground, or in a corpse), it cannot drop again or be spawned again.
• Drops on death. When the holder dies, the unique drops on their corpse like any other item. Anyone can loot it (unless the designer set the binding to %protected or %soulbound).
• Binding is designer-specified. A unique can be %none (freely lootable/tradeable), %protected (only the holder can retrieve from corpse), or %soulbound (permanently bound to the first player who picks it up). The designer chooses based on how they want the item to circulate.
• Cannot be sold to shops. Unique items have no sell value. They can be given to other players (if not soulbound) but not vendored.
• Survives remort. Unique items are always kept through remort regardless of binding type.

Circulation Tracking

The agent state tracks which unique templates are currently instantiated:

unique-items-active=(map item-id instance-id)

When a unique item instance is created (mob drop, admin spawn), it’s registered. When the instance is destroyed (item consumed, admin delete), it’s unregistered. Loot table rolls skip unique items that are already active.

Drop Mechanics

Unique items don’t use normal loot tables. They are placed by the designer in one of two ways:

1. Mob drop with unique: true — the mob’s loot entry is flagged as unique. On kill, the system checks if the unique is already in circulation. If not, it drops. If yes, nothing drops from that loot entry.

2. World placement — the designer places the item in a room or on an NPC shop via the area JSON. The item exists from world load.

Display

[!] Covenant Breaker

The [!] prefix in red (#ff6b6b) marks unique items. They should feel special every time they appear in text.

Lore

Unique items should have extended look-desc text — a paragraph of lore about the item’s history, who made it, why it matters. This is the designer’s responsibility. The system just provides the framework.

How It Works

Template Field

Add rarity=item-rarity to item-template:

+$  item-rarity  ?(%common %uncommon %rare %epic %legendary %unique)

Default: %common for any item without an explicit rarity.

Name Display

Item names in all text output are prefixed with a color tag:

• Common: Rusty Sword (no tag, default white)
• Uncommon: [U] Forest Blade
• Rare: [R] Dragonscale Shield
• Epic: [E] Voss's Spectral Blade
• Legendary: [L] Covenant Breaker

The frontend can render these with CSS colors:

• [U] → green (#51cf66)
• [R] → blue (#339af0)
• [E] → purple (#b197fc)
• [L] → orange (#ffd43b)

Stat Multiplier

When an item template has rarity above common, its weapon damage, armor defense, and effect values are scaled by the stat multiplier. This is applied at template definition time by the designer — the system doesn’t auto-scale. The multiplier is a guideline for content creators, not an engine feature.

This keeps balance in the designer’s hands. A legendary item is legendary because the designer made it powerful, not because the engine multiplied stats.

Shop Pricing

The value multiplier affects:

• Buy price: base-value * rarity-value-multiplier * shop-markup
• Sell price: base-value * rarity-value-multiplier * shop-markdown

Higher rarity items are worth more gold. This creates natural gold sinks (players saving up for rare gear) and makes finding a rare drop feel rewarding.

Loot Tables

The drop weight modifier adjusts loot table probabilities. When rolling loot from a mob’s loot table:

effective-weight = base-weight * drop-weight-modifier-for-rarity

A mob might have:

"loot": [
  {"item-id": 50, "chance": 30},
  {"item-id": 55, "chance": 10}
]

If item 50 is common (1.0x) and item 55 is rare (0.2x), the effective chances become 30% and 2%. The designer sets the base chance knowing the rarity modifier will scale it down.

Alternatively, the designer can account for rarity in their base chance values and ignore the modifier entirely. The modifier is optional — if not desired, all items can be %common and drop rates stay as-is.

JSON Format

{
  "id": 55,
  "name": "Dragonscale Shield",
  "rarity": "rare",
  "item-type": "armor",
  ...
}

If "rarity" is omitted, defaults to "common".

Display Contexts

Common items have no tag — they look the same as they do now.

Implementation

Type Changes

Add to sur/mud.hoon:

+$  item-rarity  ?(%common %uncommon %rare %epic %legendary %unique)

Add rarity=item-rarity to item-template (after item-binding).

Import

In mud-import.hoon and parse-world-json, parse the "rarity" field:

=/  rarity=item-rarity
  =/  r=@t  (json-str (json-get it 'rarity'))
  ?:  =(r 'uncommon')   %uncommon
  ?:  =(r 'rare')       %rare
  ?:  =(r 'epic')       %epic
  ?:  =(r 'legendary')  %legendary
  ?:  =(r 'unique')     %unique
  %common

Display Helper

Add a helper arm:

++  rarity-prefix
  |=  r=item-rarity
  ^-  @t
  ?-  r
    %common     ''
    %uncommon   '[U] '
    %rare       '[R] '
    %epic       '[E] '
    %legendary  '[L] '
    %unique     '[!] '
  ==

All item name display points call (cat 3 (rarity-prefix rarity.tmpl) name.tmpl) instead of bare name.tmpl.

Affected Display Points

Frontend

The frontend parses [U], [R], [E], [L] prefixes and applies CSS color classes:

.rarity-uncommon { color: #51cf66; }
.rarity-rare { color: #339af0; }
.rarity-epic { color: #b197fc; }
.rarity-legendary { color: #ffd43b; }
.rarity-unique { color: #ff6b6b; }

The log renderer splits item names on the bracket prefix and wraps in a <span> with the appropriate class.

Impact on Existing Systems

Not Included

• Random rarity on drop. Rarity is fixed per template.
• Rarity-gated content. No “must have epic gear to enter” restrictions.
• Rarity crafting/upgrading. No way to improve an item’s rarity tier.
• Rarity effects. No special procs or abilities tied to rarity — just stats and color.
• Rarity in PvP. No PvP-specific rarity balancing.
• Cross-world unique tracking. Uniques are per-world only. Two worlds can both have the same unique template.