> 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.md).

# Super Item System

## Overview

The **Super Item System** is the modular equipment system of the Animal Controller. It replaces the older [Weapon Manager](https://malbersanimations.gitbook.io/animal-controller/main-components/weapon-manager) with a data-driven design where an item is not "a sword" or "a rifle" — it is a GameObject that owns a list of **Actions**, and every action owns a list of **Processors** that do the actual work.

That inversion is the whole point. A sword swings because it has a *Play Mode* processor. A rifle fires because it has a *Projectile - Fire* processor. A shield blocks because it has a *Play Mode* processor plus a *Damageable* processor. There is no `MSword` class, no `MRifle` class, and no code to write when you invent a new weapon — you assemble it from processors in the Inspector.

The system also covers everything around the item: picking it up, storing it in a holster, drawing it with an animation, parenting it to the right bone with the right offset, blocking actions while another item is in use, ammo pooling, dual wielding, riding, and IK.

{% hint style="info" %}
**Coming from the Weapon Manager?** Read [Migrating from the Weapon Manager](/animal-controller/super-item/super-item-system/migrating-from-the-weapon-manager.md) first. The concepts map almost one to one, but nearly everything was renamed.
{% endhint %}

***

## Start here

{% content-ref url="/pages/ocSkqHezaeXf8rG3r3j2" %}
[Requirements](/animal-controller/super-item/super-item-system/requirements.md)
{% endcontent-ref %}

{% content-ref url="/pages/EjghC2emsvir7Mg3BcsZ" %}
[How it works](/animal-controller/super-item/super-item-system/how-it-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/LMMfZJOuDUE176l3H3z1" %}
[Create a Melee Weapon](/animal-controller/super-item/super-item-system/how-to/create-a-melee-weapon.md)
{% endcontent-ref %}

***

## How it works

Two components carry the system.

**On the character** — Super Item Manager. It owns the Equip Points (where items are held), the Holsters (where items are stored), the input routing, and the offsets table. It listens to the `MAnimal` for State, Mode and Stance changes — and to the `MRider` for mount and dismount — and forwards them to every held item.

**On the item** — Super Item. It owns the item's identity (`Item Type`, `Equip Point`, `Holster`), its physics behaviour, and its Action Sets.

```
SuperItemManager  (character)
├── Equip Points     ── where items are held      (Right Hand, Left Hand, Head…)
├── Holsters         ── where items are stored    (Left Holster, Right Holster…)
├── Item Offsets     ── SuperItemOffsets asset: every offset for this character
├── Actions Input    ── ItemActionID → input name
├── Default Item     ── fallback Item (Unarmed) equipped when no weapon is in hand
├── Pouch Manager    ── pooled projectile ammo
├── IK Manager       ── drives the Action Set IK profiles
└── Rider (optional) ── rein hand-off + the [Riding] Auto Activation

SuperItem  (item GameObject)
├── Item Type          (SuperItemID)
├── Equip Point        (EquipPointID)   + optional Secondary Equip Point for dual wielding
├── Holster            (HolsterID)      + optional Secondary Holster for dual wielding
├── Stats              (optional: Attack, Chamber, Charge, Durability…)
└── Action Sets  ── List<ItemActionSet>
      └── Actions      ── List<ItemAction>       one per input (Attack, Aim, Reload…)
            └── Processors ── ItemProcessor[]    the behaviour of the action
```

The full runtime flow — pick up, equip, action, interruption, unequip — is in [How it works](/animal-controller/super-item/super-item-system/how-it-works.md).

***

## The four concepts

### Item Type, Equip Points and Holsters

An item declares **what it is** (`Item Type`), **where it is held** (`Equip Point`) and **where it is stored** (`Holster`). All three are [ID assets](/animal-controller/super-item/super-item-system/id-assets.md) shared between the item and the character, so an item never references a Transform directly — the character resolves it.

See [Equip Points](/animal-controller/super-item/super-item-system/super-item-manager/equip-points.md) and [Holsters](/animal-controller/super-item/super-item-system/super-item-manager/holsters.md).

### Action Sets

An [Action Set](/animal-controller/super-item/super-item-system/super-item/item-action-sets.md) is a named configuration of the item. A shield alone behaves differently from a shield paired with a sword; a rifle hip-fires differently from a rifle that is aiming; a bow held on foot is not the bow held on horseback. Instead of branching in code, you author one Action Set per situation and let the system swap between them — manually, by Reaction, or automatically through the set's **Auto Activation** conditions.

### Actions

An [Action](/animal-controller/super-item/super-item-system/super-item/item-actions.md) is one thing the item can do in response to one input: Attack, Aim, Reload, Parry, Interact. Actions have a cooldown (`Rate`), an `Update Rate`, a `Duration`, a `Priority`, optional Conditions, and an optional **Master Action** — a dependency that makes an action only available while another one is playing (fire an arrow only while aiming).

### Processors

A Processor is the smallest unit of behaviour. Each one does one job — play a Mode, fire a projectile, apply damage on a trigger hit, play a sound, block another action. An Action executes its processors in order, and each processor decides *when* it runs through its **Execute** flags.

There are 23 built-in processors, and adding your own is a single class.

***

## Where the data lives

This is the part that most often trips up people who used the Weapon Manager, so it is worth stating plainly.

| Data                                                              | Lives on                                                                                                                              | Why                                                                                                       |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Offsets (equip point, holster), Holster Slots, Animator overrides | The [**Item Offsets**](/animal-controller/super-item/super-item-system/super-item-manager/item-offsets.md) **asset** on the character | The same sword sits differently in a human hand and an orc hand. Offsets are per character, not per item. |
| Damage, ammo in the magazine, charge, durability                  | A **`Stats` component** next to the `SuperItem`                                                                                       | Stats give you upgrades, buffs, UI bars and Conditions for free, with no extra fields.                    |
| Ammo reserve and projectile pools                                 | The [**Pouch Manager**](/animal-controller/super-item/super-item-system/pouch-manager.md) on the character                            | Ammo belongs to the character, not to the gun.                                                            |
| Which input fires which action                                    | The **Super Item Manager** `Actions Input` list                                                                                       | One mapping for every item the character can hold.                                                        |

***

## Reference

{% content-ref url="/pages/IdfDwgNu7nbCZ3rj7pXN" %}
[ID Assets](/animal-controller/super-item/super-item-system/id-assets.md)
{% endcontent-ref %}

{% content-ref url="/pages/nwH9nayFh5pXaAX4pbE3" %}
[Conditions](/animal-controller/super-item/super-item-system/conditions.md)
{% endcontent-ref %}

{% content-ref url="/pages/KsEFKeXkKaj0Q7yhwqyx" %}
[Reactions](/animal-controller/super-item/super-item-system/reactions.md)
{% endcontent-ref %}

***

## Demo content

| What            | Where                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------ |
| Test scene      | `Animal Controller/Super Item (Alpha)/Super Item.unity`                                                      |
| Example items   | `Super Item (Alpha)/Super Items/` — Axe, Bow, Pistol, Shield, Sword                                          |
| ID assets       | `Common/Scriptable Assets/IDs/Super Item ID/`                                                                |
| Equip Point IDs | `Common/Scripts/Super Item/Equip Points/` — Right Hand, Left Hand, Head, Left Forearm                        |
| Item Action IDs | `Common/Scripts/Super Item/Item Actions/` — Attack, Attack Light, Attack Heavy, Aim, Parry, Reload, Interact |