# Triggers

Triggers are MonoBehaviour components that automatically play a FlowPlayer when specific conditions are met. They provide a **no-code** way to start action sequences in response to game events.

***

## Common Properties

All triggers share these properties inherited from `FlowTriggerBase`:

| Property     | Description                                                   |
| ------------ | ------------------------------------------------------------- |
| Flow Player  | The FlowPlayer to trigger                                     |
| Trigger Once | If true, the trigger fires only once and then stops listening |
| Cooldown     | Minimum time (in seconds) between trigger fires               |

**Adding a Trigger:**

1. Select a GameObject
2. **Add Component > Flow Of Action > Triggers > \[Choose a trigger]**
3. Assign a FlowPlayer reference
4. Configure the trigger-specific settings

**Resetting a Trigger from Code:**

```csharp
// If trigger-once is enabled, reset it to allow firing again
GetComponent<FlowTriggerBase>().ResetTrigger();
```

***

## OnCollisionTrigger

Triggers when a physics collision occurs on this GameObject. Requires a Collider and Rigidbody.

| Property        | Description                                                   |
| --------------- | ------------------------------------------------------------- |
| Collision Event | Enter, Exit, or Stay                                          |
| Filter By Tag   | Only trigger for objects with a specific tag                  |
| Required Tag    | Tag to filter by (shown if Filter By Tag is enabled)          |
| Filter By Layer | Only trigger for objects on a specific layer                  |
| Required Layer  | Layer mask to filter by (shown if Filter By Layer is enabled) |

**Example Use Cases:** triggering a damage sequence when a projectile hits, playing a sound when objects collide, starting a cutscene when the player reaches an area.

***

## OnTriggerZone

Triggers when a collider enters, exits, or stays in a trigger zone. Requires a Collider with **Is Trigger** enabled.

| Property        | Description                                                   |
| --------------- | ------------------------------------------------------------- |
| Trigger Event   | Enter, Exit, or Stay                                          |
| Filter By Tag   | Only trigger for objects with a specific tag                  |
| Required Tag    | Tag to filter by (shown if Filter By Tag is enabled)          |
| Filter By Layer | Only trigger for objects on a specific layer                  |
| Required Layer  | Layer mask to filter by (shown if Filter By Layer is enabled) |

**Example Use Cases:** starting dialogue when the player enters an NPC's zone, activating traps, loading the next area, triggering ambient audio.

***

## OnInputTrigger

Triggers when a keyboard key is pressed, released, or held.

| Property    | Description                                         |
| ----------- | --------------------------------------------------- |
| Key Code    | The key to listen for (e.g., Space, E, F1)          |
| Input Event | Down (pressed), Up (released), or Hold (while held) |

**Hold trigger example:**

```
Key Code: LeftShift
Input Event: Hold
Cooldown: 0.1    // Fires repeatedly while held, throttled by cooldown
```

> **Note:** OnInputTrigger uses Unity's legacy Input system (`Input.GetKeyDown/Up/Key`). For the new Input System, create a custom trigger or invoke FlowPlayer from your input callbacks.

**Example Use Cases:** opening inventory, triggering sprint, activating abilities with number keys.

***

## OnMouseTrigger

Triggers when mouse events occur on this GameObject. Requires a Collider on the object.

| Property    | Description                     |
| ----------- | ------------------------------- |
| Mouse Event | Click, Enter, Exit, Down, or Up |

**Hover effect:** use two `OnMouseTrigger` components with different FlowPlayers for hover in/out.

**Example Use Cases:** clicking objects to interact, hover highlighting, tooltip display.

***

## OnTimerTrigger

Triggers after a specified delay, with optional repeating.

| Property          | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| Delay             | Time in seconds before the first trigger                    |
| Repeat            | If true, keeps triggering at regular intervals              |
| Repeat Interval   | Time between repeated triggers (shown if Repeat is enabled) |
| Use Unscaled Time | Use real time instead of game time                          |

**Pause-safe timer:**

```
Delay: 10.0
Use Unscaled Time: true    // Counts even when Time.timeScale = 0
```

> **Note:** The timer starts in `OnEnable` and stops in `OnDisable`. Disabling and re-enabling the component restarts the timer.

**Example Use Cases:** spawning enemies at intervals, showing a tutorial hint after idle, countdown timers.

***

## OnVariableTrigger

Triggers when a variable in VariableStorage changes or meets a specific condition.

| Property      | Description                                                            |
| ------------- | ---------------------------------------------------------------------- |
| Variable Name | Name of the variable to watch                                          |
| Variable Type | Bool, Int, Float, or String                                            |
| Trigger Mode  | OnAnyChange or OnConditionMet                                          |
| Operator      | Comparison operator (Equal, NotEqual, Greater, etc.)                   |
| Compare Value | Value to compare against (type-specific, shown based on Variable Type) |

**Example — trigger when health is low:**

```
Variable Name: health
Variable Type: Float
Trigger Mode: OnConditionMet
Operator: LessOrEqual
Compare Float Value: 25
```

> **Note:** OnVariableTrigger subscribes to `VariableStorage.OnVariableChanged` in `OnEnable` and unsubscribes in `OnDisable`. The VariableStorage singleton must exist for this trigger to work.

***

## OnEnableTrigger

Triggers when this GameObject is enabled, disabled, or both.

| Property   | Description              |
| ---------- | ------------------------ |
| Trigger On | Enable, Disable, or Both |

> **Note:** The first `OnEnable` call (when the scene loads) is automatically skipped to prevent unintended triggers during initialization.

**Example Use Cases:** playing an entrance animation when a UI panel is enabled, saving state when a panel is closed.

***

## Combining Triggers

**Example: Interactive Door**

```
GameObject: Door
├── FlowPlayer (Open Door sequence)
├── FlowPlayer (Close Door sequence)
├── OnTriggerZone (Enter → play Open Door)
├── OnTriggerZone (Exit → play Close Door)
└── BoxCollider (Is Trigger = true)
```

**Example: Timed Pickup with Input**

```
GameObject: Pickup
├── FlowPlayer (Collect sequence)
├── OnInputTrigger (E key → play Collect)
├── OnTimerTrigger (30s delay → destroy pickup)
└── SphereCollider
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://beelabs-dev.gitbook.io/beelabs-docs/flow-of-action/triggers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.