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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---