Skip to content

Add a weapon

Designer · 45 min · No code

Result: a new sword, Stone Blade, with its own look and stats. It sits in the party's bag, you equip it from the Equipment screen, the character draws it in battle, and its numbers show on the stat block.

Before you start

How a weapon is put together

A weapon is a chain of assets. Each points at the next:

Piece Sample (Blue Sword) What it decides
Item definition Weapons/BlueSword/ID_XenoCore_BlueSword Name, description, icon, slot, stats, sell value. This is what sits in the bag.
Equipment definition Weapons/ED_XenoCore_Sword_Base › Weapons/BlueSword/ED_XenoCore_BlueSword What equipping it spawns, where it attaches, and which abilities it grants
Weapon actor Weapons/B_XenoCore_Sword_Base › Weapons/BlueSword/B_BlueSword The mesh you see
Weapon instance Weapons/GreatSword/B_WeaponInstance_GreatSword Which animation layer the character uses with it drawn and sheathed
Ability set Weapons/GreatSword/AbilitySet_XenoCore_JunkSword Abilities the weapon grants while worn

Every shipped sword's actor is a child of B_XenoCore_Sword_Base (the greatsword mesh) and its equipment definition a child of ED_XenoCore_Sword_Base (the instance type, the back socket, and AbilitySet_XenoCore_SwordCommon, which draws and sheathes the sword and applies its stats). A sword differs only in its item, its material, and the Talent Art its ability set (a list of abilities granted while the weapon is worn) grants. Junk, Blue, Green and Red share AbilitySet_XenoCore_JunkSword (Turn Strike); the Violet, Amber and Ivory Swords each grant their own Talent Art. Weapons/IronBlade holds only a mesh and material.

A sword whose Talent Art you want to change is covered in step 3. A new sword is the short route below. A new kind of weapon that animates differently needs the extra section at the end.

Steps

1. Make the chain

  1. Create MyGame/Weapons/StoneBlade under Content.
  2. In Plugins › XenoCore Content › Weapons, right-click each base, choose Create Child Blueprint Class, and save the child in your folder:
    • B_XenoCore_Sword_Base → B_MyGame_StoneBlade
    • ED_XenoCore_Sword_Base → ED_MyGame_StoneBlade
  3. From Weapons › BlueSword, duplicate these two:
    • ID_XenoCore_BlueSword → ID_MyGame_StoneBlade
    • MI_XenoCore_BlueSword → MI_MyGame_StoneBlade

Why the item definition is copied, not inherited

An item definition's fragments are instanced objects, and a Blueprint child of an item definition cannot be saved once it overrides them ("Illegal reference to private object"). Lyra's own items are all copies for the same reason. Treat an item definition as data.

Fails silently: never create an item definition from blank

Always duplicate an existing weapon. A new, empty item definition has no Equipment Definition, so the item shows in the list, you select it, and nothing happens. Nothing is logged.

2. Give it its own look

  1. Open MI_MyGame_StoneBlade and change BaseColor. Save.
  2. Open B_MyGame_StoneBlade. Select the inherited SwordMesh component and set every material slot to MI_MyGame_StoneBlade (the greatsword mesh has three). To use a different mesh, set it here too. Compile and Save.

Fails silently: part of the sword keeps the default material

A slot left empty draws the mesh's own material. Set all of them.

3. Point the chain at itself

Duplicates still point at the originals. Repoint them:

  1. Open ED_MyGame_StoneBlade (Class Defaults). Under Actors To Spawn, set Actor To Spawn to B_MyGame_StoneBlade. Leave Attach Socket as it is: the weapon spawns on the back and moves to the hand when drawn.
  2. Leave Instance Type as the base set it. Ability Sets To Grant inherits AbilitySet_XenoCore_SwordCommon, which gives no Talent Art. To give the sword one, set the list to AbilitySet_XenoCore_SwordCommon plus a set granting only the Talent Art (see Make a Talent Art), or replace it with Weapons/GreatSword/AbilitySet_XenoCore_JunkSword alone for Turn Strike. Never list SwordCommon and JunkSword together: both grant the draw and stats abilities, so the weapon would get them twice.
  3. Compile and Save.
  4. Open ID_MyGame_StoneBlade (Class Defaults). Set Display Name to Stone Blade.
  5. In Fragments, expand each fragment and set:
    • Inventory Fragment Equippable Item › Equipment Definition: ED_MyGame_StoneBlade
    • Xeno Core Fragment Item Display › XenoCore › Display › Description and Icon
    • Xeno Core Fragment Item Category › XenoCore › Item › Sell Value and Sort Order (and Rarity, see Item rarity)
    • Xeno Core Fragment Equip Slots › XenoCore › Equipment › Allowed Slots: keep Weapon
  6. Compile and Save.

4. Set its stats

  1. In ID_MyGame_StoneBlade, open the Inventory Fragment Set Stats fragment.
  2. Edit Initial Item Stats. Each entry is a XenoCore.Stat.* tag and a whole number:
Tag Stone Blade Note
XenoCore.Stat.WeaponAttackMin 55 Low end of the damage roll
XenoCore.Stat.WeaponAttackMax 80 High end. The game caps the spread at Min + 99
XenoCore.Stat.CriticalRate 10 Whole percent: 10 means 10%
XenoCore.Stat.PhysicalDefence 0 Remove the row rather than leaving 0
  1. Compile and Save.

Add a stat to equipment lists every tag and what it does.

4b. Set its weapon type

Every character may only wield certain kinds of weapon (its weapon type), as in Xenoblade Chronicles: the swap list for a character never shows a weapon they cannot use.

  1. In ID_MyGame_StoneBlade, open the Xeno Core Fragment Equip Slots fragment.
  2. Under XenoCore › Equipment, set Weapon Type to Weapons/Types/DA_XenoCore_WeaponType_Greatsword.
  3. Compile and Save.

Leaving Weapon Type empty lets anyone wield it. The pawn's save-time check warns when a typed character starts with an untyped weapon.

The type also gives the weapon its gem sockets: the Greatsword's Default Gem Slots is 2. For one weapon with a different count, tick Override Gem Slots on the same fragment and set Gem Slots. See Add a gem.

5. Put it in the bag

For testing, give the party one at the start:

  1. Open the leader's pawn Blueprint, for example Kael's, Characters/VRoid/Kael/B_XenoCore_Party_VRoid_L.
  2. In the Components panel, select its equipment component (the XenoCoreEquipmentComponent) and find XenoCore › Equipment › Starting Inventory.
  3. Add an entry: Item Definition ID_MyGame_StoneBlade, Count 1.
  4. Compile and Save.

Use Starting Equipment instead to have a character wear it from the start. Never list the same weapon in both, or the party gets two.

Test it

  1. Open Maps/L_XenoCore_Gym and press Play.
  2. Open the menu and go to Equipment. Choose the character and the Weapon slot.
  3. Stone Blade is in the list. Its comparison block shows your numbers against the current weapon.
  4. Equip it. Close the menu and walk into a minion's range: the character draws Stone Blade from the back, in your material.
  5. Fight. Damage rises and falls with the attack range you set.

If the weapon is missing from the list, open the console (`) and run XenoCore.Weapon.Describe: it prints each character's allowed weapon types, held weapon and how many bag weapons their swap list shows.

A new kind of weapon

Make the type first. Right-click in the Content Browser › Data › Data Asset › XenoCoreWeaponTypeDefinition, name it DA_MyGame_WeaponType_Spear, and set its Display Name. Point your weapon's Weapon Type at it (step 4b), then give every character who may use spears the type: open their pawn Blueprint, select the equipment component, and add it to XenoCore › Equipment › Allowed Weapon Types.

Fails at save: a starting weapon the character cannot wield

If a pawn's Starting Equipment weapon is a type missing from its Allowed Weapon Types, saving the pawn reports an error naming both. It would never equip.

Run XenoCore.Weapon.Describe in the console during Play to see each character's allowed types, held weapon and how many bag weapons their swap list shows.

Then give the type its own look and swings. Everything below is on the type asset, and every field is optional: left empty, a weapon of this type uses the Greatsword's stance, draw, sheathe and swings, exactly like the shipped swords.

All of these are on the type asset's Details panel, under Animation, Attack and Gems.

Field (on the type) What it changes Empty means
Armed Layers The stance while drawn: a linked anim layer, chosen by the character's cosmetic tags (one rule for Masculine, one for Feminine, or just a Default Layer) The weapon instance's Equipped Anim Set (the greatsword stance)
Sheathed Layers The stance while sheathed The weapon instance's Unequipped Anim Set (unarmed)
Draw Montage, Sheathe Montage The draw and sheathe animations The greatsword draw and sheathe
Attack Montages The auto-attack combo, in order The greatsword swings
Attack Montages Stationary Full-body versions for standing still; only read when Attack Montages is set Use Attack Montages
Attack Range How far the auto-attack reaches, cm 420

The type also carries Default Gem Slots (2), the gem sockets every weapon of the type gets.

  1. The stance: duplicate Characters/Player/AnimLayers/ABP_XenoCore_GreatSwordAnimLayers into your folder. It is an override-only child of ABP_XenoCore_ItemLayersBase: open it and replace its asset overrides (idle, combat locomotion blend space) with your weapon's clips, and set Idle Break Anim in its class defaults, or leave it empty for no fidget. Put it in the type's Armed Layers › Default Layer.
  2. The swings: duplicate the greatsword attack montages (Characters/Player/Animations/Kwang/AM_XenoCore_Attack_A and friends) and swap in your clips, then list them in Attack Montages.
  3. Draw and sheathe: duplicate AM_GreatSword_Unsheathe / AM_GreatSword_Sheathe the same way.

No weapon instance, equipment definition or ability needs to change.

Fails silently: a swing montage with no hit notify

Every attack montage needs the XenoCore Gameplay Event notify with XenoCore.Event.MeleeHit at the moment the blow lands, copied from the greatsword montage you duplicated. Without it the swing plays and never deals damage, and nothing is logged.

Fails silently: an art using an attack montage

Never point an art at one of these montages: the auto-attack stops its own montages by asset, and would cut the art off on its first frame. Give the art its own copy.

If the new kind of weapon needs its own ability set, duplicate AbilitySet_XenoCore_JunkSword and keep all three of its entries:

  • GA_XenoCore_WeaponDrawSync moves the weapon between back and hand.
  • GA_XenoCore_EquipmentStats applies the weapon's stats.
  • GA_XenoCore_TurnStrike is the character's Talent Art.

Fails silently: an ability set missing an entry

Without GA_XenoCore_EquipmentStats the weapon equips, draws and shows its name, and adds no stats. Without GA_XenoCore_WeaponDrawSync it never leaves the back. Without GA_XenoCore_TurnStrike the character has no Talent Art while wearing it. None of these log anything.

Size, position and materials

  • Size has two knobs, both on the weapon:

    • A whole family of weapons: the Attach Transform › Scale on the family's base equipment definition. Every sword inherits 0.75 from Weapons/ED_XenoCore_Sword_Base, so all swords are drawn at 75% of their mesh. Change it there to resize every sword at once.
    • One weapon: its actor Blueprint's StaticMesh component Scale (1.0 on every shipped sword). Scale the component, never the actor: drawing and sheathing rewrite the actor's transform every time.

    The two multiply. Never size a weapon with a character's socket: see below. - Pivot: export the mesh with its pivot at the grip, where the palm closes, and the blade along +X. Then it sits in every character's hand without an offset, and scaling shrinks it toward the hand. - Where it sits on a character is that character's two weapon sockets, not the weapon. See step 7 of Add a VRoid party member. A socket places a weapon, and its Scale must stay 1.0: socket scale multiplies every weapon that character ever holds, so one character's swords quietly come out a different size from everyone else's. - Materials from a pack (Paragon, Megascans) must be moved into XenoCore with the weapon. The packs are not part of the project, so on any other machine the material slot is empty and the weapon renders grey. Use the editor's Move on the material, its textures and functions, never Copy, so the mesh is repointed; then cap the textures at 1K (right-click › Texture Source Actions › Reduce Size). The Gold Sword's Materials/ folder is the worked example.

If it doesn't work

Symptom Fix
The weapon is in the bag but not in a character's swap list Its Weapon Type is not in that character's Allowed Weapon Types. This is the weapon lock working. XenoCore.Weapon.Describe shows both.
The item is in the list but will not equip Equipment Definition is empty on the item, or Allowed Slots does not include Weapon. The Output Log names the reason (NotEquippable or WrongSlot).
The weapon renders as a grey checker on someone else's machine Its material still lives in a pack folder that is not part of the project. Move it in, as described under Size, position and materials.
The stat block shows the name but zeros Initial Item Stats is empty or on the wrong fragment. See Troubleshooting: items and equipment.
The sword stays on the back when drawn The equipment definition's ability set has no GA_XenoCore_WeaponDrawSync. Keep AbilitySet_XenoCore_SwordCommon in Ability Sets To Grant.

Going further