> ## Documentation Index
> Fetch the complete documentation index at: https://docs-unity.molca.id/llms.txt
> Use this file to discover all available pages before exploring further.

# VRPlayerManager

> XR Origin, locomotion providers, and controller visuals.

**Namespace:** `MolcaSDK.VR`\
**File:** `Assets/_MolcaSDK/_VR/Scripts/VRPlayerManager.cs`

Attach to the **XR Origin (XR Rig)** root. Uses a static **`Instance`**; resolves **`VRSubsystem`** after [RuntimeManager](/core/runtime-manager) initialization.

## When to use

Use **`VRPlayerManager`** when you need a single place to:

* Read **player ground position** (`GetGroundPosition` — head XZ with XR Origin Y).
* **Enable or disable all XR Interaction Toolkit locomotion providers** together (teleport, move, snap turn, etc.), e.g. during precision [Grab step](/vr/steps/grab-step) work.
* Access **left/right `VRControllerVisual`** from static properties for haptics or visuals.

## Inspector setup

| Field                                  | Purpose                                                                             |
| -------------------------------------- | ----------------------------------------------------------------------------------- |
| **XROrigin**                           | XR rig; required for ground position.                                               |
| **Player head**                        | Camera / head transform for ground projection and locomotion logic.                 |
| **Left / right controller visual**     | Optional `VRControllerVisual` references.                                           |
| **Auto discover locomotion providers** | When on, finds all **`LocomotionProvider`** under this object (including inactive). |
| **Manual locomotion providers**        | Used when auto-discover is off; assign the providers to toggle.                     |

After **`WaitForInitialization`**, the manager caches providers and sets **`IsLocomotionEnabled`** from the first provider’s enabled state (or false if none).

## Code

**Disable locomotion for a precision step, then restore:**

```csharp theme={null}
using MolcaSDK.VR;
using UnityEngine;

public class LocomotionGate : MonoBehaviour
{
    private VRPlayerManager player;

    private void Awake()
    {
        player = GetComponent<VRPlayerManager>();
        if (player == null)
            player = VRPlayerManager.Instance;
    }

    public void DisableMovement() => player.SetLocomotionEnabled(false);
    public void EnableMovement() => player.SetLocomotionEnabled(true);
    public void ToggleMovement() => player.ToggleLocomotion();
}
```

Listen for **`EventConstants.VR.LocomotionStateChanged`** via [EventDispatcher](/core/event-dispatcher) if other systems need to react (payload type **`LocomotionStateChangedData`**, property **`IsEnabled`**).

## API (key members)

| Member                                                  | Description                                                         |
| ------------------------------------------------------- | ------------------------------------------------------------------- |
| **`Instance`**                                          | Singleton set in `Awake`.                                           |
| **`LeftControllerVisual`**, **`RightControllerVisual`** | Static; null if no instance.                                        |
| **`GetGroundPosition()`**                               | Static; returns `Vector3.zero` if no instance.                      |
| **`IsLocomotionEnabled`**                               | Static; current locomotion flag.                                    |
| **`SetLocomotionEnabled(bool)`**                        | Enables/disables all cached providers; dispatches locomotion event. |
| **`ToggleLocomotion()`**                                | Toggles locomotion.                                                 |
| **`RefreshLocomotionProviders()`**                      | Re-runs discovery or manual list (Context Menu).                    |
| **`GetVRSubsystem()`**                                  | Returns resolved **`VRSubsystem`**.                                 |

## Troubleshooting

* **"Instance not found" / null static access** — Only one **`VRPlayerManager`** should exist on the active rig; `Awake` assigns **`Instance`**. Ensure the rig is active before calling static helpers from arbitrary objects.
* **Locomotion toggle does nothing** — Confirm **`LocomotionProvider`** components live under the same GameObject hierarchy (auto-discover) or are assigned in **manual** list. Check the Console for "No locomotion providers" warnings.
* **`VRSubsystem not found`** — [RuntimeManager](/core/runtime-manager) prefab must include **`VRSubsystem`**; wait until after subsystem init (manager waits in `Start`).
* **Wrong ground height** — **`GetGroundPosition`** uses **`xROrigin.transform.position.y`**; verify **XROrigin** reference and floor / tracking setup.

## Related

* [Scenario activity](/vr/scenario-activity) — broader scenario / VR flow
* [RuntimeManager](/core/runtime-manager) — initialization and **`GetSubsystem`**
* [Grab step](/vr/steps/grab-step) — typical reason to disable locomotion
* [EventDispatcher](/core/event-dispatcher) — locomotion state events

## Unity Editor

<Frame hint="XR Origin root with VRPlayerManager + locomotion components." caption="VRPlayerManager on XR Origin">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/ptmolcateknologinusantara/images/features/vr/vr-player-manager-inspector.png" alt="VRPlayerManager in Unity Inspector" />
</Frame>