---
generated_by: gdlink-build
generated_at: 2026-09-05T21:52:52Z
do_not_edit: true
title: XR Player Body
brick_type: executor
tier: Pro
generated: true
---

# XR Player Body

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

## Purpose

Gives the XR player real physics by driving a CharacterBody3D that is reconciled with the headset camera every physics tick, and writing that body's motion back onto the XROrigin3D.

## Runtime Behavior

**Host**
The node hosting the bricks under `XROrigin3D` (the showcase uses an `XRLogic` child). The
brick resolves the origin by walking up the tree, then finds the body and camera beneath it.

**Rig Requirements**
- `XROrigin3D` with an `XRCamera3D` child.
- A `CharacterBody3D` (default name `PlayerBody`) as a **child of the origin, sibling of the
 camera**, carrying a capsule `CollisionShape3D`.
- On first tick the body is set `top_level`, so it lives in world space and drives the origin
 rather than being dragged by it.

**Per-Tick Sequence**
1. **Self-collision exclusion** — collision exceptions are registered against every
 `PhysicsBody3D` in the player's own rig, re-scanned periodically because controller visuals
 are instanced after startup.
2. **Height calibration** — `height_offset` is applied to the origin as a rate-limited delta.
3. **Crouch** — the capsule is resized from the camera's height above the origin floor.
4. **Body placement** — the body is moved laterally under the camera (`move_and_collide`, Y
 zeroed) so walls block roomscale walking.
5. **Hang / grapple / gravity / locomotion / jump** resolve velocity.
6. `move_and_slide`, then rigid-body push, then the rope constraint.
7. **Reconciliation** — the origin is moved by the body's net movement, magnitude-clamped.

**Properties**

**Resolution**
- **body_path** (NodePath): Explicit path to the `CharacterBody3D`. Wins if set.
- **body_name** (String, default `"PlayerBody"`): Name searched under the origin.

**Movement**
- **move_hand** (Enum, default `"Left"`): Controller supplying locomotion input.

...

```{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 Player Body</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" style="width:auto; max-width:160px; overflow:hidden; text-overflow:ellipsis;">Body Path:</span><div class="real-input" style="flex-grow:0; width:120px; 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; max-width:160px; overflow:hidden; text-overflow:ellipsis;">Body Name:</span><div class="real-input" style="flex-grow:0; width:120px; justify-content:space-between; padding:4px 8px;"><span></span><div class="real-input-dropdown-btn" style="padding:2px 6px;">v</div></div></div></div>
            </div>
        </div>
    </div>
```

## Properties

This brick does not expose a generated property table yet. See the source specification for implementation notes.