---
generated_by: gdlink-build
generated_at: 2026-06-23T12:34:28Z
do_not_edit: true
title: XR Avatar
brick_type: executor
tier: Pro
generated: true
---

# XR Avatar

**Category:** Executor
**Tier:** Pro

## Purpose

Drives skeletal and blend-shape data from XR trackers onto visual meshes.

## Visual Reference

```{raw} html
<div class="illustration-container"><div class="illustration-box"><div class="box-header">As added to your scene</div><img src="https://gdlink.solventech.ca/guide/assets/images/bricks/xr_avatar_executor.png" alt="XR Avatar brick as it appears in the GDLink editor" loading="lazy" style="max-width:100%;height:auto;display:block;margin:0 auto;border-radius:8px;" /></div></div>
```

## Runtime Behavior

**Inputs**
- **Activate** (Boolean): When true, continuously drive the target skeleton/mesh from tracker data each tick.

**Properties**

**Core (always visible)**
- **avatar_target** (Enum, default `"Hand"`): `Hand`, `Body`, `Face`
- **update_frequency** (Enum, default `"Every Frame"`): `Every Frame`, `Physics Tick`

**Hand Mode (`visible_if: {avatar_target: "Hand"}`)**
- **tracker_hand** (Enum): `Left`, `Right`
- **target_skeleton** (NodePath): Path to Skeleton3D node.
- **hide_when_lost** (Bool, default `true`): Hide hand mesh when tracking is lost.
- **bone_update** (Enum, default `"Full"`): `Full` (position + rotation), `Rotation Only`

**Body Mode (`visible_if: {avatar_target: "Body"}`)**
- **tracker_name** (String, default `"PrimaryBody"`): XRBodyTracker name.
- **target_skeleton** (NodePath): Path to Skeleton3D node.
- **selective_tracking** (Flags, default `Full`): `Full`, `Upper Body`, `Lower Body`, `Hands Only`
- **bone_update** (Enum, default `"Full"`): `Full`, `Rotation Only`

**Face Mode (`visible_if: {avatar_target: "Face"}`)**
- **face_tracker** (String, default `"PrimaryFace"`): XRFaceTracker name.
- **target_mesh** (NodePath): Path to MeshInstance3D with blend shapes.
- **face_mapping** (Enum, default `"Auto-Map"`): `Auto-Map` (match blend shape names), `Manual` (explicit mapping table)

---

```{raw} html
<div class="illustration-container">
        <div class="illustration-box">
            <div class="box-header">Generated UI Mockup — showing expanded properties</div>
            <div class="real-node brick-executor">
                <div class="real-header">
                    <div class="real-title"><span class="brick-icon-fallback"></span> <span>XR Avatar</span></div>
                    <div class="real-controls"><div class="real-checkbox"></div><div class="real-btn">-</div><div class="real-btn">x</div></div>
                </div>
                <div class="real-inner-panel"><div class="real-row name-row" style="position:relative;"><span class="real-label">Name:</span><div class="real-input" style="color:#666; font-style:italic;">Label this brick...</div><div class="real-port" style="left:-15px;"></div></div><div class="real-row"><span class="real-label">Target:</span><div class="real-input-dropdown">Hand</div></div><div class="real-row"><span class="real-label">Update:</span><div class="real-input-dropdown">Every Frame</div></div><div class="real-row"><span class="real-label" style="width: auto; padding-right:8px;">Skeleton:</span><div class="real-input" style="justify-content:space-between; padding:4px 8px;"><span></span><div class="real-input-dropdown-btn" style="padding:2px 6px;">v</div></div></div><div class="real-row"><span class="real-label">Bones:</span><div class="real-input-dropdown">Full</div></div><div class="real-row"><span class="real-label" style="width: auto; padding-right:8px;">Tracker:</span><div class="real-input" style="justify-content:space-between; padding:4px 8px;"><span>PrimaryBody</span><div class="real-input-dropdown-btn" style="padding:2px 6px;">v</div></div></div><div class="real-row"><span class="real-label" style="width: auto; padding-right:8px;">Skeleton:</span><div class="real-input" style="justify-content:space-between; padding:4px 8px;"><span></span><div class="real-input-dropdown-btn" style="padding:2px 6px;">v</div></div></div><div class="real-row"><span class="real-label" style="width: auto; padding-right:8px;">Tracker:</span><div class="real-input" style="justify-content:space-between; padding:4px 8px;"><span>PrimaryFace</span><div class="real-input-dropdown-btn" style="padding:2px 6px;">v</div></div></div><div class="real-row"><span class="real-label" style="width: auto; padding-right:8px;">Mesh:</span><div class="real-input" style="justify-content:space-between; padding:4px 8px;"><span></span><div class="real-input-dropdown-btn" style="padding:2px 6px;">v</div></div></div><div class="real-row"><span class="real-label">Mapping:</span><div class="real-input-dropdown">Auto-Map</div></div><div class="real-inline-row" style="margin-top:4px;"><span class="real-inline-label">Hand</span><div class="real-inline-dropdown">Right</div><div class="real-inline-btn" style="background:#2f5c2f;">Hide Lost</div></div><div class="real-inline-row" style="margin-top:4px;"><span class="real-inline-label">Region</span><div class="real-inline-dropdown">Full</div><span class="real-inline-label">Bones</span><div class="real-inline-dropdown">Full</div></div></div>
            </div>
        </div>
    </div>
```

## Properties

| Property | Type | Default | Notes |
|---|---|---|---|
| Target | option | Hand | Avatar driving mode |
| Update | option | Every Frame | How often to sync tracker data |
| Hand | option | Right | Which hand to drive |
| Skeleton | string |  | Path to Skeleton3D node |
| Hide Lost | bool | True | Hide hand mesh when tracking is lost |
| Bones | option | Full | Full transform or rotation only |
| Tracker | string | PrimaryBody | XRBodyTracker name |
| Skeleton | string |  | Path to Skeleton3D node |
| Region | option | Full | Body regions to drive |
| Bones | option | Full | Full transform or rotation only |
| Tracker | string | PrimaryFace | XRFaceTracker name |
| Mesh | string |  | Path to MeshInstance3D with blend shapes |
| Mapping | option | Auto-Map | Auto-Map: match blend shape names. Manual: explicit table |