Set and style item rarity¶

Designer · 10 min · No code · Last tested: 2026-10-04

Result: an item draws its name in its rarity's colour, with one to three diamonds, in every menu that shows it. You can also change what each rarity looks like, or add a new rarity.

Before you start¶

Items and inventory: an item is one Blueprint with fragments.
Loot: chest tiers. A chest tier is not the same thing as an item's rarity.

How rarity works¶

XenoCore uses Xenoblade 3's three rarities: Common, Rare and Legendary.

Rarity belongs to the item. Every copy of an item has the same rarity, and nothing is rolled when an item drops. To have a Common and a Rare version of the same thing, make two items.
Every shipped item states its rarity. If an item's rarity is left empty, it falls back to the lowest-ranked row of the table below (Common), but don't rely on that: set Rarity on every item you add, Common included.
What each rarity looks like is one row of the data table UserInterface/Items/DT_XenoCore_ItemRarities: its name colour, diamond count, chest beam colour and optional pickup sound.
Rarity never changes a price. Prices still come from Sell Value, as in Xenoblade 3.

Rarity	Name colour	Diamonds	Lowest chest
Common	white	1	Wooden
Rare	gold	2	Silver
Legendary	purple	3	Gold

Steps¶

Make an item rare¶

Open the item's Blueprint, for example Inventory/Armour/ID_XenoCore_BattleArmour, and click Class Defaults.
Under Display › Fragments, expand the XenoCore Fragment Item Category entry.
Set XenoCore › Item › Rarity to XenoCore.Item.Rarity.Rare or XenoCore.Item.Rarity.Legendary.
Compile and Save.

The samples¶

New Game starts with one of each tier in the bag, so every look is on screen at once. They come from Kael's (Characters/VRoid/Kael/B_XenoCore_Party_VRoid_L) Starting Inventory:

Item	Rarity	Tab
Vanguard Plate	Legendary	Torso. It is also in every minion family's Gold chest pool, for enemies of level 10 and up
Veteran Gauntlets	Rare	Arms
Prism Chain	Legendary	Collectables
Silver Moon Flower	Rare	Collectables
Fine Scrap Plating	Rare	Materials

They are sample content. Take them out of that list before you ship: open Kael's pawn, select its equipment component, and remove the rows from XenoCore › Equipment › Starting Inventory.

Make a rarer copy of an item¶

Right-click the item and choose Duplicate. Never create an item definition from scratch: a blank one cannot be equipped.
Rename the copy, change its Display Name and its numbers, and set its Rarity.
Point quests, shops and drop tables at whichever copy they should hand out.

Change how a rarity looks¶

Open DT_XenoCore_ItemRarities and edit a row:

Column	What it does
Rarity	The tag this row describes. Rows are found by this tag, never by row name.
Display Name	The word shown in details panes ("Rare · Heavy") and used by the Rarity sort.
Rank	Higher is rarer. It orders the Rarity sort and decides which row is the default.
Name Colour / Tint Name	The colour of item names. Turn Tint Name off to leave names in each screen's own colour. On a Lyra menu button the colour is written into the label's font material for its normal, hovered and pressed states, so a focused row keeps its rarity colour.
Name Outline / Name Outline Colour / Name Outline Size	A thin dark outline round the tinted name: 1 unit, black at 85%. On by default. It frames every edge of every letter, so gold and purple stay readable on the pale menu rows. Size 2 starts to fill in small letters.
Name Shadow / Name Shadow Colour / Name Shadow Offset	A soft drop shadow under the outline: 1 unit, black at 50%. On by default. Keep it subtle: a strong 2-unit shadow makes small text look smeared.
Pips / Pip Colour / Pip Texture	The diamond count (0 for none), their colour, and their art. The shipped art is `T_XenoCore_RarityPip`, a white diamond with a dark rim, tinted by Pip Colour. Don't leave Pip Texture empty: the fallback, a turned square, reads as broken triangles at the menu's scale.
Lowest Chest Tier	Drop tables warn when an item sits in a lower chest's pool than this.
Chest Beam Colour	The beam of a chest whose tier stands for this rarity. By default a gold chest glows purple, which says Legendary.
Pickup Sound	Optional. Plays when an item of this rarity is picked up, or offered by a chest.

Add a rarity¶

Project Settings › Project › Gameplay Tags: add the gameplay tag XenoCore.Item.Rarity.Mythic, or whatever name you want, in your own tag source.
Add a row to DT_XenoCore_ItemRarities with that tag and a Rank above Legendary.
Set items to the new tag.

Turn rarity off¶

Project Settings › Game › XenoCore UI › Items › Item Rarity Table: clear it. Names then draw in each screen's own colour, with no diamonds and no rarity word.
To keep the data but hide the look, turn off Tint Name and set Pips to 0 on every row.

Change the diamond size¶

Project Settings › Game › XenoCore UI › Items › Rarity Pip Size (12) sizes the diamonds on every screen.
A widget's own Pip Size pin on Apply Item Rarity, or the loot popup's Row Pip Size, overrides it when above 0. Leave them at 0 so one setting keeps every screen matching.

Set a name's font before Apply Item Rarity

The outline is part of the font. A Set Font after Apply Item Rarity removes the outline again. Three screens had this bug: the loot popup, the quest offer and the reward banner.

Make a chest guarantee a rare item¶

Xenoblade 1's silver and gold chests always hold one rare material. Open your drop table (for example Inventory/Loot/DA_XenoCore_Drops_Grunt), expand XenoCore › Loot › Pools, open the Silver or Gold entry, and set its Guarantee One Of Rarity to XenoCore.Item.Rarity.Rare.

When the roll finds nothing that rare, its last pick is redrawn from that pool's qualifying entries, so the item count stays inside Min Items to Max Items.

Where rarity shows¶

Every details pane has a Rarity row (label and tier name, in the tier's colour):

the Items menu, on every tab;
the equipment screen's item pane and its swap list;
the shop and trade screens, under Type.

For programmers: the widgets behind the Rarity row

On the Items menu and the shop and trade screens it's a DetailsRarityHB row: a DetailsRarityLabel and a DetailsRarityValue. Shop and trade fill it from C++, and the Items menu fills it with Apply Item Instance Rarity Label. On the equipment screen the stat block adds it as its own first row.

Items menu: row name and diamonds, the details name, the labelled Rarity row, and a Rarity mode in its Y sort. The Type line is plain text (for example "Heavy"), with no rarity in it.
Equipment screen: the loadout buttons, the item pane's Rarity row (the stat block's first row; the pane's header shows the name in the rarity colour with no rarity word in front), and the swap list header.
Shop and trade:
Row names and diamonds. An unaffordable row keeps its colour, dimmed.
The details name and the Rarity row. The Type row stays plain; for a weapon it names the weapon's type ("Greatsword") rather than "Equipment".
The buy/sell confirm and the trade header.
A Rarity option in the sort cycle.
Loot panel: names and diamonds, rarest first. A "(no room)" line stays red.
Pickup badge, quest offer rewards and quest reward banner.
Chest beams, coloured by the rarity each chest tier stands for. Turn this off with Use Rarity Beam Colour on the chest Blueprint.

Test it¶

Open Maps/L_XenoCore_Gym and press Play. New Game's bag holds the samples above.
Open the main menu, then Items. On the Materials tab, Fine Scrap Plating's name is gold with two diamonds; on Collectables, Prism Chain is purple with three.
Select a row: the details pane shows a Rarity row in the same colour.
Press the sort button (Y on a pad) until the prompt reads Sort: Rarity: the rarest items rise to the top.
If you made your own item rare, add it to Kael's Starting Inventory and check it the same way.

If it doesn't work¶

Symptom	Fix
A Rare or Legendary item is drawn white, with one diamond	Its Rarity is empty, which means Common. Set it on the item's XenoCore Fragment Item Category.
Every item is drawn plain, with no diamonds	XenoCore UI › Items › Item Rarity Table is cleared. Point it back at `UserInterface/Items/DT_XenoCore_ItemRarities`.
Your new rarity draws like Common	The table has no row for its tag. The Output Log warns once: `Rarity '...' has no row in ...`. Add the row.
A name in your own widget lost its dark outline	A Set Font runs after Apply Item Rarity. Set the font first.
Diamonds look like triangles	The row's Pip Texture is empty. Set it to `UserInterface/Items/T_XenoCore_RarityPip`.

More checks: Items and equipment troubleshooting.