Actions - VRseBuilder Documentation

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

2. Understanding Actions

2.1 What Are 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

2.2 Action Structure

Every action follows a consistent JSON structure:

{
  "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.

2.3 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

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

4. Object Manipulation Actions

4.1 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

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

4.2 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

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

5. Media and Audio Actions

5.1 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

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

5.2 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

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

5.3 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

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

5.4 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

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

5.5 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

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

6. User Interface Actions

6.1 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

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

6.2 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

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

6.3 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

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

6.4 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

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

7. Player Control Actions

7.1 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

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

7.2 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

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

8. Interactive Component Actions

8.1 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

{
  "Name": "Animation",
  "Query": "AnimatedObject",
  "Option": "Play",
  "Data": "{\"_clipName\":\"OpenDoor\",\"waitForCompletion\":true}",
  "Type": 0
}

8.2 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

{
  "Name": "ObjectHighlighter",
  "Query": "TargetObject",
  "Option": "Normal",
  "Data": "{\"waitForCompletion\":false}",
  "Type": 0
}

8.3 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

{
  "Name": "TimerAction",
  "Query": "TimerObject",
  "Option": "Start",
  "Data": "{\"duration\":60,\"waitForCompletion\":true}",
  "Type": 0
}

8.4 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

{
  "Name": "GrabbablePropertyChangeAction",
  "Query": "Tool",
  "Option": "ChangeHandType",
  "Data": "{\"handType\":\"Right\",\"waitForCompletion\":false}",
  "Type": 0
}

9. Meta Layer Actions

9.1 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

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

Get Started

Guides

Studio

Workshop

Unity SDK

Features

​1. Overview

​2. Understanding Actions

​2.1 What Are Actions?

​2.2 Action Structure

​2.3 Common Parameters

​3. Action Types

​4. Object Manipulation Actions

​4.1 ObjectAction (Objects)

​Options

​Parameters

​Example Usage

​4.2 ObjectAnimationAction

​Options

​Parameters

​Example Usage

​5. Media and Audio Actions

​5.1 VoiceOver Action

​Options

​Parameters

​Example Usage

​5.2 SFXPlayerAction

​Options

​Parameters

​Example Usage

​5.3 TextMediaAction

​Options

​Parameters

​Example Usage

​5.4 ImageMediaAction

​Options

​Parameters

​Example Usage

​5.5 VideoMediaAction

​Options

​Parameters

​Example Usage

​6. User Interface Actions

​6.1 UIUpdateAction

​Options

​Parameters

​Example Usage

​6.2 ToastMessageAction

​Parameters

​Example Usage

​6.3 ChecklistUIAction

​Options

​Parameters

​Example Usage

​6.4 MCQResponseAction

​Parameters

​Example Usage

​7. Player Control Actions

​7.1 PlayerAction

​Options

​Parameters

​Features

​Example Usage

​7.2 HapticsAction

​Options

​Parameters

​Example Usage

​8. Interactive Component Actions

​8.1 AnimationAction

​Options

​Parameters

​Example Usage

​8.2 ObjectHighlighterAction

​Options

​Parameters

​Example Usage

​8.3 TimerAction

​Options

​Parameters

​Example Usage

1. Overview

2. Understanding Actions

2.1 What Are Actions?

2.2 Action Structure

2.3 Common Parameters

3. Action Types

4. Object Manipulation Actions

4.1 ObjectAction (Objects)

Options

Parameters

Example Usage

4.2 ObjectAnimationAction

Options

Parameters

Example Usage

5. Media and Audio Actions

5.1 VoiceOver Action

Options

Parameters

Example Usage

5.2 SFXPlayerAction

Options

Parameters

Example Usage

5.3 TextMediaAction

Options

Parameters

Example Usage

5.4 ImageMediaAction

Options

Parameters

Example Usage

5.5 VideoMediaAction

Options

Parameters

Example Usage

6. User Interface Actions

6.1 UIUpdateAction

Options

Parameters

Example Usage

6.2 ToastMessageAction

Parameters

Example Usage

6.3 ChecklistUIAction

Options

Parameters

Example Usage

6.4 MCQResponseAction

Parameters

Example Usage

7. Player Control Actions

7.1 PlayerAction

Options

Parameters

Features

Example Usage

7.2 HapticsAction

Options

Parameters

Example Usage

8. Interactive Component Actions

8.1 AnimationAction

Options

Parameters

Example Usage

8.2 ObjectHighlighterAction

Options

Parameters

Example Usage

8.3 TimerAction

Options

Parameters

Example Usage

8.4 GrabbablePropertyChangeAction

Options

Parameters

Example Usage

9. Meta Layer Actions

9.1 MetaLayerAction