Item Support

Enable item support when a character must collect, equip, switch, aim, use, or reload Character Items. Character Manager creates the receiving hierarchy, inventory, equip rules, slots, and abilities; it does not create the actual items or a default loadout.

Before you begin

• Create or choose an Item Collection containing the categories and definitions used by the character.
• Create an Item Set Rule that can form the intended equipment combinations. See Item Set Rules for the available rule types.
• Decide which full-body, first-person-arm, and alternate-model transforms represent each equipment slot.
• Save the scene or prefab before changing item support on an existing character. Removing support deletes generated item objects, slots, abilities, and first-person object hierarchies.

This field-based workflow applies when Template Character is empty. A template build uses its copy options instead; see Templates.

Add item support with Character Manager

1. Open Tools > Opsive > Ultimate Character Controller > Character Manager.
2. Configure a new character, or assign an existing Ultimate Character Controller root to Character.
3. Enable Items. It is enabled initially for a new character.
4. Assign Item Collection and Item Set Rule. Build Character or Update Character remains unavailable when either required asset is missing.
5. Select Adjust Slots beside Item Slots. Assign the full-body attachment transforms and, for first-person or Both layouts, the equivalent transforms beneath each First Person Arms group.
6. Give corresponding attachment points the same ID in every perspective and model. Keep IDs unique within each individual model or arm group.
7. Resolve every error in Character Item Slots, close the window, then select Build Character or Update Character.

A valid humanoid is initially populated with right hand ID 0 and left hand ID 1. Custom slots can use higher IDs; Inventory uses the highest ID plus one as its slot count, so an ID gap still creates an unused slot index.

Check the generated setup

After the build or update, inspect the controller before creating items:

Location	Generated result
Character root	Inventory and Item Set Manager. A player also receives Item Handler; an AI Agent does not.
Character root or animated model	Animator Monitor is added only when none exists, allowing item animation parameters to be forwarded even on a bodyless first-person character.
Items child of the controller	Item Placement, which identifies where Character Items are stored or spawned.
Selected attachment transforms	A child named Items with Character Item Slot and the configured ID. This is separate from the controller’s Items object with Item Placement.
Ultimate Character Locomotion > Item Abilities	Reload, Use, Equip Unequip, Toggle Equip, Equip Next, Equip Previous, Equip Scroll, and Aim.
Ultimate Character Locomotion > Abilities	Item Equip Verifier, added after the item abilities so other abilities can request temporary equip changes safely.
First-person-capable models and arm rigs	First Person Objects containers used by perspective-specific item visuals.

The configured demo below shows a populated Inventory and three Item Set groups. Character Manager does not create that loadout or those extra groups: a new build starts with an empty Inventory and one base group.

The controller-level Items object is the storage parent for Character Items. Their first- and third-person visible objects attach to the matching Character Item Slots when initialized.

Match slots across perspectives and models

Treat the slot ID as the equipment role and the selected transform as that role’s location for one representation:

• ID 0 can be the right hand on the full-body model, first-person arms, and every interchangeable model.
• ID 1 can be the corresponding left hand locations.
• An additional ID such as 2 can represent a magic, shoulder, or utility attachment that may equip independently when its Item Set Rule permits it.

The Character Item’s Slot ID must match one of these generated slots. If a first-person and third-person visual use different IDs, the item can initialize under the wrong transform or fail to find a spawn parent. Continue with Item Slots for the slot component behavior.

Configure Item Set groups and rules

On a new item-enabled character, Character Manager:

1. assigns the selected Item Collection to Item Set Manager;
2. creates one Item Set Group when none exists;
3. assigns the collection’s first category as that group’s Item Category when no category is already set; and
4. places the selected Item Set Rule in the edit-time Item Set Rules list when that list is empty.

The chosen rule determines which Character Items may form an equip set:

Rule	Useful starting point
Individual Item Set Rule	One item per set, with other slots allowed to remain empty.
Category Item Set Rule	Slot combinations based on item categories.
Item Type Item Set Rule	Fixed slot combinations based on specific item types.
Multi Item Set Rule	Several rule assets treated as alternative valid patterns.

On Add Item Update Item Sets Option defaults to Immediately. Keep it for straightforward pickup flows. Schedule To Late Update can combine several additions into one end-of-frame refresh, while Manual requires project code to call UpdateItemSets().

Add more groups when equipment categories should operate independently. Each group needs a unique Item Category, and each item-set ability that operates on that group needs the matching Item Category. An unassigned generated ability falls back to the first group at runtime.

Understand the generated item abilities

• Equip Unequip performs the actual transition between Item Sets.
• Toggle Equip, Equip Next, Equip Previous, and Equip Scroll choose a target set, then hand the work to the matching Equip Unequip ability.
• Aim coordinates aiming state and perspective item behavior.
• Use runs the selected action on the equipped Character Item; several Use abilities can target different slots or action IDs.
• Reload coordinates reload-capable item actions and their timing.

For an AI Agent, Character Manager keeps the item abilities but changes their input-driven start and stop types to Manual. The AI logic must decide when to equip and use an item.

Update an existing character

Use Update Character to add item support to a character that does not already have it or to change slot mappings. For an existing item-enabled character, edit Item Set Manager directly when changing groups and rules.

Released Version 3 limitations:

• Changing only Item Set Rule in Character Manager does not update the edit-time Item Set Rules list when item support already exists. The field is loaded from the first group’s first rule for display, but the update path does not write it back.
• Changing Item Collection clears the existing Item Set groups before assigning the new collection. Item Set Manager recreates a base group for the new collection, but Character Manager does not reapply the selected rule. Rebuild the intended groups, categories, and Item Set Rules in Item Set Manager after the update.
• Turning Items off removes the Items/Item Placement hierarchy, all generated Character Item Slot objects, Inventory, Item Set Manager, every item ability, Item Equip Verifier, and all First Person Objects hierarchies. On a first-person or Both character, this also removes the separate arm instances beneath those hierarchies. Keep a recoverable copy and reassign the arms in a later update if the character must retain them without item support.

Verify in Play Mode

1. Enter Play Mode and inspect Inventory. Pick up one known Character Item, or add it through the default loadout, and confirm it appears in the current inventory.
2. Inspect Item Set Manager. The matching group should generate a set containing that item in its configured slot; the set should be valid before an equip ability can select it.
3. Trigger Equip Unequip or one of the switcher abilities. The expected Character Item should become active in Inventory.
4. Confirm the visible item attaches to the matching full-body slot. For First or Both, switch perspective and verify that the first-person visual uses the same slot role.
5. Trigger Aim, Use, and Reload only where the Character Item provides the matching actions. Their animation and visible-object state should complete without changing to an unintended Item Set.

Troubleshooting

Symptom	Check	Fix
Build Character or Update Character is disabled with Items enabled.	Check Item Collection, Item Set Rule, and the open Character Item Slots window.	Assign both assets and resolve duplicate parents, duplicate IDs, or empty slot entries.
Inventory and Item Set Manager exist, but no items appear.	Check whether any Character Item prefab or default loadout was created. Character Manager does not generate either.	Follow Item Creation, then add the item through a pickup or Inventory default loadout.
The character owns an item but cannot equip it.	In Play Mode, check the Item Set group’s Item Category, generated sets, rule validity, and the Equip Unequip ability’s Item Category.	Make the definition, group, rule, and ability refer to the same category, then refresh the Item Sets.
A visible item is missing or attached to the wrong hand.	Compare the Character Item Slot ID with every perspective and model slot ID.	Use Adjust Slots and assign the same ID to equivalent transforms; update the character and recreate the item only if its own Slot ID is wrong.
Toggle, next, previous, or scroll input does nothing.	Check for a matching Equip Unequip ability and Item Category.	Add or correct Equip Unequip for that group; the switcher abilities do not perform the equip transition themselves.
A changed rule is ignored after Update Character.	Check Item Set Manager > Item Set Groups > Item Set Rules.	Edit the group directly; changing Character Manager’s Item Set Rule field alone does not update an existing setup.
First-person arms disappear after item support is removed.	Check whether the arms were children of a generated First Person Objects hierarchy.	Restore or reassign the arm rig from the recoverable source, then run a second update with Items left off.

Related tasks

• Character Creation
• Common Setups
• Inventory
• Item Set Rules
• Item Slots
• Character Items
• Item Creation
• Item Abilities

Developer details

CharacterBuilder.AddItemSupport is the editor workflow’s component-level entry point. At runtime, Item Set Manager exposes SetItemCollection, UpdateItemSets, and TryEquipItemSet for controlled collection changes, rule refreshes, and set selection.

Inventory determines its slot count from all Character Item Slot IDs and spawns runtime Character Item prefabs beneath Item Placement. Perspective Item initialization then resolves the active model and matching slot, including after OnCharacterSwitchModels.