Item Set

Export

Item Set abilities turn the valid equipment combinations generated by the Item Set Manager into player controls. Use them when a character should equip a numbered loadout, cycle weapons, scroll through available gear, or holster and restore one category without disturbing another.

Item Set is an abstract base and does not appear as a concrete choice in the ability picker. Add Equip Unequip to perform each equipment transition, then add one or more selector abilities that tell it which Item Set to use.

Before you begin

The character needs these parts on the same GameObject:

  • an Inventory containing the Character Items that may be equipped;
  • an Item Set Manager with its Item Collection assigned;
  • at least one entry under Item Set Groups, with an Item Category and one or more Item Set Rules; and
  • one Equip Unequip item ability for each Item Category that needs independent equipment control.

The Item Set Manager creates the runtime Item Sets from its rules and current inventory. A set is valid only when the character has the items required by that combination. Cycling abilities also respect whether a set can be switched to.

Configure an Item Set ability group

  1. Select the character and open its Item Set Manager.
  2. Assign the same Item Collection used to define the character’s items and categories.
  3. Expand Item Set Groups, add a group, and assign its Item Category. Add the Item Set Rules that describe valid slot combinations for that category.
  4. On Ultimate Character Locomotion, expand Item Abilities, select the plus button, and add Equip Unequip.
  5. Set the Equip Unequip Item Category to the category used by the Item Set Group. Keep Prevent Start Use Reload Active enabled unless this category is intentionally allowed to change while any Use or Reload item ability is active.
  6. Add the selector that matches the intended control: Equip Next, Equip Previous, Equip Scroll, or Toggle Equip. Assign the same Item Category and configure its input.
  7. Repeat the Equip Unequip and selector pairing for each independently controlled category, such as primary weapons and grenades.
  8. If the equip or unequip animation must override a persistent pose such as Aim, place Equip Unequip above that pose in the Item Abilities list. The selector row stops after delegating and does not supply an item animation state of its own.

Item Category is unassigned by default. At runtime an unassigned Item Set ability uses the first Item Set Group’s category. That fallback is convenient for a character with one group, but explicit assignments are safer and easier to verify when the character has multiple groups.

Prevent Start Use Reload Active is enabled by default. It checks for any active Use or Reload ability on the character, not only an action in the same category or slot. Keep the setting consistent across the selector and its Equip Unequip row unless the difference is deliberate.

Choose the control by player goal

Goal Ability Starting defaults What it selects
Press a numbered key for a known set Equip Unequip Button Down; Equip First Item through Equip Tenth Item The input’s position maps directly to the Item Set index, then the ability performs the transition.
Cycle forward through available sets Equip Next Button Down; Equip Next Item The next valid, switchable set in the category, wrapping around the list.
Cycle backward through available sets Equip Previous Button Down; Equip Previous Item The previous valid, switchable set in the category, wrapping around the list.
Use one bidirectional axis or mouse wheel Equip Scroll Axis; Mouse ScrollWheel; Scroll Sensitivity 0.1 Next for a positive axis value and previous for a negative value once the sensitivity threshold is reached.
Holster a category and restore its last valid set Toggle Equip Button Down; Toggle Item Equip; Toggle Default Item Set On Start disabled The category’s default set or the previously active non-default set.

All five concrete abilities use the base Stop Type Manual. The selector abilities stop themselves immediately after requesting a change. Equip Unequip stops after its unequip, equip, and completion events have finished.

Equip Unequip starts with Auto Equip set to Unequipped, Out Of Usable Item, Not Preset, and First Time; Always is not selected. Its supplied Animator defaults are Equip Item State Index 4, Unequip Item State Index 5, and Aim Item Substate Index Addition 100.

Make the category and rule decisions

Use one group for each independent equipment family

An Item Set ability resolves its Item Category to one Item Set Group. A matching Equip Unequip row is required for Equip Next, Equip Previous, Equip Scroll, and Toggle Equip; a selector logs an error and disables itself when no match exists.

Use separate groups and duplicate selector types when the controls should be independent. For example, a primary-weapon group can use the mouse wheel while a grenade group uses a toggle button. Both can operate on the same character because each pair targets a different category ID.

If multiple Item Set Groups claim the same equipment slot, the earlier group in Item Set Groups has priority. Reorder the groups or change their rules when one category unexpectedly preserves or replaces another category’s item.

Decide which sets can be selected

Equip Next, Equip Previous, and Equip Scroll skip sets that are invalid for the current inventory or cannot be switched to. This means list order expresses the cycle order, but it does not guarantee that every row will appear during play.

The default Item Set represents the category’s unequipped or fallback state. Toggle Equip returns to that default and later restores the remembered non-default set when it is still valid. Keep a valid default when the category needs a reliable holstered state.

Decide whether switching waits for actions

Keep Prevent Start Use Reload Active enabled for weapons that should finish firing or reloading before they switch. Disable it only when the design supports an equipment change during those actions and the item animations, inventory changes, and action modules have been tested together.

The setting prevents the Item Set ability from starting; it does not cancel the active Use or Reload action. An active Equip Unequip also blocks a new Use or Reload while an item is in its unequip phase.

How it runs

  1. The Item Set Manager evaluates its Item Set Rules against the Inventory and builds the valid Item Sets for each group.
  2. Input starts a selector or starts Equip Unequip directly. The ability resolves Item Category to its Item Set Group.
  3. The shared start check rejects the request while Use or Reload is active when Prevent Start Use Reload Active is enabled.
  4. A selector finds the requested valid index and calls its category-matched Equip Unequip ability. The selector then stops.
  5. Equip Unequip compares the active and target sets slot by slot. It unequips items that should leave, waits for their configured events, equips the new items, and waits for their completion events.
  6. During the transition, Equip Unequip supplies Item State Index 5 for an unequipping slot and 4 for an equipping slot. Aiming adds 100 to the Character Item’s equip or unequip substate.
  7. The Item Set Manager records the new active set, applies its State when one is configured, and notifies UI or gameplay listeners of the change.

The ability list position does not pair a selector with Equip Unequip; their matching Item Category does. List position matters only when Equip Unequip and another active item ability both offer Animator values for the same slot.

Verify in Play Mode

  1. Give the character the Item Definitions required by at least two sets in one group.
  2. Keep Item Set Manager and Ultimate Character Locomotion visible. Confirm the group’s runtime Item Sets list contains the expected combinations and shows a valid active set.
  3. Trigger the category’s selector. Confirm that selector becomes active only briefly, while its matching Equip Unequip (Active) remains visible through the equipment transition.
  4. Confirm the old item uses Item State Index 5, the new item uses Item State Index 4, and the visible objects change only at their configured animation events or durations.
  5. Cycle in both directions and confirm invalid or non-switchable sets are skipped and the sequence wraps through the valid choices.
  6. Start Use or Reload and try to switch. With Prevent Start Use Reload Active enabled, confirm the set does not change until that action stops.
  7. If the character has two Item Set Groups, operate each category’s control and confirm the other category remains unchanged unless their rules intentionally share a slot.

Troubleshoot Item Set abilities

  • Item Set is missing from the ability picker: it is an abstract base. Add Equip Unequip or one of the four concrete selectors listed above.
  • A selector disables itself at runtime: check that the character has an Item Set Manager group and an Equip Unequip ability with the same Item Category. Assign the category explicitly instead of relying on the first-group fallback.
  • The group contains no usable Item Sets: check Item Collection, Item Category, Item Set Rules, and the Character Items currently in Inventory. The character must own every required item in a combination before that set is valid.
  • Next, Previous, or Scroll appears to skip a set: inspect the runtime Item Set and confirm it is valid and can be switched to. Skipping an unavailable set is expected.
  • A numbered input equips the wrong set: the Equip Unequip input position maps to the runtime Item Set index. Check the generated order and the input’s position in Input Names.
  • Switching never starts while firing or reloading: Prevent Start Use Reload Active is enabled by default and checks all active Use and Reload abilities. Wait for the action to finish or deliberately disable the option on the relevant rows.
  • Equip Unequip becomes active but never finishes: check the Character Item’s Equip Event, Equip Complete Event, Unequip Event, and Unequip Complete Event. Add the required Animator events or use verified durations.
  • The equip animation is hidden by Aim or another pose: move Equip Unequip above the competing active item ability so state indexes 4 and 5 win for the affected slot.
  • Changing one category affects another: check whether their Item Set Rules claim the same slot. The earlier Item Set Group has priority when groups overlap.
  • Item Set and Rules explains how groups, rules, validity, default sets, and group priority determine the generated combinations.
  • Inventory explains how the character owns the Item Definitions that make sets valid.
  • Character Item covers the equip and unequip timing stored on each item.
  • Item Abilities explains shared inputs, concurrency, and Animator list order.
  • Animator Parameters describes Item State Index and Item Substate Index.

Developer reference

ItemSetAbilityBase exposes ItemCategory, ItemSetCategoryID, PreventStartUseReloadActive, and the resolved read-only ItemSetGroupIndex. Equip Next, Equip Previous, Equip Scroll, Toggle Equip, and Equip Unequip allow duplicate types so code or authoring tools can create one category-specific copy per workflow.

Use EquipUnequip.StartEquipUnequip(itemSetIndex) when code already has the matching ability and index. Overloads accept forceEquipUnequip and immediateEquipUnequip. The Item Set Manager also exposes TryEquipItemSet overloads for a set name, index, or Item Set object; these validate the set and delegate to its Equip Unequip ability.

The built-in Event System reports the important transitions:

  • OnItemSetManagerUpdateNextItemSet (int groupIndex, int previousIndex, int nextIndex) reports the pending set.
  • OnActiveItemSetChange (int groupIndex, ItemSet previousSet, ItemSet newSet) reports the active-set change.
  • OnItemSetManagerUpdateItemSet (int groupIndex, int activeIndex) reports the new active index.
  • OnEquipUnequipItemSetIndexChange (int itemSetIndex) is sent on the matching Equip Unequip ability for selector synchronization.
  • OnCharacterItemAbilityActive (ItemAbility, bool) reports selector and Equip Unequip activation like other item abilities.