UxrGrabbableObject Class

Component that, added to a GameObject, will enable the object to be grabbed by the UxrGrabber components found in the hands of an UxrAvatar. Some of the main features of grabbable objects are:

Manipulation is handled automatically by the UxrGrabManager. There is no special requirement to enable it in a scene, the grab manager will be available as soon as it is invoked.
Grabbable objects can be grabbed, released and placed. Releasing an object means dropping it mid-air, while placing it is releasing an object close enough to a compatible UxrGrabbableObjectAnchor.
Objects can be grabbed from different grab points.
Additionally, grab points can be expanded using UxrGrabPointShape components opening up more complex manipulation by describing grab points as composite shapes.
Although all avatars that have UxrGrabber components are able to interact with UxrGrabbableObject objects, it is possible to register the way specific avatars will interact with it. This allows to specify snap points and poses for different avatars and make sure that all have precise and realistic manipulation.
The Hand Pose Editor can create poses that are used by UxrGrabbableObject in order to tell how objects are grabbed. The inspector window will preview grab poses and enable editing them.
Events such as Grabbed, Released and Placed allow to write logic when a user interacts with the object. Each has pre and post events.
ConstraintsApplying, ConstraintsApplied and ConstraintsFinished allow to program more complex logic when grabbing objects.

Inheritance Hierarchy

System.Object
  Object
    Component
      Behaviour
        MonoBehaviour
          UltimateXR.Core.Components.UxrComponent
            UltimateXR.Core.Components.UxrComponent(UxrGrabbableObject)
              UltimateXR.Manipulation.UxrGrabbableObject
Namespace: UltimateXR.Manipulation
Assembly: UltimateXR (in UltimateXR.dll) Version: 0.0.0.0

Syntax

[DisallowMultipleComponent]
public class UxrGrabbableObject : UxrComponent<UxrGrabbableObject>, 
	IUxrGrabbable

The UxrGrabbableObject type exposes the following members.

Constructors

	Name	Description
	UxrGrabbableObject

Properties

	Name	Description
	AllowMultiGrab	Gets whether the object can be grabbed with more than one hand.
	ControlParentDirection	Gets or sets whether a dependent object can control the grabbable parent’s direction when both are being grabbed at the same time.
	CurrentAnchor	Gets the UxrGrabbableObjectAnchor where the object is actually placed or null if it’s not placed on any.
	DropAlignTransform	Gets the Transform that needs to align with a UxrGrabbableObjectAnchor when placing the object on it.
	DropProximityTransform	Gets the Transform that will be used to compute the distance to UxrGrabbableObjectAnchor components when looking for the closest available to place it.
	DropSnapMode	Gets how the object will align with a UxrGrabbableObjectAnchor when placing it.
	FirstGrabPointIsMain	Gets or sets whether the first grab point in the list is the main grab in objects with more than one grab point. When an object is grabbed with both hands, the main grab controls the actual position while the secondary grab controls the direction. Set it to true in objects like a rifle, where the trigger hand should be the first grab in order to keep the object in place, and the front grab will control the aiming direction. If false, the grab point order is irrelevant and the hand that grabbed the object first will be considered as the main grab.
	GrabbableParentDependency	Gets the Transform that the object is dependent on, when the grabbable object has another above in its hierarchy.
	GrabPointCount	Gets the total number of grab points.
	HasGrabbableParentDependency	Gets if the object has constraints and at the same time has a grabbable parent. This means that the object can either be considered as another grabbable part of the parent object or a separate grabbable object that is just attached to the parent object but has no control over it. The former are movable parts in a composite object while the latter are independent grabbable objects that happen to be in the hierarchy.
	HasRotationConstraint	Gets whether the object has a rotation constraint.
	HasTranslationConstraint	Gets whether the object has a translation constraint.
	HorizontalReleaseMultiplier	Gets the horizontal velocity factor that will be applied to the object when being thrown.
	IgnoreGrabbableParentDependency	Gets or sets whether to ignore the grabbable parent dependency. UsesGrabbableParentDependency.
	IsBeingGrabbed	Gets whether the object is being grabbed.
	IsConstrained	Gets whether the object has translation/rotation constraints.
	IsGrabbable	Gets or sets whether the object can be grabbed.
	IsKinematic	Gets or sets whether the rigidbody that drives the object (if any) is kinematic.
	IsLockedInPlace	Gets or sets whether the object can be moved/rotated. A locked in place object may be grabbed but cannot be moved.
	IsPlaceable	Gets or sets whether the object can be placed on an UxrGrabbableObjectAnchor.
	LimitedRangeOfMotionRotationAxes	Gets the local axes that the object can rotate around with limited range of motion (not freely, nor locked).
	LockedGrabReleaseDistance	Gets the distance that the real hand needs to have to the virtual hand in order for the object grip to be released automatically. This happens when a grabbed object has a range of movement and the grip is pulled too far from a valid position.
	NeedsTwoHandsToRotate	Gets whether the object requires both hands grabbing it in order to rotate it.
	Priority	Gets or sets the object priority. The priority is used to control which object will be grabbed when multiple objects are in reach and the user performs the grab gesture. The default behaviour is to use the distance and orientation to the objects in reach to select the one with the closest grip. The priority can override this behaviour by selecting the one with the highest priority value. By default all objects have priority 0.
	RangeOfMotionRotationAxes	Gets the local axes that the object can rotate around.
	RangeOfMotionRotationAxisCount	Gets the number of axes that the object can rotate around.
	RestrictToBox	Gets or sets the box collider used When TranslationConstraint is RestrictToBox.
	RestrictToSphere	Gets or sets the sphere collider used When TranslationConstraint is RestrictToSphere.
	RigidBodyDynamicOnRelease	Gets whether the object’s RigidBodySource will be made dynamic when the object grip is released.
	RigidBodySource	Specifies the rigidbody component that controls the grabbable object when it is in dynamic (physics-enabled) mode.
	RotationAngleLimitsMax	Gets or sets the rotational maximum limits in local space when RotationConstraint is RestrictLocalRotation.
	RotationAngleLimitsMin	Gets or sets the rotational minimum limits in local space when RotationConstraint is RestrictLocalRotation.
	RotationConstraint	Gets or sets the rotation constraint type.
	RotationLongitudinalAxis	Gets or sets which one is the longitudinal axis (x, y or z) in a rotation with constraints on two or more axes.
	RotationProvider	Gets or sets the rotation provider. The rotation provider is used in objects with constrained position to know which element drives the rotation.
	RotationResistance	Gets or sets the resistance to the object being rotated. This can be used to smooth out the rotation but also to simulate heavy objects.
	SingleRotationAxisDegrees	Gets or sets the rotation angle in degrees for objects that have a single rotational degree of freedom.
	SingleRotationAxisIndex	Gets the index of the rotation axis if the object can only rotate around that single axis. Will return any of these values: (x = 0, y = 1, z = 2, none or more than one = -1).
	StartAnchor	Gets the starting UxrGrabbableObjectAnchor the object is placed on.
	Tag	String that identifies which UxrGrabbableObjectAnchor components are compatible for placement. A UxrGrabbableObject can be placed on an UxrGrabbableObjectAnchor only if: Tag is null or empty and UxrGrabbableObjectAnchor has no compatible tags set Tag has a value that is in one of the compatible tag entries in UxrGrabbableObjectAnchor
	TranslationConstraint	Gets or sets the translation constraint.
	TranslationLimitsMax	Gets or sets the translation maximum limits in local space when TranslationConstraint is RestrictLocalOffset.
	TranslationLimitsMin	Gets or sets the translation minimum limits in local space when TranslationConstraint is RestrictLocalOffset.
	TranslationResistance	Gets or sets the resistance to the object being moved around. This can be used to smooth out the position but also to simulate heavy objects.
	UseParenting	Gets or sets whether to parent the object to the UxrGrabbableObjectAnchor being placed. Also whether to set the parent to null when grabbing the object from one.
	UsesGrabbableParentDependency	Gets whether the object has a parent dependency (HasGrabbableParentDependency is true) and is using it through _ignoreGrabbableParentDependency in the inspector. When a grabbable object that has position/rotation constraints hangs from a hierarchy where another grabbable object is somewhere above, the child grabbable object can either be: Dependent (_ignoreGrabbableParentDependency is false): The object is considered as another part of the parent grabbable object. It will be constrained by its parent object and can optionally also control the parent’s direction when both are being grabbed. Independent (_ignoreGrabbableParentDependency is true): The object is considered as a separate entity where it just happens to be placed under the hierarchy.
	VerticalReleaseMultiplier	Gets the vertical velocity factor that will be applied to the object when being thrown.

Methods

	Name	Description
	Awake	Initializes the object and creates the UxrGrabbableObjectAnchor the object is placed on initially if _autoCreateStartAnchor is set. (Overrides UxrComponent<T>.Awake().)
	CanBeGrabbedByGrabber	Checks whether the object can be grabbed by a UxrGrabber.
	CanBePlacedOnAnchor(UxrGrabbableObjectAnchor)	Checks whether the object is near enough to be placed on the given UxrGrabbableObjectAnchor.
	CanBePlacedOnAnchor(UxrGrabbableObjectAnchor, Single)	Checks whether the object is near enough to be placed on the given UxrGrabbableObjectAnchor.
	CheckAndApplyLockHand	Locks all hands that are currently grabbing the given object using a grab point if necessary. This is used to keep the grips in place after the object has been moved or constrained.
	CheckAndApplyLockHands	Locks all hands that are currently grabbing the object if necessary. This is used to keep the grips in place after the object has been moved or constrained.
	ComputeRequiredGrabberTransform	Computes the position/rotation that a UxrGrabber would have to hold the object using the current position/orientation.
	Editor_CheckRegisterAvatarsInNewGrabPoints	If we add new grab points from the editor, we want to make sure that all avatars are registered in those new entries. This method makes sure that the avatars are registered in all grab points.
	Editor_GetAllRegisteredAvatarGrabAlignTransforms()	Gets all the transforms used for alignment with the registered avatars.
	Editor_GetAllRegisteredAvatarGrabAlignTransforms(UxrAvatar, Boolean, Boolean, Boolean)	Gets all the align transforms of a given registered avatar and hand.
	Editor_GetGrabAlignTransformAvatar	Gets the prefab avatar that is used for the given grip snap transform. If there is more than one the first is returned.
	Editor_GetGrabPointGrabAlignTransform	Gets the Transform used for alignment when the given avatar grabs a point using a given hand.
	Editor_GetGrabPointsForGrabAlignTransform	Gets the grab point indices that use the given Transform for alignment when interacting with an avatar.
	Editor_GetRegisteredAvatarsGuids	Gets the avatar prefab GUIDs that have been registered to have dedicated grip parameters to grab the object.
	Editor_GetSelectedAvatarPrefabForGrips	Gets the editor currently selected avatar prefab whose grip parameters are being edited.
	Editor_GetSelectedAvatarPrefabGuidForGrips	Gets the editor currently selected avatar prefab GUID whose grip parameters are being edited.
	Editor_HasGrabPointWithGrabAlignTransform(Transform)	Checks whether the object has a grab point with the given Transform for alignment.
	Editor_HasGrabPointWithGrabAlignTransform(Transform, GameObject)	Checks whether the object has a grab point with the given Transform for alignment registered using the given prefab.
	Editor_RegisterAvatarForGrips	Registers a new avatar to have grips on this object. If the avatar is an instance it will register its source prefab, otherwise it will register the avatar prefab itself. The reason to register the prefab is so that child prefabs/instances will be able to use the same poses.
	Editor_RemoveAvatarFromGrips	Removes an avatar that was registered for grip poses. If the avatar is an instance it will unregister its source prefab, otherwise it will unregister the avatar prefab itself.
	Editor_SetSelectedAvatarForGrips	Sets the editor currently selected avatar prefab whose grip parameters will be edited.
	EnableAllGrabPoints	Re-enables all disabled grab points by SetGrabPointEnabled(Int32, Boolean).
	GetAutoRotationProvider	Tries to infer the most appropriate UxrRotationProvider to rotate the object based on the shape and size of the object, and the grip.
	GetDistanceFromGrabber	Computes the distance from the object to a UxrGrabber, which is the component found in UxrAvatar hands that are able to grab objects.
	GetGrabPoint	Gets a given grab point information.
	GetMostProbableLongitudinalRotationAxis	Tries to get the longitudinal rotation axis of the grabbable object. If it hasn’t been defined by the user (on objects where RangeOfMotionRotationAxisCount is less than 2.
	OnDisable	Unsubscribes from events. (Overrides UxrComponent<T>.OnDisable().)
	OnEnable	Subscribes to events. (Overrides UxrComponent<T>.OnEnable().)
	PlaceOnAnchor	Places the object on the currently specified anchor by CurrentAnchor.
	ReleaseGrabs	Releases the object from all its grabs if there are any.
	RemoveFromAnchor	Removes the object from the anchor it is placed on, if any.
	Reset	Resets the component. (Overrides UxrComponent.Reset().)
	ResetPositionAndState	Resets the object to its initial position/rotation and state. If the object is currently being grabbed, it will be released.
	SetGrabPointEnabled	Enables or disables the possibility to use the given grab point.
	Start	Performs additional initialization. (Overrides UxrComponent.Start().)

Events

	Name	Description
	ConstraintsApplied	Event called right after applying the position/rotation constraints to the object. This can be used to apply custom constraints to the object.
	ConstraintsApplying	Event called right before applying the position/rotation constraints to the object.
	ConstraintsFinished	Event called right after all ConstraintsApplied finished.
	Grabbed	Event called right after the object was grabbed. The grab event parameters use the same values as Grabbing.
	Grabbing	Event called when the object is about to be grabbed. The following properties from UxrManipulationEventArgs will contain meaningful data: GrabbableObject: Object that is about to be grabbed. GrabbableAnchor: Target where the object is currently placed. Null if it isn’t on an anchor. Grabber: Grabber that is about to grab the object. GrabPointIndex: Grab point index of the object that is about to be grabbed. IsMultiHands: true if it is already being grabbed with one hand and it will be grabbed with both hands after. False if no hand is currently grabbing it.
	Placed	Event called right after the object was placed. An object is placed when the last grip is released and there is a compatible UxrGrabbableObjectAnchor near enough to place it on. The grab event parameters use the same values as Placed.
	Placing	Event called when the object is about to be placed. An object is placed when the last grip is released and there is a compatible UxrGrabbableObjectAnchor near enough to place it on. The following properties from UxrManipulationEventArgs will contain meaningful data: GrabbableObject: Object that is about to be removed. GrabbableAnchor: Anchor where the object is currently placed. Grabber: Grabber that is about to remove the object by grabbing it. This can be null if the object is removed through code using RemoveObjectFromAnchor(UxrGrabbableObject, Boolean), RemoveFromAnchor(Boolean) or RemoveObject(Boolean)> GrabPointIndex: Only if the object is being removed by grabbing it: Grab point index of the object that is about to be grabbed by the UxrGrabber.
	Released	Event called right after the object was released. An object is released when the last grip is released and there is no compatible UxrGrabbableObjectAnchor near enough to place it on. The grab event parameters use the same values as Releasing.
	Releasing	Event called when the object is about to be released. An object is released when the last grip is released and there is no compatible UxrGrabbableObjectAnchor near enough to place it on. The following properties from UxrManipulationEventArgs will contain meaningful data: GrabbableObject: Object that is about to be released. GrabbableAnchor: Anchor where the object was originally grabbed from. Null if it wasn’t on a target. Grabber: Grabber that is about to release the object. GrabPointIndex: Grab point index of the object that is being grabbed by the UxrGrabber. IsMultiHands: true if it is already being grabbed with another hand that will keep it holding. False if no other hand is currently grabbing it. IsSwitchHands: True if it was released because another UxrGrabber grabbed it, false otherwise. if IsMultiHands is true then IsSwitchHands will tell if it was released by both hands (false) or if it was just released by one hand and the other one still keeps it grabbed (true). ReleaseVelocity: Velocity the object is being released with. ReleaseAngularVelocity: Angular velocity the object is being released with.

Fields

	Name	Description
	ConstrainSeconds	Seconds it takes to smoothly transition an object to or from its space constraints.
	DefaultAvatarName	Used by the editor to identify the default avatar when no avatars have been registered for grips.
	DistanceOffsetByAngle	How much a difference in angle will offset the distance at which we compute a grabbable object from a grabber. Objects that are not so well aligned with the grabber will be considered slightly farther away by(angle* DistanceOffsetByAngle) units, this means in the [0, 0.05] range. This will favor grabbing objects that are better aligned when there are two or more at similar distances.
	HandLockSeconds	Seconds it takes to smoothly transition a hand to or from a locked grab (a grab that forces to move the hand bone out of its natural position because the object is constrained in space).
	LeftGrabPoseMeshSuffix	Used by the editor to prefix the left grab pose mesh.
	ObjectAlignmentSeconds	Seconds it takes to smoothly transition an object from/to the hand.
	RightGrabPoseMeshSuffix	Used by the editor to prefix the right grab pose mesh.

Extension Methods

	Name	Description
	CheckSetEnabled	Enables/disabled the component if it isn’t enabled already. (Defined by MonoBehaviourExt.)
	GetOrAddComponent<T>	Gets the Component of a given type. If it doesn’t exist, it is added to the GameObject. (Defined by ComponentExt.)
	GetPathUnderScene	Gets the full path under current scene, including all parents, but scene name, for the given component. (Defined by ComponentExt.)
	GetSceneUid	Gets an unique identifier string for the given component. (Defined by ComponentExt.)
	GetUniqueScenePath	Gets an unique path in the scene for the given component. It will include scene name, sibling and component indices to make it unique. (Defined by ComponentExt.)
	LoopCoroutine	Creates a coroutine that simplifies executing a loop during a certain amount of time. (Defined by MonoBehaviourExt.)
	SafeGetComponentInParent<T>	Gets the Component of a given type in the GameObject or any of its parents. It also works on prefabs, where regular GetComponentInParent(Type, Boolean) will not work: https://issuetracker.unity3d.com/issues/getcomponentinparent-is-returning-null-when-the-gameobject-is-a-prefab (Defined by ComponentExt.)
	ShowInInspector(Boolean)	Overloaded. Controls whether to show the current object in the inspector. (Defined by ObjectExt.)
	ShowInInspector(Boolean, Boolean)	Overloaded. Controls whether to show the current object in the inspector and whether it is editable. (Defined by ObjectExt.)
	ThrowIfNull	Throws an exception if the object is null. (Defined by ObjectExt.)