Provide generic interface for XR hand tracking

3 files changed, 305 insertions, 0 deletions

diff --git a/doc/classes/XRHandModifier3D.xml b/doc/classes/XRHandModifier3D.xml
new file mode 100644
index 0000000000..7e08d3f687
--- /dev/null
+++ b/doc/classes/XRHandModifier3D.xml
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="XRHandModifier3D" inherits="Node3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		A node for driving hand meshes from [XRHandTracker] data.
+	</brief_description>
+	<description>
+		This node uses hand tracking data from a [XRHandTracker] to animate the skeleton of a hand mesh.
+	</description>
+	<tutorials>
+		<link title="XR documentation index">$DOCS_URL/tutorials/xr/index.html</link>
+	</tutorials>
+	<members>
+		<member name="bone_update" type="int" setter="set_bone_update" getter="get_bone_update" enum="XRHandModifier3D.BoneUpdate" default="0">
+			Specifies the type of updates to perform on the bones.
+		</member>
+		<member name="hand_tracker" type="StringName" setter="set_hand_tracker" getter="get_hand_tracker" default="&amp;&quot;/user/left&quot;">
+			The name of the [XRHandTracker] registered with [XRServer] to obtain the hand tracking data from.
+		</member>
+		<member name="target" type="NodePath" setter="set_target" getter="get_target" default="NodePath(&quot;&quot;)">
+			A [NodePath] to a [Skeleton3D] to animate.
+		</member>
+	</members>
+	<constants>
+		<constant name="BONE_UPDATE_FULL" value="0" enum="BoneUpdate">
+			The skeleton's bones are fully updated (both position and rotation) to match the tracked bones.
+		</constant>
+		<constant name="BONE_UPDATE_ROTATION_ONLY" value="1" enum="BoneUpdate">
+			The skeleton's bones are only rotated to align with the tracked bones, preserving bone length.
+		</constant>
+		<constant name="BONE_UPDATE_MAX" value="2" enum="BoneUpdate">
+			Represents the size of the [enum BoneUpdate] enum.
+		</constant>
+	</constants>
+</class>
diff --git a/doc/classes/XRHandTracker.xml b/doc/classes/XRHandTracker.xml
new file mode 100644
index 0000000000..932fec083a
--- /dev/null
+++ b/doc/classes/XRHandTracker.xml
@@ -0,0 +1,223 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="XRHandTracker" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		A tracked hand in XR.
+	</brief_description>
+	<description>
+		A hand tracking system will create an instance of this object and add it to the [XRServer]. This tracking system will then obtain skeleton data, convert it to the Godot Humanoid hand skeleton and store this data on the [XRHandTracker] object.
+		Use [XRHandModifier3D] to animate a hand mesh using hand tracking data.
+	</description>
+	<tutorials>
+		<link title="XR documentation index">$DOCS_URL/tutorials/xr/index.html</link>
+	</tutorials>
+	<methods>
+		<method name="get_hand_joint_angular_velocity" qualifiers="const">
+			<return type="Vector3" />
+			<param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" />
+			<description>
+				Returns the angular velocity for the given hand joint.
+			</description>
+		</method>
+		<method name="get_hand_joint_flags" qualifiers="const">
+			<return type="int" enum="XRHandTracker.HandJointFlags" is_bitfield="true" />
+			<param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" />
+			<description>
+				Returns flags about the validity of the tracking data for the given hand joint (see [enum XRHandTracker.HandJointFlags]).
+			</description>
+		</method>
+		<method name="get_hand_joint_linear_velocity" qualifiers="const">
+			<return type="Vector3" />
+			<param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" />
+			<description>
+				Returns the linear velocity for the given hand joint.
+			</description>
+		</method>
+		<method name="get_hand_joint_radius" qualifiers="const">
+			<return type="float" />
+			<param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" />
+			<description>
+				Returns the radius of the given hand joint.
+			</description>
+		</method>
+		<method name="get_hand_joint_transform" qualifiers="const">
+			<return type="Transform3D" />
+			<param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" />
+			<description>
+				Returns the transform for the given hand joint.
+			</description>
+		</method>
+		<method name="set_hand_joint_angular_velocity">
+			<return type="void" />
+			<param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" />
+			<param index="1" name="angular_velocity" type="Vector3" />
+			<description>
+				Sets the angular velocity for the given hand joint.
+			</description>
+		</method>
+		<method name="set_hand_joint_flags">
+			<return type="void" />
+			<param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" />
+			<param index="1" name="flags" type="int" enum="XRHandTracker.HandJointFlags" is_bitfield="true" />
+			<description>
+				Sets flags about the validity of the tracking data for the given hand joint.
+			</description>
+		</method>
+		<method name="set_hand_joint_linear_velocity">
+			<return type="void" />
+			<param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" />
+			<param index="1" name="linear_velocity" type="Vector3" />
+			<description>
+				Sets the linear velocity for the given hand joint.
+			</description>
+		</method>
+		<method name="set_hand_joint_radius">
+			<return type="void" />
+			<param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" />
+			<param index="1" name="radius" type="float" />
+			<description>
+				Sets the radius of the given hand joint.
+			</description>
+		</method>
+		<method name="set_hand_joint_transform">
+			<return type="void" />
+			<param index="0" name="joint" type="int" enum="XRHandTracker.HandJoint" />
+			<param index="1" name="transform" type="Transform3D" />
+			<description>
+				Sets the transform for the given hand joint.
+			</description>
+		</method>
+	</methods>
+	<members>
+		<member name="hand" type="int" setter="set_hand" getter="get_hand" enum="XRHandTracker.Hand" default="0">
+			The type of hand.
+		</member>
+		<member name="hand_tracking_source" type="int" setter="set_hand_tracking_source" getter="get_hand_tracking_source" enum="XRHandTracker.HandTrackingSource" default="0">
+			The source of the hand tracking data.
+		</member>
+		<member name="has_tracking_data" type="bool" setter="set_has_tracking_data" getter="get_has_tracking_data" default="false">
+			If [code]true[/code], the hand tracking data is valid.
+		</member>
+	</members>
+	<constants>
+		<constant name="HAND_LEFT" value="0" enum="Hand">
+			A left hand.
+		</constant>
+		<constant name="HAND_RIGHT" value="1" enum="Hand">
+			A right hand.
+		</constant>
+		<constant name="HAND_MAX" value="2" enum="Hand">
+			Represents the size of the [enum Hand] enum.
+		</constant>
+		<constant name="HAND_TRACKING_SOURCE_UNKNOWN" value="0" enum="HandTrackingSource">
+			The source of hand tracking data is unknown.
+		</constant>
+		<constant name="HAND_TRACKING_SOURCE_UNOBSTRUCTED" value="1" enum="HandTrackingSource">
+			The source of hand tracking data is unobstructed, meaning that an accurate method of hand tracking is used. These include optical hand tracking, data gloves, etc.
+		</constant>
+		<constant name="HAND_TRACKING_SOURCE_CONTROLLER" value="2" enum="HandTrackingSource">
+			The source of hand tracking data is a controller, meaning that joint positions are inferred from controller inputs.
+		</constant>
+		<constant name="HAND_TRACKING_SOURCE_MAX" value="3" enum="HandTrackingSource">
+			Represents the size of the [enum HandTrackingSource] enum.
+		</constant>
+		<constant name="HAND_JOINT_PALM" value="0" enum="HandJoint">
+			Palm joint.
+		</constant>
+		<constant name="HAND_JOINT_WRIST" value="1" enum="HandJoint">
+			Wrist joint.
+		</constant>
+		<constant name="HAND_JOINT_THUMB_METACARPAL" value="2" enum="HandJoint">
+			Thumb metacarpal joint.
+		</constant>
+		<constant name="HAND_JOINT_THUMB_PHALANX_PROXIMAL" value="3" enum="HandJoint">
+			Thumb phalanx proximal joint.
+		</constant>
+		<constant name="HAND_JOINT_THUMB_PHALANX_DISTAL" value="4" enum="HandJoint">
+			Thumb phalanx distal joint.
+		</constant>
+		<constant name="HAND_JOINT_THUMB_TIP" value="5" enum="HandJoint">
+			Thumb tip joint.
+		</constant>
+		<constant name="HAND_JOINT_INDEX_FINGER_METACARPAL" value="6" enum="HandJoint">
+			Index finger metacarpal joint.
+		</constant>
+		<constant name="HAND_JOINT_INDEX_FINGER_PHALANX_PROXIMAL" value="7" enum="HandJoint">
+			Index finger phalanx proximal joint.
+		</constant>
+		<constant name="HAND_JOINT_INDEX_FINGER_PHALANX_INTERMEDIATE" value="8" enum="HandJoint">
+			Index finger phalanx intermediate joint.
+		</constant>
+		<constant name="HAND_JOINT_INDEX_FINGER_PHALANX_DISTAL" value="9" enum="HandJoint">
+			Index finger phalanx distal joint.
+		</constant>
+		<constant name="HAND_JOINT_INDEX_FINGER_TIP" value="10" enum="HandJoint">
+			Index finger tip joint.
+		</constant>
+		<constant name="HAND_JOINT_MIDDLE_FINGER_METACARPAL" value="11" enum="HandJoint">
+			Middle finger metacarpal joint.
+		</constant>
+		<constant name="HAND_JOINT_MIDDLE_FINGER_PHALANX_PROXIMAL" value="12" enum="HandJoint">
+			Middle finger phalanx proximal joint.
+		</constant>
+		<constant name="HAND_JOINT_MIDDLE_FINGER_PHALANX_INTERMEDIATE" value="13" enum="HandJoint">
+			Middle finger phalanx intermediate joint.
+		</constant>
+		<constant name="HAND_JOINT_MIDDLE_FINGER_PHALANX_DISTAL" value="14" enum="HandJoint">
+			Middle finger phalanx distal joint.
+		</constant>
+		<constant name="HAND_JOINT_MIDDLE_FINGER_TIP" value="15" enum="HandJoint">
+			Middle finger tip joint.
+		</constant>
+		<constant name="HAND_JOINT_RING_FINGER_METACARPAL" value="16" enum="HandJoint">
+			Ring finger metacarpal joint.
+		</constant>
+		<constant name="HAND_JOINT_RING_FINGER_PHALANX_PROXIMAL" value="17" enum="HandJoint">
+			Ring finger phalanx proximal joint.
+		</constant>
+		<constant name="HAND_JOINT_RING_FINGER_PHALANX_INTERMEDIATE" value="18" enum="HandJoint">
+			Ring finger phalanx intermediate joint.
+		</constant>
+		<constant name="HAND_JOINT_RING_FINGER_PHALANX_DISTAL" value="19" enum="HandJoint">
+			Ring finger phalanx distal joint.
+		</constant>
+		<constant name="HAND_JOINT_RING_FINGER_TIP" value="20" enum="HandJoint">
+			Ring finger tip joint.
+		</constant>
+		<constant name="HAND_JOINT_PINKY_FINGER_METACARPAL" value="21" enum="HandJoint">
+			Pinky finger metacarpal joint.
+		</constant>
+		<constant name="HAND_JOINT_PINKY_FINGER_PHALANX_PROXIMAL" value="22" enum="HandJoint">
+			Pinky finger phalanx proximal joint.
+		</constant>
+		<constant name="HAND_JOINT_PINKY_FINGER_PHALANX_INTERMEDIATE" value="23" enum="HandJoint">
+			Pinky finger phalanx intermediate joint.
+		</constant>
+		<constant name="HAND_JOINT_PINKY_FINGER_PHALANX_DISTAL" value="24" enum="HandJoint">
+			Pinky finger phalanx distal joint.
+		</constant>
+		<constant name="HAND_JOINT_PINKY_FINGER_TIP" value="25" enum="HandJoint">
+			Pinky finger tip joint.
+		</constant>
+		<constant name="HAND_JOINT_MAX" value="26" enum="HandJoint">
+			Represents the size of the [enum HandJoint] enum.
+		</constant>
+		<constant name="HAND_JOINT_FLAG_ORIENTATION_VALID" value="1" enum="HandJointFlags" is_bitfield="true">
+			The hand joint's orientation data is valid.
+		</constant>
+		<constant name="HAND_JOINT_FLAG_ORIENTATION_TRACKED" value="2" enum="HandJointFlags" is_bitfield="true">
+			The hand joint's orientation is actively tracked. May not be set if tracking has been temporarily lost.
+		</constant>
+		<constant name="HAND_JOINT_FLAG_POSITION_VALID" value="4" enum="HandJointFlags" is_bitfield="true">
+			The hand joint's position data is valid.
+		</constant>
+		<constant name="HAND_JOINT_FLAG_POSITION_TRACKED" value="8" enum="HandJointFlags" is_bitfield="true">
+			The hand joint's position is actively tracked. May not be set if tracking has been temporarily lost.
+		</constant>
+		<constant name="HAND_JOINT_FLAG_LINEAR_VELOCITY_VALID" value="16" enum="HandJointFlags" is_bitfield="true">
+			The hand joint's linear velocity data is valid.
+		</constant>
+		<constant name="HAND_JOINT_FLAG_ANGULAR_VELOCITY_VALID" value="32" enum="HandJointFlags" is_bitfield="true">
+			The hand joint's angular velocity data is valid.
+		</constant>
+	</constants>
+</class>
diff --git a/doc/classes/XRServer.xml b/doc/classes/XRServer.xml
index f98c1d66a4..09e14f1b21 100644
--- a/doc/classes/XRServer.xml
+++ b/doc/classes/XRServer.xml
@@ -18,6 +18,14 @@
 				Registers a new [XRFaceTracker] that tracks the blend shapes of a face.
 			</description>
 		</method>
+		<method name="add_hand_tracker">
+			<return type="void" />
+			<param index="0" name="tracker_name" type="StringName" />
+			<param index="1" name="hand_tracker" type="XRHandTracker" />
+			<description>
+				Registers a new [XRHandTracker] that tracks the joints of a hand.
+			</description>
+		</method>
 		<method name="add_interface">
 			<return type="void" />
 			<param index="0" name="interface" type="XRInterface" />
@@ -71,6 +79,19 @@
 				Returns a dictionary of the registered face trackers. Each element of the dictionary is a tracker name mapping to the [XRFaceTracker] instance.
 			</description>
 		</method>
+		<method name="get_hand_tracker" qualifiers="const">
+			<return type="XRHandTracker" />
+			<param index="0" name="tracker_name" type="StringName" />
+			<description>
+				Returns the [XRHandTracker] with the given tracker name.
+			</description>
+		</method>
+		<method name="get_hand_trackers" qualifiers="const">
+			<return type="Dictionary" />
+			<description>
+				Returns a dictionary of the registered hand trackers. Each element of the dictionary is a tracker name mapping to the [XRHandTracker] instance.
+			</description>
+		</method>
 		<method name="get_hmd_transform">
 			<return type="Transform3D" />
 			<description>
@@ -123,6 +144,13 @@
 				Removes a registered [XRFaceTracker].
 			</description>
 		</method>
+		<method name="remove_hand_tracker">
+			<return type="void" />
+			<param index="0" name="tracker_name" type="StringName" />
+			<description>
+				Removes a registered [XRHandTracker].
+			</description>
+		</method>
 		<method name="remove_interface">
 			<return type="void" />
 			<param index="0" name="interface" type="XRInterface" />
@@ -171,6 +199,26 @@
 				Emitted when an existing face tracker is updated.
 			</description>
 		</signal>
+		<signal name="hand_tracker_added">
+			<param index="0" name="tracker_name" type="StringName" />
+			<param index="1" name="hand_tracker" type="XRHandTracker" />
+			<description>
+				Emitted when a new hand tracker is added.
+			</description>
+		</signal>
+		<signal name="hand_tracker_removed">
+			<param index="0" name="tracker_name" type="StringName" />
+			<description>
+				Emitted when a hand tracker is removed.
+			</description>
+		</signal>
+		<signal name="hand_tracker_updated">
+			<param index="0" name="tracker_name" type="StringName" />
+			<param index="1" name="hand_tracker" type="XRHandTracker" />
+			<description>
+				Emitted when an existing hand tracker is updated.
+			</description>
+		</signal>
 		<signal name="interface_added">
 			<param index="0" name="interface_name" type="StringName" />
 			<description>