AR/VR Puzzles Reference — Soft8Soft
Description: How to enable and use the augmented reality and virtual reality modes in Puzzles.

# AR/VR Puzzles

These puzzles are used to enable web-based Augmented Reality (AR) and Virtual Reality (VR) experiences running on top of the browser technology called WebXR (eXtended Reality on the Web).

For more information with regard to supported AR/VR devices and best practices see the corresponding topic of this User Manual.

## Contents

- Puzzles Reference
  - check VR mode
  - enter VR mode
  - check AR mode
  - enter AR mode
  - detect surface AR
  - AR hit point
  - AR hit normal
  - camera control object
  - on session event
  - traverse controllers
  - get controller prop
  - end AR/VR session

#

## Puzzles Reference

#

### check VR mode

Checks the virtual reality system. If successful, the puzzles in the if available do are triggered. Otherwise, if the browser does not support VR or VR hardware not found, the puzzles in the if unavailable do slot are triggered.

See the following section for more info on creating virtual reality applications with Verge3D.

#

### enter VR mode

Enters the virtual reality mode. Puzzles placed in the on enter do and on exit do slots are triggered upon entering or exiting the VR mode. Puzzles placed in the if unavailable do are triggered if a VR session could not be established.

VR positioning modes:

sitting or standing
  Immobile camera positioned at some height above the ground. The center of the world coordinate space located just under the user's feet. This mode is recommended because it's compatible with the most popular VR headsets available on the market such as Meta Quest 1-3, HTC Vive, etc.
looking around
  Immobile camera positioned at zero coordinates.
room
  Mobile camera located inside some bounds such as room.
walking
  Mobile unbounded camera.
viewer locked
  Immobile camera positioned at zero coordinates. All content is parented to the view.

In order to properly control the camera in VR mode, be sure to snap and parent it to some empty/dummy or real object, positioned in the 3D editor of your choice, upon entering the VR mode. This is needed because the VR session has the full control over your camera, and you can move only the empty/dummy object to which the camera is parented.

Starting from Verge3D 4.3 you can use camera control object puzzle instead of creating a control object by hand.

#

### check AR mode

Checks the augmented reality system (WebXR). If successful, the puzzles in the if available do slot are triggered. Otherwise, if the browser does not support AR or AR hardware not found, the puzzles in the else if unavailable do slot are triggered. The puzzles in the else if Apple USDZ do slot are triggered when no WebXR-compatible hardware found, but the system supports USDZ-based Apple AR Quick Look technology.

See the following section for more info on creating augmented reality applications with Verge3D.

#

### enter AR mode

Enters the augmented reality mode. Puzzles placed in the on enter do and on exit do slots are triggered upon entering or exiting the AR mode. Puzzles placed in the if unavailable do are triggered if a AR session could not be established.

Property allow HTML is used to display HTML content in AR mode. If specified, the content of the canvas container element will be rendered above 3D content. This option is considered experimental.

AR positioning modes:

looking around
  Immobile camera positioned at zero coordinates. This mode is recommended for typical AR use cases, e.g for positioning a model on some horizontal or vertical surface.
sitting or standing
  Immobile camera positioned at some height above the ground. The center of the world coordinate space located just under the user's feet.
room
  Mobile camera located inside some bounds such as room.
walking
  Mobile unbounded camera.
viewer locked
  Immobile camera positioned at zero coordinates. All content is parented to the view.

#

### detect surface AR

Detect surfaces in AR mode by casting a ray forward. Upon intersection, this ray will trigger puzzles in on intersection do slot. If no intersection occurred or the device is in warming-up state the puzzles triggers if missed do slot.

Parameter smooth is used to make AR marker movement smoother. Specify value 0 to disable smoothing, value close to 1 for maximum smoothing.

#

### AR hit point

Surface point coordinate(s) detected by the detect surface AR puzzle. Can be X, Y, Z value, or XYZ vector.

#

### AR hit normal

Surface normal vector detected by the detect surface AR puzzle. Can be X, Y, Z value, or XYZ vector.

#

### camera control object

Get camera control object. By offsetting this object (e.g. with the set transform puzzle), you can efficiently move the camera in the AR or VR mode. This spares you from the need to maintain some empty object specifically to parent and snap the camera to, as this object is created or dropped automatically when entering or exiting WebXR.

#

### on session event

Captures a VR session event generated by a VR device (e.g. a headset or controller button) and triggers puzzles specified in the do slot.

Supported events:

- select — triggered when user pressed and released the primary controller button.
- selectstart — triggered when user pressed the primary controller button.
- selectend — triggered when user released the primary controller button.
- squeeze — triggered when user squeezed and released a controller.
- squeezestart — triggered when user squeezed a controller.
- squeezeend — triggered when user unsqueezed controller.
- connected — triggered when VR controller connected, i.e. upon entering a VR session. Use this event to initialize any controller logic.
- disconnected — triggered when VR controller disconnected.

#

### traverse controllers

Loop over all connected VR controllers, execute puzzles specified in the do slot.

#

### get controller prop

Get the specified property of the VR controller.

Supported properties:

- object — an empty object representing controller.
- ray/reticle — controller ray or reticle object.
- handedness — controller handedness, one of: "left" (left controller), "right" (right controller), "none" (unspecified, likely head-mounted controller).
- target ray mode — one of: "gaze" (for gaze aka cardboard-like devices), "tracked-pointer" (for regular handheld controllers), "screen" (the event is associated with canvas input, currently not implemented).
- profiles — a list of controller profile names.
- gamepad index — a controller gamepad index which can be passed to the get gamepad property puzzle to retrieve more info from your controller, such as the status of buttons/axes.

#

### end AR/VR session

Ends a virtual reality or augmented reality session.

## Having Troubles with Puzzles?

Seek help on the forums!