> 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 Last updated AC v1.5.3 ## 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, * routes the Action inputs of **holstered** items too, so **Fast Weapons** can draw and attack in one press, * can send every picked-up item straight to the hands for the whole character (**Auto Equip**), * 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, * puts every item away and refuses every item operation while it is **Locked** (carrying a box, climbing a rope…), * stores an item that has been idle for too long (**Auto Holster**), * keeps a **Default Item** in hand when nothing else is, * gates every Item Action behind one set of **Global Action Conditions**, * forwards the Animator's damager activation calls to the held items' trigger proxies. *** ## Validation report Above the tabs the inspector draws a live report of the current setup, rebuilt whenever an edit is applied: * a **red box** lists what will break at runtime — missing references, a bad hierarchy, an Equip Point with no Transform, * a **yellow box** lists what works but has a feature silently off — a missing Animator parameter, a Holster with no Input, * the **Refresh** button re-runs the check after the problem was fixed somewhere else (Animator, Input asset, Items). When nothing is wrong the report only appears after an explicit **Refresh**, so a clean character costs no inspector space. *** ## Properties The inspector is split across two toolbars: **General / Equip Points / Holsters** and **References / Inputs / Debug**. ### General #### Equip Behaviour The six Manager-wide switches that decide how items come out and go back in. | Field | Behaviour | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Auto Equip** | Global auto equip for every pick this character makes (Interactor, AI Pick Task, Pick reactions). **On**: every picked item goes straight to the hands, whatever the item's own `Auto Equip` says. **Off** (default): the item's own `Auto Equip` decides, hands or holster. Picks from the world only — the starting items authored on the Equip Points and Holsters are not affected. | | **Use Fast Weapons** | Assassin's Creed style instant draw. Pressing the input of a **holstered** item's `Fast Equip` Action draws it with no Equip animation and starts that Action. Off by default. | | **Self Store Holster** | Pressing the holster input of an item that is **already in the hands** puts it away. Off: the press is ignored, and the item can only be put away by drawing another one. | | **Fast Equip Back** | How the items held by a **No Items** State / Stance / Mode — or by a **Lock** — come back. Off: the `Equip Mode` animation plays. On: the items reappear in the hands instantly. Putting them away is always instant. | | **Auto Holster Time** | Seconds an equipped item may sit doing **nothing** before it is stored back with the normal Store animation. Zero or less disables it for every item. Default `3`. | | **Cross Item Priority** | Compare Action `Priority` **across** the equipped items. When two items answer the same Action ID, only the highest Priority one starts — a Shield `Parry` with Priority 1 wins over a Sword `Attack` with Priority 0. Equal Priorities both start, so dual wielding keeps swinging both hands on one press. The winner also holds the input while it is playing. Off: every item starts its own Action and Priority is compared only inside each item. On by default. | {% hint style="info" %} **Cross Item Priority only compares Actions that share an Action ID.** It never blocks an Action bound to a different input, and it never interrupts an Action that is already playing — it only decides which one *starts*. To suppress whole Actions across items, use the **Block Action** processor. {% endhint %} {% hint style="info" %} **Auto Equip is a one-way override.** On, it forces every pick into the hands; off, it steps aside and the per-item `Auto Equip` flag is the only say, exactly as before. It is a Bool Reference, so a Bool Var can flip a whole squad at once. A Pick reaction or AI Task set to **Force Equip** / **Force Holster** still wins over both. {% endhint %} #### Lock The settings of the [Lock](#lock) feature: the character needs its hands for something else, so every equipped item goes away and the Manager freezes until it is unlocked. | Field | Behaviour | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Lock Mode** | What happens to the equipped items when the Manager is locked. **Holster** (default): stored instantly in their holsters, with no Store animation; an item with no holster is hidden in place instead. **Hide**: deactivated in place, still on their Equip Point; their holsters are not touched. | | **On Locked** | `UnityEvent`. Invoked with `true` right after the Manager is locked (the items are already away) and with `false` right after it is unlocked (before the items are drawn back). | \[Insert Image - the Lock group on the General tab: Lock Mode dropdown and the On Locked event] #### Action Conditions A single `Conditions2` list, evaluated **on the Manager** — the character is the target — that every Item Action of every equipped item must pass **to start**. It is checked before the Action's own `[Owner]`/`[Target]` Conditions and before the Set Conditions, so one entry here vetoes the whole character: `[Mode is NOT Playing: Dodge]` stops every swing and every shot while the character dodges. {% hint style="info" %} **Activation only.** An Action that is already playing — a held Aim, for example — is never cut by these Conditions. It keeps playing through the block. Leave the list empty to skip the check entirely. {% endhint %} #### 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. The same layer is copied to every `IMLayer` child that lives **outside** a Super Item (the unarmed Attack Triggers), so fists hit exactly what the items hit. #### 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. #### 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. #### 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. #### 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. How they come back is set by **Fast Equip Back**, on the General tab. {% 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 %} #### Equip Points list One row per place an item can be held. Selecting a row exposes its settings — **Store On Holster** and the **On Equip / On Unequip** Reactions — plus an inline inspector of the equipped item. {% content-ref url="/pages/UCDD7PVfglRFlxTQDgrH" %} [Equip Points](/animal-controller/super-item/super-item-system/super-item-manager/equip-points.md) {% endcontent-ref %} *** ### 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. Selecting a holster row exposes its **Input**, **Auto Equip**, **Capacity**, its **Slots** list and its four Reactions. {% content-ref url="/pages/63ATgjppCEfn9wi0K31x" %} [Holsters](/animal-controller/super-item/super-item-system/super-item-manager/holsters.md) {% endcontent-ref %} *** ### 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. {% hint style="info" %} The rig-specific **IK Set Remap** is set on the **IK Manager** itself, not here. A profile with no row on that Remap still runs, but with the offsets of the rig it was authored on. {% endhint %} #### 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 Every holster's own `Input`, gathered in one list next to the Action Inputs. The Holster ID column is disabled here — it is edited on the Holsters tab — so this list is only about which key draws from which holster. *** ## Fast Weapons **Fast Weapons** is the Assassin's Creed draw: one press both takes the weapon out and attacks with it. A holstered item has no input subscriptions of its own — those are only connected on equip — so the Manager keeps **one listener per `Actions Input` row** and routes the press itself. On a press it draws a candidate only when **all** of these hold: * `Use Fast Weapons` is on, * no **No Items** State, Stance or Mode is blocking items, and the Manager is not **Locked**, * **no Action of any equipped item is playing** (so a held `Aim → Fire` is never interrupted), * no animated draw or store is in flight, * the **Global Action Conditions** pass — otherwise the Action would be vetoed right after the draw, so the draw is skipped too. The candidate is the **holstered** item whose Active Set has the highest `Fast Equip` value for that Action ID. It is equipped with no Equip animation, and its `Fast Equip` Action is started immediately. #### Arbitration with equipped items An equipped Action with `Valid On Fast Weapons` **on** (the default) owns its input as usual — nothing is drawn. Set it **off** and that Action yields its input to a fast draw whenever a holstered candidate exists. Both sides apply the same rule, so the result does not depend on which listener the input source happens to fire first. {% hint style="info" %} `Fast Equip` and `Valid On Fast Weapons` are authored per **Item Action**, on the item — not here. `Fast Equip = 0` means "this Action is not a fast draw". {% endhint %} *** ## Auto Holster An equipped item that sits doing nothing for `Auto Holster Time` seconds is put away with the **normal Store animation**. "Doing nothing" is decided by the item alone: no Action of its Active Set is playing (a held Aim counts as playing) and no equip/store animation is in flight. The character's own Modes no longer reset the timer, so attacking with one hand no longer keeps the **other** hand's item out. The store waits for a clean frame: while a **No Items** block or a **Lock** owns the item, or while the character is playing a Mode, the timer stays elapsed and fires on the first free frame instead. Set `Auto Holster Time` to `0` (or less) to switch the feature off for the whole character. *** ## Lock **Lock** is for the moments the character needs its hands for something that is not an item: carrying a box, pushing a cart, climbing a rope, holding a torch in a cutscene. Locking the Manager does two things at once: * **Every equipped item is put away instantly** — no Store animation — and remembered. **Lock Mode** decides how: **Holster** sends each item to its holster (an item with no holster is hidden in place), **Hide** deactivates each item where it is, still on its Equip Point, without touching the holsters. The Default Item (fists) is suppressed too. * **Every item operation is refused** until Unlock: Item Actions, equip, draw from a holster (the holster inputs included), holster, unholster, drop, pick-up from the Interactor or the AI, and the Fast Weapons draw. With `Debug Log` on, every refused call is printed in red with the `[Locked]` reason. **Unlock** draws the remembered items back on the next frame, through the same restore path the **No Items** block uses: with the Equip animation, or instantly when **Fast Equip Back** is on. `On Locked` fires `true` on lock and `false` on unlock. The two blocks coexist. Lock the character while a **No Items** State is active and nothing changes — the items are already away. Whichever of the two ends **last** is the one that draws the items back, so a locked character never gets its weapons back mid-swim. {% hint style="info" %} **An equip request made while Locked is refused, not queued.** Only the items that were in the hands at lock time come back on Unlock. A pick-up is refused as well, so a box carrier walking over a sword leaves it on the ground. {% endhint %} {% hint style="info" %} Locking the Manager **before it initialised** (a Lock reaction on `Start`, or re-enabling a locked character) still places the starting items: they are holstered or hidden and remembered, instead of being refused and lost. {% endhint %} #### Example — carrying a box On the box's `Interactable`: an `On Interact` reaction **\[Manager] Global** → `Lock`, Bool Value `on`. On the drop event of the carry logic: the same reaction with Bool Value `off`. Between the two, the character walks around with empty hands and every attack input is ignored; the weapons come back the moment the box lands. *** ## Events The Manager has one UnityEvent of its own, **On Locked** (`bool`), fired by the [Lock](#lock) feature. Everything else that can be listened to lives one level down, where the dynamic target is meaningful: | Where | What | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | **Super Item** | `On Equip`, `On Unequip`, `On Holstered`, `On Focused`… — the item's own life cycle. | | **Equip Point** | `On Equip` / `On Unequip` Reactions, dynamic target = the item that landed on or left the point. | | **Holster** | `On Item Holster Enter/Exit` events, and the `On Holster`, `On Unholster`, `On Holster Item Changed`, `On Holster Empty` Reactions. | *** ## 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 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.Item_Pick(SuperItem item); // global Auto Equip (ON) or the item's own flag decides hands vs holster; false when refused manager.Item_Pick(SuperItem item, bool equip); // force the outcome, ignoring every Auto Equip setting manager.Pick_and_Equip(SuperItem item); manager.Pick_and_Holster(SuperItem item); manager.AutoEquip = true; // the global Auto Equip: every pick goes to the hands bool toHands = manager.ResolveAutoEquip(item); // what a pick of this item would do right now // Drop manager.Item_Drop(SuperItem item); manager.Item_Drop(EquipPointID equipPoint); manager.Item_Drop(HolsterID holster); manager.Item_Release(SuperItem item); // Lock: put every equipped item away and refuse every item operation until Unlock manager.Lock(bool value); // true = Lock with the inspector Lock Mode, false = Unlock manager.Lock(); // Lock with the inspector Lock Mode manager.Lock(LockItemsMode mode); // Lock with an explicit mode (Holster / Hide) manager.Lock_Holster(); // UnityEvent friendly: Lock, items to their holsters manager.Lock_Hide(); // UnityEvent friendly: Lock, items hidden in place manager.Unlock(); // draw the remembered items back (next frame) manager.Locked = true; // the property routes to Lock(bool) // 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); ``` ### Driving Actions from code (AI, cutscenes, UI) ```csharp // Press / release an Action by ID. Optionally restrict it to one Item ID. // Action_Press falls back to a [Fast Weapons] draw when nothing equipped answers the ID, // and returns false while the Manager is Locked. manager.Action_Press(ItemActionID actionID, SuperItemID itemID = null); manager.Action_Release(ItemActionID actionID, SuperItemID itemID = null); // Force-stop. A null ID interrupts every Action of every equipped Item. manager.Action_Interrupt(ItemActionID actionID = null); // Find the equipped Item + Action that answers an ID manager.TryGet_Action(actionID, out SuperItem item, out ItemAction action, SuperItemID itemID = null); // Release a No Items hold that was never closed (a Mode interrupted without its Mode End). // A Lock is not cleared by it: the items wait for Unlock. manager.Items_ReleaseHold(); // Re-check whether the Default Item should be in hand manager.RefreshDefaultItem(); ``` ### Queries ```csharp bool blocked = manager.NoItemsBlocked; // a State, Stance or Mode forbids items in hand bool locked = manager.Locked; // the Manager is Locked (items away, every operation refused) bool noHands = manager.HandsBlocked; // NoItemsBlocked OR Locked: nothing can be in the hands right now bool drawing = manager.IsEquipping; // an animated draw or store is in flight bool canAct = manager.CheckActionConditions(); // the Global Action Conditions pass bool cross = manager.CrossItemPriority; // compare Action Priority across the equipped items (runtime toggle) bool unarmed = manager.DefaultItemActive; manager.IsItemEquipped(SuperItemID id); manager.IsItemHolstered(SuperItemID id); manager.OwnsItem(SuperItemID id); // equipped OR holstered manager.Get_ItemEquipped(SuperItemID id); manager.Get_ItemHolstered(SuperItemID id); manager.IsItemEquippedWithTag(List tags, bool all = false); manager.IsAnyItemHolstered(); manager.IsHolsterOccupied(HolsterID id); manager.HasFreeEquipPoint(); manager.HasFreeHolster(); manager.IsActionPlaying(SuperItemID itemID, ItemActionID actionID); manager.IsAnyActionPlaying(); manager.FocusedItems; // free Items inside the Interactor trigger manager.D_Holsters[holsterID]; // runtime holster lookup manager.D_EquipPoints[equipPointID]; // runtime equip point lookup ``` ### 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 The **Debug** tab is both the log switch and a live window into the Manager. #### Debug Log Prints equip, unequip, holster, unholster, drop, auto-holster and lock decisions 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. #### Test Actions One row per `Actions Input` entry, with the resolved Action ID shown in a disabled field. **\[Play]** taps the input once; **\[Hold]** latches it down until **\[Release]**. A row is disabled when nothing currently answers that ID. #### Runtime state (Play Mode only) Four live sections: the **Manager** (blocks, Locked, Auto Store window, Default Item, plus a live **Lock / Unlock** button next to the Lock Mode so the feature can be tried without wiring anything), the **Equip Points** (occupant and its idle timer against the Auto Store window), the **Holsters** (input, stored items, slots), and every **tracked item** with its Active Set, playing Actions and Main/Slave Action. #### 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 the **selected** 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.