PhysicsHandBone

• Script that derives from HandBone and represent a hand bone for a PhysicsHandSkeleton

• It is abstract and requires implementation for the method that should move it towards target pose

Public methods

abstract void MoveToPose(in PhysicsHandBonePose pose, float scale, float oneOverScale, float deltaTime, float oneOverDeltaTime)

• Called by the PhysicsHandSkeleton the bone is added to from the skeleton's FixedUpdate

• Implementation of this method should move the hand bone to the pose specified by the first method parameter. This is a struct that contains all the relevant pose data, such as the bone's target absolute pose and target relative pose as well as its target parent bone pose etc

• The rest of the method parameters specify target scale of the bone's hand and time passed since the last frame (which will under default circumstances correspond to Unity's fixed delta time) as well as their reciprocal values

• This method is not called by the PhysicsHandSkeleton if it does not have a pose provider assigned

• It is also not called in edit mode

virtual void UpdateState()

• Called by the PhysicsHandSkeleton the bone is added to before the MoveToPose is called in case the PhysicsHandBone needs to update certain internal state before its pose updating logic is executed

• This method is called by the bone's PhysicsHandSkeleton even if there is no pose provider assigned for it and in edit mode as well

PhysicsBodyHandBone

• Base class for a physics hand bone that can be queried for a physics body component

• It derives from PhysicsHandBone and defines one additional public abstract method:

abstract void GetBody(out Rigidbody rigidBody, out ArticulationBody articulationBody)

• It assigns the bone's physics body component to the corresponding output reference, it is expected that the bone will have either a Rigidbody or an ArticulationBody associated, but never both

• This script is used in OctoXR as an auxiliary base type for other more specific physics hand bones

PhysicsJointHandBone

• Base class for a physics hand bone that uses a physics joint to connect itself with its parent bone from the same HandSkeleton the bone is added to

• It is abstract, inherits from the PhysicsBodyHandBone and adds one public abstract method:

abstract Joint GetJoint()

• Implementing behaviours should return a reference to the physics joint component that is used to connect the bone to its parent physics bone

• This script is used in OctoXR as a common base class for other more specific physics joint based hand bones, since it encapsulates certain common functionality that is used by physics hand bones with any type of joint

• The common functionality it encapsulates is related to configuring some common properties of a physics joint used by the bone as well as its child bones, such as setting up joint anchors. This functionality is executed each time the bone is added to a hand skeleton or removed from one

PhysicsJointMovableHandBone

• Abstract script that inherits from PhysicsJointHandBone, but it adds certain properties that specify options to use for moving the bone to target poses

• Properties it defines are:

PhysicsBodyMoveOption LinearMove { get; set; }

• Specifies in what way should the bone's position change to follow target positions - it can be by setting the bone's physics body velocity, setting the bone's physics body position directly (e.g. using Rigidbody.MovePosition method), by using the bone's joint (its drives, motors or other) or it can be set to None to specify no movement

PhysicsBodyMoveOption AngularMove { get; set; }

• Specifies the same set of options as LinearMove, but for rotating the bone towards target rotations

RigidBodyHandBone

• Physics hand bone script that requires a Rigidbody attached to the same object it is attached to, it moves to target poses by manipulating properties of its Rigidbody component

• Although RigidBodyHandBone inherits from PhysicsJointMoveableHandBone, it does not support Joint options for moving to target poses and it does not require a Joint component

• The required GetJoint method inherited from PhysicsJointHandBone returns a Joint that might be attached to the same GameObject that the RigidBodyHandBone is attached to, so this joint, if there is one, can still be used to connect the RigidBodyHandBone to its parent bone, but it will never be used by it in any other meaningful way

• Specifying Joint option for its LinearMove/AngularMove will have the same effect as specifying None

RigidBodyJointHandBone

• This script serves as the base class for all physics hand bones that require a Joint component along with Rigidbody

• It is abstract and generic, its type parameter (TJoint) is restricted to inherit from UnityEngine.Joint and it specifies which exact type of Joint the bone requires

• This script is intended for physics hand bones that require a Joint for connecting itselves to their parent bones in the same hand skeleton they are added to, but that don't necessarily intend to move to target poses by using their Joints, i.e. they don't want to support Joint option for Linear/Angular Move, they just want a Joint component for additional stability and restriction

RigidBodyConfigurableJointHandBone

• This scripts defines a hand bone that requires a ConfigurableJoint along with Rigidbody attached to the same GameObject the script is attached to

• It derives from RigidBodyJointHandBone<ConfigurableJoint>

• The ConfigurableJoint is used for connecting the bone to its parent bone and it provides many properties that can be freely configured for additional stability and/or bone rotation limiting or some other needs

RigidBodyJointMovableHandBone

• This script serves as the base class for all physics hand bones that require a Joint component along with Rigidbody, but that also intend to support moving to target poses by using that joint among other options

• It is abstract and generic, its type parameter (TJoint) is restricted to inherit from UnityEngine.Joint and it specifies which exact type of Joint the bone requires

• RigidBodyJointMovableHandBone requires implementation of these two protected methods:

abstract void MoveToPositionUsingJoint(TJoint joint, in PhysicsHandBonePose pose, float scale, float oneOverScale, float deltaTime, float oneOverDeltaTime)

• Moves the physics hand bone to the target position specified by the 'pose' parameter using its Joint, which is specified by the 'joint' parameter - how exactly is this achieved is left to the specific derived physics hand bones to decide, it might be by using joint linear drives or linear motor or by some other means supported by the bone's joint

abstract void MoveToRotationUsingJoint(TJoint joint, in PhysicsHandBonePose pose, float scale, float oneOverScale, float deltaTime, float oneOverDeltaTime)

• Does the same as the previous method, but for physics bone's angular movement, i.e. for moving the bone's rotation

• These two methods are called only if Joint option is used for their corresponding Move property (Linear/Angular)

ConfigurableJointHandBone

• Script that represents a hand bone that requires a ConfigurableJoint along with Rigidbody component, ConfigurableJoint connects the hand bone to its parent bone and it can also move the bone to a target position/rotation

HingeJointHandBone

• Script that represents a hand bone that requires a HingeJoint along with Rigidbody component, HingeJoint connects the hand bone to its parent bone and it can also move the bone to a target position/rotation

• Since this type of physics hand bone uses the HingeJoint, it is restricted to rotate around a single axis of rotation that can be specified by the HingeJointHandBone's Axis property, it can be set to either X, Y or Z and it specifies the bone's local x, y or z axis

• It is fit to represent any finger bone except any of the first phalanges of a finger, since those usually rotate around two axes

ArticulationBodyRotationZXYHandBone

• A special kind of hand bone that requires ArticulationBody attached to the same object it is attached to along with two more articulation bodies, one attached to its parent object and one attached to its parent's parent object

• All three ArticulationBody components are configured by the script to be revolute bodies, the first body, attached to the parent's parent object, is configured to rotate around its local Z axis, the second body, attached to the parent, is configured to rotate around the axis X and final third body rotates around axis Y

• ArticulationBody components in parent objects can be attached by the user before adding the ArticulationBodyRotationZXYHandBone script to a HandSkeleton, otherwise the script will add ones if it determines that it is safe to attach ArticulationBody to each corresponding object. Configuring the bodies is taken care of by the script once it is added to a HandSkeleton

• Once added to a HandSkeleton the script will traverse up its object hierarchy and try and find Articulation bodies to use for rotations around Z and X axes performing certain checks to ensure its state is valid. If there is a Rigidbody attached to a GameObject it cannot be used for rotation around an axis as well as if there is a HandBone attached to the object. If no ArticulationBody is found in a target parent object, but it is determined as safe to have one, the script attaches ArticulationBody and configures it appropriately

• If either of the two required ancestor objects are missing or ArticulationBody cannot be attached to either one of them, ArticulationBodyRotationZXYHandBone will remove itself from the HandSkeleton it is added to

• The reason to have three connected revolute articulation bodies instead of one with spherical joint type in order to rotate an object around three axes is because spherical articulation bodies are notoriously unstable and prone to 'exploding', this is either due to Unity engine itself or perhaps it is a bug in the underlying physics engine (PhysX), but either way revolute bodies appear to be much more stable and with correct behaviour

• This type of HandBone is used in practice for thumb finger's first bone (ThumbFingerMetacarpal), as it is the only one that rotates around axes Z and X with a small range of rotation around axis Y as well

ArticulationBodyRotationZXHandBone

• Another ArticulationBody based hand bone, it is completely equivalent to the previously described ArticulationBodyRotationZXYHandBone, except it requires only two ArtculationBody components, one attached to the same object it is attached to and one attached to its parent object

• ArticulationBody attached to the parent object is used to rotate the bone around axis Z and the one attached to the same object it is attached to rotates the bone around axis X

• The same rules and behaviour that apply to the ArticulationBodyRotationZXYHandBone equivalently apply here when it comes to parent object(s) and required articulation bodies

• This type of HandBone is in practice best used for representing the first phalanx of a finger, with the possible exception of a thumb finger

ArticulationBodyRotationXHandBone

• Like the previous two, ArticulationBodyRotationZXYHandBone and ArticulationBodyRotationZXHandBone, this script represents an ArticulationBody based hand bone, one that rotates around single axis - X

• Since it only depends on one ArticulationBody, it is somewhat simpler than the previously mentioned ones when it comes to its behaviour and requirements. It requires ArticulationBody be attached to the same object it is attached to and it configures that body as a revolute body

• Because it allows rotation around a single axis, it is fit to represent either the second or the third phalanx bone of a finger

ConfigurableJointDrivenPhysicsBodyHandBone

• An abstract base class for a special type of PhysicsHandBone, it is somewhat more complex than all the rest of physics hand bones

• It consists of two GameObjects which are not connected via their Transforms in any way, i.e. they are not in a parent-child relationship via Transform hierarchy

• One GameObject has this script attached (concrete implementation of it to be exact) and it represents an actual hand bone, the other object has a ConfigurableJoint along with Rigidbody and it is connected with the ConfigurableJointDrivenPhysicsBodyHandBone's object via that ConfigurableJoint

• Moving the ConfigurableJointDrivenPhysicsBodyHandBone into target pose is not done by directly manipulating its own physics body or a physics joint, but rather indirectly by moving the connected object into target pose which then causes the hand bone object to be moved towards it as a consequence of ConfigurableJoint acting between the hand bone and the connected object

• Exact way in which the connected object is moved is performed by moving its rigid body directly to a target pose, either via MovePosition/Rotation methods or by setting the linear and angular velocities of the body

• Properties that control the way the connected object gets moved to a target pose are defined in ConfigurableJointDrivenPhysicsBodyHandBone:

PhysicsBodyMoveOption TargetBodyLinearMove { get; set; }

• Specifies how to move the connect object's rigid body to a target position

PhysicsBodyMoveOption TargetBodyAngularMove { get; set; }

• Specifies how to move the connect object's rigid body to a target rotation

• Both properties support two options - either SetVelocity or SetPosition, any other option will cause the connected object's body not be moved at all

• Configuration of the connected object's Rigidbody and its ConfigurableJoint is left to the user, the only thing that the ConfigurableJointDrivenPhysicsBodyHandBone is setting is connected body (Joint.connectedBody and Joint.connectedArticulationBody)

• Usual configuration of ConfigurableJointDrivenPhysicsBodyHandBone used in various prefabs in OctoXR is to set connected object's Rigidbody as kinematic and move it via SetPosition option; ConfigurableJoint is set to have all motions free and use linear and angular drive springs to pull the ConfigurableJointDrivenPhysicsBodyHandBone towards the connected object which is always located at the current target position and rotation

• Creation and management of ConfigurableJointDrivenPhysicsBodyHandBone's connected object is done automatically by the ConfigurableJointDrivenPhysicsBodyHandBone:

  • When ConfigurableJointDrivenPhysicsBodyHandBone is added to a GameObject it will first search all the objects at its own Transform hierarchy level, i.e. its siblings, in order to find one that has PhysicsBodyHandBonePoseDriveTarget script attached and that is not already connected to any other ConfigurableJointDrivenPhysicsBodyHandBone. If such an object is found then it gets reused by the ConfigurableJointDrivenPhysicsBodyHandBone as its new connection

  • If there isn't any object that satisfies the previous criteria, ConfigurableJointDrivenPhysicsBodyHandBone creates and setups one to be its new connected object that will serve as its own pose drive target

  • If the ConfigurableJointDrivenPhysicsBodyHandBone's connected PhysicsBodyHandBonePoseDriveTarget is destroyed then the ConfigurableJointDrivenPhysicsBodyHandBone is destroyed with it. If the ConfigurableJointDrivenPhysicsBodyHandBone is destroyed before its connected PhysicsBodyHandBonePoseDriveTarget then the PhysicsBodyHandBonePoseDriveTarget is disabled and left to be potentially reused later by a new ConfigurableJointDrivenPhysicsBodyHandBone

• ConfigurableJointDrivenPhysicsBodyHandBone is fit represent any hand bone if needed, though throughout OctoXR it is mainly used for wrist root bone

ConfigurableJointDrivenRigidBodyHandBone

• Concrete implementation of previously described ConfigurableJointDrivenPhysicsBodyHandBone

• It requires a Rigidbody and moves to a target pose by being pulled towards its connected object with PhysicsBodyHandBonePoseDriveTarget component, just as described in more detail in the preceding section

ConfigurableJointDrivenArticulationBodyHandBone

• Concrete implementation of previously described ConfigurableJointDrivenPhysicsBodyHandBone

• It requires an ArticulationBody and moves to a target pose by being pulled towards its connected object with PhysicsBodyHandBonePoseDriveTarget component, just as described in more detail in the previous section about ConfigurableJointDrivenPhysicsBodyHandBone