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

# Holsters

Last updated AC v1.5.3

## Overview

A **Holster** is where an item rests when it is owned but not in the character's hands — a scabbard on the hip, a quiver on the back, a pistol on the thigh. It pairs a `HolsterID` asset with one or more **Slot** Transforms, and tracks every item currently stored in it.

The Holster ID does double duty: it identifies the storage location, **and** it becomes the ability index of the draw/store Mode, which is how one `Weapon Draw` Mode plays the correct animation for every holster on the body.

Holsters live on the **Holsters** tab of the Super Item Manager.

***

## Requirements

* A `HolsterID` asset. `Left Holster` and `Right Holster` are created by `Reset`.
* At least one **Slot** Transform, parented to the bone the item should rest on.
* Items whose `Holster` — or `Secondary Holster` — field matches the ID.

***

## How it works

### Storing

`Item_Holster(item)` finds the holster whose ID matches the item's `Holster`, then:

1. unequips the item instantly if it was held,
2. resolves a **slot** from the item's authored **Holster Slots** priority list in the Item Offsets asset,
3. parents the item to that slot Transform and applies the holster offset for this **(Item Type + Holster)** pair,
4. disables the item's physics, sets `Is In Holster`, and fires `On Item Holster Enter`.

### Resolving the slot

The authored list wins, in order. The **first** index in it that exists on this holster and is still free is taken — `[0, 2]` sends the first dagger to slot `0` and the second to slot `2`. Only when every authored slot is occupied does the holster scan the rest of its Slots list, wrapping around from the preferred one.

If nothing is free anywhere and the item declares a **Secondary Holster**, the copy falls through to that holster instead, where it gets its own Offset, Slots and Holster Anim entry. That is how a second dagger ends up on the other hip rather than pushing the first one out.

When there is genuinely nowhere left, the **oldest** stored item is evicted, properly dropped (unparented, with its physics restored) and a warning tells you to add more slots.

{% hint style="info" %}
**Swapping is slot-preserving.** An item being drawn out of a holster still hangs in its slot while the Equip animation plays, but its slot already counts as free — so the item holstered in exchange (stored immediately, before the draw finishes) takes that very slot instead of being bumped elsewhere. If the draw is cancelled, the item simply keeps its slot.
{% endhint %}

{% hint style="info" %}
A **prefab** assigned to a holster at edit time is instantiated the first time it is stored, so you can author "the character starts with a spare sword on their back" without putting an instance in the scene.
{% endhint %}

### Drawing

Pressing the holster's `Input` calls `Item_Equip_From_Holster(id)`:

* **The holster has items** — *every* item stored in it is drawn. This matters for dual wielding, where two swords share one holster.
* **The holster is empty** and `Self Store Holster` is on — every equipped item whose `Holster` ID matches is stored instead. The same key toggles draw and store.

`Self Store Holster` is a character-wide switch, in the **Equip Behaviour** group on the Manager's **General** tab.

### The draw animation

The ability index passed to the Equip / Unequip Mode is:

```
ability = Holster Anim ID (or the item's Holster ID when no override exists)
ability *= (side == Left) ? +1 : -1
```

So the Mode transition conditions can distinguish "draw the left-hip sword with the right hand" from "draw the back axe with the left hand" using a single signed integer. The `Holster Anim` override lives per item in the Item Offsets asset, so one holster can play different animations for different items.

***

## Properties

### Holster entry

#### ID

The `HolsterID` asset. Items with a matching `Holster` field are stored here.

#### Item

The item currently stored — the **head** of the holster, meaning the most recently stored one. Assign one at edit time to have the character start with it. A prefab is instantiated on first use.

#### Input

The input name that draws from — or stores into — this holster. Connected on `OnEnable`, disconnected on `OnDisable`. The same field is listed again, next to the Action Inputs, on the Manager's **Inputs** tab.

#### Auto Equip

When an item is added to this holster, equip it to the hand immediately instead of leaving it stored.

#### Capacity

Maximum number of items this holster may store, **independently of how many Slots it has**. A holster with 3 Slots and a Capacity of `2` stores two items. Storing one more drops the **oldest** stored item.

`0` (or less) means no limit — only the Slots cap the amount. Default: `2`.

The inspector warns when Capacity is larger than the number of Slots, because the Slots are then the real limit.

#### Slots

The list of Transforms items are parented to. A holster with three slots can hold three items.

It is drawn as a proper list so the **selected** slot is known: that is the only one the Scene View handles edit, and the one drawn with the bigger gizmo.

Which slots a given item prefers, and in what order, is authored per item in the `SuperItemOffsets` asset (the **Holster Slots** list of the Holster Offsets table), not here.

***

## Events and Reactions

Two of each, and they answer different questions. The **events** report one item moving. The **state Reactions** report what the holster holds once the move is done — which is what a UI icon needs, because a holster that loses one item is not necessarily empty.

### Events

| Event                                   | Fires when                                                           |
| --------------------------------------- | -------------------------------------------------------------------- |
| **On Item Holster Enter** (`SuperItem`) | An item is stored in this holster.                                   |
| **On Item Holster Exit** (`SuperItem`)  | An item leaves this holster — drawn, dropped, or evicted by another. |

### Reactions

| Reaction                    | Fires when                                                                                    | Dynamic Target     |
| --------------------------- | --------------------------------------------------------------------------------------------- | ------------------ |
| **On Holster Item Changed** | The item this holster *shows* changes — one is stored, or one is promoted after another left. | Current Item       |
| **On Holster Empty**        | The **last** item leaves and the holster is now empty.                                        | Super Item Manager |
| **On Holster**              | An item is stored in this holster.                                                            | Holstered Item     |
| **On Unholster**            | An item is removed from this holster.                                                         | Unholstered Item   |

Use the first pair to drive UI (the icon of the item on top, blank when nothing is left) and the second pair for behaviour that belongs to the item that just moved.

The item itself also fires `On Holstered` and `On Unholstered`, sending the character's GameObject.

***

## The Holster ID asset

`HolsterID` is a plain Malbers `IDs` asset: an auto-assigned unique integer and a name. Create one with `Assets ▸ Create ▸ Malbers Animations ▸ ID ▸ Holster ID`.

{% hint style="warning" %}
Duplicated ID **values** break the lookup — the Manager builds a dictionary keyed by ID on `Awake`. When you duplicate a holster asset, make sure the integer is regenerated (right-click ▸ *Get ID*).
{% endhint %}

***

## Debug

With the **Holsters** tab selected, the Scene View draws the assigned item's Display Mesh at each slot, at the exact transform it will have at runtime, with a cube tinted by the item's `Holster Color` (or red when the item's Holster ID does not match). Position, rotation and scale handles write the offset into the asset as you drag — there is no Save button.

The Manager's **Debug** tab prints holster and unholster decisions with the resolved slot index, and in Play Mode lists every holster with its Input and the items it currently stores.

***

## API

```csharp
SItemHolster holster = manager.D_Holsters[holsterID];

holster.HasItem;                 // is anything stored
holster.Item;                    // the most recently stored item (the head)
holster.Count;                   // how many items are stored
holster.Capacity;                // hard limit, 0 = no limit
holster.IsFull();                // Capacity reached
holster.Contains(item);          // is this specific item stored here
holster.HasRoomFor(item);        // is one of the item's authored slots still free
holster.ValidItem(item);         // does the item accept this holster (primary or secondary)
holster.GetUsedSlot(item);       // which slot index it occupies
holster.GetSlotPriority(item);   // the authored slot priority list
holster.GetSlot(index);          // the slot Transform
holster.Holster(item);           // store
holster.Holster(item, out var evicted);  // store, and learn who was pushed out
holster.Clear(item);             // remove one item; the previous one is promoted to head
```

***

## See also