> For the complete documentation index, see [llms.txt](https://malbersanimations.gitbook.io/animal-controller/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://malbersanimations.gitbook.io/animal-controller/super-item/super-item-system/reactions.md).

# Reactions

Reactions for driving the Super Item System. Last updated AC v1.5.3

## Overview

The Super Item System ships **twelve** `Reaction` entries. Reactions are the Animal Controller's scriptable callbacks — you drop them into any Reaction list on any component and they act on their target without you writing code.

They are grouped by what they react on:

| Group           | Reacts on          | What it drives                                                                      |
| --------------- | ------------------ | ----------------------------------------------------------------------------------- |
| `[Manager]` — 6 | `SuperItemManager` | The character: what it draws, stores, drops, picks, locks and which Action it fires |
| `[Item]` — 5    | `SuperItem`        | One item: its Action Sets, its Actions, its Target and its own switches             |
| `[Pouch]` — 1   | `PouchManager`     | The ammunition reserve                                                              |

Anything in the game can therefore drive an item: a cutscene, a UI button, a pickup, an AI decision, a Mode's own reaction list.

{% hint style="info" %}
These are `Reaction2` entries. The older `MReactions` class is marked `[Obsolete]` — do not use it in new work.
{% endhint %}

{% hint style="warning" %}
**Point each one at the right component.** A reaction resolves its target by searching the reactor, then its parents, then its children. A `[Manager]` reaction therefore works when aimed at the character root, at the Animal, or at an item already in that character's hierarchy — but aimed at an item lying free in the world it finds no manager and does nothing.
{% endhint %}

### Which one do I need

| I want to…                                                                  | Use                                                                                              |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Draw / store / drop an item by ID, with no scene reference                  | [Manager Equip and Unequip](#manager-equip-and-unequip), [Manager Drop Item](#manager-drop-item) |
| Make an NPC or a UI button fire, aim or block                               | [Manager Item Action](#manager-item-action)                                                      |
| Change what an item can do (its Action Set)                                 | [Manager Item Action Set](#manager-item-action-set) or [Item Action Set](#item-action-set)       |
| Give a character an item from a pickup or a cutscene                        | [Manager Pick Item](#manager-pick-item)                                                          |
| Put every weapon away while the character carries a box, then get them back | [Manager Global](#manager-global) → `Lock`                                                       |
| Make a character draw everything it picks up                                | [Manager Global](#manager-global) → `Auto Equip`                                                 |
| Drive one specific item, dual-wield copies included                         | the `[Item]` reactions                                                                           |
| Add, remove or cheat ammunition                                             | [Pouch Ammo](#pouch-ammo)                                                                        |

***

## Manager Equip and Unequip

**Menu path:** `Malbers ▸ Super Item ▸ [Manager] Equip - Unequip` **Reacts on:** a `SuperItemManager`

Draws, stores and holsters the items the character already owns. Every command addresses its item through an **ID asset**, so nothing here needs a scene reference — the same reaction asset works on every character.

#### Command

| Value                        | Effect                                                                                                                                                                               |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Equip**                    | Draws the item with that Super Item ID out of its holster and into the hands. An item that is not holstered is left alone.                                                           |
| **Equip From Holster**       | Draws whatever is stored in that Holster. When the holster is empty and **Self Store Holster** is on, it stores the item in hand instead — the same toggle a holster input performs. |
| **Unequip**                  | Stores the item with that ID, playing its Unequip animation.                                                                                                                         |
| **Unequip From Equip Point** | Stores whatever item sits on that Equip Point.                                                                                                                                       |
| **Unequip All**              | Stores every item held in the hands.                                                                                                                                                 |
| **Unequip All But**          | Stores every item in the hands *except* the one with that ID. Does nothing when that item is not in the hands, so it can never empty both hands by accident.                         |
| **Store In Holster**         | Sends the item straight to its holster, with no Unequip animation.                                                                                                                   |
| **UnHolster**                | Takes the item out of its holster without equipping it.                                                                                                                              |

#### Item

The Super Item ID the command applies to. Shown for every command that targets one item.

#### Holster

The Holster slot to draw from. Shown for **Equip From Holster**.

#### Equip Point

The Equip Point holding the item to store. Shown for **Unequip From Equip Point**.

#### Fast

Skips the Equip animation: the item appears directly in the hand. Shown for **Equip**.

{% hint style="info" %}
**Dual wielding is handled.** The holster lookups scan every stored slot, not only the holster head, so the off-hand copy of a paired item is found like any other.
{% endhint %}

***

## Manager Drop Item

**Menu path:** `Malbers ▸ Super Item ▸ [Manager] Drop Item` **Reacts on:** a `SuperItemManager`

Releases items back into the world. Dropping unequips and unholsters first, so the item leaves the character cleanly whichever state it was in.

#### Command

| Value                | Effect                                                              |
| -------------------- | ------------------------------------------------------------------- |
| **By Item ID**       | Drops that item, equipped or holstered.                             |
| **From Equip Point** | Drops whatever item sits on that Equip Point.                       |
| **From Holster**     | Drops the item stored in that Holster.                              |
| **All Equipped**     | Drops every item held in the hands.                                 |
| **Everything**       | Drops every item in the hands *and* every item stored in a holster. |

{% hint style="warning" %}
**Everything** empties the character completely — hands and holsters. It is what a death or a disarm cutscene wants, not a "put your weapon away" button. That one is **Unequip All** on the [Equip and Unequip](#manager-equip-and-unequip) reaction.
{% endhint %}

***

## Manager Item Action

**Menu path:** `Malbers ▸ Super Item ▸ [Manager] Item Action` **Reacts on:** a `SuperItemManager`

Presses, releases and interrupts an Item Action (Fire, Aim, Block…) from outside the input system. It goes through the very same path a real input press takes, so an NPC, a UI button and the player produce identical behaviour — including the Fast Weapons draw when nothing equipped answers the Action.

#### Command

| Value             | Effect                                                             |
| ----------------- | ------------------------------------------------------------------ |
| **Press**         | Presses the Action input and holds it, exactly like a held button. |
| **Release**       | Releases the Action input.                                         |
| **Tap**           | Presses, then releases after **Hold Time**.                        |
| **Interrupt**     | Force-stops that Action on every equipped item.                    |
| **Interrupt All** | Force-stops every Action of every equipped item.                   |

#### Action

The Item Action ID to drive.

#### Item

Restricts the Action to the item with this ID. Leave it empty and the manager picks the best equipped item that answers the Action — the one already holding the input first, then the one that can actually start it right now.

#### Hold Time

Seconds the input stays pressed before **Tap** releases it. Zero releases on the next frame.

{% hint style="info" %}
**Press without Release leaves the input held.** A held Aim or Block stays on until something releases it. Pair every **Press** with a **Release**, or use **Tap** when you only want one shot.
{% endhint %}

{% hint style="info" %}
When nothing equipped answers the Action and **Fast Weapons** is on, the manager draws a holstered candidate and starts the Action on it. A single "Fire" reaction can therefore arm an unarmed character and shoot.
{% endhint %}

***

## Manager Item Action Set

**Menu path:** `Malbers ▸ Super Item ▸ [Manager] Item Action Set` **Reacts on:** a `SuperItemManager`

Changes the [Action Set](/animal-controller/super-item/super-item-system/super-item/item-action-sets.md) of the items the character is holding, without needing a reference to the item itself. This is the character-side twin of the [Item Action Set](#item-action-set) reaction.

#### Command

| Value                   | Effect                                                              |
| ----------------------- | ------------------------------------------------------------------- |
| **Set Active By Name**  | Activates the set whose Name matches.                               |
| **Set Active By Index** | Activates the set at this index, wrapping around the list.          |
| **Set Default By Name** | Changes *which* set counts as the Default, without activating it.   |
| **Restore To Default**  | Returns the item to its Default set.                                |
| **Interrupt Set**       | Force-stops every Action of the Active Set, keeping the set active. |

#### Item

The item the command applies to. **Leave it empty to hit every equipped item**, the Default Item (fists) included.

#### Action Set Name

The name to match. Shown for the two by-name commands.

#### Index

The index to activate. Shown for the by-index command.

***

## Manager Pick Item

**Menu path:** `Malbers ▸ Super Item ▸ [Manager] Pick Item` **Reacts on:** a `SuperItemManager`

Picks a Super Item up from the world, playing the item's Pick Mode and honouring its Pick Duration — the same path the Interactor uses.

#### Command

| Value             | Effect                                                                                                                                             |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Auto**          | To the hands when the manager's global **Auto Equip** is on; otherwise the item's own **Auto Equip** decides, hands or holster.                    |
| **Force Equip**   | Always to the hands, ignoring every **Auto Equip** setting.                                                                                        |
| **Force Holster** | Always to its holster, ignoring every **Auto Equip** setting.                                                                                      |
| **Focused**       | Picks the first free item currently inside the character's Interactor — what the pick-up prompt is pointing at. Lands where **Auto** would put it. |

#### Item GameObject

The GameObject holding the Super Item to pick. Shown for the three explicit commands; **Focused** needs no reference.

{% hint style="info" %}
A pick is refused when the item already belongs to another character, when it happens inside the pick cooldown, or while the manager is **Locked**. **Focused** is the one to wire to a "Pick Up" button, since it always targets what the character is actually looking at.
{% endhint %}

***

## Manager Global

**Menu path:** `Malbers ▸ Super Item ▸ [Manager] Global` **Reacts on:** a `SuperItemManager`

The manager-wide switches and escape hatches.

#### Command

| Value                    | Effect                                                                                                                                                                                 |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Release Hold**         | Clears every **No Items in State / Stance / Mode** block and draws the held items back. A **Lock** is not cleared by it.                                                               |
| **Refresh Default Item** | Re-checks whether the Default Item (fists) belongs in the hands right now.                                                                                                             |
| **Check Action Sets**    | Re-runs the **External** Auto Activation of every equipped item's Action Sets.                                                                                                         |
| **Fast Weapons**         | Turns Fast Weapons on or off.                                                                                                                                                          |
| **Auto Store**           | Sets the Auto Store idle time. Zero disables Auto Store.                                                                                                                               |
| **Enable**               | Enables or disables the Super Item Manager component.                                                                                                                                  |
| **Lock**                 | **Bool Value** on: locks the manager — every equipped item is put away with the manager's **Lock Mode** and every item operation is refused. Off: unlocks it and draws the items back. |
| **Lock Holster**         | Locks the manager, storing every equipped item in its holster whatever the manager's **Lock Mode** says.                                                                               |
| **Lock Hide**            | Locks the manager, hiding every equipped item in place whatever the manager's **Lock Mode** says.                                                                                      |
| **Auto Equip**           | Turns the manager's global **Auto Equip** on or off. On: every picked item goes to the hands. Off: each item's own **Auto Equip** decides.                                             |

#### Bool Value

The on/off value applied by **Fast Weapons**, **Enable**, **Lock** and **Auto Equip**.

#### Float Value

The idle time applied by **Auto Store**.

{% hint style="warning" %}
**Release Hold is a repair tool.** It exists for the case where a Mode is interrupted without ever firing its Mode End, leaving the hands blocked forever. In normal flow the block clears itself — if you find yourself wiring Release Hold routinely, the Mode that opened the block is the thing to fix.
{% endhint %}

{% hint style="info" %}
**Check Action Sets** is what you call after changing something a Set's Auto Activation condition reads (a Stance, a Stat, an inventory flag). Without it the Set only re-evaluates on its own triggers.
{% endhint %}

{% hint style="info" %}
**Lock is a pair.** Lock with Bool Value on when the hands get busy (the box is picked up), and again with Bool Value off when they are free (the box is dropped). Locking twice is harmless; only the items that were in the hands at lock time come back, and an equip requested while locked is refused rather than queued. **Lock Holster** and **Lock Hide** only lock — use **Lock** with the value off to unlock either.
{% endhint %}

### Example — carrying a box

On the box's `Interactable`, an `On Interact` reaction: **\[Manager] Global**, `Lock`, Bool Value `on`. When the carry ends, the same reaction with Bool Value `off`. The character's sword slides into its scabbard instantly on pick-up, every attack input is ignored while the box is carried, and the sword is drawn again with its normal Equip animation once the box lands.

### Example — a brawler that draws everything

On an AI's `Start` reactions: **\[Manager] Global**, `Auto Equip`, Bool Value `on`. Every item its Pick Task collects goes straight to the hands, whatever each item prefab's own **Auto Equip** says, so the NPC is armed the moment it reaches a weapon.

***

## Item Action Set

**Menu path:** `Malbers ▸ Super Item ▸ [Item] Action Set` **Reacts on:** a `SuperItem`

Switches which [Action Set](/animal-controller/super-item/super-item-system/super-item/item-action-sets.md) an item is running. This is the manual counterpart to a set's Auto Activation conditions — reach for it when the trigger is a game event rather than a character state.

#### Command

| Value                       | Effect                                                                                   |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| **Set Action Set By Name**  | Activate the set whose Name matches. Falls back to the Default set if there is no match. |
| **Set Action Set By Index** | Activate the set at this index, wrapping around the list.                                |
| **Set Default Action Set**  | Change *which* set counts as the Default, without activating it now.                     |
| **Restore To Default**      | Return to the Default set.                                                               |

#### Action Set Name

The name to match. Shown for the two by-name commands.

#### Index

The index to activate. Shown for the by-index command.

{% hint style="warning" %}
The reactor must be a `SuperItem`. Pointing this reaction at the character logs an error — target the item, or use [Manager Item Action Set](#manager-item-action-set) instead, which addresses the item by ID.
{% endhint %}

{% hint style="info" %}
A set flagged **Ignore** cannot be activated, not even from here. The request falls back to the Default set and says so in orange in the console.
{% endhint %}

### Example — lighting a torch

The brazier's interaction fires an **\[Item] Action Set** reaction on the torch with `Set Action Set By Name` → `Ignited`. That set has an [Add Element](/animal-controller/super-item/super-item-system/item-processors/damager-add-element.md) processor carrying `Fire` and a different IK profile. The torch's behaviour changes with no code and no branch.

***

## Item Action

**Menu path:** `Malbers ▸ Super Item ▸ [Item] Action` **Reacts on:** a `SuperItem`

Drives one Action of **this** item's Active Set, and blocks or unblocks Actions on it. Where the [Manager Item Action](#manager-item-action) reaction picks the best item that answers an Action ID, this one is anchored to the item it reacts on — which is how you drive one half of a dual-wield pair and leave the other alone.

#### Command

| Value             | Effect                                                                                |
| ----------------- | ------------------------------------------------------------------------------------- |
| **Press**         | Presses the Action input and holds it.                                                |
| **Release**       | Releases the Action input.                                                            |
| **Tap**           | Presses, then releases after **Hold Time**.                                           |
| **Interrupt**     | Force-stops that Action.                                                              |
| **Interrupt All** | Force-stops every Action of the Active Set.                                           |
| **Block**         | Adds the Action to the item's Blocked Actions: it cannot start until it is unblocked. |
| **Unblock**       | Removes the Action from the Blocked Actions.                                          |
| **Clear Blocked** | Empties the Blocked Actions list.                                                     |

#### Action

The Action ID to look for on the item's **Active** Action Set.

#### Hold Time

Seconds the input stays pressed before **Tap** releases it. Zero releases on the next frame.

{% hint style="warning" %}
**The Action has to be on the Active Set.** An Action that lives on another Set is not found and the reaction does nothing — switch the Set first with [Item Action Set](#item-action-set).
{% endhint %}

{% hint style="info" %}
**Block / Unblock always come in pairs.** A blocked Action stays blocked until something removes it, including across an unequip. **Clear Blocked** is the safety net when a block's owner is destroyed or interrupted.
{% endhint %}

***

## Item Equip and Unequip

**Menu path:** `Malbers ▸ Super Item ▸ [Item] Equip - Unequip` **Reacts on:** a `SuperItem`

Equips, stores, holsters or drops **this** item, through the Super Item Manager that owns it.

#### Command

| Value                | Effect                                                             |
| -------------------- | ------------------------------------------------------------------ |
| **Equip**            | Puts the item in the hands.                                        |
| **Unequip**          | Stores the item, playing its Unequip animation.                    |
| **Store In Holster** | Sends the item straight to its holster, with no Unequip animation. |
| **UnHolster**        | Takes the item out of its holster without equipping it.            |
| **Drop**             | Drops the item back into the world.                                |

#### Fast

Skips the Equip animation. Shown for **Equip**.

{% hint style="warning" %}
**The item needs a User.** All five commands run through the manager that owns the item, so an item lying free in the world has nothing to run them on — the reaction warns in the console and does nothing. To give a free item to a character, use [Manager Pick Item](#manager-pick-item).
{% endhint %}

***

## Item Target

**Menu path:** `Malbers ▸ Super Item ▸ [Item] Target` **Reacts on:** a `SuperItem`

Sets or clears the Target the item is pointed at — what the Aim logic and the item's Processors read.

#### Command

| Value                  | Effect                                         |
| ---------------------- | ---------------------------------------------- |
| **Set Target**         | Uses the GameObject stored on the reaction.    |
| **Set Target To User** | Uses the character currently holding the item. |
| **Clear Target**       | Removes the item's Target.                     |

#### Target

The GameObject the item will aim at. Shown for **Set Target**, and it accepts a GameObject Var so a runtime target can be shared between systems.

***

## Item Toggle

**Menu path:** `Malbers ▸ Super Item ▸ [Item] Toggle` **Reacts on:** a `SuperItem`

Flips the item's own switches.

#### Command

| Value            | Effect                                                                                                                        |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Auto Equip**   | On: a picked item goes to the hands. Off: it goes to its holster. Overridden while the manager's global **Auto Equip** is on. |
| **Interactable** | Whether the item can be focused and picked by an Interactor.                                                                  |
| **Physics**      | On restores the Rigidbody and colliders, off freezes them — what equipping does internally.                                   |
| **Colliders**    | The item's internal colliders (hit boxes and triggers).                                                                       |
| **GameObject**   | The item's GameObject itself.                                                                                                 |

#### Value

The on/off value applied to the switch.

{% hint style="warning" %}
**Physics and Colliders are managed by the equip flow.** Equipping, holstering and dropping already set them. Overriding them by hand on an item the character is holding will be undone by the next equip change — use these for items that stay in the world (a trap, a display piece, a locked prop).
{% endhint %}

***

## Pouch Ammo

**Menu path:** `Malbers ▸ Super Item ▸ [Pouch] Ammo` **Reacts on:** a `PouchManager`

Adds, removes and sets ammunition in the character's reserve, and switches infinite ammo on and off.

#### Action

| Value             | Effect                                                                                                  |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| **Add Amount**    | Add `Amount` of the projectile to the reserve.                                                          |
| **Remove Amount** | Subtract `Amount` from the reserve.                                                                     |
| **Clear**         | Empty that reserve. The Ammo entry itself stays in the pouch.                                           |
| **Infinite**      | Turn Infinite Ammo on or off for **one** projectile reserve.                                            |
| **Infinite All**  | Turn Infinite Ammo on or off for the **whole pouch** (the master switch).                               |
| **Set Amount**    | Set the reserve to exactly `Amount`, up or down.                                                        |
| **Clear All**     | Empty every reserve in the pouch.                                                                       |
| **Refresh UI**    | Re-fire **On Ammo Changed** so any bound UI redraws. Leave the Projectile ID empty to refresh them all. |

#### Projectile ID

Which ammo type. Hidden for **Infinite All** and **Clear All**, which have no per-projectile target.

#### Amount

How many. Shown for **Add Amount**, **Remove Amount** and **Set Amount**.

#### Infinite Value

The on/off value applied by **Infinite** and **Infinite All**.

{% hint style="warning" %}
**Infinite affects the reserve only.** A weapon that uses a Chamber still empties its magazine and still has to Reload — it simply never runs out of rounds to reload with. For a gun that never needs reloading, give it a Chamber Stat that cannot be depleted, or drop the Chamber entirely.
{% endhint %}

{% hint style="info" %}
Adding ammo for a `ProjectileID` the Pouch does not have **creates the entry** and initialises its pool. A pickup can therefore grant a brand-new ammo type without every character pre-declaring it. **Set Amount** does the same when the entry is missing.

`Infinite`, by contrast, needs the entry to exist — it warns instead of creating one.
{% endhint %}

{% hint style="info" %}
**Set Amount** and **Clear** fire the same events as Add and Remove: **On Ammo Changed** with the new total, then **On Ammo Added Or Removed** with the delta. Bound UI updates without any extra wiring.
{% endhint %}

### Example — an arrow pickup

On the pickup's `Interactable`, an `On Interact` reaction: **\[Pouch] Ammo**, `Add Amount`, Projectile `Arrow`, Amount `10`.

### Example — a god-mode cheat

A debug menu button wired to **\[Pouch] Ammo**, `Infinite All`, Infinite Value `on`. Every reserve on the character stops being consumed; pressing it again with the value off restores normal ammo.

***

## Driving items without a Reaction

The Super Item Manager API is UnityEvent-friendly, so `Item_Equip`, `Item_Holster`, `Item_Drop`, `Item_Equip_From_Holster`, `Lock`, `Lock_Holster`, `Lock_Hide` and `Unlock` can still be wired straight into any event slot when you already hold a scene reference to the item or the manager. The reactions above exist for the cases that slot cannot cover: addressing an item by **ID** instead of by reference, reusing one asset across every character, and gating the call behind a condition.

For the reverse direction — an item Action driving the rest of the game — use the [Reactions List](/animal-controller/super-item/super-item-system/item-processors/reactions-list.md) processor, which runs any `Reaction2` on the character or on the item's Target.