XREntity3D
Bind an Entity to a named tracker pose.
XREntity3D receives the selected pose transform. Parent directly under XROrigin3D. A new instance has an empty Tracker, Pose=default and ShowWhenTracked=false. Assign Tracker before Pose: changing tracker normally resets the pose name.
GetIsActive tests pose existence, not data freshness. Tracking loss retains the last transform. GetHasTrackingData stores a cached flag. Confirmed defect: SetPoseName does not refresh it, so selecting a missing pose can retain true. For dynamic selection obtain GetPose(), check for null and inspect the pose’s own HasTrackingData, together with application focus. Do not edit a pose managed by the XR interface.
TrackingChanged reports only cached-flag transitions. ShowWhenTracked requires a primary XR interface. Source updates visibility before storing the new tracking flag; correct device visibility transitions are not established. Gate interactions explicitly by state.
TriggerHapticPulse is a request, not a vibration acknowledgement. Duration is seconds; the current OpenXR path does not apply delaySec. Transforms, pose availability, tracking loss and the selection defect were checked with a synthetic tracker; no engine fix was made. Structure and diagnostics: XR components.
Declarations checked against C# SDK 1.0.0. Expand a name to see declarations and documentation.
Constructors1
XREntity3DConstructor
public XREntity3D();Creates a tracker-bound Entity: Tracker is empty, Pose=default, ShowWhenTracked=false and no current tracking data. Parent under XROrigin3D. Does not start an XR session.
Properties3
PoseProperty
public StringName Pose { get; set; }Selected pose name, initially default; grip or aim when available. The setter copies an existing pose transform but does not refresh GetHasTrackingData. Confirmed defect: selecting a missing pose retains an old true flag. For dynamic selection inspect GetPose() and that pose’s HasTrackingData; configure the name before processing interactions.
ShowWhenTrackedProperty
public bool ShowWhenTracked { get; set; }Tracking-driven visibility policy, initially false. Requires a primary XR interface; otherwise Visible is unchanged. Source updates visibility before storing the new tracking flag, so timely hiding on a device is not established here. Gate interactions by pose and tracking separately; visibility is not a safety check.
TrackerProperty
public StringName Tracker { get; set; }Tracker name, initially empty; for example left_hand or right_hand. Not a numeric ID or resource path. A change unbinds the old tracker, selects the new one and resets Pose to default. An already bound identical tracker is left unchanged. Set Tracker before Pose. A name alone does not establish device connection.
Methods10
GetHasTrackingDatabool
public bool GetHasTrackingData();Returns the cached flag updated by selected-pose events and tracker binding. Data loss sets it false while retaining the previous transform. Pose-selection defect: the setter does not recompute the flag, so it may be stale. For dynamic selection also check GetPose() and the returned pose’s HasTrackingData.
boolCached bool that can be stale after changing Pose until a subsequent update.
GetIsActivebool
public bool GetIsActive();Checks that a tracker and named pose exist. Can remain true after InvalidatePose despite lost tracking. Neither session focus, data freshness nor interaction permission.
booltrue when tracker and pose exist, even after that pose loses tracking.
GetPoseXRPose
public XRPose GetPose();Returns the selected pose object, or null when the tracker/name is unavailable. Tracker state, not a snapshot: tracking loss retains the previous transform. Inspect the pose’s own HasTrackingData; do not edit state fields managed by the XR interface.
XRPoseSelected pose state or null. Data may be retained after tracking loss.
GetPoseNameStringName
public StringName GetPoseName();Returns the configured pose name, initially default. Does not establish pose availability or current data.
StringNameConfigured pose name; initially default.
GetShowWhenTrackedbool
public bool GetShowWhenTracked();Returns ShowWhenTracked, initially false. Neither current Visible nor tracking availability.
boolPolicy setting, initially false; not current visibility.
GetTrackerStringName
public StringName GetTracker();Returns the configured tracker name even when the device is absent. Initially empty; not a numeric ID.
StringNameConfigured tracker name; initially empty.
SetPoseNamevoid
public void SetPoseName(StringName pose);Selected pose name, initially default; grip or aim when available. The setter copies an existing pose transform but does not refresh GetHasTrackingData. Confirmed defect: selecting a missing pose retains an old true flag. For dynamic selection inspect GetPose() and that pose’s HasTrackingData; configure the name before processing interactions.
| Name | Type | Default |
|---|---|---|
pose | StringName | — |
poseTracker pose name, such as grip; check availability separately. The setter does not refresh the tracking cache.
SetShowWhenTrackedvoid
public void SetShowWhenTracked(bool show);Tracking-driven visibility policy, initially false. Requires a primary XR interface; otherwise Visible is unchanged. Source updates visibility before storing the new tracking flag, so timely hiding on a device is not established here. Gate interactions by pose and tracking separately; visibility is not a safety check.
| Name | Type | Default |
|---|---|---|
show | bool | — |
showEnable the visibility policy; without a primary XR interface it does not change Visible.
SetTrackervoid
public void SetTracker(StringName trackerName);Tracker name, initially empty; for example left_hand or right_hand. Not a numeric ID or resource path. A change unbinds the old tracker, selects the new one and resets Pose to default. An already bound identical tracker is left unchanged. Set Tracker before Pose. A name alone does not establish device connection.
| Name | Type | Default |
|---|---|---|
trackerName | StringName | — |
trackerNameTracker name, such as left_hand; assign before selecting Pose.
TriggerHapticPulsevoid
public void TriggerHapticPulse(string actionName, double frequency, double amplitude, double durationSec, double delaySec);Forwards a request to the primary XR interface for the configured Tracker. Requires a running session and configured output action. Frequency is Hz, amplitude 0…1, duration and delay are seconds. The current OpenXR path converts duration to nanoseconds but ignores delaySec. Returns no device acknowledgement; physical vibration was not checked here.
| Name | Type | Default |
|---|---|---|
actionName | string | — |
frequency | double | — |
amplitude | double | — |
durationSec | double | — |
delaySec | double | — |
actionNameInternal action name. A vibration request requires a configured output action.
frequencyFrequency in Hz; 0 requests the runtime choice. Validate a finite nonnegative value before calling.
amplitudeFinite amplitude from 0 through 1; this proxy does not guarantee range validation.
durationSecPositive finite duration in seconds; not milliseconds or nanoseconds.
delaySecDelay in seconds. Ignored by the current OpenXR path; use 0 and schedule deferred calls in application logic.
Signals and events1
TrackingChangedEvent
public event XREntity3D.TrackingChangedEventHandler TrackingChanged;Emitted when the cached tracking flag changes; repeated identical states are suppressed. Not a per-pose-frame event, focus event or notification for every Pose assignment. Account for the pose-selection flag defect.
| Name | Type | Default |
|---|---|---|
tracking | bool | — |
trackingNew cached flag value; neither device availability nor focus state.