---
order: 3
title: XR Workflows
---

# XR Workflows

XR workflows are for projects that need headset input and interaction. The listener → gate → executor shape is unchanged; the bricks source their data from XR trackers and drive the `XROrigin3D` rig. XR bricks are **Pro tier**. The set is deliberately consolidated — one brick per concern instead of dozens — so a full VR loop stays readable.

```{note}
XR bricks build and wire like any other GDLink brick, but headset-specific behavior is validated manually on hardware as a release step. Test on your target device before shipping.
```

## Starting a session

**[XR Session](../reference/generated/executors/xr_session_executor.md)** owns the session lifecycle — initialization, shutdown, world scale, orientation reset, interface switching, and hardware feature toggles. Nothing else calls `XRInterface::initialize()`, so most XR graphs begin here. The canonical init wiring:

```
Always -> State Gate(state 0 = "needs init") -> XR Session(Initialize) -> State(remove 0)
```

## Reading the player

There are three input listeners, each consolidating what used to be many bricks:

**[XR Input](../reference/generated/listeners/xr_input_listener.md)** — one brick for every controller across Quest, Vive, Index, and others: buttons, triggers, grips, joysticks, and pose. Select the source via mode; irrelevant properties auto-hide.
**[XR Tracking](../reference/generated/listeners/xr_tracking_listener.md)** — spatial, skeletal, and biometric state. The `tracking_source` mode picks the domain: hand gestures, skeletal joints, facial expression, body pose, or boundary/object proximity.
**[XR Ray](../reference/generated/listeners/xr_ray_listener.md)** — spatial raycasting from a controller or HMD for pointer interaction and teleport targeting, in straight-line or parabolic-arc mode, exposing hit point, normal, and collider.

```
XR Input(source=RightTrigger, On Press) -> AND -> XR Interaction(grab)
XR Ray(source=RightHand, mode=Arc)      -> AND -> XR Movement(teleport)
```

## Filtering with the XR gate

**[XR Gate](../reference/generated/gates/xr_gate.md)** is a pure boolean filter for XR conditions — gesture recognition and tracking confidence — with no state mutation or spatial queries (those moved into the executors below as built-in pre-validation).

![XR Tracking detecting a Thumbs Up hand gesture, through an XR Gate that requires high tracking confidence, into an XR Haptic pulse](https://gdlink.solventech.ca/guide/assets/images/gdlink-assembly-xr.png)

## Moving and interacting

**[XR Movement](../reference/generated/executors/xr_movement_executor.md)** is the XR analog of Motion3D — it moves the `XROrigin3D` for every locomotion paradigm: teleport, smooth slide, snap/continuous turn, climb, and flight, with comfort vignette tied to velocity. Teleport's slope/fit/collision checks are built in.

**[XR Interaction](../reference/generated/executors/xr_interaction_executor.md)** handles hand-to-object and hand-to-UI: grabbing, throwing, poking, UI pointing, and AR anchors, with grab weight/lock/distance validation absorbed as pre-checks.

**[XR Haptic](../reference/generated/executors/xr_haptic_executor.md)** triggers controller vibration — a standalone brick for performance, since haptics fire in tight loops during grab feedback, UI hover, and impacts.

```
XR Input(grip, While Held) -> AND -> XR Interaction(grab, hand=Left)
Collision(group=Wall)      -> AND -> XR Haptic(pattern=Bump, hand=Left)
```

## Embodiment and mixed reality

**[XR Avatar](../reference/generated/executors/xr_avatar_executor.md)** drives skeletal and blend-shape data from trackers onto visual meshes — hand-skeleton animation, full-body IK, and facial expression — all following the same read-tracker, write-target pattern.

**[XR Passthrough](../reference/generated/executors/xr_passthrough_executor.md)** controls mixed-reality passthrough: camera-feed overlay, alpha blending, and edge enhancement for blended AR/MR scenes.

## Putting it together — a basic VR loop

```
Always                      -> State Gate(needs init) -> XR Session(Initialize) -> State(remove)
XR Tracking(Hand skeleton)  -> AND -> XR Avatar(hands)
XR Input(grip, While Held)  -> AND -> XR Interaction(grab)
XR Ray(Arc) + XR Input(A)   -> AND -> XR Movement(teleport)
```

Initialize once, mirror the hands, grab on grip, teleport on a ray — a complete interaction loop with five bricks.

## Where to go next

- The full [Logic Reference](../reference/index.md) for every XR brick
- The **3D** guide — XR builds on the same `Node3D` movement and sensing bricks
- The **Debugging** guide for proving XR graphs before putting on the headset