Toggle Equip

Export

Toggle Equip switches one equipment category between its default Item Set and the last valid non-default set. Use it for a holster button, a show-or-hide equipment control, or any input that should restore the player’s previous loadout with one press.

Toggle Equip only chooses the target. A matching Equip Unequip ability performs the visible multi-slot transition.

Before you begin

The character needs:

  • an Inventory containing the Character Items used by the category;
  • an Item Set Manager with an Item Set Group for that Item Category;
  • an Item Set Rule that produces a predictable default when the category should holster to a defined combination;
  • at least one valid non-default Item Set; and
  • an Equip Unequip item ability with the same Item Category.

The default Item Set does not have to be empty. Toggling away from a weapon set equips whatever combination the group marks as default. If the group has no default Item Set, Toggle Equip hands index -1 to Equip Unequip and the category is unequipped instead.

Configure Toggle Equip

  1. Select the character and expand the target group under Item Set Manager > Item Set Groups.
  2. Confirm the group’s Item Category and Item Set Rules generate the equipped combinations you want to restore. Configure one rule to produce the intended default combination and enable Default on that rule.
  3. On Ultimate Character Locomotion, expand Item Abilities and add Equip Unequip if this category does not already have one. Assign the same Item Category.
  4. Add Toggle Equip to Item Abilities and assign that Item Category.
  5. Keep the normal input defaults: Start Type is Button Down, Stop Type is Manual, and Input Names contains Toggle Item Equip. Toggle Equip stops itself immediately after handing off the target.
  6. Keep Prevent Start Use Reload Active enabled when firing or reloading should finish before the category changes. It is enabled by default. Keep the matching Equip Unequip row consistent with this setting.
  7. Leave Toggle Default Item Set On Start disabled for the normal player-controlled workflow. Enable it only when this row should make one conditional toggle request during startup if the Item Set Manager still reports no active set.
  8. Map Toggle Item Equip to the intended player control and configure the visible timing on each Character Item’s equip and unequip events or durations.

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 multiple groups so Toggle Equip finds the intended Equip Unequip row.

Toggle Equip allows duplicate types. Add one row per independently toggled category, such as a primary weapon and a shield, and give each row its own Item Category and input when needed.

Choose the toggle behavior

Define the default state

Use the group’s default Item Set as the state reached when equipment is put away. An empty default holsters everything in that category. A non-empty default can keep a baseline item equipped, such as unarmed hands or a permanent tool.

Toggle Equip can select the default even when that set’s Can Switch To option is disabled. This is useful when cycling abilities should skip the holstered set but the dedicated toggle should still reach it.

If the default set is invalid or disabled, Toggle Equip can briefly start and stop without a visible change because Equip Unequip rejects the target. Keep the default valid for the inventory state in which the player may holster.

Understand the remembered set

Whenever this category changes to a non-default Item Set, Toggle Equip remembers both that set and its current index. A press from the non-default set requests the default. A later press from the default restores the remembered set when it is still valid.

The remembered Item Set object survives list reordering. If the Item Set Manager rebuilds the group and the same set moves to another index, Toggle Equip resolves its new index before restoring it.

If the remembered set becomes invalid or is removed, Toggle Equip clears that memory and searches forward from the current active index for the next valid, switchable Item Set. It wraps through the group and refuses to start when no alternative exists. Can Switch To is checked during this fallback search; it does not block a still-valid remembered set from being restored.

Decide whether to toggle during startup

Toggle Default Item Set On Start is disabled by default. When enabled, the ability checks the Item Set Manager during Start. It only requests a toggle when that group still reports active index -1; it does nothing when the manager has already established an active set.

That startup request uses the same remembered-set and next-valid-set rules as a button press. It is not an unconditional "equip the default" command. For predictable starting equipment, configure the Inventory, default Item Set, and Item Set Rules so the manager can establish the intended active set; use this option only for the conditional toggle behavior.

Coordinate Use and Reload

The inherited Prevent Start Use Reload Active setting is checked by Toggle Equip before it hands off. Equip Unequip performs its own check afterward. Unlike the cycling selectors, Toggle Equip does not temporarily copy its prevention setting to Equip Unequip, so keep the two rows aligned.

With both defaults enabled, any active Use or Reload prevents the toggle. Toggle Equip never cancels those actions. While Equip Unequip is removing an item, the worker also prevents a new Use or Reload from starting.

How it runs

  1. Toggle Equip listens to the category-matched Equip Unequip ability and Item Set Manager for active-index changes.
  2. When a non-default set becomes active, it stores that Item Set and index. When the default becomes active, it keeps the stored set only while it remains valid.
  3. The Toggle Item Equip input attempts to start the ability. The shared category and Prevent Start Use Reload Active checks run first.
  4. If there is no valid remembered set, Toggle Equip asks the manager for the next valid, switchable set after the active index. The search wraps at the end of the group.
  5. Otherwise, it chooses the default when a non-default set is active, or the remembered non-default set when the default is active.
  6. Toggle Equip calls StartEquipUnequip on the matching worker and stops immediately. It does not stay active for an animation and does not supply Item State Index or Item Substate Index values.
  7. Equip Unequip compares the active and target sets across every slot, completes all outgoing unequips, then equips the incoming items. Its default Animator state indexes are 5 for unequip and 4 for equip.

When Unequip All On Death is enabled on the Inventory, Toggle Equip clears its remembered set on death. When it is disabled, the memory remains available while Equip Unequip handles the normal death and respawn equipment lifecycle.

Verify in Play Mode

  1. Create one Item Set Group with a valid empty default plus two valid non-default sets, such as Sword and Rifle. Give the Inventory the required Character Items.
  2. Start with Sword active and press Toggle Item Equip. Confirm Toggle Equip (Active) appears only briefly, Equip Unequip (Active) remains through the transition, and the default set becomes active.
  3. Press again. Confirm Sword, not simply the next list entry, is restored.
  4. Equip Rifle through another selector, then toggle to the default and back. Confirm Toggle Equip now restores Rifle.
  5. While the default is active, remove the remembered Rifle or make its set invalid. Press Toggle and confirm the next valid, switchable alternative is selected; if none exists, confirm the ability does not start.
  6. Reorder the runtime sets while the remembered set still exists. Toggle away and back, then confirm the same combination returns at its new index.
  7. Start Use or Reload and press the toggle. With prevention enabled on both rows, confirm the set does not change until the action stops.
  8. If testing Toggle Default Item Set On Start, begin with no active set and inspect the runtime group. Confirm the option makes only one startup request and that the resulting set follows the normal selection rules.

Troubleshoot Toggle Equip

  • Toggle Equip is disabled at runtime: check that an Item Set Manager group and an Equip Unequip ability use the same Item Category. A missing worker logs an error and disables the selector.
  • Pressing the input does nothing: confirm Toggle Item Equip is mapped, the active index is not -1, and the group contains a valid alternative. With no remembered set, the fallback search needs at least two generated sets and skips sets that are invalid or cannot be switched to.
  • The row flashes active but equipment does not change: check that the target default or remembered set is valid, then inspect the matching Equip Unequip row and Character Item timing events.
  • The wrong category changes: assign Item Category explicitly on both Toggle Equip and Equip Unequip. Leaving it empty selects the first Item Set Group.
  • The toggle restores the wrong set after another equipment change: inspect which non-default set most recently became active in this category. Every accepted active-index change updates the remembered set.
  • The remembered set is skipped after inventory changes: confirm the same Item Set still exists and is valid. If it was removed or became invalid, Toggle Equip deliberately searches for the next valid, switchable set.
  • The default does not look holstered: inspect the items generated for the group’s default Item Set. Toggle Equip equips that combination; it does not assume the default is empty.
  • Toggling waits while firing or reloading: check Prevent Start Use Reload Active on both Toggle Equip and Equip Unequip. Both are enabled by default and either row can block the handoff.
  • Toggle Default Item Set On Start appears to do nothing: the option only acts when the manager reports active index -1 during Start. If the manager already established its default, no startup toggle is requested.
  • The toggle animation is hidden by Aim or another pose: move Equip Unequip above the competing active item ability. Reordering Toggle Equip does not change Animator priority because the selector supplies no item state.

Developer reference

Toggle Equip adds the public ToggleDefaultItemSetOnStart property to the inherited ItemSetAbilityBase members. Its remembered Item Set, previous index, and next index are internal runtime state.

Call StartAbility() on the category-matched Toggle Equip instance to request the same validated toggle used by input. On a character with duplicate Toggle Equip rows, select the copy whose ItemSetCategoryID or ItemCategory matches the intended group before starting it.

The built-in Event System keeps the selector synchronized:

  • OnEquipUnequipItemSetIndexChange (int itemSetIndex) is received from the matching Equip Unequip ability and updates the remembered set.
  • OnItemSetIndexChange (int groupIndex, int itemSetIndex) updates the same state when the Item Set Manager changes or rebuilds the group.
  • OnDeath clears the remembered set only when the Inventory’s Unequip All On Death option is enabled.
  • OnCharacterItemAbilityActive (ItemAbility, bool) reports Toggle Equip’s brief start and stop like other item abilities; the matching Equip Unequip row reports the longer transition separately.

Toggle Equip emits no unique gameplay event. Listen to the Item Set Manager’s active-set events or the matched Equip Unequip lifecycle when code needs to observe the resulting equipment change.