> 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/super-item-manager.md).

# Super Item Manager

## Overview

The **Super Item Manager** is the character-side half of the Super Item System. It is the component that actually owns the items: where they are held, where they are stored, which input triggers which action, and how they line up on the skeleton.

Add it to the character root: `Malbers ▸ Interaction ▸ Super Item Manager`. On `Reset` it finds the `MAnimal`, `Aim`, `PouchManager`, `ComboManager`, `MInteractor`, `IKManager` and `Animator`, creates two Equip Points under the humanoid hand bones, and fills the default Holsters and Action Inputs.

{% hint style="info" %}
One Manager per character. The component is not `[DisallowMultipleComponent]`, but a second one would fight the first over the Animator parameters.
{% endhint %}

***

## Requirements

An `MAnimal`, an `Animator`, and an input source are mandatory; everything else is needed only by the features that use it.

***

## How it works

The Manager is a router. It:

* resolves an item's `EquipPointID` / `HolsterID` into real Transforms,
* applies the per-character offsets from the `SuperItemOffsets` asset,
* connects and disconnects item inputs on equip and unequip,
* forwards the `MAnimal`'s State, Mode and Stance events to every held item,
* forwards the `MRider`'s mount and dismount notifications, and hands the rein to whichever hand is free,
* writes the `Left Item Type`, `Right Item Type` and `Mirror` Animator parameters,
* hides items while the character is in a blocking State, Mode or Stance,
* keeps a **Default Item** in hand when nothing else is,
* forwards the Animator's damager activation calls to the held items' trigger proxies.

***

## Properties

The inspector is split across two toolbars: **General / Equip Points / Holsters** and **References / Inputs / Events**.

### General

#### Target Interaction — Override Item Layer / Trigger Interaction / Item Tag Interaction

When an item is equipped, its trigger proxies are re-layered to these values so the character — not the item prefab — decides what the weapon can hit. Set `Override Item Layer` to `0` (Nothing) to leave the item's own layer alone.

#### Animator Parameters — Item Left Hand Type / Item Right Hand Type / Mirror

The names of the Animator parameters the Manager writes. Defaults: `Left Item Type`, `Right Item Type`, `Mirror`. A name that does not exist on the controller is skipped silently.

***

### Equip Points

The list of places an item can be held, plus everything that belongs to holding one. Selecting this tab enables the Scene View handles for editing equip offsets, and draws a preview mesh of the assigned item at each point.

#### Item Offsets

The `SuperItemOffsets` ScriptableObject that holds **every** offset for this character — equip point offsets, holster offsets, holster slot lists, and the Animator overrides. It is injected into each Equip Point and Holster on `Awake`, and its **Equip Point Offsets** table is drawn inline right under the field so you can author entries without leaving the character.

Leave it empty and every item uses the identity offset: Position `(0,0,0)`, Rotation `(0,0,0)`, Scale `(1,1,1)`, Slot `0`. Use the `+` button to create the asset in place.

#### Drop Point

A Transform the item is teleported to before being dropped. Leave it empty to drop the item wherever it currently is. Drawn in the Scene View as a yellow sphere.

#### No Items In State / In Stance / In Mode

Include/exclude lists of `StateID`, `StanceID` and `ModeID`. Entering any of them puts **every equipped item away instantly** — never with a Store animation — and draws them back when the character leaves. Use this for swimming, flying, climbing, or a cutscene mode.

#### Fast Equip Back

How those items come back when the block ends. This is the only configurable half; putting them away is always instant.

| Value             | Behaviour                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| **Off** (default) | The `Equip Mode` animation plays — when the Open Chest animation ends, the weapon is drawn normally. |
| **On**            | The items reappear in the hands instantly, with no Equip animation.                                  |

{% hint style="info" %}
Held items are tracked with a counter, so overlapping reasons (a blocking State *and* a blocking Stance at once) cannot re-equip the item twice.
{% endhint %}

***

### Holsters

The list of places an item can be stored. Selecting this tab enables the Scene View handles for editing holster offsets, and draws the asset's **Holster Offsets** table inline.

#### Self Store Holster

When on, pressing the holster input for a holster whose item is already equipped **puts it away**. When off, the press is ignored — the item can only be stored some other way.

***

### References

Component references the Manager needs. All are auto-filled by `Reset` and re-checked in `OnValidate`, so you rarely touch this tab.

| Field             | Purpose                                                                      |
| ----------------- | ---------------------------------------------------------------------------- |
| **Animal**        | The `MAnimal`. Mandatory. Source of State/Mode/Stance events.                |
| **Animator**      | The `Animator`.                                                              |
| **Aim**           | The `Aim` component. Feeds aim direction and the aim target to ranged items. |
| **Pouch**         | The Pouch Manager. Required by the projectile processors.                    |
| **Combo Manager** | Required by the **Combo** processor.                                         |
| **Interactor**    | The `MInteractor` used to focus and pick up items in the world.              |
| **IK Manager**    | Drives the Action Set `IK Profile`. Without it, IK profiles are ignored.     |

The `MRider` is **not** a field. It is found through the `IRider` interface on `Awake`, so riding support switches itself on for any character that has one.

#### Validate IK Remap

Under the IK Manager field, the tab names the rig-specific **IK Set Remap** assigned to it and offers a **Validate IK Remap** button. It lists every Item IK Set Profile used by this character that has no row on that Remap — those profiles still run, but with the offsets of the rig they were authored on. A missing row is a warning, not an error.

#### Default Item

A fallback `SuperItem` — an Unarmed item, typically — auto-equipped whenever **no** weapon occupies an equip point, so the character can still act (unarmed combo attacks, for instance).

It is not placed on an equip point: it is equipped directly, so it never counts towards the equipped item count and never conflicts with a real weapon. Make it a child `SuperItem` with combo actions and an `Equip Duration` of `0` for an instant swap. Leave the field empty to disable it.

***

### Inputs

#### Actions Input

The mapping from `ItemActionID` to input name. This is the bridge between an item's Actions and the character's input source — an Action whose `Action ID` is not in this list will never receive input.

The defaults created by `Reset` are `Action1`, `Action2`, `Action3`, `Action4`, `Reload` and `Interact`.

{% hint style="warning" %}
The mapping lives on the **character**, not the item. Two different weapons using the `Attack` Action ID both fire from the same input. That is the intent — do not create one Action ID per weapon.
{% endhint %}

#### Holster inputs

Each Holster has its own `Input` string, connected on `OnEnable`. Pressing it draws the items stored in that holster; pressing it again stores them, if `Self Store Holster` is on.

***

## Events

#### On Item Equipped (GameObject)

Invoked when an item is equipped.

#### On Item Unequipped (GameObject)

Invoked when an item is unequipped.

{% hint style="info" %}
Per-item events (`On Equip`, `On Holstered`, `On Focused`…) live on the Super Item itself, per-holster events (`On Item Holster Enter/Exit`) on the Holster, and per-equip-point Reactions (`On Equip` / `On Unequip`) on the Equip Point.
{% endhint %}

***

## API

Everything below is safe to call from code or wire to a UnityEvent.

```csharp
// Equip / unequip
manager.Item_Equip(SuperItem item, bool fast = false);
manager.Item_Equip(GameObject item);
manager.Item_Unequip(SuperItem item);

// Holsters
manager.Item_Holster(SuperItem item);
manager.Item_Holster(GameObject item);
manager.Item_UnHolster(SuperItem item);
manager.Item_HolsterAll();
manager.Item_HolsterAllBut(SuperItem item);
manager.Item_HolsterAll(IDList<SuperItemID> items, bool include);

// Draw from a holster (this is what the holster input calls)
manager.Item_Equip_From_Holster(HolsterID id);
manager.Item_Equip_From_Holster(SuperItem item);

// Pick up
manager.Pick_and_Equip(SuperItem item);
manager.Pick_and_Holster(SuperItem item);

// Drop
manager.Item_Drop(SuperItem item);
manager.Item_Drop(EquipPointID equipPoint);
manager.Item_Drop(HolsterID holster);
manager.Item_Release(SuperItem item);

// Damagers — called by the Animator through the Attack Trigger behaviour
manager.ActivateDamager(int id, int profile);

// Force every equipped item to re-check its Action Set Auto Activation
manager.Set_AutoActivation_External();   // the [External] flag
manager.Set_AutoActivation_Riding();     // the [Riding] flag (the Rider calls this itself)

// Riding / hands
manager.UpdateReinHands();               // recompute which hands are busy and hand the rein over
ItemHands busy = manager.HandsInUse;     // hands taken by items, their Sets and their playing Actions
bool left = manager.IsHandInUse(WeaponSide.Left);
```

### ActivateDamager(id, profile)

Called from the Animator (via the Attack Trigger behaviour) to switch the trigger proxies of every held item on and off during an attack animation.

| `id`      | Effect                                      |
| --------- | ------------------------------------------- |
| `0`       | Disable **all** trigger proxies.            |
| `-1`      | Enable **all** trigger proxies.             |
| any other | Enable only the proxies whose `ID` matches. |

The `profile` is stored as `CurrentDamagerProfile` and read by the **Damager** processors, which skip the hit when their own `Profile` does not match. That is how one weapon can deal different damage on a light and a heavy swing.

***

## Riding

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

**Hands the rein over.** A hand holding an item cannot hold the rein. The hand of the Equip Point is always counted; `Free Hands` on the Action Set adds the off hand for as long as the set is active, and `Free Hands` on an Action adds it only while that Action plays. The result is pushed to `MRider.ReinLeftHand` / `ReinRightHand`.

**Re-checks the `Riding` Action Sets.** One flag covers the whole mount cycle; each set's own `Auto Activation On` / `Off` conditions decide what it means — `[Riding] Rider is Riding`, for example.

Both are safe with no Rider: `HandsInUse` is still maintained as a public query of its own.

***

## Debug

Enable **Debug** on the Manager to print equip, unequip, holster, unholster, drop and rein-hand events to the console, colour-coded and prefixed with the character name. All logging is inside `#if UNITY_EDITOR`, so it costs nothing in a build.

In the Scene View:

* The **Drop Point** is drawn as a yellow sphere whenever it is assigned.
* With the **Equip Points** tab selected, each point draws its assigned item's mesh at the exact runtime transform, a green anchor sphere, and a cube tinted green (valid) or red (the item does not accept that equip point).
* With the **Holsters** tab selected, the same preview is drawn at each holster slot.

Position, rotation and scale handles write straight into the `SuperItemOffsets` asset as you drag — there is no Save button, and the rows are kept in sync automatically.