> ## Documentation Index
> Fetch the complete documentation index at: https://docs-vrsebuilder.autovrse.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers

## Overview

Triggers are the detection mechanisms that power interactive experiences in VRse Studio. They act as the "sensors" of your VR world, continuously monitoring for specific user actions and environmental changes. When conditions are met, triggers fire events that can advance your story, execute actions, or respond to user behavior. This comprehensive reference covers all available triggers and their implementation based on the current VRse Studio codebase.

## Understanding Triggers

### What Are Triggers?

Triggers are event detection systems that monitor specific conditions within your VR experience. Each trigger watches for discrete events such as:

* **Object Interactions**: Grabbing, touching, or manipulating objects
* **Spatial Relationships**: Object placement, collisions, or proximity
* **User Behavior**: Eye tracking, movement patterns, or responses
* **Time-Based Events**: Countdown completions or duration thresholds
* **System Events**: UI interactions, evaluations, or custom conditions

Think of triggers as the "if" statements in your VR experience - they define when specific story moments should progress or when feedback should be provided to users.

### Trigger Structure

Every trigger follows a consistent JSON structure:

```json theme={null}
{
  "Name": "TriggerName",
  "Query": "TargetObjectName", 
  "Option": "SpecificDetection",
  "Data": "{\"parameter\":\"value\"}",
  "Type": 1
}
```

**Components:**

* **Name**: The trigger type identifier
* **Query**: Target object name being monitored
* **Option**: Specific detection behavior within the trigger type
* **Data**: JSON string containing configuration parameters
* **Type**: Legacy field (currently unused, reserved for future functionality)

> **Note**: The `Type` field is currently not used in the system and has no functionality. It is maintained for backward compatibility and may be utilized for future features. Always set this to `1` for triggers.

### Common Parameters

Most triggers support these universal parameters:

* **handOption**: Specify hand detection ("None", "Left", "Right", "Both")
* **waitForCompletion**: Control trigger completion behavior
* **targetObjectName**: Reference to monitored object
* **duration**: Time-based thresholds for detection
* **isTrigger**: Physics detection mode (trigger vs collision)

## Trigger Categories

Triggers are organized into several categories based on their detection focus:

| Category               | Purpose                         | Examples                           |
| :--------------------- | :------------------------------ | :--------------------------------- |
| **Object Interaction** | Monitor object manipulation     | Grab, touch, placement             |
| **Spatial Detection**  | Track spatial relationships     | Collisions, eye level, proximity   |
| **Time-Based**         | Respond to temporal events      | Countdown completion, duration     |
| **Universal**          | Catch-all interaction detection | Any trigger, custom conditions     |
| **Evaluation**         | Assessment and feedback         | MCQ responses, completion tracking |

## Object Interaction Triggers

### GrabbableTrigger

Detects when objects are grabbed, released, or used (squeezed) with hand-specific detection capabilities.

**Options**

| Option      | Description                             |
| :---------- | :-------------------------------------- |
| **Grab**    | Object is grabbed by user               |
| **Release** | Object is released from grip            |
| **Used**    | Object is squeezed/activated while held |

**Parameters**

| Parameter    | Type   | Description                                         |
| :----------- | :----- | :-------------------------------------------------- |
| `handOption` | String | Hand specification: "None", "Left", "Right", "Both" |

**Example Usage**

```json theme={null}
{
  "Name": "GrabbableTrigger",
  "Query": "TrainingCube",
  "Option": "Grab",
  "Data": "{\"handOption\":\"Right\"}",
  "Type": 1
}
```

### HandTouchTrigger

Detects hand contact with objects or surfaces for precise touch interactions.

**Options**

| Option      | Description                     |
| :---------- | :------------------------------ |
| **Touch**   | Hand makes contact with object  |
| **Untouch** | Hand breaks contact with object |

**Example Usage**

```json theme={null}
{
  "Name": "HandTouchTrigger",
  "Query": "TouchButton",
  "Option": "Touch",
  "Data": "",
  "Type": 1
}
```

### PlacePointTrigger

Monitors object placement at specific locations with support for correct/incorrect placement detection.

**Options**

| Option            | Description                      |
| :---------------- | :------------------------------- |
| **Place**         | Any object placed at location    |
| **Remove**        | Any object removed from location |
| **PlaceCorrect**  | Correct object placed            |
| **PlaceWrong**    | Incorrect object placed          |
| **RemoveCorrect** | Correct object removed           |
| **RemoveWrong**   | Incorrect object removed         |

**Parameters**

| Parameter                | Type    | Description                           |
| :----------------------- | :------ | :------------------------------------ |
| `grabbableName`          | String  | Target object name (for Place/Remove) |
| `disableGrabOnPlace`     | Boolean | Prevent grabbing after placement      |
| `createGhostMesh`        | Boolean | Show placement preview                |
| `deleteGhostMeshOnPlace` | Boolean | Remove preview after placement        |

**Example Usage**

```json theme={null}
{
  "Name": "PlacePointTrigger",
  "Query": "AssemblyPoint",
  "Option": "PlaceCorrect",
  "Data": "{\"createGhostMesh\":true,\"deleteGhostMeshOnPlace\":true}",
  "Type": 1
}
```

## Spatial Detection Triggers

### CollisionTrigger

Detects physical interactions between objects with support for both trigger and collision detection.

**Options**

| Option    | Description               |
| :-------- | :------------------------ |
| **Enter** | Objects begin contact     |
| **Stay**  | Objects remain in contact |
| **Exit**  | Objects separate          |

**Parameters**

| Parameter                   | Type    | Description                                   |
| :-------------------------- | :------ | :-------------------------------------------- |
| `targetCollisionGameObject` | String  | Object to detect collision with               |
| `isTrigger`                 | Boolean | Use trigger (true) or solid collision (false) |

**Example Usage**

```json theme={null}
{
  "Name": "CollisionTrigger",
  "Query": "MovingPlatform",
  "Option": "Enter",
  "Data": "{\"targetCollisionGameObject\":\"SafetyBarrier\",\"isTrigger\":false}",
  "Type": 1
}
```

### EyeLevelDetectionTrigger

Tracks when objects enter, stay within, or exit the user's eye level for attention-based interactions.

**Options**

| Option              | Description                              |
| :------------------ | :--------------------------------------- |
| **EnteredEyeLevel** | Object enters user's eye level           |
| **StayedEyeLevel**  | Object remains in eye level for duration |
| **ExitedEyeLevel**  | Object exits user's eye level            |

**Parameters**

| Parameter          | Type   | Description                            |
| :----------------- | :----- | :------------------------------------- |
| `targetObjectName` | String | Object to track                        |
| `stayDuration`     | Float  | Required duration for stayed detection |

**Example Usage**

```json theme={null}
{
  "Name": "EyeLevelDetectionTrigger",
  "Query": "PlayerCamera",
  "Option": "StayedEyeLevel",
  "Data": "{\"targetObjectName\":\"CriticalEquipment\",\"stayDuration\":3.0}",
  "Type": 1
}
```

## Time-Based Triggers

### TimerTrigger

Responds to countdown timer completion for time-sensitive training scenarios.

**Parameters**

| Parameter | Type  | Description               |
| :-------- | :---- | :------------------------ |
| `endTime` | Float | Timer duration in seconds |

**Example Usage**

```json theme={null}
{
  "Name": "TimerTrigger",
  "Query": "SafetyTimer",
  "Option": "",
  "Data": "{\"endTime\":60.0}",
  "Type": 1
}
```

## Universal Triggers

### AnyTrigger

Universal interaction detector that captures any user action with advanced filtering capabilities.

**Parameters**

| `ignoreQueries`         | String Array | Object names to ignore                    |
| :---------------------- | :----------- | :---------------------------------------- |
| `ignoreTriggerTypes`    | String Array | Trigger types to ignore                   |
| `triggerFrom`           | Integer      | Trigger after N interactions (default: 1) |
| `triggerInterval`       | Integer      | Trigger every N interactions (default: 0) |
| `triggerOnce`           | Boolean      | Only trigger once (default: false)        |
| `ignoreOnRightTriggers` | Boolean      | Ignore correct interaction objects        |

**Example Usage**

```json theme={null}
{
  "Name": "AnyTrigger",
  "Query": "",
  "Option": "",
  "Data": "{\"triggerFrom\":2,\"triggerOnce\":true,\"ignoreOnRightTriggers\":true}",
  "Type": 1
}
```

## Evaluation Triggers

### MCQResponseTrigger

Detects responses to multiple-choice questions with support for correctness evaluation.

**Options**

| Option              | Description            |
| :------------------ | :--------------------- |
| **AnyResponse**     | Any answer provided    |
| **CorrectResponse** | Correct answer given   |
| **WrongResponse**   | Incorrect answer given |

**Example Usage**

```json theme={null}
{
  "Name": "MCQResponseTrigger",
  "Query": "EvaluationPanel",
  "Option": "CorrectResponse",
  "Data": "",
  "Type": 1
}
```