> 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/utilities/animal-tracker.md).

# Animal Tracker

Last updated AC v1.5.3

## Overview

\[Insert Image - Animal Tracker component in the Inspector with two or three Tracker rows]

`Animal Tracker` watches a character's **States**, **Stances** and **Modes** and reacts when they change. Every row on its list is one rule: *while the character is in these States / Stances / Modes, fire this Reaction and (optionally) move a Transform to this offset.*

It does two independent jobs, and either one works on its own:

* **Reposition a Transform.** Smoothly lerp a "tracker" GameObject to a position and rotation that depend on what the character is doing — a camera Look At target that shifts when the character crouches, aims, swims or climbs.
* **Dispatch Reactions.** Fire a `Reaction2` when a State, Stance or Mode becomes active, without touching any Transform at all.

{% hint style="info" %}
**The Tracker Transform is optional.** Leave **Tracker** empty and the component becomes a pure *"when the character does X, react"* dispatcher. Every Reposition parameter hides itself in the Inspector, and each row keeps only its States, Stances, Modes, Abilities and Reaction. See [Reactions only, without a Tracker](#reactions-only-without-a-tracker).
{% endhint %}

## Requirements

Add the component to the character, or to a child GameObject inside the Animal Controller's internal components.

It needs a reference to the **Animal** component — it is found automatically when you add the component, and can also be set at runtime with `SetAnimal()`.

The component uses `[DefaultExecutionOrder(10000)]`, so it always evaluates after the Animal Controller has finished updating for the frame.

## How it Works

The component subscribes to the Animal's own events. Every time one fires, it walks the Tracker list from top to bottom looking for a row that matches.

```
 MAnimal events               Animal Tracker
 ──────────────               ──────────────

 OnStateChange   ──┐
 OnStanceChange  ──┼──▶  match a row  ──┬──▶  Reaction2
 OnModeStart     ──┤   States/Stances/  │
 OnModeEnd       ──┘   Modes/Abilities  └──▶  move Tracker to Position + Rotation,
                                              relative to [Relative To]
```

**State and Stance changes: the first matching row wins.** Rows below it are skipped, so put the most specific rules at the top of the list and the general ones underneath.

**Mode changes: every matching row fires.** A Mode row is not exclusive — all rows matching that Mode run their Reaction, and the last one with **Reposition** enabled is the one that moves the Tracker.

**When nothing matches**, the Tracker returns to the position, rotation and parent it had when the scene started. That default is captured on `Awake` from the Tracker's own Transform, so place the Tracker where it should normally sit and the component treats that as home.

A row is only considered while its **Active** toggle is on, so a rule can be muted without deleting it.

### Reactions only, without a Tracker

Assigning a **Tracker** is optional. With the field empty the component still listens to everything and still runs each row's **Reaction** — it simply has no Transform to move.

The Inspector follows suit. **Fixed Update**, **No Parent** and **Debug Size** disappear from the top section, the **Reposition** column and its per-row toggle disappear from the list, and each row drops **Lerp**, **Position**, **Rotation**, **Relative To** and **Debug Color**. No debug cubes are drawn in the Scene View either.

Nothing is lost: the per-row **Reposition** values already authored are only hidden, so assigning a Tracker later brings them straight back.

Use this whenever the only thing you need is *"when the character enters this State, run this Reaction"*.

### Include and Exclude lists

**States**, **Stances** and **Modes** are ID lists with an Include/Exclude toggle — the green **I** / red **E** button on the right of the list. Click **+** to add IDs; right-click the list to copy and paste a whole set between rows.

| List state           | Meaning                                                |
| -------------------- | ------------------------------------------------------ |
| **Include** with IDs | The row matches only those IDs.                        |
| **Exclude** with IDs | The row matches every ID **except** those listed.      |
| Empty                | The row never matches — nothing was authored to match. |

**Abilities** works the same way, with one deliberate difference: an empty Abilities list means **any** ability, because the Mode itself is already doing the filtering.

{% hint style="info" %}
**Coming from an older version?** Each row used to hold a single State, a single Stance, a single Mode and a single Ability index. Those values are folded into the new lists automatically the first time the prefab or scene is loaded — **save it afterwards** so the migrated result is kept.

One case is worth a manual check: a row that tracked **Ability** with the index left at `-1` now means *any ability* rather than *ability −1*.
{% endhint %}

## Parameters

\[Insert Image - top section of the component: Animal, Tracker, Fixed Update, No Parent, Debug Size]

#### Animal

Reference to the Animal component this tracker listens to. Found automatically when the component is added.

#### Tracker

The Transform to move. Optional — leave it empty to use the component only to dispatch Reactions.

#### Fixed Update

Update the Tracker on `FixedUpdate` instead of `Update`. Enable it when the Tracker has to stay in sync with a physics-driven object; leave it off otherwise. Only shown when a **Tracker** is assigned.

#### No Parent

Unparents the Tracker when the component is enabled, so its world position is driven purely by this component and never inherited from a parent. Only shown when a **Tracker** is assigned.

#### Debug Size

Size of the debug cube drawn in the Scene View at each row's Tracker position. Only shown when a **Tracker** is assigned.

### Tracker List

\[Insert Image - the Tracker list with its Active, Tracking Action, Description and Reposition columns]

Each row in the list is one rule. The columns are:

| Column              | What it does                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------- |
| **Active**          | Mutes or enables the row without deleting it.                                                     |
| **Tracking Action** | Which things this row checks: State, Stance, Mode, Ability.                                       |
| **Description**     | Auto-generated summary of the row, built from the lists it checks.                                |
| **Reposition**      | Whether a match moves the **Tracker**, or only fires the Reaction. Only shown with a **Tracker**. |

The **Description** is generated for you — `[Idle, Locomotion] [Attack] Ability [1, 2]`. An excluded list is shown with a leading `!`, and an empty Abilities list shows as `ANY`.

**Tracking Action** is a set of flags, so a single row can require a State *and* a Stance *and* a Mode at the same time. Selecting **Ability** also brings in the Mode fields, since an ability only exists inside a Mode.

Selecting a row shows its settings underneath, and only the fields the row's Tracking Action actually uses:

\[Insert Image - selected row settings: States, Stances, Modes, Abilities, Mode Action, Reaction, Lerp, Position, Rotation, Relative To]

#### States

Include/Exclude list of States that can activate this row.

#### Stances

Include/Exclude list of Stances that can activate this row. Combined with **States**, both have to pass.

#### Modes

Include/Exclude list of Modes that can activate this row.

#### Abilities

Ability indexes, within the Modes above, that can activate this row. Leave it empty to accept any ability.

#### Mode Action

Whether the row reacts when the Mode **Starts** or when it **Exits**.

#### Reaction

The `Reaction2` executed on the Animal when the row matches. This is where the row does its work beyond moving a Transform — enable a component, play a sound, change a Stat, drive a camera.

### Reposition

These fields only appear when a **Tracker** is assigned and the row's **Reposition** toggle is on.

#### Lerp

Speed the Tracker moves and rotates towards this row's offset. Higher values snap faster; lower values glide.

#### Position

Local position offset for the Tracker, relative to **Relative To**.

#### Rotation

Local rotation offset (Euler angles) for the Tracker, relative to **Relative To**.

You can edit **Position** and **Rotation** with the Move and Rotate handles in the Scene View while the row is selected.

#### Relative To

The Transform that **Position** and **Rotation** are measured from. Defaults to the parent of the GameObject holding the component. Point it at a bone to make the offset follow that bone.

#### Debug Color

Color of the row's debug cube in the Scene View.

## Methods and Properties

#### SetAnimal (GameObject) / SetAnimal (Component)

Re-targets the tracker at a different character at runtime, moving all the event listeners across. Useful with character swapping and local multiplayer.

#### Current Index

`{get;}` Index of the row currently driving the Tracker. The Inspector highlights this row while the game is playing.

#### Current State / Last State

`{get;}` ID of the State the character is in now, and the one before it.

#### Current Stance / Last Stance

`{get;}` ID of the Stance the character is in now, and the one before it.