Skip to content

Add a gem

Designer · 15 min · No code · Last tested: 2026-10-05

Result: a new gem the party can find, carry, and fit into weapons and armour from the Equipment screen. Its strength is rolled when it is found, and it raises one stat on whoever wears it.

How gems work

  • A gem is an item in the Gems tab. One item per kind and rank: Strength Up I, Strength Up II.
  • Strength is rolled per gem. The item gives a range (Strength Up I: 5-10); every copy found rolls its own number inside it, so two Strength Up I can read +6 and +9.
  • Gems sit in the equipment, not the character. Hand a gemmed sword to someone else and the gems go with it. A weapon has up to 3 sockets, an armour piece up to 1 - so 8 gems per character at most.
  • Each kind has a cap per character. Strength Up stops adding at +150 however many are worn.
  • Permanent gems are fitted to an item when it is made and can never be removed.

Make a new gem

  1. In the Content Browser, open Plugins › XenoCore Content › Inventory › Gems. Right-click ID_XenoCore_Gem_StrengthUp_I and choose Duplicate. Move the copy into your own folder (for example Content/MyGame/Gems) and name it, e.g. ID_MyGame_Gem_EtherUp_IV.

    Fails silently: never create an item from blank

    A blank item definition has none of the fragments below. It appears in the bag and can never be socketed. Always duplicate a shipped gem.

  2. Open it and click Class Defaults. Set Display Name, including the rank: Ether Up IV.

  3. In Fragments, expand Xeno Core Fragment Gem (XenoCore › Gems) and set:
    • Gem Id - a number no other gem uses. The shipped ones are kind x 10 + rank (Strength Up I is 101). Never change an id once players have socketed the gem - the socket stores the number.
    • Rank, Stat Tag (the XenoCore.Stat.* gameplay tag it raises), Min Value / Max Value, and Cap (the most this kind can add to one character).
    • A percent stat (Critical Rate) is entered as whole percent: 4 means +4%.
  4. Expand Xeno Core Fragment Item Category (XenoCore › Item). Set Sell Value and Rarity (rarity); keep Category on Gems.
  5. Expand Xeno Core Fragment Item Display (XenoCore › Display). Symbol Colour is the gem's colour on the Equipment screen. The shipped gems use their XC1 element: Strength Up red, Ether Up yellow, Agility Up green, Ether Def Up cyan, Muscle Up and Critical Up orange.
  6. Compile and Save.

  7. Open Inventory/Gems/DA_XenoCore_GemRegistry. Under XenoCore › Gems, add your gem to the Gems array. Save.

    A gem missing from the registry cannot be socketed

    It can be carried and sold, but the game refuses to put it in a socket and logs why. Every gem must be in Gems.

  8. Put it where the player can get it: a quest reward (Create a collection quest) or a shop (Open a shop). The shipped game keeps gems out of chests, as XC1 does; a chest pool in a drop table works if you want them there.

Give equipment sockets

  • Weapons get sockets from their weapon type. Every weapon type asset (e.g. Weapons/Types/DA_XenoCore_WeaponType_Greatsword) has Gems › Default Gem Slots = 2, so a new weapon has two sockets with nothing to set. Change it there to change every weapon of that type.
  • One weapon different? On the weapon item's Class Defaults, expand Xeno Core Fragment Equip Slots (XenoCore › Equipment), tick Override Gem Slots and set Gem Slots (0-3).
  • Armour sets Gem Slots on its own Equip Slots fragment: 0 or 1.
  • Fixed Gems (same fragment) are permanent gems, filling sockets 1, 2, 3 in order. Each entry names a Gem and its Value.

Look and feel

  • The socket icons are in Edit › Project Settings › Game › XenoCore UI › Items (Gem Socket Filled Icon, Gem Socket Empty Icon). Clear them and the column draws text instead.
  • The popup that lists gems is UserInterface/W_XenoCore_GemPopup, chosen in XenoCore UI › Screens › Gem Popup. Restyle that widget, or point the setting at your own.

Test it

  1. Validate the registry: right-click DA_XenoCore_GemRegistry in the Content Browser and choose Asset Actions › Validate Assets. No errors.
  2. To carry the gem from the start, open Characters/VRoid/Kael/B_XenoCore_Party_VRoid_L, select Equipment Component in Components, and add your gem to XenoCore › Equipment › Starting Inventory (Item Definition your gem, Count 1). Compile and Save.
  3. Open Maps/L_XenoCore_Gym and press Play (not Continue: a save remembers the old bag).
  4. Open the menu (pad Y, keyboard I), go to Equipment, and move right onto the Gems column beside the weapon. Press A, pick an empty socket, and highlight your gem: the character's stats preview the change.
  5. Pick it. The column shows one icon in your gem's Symbol Colour, the gem's name appears on the line under the weapon, and the stat rises by the rolled amount.
  6. Remove step 2's entry from Kael when you are done.

If it doesn't work

What you see Fix
Picking the gem does nothing; the Output Log (LogXenoCoreGems) says "Refused to socket ... the gem is not in the gem registry" Add it to Gems on DA_XenoCore_GemRegistry (step 7). If you made your own registry, check Project Settings › XenoCore Content › Items › Gem Registry points at it.
A permanent gem is missing; the log says "it was not fitted" Fixed Gems lists more gems than the item has sockets. Raise Gem Slots.
Validation: "has Gem Id 0" or "share Gem Id" Give it a unique Gem Id above 0.
Validation: "raises no stat" Set Stat Tag.
Validation: "Max Value is below Min Value" Swap them.
It sockets, but the stat does not move; the Output Log warns the gem adds nothing The Stat Tag is one the equipment stats effect has no channel for. That is a programmer job: Add a stat to equipment.
The stat stops rising after a few gems That is the Cap: per character, across every socket.
No socket to put it in The weapon's type has Default Gem Slots 0, or the item ticks Override Gem Slots with Gem Slots 0.
It never appears in the bag It is not in any quest reward, shop or drop table; or you pressed Continue on an old save.

Limits

  • Gems that do something other than add to a stat (Aggro Up, HP Steal, EXP Up) are not supported yet.