> 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/how-it-works.md).

# How it works

## Overview

This page follows an item through its whole life — lying on the ground, picked up, holstered, drawn, used, interrupted, put away, dropped — and names the method that runs at each step. Read it once and the rest of the documentation stops being a list of fields.

***

## The object graph

```
SuperItemManager ──── owns ────► SEquipPoint[]   (ID + Transform + current Item)
        │                        SItemHolster[]  (ID + Slots[] + stored Items)
        │                        SuperItemOffsets (asset: all offsets for this character)
        │
        └──── listens to ──────► MAnimal   (ModeStart, ModeEnd, OnState, OnStance)
                                 MInteractor (OnFocusing, OnUnFocusing, OnInteract)
                                 IKManager (AnimatorIKAction, UpdateIKAction)
                                 IRider    (RiderStatus — mount, dismount, mount trigger)

SuperItem ─────── owns ────────► ItemActionSet[]
                                       └── ItemAction[]
                                                 └── ItemProcessor[]
```

Nothing in that graph is a Transform reference from the item to the character. The item stores IDs; the Manager resolves them. That is what lets one sword prefab work on every character in the project.

***

## 1 — Picking up

The item is an `IInteractable`. When the character's `MInteractor` focuses it, `SuperItem.Focus()` fires `On Focused` and the `Focused By Reaction`. When the interactor actually interacts, `SuperItemManager.OnInteractorInteract` runs:

1. If `Pick Duration` is `0`, the item is equipped (`Auto Equip` on) or holstered (`Auto Equip` off) immediately.
2. Otherwise the `Pick Mode` is force-activated on the `MAnimal`, and the equip/holster is delayed by `Pick Duration` so it lands on the animation.

{% hint style="info" %}
`Auto Pick` on the item makes the pick-up happen the moment the interactor focuses it, with no input. Use it for ammo and consumables.
{% endhint %}

***

## 2 — Holstering

`Item_Holster(item)` looks up the holster whose `HolsterID` matches the item's `Holster`:

1. If the item was equipped, it is unequipped instantly (no store animation — you asked for it to be put away *now*).
2. The holster resolves a **slot** from the item's authored **Slot priority list** in the `SuperItemOffsets` asset: the first slot of that list that is still free wins. If every authored slot is taken it scans the rest of the holster, wrapping around.
3. The item is parented to the slot Transform and given the **holster offset** from the same asset.
4. Physics are disabled, `Is In Holster` becomes `true`, and `On Holstered` fires.

If the primary holster has no free slot left and the item declares a **Secondary Holster**, the copy falls through to it — with its own Offset, Slots and Holster Anim entry. Only when there is nowhere left to go is the **oldest** stored item evicted and dropped properly — unparented, with its physics restored — and a warning tells you to add more slot Transforms.

{% hint style="danger" %}
If the item's `Holster` ID has no matching holster on the Manager, the item is **dropped** and a red console message names the missing ID. This is the single most common Super Item setup mistake.
{% endhint %}

***

## 3 — Equipping

`Item_Equip(newItem)` is the busiest method in the system. In order:

### a. Resolve conflicts with what is already held

For every occupied Equip Point it compares the new item against the old one using `Unique Equipment` and the `Can Be Equipped With` list:

| Situation                                  | Result                                                                                                              |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| Same item, and `Self Store Holster` is on  | The item is put away instead — pressing the holster input twice toggles.                                            |
| New item is unique, or rejects the old one | Old item is holstered (or dropped if it was not equipped).                                                          |
| Old item is unique, or rejects the new one | Old item is holstered. If it shares a holster with the new item, the previously stored item is drawn to replace it. |
| Both accept each other                     | Both stay equipped — this is how a sword and shield coexist.                                                        |

### b. Resolve the Equip Point

The primary point wins if it is free or already holds this item. If it is occupied by a *compatible* item and the new item declares a `Secondary Equip Point`, the item falls through to the secondary point — that is dual wielding. If nothing is free, the occupant is evicted.

### c. Play the draw animation

If `Equip Duration` is greater than `0` and an `Equip Mode` is set, the Mode is force-activated with the Holster ID as its ability (signed by the side), the Equip Point is *reserved* for the item, and the actual parenting is delayed by `Equip Duration`.

### d. Land the item

`Equip_INTERNAL_FAST` unholsters it, parents it to the Equip Point with the offset from the `SuperItemOffsets` asset, and calls `SuperItem.Equip(manager)`, which:

* disables the item's physics and colliders,
* overrides the item's trigger layers with the character's,
* fires the `Equip Reaction`,
* sets the character's `Stance` and `Strafe` to what the item asks for,
* calls `Item Equipped` on every processor of every set,
* enters the Active Action Set,
* **connects the inputs**,
* fires `On Equip`.

Finally the Manager writes the `Left/Right Item Type` and `Mirror` Animator parameters, refreshes the rein hands, and tells the item to **re-sync with the whole ambient world state**.

{% hint style="info" %}
**Ambient re-sync on equip.** An item is not only checked for `On Equip`. It re-evaluates every Auto Activation that describes *state* rather than an event: `On Equip`, `Riding`, `Check State`, `Check Stance`, `Check Interactor` and `Check Target Changed`. Without it, mounting first and drawing the bow four frames later would leave the bow's `Riding` set unchecked. `On Action` and `External` are deliberately excluded — those are events, not state.
{% endhint %}

{% hint style="info" %}
**The Equip Point reservation matters.** During the draw animation the point holds no item yet, only a reservation. Without it, drawing two dual-wield items in the same frame would send both to the primary point.
{% endhint %}

***

## 4 — Using the item

### Input to Action

When the item is equipped, every Action in the Active Set whose `Action ID` appears in the Manager's `Actions Input` list gets its input connected. Pressing that input calls `ItemAction.ActivateOnInput`:

* **Pressed** — the action starts on press and is released on release.
* **Toggle** — each press flips the state; releases are ignored.

### StartAction

Before an action runs, it must pass, in order:

1. `Just Activate` — an action cannot restart on the frame it started.
2. `Primary Hand Only` — a dual-wield follower copy skips the action entirely.
3. `Interrupt Self` — if off and the action is already playing, nothing happens.
4. `Rate` — the cooldown since the last activation.
5. **PreRequisites** — the item is enabled, the action and set are Active, the item is equipped, the action ID is not in `Blocked Actions`, no higher-`Priority` Main Action is playing, and (for a Secondary action) its Master Action is the playing Main Action.
6. **Conditions** — `Conditions On Owner`, `Conditions On Target`, and the set's `Set Conditions`.

If all pass, the action becomes the item's **Main Action** (or its **Slave Action** if it has a Master), any previous Main Action is exited, and every processor flagged `On Action Start` executes.

{% hint style="info" %}
The cooldown is stamped **after** the vetoes, not before. An activation that never happened — item not equipped, action blocked, conditions failed — does not burn the `Rate`, so a failed press never pushes the next valid one away.
{% endhint %}

### Processor execution

Each processor declares **when** it runs through its `Execute` flags, and each can carry its own `Delay`.

Processors can also chain: a processor that finishes calls `ProcessorCompleted`, which executes every **following** processor flagged `On Prev Completed`. A processor that is cut short calls `ProcessorInterrupted`, which triggers `On Prev Interrupted`. This is how a charged bow works — the *Charge* processor completes, and the *Projectile - Fire* below it fires.

### Update, release and exit

While playing, `Update` runs each frame and re-checks PreRequisites and Conditions. The `Update Rate` on the Action throttles the `On Action Updated` processors only — `0` means every frame, which is what time-based processors (Charge, Wait) need; a value above `0` turns the Action into an automatic repeater (`0.1` on a Fire processor = 10 shots per second).

The action is released when the input is released (for `Duration` ≤ 0), when the `Duration` elapses, or when a condition stops passing. `Released` runs the `On Action Released` processors and then, if `Stop Action On Release` is set, exits the action.

With **Restart On Conditions** enabled, an Action that its Conditions cut short while the input is still held stays **armed**: it starts again by itself the moment the Conditions pass again, with no second press. Aiming a bow while mounted is the case it exists for — the aim angle leaves the allowed range, the Action ends, and it resumes when the angle is valid again.

***

## 5 — Interruption

Two different things can stop an action, and they behave differently.

**A normal exit** respects `Can Exit`, PreRequisites, and any hold placed by a Secondary action.

**An interruption** ignores all of that. It happens when the character enters a State, Mode or Stance listed in the Action Set's `Interrupt States` / `Interrupt Modes` / `Interrupt Stances`. Every playing Action of the set is force-ended, every pending processor delay is cancelled so it can never fire, and the set's `On Interrupt Reaction` runs once.

{% hint style="info" %}
An action cannot be interrupted on the frame it started. Its own processors usually start a Mode and change a State, and without that guard an `[✕ Exclude]` interrupt list would kill the action instantly.
{% endhint %}

The Manager has a broader version of the same idea. `No Items In State`, `No Items In Mode` and `No Items In Stance` **temporarily hold** every equipped item — they are put away **instantly** (never with a Store animation) when the character enters the blocking state, and drawn back when it leaves. How they come back is the only configurable part: **Fast Equip Back** off plays the normal Equip Mode animation, on makes them reappear in the hands instantly.

***

## 6 — Action Set swapping

Sets swap in three ways:

| Trigger                   | How                                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| From code or a UnityEvent | `item.ActionSet_Active("name")`, `ActionSet_Active(index)`, `ActionSet_RestoreToDefault()` |
| From a Reaction           | The Super Item Reaction                                                                    |
| Automatically             | The set's `Auto Activation` flags + `Auto Activation On` / `Off` conditions                |

Automatic activation is evaluated whenever a listed event happens (state change, stance change, mode start/end, interactor focus, target change, equip, unequip, any Rider notification, or an external call). The sets are checked **top-down and the first match wins** — reorder the list to change priority. Sets flagged **Ignore** are skipped by every one of these checks. If no set claims the activation, the currently active set returns to Default when its `Auto Activation Off` conditions pass.

Swapping a set exits the old one (releasing its IK targets and disconnecting inputs), enters the new one (adding its IK targets, resolving and initialising its IK profile, connecting inputs), refreshes the rein hands for the new set's `Free Hands`, and leaves the item otherwise untouched.

***

## 7 — Riding

When the character has an `MRider`, the Manager subscribes to its `RiderStatus` notifications — mount trigger enter/exit, start/end mount, start/end dismount, call mount. Every one of them does two things:

1. **Refreshes the rein hands.** A hand that holds an item cannot hold the rein. `Free Hands` on the Action Set (held for as long as the set is active) and on the Action (held only while it plays) add the *off* hand to that count — a bow being drawn takes both.
2. **Re-checks every Action Set listening to `Riding`.** One flag covers the whole mount cycle; the set's own `Auto Activation On` / `Off` conditions do the filtering (for example `[Riding] Rider is Riding`).

***

## 8 — Unequipping and dropping

`Item_Unequip(item)` plays the `Unequip Mode` for `Equip Duration` seconds, then clears the Animator hand parameter for the side the item was on, clears the Equip Point, and calls `SuperItem.Unequip(manager)` — which restores the character's Stance and Strafe, exits the Action Set, disconnects the inputs, and fires `On Unequip`. If the Equip Point has `Store On Holster` enabled, the item is holstered afterwards.

`Item_Release(item)` (also reachable as `Item_Drop`) unequips and unholsters instantly, moves the item to the Manager's `Drop Point` if one is assigned, restores its physics and colliders, and clears its `User`.

With a **Default Item** assigned on the Manager, emptying the hands is not the end of it: the fallback item (an Unarmed item, typically a child of the character with `Equip Duration` at `0`) is equipped automatically so the character can still act.

***

## Execution order

`SuperItemManager` runs at `[DefaultExecutionOrder(1500)]`, after the `MAnimal` and the Animator, so that state and mode events for the frame have already been dispatched. On `OnEnable` it delays its `Initialize` by 5 frames before equipping any item authored in an Equip Point or Holster at edit time — everything else must finish waking up first.