> ## 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.

# Actions

## Overview

Actions are the fundamental building blocks of VRse Studio experiences. They define what happens in your VR world - from moving objects and playing sounds to updating user interfaces and controlling player behavior. This comprehensive reference covers all available actions and their implementation based on the current VRse Studio codebase.

## Understanding Actions

Actions are executable instructions that define specific behaviors in your VR experience. Each action performs a discrete task such as:

* Manipulating objects in the 3D environment
* Playing audio or visual media
* Updating user interface elements
* Controlling player movement and interactions
* Managing game logic and flow

### Structure

Every action follows a consistent JSON structure:

```json theme={null}
{
  "Name": "ActionName",
  "Query": "TargetObjectName", 
  "Option": "SpecificOperation",
  "Data": "{\"parameter\":\"value\"}",
  "Type": 0
}
```

**Components:**

* **Name**: The action type identifier
* **Query**: Target object name (when applicable)
* **Option**: Specific operation within the action type
* **Data**: JSON string containing 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 `0` for actions.

### Common Parameters

Most actions support these universal parameters:

* **waitForCompletion**: Boolean indicating whether to wait for action completion before proceeding
* **targetTransform**: Reference to target position/rotation object
* **duration**: Time-based parameter for timed operations
* **lerpSpeed**: Animation speed for transform operations

***

## Action Types

Actions are organized into several categories based on their functionality:

| Category                   | Purpose                   | Examples                                      |
| :------------------------- | :------------------------ | :-------------------------------------------- |
| **Object Manipulation**    | Control 3D objects        | Move, scale, animate, spawn/despawn           |
| **Media & Audio**          | Handle multimedia content | Voice-over, SFX, videos, images               |
| **User Interface**         | Manage UI elements        | Update text, reposition panels, notifications |
| **Player Control**         | Manage user experience    | Teleport, camera effects, movement            |
| **Interactive Components** | Control VR interactions   | Highlighting, animations, physics             |
| **Meta Layer**             | Advanced visual effects   | Outlines, labels, arrows                      |
| **Specialized**            | Domain-specific features  | Haptics, evaluation tools, checklists         |

***

## Object Manipulation Actions

### ObjectAction (Objects)

Controls basic object properties and transformations with enhanced animation capabilities.

**Options**

| Option                      | Description                                    |
| :-------------------------- | :--------------------------------------------- |
| **Spawn**                   | Enable an item (SetActive = true)              |
| **Despawn**                 | Disable the item (SetActive = false)           |
| **SetComponentProperty**    | Modify IGrabbableWrapper properties            |
| **ChangePosition**          | Instantly move object to target transform      |
| **AnimatePosition**         | Smoothly animate object to target position     |
| **AnimateScale**            | Smoothly animate object scale                  |
| **AnimatePositionAndScale** | Animate both position and scale simultaneously |

**Parameters**

| Parameter           | Type    | Description                                |
| :------------------ | :------ | :----------------------------------------- |
| `waitForCompletion` | Boolean | Wait for action completion                 |
| `lerpSpeed`         | Float   | Animation transition speed (default: 0.5f) |
| `component`         | String  | Component name for property modification   |
| `property`          | String  | Property name to modify                    |
| `propertyValue`     | Boolean | New property value                         |
| `targetTransform`   | String  | Target transform reference                 |
| `isAnimated`        | Boolean | Whether to use animation                   |

**Example Usage**

```json theme={null}
{
  "Name": "Objects",
  "Query": "Cube.001",
  "Option": "AnimatePosition",
  "Data": "{\"waitForCompletion\":true,\"lerpSpeed\":2.5,\"targetTransform\":\"targetPos\"}",
  "Type": 0
}
```

### ObjectAnimationAction

Advanced object animation with precise control over position, rotation, and scale.

**Options**

| Option                    | Description                      |
| :------------------------ | :------------------------------- |
| **Position**              | Animate position only            |
| **Rotation**              | Animate rotation only            |
| **Scale**                 | Animate scale only               |
| **PositionRotation**      | Animate position and rotation    |
| **PositionScale**         | Animate position and scale       |
| **RotationScale**         | Animate rotation and scale       |
| **PositionRotationScale** | Animate all transform properties |

**Parameters**

| Parameter           | Type    | Description                     |
| :------------------ | :------ | :------------------------------ |
| `targetTransform`   | String  | Target transform reference      |
| `lerpSpeed`         | Float   | Animation speed (default: 1.0f) |
| `waitForCompletion` | Boolean | Wait for animation completion   |

**Example Usage**

```json theme={null}
{
  "Name": "ObjectAnimation",
  "Query": "GameObject",
  "Option": "PositionRotation",
  "Data": "{\"targetTransform\":\"TargetPos\",\"lerpSpeed\":1.5,\"waitForCompletion\":true}",
  "Type": 0
}
```

***

## Media and Audio Actions

### VoiceOver Action

Converts text to speech with advanced localization and caching support.

**Options**

| Option          | Description               |
| :-------------- | :------------------------ |
| **Play**        | Play text-to-speech audio |
| **Pause**       | Pause ongoing voiceover   |
| **StopAndSkip** | Stop ongoing voiceover    |

**Parameters**

| Parameter           | Type    | Description                    |
| :------------------ | :------ | :----------------------------- |
| `text`              | String  | Text to be converted to speech |
| `waitForCompletion` | Boolean | Wait for audio completion      |

**Example Usage**

```json theme={null}
{
  "Name": "VoiceOver",
  "Query": "",
  "Option": "Play",
  "Data": "{\"text\":\"Welcome to the VR experience\",\"waitForCompletion\":true}",
  "Type": 0
}
```

### SFXPlayerAction

Enhanced sound effects management with cloud audio support.

**Options**

| Option          | Description                      |
| :-------------- | :------------------------------- |
| **Play**        | Play the specified audio clip    |
| **Pause**       | Pause current audio              |
| **PlayLoop**    | Loop the audio clip continuously |
| **StopAndSkip** | Stop and skip current audio      |

**Parameters**

| Parameter       | Type    | Description                                     |
| :-------------- | :------ | :---------------------------------------------- |
| `audioClipName` | String  | Name of audio clip in Resources folder          |
| `useCloudAudio` | Boolean | Whether to use cloud-based audio                |
| `audioUrl`      | String  | URL for cloud audio (when useCloudAudio = true) |
| `audioRange`    | Float   | Audio hearing distance                          |
| `setVolume`     | Float   | Volume level (0.0 to 1.0)                       |

**Example Usage**

```json theme={null}
{
  "Name": "SFXPlayer",
  "Query": "AudioSource",
  "Option": "Play",
  "Data": "{\"waitForCompletion\":true,\"audioClipName\":\"ButtonClick\",\"audioRange\":5.0,\"setVolume\":0.8}",
  "Type": 0
}
```

### TextMediaAction

Controls text content display using MultiMediaPlayer component.

**Options**

| Option      | Description          |
| :---------- | :------------------- |
| **Enable**  | Display text content |
| **Disable** | Hide text content    |

**Parameters**

| Parameter           | Type    | Description                |
| :------------------ | :------ | :------------------------- |
| `content`           | String  | Text content to display    |
| `waitForCompletion` | Boolean | Wait for action completion |

**Example Usage**

```json theme={null}
{
  "Name": "TextMediaAction",
  "Query": "TextPanel",
  "Option": "Enable",
  "Data": "{\"content\":\"Instructions: Complete the task\",\"waitForCompletion\":false}",
  "Type": 0
}
```

### ImageMediaAction

Controls image content display using MultiMediaPlayer component.

**Options**

| Option      | Description           |
| :---------- | :-------------------- |
| **Enable**  | Display image content |
| **Disable** | Hide image content    |

**Parameters**

| Parameter           | Type    | Description                    |
| :------------------ | :------ | :----------------------------- |
| `content`           | String  | Image path in Resources folder |
| `waitForCompletion` | Boolean | Wait for action completion     |

**Example Usage**

```json theme={null}
{
  "Name": "ImageMediaAction",
  "Query": "ImagePanel",
  "Option": "Enable",
  "Data": "{\"content\":\"Images/Diagram\",\"waitForCompletion\":false}",
  "Type": 0
}
```

### VideoMediaAction

Controls video content display with completion tracking.

**Options**

| Option      | Description                    |
| :---------- | :----------------------------- |
| **Enable**  | Display and play video content |
| **Disable** | Stop and hide video content    |

**Parameters**

| Parameter           | Type    | Description                    |
| :------------------ | :------ | :----------------------------- |
| `content`           | String  | Video path in Resources folder |
| `waitForCompletion` | Boolean | Wait for video completion      |

**Example Usage**

```json theme={null}
{
  "Name": "VideoMediaAction",
  "Query": "VideoPanel",
  "Option": "Enable",
  "Data": "{\"content\":\"Videos/Tutorial\",\"waitForCompletion\":true}",
  "Type": 0
}
```

***

## User Interface Actions

### UIUpdateAction

Updates Experience Panel interface elements with enhanced positioning.

**Options**

| Option                | Description                         |
| :-------------------- | :---------------------------------- |
| **UpdateDescription** | Change Experience Panel description |
| **UpdateUIPosition**  | Move UI to target position          |

**Parameters**

| Parameter         | Type   | Description            |
| :---------------- | :----- | :--------------------- |
| `textDescription` | String | New description text   |
| `targetTransform` | String | Target position for UI |

**Example Usage**

```json theme={null}
{
  "Name": "UIUpdate",
  "Query": "",
  "Option": "UpdateDescription",
  "Data": "{\"textDescription\":\"Step 2: Grab the tool\",\"waitForCompletion\":false}",
  "Type": 0
}
```

### ToastMessageAction

Displays temporary notification messages with type-based styling.

**Parameters**

| Parameter     | Type   | Description                      |
| :------------ | :----- | :------------------------------- |
| `message`     | String | Message text to display          |
| `messageType` | String | "Default", "Wrong", or "Correct" |
| `duration`    | Float  | Display duration in seconds      |

**Example Usage**

```json theme={null}
{
  "Name": "ToastMessage",
  "Query": "",
  "Option": "",
  "Data": "{\"message\":\"Task completed successfully!\",\"messageType\":\"Correct\",\"duration\":3.0}",
  "Type": 0
}
```

### ChecklistUIAction

Advanced checklist management with move-to-next functionality.

**Options**

| Option        | Description                               |
| :------------ | :---------------------------------------- |
| **Check**     | Check the toggle                          |
| **Uncheck**   | Uncheck the toggle                        |
| **Current**   | Set toggle as current                     |
| **Configure** | Populate checklist with title and toggles |

**Parameters**

| Parameter     | Type         | Description                              |
| :------------ | :----------- | :--------------------------------------- |
| `index`       | Integer      | Toggle index (starting from 1)           |
| `titleText`   | String       | Checklist title (Configure option only)  |
| `toggleInfos` | String Array | Array of toggle text labels              |
| `moveToNext`  | Boolean      | Auto-advance to next item after checking |

**Example Usage**

```json theme={null}
{
  "Name": "ChecklistUIToggle",
  "Query": "ChecklistUI",
  "Option": "Check",
  "Data": "{\"index\":1,\"moveToNext\":true,\"waitForCompletion\":false}",
  "Type": 0
}
```

### MCQResponseAction

Multiple-choice question evaluation with multi-answer support.

**Parameters**

| Parameter            | Type          | Description                      |
| :------------------- | :------------ | :------------------------------- |
| `questionIndex`      | Integer       | Question number                  |
| `questionText`       | String        | Question content                 |
| `optionsList`        | String Array  | Answer options                   |
| `correctOptionIndex` | Integer Array | Correct answer indices (0-based) |
| `showAnswerDuration` | Float         | Time to display answer           |

**Example Usage**

```json theme={null}
{
  "Name": "MCQResponseAction",
  "Query": "MCQ_Panel",
  "Option": "",
  "Data": "{\"questionIndex\":1,\"questionText\":\"What is 2+2?\",\"optionsList\":[\"3\",\"4\",\"5\"],\"correctOptionIndex\":[1],\"showAnswerDuration\":3}",
  "Type": 0
}
```

***

## Player Control Actions

### PlayerAction

Enhanced player control with improved fade and movement systems.

**Options**

| Option             | Description                    |
| :----------------- | :----------------------------- |
| **Teleport**       | Move player to target position |
| **LockMovement**   | Disable player movement        |
| **UnlockMovement** | Enable player movement         |
| **CameraFade**     | Apply camera fade effects      |

**Parameters**

| Parameter         | Type    | Description                         |
| :---------------- | :------ | :---------------------------------- |
| `targetTransform` | String  | Target position for teleport        |
| `shouldFade`      | Boolean | Whether to fade during teleport     |
| `fadeType`        | String  | "FadeIn", "FadeOut", or "FadeInOut" |
| `fadeDuration`    | Float   | Fade effect duration                |

**Features**

* **IPlayer Interface**: Uses standardized player interface
* **Event-Driven**: Waits for action completion events
* **Flexible Fading**: Configurable fade effects
* **Error Handling**: Robust parameter validation

**Example Usage**

```json theme={null}
{
  "Name": "Player",
  "Query": "XRPlayer",
  "Option": "Teleport",
  "Data": "{\"targetTransform\":\"WaypointA\",\"shouldFade\":true,\"fadeDuration\":1.0,\"waitForCompletion\":true}",
  "Type": 0
}
```

### HapticsAction

Precise haptic feedback control for enhanced immersion.

**Options**

| Option    | Description                              |
| :-------- | :--------------------------------------- |
| **Left**  | Send haptic feedback to left controller  |
| **Right** | Send haptic feedback to right controller |
| **Both**  | Send haptic feedback to both controllers |

**Parameters**

| Parameter           | Type    | Description                      |
| :------------------ | :------ | :------------------------------- |
| `hapticIntensity`   | Float   | Vibration intensity (0.0 to 1.0) |
| `hapticDuration`    | Float   | Duration in seconds              |
| `waitForCompletion` | Boolean | Wait for haptic completion       |

**Example Usage**

```json theme={null}
{
  "Name": "HapticsAction",
  "Query": "",
  "Option": "Both",
  "Data": "{\"hapticIntensity\":0.7,\"hapticDuration\":0.3,\"waitForCompletion\":true}",
  "Type": 0
}
```

***

## Interactive Component Actions

### AnimationAction

Enhanced animation control supporting both Animation and Animator components.

**Options**

| Option     | Description                   |
| :--------- | :---------------------------- |
| **Play**   | Play animation from beginning |
| **Pause**  | Pause current animation       |
| **Resume** | Resume from current position  |
| **Stop**   | Stop current animation        |

**Parameters**

| Parameter           | Type    | Description                   |
| :------------------ | :------ | :---------------------------- |
| `_clipName`         | String  | Animation clip name           |
| `waitForCompletion` | Boolean | Wait for animation completion |

**Example Usage**

```json theme={null}
{
  "Name": "Animation",
  "Query": "AnimatedObject",
  "Option": "Play",
  "Data": "{\"_clipName\":\"OpenDoor\",\"waitForCompletion\":true}",
  "Type": 0
}
```

### ObjectHighlighterAction

Object highlighting with improved state management.

**Options**

| Option     | Description                 |
| :--------- | :-------------------------- |
| **Idle**   | Remove highlighting         |
| **Normal** | Apply normal highlight      |
| **Alert**  | Apply alert/pulse highlight |

**Parameters**

| Parameter        | Type    | Description               |
| :--------------- | :------ | :------------------------ |
| `enableDuration` | Boolean | Enable timed highlighting |
| `duration`       | Float   | Highlight duration        |

**Example Usage**

```json theme={null}
{
  "Name": "ObjectHighlighter",
  "Query": "TargetObject",
  "Option": "Normal",
  "Data": "{\"waitForCompletion\":false}",
  "Type": 0
}
```

### TimerAction

Countdown timer with automatic component management.

**Options**

| Option    | Description                             |
| :-------- | :-------------------------------------- |
| **Start** | Start countdown from specified duration |
| **Stop**  | Stop the timer                          |
| **Reset** | Reset timer to 0                        |

**Parameters**

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

**Example Usage**

```json theme={null}
{
  "Name": "TimerAction",
  "Query": "TimerObject",
  "Option": "Start",
  "Data": "{\"duration\":60,\"waitForCompletion\":true}",
  "Type": 0
}
```

### GrabbablePropertyChangeAction

Advanced grabbable object property management.

**Options**

| Option                | Description                   |
| :-------------------- | :---------------------------- |
| **ChangeHandType**    | Restrict which hands can grab |
| **ChangeIsGrabbable** | Enable/disable grabbing       |

**Parameters**

| Parameter     | Type    | Description                |
| :------------ | :------ | :------------------------- |
| `handType`    | String  | "Left", "Right", or "Both" |
| `isGrabbable` | Boolean | Grabbable state            |

**Example Usage**

```json theme={null}
{
  "Name": "GrabbablePropertyChangeAction",
  "Query": "Tool",
  "Option": "ChangeHandType",
  "Data": "{\"handType\":\"Right\",\"waitForCompletion\":false}",
  "Type": 0
}
```

***

## Meta Layer Actions

### MetaLayerAction

Advanced visual effects system for enhanced object interaction feedback.

**Options**

| Option        | Description                                |
| :------------ | :----------------------------------------- |
| **SetActive** | Enable/disable meta layer components       |
| **Edit**      | Modify properties of meta layer components |

**Supported Layer Types**

* **Outline**: Visual object outlining with color and width control
* **Label**: Text labels with spatial positioning
* **Arrow**: Directional indicators (when available)

**Parameters**

| Parameter      | Type    | Description                        |
| :------------- | :------ | :--------------------------------- |
| `Outline`      | Object  | Outline configuration              |
| `Label`        | Object  | Label configuration                |
| `outlineColor` | String  | Hex color code (e.g., "`#FF0000`") |
| `outlineWidth` | Float   | Outline thickness                  |
| `labelText`    | String  | Text content for label             |
| `setActive`    | Boolean | Enable/disable state for layer     |

**Features**

* **Simultaneous Control**: Manage multiple layers in one action
* **Hex Color Support**: Standard hex color format (#RRGGBB or #RRGGBBAA)
* **Fallback System**: Uses magenta color for invalid formats
* **Auto-Component Creation**: Adds components if missing

**Example Usage**

```json theme={null}
{
  "Name": "MetaLayerAction",
  "Query": "TargetObject",
  "Option": "Edit",
  "Data": "{\"Outline\":{\"outlineColor\":\"#00FF00\",\"outlineWidth\":2.0,\"setActive\":true},\"Label\":{\"labelText\":\"Important Item\",\"setActive\":true}}",
  "Type": 0
}
```

***