Equip Scroll

Export

Equip Scroll uses one signed input axis to move forward or backward through the valid Item Sets in one equipment category. Use it for a mouse wheel, controller wheel, or another bidirectional control where a positive value selects the next set and a negative value selects the previous set.

Equip Scroll selects the target only. A category-matched Equip Unequip ability performs the visible unequip and equip sequence.

Before you begin

The character needs:

  • an Inventory containing the Character Items used by the target sets;
  • an Item Set Manager with an Item Set Group for the intended Item Category;
  • at least two generated Item Sets in that group; and
  • an Equip Unequip item ability with the same Item Category.

At least one alternative set must be enabled, valid for the current inventory, and allowed to switch to. Otherwise neither axis direction has a target and Equip Scroll will not start.

Configure Equip Scroll

  1. Select the character and expand the target group under Item Set Manager > Item Set Groups.
  2. Confirm its Item Category, Item Set Rules, and runtime Item Set order describe the cycle you want.
  3. On Ultimate Character Locomotion, expand Item Abilities and add Equip Unequip if the category does not already have one. Assign the same Item Category.
  4. Add Equip Scroll to Item Abilities and assign that Item Category.
  5. Keep the input defaults for a mouse wheel: Start Type is Axis, Stop Type is Manual, and Input Names contains Mouse ScrollWheel. Equip Scroll stops itself after handing off the selected index.
  6. Start with Scroll Sensitivity 0.1. This is the default minimum absolute raw-axis value required for a switch.
  7. Keep Prevent Start Use Reload Active enabled when firing or reloading should finish before the player changes equipment. This option is enabled by default.
  8. Confirm the input source reports a positive value for the direction that should move forward and a negative value for the direction that should move backward. Invert the input binding when the physical wheel direction should behave differently.

Item Category is unassigned by default. An unassigned Item Set ability uses the first Item Set Group’s category at runtime. Assign it explicitly whenever the character has more than one group so Equip Scroll finds the intended group and Equip Unequip row.

Equip Scroll allows duplicate types. Add separate rows with different Item Categories or input axes when primary weapons, grenades, or other equipment families need independent scroll controls.

Choose the axis and cycle behavior

Set the direction and threshold

Equip Scroll reads the raw value of the active axis:

  • a value greater than 0 searches forward for the next eligible Item Set;
  • a value less than 0 searches backward for the previous eligible Item Set; and
  • an absolute value below Scroll Sensitivity is ignored.

With the default sensitivity of 0.1, values from greater than -0.1 to less than 0.1 form the ignored range. A value exactly equal to either threshold is accepted. Raising the setting requires a stronger scroll pulse; lowering it accepts smaller input noise.

The threshold is checked against each raw axis reading. Equip Scroll does not accumulate several small values into one switch.

Order the Item Sets

For a positive value, Equip Scroll starts after the active Equip Unequip Item Set index and advances through the runtime list. For a negative value, it starts before that index and moves backward. Forward traversal wraps from the last index to 0; reverse traversal wraps from index 0 to the final index.

The runtime Item Set order is generated by the group’s rules and can change when inventory or rules change. Inspect the group in Play Mode when the scroll sequence does not match the order expected from the edit-time rule list.

Decide which sets are eligible

Both directions skip an Item Set when any of these conditions applies:

  • the set is disabled;
  • Can Switch To is disabled;
  • its Item Set Rule reports that the combination is invalid;
  • a required Character Item is missing from its slot or the inventory does not contain the required count; or
  • a usable item in the set currently cannot be equipped, such as an item with no usable supply remaining.

The default Item Set participates only when it is valid and Can Switch To is enabled. Keep Can Switch To disabled when the default represents a holstered state that should be reached only by Toggle Equip or another deliberate action.

Prevent stacked scroll changes

An active Equip Unequip ability blocks Equip Scroll from starting. A second wheel pulse therefore cannot queue another scroll selection while the previous equip or unequip transition is still active.

With Prevent Start Use Reload Active enabled, any active Use or Reload item ability also prevents Equip Scroll from starting. This check is character-wide rather than limited to this category or slot.

How it runs

  1. A nonzero raw value from Mouse ScrollWheel or the configured axis attempts to start Equip Scroll.
  2. The base axis input check records the raw value. Equip Scroll then rejects it when its absolute magnitude is below Scroll Sensitivity.
  3. The shared start check rejects the request while Use or Reload is active when Prevent Start Use Reload Active is enabled. An active Equip Unequip transition also blocks the request.
  4. Equip Scroll uses the sign of the axis value and the matched Equip Unequip ability’s active Item Set index to request the next or previous eligible index.
  5. The Item Set Manager traverses the list in that direction, wraps at the boundary, and skips every set that fails the eligibility checks above.
  6. Equip Scroll refuses to start when no alternative is found, the resulting index is -1, or the result is already active.
  7. For an accepted target, Equip Scroll temporarily applies its Prevent Start Use Reload Active value to the matching Equip Unequip call, requests the target index, restores the worker’s setting, and immediately stops itself.
  8. Equip Unequip performs the visible transition. The manager marks the target active as the new items reach their equip point, and Equip Unequip remains active until their equip-complete events finish.

Equip Scroll does not supply an Item State Index or item substate. Its position in the Item Abilities list therefore does not choose the equip animation. Equip Unequip supplies the default unequip and equip state indexes 5 and 4; position that row above a persistent pose such as Aim when the equipment transition should win.

Verify in Play Mode

  1. Give one Item Set Group three ordered sets, such as Sword, Rifle, and Bow, and add all required Character Items to the Inventory.
  2. Start with Rifle active and produce a positive axis value at or above 0.1. Confirm Equip Scroll (Active) appears only briefly, Equip Unequip (Active) remains through the transition, and Bow becomes active.
  3. Produce another positive value and confirm the cycle wraps to Sword. Produce a negative value and confirm it wraps back to Bow.
  4. Remove Rifle’s required Character Item or disable Can Switch To on that runtime set. Scroll backward from Bow and confirm the selector skips Rifle and chooses Sword.
  5. Provide axis values whose absolute magnitude is below 0.1 and confirm the set does not change. Test values at both 0.1 and -0.1 and confirm they are accepted.
  6. Scroll again while Equip Unequip is still active. Confirm the second request is ignored until the current transition ends.
  7. Start Use or Reload and scroll. With Prevent Start Use Reload Active enabled, confirm the active set does not change until the action stops.
  8. If the character has two groups, operate each group’s configured axis and confirm only the category assigned to that Equip Scroll row changes.

Troubleshoot Equip Scroll

  • Equip Scroll is disabled at runtime: check that an Item Set Manager group and an Equip Unequip ability use the same Item Category. A missing match logs an error and disables the selector.
  • The wheel never changes equipment: inspect the raw axis value, confirm Start Type is Axis, and verify Input Names uses the correct mapping. Lower Scroll Sensitivity only when the value never reaches the current threshold.
  • The physical wheel direction feels reversed: the code maps positive to next and negative to previous. Invert the input binding or processor so its sign matches the desired physical direction.
  • One wheel movement changes several sets: confirm the input produces one pulse and that the matching Equip Unequip remains active for the intended transition. Equip Unequip blocks later Equip Scroll starts only while it is active.
  • A set is unexpectedly skipped: inspect it in the runtime Item Set list. Check Enabled, Can Switch To, the Item Set Rule, required slots and counts, and whether every usable Character Item can currently equip.
  • The cycle starts in the wrong group: assign Item Category explicitly. Leaving it empty selects the first Item Set Group.
  • Scrolling waits until firing or reloading ends: this is the default Prevent Start Use Reload Active behavior. Disable it only after confirming that the item actions and transition animations support switching mid-action.
  • Equip Scroll flashes active but the item never changes: check the matching Equip Unequip row and its Character Item Equip Event, Equip Complete Event, Unequip Event, and Unequip Complete Event.
  • The new item appears but the wrong animation remains visible: move Equip Unequip above the active item ability whose pose should yield. Reordering Equip Scroll itself does not change Animator priority.
  • Item Set abilities explains the shared category, Item Set Manager, and Equip Unequip architecture.
  • Equip Unequip performs the transition selected by Equip Scroll.
  • Equip Next provides a dedicated forward button.
  • Equip Previous provides a dedicated reverse button.
  • Toggle Equip switches between a non-default set and the category’s default set.
  • Item Set and Rules explains generated sets, validity, Can Switch To, and the default Item Set.
  • Animator Parameters describes the Item State Index values supplied by Equip Unequip.

Developer reference

Equip Scroll exposes ScrollSensitivity and inherits ItemCategory, ItemSetCategoryID, PreventStartUseReloadActive, and the resolved read-only ItemSetGroupIndex. The base Ability also exposes InputAxisValue, which is populated from the raw player input before CanStartAbility() evaluates the threshold and direction.

For programmatic switching, use ItemSetManagerBase.NextActiveItemSetIndex(groupIndex, activeIndex, next) to resolve a target and pass that result to the matching EquipUnequip.StartEquipUnequip(itemSetIndex). This avoids depending on a stored axis value when no player input initiated the request.

Equip Scroll has no feature-specific event. Use the built-in Event System to observe the resulting transition:

  • OnItemSetManagerUpdateNextItemSet (int groupIndex, int previousIndex, int nextIndex) reports the pending target.
  • OnActiveItemSetChange (int groupIndex, ItemSet previousSet, ItemSet newSet) reports the active-set change.
  • OnCharacterItemAbilityActive (ItemAbility, bool) reports Equip Scroll’s brief start and stop and the longer Equip Unequip lifecycle.