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

# Item Processors

## Overview

A **Processor** is the smallest unit of behaviour in the Super Item System. Each one does exactly one job — play a Mode, fire a projectile, apply damage, play a sound, block another item's action — and an [Item Action](/animal-controller/super-item/super-item-system/super-item/item-actions.md) runs an ordered array of them.

This is the extension point. Everything a weapon does is a stack of processors, and a behaviour nobody anticipated is one new class rather than a fork of the framework.

Processors are serialised inline with `[SerializeReference]`, so they are **not** assets. There is no `CreateAssetMenu`, nothing to save, and nothing to reference — you pick a type from a dropdown in the Action's **Processors** tab and configure it there.

***

## Requirements

An Action to hold them. Individual processors have their own requirements — a Trigger Proxy, a Pouch Manager, a Stat — listed on their pages.

***

## How it works

### The processor row

Every processor, whatever its type, has the same controls in its header row:

| Control                      | Meaning                                                                                            |
| ---------------------------- | -------------------------------------------------------------------------------------------------- |
| **Active** (checkbox)        | A disabled processor never executes and is skipped by the Prev Completed / Prev Interrupted chain. |
| **Delay** (clock field)      | Seconds to wait before this processor executes. Applies to every execution path.                   |
| **Execute** (flags dropdown) | *When* this processor runs. See below.                                                             |
| **Help** (?)                 | Opens this documentation page for that processor type.                                             |
| **Trash**                    | Remove the processor.                                                                              |

The rest of the row is the processor's **dynamic name** — a live summary of its configuration, so a collapsed list still tells you what the Action does.

{% hint style="info" %}
The Help button reads the `[HelpURL]` attribute off the processor class, so a **custom** processor gets a working Help button just by carrying the attribute — Unity itself ignores `[HelpURL]` on non-Object types, the drawer handles it.
{% endhint %}

### Execute flags

`Execute` is a flags field: combine as many as you need.

| Flag                    | Runs when                                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------------------- |
| **On Action Start**     | The Action passed its checks and started.                                                         |
| **On Action Updated**   | While the Action plays, at the Action's **Update Rate** (`0` = every frame). Receives delta time. |
| **On Action Released**  | The Action was released (input up, duration elapsed, condition failed).                           |
| **On Trigger Enter**    | The Action's Trigger Proxy entered a collider.                                                    |
| **On Trigger Exit**     | The Action's Trigger Proxy left a collider.                                                       |
| **On Animation**        | An animation reached the frame that calls back into the item.                                     |
| **On Prev Completed**   | A processor **above** this one finished successfully.                                             |
| **On Prev Interrupted** | A processor **above** this one was cut short.                                                     |

### Chaining

The last two flags are what let an Action express a sequence rather than a burst.

When a processor finishes its job it calls `ProcessorCompleted`, which executes **every following processor** flagged `On Prev Completed`. When it is cut short it calls `ProcessorInterrupted`, triggering `On Prev Interrupted` instead.

A charged bow is the canonical example: a [Charge](/animal-controller/super-item/super-item-system/item-processors/charge.md) processor fills over time, and a [Projectile - Fire](/animal-controller/super-item/super-item-system/item-processors/projectile-fire.md) processor below it is flagged `On Action Released` — or `On Prev Completed`, if you only want the shot at full draw.

{% hint style="info" %}
**Order matters.** Processors execute top to bottom, and the chain only ever signals *downward*. Put the thing that decides above the thing that acts.
{% endhint %}

### Interruption

When an Action is forcefully interrupted — another Action takes over, the Action Set is swapped, the item is unequipped or disabled — every **pending Delay is cancelled**, so a delayed Execute can never fire after the Action it belonged to has ended. A normal exit (input released, mode finished by itself) does not cancel it.

### Validation

Every processor implements a `Validation` method, surfaced by the **Validate** button in the item inspector. It reports missing references, impossible ranges and conflicting settings before you enter Play Mode. The specific checks are listed on each processor's page.

***

## The catalogue

### Animation and flow

| Processor                                                                                 | What it does                                                  |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [Play Mode](/animal-controller/super-item/super-item-system/item-processors/play-mode.md) | Activates a Mode on the character. The most common processor. |
| [Combo](/animal-controller/super-item/super-item-system/item-processors/combo.md)         | Advances a Combo Manager branch so presses chain.             |
| [Charge](/animal-controller/super-item/super-item-system/item-processors/charge.md)       | Builds a charge value while the input is held.                |
| [Wait](/animal-controller/super-item/super-item-system/item-processors/wait.md)           | Waits, then signals the processors below.                     |

### Damage

All five require a Trigger Proxy on the Action and default to `On Trigger Enter`. The last four *modify* a hit; stack them above the one that deals it.

| Processor                                                                                                                   | What it does                        |
| --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| [Do Damage (Attack Stat)](/animal-controller/super-item/super-item-system/item-processors/damager-do-damage-attack-stat.md) | Applies a Stat-driven damage value. |
| [Critical](/animal-controller/super-item/super-item-system/item-processors/damager-critical.md)                             | Rolls a critical hit.               |
| [Can Miss](/animal-controller/super-item/super-item-system/item-processors/damager-can-miss.md)                             | Rolls a miss.                       |
| [Add Element](/animal-controller/super-item/super-item-system/item-processors/damager-add-element.md)                       | Tags the hit with a damage element. |
| [Override Hit Reaction](/animal-controller/super-item/super-item-system/item-processors/damager-override-hit-reaction.md)   | Replaces the target's hit reaction. |

### Projectiles

| Processor                                                                                                   | What it does                                                    |
| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| [Projectile - Fire](/animal-controller/super-item/super-item-system/item-processors/projectile-fire.md)     | Fires pooled projectiles, with spread, arcs and charge scaling. |
| [Projectile - Reload](/animal-controller/super-item/super-item-system/item-processors/projectile-reload.md) | Refills the Chamber Stat from the Pouch reserve.                |

### Item control

| Processor                                                                                                     | What it does                                                           |
| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [Item - Block Actions](/animal-controller/super-item/super-item-system/item-processors/item-block-actions.md) | Blocks an Action ID on the character's other items.                    |
| [Item - Holster Items](/animal-controller/super-item/super-item-system/item-processors/item-holster-items.md) | Sends the character's items to their holsters.                         |
| [Animal Strafe](/animal-controller/super-item/super-item-system/item-processors/animal-strafe.md)             | Turns the character's Strafe on or off.                                |
| [Damageable](/animal-controller/super-item/super-item-system/item-processors/damageable.md)                   | Swaps the character's Damageable profile — this is how blocking works. |
| [Align To Target](/animal-controller/super-item/super-item-system/item-processors/align-to-target.md)         | Rotates the character and target to face each other.                   |

### Interaction

| Processor                                                                                                           | What it does                                        |
| ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| [Owner Interactor](/animal-controller/super-item/super-item-system/item-processors/interaction-owner-interactor.md) | Fires the character's Interactor.                   |
| [Trigger Interact](/animal-controller/super-item/super-item-system/item-processors/interaction-trigger-interact.md) | Interacts with whatever the item's trigger touches. |

### Feedback and escape hatches

| Processor                                                                                                                       | What it does                                          |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [Reactions List](/animal-controller/super-item/super-item-system/item-processors/reactions-list.md)                             | Runs a `Reaction2` on the owner or the target.        |
| [Surface Hit](/animal-controller/super-item/super-item-system/item-processors/surface-hit.md)                                   | Spawns surface-specific impact effects.               |
| [Sound - Audio](/animal-controller/super-item/super-item-system/item-processors/sound-audio.md)                                 | Plays an audio clip with randomised volume and pitch. |
| [Unity - Unity Event](/animal-controller/super-item/super-item-system/item-processors/unity-unity-event.md)                     | Invokes a UnityEvent.                                 |
| [Unity - GameObject Set Active](/animal-controller/super-item/super-item-system/item-processors/unity-gameobject-set-active.md) | Enables and disables GameObjects.                     |

***

## Writing your own

A processor is one serializable class. Drop it anywhere in the `MalbersAnimations` assembly and it appears in the dropdown.

```csharp
using UnityEngine;

namespace MalbersAnimations.Items
{
    [System.Serializable, AddTypeMenu("My Category/My Processor")]
    [HelpURL("https://your-docs/my-processor")]   // gives the row a working Help button
    public class MyProcessor : ItemProcessor
    {
        [Tooltip("Shown in the Inspector")]
        public float amount = 1f;

        // The live summary shown in the collapsed processor row
        public override string DynamicName => $"My Processor [{amount}]";

        // Which Execute flag is preselected when the processor is created
        public override ExecuteProcessor InitialExecute => ExecuteProcessor.OnActionStart;

        public override void Execute(SuperItem item, ItemActionSet set, ItemAction action)
        {
            // main logic
        }

        // Reported by the Validate button. Empty string means "all good".
        public override string Validation(SuperItem item, ItemActionSet set, ItemAction action)
            => amount <= 0 ? "Amount must be greater than zero." : string.Empty;
    }
}
```

### Lifecycle hooks worth overriding

| Hook                                                       | Called when                                                                                                                                                                  |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Awake`                                                    | The item wakes. Cache anything that never changes.                                                                                                                           |
| `ItemEquipped` / `ItemUnequipped`                          | The item is equipped or put away. Resolve and release character references here.                                                                                             |
| `SetEnter` / `SetExit`                                     | The owning Action Set became active or was swapped out.                                                                                                                      |
| `ActionStart` / `ActionReleased` / `ActionExit`            | The Action's lifecycle, independent of the Execute flags.                                                                                                                    |
| `ActionFailed`                                             | The Action's Conditions rejected the activation. Fires once per activation.                                                                                                  |
| `Execute(item, set, action)`                               | The processor's Execute flag fired.                                                                                                                                          |
| `Execute(item, set, action, delta)`                        | Same, with delta time — used by `On Action Updated`.                                                                                                                         |
| `EnterTrigger` / `ExitTrigger`                             | The Action's Trigger Proxy touched something.                                                                                                                                |
| `ModeStart` / `ModeEnd` / `StateChanged` / `StanceChanged` | The character's Animal Controller changed.                                                                                                                                   |
| `OnDrawGizmos`                                             | Scene View drawing, while the owning Action has debug enabled.                                                                                                               |
| `OnDrawGizmosSelected`                                     | Same, plus the item being **anywhere in the selection** — the root, any child of it, or the character holding it.                                                            |
| `Reset`                                                    | Right after creation — set your defaults.                                                                                                                                    |
| `OnCreated`                                                | Editor only, right after creation, **with the owning Item, Set and Action**. Use it to auto-configure the item: add a component, seed a Stat, add a Condition to the Action. |

{% hint style="info" %}
`OnCreated` is what makes several built-in processors feel helpful rather than fiddly. The Reload processor uses it to add a `Stats` component, seed a `Chamber` Stat, copy the Projectile ID from a Fire processor in the same set, and gate the Action with a "chamber is not full" condition — all before you have touched a field.
{% endhint %}

### Signalling the chain

Call `ProcessorCompleted(item, set, action)` when your processor finishes its job, and `ProcessorInterrupted(...)` when it is cut short. Both signal every following processor with the matching flag, honouring each one's own Delay.