Equipment Manager

EquipmentManager is the runtime system that equips wearable content on a character and maps equipment rigs to the active character rig.

In this context, equipment can be anything the character wears:

• hair

• face attachments

• helmets and armor

• clothing

• shoes and gloves

• accessories

Core Idea

The manager is designed to work across different model sources. You can often equip an item made for one character onto another character, even when bone naming conventions are different.

Smart Bone Matching Algorithm

In SmartMapping mode, matching runs in ordered passes per equipment bone:

1. exact bone name lookup in playerBoneTransforms

2. humanoid avatar name lookup (HumanBodyBones transform names)

3. runtime cross-convention matching:

   • case-insensitive match

   • normalized name + side-aware (Left/Right) matching

   • synonym matching (for common DAZ/CC3/Mixamo/UE naming differences)

   • constrained Levenshtein fuzzy matching

4. mismatch fallback strategy (BoneMismatchHandling)

Important behavior:

• Mapping preserves bone index parity with the equipment bindposes.

• If a bone cannot be matched, a fallback bone is used (Humanoid hips, then playerRootBone, then manager transform).

Bone Mismatch Handling

Per equipment entry, you can choose:

• Ignore (maps unmatched bones to fallback)

• MapToParent

• MapToClosestAncestor

• AutoMap

• CreateFakeBone (only when Animation Rigging is present)

Custom Bone Mapping

Use CustomMapped when you want explicit control.

Mapping order in this mode:

1. custom mapping override (equipmentBoneName -> playerBoneName)

2. name match fallback

3. runtime cross-convention matching fallback

4. mismatch strategy fallback

Notes:

• Setting a target to empty/None/(None)/null/- marks it as intentionally unmapped.

• In the inspector drawer, Auto-Populate Mappings can generate an initial mapping set.

ParentToBone Mode

ParentToBone is a simple attach mode intended mainly for Hair:

• attaches the equipment root to Head when Humanoid

• falls back to playerRootBone, then manager transform

• applies per-item local position/rotation/scale offsets

Registering Equipment

Equipment is considered registered when it exists in EquipmentManager.equipmentPrefabs as an EquipmentPrefab entry.

Each entry contains:

• slot

• prefab

• uniqueID (used by save/restore ID workflows)

• boneMappingMode

• boneMismatchHandling

• optional customBoneMappings

• optional thumbnail fields

Registration workflows:

• Setup Wizard: adds entries from dropped prefabs and sets defaults.

• Manual: add entries directly in the EquipmentManager inspector.

Recommended:

• keep uniqueID stable after release (changing IDs can break saved equipment state restore).

How Slots Work

Available slots:

• Head

• Chest

• Arms

• Legs

• Feet

• Hands

• Accessories

• Hair

• Face

At runtime, EquipmentManager tracks equipped items per slot using a list, so multiple items in one slot are supported.

Slot Auto-Recognition

Slot recognition is mostly automatic during authoring:

• CharacterCreatorSetupWizard auto-detects slot by prefab name keyword scoring.

• EquipmentPrefabDrawer also auto-detects slot when prefab reference changes.

If no keyword match is found, slot is left for manual assignment. Always verify slot assignment in the inspector for final content.

Runtime API (Common)

Use:

• EquipItem(prefab, slot)

• ToggleEquipItem(prefab, slot)

• DetachItem(equippedObject, slot)

• DetachAllItems(slot)

• GetEquippedItems(slot)

• GetEquippedEquipmentIDs() / SetEquippedEquipmentIDs(ids)

Setup Checklist

1. Assign playerAnimator.

2. Populate playerBoneTransforms (use editor Auto-Populate Bones when possible).

3. Ensure each equipment prefab is registered in equipmentPrefabs.

4. Use SmartMapping first, then switch to CustomMapped only where needed.

5. Verify final slot assignments and unique IDs.

Related Files

• Assets/Arawn/CharacterCreator/Runtime/EquipmentManager.cs

• Assets/Arawn/CharacterCreator/Editor/EquipmentManagerEditor.cs

• Assets/Arawn/CharacterCreator/Editor/EquipmentPrefabDrawer.cs

• Assets/Arawn/CharacterCreator/Editor/CharacterCreatorSetupWizard.cs