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

# Item Actions

## Overview

An **Item Action** is one thing an item can do in response to one input: Attack, Aim, Reload, Parry, Interact. It lives inside an Action Set and owns an ordered array of Item Processors that provide the actual behaviour.

An Action by itself does nothing. It is the scheduler: it decides *whether* the action may run (rate, priority, conditions, dependencies) and *when* the processors fire. The processors decide *what* happens.

***

## Requirements

* An `ItemActionID` asset assigned to **Action ID**.
* That same ID present in the character's Super Item Manager **Actions Input** list, if the action should respond to input.
* At least one Processor, otherwise the action starts and ends with no effect.
* A `TriggerProxy` assigned to **Trigger**, for any Damager or Surface Hit processor.

The provided Action IDs are `Attack`, `Attack Light`, `Attack Heavy`, `Aim`, `Parry`, `Reload` and `Interact`; the Manager's defaults map `Action1`–`Action4`, `Reload` and `Interact`.

***

## How it works

### Activation

Pressing the mapped input calls the action. Before anything runs it must pass, in order:

1. **Just Activate** — an action cannot restart on the frame it started.
2. **Primary Hand Only** — a dual-wield follower copy skips the action.
3. **Interrupt Self** — if off and the action is already playing, nothing happens.
4. **Rate** — the cooldown since the last activation.
5. **PreRequisites** — item enabled, action and set Active, item equipped, the ID not in `Blocked Actions`, no higher-priority Main Action playing, and (for a Secondary) its Master is the playing Main Action.
6. **Conditions** — `Conditions On Owner`, `Conditions On Target`, and the set's `Set Conditions`.

{% hint style="info" %}
The cooldown is stamped **after** the vetoes. A press that was rejected — blocked action, failed condition, item not equipped — does not burn the `Rate`, so it never pushes the next valid press a full cooldown away.
{% endhint %}

### Main and Slave

An item has at most one **Main Action** playing. Starting a new Main Action force-exits the previous one.

An action with a **Master Action** is a **Secondary** (Slave) action: it can only start while its Master is the playing Main Action, and while it plays it puts the Master "on hold" so releasing the Master's input does not end it. Fire-while-aiming is exactly this: `Aim` is the Master, `Fire` is the Secondary.

### Ending

The action is released when:

* the input is released (only when `Duration` ≤ 0),
* the `Duration` elapses,
* a PreRequisite or Condition stops passing.

Release runs the `On Action Released` processors, then exits the action if `Stop Action On Release` is set. Some processors change that flag for you — **Play Mode** clears it for a Toggle/Forever ability, and **Combo** always clears it.

***

## Properties

#### Name

The action's name. Used by the Super Item Processor By Animation to address it from an animation.

#### Active

Disable to switch the action off without deleting it.

#### Action ID

The `ItemActionID` that connects this action to an input through the Manager's **Actions Input** list. It is also the ID other items block through the **Block Actions** processor.

#### Activation

| Value       | Behaviour                                         |
| ----------- | ------------------------------------------------- |
| **Pressed** | Starts on press, releases on release.             |
| **Toggle**  | Each press flips the state. Releases are ignored. |

#### Rate

Cooldown in seconds between two **activations**. The action cannot start again until it elapses. `0` disables the check.

It does **not** throttle the processors while the action is playing — that is Update Rate.

#### Update Rate

Repeat rate for the `On Action Updated` processors while the action is playing.

| Value | Behaviour                                                                                              |
| ----- | ------------------------------------------------------------------------------------------------------ |
| `0`   | Every frame. Required by time-based processors — **Charge** and **Wait** both need the real delta.     |
| `> 0` | Automatic repetition. `0.1` on a Fire processor flagged `On Action Updated` gives 10 shots per second. |

{% hint style="warning" %}
`Rate` and `Update Rate` used to be one field, and the cooldown gated the whole per-frame update. That meant a Charge processor on an Action with a `1` second Rate only charged once per second. They are two separate things now — if a charge or a wait behaves oddly, check that **Update Rate** is `0`.
{% endhint %}

#### Duration

How long the action runs. `0` or less means "until the input is released".

#### Priority

Higher-priority Main Actions cannot be interrupted by lower-priority ones. A Parry with priority `2` cannot be cancelled by an Attack with priority `0`.

#### Interrupt Self

Whether pressing the input again while the action is playing restarts it.

#### Restart On Conditions

When the action is ended by its **Conditions** — its own, its Target's, or the set's — while the input is **still held**, it stays armed and starts again by itself the moment the conditions pass again. The player does not have to release and press a second time.

Only a conditions failure arms it. A `Duration` that elapsed, an interruption, or a released input do not.

On a **Secondary** action it also covers its Master: the Secondary goes down with the Master and, if its own input is still pressed, comes back as soon as the Master is playing again — which is what keeps a `Charge` on a Fire action alive across an Aim that was cut short.

{% hint style="info" %}
The case this exists for: aiming a bow on horseback. The aim angle leaves the range allowed by an `[Aim Angle]` condition, the Aim action ends, and it resumes on its own the instant the angle is valid again.
{% endhint %}

#### Primary Hand Only

When dual wielding, only run this action on the item held on its **primary** equip point. The off-hand fall-through copy skips it, which is what stops two identical weapons from firing the same action twice.

#### Free Hands \[Action]

Hands this action **frees from the rein** while it is playing — aiming a bow, bracing a rifle, a two-handed swing.

The hand of the Equip Point is always taken, and so are the hands the Action Set declares; this only **adds** to them, and it is released as soon as the action ends. Leave it empty when the action does not need an extra hand. It only matters while the character is mounted.

#### Master Action

Selects another Action in the same set as this action's prerequisite. Picking one makes this a Secondary action.

{% hint style="warning" %}
An Action cannot be its own Master, and a stale index left behind after deleting Actions is ignored with a warning. Re-pick the Master after reordering a set.
{% endhint %}

#### Trigger

The `TriggerProxy` on the item this action's trigger-based processors listen to. Required by every **Damager** processor.

***

## Conditions

#### Conditions On Owner

Evaluated against the **character** holding the item. Failing them fires `On Action Failed On Owner`.

#### Conditions On Target

Evaluated against the item's **Target**. An action with target conditions and no Target always fails.

The Action Set's `Set Conditions` are checked as well, so a condition shared by every action in a set belongs there instead.

***

## Reactions

| Reaction                       | Fires when                                     |
| ------------------------------ | ---------------------------------------------- |
| **On Action Pressed**          | The input went down (before the checks).       |
| **On Action Start**            | The action passed every check and started.     |
| **On Action Released**         | The action was released.                       |
| **On Action Exit**             | The action ended.                              |
| **On Action Failed On Owner**  | The Owner conditions rejected the activation.  |
| **On Action Failed On Target** | The Target conditions rejected the activation. |

`On Action Failed` is the hook for "click on an empty gun" feedback — wire it to a dry-fire sound. It fires **once** per activation, so holding the input down does not spam it.

***

## Editor

The Action inspector is tabbed: **Processors**, **Conditions**, **Reactions**, **IK** and **\[Set] Auto**. Each tab shows a count so you can see at a glance where a configuration lives.

{% hint style="info" %}
The selected tab is stored on the **item**, not on the Action, so browsing through Actions keeps you on the same tab.
{% endhint %}

**Copy Action** / **Paste** move a fully configured Action between sets and items.

***

## Debug

Enable **Debug** on an Action to trace its start, exit, interruption and condition failures in the console, and to draw its processors' gizmos in the Scene View.

The Conditions gizmos and the processors' *selected* gizmos additionally require the item to be **anywhere in the current selection** — the item root, any of its children, or the character holding it. Clicking the item's mesh child is enough; it no longer has to be the exact object selected.