XR components: hand visuals and external packages

XR support provides tracking, poses and controller input. It does not automatically implement grabbing, teleportation, animated hands or interaction with menus. Build those mechanics on a working rig or integrate a separately verified package. This page does not require a toolkit download.

Start with a working rig

Complete XR setup and startup handling. Confirm an image in the headset and correct focus handling before adding interaction code.

Keep tracked entities directly under XROrigin3D. Put artwork under the corresponding controller:

XROrigin3D
├── XRCamera3D
├── XRController3D (left_hand, grip)
│   └── Entity3D (visual offset)
│       └── MeshInstance3D
└── XRController3D (right_hand, grip)
    └── Entity3D (visual offset)
        └── MeshInstance3D

Set Tracker first, then Pose: changing Tracker resets Pose to default. For the left controller use left_hand, for the right use right_hand; select grip for a held-object visual. These are tracker/pose names, not resource filenames. Use an available aim pose for a pointing direction when the configured action map and runtime provide it.

Adjust the visual child's local transform to fit your model. Do not move the tracked controller every frame to correct a model offset: pose updates replace its local transform. A MeshInstance3D is enough to test placement; a skinned hand additionally needs a model, skeleton and animation logic. Parenting a mesh does not provide finger tracking or collision.

Connect input to a mechanic

Create the required action map. Read actions by their exact internal names through IsButtonPressed or GetVector2. A Boolean select action can drive selection; a Vector2 movement action requires suitable bindings for the intended controller profiles. The minimal Simple Controller selection map does not supply thumbsticks.

Separate three conditions:

After pose loss the controller can retain its last transform and GetIsActive() can remain true. Stop spatial interaction when tracking is invalid; do not treat a stationary visual as evidence of valid tracking. Without a tracker, input reads return neutral values, which alone cannot distinguish disconnection from a released control. ShowWhenTracked changes visibility only when a primary XR interface exists; implement interaction gating independently.

For player collision and origin ownership, continue with room scale. A visual hand does not establish a player collider or prevent the physical head from crossing virtual geometry.

Dynamic Pose selection has a confirmed defect: SetPoseName does not recompute GetHasTrackingData(), so selecting a missing pose can retain true. Obtain GetPose(), check for null and inspect that pose’s own HasTrackingData. Prefer configuring Tracker and Pose before input processing. Check application focus separately.

Integrate an external package

Before adding a package, record its actual release, license, supported Reckfell API and dependencies. Test it in a copy of the working project. Do not assume a similarly named package or an advertised engine version matches the renamed Entity API and resource formats.

Use the package's real files and installation instructions. An editor plugin has plugin.cfg; importing models or a runtime prefab alone does not necessarily require enabling an editor plugin. Script-load errors need diagnosis: check the first error, missing types and paths, then dependencies. They are not a normal successful installation result.

Run the same baseline with and without the package: startup, both controller poses, tracking loss/recovery, input, focus loss and exported build. Keep one owner for locomotion and player collision; two controllers moving the origin cause conflicting movement. If the package cannot pass this baseline, keep the working rig and integrate only the required mechanic.

What was checked

Twelve checks on the installed Windows runtime used a synthetic XRControllerTracker: pose propagation, child transforms, named input, lost tracking, tracker changes and removal. They do not prove real headset tracking, model quality, a third-party package, editor installation or an exported build. No package download or universal XR Tools bundle is established by this guide.