Skip to main content

Mutable equipment

With the engine's Mutable plugin, equipment can change the character's mesh rather than hang off it. Put on iron boots and the body's feet become iron boots: they deform with the animation and cost no extra draw call.

This module is optional in the strongest sense — without Mutable installed it compiles itself out, and the same item assets work either way.

Turning it on​

Enable the engine's Mutable plugin. EDInventoryEquipmentMutable detects it at build time and sets WITH_ED_MUTABLE; with it absent, the component is inert, ticks nothing, and never touches an API that is not there.

if (UEDMutableEquipmentComponent::IsMutableAvailable())
{
    // This build has Mutable.
}

Setup​

  1. Give the character a UCustomizableSkeletalComponent with a Customizable Object instance — the usual Mutable setup, unchanged.
  2. Add UEDMutableEquipmentComponent to the same actor.
  3. Give items a Mutable Equipment fragment.

The fragment​

FEDMutableEquipmentFragment lists the Customizable Object parameters an item writes while it is worn:

FieldMeaning
ParametersName, type and value. Option (int), Float, Bool or Color.
Container Filter / Slot FilterWhere the item must be for the parameters to apply.

The filters are the same vocabulary equipment visuals and GAS grants use, so an item can drive a mesh attachment, a buff and a body change from one description of where it is.

How it applies​

The component watches the actor's containers and, on any change, rewrites the whole parameter set and asks Mutable for one rebuild.

Two details are deliberate:

It coalesces. Putting on a suit of armour is five container changes in one frame. Applying each as it arrived would rebuild the character five times — the difference between a hitch and no hitch. The component queues one rebuild for the end of the frame.

It gathers before it writes. Every worn piece's parameters are collected first, then written together, so a later piece can legitimately override an earlier one's parameter instead of the two fighting across frames.

The rebuild itself is asynchronous. A Mutable update is far too expensive to block a frame on, so the character pops to its new look when it lands.

Mixing both approaches​

Nothing stops an item from carrying an Equipment Visuals fragment and a Mutable fragment. A common split:

  • Mutable for anything that should deform with the body — armour, clothing, gloves.
  • Attached meshes for anything rigid — a sword, a shield, a backpack.

Both are driven by where the item is, so they stay in step without coordination.

Swapping the instance​

If you replace the character's Customizable Object instance at runtime, call RefreshMutableEquipment() afterwards. The component reacts to inventory changes, not to the character's rig changing underneath it.

Where next​

Last updated on