> 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/migrating-from-the-weapon-manager.md).

# Migrating from the Weapon Manager

## Overview

The Super Item System is the successor to the [Weapon Manager](https://malbersanimations.gitbook.io/animal-controller/main-components/weapon-manager). Almost every concept survived; almost every name changed. This page is the translation table.

{% hint style="info" %}
The Weapon Manager is **not removed**. Existing projects keep working. There is no automatic upgrade path — a weapon is rebuilt, not converted — so migrate when you want the new features, not on principle.
{% endhint %}

***

## Should you migrate?

**Stay on the Weapon Manager if** your weapons are conventional (melee swing, shoot, bow) and already working. It is the more mature system and the demo content is richer.

**Move to Super Items if** you need any of these:

* weapons that change behaviour by context (aiming vs hip fire, shield alone vs shield + sword, on foot vs mounted),
* dual wielding,
* per-character offsets for shared weapon prefabs,
* damage, ammo and charge driven by Stats (so upgrades and buffs work with no extra code),
* items that are not weapons — torches, tools, keys, instruments,
* custom weapon behaviour without subclassing `MWeapon`.

***

## Component mapping

| Weapon Manager                             | Super Item System                                                                  |
| ------------------------------------------ | ---------------------------------------------------------------------------------- |
| `MWeaponManager` on the character          | `SuperItemManager` on the character                                                |
| `MWeapon` on the weapon                    | `SuperItem` on the item                                                            |
| `MMelee`                                   | A `SuperItem` with a **Damager** processor                                         |
| `MShootable`                               | A `SuperItem` with a **Projectile - Fire** processor                               |
| `MBow`                                     | A `SuperItem` with **Charge** + **Projectile - Fire** processors                   |
| `Weapon Type`                              | `Item Type` (`SuperItemID`)                                                        |
| `Holster ID`                               | `Holster` (`HolsterID`) — same asset type, same role                               |
| Weapon Hand Equip Points (Left/Right)      | The **Equip Points** list, keyed by `EquipPointID`                                 |
| Weapon `Right/Left Hand Offset`            | An entry in the character's `SuperItemOffsets` asset                               |
| Weapon `Holster Offset` and `Holster Slot` | A Holster entry in the same asset (the Slot is a **priority list** now)            |
| `Ignore Draw` / `Ignore Store`             | `Equip Duration` = `0`, or an empty `Equip Mode`                                   |
| `Store After`                              | `Auto Store` on the Equip Point                                                    |
| `Exit on States` / `Exit on Modes`         | `No Items In State` / `No Items In Mode` on the Manager                            |
| `Disable Modes`                            | Handled per Action Set, or with the **Block Actions** processor                    |
| Attack inputs on the Manager               | The `Actions Input` list, mapping `ItemActionID` → input name                      |
| Weapon Actions (int)                       | Named **Actions** inside an **Action Set**                                         |
| Damage authored on `MMelee`                | A **Stat Modifier** on the Damager processor, sourced from an `[Attack]` Stat      |
| Ammo on the weapon                         | A **Chamber** Stat on the item + the `PouchManager` reserve                        |
| `Combo Manager`                            | Same component, reached through the **Combo** processor                            |
| `CheckReinHandsEquip` (rein hands)         | Automatic — the Manager recomputes it, plus `Free Hands` on the Set and the Action |
| `CurrentIKProfile`                         | `ActionSet.CurrentIKProfile`, resolved through the IK Manager's Remap              |

***

## The four things that genuinely changed

### 1. Offsets moved off the weapon

On `MWeapon` the hand and holster offsets lived on the weapon prefab. That works until two characters with different proportions share a sword.

In the Super Item System every offset lives in a single `SuperItemOffsets` ScriptableObject on the **character**, keyed by `(Item Type + Equip Point)` and `(Item Type + Holster)`. One sword prefab, one offset entry per character that uses it.

### 2. Damage is a Stat

`MMelee` carried a `StatModifier` with a hardcoded value. A Super Item carries a `Stats` component with an `[Attack]` Stat, and the **Damager** processor reads it through a **Source expression** — which can also multiply by a `Charge`, add a percentage from a `Rage` Stat, or clamp to a floor. The character can contribute too: a second Damager processor whose Source Stats points at the character stacks additively on the same hit.

The payoff is that weapon upgrades, temporary buffs, durability-scaled damage and UI all work through the existing Stat system — `StatReaction`, `ModifyStat`, the `[Stats]` Conditions — with no new fields and no new code.

### 3. Behaviour is composed, not subclassed

A new weapon type used to mean a new class deriving from `MWeapon`. Now it means picking processors from a dropdown. If you genuinely need new behaviour, you write one `ItemProcessor` subclass and it becomes available to every item in the project.

### 4. Context is an Action Set, not a branch

The Weapon Manager expressed context with weapon actions and animator state. Super Items express it with Action Sets that swap themselves based on Conditions. A shield's "alone" and "with sword" behaviours are two sets, not two code paths — and so are a bow's on-foot and mounted behaviours.

***

## Porting a melee weapon, step by step

1. Duplicate the weapon prefab. Remove `MWeapon` / `MMelee`, add `SuperItem`.
2. Assign `Item Type`, `Equip Point` and `Holster`. Reuse the old `Holster ID` asset directly.
3. Add a `Stats` component with an `[Attack]` Stat. Set its Min/Max to the old damage values.
4. In the item's **Sets & Actions** tab, create an Action Set named `Default` with an `Attack` Action.
5. On that Action add a **Play Mode** processor pointing at the old attack Mode.
6. Add a **Damager / Do Damage (Attack Stat)** processor. Its defaults already do what `MMelee` did: Target `Health`, Modify `Substract Value`, Value From `Use Sources` with one term reading `Attack`. Assign the weapon's `TriggerProxy` to the Action's `Trigger` field.
7. Press **Equip in Char** on the item, pick the character, and drag the Scene View handles until it sits in the hand. The offset is written to the character's `SuperItemOffsets` asset as you drag — there is no Save button.
8. Repeat with **Holster in Char**.

***

## Things that have no equivalent yet

* There is no `Use External` mode. Items are always parented to an Equip Point.
* The `Advanced` tab that injected an upper-body layer into third-party Animator Controllers has no counterpart — the arm layers are driven purely through the `Left/Right Item Type` parameters.